wcz-layout 6.7.2 → 9.4.2

package/skills/db-schema/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: db-schema
+description: "Use when: defining or updating Drizzle ORM table schemas, relations, enums, migrations, or Zod schemas derived from database models."
+---
+
+# Database Schema Patterns
+
+## Rules
+
+- Always use `uuid` for primary keys, and `snakeCase` for generating tables.
+- For `uuid` columns, do not generate random values in the schema. Client should generate UUIDs when creating new records.
+- Always add `withTimezone: true` to timestamp columns.
+- Always add `onDelete: "cascade"` on foreign keys for child/dependent tables.
+- Define relations in a central `relations.ts` file.
+- Generate Zod schemas with `createSelectSchema`; override fields with stricter rules (trim, min/max) where needed.
+- Use `.transform()` on all Zod schemas that include related data to assign parent IDs.
+- Do not auto-generate migrations unless the user explicitly asks. When asked, run `npm run db:generate`; migrations apply automatically at app startup while `DATABASE_AUTO_MIGRATE=true`.
+
+## File Placement
+
+```
+drizzle-orm                     - defineRelations utility
+drizzle-orm/pg-core             - snakeCase table builder and column types
+drizzle-orm/zod                 - createSelectSchema
+zod                             - Zod
+src/server/db/schemas/          - Drizzle table schemas and relations
+src/server/db/migrations/       - Drizzle migration files
+src/lib/schemas/                - Zod schemas (shared between client and server)
+wcz-layout/utils                - `t` translation function
+```
+
+## Examples
+
+```ts
+// src/server/db/schemas/<feature>.ts
+export const bookTable = snakeCase.table("books", {
+  id: uuid().primaryKey(),
+  title: text().notNull(),
+  libraryId: uuid()
+    .notNull()
+    .references(() => libraryTable.id, { onDelete: "cascade" }),
+});
+
+// src/server/db/schemas/relations.ts
+export const relations = defineRelations(
+  { libraryTable, bookTable },
+  ({ one, many, libraryTable: library, bookTable: book }) => ({
+    libraryTable: {
+      books: many.bookTable(),
+    },
+    bookTable: {
+      library: one.libraryTable({ from: book.libraryId, to: library.id }),
+    },
+  }),
+);
+
+// src/lib/schemas/<feature>.ts
+export const BookSchema = createSelectSchema(bookTable, {
+  title: (schema) =>
+    schema
+      .trim()
+      .min(1, t("Validation.Required"))
+      .max(255, t("Validation.MaxLength", { length: 255 })),
+  pages: PageSchema.array().min(1, t("Validation.Required")),
+}).transform((data) => ({
+  ...data,
+  pages: data.pages.map((page) => ({ ...page, bookId: data.id })),
+}));
+
+export type Book = z.infer<typeof BookSchema>;
+```

package/skills/dialogs/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: dialogs
+description: "Use when: creating or modifying alert dialogs, confirm dialogs, typed custom dialogs, or dialog-driven user flows."
+---
+
+## Rules
+
+- Always use `useDialogs()` for modal interactions.
+- Use `confirm()` for destructive or user-confirmed actions.
+- Use `alert()` for informational or error messages that require acknowledgement.
+- Use `open()` for feature-specific custom dialogs with typed payloads.
+- Custom dialogs must receive `DialogProps<T>`.
+- Keep dialogs colocated inside `routes/feature/-components` when feature-specific.
+- Always use translation; add new keys for feature-specific messages.
+- Use notifications for lightweight feedback; dialogs when the user must decide or acknowledge.
+
+## File Placement
+
+```txt
+src/components/dialogs/         — shared dialogs used across features
+src/routes/<feature>s/-components/ — feature-scoped dialogs
+wcz-layout/hooks                — useDialogs hook, DialogProps type, useTranslation
+src/lib/locales/                — translation keys
+@mui/material                   — MUI Dialog components
+```
+
+## Examples
+
+```ts
+// confirmation dialog
+const { confirm } = useDialogs();
+const { t } = useTranslation();
+
+const confirmed = await confirm(t("DeleteConfirmation", { count: selectedIds.length }));
+if (confirmed) await deleteFeature({ data: id });
+
+// alert dialog
+const { alert } = useDialogs();
+const { t } = useTranslation();
+
+try {
+  await saveFeature(values);
+  await alert(t("FeatureSavedSuccessfully"));
+} catch (error) {
+  await alert(error instanceof Error ? error.message : t("UnknownError"));
+}
+
+// custom dialog
+const { open } = useDialogs();
+
+await open(EditFeatureDialog, { id });
+
+// custom dialog component
+interface Payload {
+  id: string;
+}
+
+export const EditFeatureDialog = ({
+  payload,
+  open,
+  onClose,
+}: DialogProps<Payload>) => {
+  const { t } = useTranslation();
+
+  return (
+    <Dialog fullWidth open={open} onClose={() => onClose()}>
+      <DialogTitle>{t("EditFeature")}</DialogTitle>
+      <DialogContent>
+        {payload.id}
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={() => onClose()}>
+          Close
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+};
+```

