wcz-layout 7.6.0 → 7.6.2

package/skills/forms-validation/references/field-components.md

@@ -0,0 +1,212 @@
+# Field Components Reference
+
+All field components are accessed via `field.*` inside a `form.AppField` children render prop. Props listed below are the MUI props you can pass — `FormOmittedProps` (`name`, `value`, `onChange`, `onBlur`, `error`, `helperText`, `renderInput`, `type`, `aria-label`) are automatically stripped and managed by TanStack Form.
+
+## TextField
+
+```typescript
+<form.AppField
+  name="title"
+  children={(field) => (
+    <field.TextField
+      label="Title"
+      required
+      multiline          // optional: enables textarea
+      rows={3}           // optional: fixed row count for multiline
+      placeholder="..."  // optional
+      disabled           // optional
+      slotProps={{        // optional: MUI slot props
+        input: { startAdornment: <InputAdornment position="start">$</InputAdornment> }
+      }}
+    />
+  )}
+/>
+```
+
+## NumberField
+
+```typescript
+<form.AppField
+  name="quantity"
+  children={(field) => (
+    <field.NumberField
+      label="Quantity"
+      required
+      slotProps={{
+        input: { inputProps: { min: 0, max: 100, step: 1 } }
+      }}
+    />
+  )}
+/>
+```
+
+## Autocomplete
+
+```typescript
+<form.AppField
+  name="assignee"
+  children={(field) => (
+    <field.Autocomplete
+      label="Assignee"
+      options={users}
+      getOptionLabel={(user) => user.displayName}
+      isOptionEqualToValue={(option, value) => option.id === value.id}
+      multiple               // optional: multi-select
+      freeSolo               // optional: allow custom input
+      loading={isLoading}    // optional: show loading indicator
+    />
+  )}
+/>
+```
+
+## Checkbox
+
+```typescript
+<form.AppField
+  name="isActive"
+  children={(field) => (
+    <field.Checkbox
+      label="Active"
+      disabled  // optional
+    />
+  )}
+/>
+```
+
+Renders `FormControlLabel` wrapping MUI `Checkbox`.
+
+## Switch
+
+```typescript
+<form.AppField
+  name="notifications"
+  children={(field) => (
+    <field.Switch
+      label="Enable Notifications"
+      disabled  // optional
+    />
+  )}
+/>
+```
+
+Renders `FormControlLabel` wrapping MUI `Switch`.
+
+## RadioGroup
+
+```typescript
+<form.AppField
+  name="priority"
+  children={(field) => (
+    <field.RadioGroup
+      label="Priority"
+      options={[
+        { label: "Low", value: "low" },
+        { label: "Medium", value: "medium" },
+        { label: "High", value: "high" },
+      ]}
+      row  // optional: horizontal layout
+    />
+  )}
+/>
+```
+
+**Warning:** `onChange` returns `event.target.value` as a string. Use string values.
+
+## Slider
+
+```typescript
+<form.AppField
+  name="rating"
+  children={(field) => (
+    <field.Slider
+      min={0}
+      max={10}
+      step={1}
+      marks
+      valueLabelDisplay="auto"
+    />
+  )}
+/>
+```
+
+## DatePicker
+
+```typescript
+<form.AppField
+  name="dueDate"
+  children={(field) => (
+    <field.DatePicker
+      label="Due Date"
+      minDate={dayjs()}       // optional
+      maxDate={dayjs().add(1, "year")}  // optional
+    />
+  )}
+/>
+```
+
+## DateRangePicker
+
+```typescript
+<form.AppField
+  name="dateRange"
+  children={(field) => (
+    <field.DateRangePicker
+      localeText={{ start: "Start", end: "End" }}
+    />
+  )}
+/>
+```
+
+## TimePicker
+
+```typescript
+<form.AppField
+  name="startTime"
+  children={(field) => (
+    <field.TimePicker
+      label="Start Time"
+      ampm={false}  // optional: 24-hour format
+    />
+  )}
+/>
+```
+
+## TimeRangePicker
+
+```typescript
+<form.AppField
+  name="timeRange"
+  children={(field) => (
+    <field.TimeRangePicker
+      localeText={{ start: "From", end: "To" }}
+    />
+  )}
+/>
+```
+
+## DateTimePicker
+
+```typescript
+<form.AppField
+  name="scheduledAt"
+  children={(field) => (
+    <field.DateTimePicker
+      label="Scheduled At"
+      ampm={false}
+    />
+  )}
+/>
+```
+
+## DateTimeRangePicker
+
+```typescript
+<form.AppField
+  name="availability"
+  children={(field) => (
+    <field.DateTimeRangePicker
+      localeText={{ start: "From", end: "Until" }}
+    />
+  )}
+/>
+```

