@quickback-dev/cli 0.66.21 → 0.66.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (114) hide show
  1. package/dist/commands/check.js +1 -1
  2. package/dist/commands/check.js.map +1 -1
  3. package/dist/commands/create.js +82 -165
  4. package/dist/commands/create.js.map +1 -1
  5. package/dist/commands/mcp.d.ts.map +1 -1
  6. package/dist/commands/mcp.js +92 -1
  7. package/dist/commands/mcp.js.map +1 -1
  8. package/dist/index.js +1 -1
  9. package/dist/lib/api-client.d.ts +3 -0
  10. package/dist/lib/api-client.d.ts.map +1 -1
  11. package/dist/lib/api-client.js +1 -1
  12. package/dist/lib/api-client.js.map +1 -1
  13. package/dist/lib/file-writer.d.ts +2 -0
  14. package/dist/lib/file-writer.d.ts.map +1 -1
  15. package/dist/lib/file-writer.js.map +1 -1
  16. package/dist/lib/harness.d.ts +59 -0
  17. package/dist/lib/harness.d.ts.map +1 -0
  18. package/dist/lib/harness.js +178 -0
  19. package/dist/lib/harness.js.map +1 -0
  20. package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
  21. package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
  22. package/dist/lib/migrations/drizzle-prompts.js +11 -0
  23. package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
  24. package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
  25. package/dist/lib/migrations/file-envelopes.js +21 -51
  26. package/dist/lib/migrations/file-envelopes.js.map +1 -1
  27. package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
  28. package/dist/lib/migrations/prompt-runner.js +6 -1
  29. package/dist/lib/migrations/prompt-runner.js.map +1 -1
  30. package/dist/skill/docs/api/actions.md +13 -6
  31. package/dist/skill/docs/api/batch-operations.md +6 -2
  32. package/dist/skill/docs/api/crud.md +72 -9
  33. package/dist/skill/docs/api/errors.md +78 -6
  34. package/dist/skill/docs/api/openapi.md +1 -1
  35. package/dist/skill/docs/api/query-params.md +6 -7
  36. package/dist/skill/docs/api/typescript.md +193 -0
  37. package/dist/skill/docs/configure/index.md +36 -2
  38. package/dist/skill/docs/configure/providers.md +32 -7
  39. package/dist/skill/docs/define/changesets.md +2 -0
  40. package/dist/skill/docs/define/guards.md +7 -2
  41. package/dist/skill/docs/define/masking.md +14 -0
  42. package/dist/skill/docs/define/read.md +3 -0
  43. package/dist/skill/docs/define/schema.md +13 -10
  44. package/dist/skill/docs/define/transitions.md +9 -4
  45. package/dist/skill/docs/index.md +1 -0
  46. package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  47. package/dist/skill/docs/platform/payments/index.md +1 -1
  48. package/dist/skill/docs/start/frontend.md +278 -0
  49. package/dist/skill/docs/start/index.md +1 -0
  50. package/dist/skill/docs/start/template-blog.md +36 -58
  51. package/dist/skill/docs/start/templates.md +3 -3
  52. package/dist/skill/docs/tooling/claude-skill.md +10 -1
  53. package/dist/skill/docs/tooling/cli.md +5 -1
  54. package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
  55. package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  56. package/dist/skill/docs/tooling/output.md +38 -9
  57. package/dist/skill/docs/tooling/troubleshooting.md +67 -0
  58. package/dist/skill/docs/ui/admin/actions.md +6 -2
  59. package/dist/skill/docs/ui/admin/index.md +1 -1
  60. package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
  61. package/dist/skill/docs/ui/admin/schema-format.md +74 -36
  62. package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
  63. package/dist/skill/docs/ui/admin/security.md +2 -2
  64. package/dist/skill/docs/ui/components/action-dialog.md +62 -0
  65. package/dist/skill/docs/ui/components/auth.md +90 -0
  66. package/dist/skill/docs/ui/components/index.md +48 -0
  67. package/dist/skill/docs/ui/components/install.md +118 -0
  68. package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
  69. package/dist/skill/docs/ui/components/resource-form.md +80 -0
  70. package/dist/skill/docs/ui/components/resource-table.md +46 -0
  71. package/dist/templates/registry.js +1 -1
  72. package/dist/templates/registry.js.map +1 -1
  73. package/package.json +1 -1
  74. package/src/skill/docs/api/actions.md +13 -6
  75. package/src/skill/docs/api/batch-operations.md +6 -2
  76. package/src/skill/docs/api/crud.md +72 -9
  77. package/src/skill/docs/api/errors.md +78 -6
  78. package/src/skill/docs/api/openapi.md +1 -1
  79. package/src/skill/docs/api/query-params.md +6 -7
  80. package/src/skill/docs/api/typescript.md +193 -0
  81. package/src/skill/docs/configure/index.md +36 -2
  82. package/src/skill/docs/configure/providers.md +32 -7
  83. package/src/skill/docs/define/changesets.md +2 -0
  84. package/src/skill/docs/define/guards.md +7 -2
  85. package/src/skill/docs/define/masking.md +14 -0
  86. package/src/skill/docs/define/read.md +3 -0
  87. package/src/skill/docs/define/schema.md +13 -10
  88. package/src/skill/docs/define/transitions.md +9 -4
  89. package/src/skill/docs/index.md +1 -0
  90. package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
  91. package/src/skill/docs/platform/payments/index.md +1 -1
  92. package/src/skill/docs/start/frontend.md +278 -0
  93. package/src/skill/docs/start/index.md +1 -0
  94. package/src/skill/docs/start/template-blog.md +36 -58
  95. package/src/skill/docs/start/templates.md +3 -3
  96. package/src/skill/docs/tooling/claude-skill.md +10 -1
  97. package/src/skill/docs/tooling/cli.md +5 -1
  98. package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
  99. package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
  100. package/src/skill/docs/tooling/output.md +38 -9
  101. package/src/skill/docs/tooling/troubleshooting.md +67 -0
  102. package/src/skill/docs/ui/admin/actions.md +6 -2
  103. package/src/skill/docs/ui/admin/index.md +1 -1
  104. package/src/skill/docs/ui/admin/inline-editing.md +6 -2
  105. package/src/skill/docs/ui/admin/schema-format.md +74 -36
  106. package/src/skill/docs/ui/admin/schema-registry.md +22 -9
  107. package/src/skill/docs/ui/admin/security.md +2 -2
  108. package/src/skill/docs/ui/components/action-dialog.md +62 -0
  109. package/src/skill/docs/ui/components/auth.md +90 -0
  110. package/src/skill/docs/ui/components/index.md +48 -0
  111. package/src/skill/docs/ui/components/install.md +118 -0
  112. package/src/skill/docs/ui/components/quickback-provider.md +123 -0
  113. package/src/skill/docs/ui/components/resource-form.md +80 -0
  114. package/src/skill/docs/ui/components/resource-table.md +46 -0