package/skills/forms/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: forms
+description: "Use when: creating or modifying TanStack Form components, field layouts, validation schemas, submit handling, or custom form controls."
+---
+
+# Form Patterns
+
+## Rules
+
+- Always use `useLayoutForm` with pre-defined components.
+- Define `width` for all form fields based on the expected content length.
+- Reuse Zod schemas from `src/lib/schemas/` which are derived from Drizzle schemas with `createSelectSchema` from table schemas.
+- Use translation for labels, helper text, validation messages and submit.
+- Reset the form after successful create.
+- Use one of the following field based on the use case: `Autocomplete`, `Checkbox`, `DatePicker`, `DateRangePicker`, `DateTimePicker`, `DateTimeRangePicker`, `NumberField`, `RadioGroup`, `Slider`, `SubmitButton`, `Switch`, `TextField`, `TimePicker`, or `TimeRangePicker`.
+
+## File Placement
+
+```
+src/routes/<feature>s/-components/ - route-scoped forms
+src/lib/schemas/                   — Zod schemas (shared between client and server)
+wcz-layout/hooks                   - useLayoutForm hook, useTranslation
+```
+
+## Examples
+
+```ts
+// Form Component
+interface FormProps {
+  defaultValues: Feature;
+  onSubmit: (value: Feature) => Promise<void>;
+}
+
+export const Form: FC<FormProps> = ({ defaultValues, onSubmit }) => {
+  const { t } = useTranslation();
+
+  const form = useLayoutForm({
+    defaultValues,
+    validators: { onChange: FeatureSchema },
+    onSubmit: async ({ value, formApi }) => {
+      await onSubmit(value);
+      formApi.reset();
+    },
+  });
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        form.handleSubmit();
+      }}
+    >
+      {/* some styling */}
+      <form.AppField name="name">
+        {(field) => <field.TextField label={t("Feature.Name")} required sx={{ width: 420 }} />}
+      </form.AppField>
+      {/* some styling */}
+      <form.AppForm>
+        <form.SubmitButton variant="contained">{t("Submit")}</form.SubmitButton>
+      </form.AppForm>
+    </form>
+  );
+};
+
+// Autocomplete
+<field.Autocomplete
+  options={options}
+  sx={{ width: 250 }}
+  autoHighlight
+  autoSelect
+  autoComplete
+  loading={isLoading}
+  textFieldProps={{
+    label: t("Customer"),
+    required: true,
+  }}
+/>
+
+// Checkbox
+<field.Checkbox label={t("IsThisTrue")} />
+```

