@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.
- package/dist/commands/check.js +1 -1
- package/dist/commands/check.js.map +1 -1
- package/dist/commands/create.js +82 -165
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/mcp.d.ts.map +1 -1
- package/dist/commands/mcp.js +92 -1
- package/dist/commands/mcp.js.map +1 -1
- package/dist/index.js +1 -1
- package/dist/lib/api-client.d.ts +3 -0
- package/dist/lib/api-client.d.ts.map +1 -1
- package/dist/lib/api-client.js +1 -1
- package/dist/lib/api-client.js.map +1 -1
- package/dist/lib/file-writer.d.ts +2 -0
- package/dist/lib/file-writer.d.ts.map +1 -1
- package/dist/lib/file-writer.js.map +1 -1
- package/dist/lib/harness.d.ts +59 -0
- package/dist/lib/harness.d.ts.map +1 -0
- package/dist/lib/harness.js +178 -0
- package/dist/lib/harness.js.map +1 -0
- package/dist/lib/migrations/drizzle-prompts.d.ts +2 -0
- package/dist/lib/migrations/drizzle-prompts.d.ts.map +1 -1
- package/dist/lib/migrations/drizzle-prompts.js +11 -0
- package/dist/lib/migrations/drizzle-prompts.js.map +1 -1
- package/dist/lib/migrations/file-envelopes.d.ts.map +1 -1
- package/dist/lib/migrations/file-envelopes.js +21 -51
- package/dist/lib/migrations/file-envelopes.js.map +1 -1
- package/dist/lib/migrations/prompt-runner.d.ts.map +1 -1
- package/dist/lib/migrations/prompt-runner.js +6 -1
- package/dist/lib/migrations/prompt-runner.js.map +1 -1
- package/dist/skill/docs/api/actions.md +13 -6
- package/dist/skill/docs/api/batch-operations.md +6 -2
- package/dist/skill/docs/api/crud.md +72 -9
- package/dist/skill/docs/api/errors.md +78 -6
- package/dist/skill/docs/api/openapi.md +1 -1
- package/dist/skill/docs/api/query-params.md +6 -7
- package/dist/skill/docs/api/typescript.md +193 -0
- package/dist/skill/docs/configure/index.md +36 -2
- package/dist/skill/docs/configure/providers.md +32 -7
- package/dist/skill/docs/define/changesets.md +2 -0
- package/dist/skill/docs/define/guards.md +7 -2
- package/dist/skill/docs/define/masking.md +14 -0
- package/dist/skill/docs/define/read.md +3 -0
- package/dist/skill/docs/define/schema.md +13 -10
- package/dist/skill/docs/define/transitions.md +9 -4
- package/dist/skill/docs/index.md +1 -0
- package/dist/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/dist/skill/docs/platform/payments/index.md +1 -1
- package/dist/skill/docs/start/frontend.md +278 -0
- package/dist/skill/docs/start/index.md +1 -0
- package/dist/skill/docs/start/template-blog.md +36 -58
- package/dist/skill/docs/start/templates.md +3 -3
- package/dist/skill/docs/tooling/claude-skill.md +10 -1
- package/dist/skill/docs/tooling/cli.md +5 -1
- package/dist/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- package/dist/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/dist/skill/docs/tooling/output.md +38 -9
- package/dist/skill/docs/tooling/troubleshooting.md +67 -0
- package/dist/skill/docs/ui/admin/actions.md +6 -2
- package/dist/skill/docs/ui/admin/index.md +1 -1
- package/dist/skill/docs/ui/admin/inline-editing.md +6 -2
- package/dist/skill/docs/ui/admin/schema-format.md +74 -36
- package/dist/skill/docs/ui/admin/schema-registry.md +22 -9
- package/dist/skill/docs/ui/admin/security.md +2 -2
- package/dist/skill/docs/ui/components/action-dialog.md +62 -0
- package/dist/skill/docs/ui/components/auth.md +90 -0
- package/dist/skill/docs/ui/components/index.md +48 -0
- package/dist/skill/docs/ui/components/install.md +118 -0
- package/dist/skill/docs/ui/components/quickback-provider.md +123 -0
- package/dist/skill/docs/ui/components/resource-form.md +80 -0
- package/dist/skill/docs/ui/components/resource-table.md +46 -0
- package/dist/templates/registry.js +1 -1
- package/dist/templates/registry.js.map +1 -1
- package/package.json +1 -1
- package/src/skill/docs/api/actions.md +13 -6
- package/src/skill/docs/api/batch-operations.md +6 -2
- package/src/skill/docs/api/crud.md +72 -9
- package/src/skill/docs/api/errors.md +78 -6
- package/src/skill/docs/api/openapi.md +1 -1
- package/src/skill/docs/api/query-params.md +6 -7
- package/src/skill/docs/api/typescript.md +193 -0
- package/src/skill/docs/configure/index.md +36 -2
- package/src/skill/docs/configure/providers.md +32 -7
- package/src/skill/docs/define/changesets.md +2 -0
- package/src/skill/docs/define/guards.md +7 -2
- package/src/skill/docs/define/masking.md +14 -0
- package/src/skill/docs/define/read.md +3 -0
- package/src/skill/docs/define/schema.md +13 -10
- package/src/skill/docs/define/transitions.md +9 -4
- package/src/skill/docs/index.md +1 -0
- package/src/skill/docs/platform/auth/plugins/agent-auth.md +1 -1
- package/src/skill/docs/platform/payments/index.md +1 -1
- package/src/skill/docs/start/frontend.md +278 -0
- package/src/skill/docs/start/index.md +1 -0
- package/src/skill/docs/start/template-blog.md +36 -58
- package/src/skill/docs/start/templates.md +3 -3
- package/src/skill/docs/tooling/claude-skill.md +10 -1
- package/src/skill/docs/tooling/cli.md +5 -1
- package/src/skill/docs/tooling/cloud-compiler/endpoints.md +10 -0
- package/src/skill/docs/tooling/cloud-compiler/troubleshooting.md +6 -0
- package/src/skill/docs/tooling/output.md +38 -9
- package/src/skill/docs/tooling/troubleshooting.md +67 -0
- package/src/skill/docs/ui/admin/actions.md +6 -2
- package/src/skill/docs/ui/admin/index.md +1 -1
- package/src/skill/docs/ui/admin/inline-editing.md +6 -2
- package/src/skill/docs/ui/admin/schema-format.md +74 -36
- package/src/skill/docs/ui/admin/schema-registry.md +22 -9
- package/src/skill/docs/ui/admin/security.md +2 -2
- package/src/skill/docs/ui/components/action-dialog.md +62 -0
- package/src/skill/docs/ui/components/auth.md +90 -0
- package/src/skill/docs/ui/components/index.md +48 -0
- package/src/skill/docs/ui/components/install.md +118 -0
- package/src/skill/docs/ui/components/quickback-provider.md +123 -0
- package/src/skill/docs/ui/components/resource-form.md +80 -0
- 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).
|