package/skills/layout-navigation/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: layout-navigation
+description: >
+  Configure LayoutProvider with theme, options, and Navigation structure.
+  Shell: AppBar with env chip + NavigationRail (permanent sm+, modal xs).
+  Navigation items: page (title, icon, to/href), header, divider.
+  LayoutOptions: showShell, snackbarOrigin, publicRoutes. Dark mode via
+  theme.applyStyles("dark", ...) with colorSchemeSelector
+  data-mui-color-scheme. i18n with i18next, locale files auto-detected.
+  Activate when configuring the layout shell, navigation, or theming.
+type: core
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/providers/LayoutProvider.tsx"
+  - "wcz-layout:src/components/core/Layout.tsx"
+  - "wcz-layout:src/models/Navigation.ts"
+  - "wcz-layout:src/models/LayoutOptions.ts"
+  - "wcz-layout:src/lib/theme.ts"
+---
+
+# Layout & Navigation
+
+## Setup
+
+The layout shell is configured in the root route via `LayoutProvider`:
+
+```typescript
+// src/routes/__root.tsx
+import { LayoutProvider, rootRouteHead, RouterNotFound, RouterError } from "wcz-layout";
+import { theme } from "~/lib/theme";
+import { navigation } from "~/navigation";
+import type { LayoutOptions } from "wcz-layout/models";
+
+const options: LayoutOptions = {
+  showShell: true,
+  publicRoutes: ["/login"],
+};
+
+export const Route = createRootRouteWithContext()({
+  head: rootRouteHead,
+  component: RootComponent,
+  notFoundComponent: RouterNotFound,
+  errorComponent: RouterError,
+});
+
+function RootComponent() {
+  return (
+    <LayoutProvider theme={theme} navigation={navigation} options={options}>
+      <Outlet />
+    </LayoutProvider>
+  );
+}
+```
+
+## Core Patterns
+
+### Navigation structure
+
+Navigation is an array of items with three types — discriminated by the presence of `kind`:
+
+```typescript
+import type { Navigation } from "wcz-layout/models";
+import HomeIcon from "@mui/icons-material/Home";
+import ListIcon from "@mui/icons-material/List";
+import SettingsIcon from "@mui/icons-material/Settings";
+
+export const navigation: Navigation = [
+  { title: "Home", icon: <HomeIcon />, to: "/" },
+  { kind: "divider" },
+  { kind: "header", title: "Management" },
+  { title: "Todos", icon: <ListIcon />, to: "/todos" },
+  { kind: "divider" },
+  { title: "Settings", icon: <SettingsIcon />, to: "/settings" },
+];
+```
+
+### Navigation item types
+
+| Type      | Shape                       | Required fields |
+| --------- | --------------------------- | --------------- |
+| Page item | `{ title, icon, to }`       | `title`, `icon` |
+| Divider   | `{ kind: "divider" }`       | `kind`          |
+| Header    | `{ kind: "header", title }` | `kind`, `title` |
+
+Page items also accept:
+
+- `to` — internal route (TanStack Router link, type-safe)
+- `href` — external URL (opens in new tab)
+- `params`, `search` — TanStack Router link params
+- `children` — nested navigation items (sub-menu)
+- `hidden` — conditionally hide the item
+
+### Nested navigation
+
+```typescript
+const navigation: Navigation = [
+  {
+    title: "Admin",
+    icon: <AdminIcon />,
+    to: "/admin",
+    children: [
+      { title: "Users", icon: <PeopleIcon />, to: "/admin/users" },
+      { title: "Roles", icon: <SecurityIcon />, to: "/admin/roles" },
+    ],
+  },
+];
+```
+
+### LayoutOptions
+
+```typescript
+interface LayoutOptions {
+  showShell?: boolean; // Show AppBar + NavigationRail (default: true)
+  snackbarOrigin?: SnackbarOrigin; // Notification position
+  publicRoutes?: string[]; // Routes that skip authentication
+}
+```
+
+### Theme configuration
+
+The theme is pre-configured in the template at `src/lib/theme.ts`. Use MUI's `extendTheme` to customize:
+
+```typescript
+// src/lib/theme.ts
+import { extendTheme } from "@mui/material/styles";
+
+export const theme = extendTheme({
+  colorSchemes: {
+    light: { palette: { primary: { main: "#1976d2" } } },
+    dark: { palette: { primary: { main: "#90caf9" } } },
+  },
+  colorSchemeSelector: "data-mui-color-scheme",
+});
+```
+
+### Dark mode styling
+
+Always use `theme.applyStyles("dark", ...)` for mode-specific styling:
+
+```typescript
+<Box
+  sx={(theme) => ({
+    backgroundColor: "#fff",
+    ...theme.applyStyles("dark", {
+      backgroundColor: "#121212",
+    }),
+  })}
+/>
+```
+
+### i18n setup
+
+Locale files in `src/locales/` are auto-detected by `viteWczLayout()`:
+
+```
+src/locales/en.json    # English (default)
+src/locales/cs.json    # Czech
+```
+
+The Vite plugin generates the `virtual:wcz-layout` module with all locale resources. `LayoutProvider` initializes `i18next` with language detection (cookie-based, 1-year expiry) and syncs Zod and DayJS locales on language change.
+
+```typescript
+import { useTranslation } from "react-i18next";
+
+function MyComponent() {
+  const { t } = useTranslation();
+  return <Typography>{t("welcome")}</Typography>;
+}
+```
+
+### Root route head
+
+`rootRouteHead` provides meta tags and manifest link:
+
+```typescript
+export const Route = createRootRouteWithContext()({
+  head: rootRouteHead,
+  // optionally: head: rootRouteHead({ manifest: "/manifest.json" }),
+});
+```
+
+### Service worker
+
+`LayoutProvider` registers `/sw.js` on mount for PWA support.
+
+## Common Mistakes
+
+### HIGH Using theme.palette for dark mode instead of theme.applyStyles
+
+Wrong:
+
+```typescript
+sx={{ color: mode === "dark" ? "white" : "black" }}
+```
+
+Correct:
+
+```typescript
+sx={(theme) => ({
+  color: "black",
+  ...theme.applyStyles("dark", { color: "white" }),
+})}
+```
+
+The app uses `colorSchemeSelector: "data-mui-color-scheme"`. Mode-specific styles must use `theme.applyStyles("dark", ...)`, not conditional palette checks or mode variables.
+
+Source: copilot-instructions.md / wcz-layout:src/lib/theme.ts
+
+Cross-skill: See also skills/ui-pages/SKILL.md § Common Mistakes
+
+### HIGH Using href for internal routes in Navigation
+
+Wrong:
+
+```typescript
+{ title: "Todos", icon: <ListIcon />, href: "/todos" }
+```
+
+Correct:
+
+```typescript
+{ title: "Todos", icon: <ListIcon />, to: "/todos" }
+```
+
+`NavigationPageItem` supports dual destination: `to` for internal TanStack Router links, `href` for external URLs. Using `href` for internal routes causes full page reloads.
+
+Source: wcz-layout:src/models/Navigation.ts
+
+### MEDIUM Creating NavigationPageItem without icon
+
+Wrong:
+
+```typescript
+{ title: "Todos", to: "/todos" }
+```
+
+Correct:
+
+```typescript
+{ title: "Todos", icon: <ListIcon />, to: "/todos" }
+```
+
+`NavigationPageItem` requires both `title` and `icon`. Missing `icon` renders an empty slot in the NavigationRail.
+
+Source: wcz-layout:src/models/Navigation.ts
+
+### MEDIUM Adding locale without updating supportedLngs
+
+This is actually **not** an issue — the Vite plugin auto-detects locale files in `src/locales/`. Adding a new JSON file (e.g. `de.json`) is sufficient; `supportedLngs` is derived from `Object.keys(resources)` automatically.
+
+Source: wcz-layout:src/providers/LayoutProvider.tsx
+
+---
+
+See also:
+
+- skills/ui-pages/SKILL.md — Pages render inside the layout shell.
+- skills/auth/SKILL.md — publicRoutes bypass auth; permission guards need auth context.