package/skills/general/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: general
+description: "Use ALWAYS for project-wide conventions and coding standards. It defines the default style, rules, and best practices that apply to every file and feature."
+---
+
+## Rules
+
+- Generate modern ES6+ TypeScript with explicit types and never use `any`.
+- Stick to double quotes, semicolons, and the `~/` alias for `src/` imports.
+- Avoid `useMemo` / `useCallback`; the React Compiler handles memoization.
+- Keep code self-documenting; only add comments to clarify non-obvious intent.
+- When building UI, always design for both light and dark mode; this app uses `colorSchemeSelector: "data-mui-color-scheme"`, so prefer `theme.applyStyles("dark", ...)` for mode-specific styling.
+- Before implementing features of external libraries, search for the latest docs on Context7 MCP.
+
+## When to Use This Skill
+
+This is the default skill. Reference it in combination with more specific skills (e.g., `forms`, `tables`, `dialogs`) for targeted tasks.

package/skills/notifications/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: notifications
+description: "Use when: displaying success, error, warning, or informational feedback with snackbars or async user actions."
+---
+
+## Rules
+
+- Use `useNotification()` for lightweight non-blocking user feedback.
+- Always use translation; add new keys for feature-specific messages.
+- Notifications are automatically queued by the provider and shown one at a time.
+- `autoHideDuration` defaults to 5000 ms; override it (up to 10000 ms) only for messages that need more reading time.
+- Use `severity: "success" | "info" | "warning" | "error"` consistently with the outcome.
+- Use notifications for lightweight feedback; dialogs when the user must decide or acknowledge.
+
+## File Placement
+
+```txt
+wcz-layout/hooks                       — useNotification hook, useTranslation
+src/lib/locales/                       — translation keys
+```
+
+## Examples
+
+```ts
+// basic usage
+const { notify } = useNotification();
+const { t } = useTranslation();
+
+notify(t("Feature.Created"), {
+  severity: "success",
+  autoHideDuration: 6000,
+});
+
+// error handling
+try {
+  await deleteFeature({ data: id });
+} catch (error) {
+  notify(error instanceof Error ? error.message : t("DeleteFailed"), {
+    severity: "error",
+    autoHideDuration: 10000,
+  });
+}
+```

