create-quadrokit 0.3.2 → 0.3.4

package/README.md

@@ -32,7 +32,7 @@ Interactive mode: run without `--template` / `--dir` / `--name` to be prompted.
 ## What it does
 
 1. Copies the chosen template from `create-quadrokit/templates/<name>` when installed from npm, or `packages/templates/<name>` when you run the CLI from the monorepo (skips `node_modules`, `dist`, `.quadrokit`, lockfiles).
-2. Overlays **`template-common/`** (shared across all templates): `.env.example`, `vite.config.ts`, `tailwind.config.ts`, `tsconfig*.json`, `postcss.config.js`, `biome.json`, `src/vite-env.d.ts`, `.cursor/rules/commitlint-conventional.mdc`, etc. In the monorepo, `packages/templates/*` receives the same overlay via `bun run sync:template-common` (root **postinstall** and `bun run build`); those paths are gitignored under `packages/templates/` so only `template-common/` is the source of truth in git.
+2. Overlays **`template-common/`** (shared across all templates): `.env.example`, `vite.config.ts`, `tailwind.config.ts`, `tsconfig*.json`, `postcss.config.js`, `biome.json`, `src/vite-env.d.ts`, `.cursor/rules/commitlint-conventional.mdc`, `.agents/skills/**`, `skills-lock.json`, etc. In the monorepo, `packages/templates/*` receives the same overlay via `bun run sync:template-common` (root **postinstall** and `bun run build`); those paths are gitignored under `packages/templates/` so only `template-common/` is the source of truth in git.
 3. Rewrites `src/lib/quadro-client.ts` to import from `@quadrokit/generated/client.gen.js` (alias in `vite.config.ts` / `tsconfig.app.json`).
 4. Removes `@quadrokit/sample-client` and rewrites any `workspace:…` protocol on `@quadrokit/*` deps to published semver ranges. **`quadrokitScaffoldVersions`** in this package’s `package.json` pins `^` ranges for `@quadrokit/client` and `@quadrokit/ui` (fallback: `^<create-quadrokit version>`). Use **`--keep-workspace`** only for development inside the QuadroKit repo.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-quadrokit",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Scaffold a QuadroKit Vite + React app from a template",
   "type": "module",
   "bin": "./dist/index.mjs",
@@ -26,7 +26,7 @@
     "typescript": "^5.9.3"
   },
   "quadrokitScaffoldVersions": {
-    "@quadrokit/client": "^0.3.2",
-    "@quadrokit/ui": "^0.3.2"
+    "@quadrokit/client": "^0.3.4",
+    "@quadrokit/ui": "^0.3.4"
   }
 }

package/template-common/.agents/skills/quadro-paged-collection/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: quadro-paged-collection
+description: >-
+  Prefer `useQuadroPagedCollection` from `@quadrokit/ui` for client-side paginated
+  Quadro REST lists (page, page size, next/prev, loading and error). Use when
+  building tables or lists with pagination, infinite scroll that maps to pages,
+  or any UI that loads a slice of a `.all()` collection from the generated
+  `quadro` client.
+---
+
+# Quadro paginated collections
+
+## Default pattern
+
+For **paginated** data backed by the generated Quadro client (`@/lib/quadro-client`), use **`useQuadroPagedCollection`** from `@quadrokit/ui`. It wires `page` / `pageSize` to the collection API and returns **`rows`**, **`hasNext`**, **`loading`**, and **`error`**.
+
+Do **not** hand-roll `useEffect` + `useState` to call `.all()` with skip/limit unless there is a documented reason the hook cannot be used.
+
+## How to wire it
+
+1. Import `useQuadroPagedCollection` from `@quadrokit/ui` and `CollectionHandle` from `@quadrokit/client/runtime` when you need typed handles.
+2. Import the **`quadro`** singleton from `@/lib/quadro-client`.
+3. Keep **`page`** and **`pageSize`** in React state (reset page when page size changes).
+4. Pass an **`all`** function that forwards to the appropriate `quadro.<Table>.all({ ...opts, select: [...] })` and returns a **`CollectionHandle<Row>`** (cast if needed so the row type matches your `select` projection).
+
+## Reference implementation
+
+See `src/pages/SampleDataPage.tsx` for a full example: agency list with row type matching `select`, prev/next buttons, and `hasNext` for the next button.
+
+## When not to use
+
+- **Non-paginated** loads: a single `.all()` or `.one()` without paging UX can call the client directly or use a simpler pattern.
+- **Server-only** routes: this hook is for client components; server data fetching follows your SSR/RSC patterns instead.