package/skills/project-initialization/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: project-initialization
+description: >
+  Scaffold a new wcz-layout project from the template. Covers placeholder
+  replacement across three naming conventions (kebab-case, Title Case,
+  snake_case), .env and .env.local configuration, VITE_ENTRA_CLIENT_ID,
+  VITE_APP_TITLE, VITE_MUI_LICENSE_KEY, favicon generation via favicon.io,
+  and viteWczLayout() Vite plugin registration. Activate when starting a
+  new internal project or configuring environment variables.
+type: lifecycle
+library: wcz-layout
+library_version: "7.6.1"
+sources:
+  - "wcz-layout:src/env.ts"
+  - "wcz-layout:src/lib/vite-plugin.ts"
+  - "wcz-layout:vite.config.ts"
+  - "wcz-layout:.env"
+---
+
+# Project Initialization
+
+## Setup
+
+After cloning the template repository, initialize the project in this order:
+
+### 1. Replace all template placeholders
+
+Use your editor's replace-all (across all files) for each naming convention:
+
+| Find           | Replace with | Used in                                          |
+| -------------- | ------------ | ------------------------------------------------ |
+| `project-name` | `app-store`  | package.json name, URLs, CSS classes             |
+| `Project Name` | `App Store`  | VITE_APP_TITLE, display strings, docs            |
+| `my_app`       | `app_store`  | Database names, env vars, snake_case identifiers |
+
+### 2. Configure environment variables
+
+```sh
+# .env — committed to repo, shared across team
+VITE_ENTRA_CLIENT_ID=your-entra-client-id
+VITE_ENTRA_TENANT_ID=your-tenant-id
+VITE_APP_TITLE=App Store
+VITE_MUI_LICENSE_KEY=your-mui-license-key
+```
+
+Create `.env.local` (gitignored) for local secret overrides:
+
+```sh
+# .env.local — never committed
+VITE_ENTRA_CLIENT_ID=your-dev-client-id
+ENTRA_CLIENT_ID=your-server-client-id
+ENTRA_TENANT_ID=your-server-tenant-id
+ENTRA_CLIENT_SECRET=your-client-secret
+```
+
+### 3. Generate favicon
+
+Go to https://favicon.io/favicon-converter/, upload your logo, and place the generated files in `public/`.
+
+### 4. Verify Vite plugin registration
+
+```typescript
+// vite.config.ts
+import { viteWczLayout } from "wcz-layout/vite";
+
+export default defineConfig({
+  plugins: [
+    tanstackStart(),
+    nitro(),
+    viteReact(),
+    babel(reactCompilerPreset()),
+    checker({ typescript: true }),
+    viteWczLayout(),
+  ],
+});
+```
+
+## Core Patterns
+
+### Environment validation with createEnv
+
+```typescript
+// src/env.ts
+import { createEnv } from "wcz-layout/utils";
+import { z } from "zod";
+
+export const clientEnv = createEnv({
+  clientPrefix: "VITE_",
+  client: {
+    VITE_ENTRA_CLIENT_ID: z.string(),
+    VITE_ENTRA_TENANT_ID: z.string(),
+    VITE_APP_TITLE: z.string(),
+    VITE_MUI_LICENSE_KEY: z.string(),
+  },
+  runtimeEnv: import.meta.env,
+  emptyStringAsUndefined: true,
+});
+
+export const serverEnv = createEnv({
+  server: {
+    ENTRA_CLIENT_ID: z.string(),
+    ENTRA_TENANT_ID: z.string(),
+    ENTRA_CLIENT_SECRET: z.string(),
+  },
+  runtimeEnv: process.env,
+  emptyStringAsUndefined: true,
+});
+```
+
+### Vault secrets for local development
+
+The `viteWczLayout()` plugin automatically loads secrets from HashiCorp Vault during `vite dev` if `VAULT_ADDRESS`, `VAULT_USERNAME`, `VAULT_PASSWORD`, and `VAULT_SECRET_PATH` are set in `.env`. Vault-loaded secrets only populate `process.env` keys that are not already set.
+
+## Common Mistakes
+
+### CRITICAL Missing viteWczLayout() in Vite config
+
+Wrong:
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [tanstackStart(), viteReact()],
+});
+```
+
+Correct:
+
+```typescript
+// vite.config.ts
+import { viteWczLayout } from "wcz-layout/vite";
+export default defineConfig({
+  plugins: [tanstackStart(), viteReact(), viteWczLayout()],
+});
+```
+
+Without `viteWczLayout()`, the `virtual:wcz-layout` module won't resolve, breaking i18n resources, permissions, and scopes at build time.
+
+Source: wcz-layout:src/lib/vite-plugin.ts
+
+### HIGH Forgetting .env.local for local secrets
+
+`.env` is committed to the repo and shared across the team. Local overrides (Entra client IDs, secrets) must go in `.env.local` which is gitignored. Committing secrets to `.env` exposes them in the repository.
+
+Source: maintainer interview
+
+### HIGH Not replacing all naming conventions
+
+The template uses three naming conventions. Use replace-all across the entire project for each one. Missing any convention leaves stale references in package.json, env files, or source imports.
+
+Source: maintainer interview
+
+### MEDIUM Empty string env vars pass silently
+
+Wrong:
+
+```sh
+# .env
+VITE_APP_TITLE=
+```
+
+Correct:
+
+```sh
+# .env
+VITE_APP_TITLE=My Application
+```
+
+`createEnv` uses `emptyStringAsUndefined: true`, so empty strings become `undefined` and fail Zod validation at runtime, not build time.
+
+Source: wcz-layout:src/env.ts
+
+### HIGH Tension: Simplicity vs. full-stack rigor
+
+This skill's simple setup conflicts with production readiness from api-routes. Agents scaffolding a quick prototype may skip authorizationMiddleware and validationMiddleware, producing code that works locally but is insecure in production. Always include middleware from the start.
+
+See also: skills/api-routes/SKILL.md § Common Mistakes
+
+---
+
+See also: skills/project-structure/SKILL.md — After init, understand where to place new code.