wcz-layout 8.1.0 → 8.2.0

package/package.json

@@ -1,154 +1,154 @@
-{
-  "name": "wcz-layout",
-  "version": "8.1.0",
-  "private": false,
-  "keywords": [
-    "tanstack-intent"
-  ],
-  "files": [
-    "dist",
-    "skills",
-    "!skills/_artifacts"
-  ],
-  "type": "module",
-  "sideEffects": false,
-  "types": "./dist/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "components": [
-        "./dist/components.d.ts"
-      ],
-      "hooks": [
-        "./dist/hooks.d.ts"
-      ],
-      "middleware": [
-        "./dist/middleware.d.ts"
-      ],
-      "models": [
-        "./dist/models.d.ts"
-      ],
-      "data": [
-        "./dist/data.d.ts"
-      ],
-      "data/client": [
-        "./dist/data/client.d.ts"
-      ],
-      "data/server": [
-        "./dist/data/server.d.ts"
-      ],
-      "utils": [
-        "./dist/utils.d.ts"
-      ],
-      "vite": [
-        "./dist/vite.d.ts"
-      ]
-    }
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./components": {
-      "types": "./dist/components.d.ts",
-      "import": "./dist/components.js"
-    },
-    "./hooks": {
-      "types": "./dist/hooks.d.ts",
-      "import": "./dist/hooks.js"
-    },
-    "./middleware": {
-      "types": "./dist/middleware.d.ts",
-      "import": "./dist/middleware.js"
-    },
-    "./models": {
-      "types": "./dist/models.d.ts",
-      "import": "./dist/models.js"
-    },
-    "./data": {
-      "types": "./dist/data.d.ts",
-      "import": "./dist/data.js"
-    },
-    "./data/client": {
-      "types": "./dist/data/client.d.ts",
-      "import": "./dist/data/client.js"
-    },
-    "./data/server": {
-      "types": "./dist/data/server.d.ts",
-      "import": "./dist/data/server.js"
-    },
-    "./utils": {
-      "types": "./dist/utils.d.ts",
-      "import": "./dist/utils.js"
-    },
-    "./vite": {
-      "types": "./dist/vite.d.ts",
-      "import": "./dist/vite.js"
-    }
-  },
-  "scripts": {
-    "dev": "vp dev",
-    "vp:install": "vp install",
-    "vp:update": "vp update",
-    "ncu:install": "npx npm-check-updates -i",
-    "lint:package": "publint",
-    "build": "vp pack",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@azure/msal-browser": "^5.9.0",
-    "@azure/msal-node": "^5.1.5",
-    "@azure/msal-react": "^5.3.2",
-    "@t3-oss/env-core": "^0.13.11",
-    "file-saver": "^2.0.5",
-    "i18next": "^26.0.8",
-    "i18next-browser-languagedetector": "^8.2.1",
-    "jose": "^6.2.3",
-    "react-dropzone": "^15.0.0",
-    "react-i18next": "^17.0.6",
-    "react-intersection-observer": "^10.0.3",
-    "react-number-format": "^5.4.5",
-    "tus-js-client": "^4.3.1",
-    "uuidv7": "^1.2.1"
-  },
-  "devDependencies": {
-    "@rolldown/plugin-babel": "^0.2.3",
-    "@tanstack/intent": "^0.0.40",
-    "@types/file-saver": "^2.0.7",
-    "@types/node": "^24.10.13",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.1",
-    "babel-plugin-react-compiler": "^1.0.0",
-    "nitro": "npm:nitro-nightly@latest",
-    "publint": "^0.3.18",
-    "typescript": "^6.0.3",
-    "vite-plugin-checker": "^0.13.0"
-  },
-  "peerDependencies": {
-    "@emotion/react": "11.x",
-    "@emotion/styled": "11.x",
-    "@mui/icons-material": "9.x",
-    "@mui/material": "9.x",
-    "@mui/x-data-grid-premium": "9.x",
-    "@mui/x-date-pickers-pro": "9.x",
-    "@tanstack/query-db-collection": "1.x",
-    "@tanstack/react-db": "0.x",
-    "@tanstack/react-form": "1.x",
-    "@tanstack/react-query": "5.x",
-    "@tanstack/react-router": "1.x",
-    "@tanstack/react-router-ssr-query": "1.x",
-    "@tanstack/react-start": "1.x",
-    "axios": "1.x",
-    "dayjs": "1.x",
-    "react": "19.x",
-    "react-dom": "19.x",
-    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
-    "vite-plus": "latest",
-    "zod": "4.x"
-  },
-  "overrides": {
-    "vite": "npm:@voidzero-dev/vite-plus-core@latest"
-  },
-  "packageManager": "npm@11.13.0"
-}
+{
+  "name": "wcz-layout",
+  "version": "8.2.0",
+  "private": false,
+  "keywords": [
+    "tanstack-intent"
+  ],
+  "files": [
+    "dist",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "components": [
+        "./dist/components.d.ts"
+      ],
+      "hooks": [
+        "./dist/hooks.d.ts"
+      ],
+      "middleware": [
+        "./dist/middleware.d.ts"
+      ],
+      "models": [
+        "./dist/models.d.ts"
+      ],
+      "data": [
+        "./dist/data.d.ts"
+      ],
+      "data/client": [
+        "./dist/data/client.d.ts"
+      ],
+      "data/server": [
+        "./dist/data/server.d.ts"
+      ],
+      "utils": [
+        "./dist/utils.d.ts"
+      ],
+      "vite": [
+        "./dist/vite.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components": {
+      "types": "./dist/components.d.ts",
+      "import": "./dist/components.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks.d.ts",
+      "import": "./dist/hooks.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware.d.ts",
+      "import": "./dist/middleware.js"
+    },
+    "./models": {
+      "types": "./dist/models.d.ts",
+      "import": "./dist/models.js"
+    },
+    "./data": {
+      "types": "./dist/data.d.ts",
+      "import": "./dist/data.js"
+    },
+    "./data/client": {
+      "types": "./dist/data/client.d.ts",
+      "import": "./dist/data/client.js"
+    },
+    "./data/server": {
+      "types": "./dist/data/server.d.ts",
+      "import": "./dist/data/server.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "import": "./dist/utils.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "scripts": {
+    "dev": "vp dev",
+    "vp:install": "vp install",
+    "vp:update": "vp update",
+    "ncu:install": "npx npm-check-updates -i",
+    "lint:package": "publint",
+    "build": "vp pack",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@azure/msal-browser": "^5.10.1",
+    "@azure/msal-node": "^5.2.1",
+    "@azure/msal-react": "^5.4.1",
+    "@t3-oss/env-core": "^0.13.11",
+    "file-saver": "^2.0.5",
+    "i18next": "^26.1.0",
+    "i18next-browser-languagedetector": "^8.2.1",
+    "jose": "^6.2.3",
+    "react-dropzone": "^15.0.0",
+    "react-i18next": "^17.0.7",
+    "react-intersection-observer": "^10.0.3",
+    "react-number-format": "^5.4.5",
+    "tus-js-client": "^4.3.1",
+    "uuidv7": "^1.2.1"
+  },
+  "devDependencies": {
+    "@rolldown/plugin-babel": "^0.2.3",
+    "@tanstack/intent": "^0.0.41",
+    "@types/file-saver": "^2.0.7",
+    "@types/node": "^24.10.13",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "babel-plugin-react-compiler": "^1.0.0",
+    "nitro": "npm:nitro-nightly@latest",
+    "publint": "^0.3.20",
+    "typescript": "^6.0.3",
+    "vite-plugin-checker": "^0.13.0"
+  },
+  "peerDependencies": {
+    "@emotion/react": "11.x",
+    "@emotion/styled": "11.x",
+    "@mui/icons-material": "9.x",
+    "@mui/material": "9.x",
+    "@mui/x-data-grid-premium": "9.x",
+    "@mui/x-date-pickers-pro": "9.x",
+    "@tanstack/query-db-collection": "1.x",
+    "@tanstack/react-db": "0.x",
+    "@tanstack/react-form": "1.x",
+    "@tanstack/react-query": "5.x",
+    "@tanstack/react-router": "1.x",
+    "@tanstack/react-router-ssr-query": "1.x",
+    "@tanstack/react-start": "1.x",
+    "axios": "1.x",
+    "dayjs": "1.x",
+    "react": "19.x",
+    "react-dom": "19.x",
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest",
+    "vite-plus": "latest",
+    "zod": "4.x"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core@latest"
+  },
+  "packageManager": "npm@11.14.1"
+}

package/skills/client-db/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: client-db
+description: Querying data on client by creating reactive TanStack DB collections.
+---
+
+## Rules
+
+- Use `eager` syncMode for top-level collections, `on-demand` for child/relational data.
+- Use `useLiveQuery` on list pages (provides `isLoading` for DataGrid), `useLiveSuspenseQuery` on detail/edit pages or components (wrap in `<Suspense>` with loading fallback).
+- For mutations use `createOptimisticAction` — mirror the server mutation in `onMutate`, then call the server function and `collection.utils.refetch()` in `mutationFn`.
+- Use `meta.loadSubsetOptions` for relational subset loading.
+- Use Axios with auth interceptor `getAccessToken` but only for public REST APIs; use default `api` as a scope key.
+
+## File Placement
+
+```
+src/db-collections/           — DB collections
+src/server/actions/           — server functions (select/update/insert/delete)
+src/lib/schemas/              — Zod schemas
+src/lib/auth/scopes.ts        — API scope keys
+wcz-layout/data               — shared data utilities and server functions from npm package
+wcz-layout/utils              — shared utils from npm package
+```
+
+## Examples
+
+```ts
+// imports
+import { queryClient } from "wcz-layout/data";
+import { getAccessToken } from "wcz-layout/utils";
+
+// src/db-collections/library.ts
+export const api = axios.create({
+  baseURL: "/api/libraries",
+});
+
+api.interceptors.request.use(async (config) => {
+  const accessToken = await getAccessToken("api");
+  config.headers.set("Authorization", `Bearer ${accessToken}`);
+  return config;
+});
+
+export const librariesCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["libraries"],
+    queryFn: () => selectLibraries(),
+    getKey: ({ id }) => id,
+    schema: LibrarySchema,
+    queryClient: queryClient,
+    syncMode: "eager",
+  }),
+);
+
+// src/db-collections/book.ts
+export const bookCollection = createCollection(
+  queryCollectionOptions({
+    queryKey: ["books"],
+    queryFn: ({ meta }) => selectBooks({ data: meta?.loadSubsetOptions }),
+    getKey: ({ id }) => id,
+    schema: BookSchema,
+    queryClient: queryClient,
+    syncMode: "on-demand",
+  }),
+);
+
+// src/routes/libraries/edit/$id.tsx
+const { data, isLoading } = useLiveQuery((q) =>
+  q.from({ library: libraryCollection }).orderBy(({ library }) => library.name, "asc"),
+);
+
+const { data } = useLiveQuery((q) =>
+  q
+    .from({ library: libraryCollection })
+    .where(({ library }) => eq(library.id, id))
+    .findOne()
+    .select(({ library }) => ({
+      ...library,
+      books: toArray(
+        q
+          .from({ book: bookCollection })
+          .where(({ book }) => eq(book.libraryId, library.id))
+          .orderBy(({ book }) => book.title, "asc")
+          .select(({ book }) => ({
+            id: book.id,
+            title: book.title,
+          })),
+      ),
+    })),
+);
+
+const handleOnSubmit = createOptimisticAction<Library>({
+  onMutate: (formValues) => {
+    libraryCollection.update(id, (prev) => Object.assign(prev, formValues));
+  },
+  mutationFn: async (formValues) => {
+    await updateLibrary({ data: formValues });
+    await libraryCollection.utils.refetch();
+  },
+});
+
+try {
+  const transaction = handleOnSubmit(formValues);
+  await transaction.isPersisted.promise;
+} catch (error) {
+  if (error instanceof Error) alert(error.message);
+}
+```
+
+## Next Step (ask user after completion)
+
+- Create a new Route

package/skills/db-schema/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: db-schema
+description: Define PostgreSQL database schemas with Drizzle ORM.
+---
+
+## Rules
+
+- Always use `uuid` for primary keys.
+- Define enums with `pgEnum`; they can be shared across schema files.
+- Omit column name strings; Drizzle auto-maps camelCase to snake_case via `casing: "snake_case"`.
+- Use `onDelete: "cascade"` on foreign keys for child/dependent tables.
+- Define relations into `relations.ts` file.
+- Derive form schemas with `.extend()` from the base schema; use `.transform()` to set parent IDs on children.
+- Always add `withTimezone: true` to timestamp columns.
+- Generate Zod schemas with `createSelectSchema`; override fields with stricter rules (trim, min/max) where needed.
+- Don't auto-generate migrations.
+
+## File Placement
+
+```
+src/server/db/migrations/       — migrations
+src/server/db/schemas/          — tables, enums, relations
+src/lib/schemas/                — Zod schemas
+wcz-layout/utils                — shared utils from npm package
+```
+
+## Examples
+
+```ts
+// imports
+import { t } from "wcz-layout/utils";
+
+// src/server/db/schemas/book.ts
+export const bookTable = pgTable("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/book.ts
+export const BookSchema = createSelectSchema(bookTable, {
+  title: (schema) =>
+    schema
+      .trim()
+      .min(1, t("Validation.Required"))
+      .max(255, t("Validation.MaxLength", { length: 255 })),
+});
+
+export type Book = z.infer<typeof BookSchema>;
+```
+
+## Next Step (ask user after completion)
+
+- Create REST API routes or server functions with TanStack Start/Router to query these tables.

package/skills/forms/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: forms
+description: Best practices for building forms including validation and field types.
+---
+
+## Rules
+
+- Always use `useLayoutForm` with pre-defined components.
+- Define `width` for all form fields based on the expected content length.
+- Derive Zod schemas from Drizzle table schemas using `createSelectSchema` with `t()` for validation messages.
+
+## File Placement
+
+```
+src/routes/features/-components   — Form components scoped to a feature
+src/lib/schemas/                  — Zod schemas
+wcz-layout/hooks                  — shared hooks from npm package
+```
+
+## Examples
+
+```ts
+// Imports
+import { useLayoutForm } from "wcz-layout/hooks";
+import { LibrarySchema } from "~/lib/schemas/library";
+
+// Form Component
+interface FormProps {
+  defaultValues: Library;
+  onSubmit: (value: Library) => Promise<void>;
+}
+
+export const Form: FC<FormProps> = ({ defaultValues, onSubmit }) => {
+  const { t } = useTranslation();
+
+  const form = useLayoutForm({
+    defaultValues,
+    validators: { onChange: LibrarySchema },
+    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("Library.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")} />
+```
+
+## Field Types
+
+`Autocomplete` · `Checkbox` · `DatePicker` · `DateRangePicker` · `DateTimePicker` · `DateTimeRangePicker` · `NumberField` · `RadioGroup` · `Slider` · `SubmitButton` · `Switch` · `TextField` · `TimePicker` · `TimeRangePicker`