package/skills/routing/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: routing
+description: "Use when: creating or modifying TanStack Router routes, feature folders, navigation, permissions, loaders, suspense flows, or route-scoped components/hooks."
+---
+
+## Rules
+
+- Always include `requirePermission("all")` in the route's `beforeLoad` function to enforce access control unless the route is meant to be public.
+- Use `Route.useRouteContext()` to access the authenticated user. User can be `null` if the route doesn't include `requirePermission`.
+- Use the route `loader` option to preload db collections. Preload only root-level collections.
+- Create a `pendingComponent` for routes that suspend or preload meaningful data.
+- Route names must always be kebab-case. Entity route names must always be plural.
+- If a feature contains only one route, create a single file route: `src/routes/libraries.tsx`
+- If a feature contains multiple related routes, create a folder: `src/routes/libraries/index.tsx`
+- Colocate route-specific components/hooks inside `routes/<feature>/-components` or `-hooks`.
+- Root-level `components/` and `hooks/` are only for code shared across multiple routes.
+- After creating a new route, add or ask for a navigation item with a unique icon from `@mui/icons-material` in `src/routes/__root.tsx`.
+
+## Base Project Structure
+
+```txt
+src/                           # client-first architecture
+├── components/                # shared components across multiple routes
+├── db-collections/            # tanstack-db collections
+├── hooks/                     # shared hooks across multiple routes
+├── lib/                       # contains isomorphic/shared logic usable by both client and server
+│   ├── auth/
+│   │   ├── permissions.ts
+│   │   └── scopes.ts
+│   ├── locales/
+│   │   ├── cs.json
+│   │   └── en.json
+│   └── schemas/               # shared zod schemas
+├── routes/                    # TanStack Router file-based routing
+│   ├── __root.tsx
+│   ├── index.tsx
+│   └── features/              # route group with multiple pages
+│       ├── -components/       # components specific to feature routes
+│       ├── -hooks/            # hooks specific to feature routes
+│       ├── index.tsx
+│       ├── create.tsx
+│       ├── edit.$id.tsx
+│       └── $id.tsx
+├── server/                    # server-only code
+│   ├── actions/
+│   │   └── feature.ts         # server functions
+│   ├── db/
+│   │   ├── migrations/
+│   │   ├── schemas/           # drizzle database schemas
+│   │   │   └── feature.ts
+│   │   └── index.ts           # drizzle db instance
+│   └── middleware/
+│       └── databaseMiddleware.ts
+└── types/
+```
+
+## Examples
+
+```ts
+// imports
+import { useDialogs, useTranslation } from "wcz-layout/hooks";
+import { requirePermission, uuidv7 } from "wcz-layout/utils";
+
+// src/routes/features/create.tsx
+export const Route = createFileRoute("/features/create")({
+  component: RouteComponent,
+  beforeLoad: requirePermission("all"),
+  pendingComponent: FeatureSkeleton,
+  loader: () => {
+    featureCollection.preload();
+  },
+});
+
+function RouteComponent() {
+  const { t } = useTranslation();
+  const { alert, confirm } = useDialogs();
+  const { user } = Route.useRouteContext();
+  // route component code...
+}
+
+// __root.tsx
+import { hasPermission } from "wcz-layout/utils";
+
+const { user } = Route.useRouteContext();
+
+const navigation: Navigation = [
+  {
+    kind: "item",
+    to: "/",
+    title: "Home",
+    icon: <Home />,
+    hidden: !hasPermission(user, "all"),
+  },
+  {
+    kind: "header",
+    title: "Documentation",
+  },
+  {
+    kind: "group",
+    title: "Components",
+    icon: <Widgets />,
+    children: [
+      {
+        kind: "item",
+        to: "/components/navigation",
+        title: "Navigation",
+        icon: <AccountTree />,
+      },
+      {
+        kind: "divider",
+      },
+      {
+        kind: "item",
+        to: "/components/forms",
+        title: "Forms",
+        icon: <Code />,
+      },
+    ],
+  },
+];
+
+// Routes are public by default. Protect a route by adding requirePermission to
+// its beforeLoad — it redirects to login when signed out, then checks the group.
+export const Route = createFileRoute("/feature-name")({
+  component: RouteComponent,
+  beforeLoad: requirePermission("all"),
+});
+```