@@ -0,0 +1,90 @@
1
+ # Auth
2
+
3
+ The components never touch credentials. The emitted client you pass to
4
+ `<QuickbackProvider client>` decides how each request is authenticated.
5
+
6
+ | Mode | Use it for | Credential | Writes need |
7
+ |---|---|---|---|
8
+ | `auth: "cookie"` (default) | Browser apps | Better Auth session cookie, `credentials: "include"` | The page's origin in the trusted origins |
9
+ | `auth: "bearer"` | React Native, CLIs, servers | `Authorization: Bearer <token>` | Nothing extra. Bearer requests skip the CSRF origin check. |
10
+
11
+ ## Browser: cookie
12
+
13
+ Sign in with Better Auth's own client. The session cookie it sets is what the
14
+ Quickback client sends.
15
+
16
+ ```tsx
17
+ import { createAuthClient } from "better-auth/react"
18
+ import { organizationClient } from "better-auth/client/plugins"
19
+ import { createClient } from "@/lib/quickback.client"
20
+
21
+ const baseURL = import.meta.env.VITE_API_URL // e.g. http://localhost:8787
22
+
23
+ export const auth = createAuthClient({
24
+ baseURL,
25
+ basePath: "/auth/v1",
26
+ plugins: [organizationClient()],
27
+ })
28
+
29
+ export const client = createClient({ baseUrl: baseURL })
30
+
31
+ await auth.signIn.email({ email, password })
32
+ // Tenant-scoped tables are firewalled to the session's active organization.
33
+ await auth.organization.setActive({ organizationId })
34
+ ```
35
+
36
+ The cookie only works if the API trusts your page's origin:
37
+
38
+ - **Same Worker (recommended).** Mount the built app with
39
+ [`apps.<name>`](/configure/domains#app-domains). It is then served on the
40
+ same origin as `/api` and `/auth`, and its hostname is trusted
41
+ automatically.
42
+ - **Local dev.** Until a project has a production domain, `http://localhost:5173`
43
+ (Vite), `:3000`, and `:8787` are trusted by default.
44
+ - **Anywhere else.** Add the origin to
45
+ [`trustedOrigins`](/configure#trusted-origins). A write from an untrusted
46
+ origin fails with `403 CSRF_ORIGIN_REJECTED`, and the browser blocks reads
47
+ through CORS.
48
+
49
+ ## React Native and other non-browser clients: bearer
50
+
51
+ React Native has no cookie jar and sends no `Origin` header. Cookie-backed
52
+ writes therefore fail with `403 CSRF_ORIGIN_REJECTED`. Use the bearer lane
53
+ instead:
54
+
55
+ ```tsx
56
+ import * as SecureStore from "expo-secure-store"
57
+ import { createClient } from "@/lib/quickback.client"
58
+
59
+ const KEY = "quickback_session"
60
+
61
+ export const client = createClient({
62
+ baseUrl: "https://api.example.com",
63
+ auth: "bearer",
64
+ sessionStore: {
65
+ get: () => SecureStore.getItemAsync(KEY),
66
+ set: (token) => (token ? SecureStore.setItemAsync(KEY, token) : SecureStore.deleteItemAsync(KEY)),
67
+ },
68
+ })
69
+
70
+ // set-auth-token on /auth/v1/* is saved to sessionStore.
71
+ await client.request("POST", "/auth/v1/sign-in/email", { body: { email, password } })
72
+ await client.request("POST", "/auth/v1/organization/set-active", { body: { organizationId } })
73
+ ```
74
+
75
+ Sign in **through the client**, as above. It saves the `set-auth-token`
76
+ **header**: the signed `<token>.<signature>`. If you sign in with your own
77
+ `fetch`, store that header too, never the body's `token`. The body carries
78
+ the raw session id, and the generated API runs Better Auth's
79
+ `bearer({ requireSignature: true })`. An unsigned token is silently ignored:
80
+ `get-session` returns `null` and every API call answers `401`.
81
+
82
+ With `auth: "bearer"`, the client:
83
+
84
+ - sends `Authorization: Bearer <token>` and defaults `credentials` to `"omit"`;
85
+ - caches the short-lived JWT that API responses return in `set-auth-token`
86
+ (see [JWT optimization](/platform/auth/jwt-optimization));
87
+ - on a `401` with a cached JWT, drops the JWT and retries once with the
88
+ session token from `sessionStore`.
89
+
90
+ Full lane semantics: [Bearer lane](/api/typescript#bearer-lane-react-native-native-clients).
@@ -0,0 +1,48 @@
1
+ # Components
2
+
3
+ Add tables, forms, and action dialogs for your API to your own React app with
4
+ `shadcn add`. There's no fork of the CMS and no admin framework involved. Each
5
+ component is a file in your repo, and you edit it like any other code.
6
+
7
+ ```bash
8
+ npx shadcn add @quickback/resource-table @quickback/resource-form @quickback/action-dialog
9
+ ```
10
+
11
+ ## Two layers
12
+
13
+ | Layer | Who owns it | Regenerated? | Knows the wire format? |
14
+ |---|---|---|---|
15
+ | `quickback.client.ts` | The compiler emits it (`client` config) | Every compile | **Yes. Only this file does.** |
16
+ | `quickback-provider`, `resource-table`, `resource-form`, `action-dialog` | You. `shadcn add` copies them into your repo | Never | No |
17
+
18
+ The components never build a URL, unwrap a list envelope, or parse
19
+ `application/problem+json`. They call the emitted
20
+ [fetch client](/api/typescript#fetch-client) and read the
21
+ [schema registry](/ui/admin/schema-registry) for column kinds, guards, and
22
+ action inputs. When the API changes shape, you recompile and only the client
23
+ changes. Your edits to the components survive.
24
+
25
+ ## Base-ui only
26
+
27
+ The items target shadcn's **base-ui** styles (`base-nova`, `base-mira`, …).
28
+ Radix styles are not supported.
29
+
30
+ - They compose your own primitives (`button`, `dialog`, `table`, …) through
31
+ `registryDependencies`, using base-ui's `render=` prop where composition is
32
+ needed.
33
+ - They never use Radix's `asChild`. On a base-ui project, `shadcn add`
34
+ silently rewrites `asChild` to `render={<firstChild />}`. That still
35
+ typechecks but drops the other children.
36
+ - The namespace URL includes the style (`/r/{style}/{name}.json`), and only
37
+ `base-*` paths exist. A Radix project therefore fails at **install**, with a
38
+ `404` that names its style, before any file is written.
39
+
40
+ ## Pages
41
+
42
+ - [Install](/ui/components/install): the `client` config, the `@quickback` namespace, and direct URLs
43
+ - [Auth](/ui/components/auth): cookie vs bearer, React Native
44
+ - [`quickback-provider`](/ui/components/quickback-provider): `<QuickbackProvider>` and the TanStack Query hooks
45
+ - [`resource-table`](/ui/components/resource-table): paginated, sortable, searchable list
46
+ - [`resource-form`](/ui/components/resource-form): create / edit form
47
+ - [`action-dialog`](/ui/components/action-dialog): run an action with its inputs
48
+ - [Build a frontend](/start/frontend): end-to-end guide
@@ -0,0 +1,118 @@
1
+ # Install
2
+
3
+ ## Requirements
4
+
5
+ - A React app initialised with a shadcn **base-ui** style. `components.json` has `"style": "base-…"`. For a new Vite app:
6
+ `npx shadcn@latest init -t vite -b base -p nova`
7
+ - The `@/` import alias. The shadcn templates set it up.
8
+ - The emitted client at `@/lib/quickback.client`. Every item imports it from that path.
9
+
10
+ ## 1. Emit the client into the frontend
11
+
12
+ In `quickback.config.ts`, point `client` at the frontend's `src/lib/`. Put
13
+ the `types` output next to it. The client imports `Api` and `Qb` from the
14
+ first `types` output by relative path, so keeping both inside the frontend
15
+ keeps its `tsconfig` self-contained.
16
+
17
+ ```typescript
18
+ import { defineConfig } from "@quickback/compiler";
19
+
20
+ export default defineConfig({
21
+ name: "my-app",
22
+ types: { output: "web/src/lib/quickback.gen.ts" },
23
+ client: "web/src/lib/quickback.client.ts",
24
+ });
25
+ ```
26
+
27
+ `client` requires `types`. The compile fails if `types` is `false`.
28
+ `quickback build` rewrites both files on every compile. Don't edit them. See
29
+ [Fetch client](/api/typescript#fetch-client) for the full client API.
30
+
31
+ The components read the schema registry from `GET /api/v1/schema`. By
32
+ default only platform sysadmins may read it. For a UI that other users use,
33
+ widen it with [`schemaRegistry.access`](/configure#schema-registry-access):
34
+
35
+ ```typescript
36
+ export default defineConfig({
37
+ schemaRegistry: { access: "member" }, // any organization member
38
+ // schemaRegistry: { access: "authenticated" }, // any signed-in user (apps without organizations)
39
+ });
40
+ ```
41
+
42
+ Without this, every component shows a `403 CMS_ACCESS_DENIED` error. When
43
+ `cms` is also enabled, `schemaRegistry.access` must equal `cms.access`. The
44
+ route gates the CMS too, so widening one must not silently widen the other.
45
+
46
+ ## 2. Add the registry
47
+
48
+ **Namespace (recommended).** Add the registry to the frontend's
49
+ `components.json`:
50
+
51
+ ```json
52
+ {
53
+ "registries": {
54
+ "@quickback": "https://docs.quickback.dev/r/{style}/{name}.json"
55
+ }
56
+ }
57
+ ```
58
+
59
+ ```bash
60
+ npx shadcn add @quickback/quickback-provider @quickback/resource-table @quickback/resource-form @quickback/action-dialog
61
+ ```
62
+
63
+ shadcn fills `{style}` from `components.json`. Only `base-*` style paths
64
+ exist, so a Radix project stops here with nothing written:
65
+
66
+ ```
67
+ The item at https://docs.quickback.dev/r/radix-nova/resource-table.json was not found. It may not exist at the registry.
68
+ Message:
69
+ [Quickback registry items support shadcn base-ui styles only; "radix-nova" is not one. See https://docs.quickback.dev/ui/components]
70
+ ```
71
+
72
+ **Direct URL.** Add one item without configuring the namespace:
73
+
74
+ ```bash
75
+ npx shadcn add https://docs.quickback.dev/r/resource-table.json
76
+ ```
77
+
78
+ Direct URLs resolve `quickback-provider` for you, but they skip the style
79
+ check. Use them only on a base-ui project.
80
+
81
+ | URL | Serves |
82
+ |---|---|
83
+ | `https://docs.quickback.dev/r/registry.json` | Registry index |
84
+ | `https://docs.quickback.dev/r/{name}.json` | One item (direct-URL installs) |
85
+ | `https://docs.quickback.dev/r/base-{style}/{name}.json` | One item (namespace installs) |
86
+
87
+ `{name}` is one of `quickback-provider`, `resource-table`, `resource-form`, `action-dialog`.
88
+
89
+ ## 3. What gets installed
90
+
91
+ | Item | Files | Also installs |
92
+ |---|---|---|
93
+ | `quickback-provider` | `components/quickback-provider.tsx` | `@tanstack/react-query@^5` |
94
+ | `resource-table` | `components/resource-table.tsx` | `button`, `dropdown-menu`, `input`, `label`, `table`, `@remixicon/react` |
95
+ | `resource-form` | `components/resource-form.tsx` | `button`, `checkbox`, `combobox`, `input`, `label`, `native-select`, `textarea`, `@remixicon/react` |
96
+ | `action-dialog` | `components/action-dialog.tsx` | `button`, `checkbox`, `dialog`, `input`, `label`, `native-select`, `@remixicon/react` |
97
+
98
+ Every item except `quickback-provider` depends on it, so adding any one of
99
+ them pulls it in. Re-run `shadcn add` with `--overwrite` to take a newer
100
+ version. That replaces any local edits you made to those files.
101
+
102
+ ## 4. Wire it up
103
+
104
+ ```tsx
105
+ // web/src/main.tsx
106
+ import { createClient } from "@/lib/quickback.client"
107
+ import { QuickbackProvider } from "@/components/quickback-provider"
108
+
109
+ const client = createClient({ baseUrl: import.meta.env.VITE_API_URL })
110
+
111
+ createRoot(document.getElementById("root")!).render(
112
+ <QuickbackProvider client={client}>
113
+ <App />
114
+ </QuickbackProvider>,
115
+ )
116
+ ```
117
+
118
+ Next: [Auth](/ui/components/auth) to sign users in. For the whole flow, see [Build a frontend](/start/frontend).
@@ -0,0 +1,123 @@
1
+ # quickback-provider
2
+
3
+ ```bash
4
+ npx shadcn add @quickback/quickback-provider
5
+ ```
6
+
7
+ Installs `components/quickback-provider.tsx` and `@tanstack/react-query@^5`.
8
+ The other items import their hooks from it.
9
+
10
+ ## `<QuickbackProvider>`
11
+
12
+ ```tsx
13
+ import { createClient } from "@/lib/quickback.client"
14
+ import { QuickbackProvider } from "@/components/quickback-provider"
15
+
16
+ const client = createClient({ baseUrl: "https://api.example.com" })
17
+
18
+ <QuickbackProvider client={client} roles={roles}>
19
+ <App />
20
+ </QuickbackProvider>
21
+ ```
22
+
23
+ | Prop | Type | Description |
24
+ |---|---|---|
25
+ | `client` | `Client` | The result of `createClient()` from the emitted `@/lib/quickback.client`. Required. |
26
+ | `roles` | `readonly string[]` | The signed-in caller's roles, e.g. the active organization member role from Better Auth. A UI hint only. See [Roles](#roles). |
27
+ | `realtime` | `{ subscribe(handler) => unsubscribe }` | Source of realtime frames for `useLive`. Defaults to `client.realtime` when the emitted client has one. |
28
+ | `queryClient` | `QueryClient` | Share your app's TanStack Query cache. Omit it and the provider creates one that retries network errors and `5xx` twice and never retries a `4xx`. |
29
+ | `children` | `ReactNode` | |
30
+
31
+ ## Hooks
32
+
33
+ Every hook takes a **schema-registry table name** (`"jobs"`). The name is
34
+ resolved through the client's `resources` table, so generic UI never
35
+ hard-codes a URL. An unknown name throws `Unknown Quickback resource "<name>"`.
36
+ Calling a verb the table has no route for throws `"<table>" has no <verb> route`.
37
+
38
+ | Hook | Returns | Notes |
39
+ |---|---|---|
40
+ | `useQuickback()` | `Client` | The typed client. Use it for anything the hooks don't cover. |
41
+ | `useRoles()` | `readonly string[] \| undefined` | The `roles` passed to the provider. |
42
+ | `useSchema()` | query of `SchemaRegistry` | `GET /api/v1/schema`. Cached for the session. |
43
+ | `useTableMeta(table)` | `TableMeta \| undefined` | One table from the registry. `undefined` while the registry loads. |
44
+ | `useOps(table)` | `string[]` | The operations that have a route (`list`, `get`, `create`, …). |
45
+ | `useList(table, params?)` | query of `{ data, pagination }` | `params` takes [list params](/api/query-params), plus `view` to read a named view and `enabled`. Keeps the previous page while the next one loads. |
46
+ | `useInfiniteList(table, params?)` | infinite query | Pages with the keyset cursor (`nextCursor` → `startingAfter`). Falls back to offset when the server returns no cursor, for example when sorting on a masked column. |
47
+ | `useRecord(table, id)` | query of the record | Disabled while `id` is `undefined`. |
48
+ | `useCreate(table)` | mutation `(body) => row` | |
49
+ | `useUpdate(table)` | mutation `({ id, body }) => row` | |
50
+ | `useDelete(table)` | mutation `(id) => void` | |
51
+ | `useAction(table, action)` | mutation `({ id?, params?, input }) => output` | Record-bound actions need `id`. Standalone actions with path parameters need `params`. |
52
+ | `useLive(table, enabled = true)` | `boolean` | Refetches the table when a `postgres_changes` frame for it arrives. Returns whether a realtime source is wired up. |
53
+ | `useDebouncedValue(value, ms = 250)` | `T` | `value`, updated only after it stops changing for `ms`. |
54
+
55
+ Every mutation invalidates all of the table's cached queries.
56
+
57
+ ```tsx
58
+ import { useList, useUpdate } from "@/components/quickback-provider"
59
+
60
+ function OpenJobs() {
61
+ const jobs = useList("jobs", { filter: { status: "open" }, sort: "-createdAt", limit: 10 })
62
+ const update = useUpdate("jobs")
63
+ if (jobs.isPending) return <p>Loading…</p>
64
+ return jobs.data?.data.map((job) => (
65
+ <button key={String(job.id)} onClick={() => update.mutate({ id: String(job.id), body: { status: "closed" } })}>
66
+ Close {String(job.title)}
67
+ </button>
68
+ ))
69
+ }
70
+ ```
71
+
72
+ The hooks are deliberately untyped by name (`Row = Record<string, unknown>`),
73
+ because they serve generic UI. For typed rows, call the client directly:
74
+ `useQuickback().jobs.list()` returns `Api.jobs.Row[]`.
75
+
76
+ ## Roles
77
+
78
+ The emitted client has no session method, so the provider only knows the
79
+ caller's roles if you pass them. Read the role from your auth client:
80
+
81
+ ```tsx
82
+ const member = auth.useActiveMember() // better-auth organizationClient()
83
+ <QuickbackProvider client={client} roles={member.data ? [member.data.role] : undefined}>
84
+ ```
85
+
86
+ Roles are a **UI hint**. The API stays authoritative:
87
+
88
+ - **Masking.** A [masked](/define/masking) column is read-only unless the
89
+ roles satisfy its `show` rule. With no `roles`, every masked column is
90
+ read-only. A value that arrives masked (`[REDACTED]`, `j***@…`) is always
91
+ read-only.
92
+ - **Access.** When the roles plainly fail an operation's `access.roles`,
93
+ the form's Delete button is hidden and the action dialog shows a role
94
+ message instead of its form. The client can't decide hierarchy
95
+ (`member+`), `record`, or FGA rules, so those controls stay available and
96
+ the API answers.
97
+
98
+ ## Realtime
99
+
100
+ `useLive(table)` refetches the table on its change frames. `ResourceTable`
101
+ calls it unless `live={false}`. The frames come from `client.realtime` when
102
+ the emitted client has one, which it does when the project enables
103
+ [realtime](/api/typescript#realtime). Otherwise pass any
104
+ `{ subscribe(handler) => unsubscribe }` source as `realtime`. See
105
+ [Using Realtime](/platform/realtime/using-realtime) for the ticket and
106
+ WebSocket handshake.
107
+
108
+ ## Helpers
109
+
110
+ The other items use these, and you can too:
111
+
112
+ | Export | Description |
113
+ |---|---|
114
+ | `describeError(error)` | `{ message, fields, status? }`. `message` is the problem's `detail`, then its `title`, then `error.message`. `fields` maps field names to messages, from [`QuickbackError.fields`](/api/typescript#fetch-client). |
115
+ | `isMasked(meta, column, roles, value?)` | Whether the column may reach these roles masked. |
116
+ | `canAccess(access, roles)` | Best-effort role check. Returns `true` for rules the client can't decide. |
117
+ | `canWrite(meta, op, roles)` | `canAccess` for `create` / `update` / `delete` from the registry. |
118
+ | `getDisplayColumn(tableMeta)` | The column that names a record: the table's `displayColumn`, else the first of `name`, `title`, `label`, … |
119
+ | `formatLabel(name)` / `columnLabel(name, col?)` | `salaryMin` → `Salary Min`. An FK column reads as its target: `companyId` → `Company`. |
120
+ | `REDACTED` | `"[REDACTED]"`, the value the API sends in place of a redacted value. |
121
+
122
+ Types: `TableMeta`, `ColumnMeta`, `ActionMeta` (all derived from the emitted
123
+ `SchemaRegistry`), `Row`, `Page`, `RealtimeSource`, and `RealtimeFrame`.
@@ -0,0 +1,80 @@
1
+ # resource-form
2
+
3
+ ```bash
4
+ npx shadcn add @quickback/resource-form
5
+ ```
6
+
7
+ ```tsx
8
+ import { ResourceForm } from "@/components/resource-form"
9
+
10
+ // Create
11
+ <ResourceForm table="jobs" onSuccess={(row) => navigate(`/jobs/${row.id}`)} />
12
+
13
+ // Edit, with a confirmed Delete
14
+ <ResourceForm table="jobs" id={jobId} onSuccess={close} onCancel={close} onDeleted={close} />
15
+ ```
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Description |
20
+ |---|---|---|
21
+ | `table` | `string` | Schema-registry table name. Required. |
22
+ | `id` | `string` | Record id. Set it to edit that record (the form loads it first). Leave it out to create a new one. |
23
+ | `onSuccess` | `(row) => void` | Called with the saved record. The API's bare record, not an envelope. |
24
+ | `onCancel` | `() => void` | Shows a Cancel button when set. |
25
+ | `onDeleted` | `(id) => void` | Edit mode. Shows a Delete button that asks for confirmation inline, then calls this. See [Delete](#delete) for when the button is hidden. |
26
+
27
+ ## Which fields appear
28
+
29
+ The form shows exactly the fields the API accepts:
30
+
31
+ - **Create** shows [`guards.createable`](/define/guards). **Edit** shows
32
+ `guards.updatable`.
33
+ - These fields are read-only, with persistent helper text saying why:
34
+ `guards.immutable` fields on edit, `guards.protected` fields ("Updated via
35
+ actions only"), and masked fields the caller's [roles](/ui/components/quickback-provider#roles)
36
+ can't see unmasked.
37
+ - The form needs the table's `create` (create mode) or `update` (edit mode)
38
+ route. Without it, submitting fails with `"<table>" has no create route`.
39
+
40
+ ## Controls
41
+
42
+ | Column | Control |
43
+ |---|---|
44
+ | `inputHints` entry `textarea` / `richtext` | Textarea |
45
+ | Enum validation | Select of the allowed values |
46
+ | FK (`.references()`) | Searchable combobox over the target table (see below) |
47
+ | `bool` | Checkbox |
48
+ | `timestamp` / `date` | Date-time / date input |
49
+ | `decimal` | Text input. `q.decimal()` is an exact decimal string, and a number input would round it. |
50
+ | `json` or array | Textarea (JSON) |
51
+ | `int`, `bigint`, `smallint`, `real` | Number input, with `min` / `max` from validation |
52
+ | `url` | URL input |
53
+ | `email` validation | Email input |
54
+ | anything else | Text input |
55
+
56
+ Constraints show as persistent helper text under the field
57
+ (`Up to 200 characters · Optional`), never as placeholder text.
58
+
59
+ **FK lookups** query the target table as you type (`?search=`, debounced)
60
+ and load more rows by cursor on demand, so there is no first-page cap. When
61
+ the target declares named views, it must set `read.defaultView`. Without it
62
+ the field is disabled with `<Target> needs read.defaultView to be looked up`.
63
+
64
+ ## Validation and errors
65
+
66
+ - **Before submit**, the form checks the registry's `validation` block:
67
+ required (NOT NULL without a default on create, NOT NULL on edit),
68
+ `minLength` / `maxLength`, `min` / `max`, whole numbers for integer
69
+ columns, enum membership, URL, email, and `pattern`.
70
+ - **On submit**, create sends every non-blank value. Edit sends only the
71
+ fields you changed. A field you cleared is sent as `null`, which clears
72
+ it. It is never sent as `""`.
73
+ - **Server errors** show the problem's `detail` above the form. Per-field
74
+ messages from `QuickbackError.fields` are shown under their fields.
75
+
76
+ ## Delete
77
+
78
+ The Delete button renders only when **all** of these hold: `onDeleted` is
79
+ set, the table has a `delete` route, and the caller's roles don't plainly
80
+ fail its `access.roles`. It asks for confirmation before calling the API.
@@ -0,0 +1,46 @@
1
+ # resource-table
2
+
3
+ ```bash
4
+ npx shadcn add @quickback/resource-table
5
+ ```
6
+
7
+ ```tsx
8
+ import { ResourceTable } from "@/components/resource-table"
9
+
10
+ <ResourceTable
11
+ table="jobs"
12
+ onRowClick={(row) => navigate(`/jobs/${row.id}`)}
13
+ rowActions={(row) => <CloseJobButton id={String(row.id)} />}
14
+ />
15
+ ```
16
+
17
+ ## Props
18
+
19
+ | Prop | Type | Default | Description |
20
+ |---|---|---|---|
21
+ | `table` | `string` | required | Schema-registry table name. |
22
+ | `view` | `string` | — | Read through a named [view](/define/views). Omit it to read the collection route, which serves `read.defaultView` when the table sets one. |
23
+ | `columns` | `string[]` | every non-system column | Columns visible at first. Users toggle the rest from the column menu. |
24
+ | `pageSize` | `number` | `25` | Sent as `limit`. The server caps it at the table's `maxPageSize`. |
25
+ | `onRowClick` | `(row) => void` | — | Makes rows clickable. |
26
+ | `rowActions` | `(row) => ReactNode` | — | Renders a trailing cell per row, e.g. edit or action buttons. |
27
+ | `live` | `boolean` | `true` | Refetch on realtime change frames for this table (see [Realtime](/ui/components/quickback-provider#realtime)). Has no effect without a realtime source. |
28
+ | `className` | `string` | — | |
29
+
30
+ ## Behavior
31
+
32
+ - **Columns** come from the view's declared `fields` when it has them, else
33
+ from the schema. The primary key, the tenant scope, and audit bookkeeping
34
+ (`createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`) start
35
+ hidden.
36
+ - **Pagination** uses the keyset cursor (`startingAfter` / `endingBefore`). It
37
+ falls back to offset when the server returns no cursor, for example when
38
+ sorting on a masked column.
39
+ - **Search** is debounced and sent as `?search=`. The box is hidden when the
40
+ view's `query.searchable` is empty, since the server would answer `400`.
41
+ - **Sorting** is by column header, sent as `?sort=`. The first load uses the
42
+ table's `defaultSort`.
43
+ - **States.** Loading, empty (`No records yet`, or `No records match "…"`),
44
+ and error with a retry button. The error shows the problem's `detail`.
45
+ - **Masked fields** render exactly what the API returns (`[REDACTED]`,
46
+ `***-**-1234`). The table can't see past [masking](/define/masking).