wcz-layout 8.1.0 → 8.2.0

package/skills/layout-navigation/SKILL.md

@@ -1,259 +0,0 @@
----
-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

@@ -1,181 +0,0 @@
----
-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.

package/skills/project-structure/SKILL.md

@@ -1,157 +0,0 @@
----
-name: project-structure
-description: >
-  Domain-scoped co-location rules for TanStack Router file-based routing.
-  Dash-prefix convention (-components/, -hooks/) excludes folders from
-  route generation. Domain-specific code lives in route folders; shared
-  code in src/components/, src/hooks/. Drizzle schemas in src/lib/db/schemas/,
-  Zod schemas in src/schemas/, collections in src/lib/db/collections/.
-  Activate when deciding where to place a new file or organizing a feature.
-type: lifecycle
-library: wcz-layout
-library_version: "7.6.1"
-requires:
-  - project-initialization
-sources:
-  - "wcz-layout:src/routeTree.gen.ts"
-  - "TanStack/router:docs/router/api/file-based-routing.md"
----
-
-This skill builds on project-initialization. Read it first for env and plugin setup.
-
-# Project Structure Conventions
-
-## Setup
-
-A typical project follows this structure:
-
-```
-src/
-├── components/              # SHARED components (used across multiple domains)
-│   ├── StyledCard.tsx
-│   └── DataGridToolbar.tsx
-├── hooks/                   # SHARED hooks
-├── lib/
-│   ├── auth/
-│   │   ├── permissions.ts   # AD group → permission key mapping
-│   │   └── scopes.ts        # OAuth scope definitions
-│   ├── db/
-│   │   ├── schemas/          # Drizzle pgTable definitions
-│   │   │   └── todo.ts
-│   │   ├── collections/      # TanStack DB collections
-│   │   │   └── todoCollection.ts
-│   │   └── migrations/       # Drizzle migrations
-│   └── theme.ts
-├── middleware/               # Custom middleware (e.g. databaseMiddleware)
-├── schemas/                  # Zod validation schemas (derived from Drizzle)
-│   └── todo.ts
-├── locales/                  # i18n translation files
-│   ├── en.json
-│   └── cs.json
-├── routes/
-│   ├── __root.tsx            # Root layout with LayoutProvider
-│   ├── index.tsx             # Home page
-│   ├── api/
-│   │   ├── health.ts         # Health check endpoint
-│   │   └── todos/
-│   │       ├── index.ts      # GET / POST handlers
-│   │       └── $id.ts        # GET / PUT / DELETE by id
-│   └── todos/
-│       ├── -components/      # Domain-specific components (dash prefix!)
-│       │   └── Form.tsx
-│       ├── index.tsx          # List page
-│       ├── create.tsx         # Create page
-│       ├── $id.tsx            # Detail page
-│       └── edit.$id.tsx       # Edit page
-├── env.ts                    # Environment variable validation
-├── router.tsx                # Router configuration
-├── start.ts                  # TanStack Start configuration
-└── routeTree.gen.ts          # AUTO-GENERATED — never edit
-```
-
-## Core Patterns
-
-### Domain-scoped co-location
-
-When a component, hook, or utility is used only within one route domain, place it inside that route folder with a dash-prefix directory:
-
-```
-src/routes/todos/-components/Form.tsx     # Only used in /todos routes
-src/routes/todos/-hooks/useTodoFilters.ts # Only used in /todos routes
-src/routes/orders/-components/OrderCard.tsx
-```
-
-When the same component is reused across multiple domains, move it to the top-level shared directory:
-
-```
-src/components/StyledCard.tsx    # Used by both /todos and /orders
-src/hooks/useDebounce.ts         # Used everywhere
-```
-
-### Data layer file placement
-
-```
-src/lib/db/schemas/todo.ts           # Drizzle table: pgTable("todos", { ... })
-src/schemas/todo.ts                  # Zod schema: createSelectSchema(todoTable, { ... })
-src/lib/db/collections/todoCollection.ts  # TanStack DB collection
-```
-
-## Common Mistakes
-
-### CRITICAL Missing dash prefix on route-scoped folders
-
-Wrong:
-
-```
-src/routes/todos/components/Form.tsx
-```
-
-Correct:
-
-```
-src/routes/todos/-components/Form.tsx
-```
-
-TanStack Router treats folders without a dash prefix as route segments. `components/Form.tsx` becomes a `/todos/components/Form` route. The dash prefix (`-components/`) tells the router to ignore this directory.
-
-Source: TanStack/router:docs/router/api/file-based-routing.md
-
-### CRITICAL Editing routeTree.gen.ts
-
-Wrong:
-
-```typescript
-// src/routeTree.gen.ts — manually adding a route
-```
-
-Correct:
-
-Create a new file in `src/routes/` and let TanStack Router auto-generate the route tree.
-
-This file is auto-generated and overwritten on every route change. Manual edits are silently lost.
-
-Source: wcz-layout:src/routeTree.gen.ts header comment
-
-### HIGH Placing domain-specific component in src/components/
-
-Wrong:
-
-```typescript
-// src/components/TodoForm.tsx — only used in /todos routes
-export function TodoForm() {
-  return <form>...</form>;
-}
-```
-
-Correct:
-
-```typescript
-// src/routes/todos/-components/TodoForm.tsx
-export function TodoForm() {
-  return <form>...</form>;
-}
-```
-
-Components used only within one route domain should live in that domain's `-components/` folder. `src/components/` is reserved for components shared across multiple domains.
-
-Source: maintainer interview