package/skills/server-functions/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: server-functions
+description: "Use when: creating or modifying TanStack Start server functions, REST routes, middleware, validation, database transactions, external service calls, or permission checks."
+---
+
+## Rules
+
+- Before generating code, clarify whether the feature should be exposed as public REST API routes or implemented as internal TanStack Start server functions (recommended), and what permission should be required for access.
+- If permission is unknown, use `"all"`.
+- Every server function MUST include `authorizationMiddleware` — server functions are callable RPC endpoints, so a route-level `requirePermission` in `beforeLoad` only hides the UI and does not protect them.
+- Follow the chain order for server functions: `validator` → `middleware` → `handler`.
+- In middleware, always follow this order: `validationMiddleware` → `authorizationMiddleware` → `databaseMiddleware` (reject unauthorized callers before opening a DB transaction).
+- Use `validationMiddleware` only in REST API routes. Server functions use `.validator()`.
+- `databaseMiddleware` wraps the handler in a DB transaction and sets `app.user_name` so audit triggers can record who made the change.
+- Reuse schemas from `src/lib/schemas/`.
+
+## File Placement
+
+```
+src/server/actions/             — server functions
+src/routes/api/                 — REST API routes
+src/server/middleware/          — databaseMiddleware
+wcz-layout/middleware/          — authorizationMiddleware, validationMiddleware
+src/server/db/schemas/          — tables, enums, relations
+src/lib/schemas/                — Zod schemas (shared between client and server)
+src/lib/auth/permissions.ts     — permission keys
+```
+
+## Examples
+
+```ts
+// src/server/actions/<feature>.ts
+export const selectFeatures = createServerFn()
+  .middleware([authorizationMiddleware("all"), databaseMiddleware])
+  .handler(async ({ context }) => {
+    return await context.db.select().from(featureTable);
+  });
+
+export const insertFeature = createServerFn({ method: "POST" })
+  .validator(FeatureSchema)
+  .middleware([authorizationMiddleware("admin"), databaseMiddleware])
+  .handler(async ({ data, context }) => {
+    await context.db.insert(featureTable).values(data);
+  });
+
+export const updateFeature = createServerFn({ method: "POST" })
+  .validator(FeatureSchema)
+  .middleware([authorizationMiddleware("admin"), databaseMiddleware])
+  .handler(async ({ data, context }) => {
+    await context.db.update(featureTable).set(data).where(eq(featureTable.id, data.id));
+  });
+
+export const deleteFeature = createServerFn({ method: "POST" })
+  .validator(FeatureSchema.pick({ id: true }))
+  .middleware([authorizationMiddleware("admin"), databaseMiddleware])
+  .handler(async ({ data, context }) => {
+    await context.db.delete(featureTable).where(eq(featureTable.id, data.id));
+  });
+
+// src/routes/api/<feature>s/index.ts
+export const Route = createFileRoute("/api/features/")({
+  server: {
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        GET: {
+          middleware: [authorizationMiddleware("all"), databaseMiddleware],
+          handler: async ({ context }) => {
+            const items = await context.db.select().from(featureTable);
+            return Response.json(items);
+          },
+        },
+        POST: {
+          middleware: [
+            validationMiddleware(FeatureSchema),
+            authorizationMiddleware("admin"),
+            databaseMiddleware,
+          ],
+          handler: async ({ context }) => {
+            const [response] = await context.db
+              .insert(featureTable)
+              .values(context.data)
+              .returning();
+            return Response.json(response, { status: 201 });
+          },
+        },
+      }),
+  },
+});
+
+// src/routes/api/<feature>s/$id.ts
+export const Route = createFileRoute("/api/features/$id")({
+  server: {
+    middleware: [authorizationMiddleware("admin"), databaseMiddleware],
+    handlers: ({ createHandlers }) =>
+      createHandlers({
+        PUT: {
+          middleware: [validationMiddleware(FeatureSchema)],
+          handler: async ({ params, context }) => {
+            await context.db
+              .update(featureTable)
+              .set(context.data)
+              .where(eq(featureTable.id, params.id));
+            return new Response(null, { status: 204 });
+          },
+        },
+        DELETE: async ({ params, context }) => {
+          await context.db.delete(featureTable).where(eq(featureTable.id, params.id));
+          return new Response(null, { status: 204 });
+        },
+      }),
+  },
+});
+```

package/skills/services/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: services
+description: "Use when: integrating file, approval, PeopleSoft, email, or attendance services into your workflow."
+---
+
+## Info
+
+You can read about each service in the links below. Services are categorized as either client or server exports, depending on their intended usage.
+
+- **Client exports** — Contains `queryOptions` and `mutationOptions`; use for data fetching/mutations on the client with React Query.
+- **Server exports** — Server functions; prefer calling mutations inside other server functions or database transactions.
+- All mutation options take `{ queryClient }` so they can invalidate related queries.
+- To read about a service, open the linked file in the **File** column directly.
+
+## Import Paths
+
+- Client exports: `wcz-layout/data/client`
+- Server exports: `wcz-layout/data/server`
+- Schemas & Models: `wcz-layout/models`
+
+## Services
+
+| Service    | File                                | Summary                                                                 |
+| ---------- | ----------------------------------- | ----------------------------------------------------------------------- |
+| file       | [file.md](docs/file.md)             | File metadata, thumbnails, binary download/open, upload, update, delete |
+| approval   | [approval.md](docs/approval.md)     | Approval request lifecycle, approvers, flows, statuses, step results    |
+| peoplesoft | [peoplesoft.md](docs/peoplesoft.md) | Employee, manager, department, and company general manager lookups      |
+| email      | [email.md](docs/email.md)           | Server-only email sending with optional file attachment references      |
+
+> The attendance service is not available yet — do not generate code against it; tell the user it is coming in a future release.