wcz-layout/skills/general/references/exports.md

# wcz-layout exports

Public import subpaths and commonly used exports. Read this when you need to know where a
symbol lives; you do not need it loaded for ordinary feature work.

## `wcz-layout`

The root subpath. Everything the application shell needs.

- `LayoutProvider` — root shell provider. Props: `theme` (required), `navigation?`,
  `options?` (`appBarActions`, `showShell`; see the `routing` skill). Installs the Emotion
  cache, MUI `ThemeProvider`, `LocalizationProvider`
  (dayjs), i18next and the dialogs provider. Wrap `{children}` with it inside `<body>` in
  `__root.tsx`. Do not install any of those yourself. Render `<html lang={i18n.language}>`
  in the shell: the browser starts i18next in that language before hydrating, so the
  server-rendered page is kept rather than rebuilt in another language.
- `Navigation` — the type for the sidebar tree. Items are
  `{ kind: "item" | "header" | "group" | "divider" }`; an item takes `to` or `href`,
  `title`, `icon` and optional `search`; groups take `title`, `icon` and `children`; headers
  take `title`; every kind accepts `hidden`.
- `rootRouteHead` — returns the root route's `head()` value (title, meta, links).
- `getUser({ queryClient })` — resolves the signed-in user. Call it in the root
  `beforeLoad` and return `{ user }`; that is what makes `Route.useRouteContext().user`
  available on every route.
- `setLanguageFromRequest()` — on the server, switches i18next to the request's language (the
  `i18next` cookie, then `Accept-Language`) so pages server-render in it; a no-op in the
  browser. `await` it first in the root `beforeLoad`, before `getUser`.
- `loginProvidersQueryOptions` — query options for the configured OAuth providers. The
  `/login` route loads it so the buttons server-render.
- `WISTRON_PRIMARY_COLOR`, `WISTRON_SECONDARY_COLOR` — brand colors for the app's theme.

## `wcz-layout/vite`

- `viteWczLayout()` — **required** Vite plugin. Keep the template's plugin order after
  `tanstackStart()`, `nitro()`, `viteReact()` and the React Compiler babel plugin. It
  builds the `virtual:wcz-layout` module from the app's `src/lib/locales/*.json`,
  `src/lib/auth/permissions.ts`, `src/lib/auth/scopes.ts`, `src/env.ts` and
  `public/manifest.json`, and loads Vault secrets into `process.env` during `serve`.
  Without it the build fails to resolve
  `virtual:wcz-layout`. The app must also declare that module in
  `src/types/wcz-layout.d.ts`.

## `wcz-layout/components`

- `LayoutTable` — table renderer; see the `table` skill. Types: `LayoutTableProps`,
  `RowAction`, `LayoutColumnMeta`, `FilterOperator`, `TableFilterOption`,
  `TableFilterVariant`
- `AggregatedCell` — aggregated value cell for grouped rows
- `Fullscreen` — Box that fills the rest of the viewport and scrolls inside (tables, maps, charts)
- `Dropzone`, `FileViewer` — file upload and preview; see the `services` skill
- `LoginForm` — provider buttons for the login route; takes no props and reads
  `?returnTo` itself
- `RouterButton`, `RouterFab`, `RouterIconButton`, `RouterLink`, `RouterListItemButton`,
  `RouterTab` — MUI components taking router `to` / `params` / `search`
- `RouterNotFound`, `RouterError` — default 404 and error components. Pass them to
  `createRouter` as `defaultNotFoundComponent` and `defaultErrorComponent`.

## `wcz-layout/hooks`

- `useLayoutForm`, `withLayoutForm`, `useFormContext`, `useFieldContext` — form instance,
  reusable sub-forms, and the contexts custom field components read; see the `forms` skill
- `useLayoutTable`, `createLayoutColumnHelper`, `layoutTableFeatures`, `useTableContext`,
  `useHeaderContext`, `useCellContext` — table instance, column helper and contexts, plus
  type `LayoutTableFeatures`; see the `table` skill
- `createLayoutChatHook` — binds a chat server function to the MUI chat (generated UI,
  approvals, persistence) and returns `useLayoutChat` and `LayoutChat`; see the `ai` skill
- `useDialogs` — alert, confirm, custom dialogs and `close`, plus type `DialogProps`; see
  the `dialogs` skill
- `useTranslation` — translation inside components
- `useInView` — element visibility observer (react-intersection-observer); defers queries until visible, drives infinite scroll
- `useScanDetection` — barcode laser scanner keystrokes; see the `scanning` skill

## `wcz-layout/middleware`

- `authMiddleware` — rejects unauthenticated calls, optionally checks a permission key.
  Goes in a server function's `.middleware([])`, **after** `databaseMiddleware` so it
  narrows `context.user` to `User`. See the `server-functions` skill for the full order.
- `userMiddleware` — attaches the user without requiring one, as `User | null`
- `validationMiddleware` — validates API route input against a Zod schema. REST routes
  only; server functions use `.validator()`.
- `csrfMiddleware` — CSRF protection for server functions. Without a `src/start.ts`, Start
  applies the same check by default, so the template has none. If the app adds
  `src/start.ts` for its own request middleware, list `csrfMiddleware` there too —
  `createStart(() => ({ requestMiddleware: [csrfMiddleware, ...] }))` — because a start
  instance replaces that default. It is a **request** middleware, never part of a
  `.middleware([])` array.

`databaseMiddleware` is **not** here. It is app-local; every app writes its own. See the
`server-functions` skill.

## `wcz-layout/utils`

- `t`, `i18next` — translation outside components
- `uuidv7` — time-sortable id. Use it for every client-generated primary key.
- `requireAuth` — `beforeLoad` route guard, redirects to `/login`; see the `routing` skill
- `hasPermission` — permission check for a user
- `Platform` — OS detection from the user agent
- `createEnv` — typed environment schema

## `wcz-layout/auth`

- `handleLogin`, `handleCallback`, `handleLogout` — OAuth route handlers. Mount each as a
  server `GET` handler at `/auth/login`, `/auth/callback` and `/auth/logout`.
- `getAccessToken` — delegated token for the signed-in user, server-only
- `getAppToken` — app-only token for background jobs, server-only

## `wcz-layout/models`

- Service types: `User`, `Permissions`, `Scopes`, `FileMeta`, `Email`, `EmailAttachment`,
  `Employee`, `Department`, `EmployeeStatus`, `EmployeeCategoryGroup`, `Approval*`
- Matching Zod schemas: `FileMetaSchema`, `EmailSchema`, `EmailAttachmentSchema`,
  `EmployeeSchema`, `DepartmentSchema` and the approval `*Schema`

## `wcz-layout/data/client`, `wcz-layout/data/server`

- Client query and mutation option factories for file, approval and PeopleSoft services.
  Server exports contain those operations plus `sendEmail`; see the `services` skill.