@quickback-dev/cli 0.10.15 → 0.10.20

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 (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -0,0 +1,199 @@
1
+ # Actions
2
+
3
+ Actions are custom operations defined in your feature files (e.g., `approve`, `void`, `post`, `applyPayment`). The CMS renders them as clickable buttons with auto-generated input forms — no UI code required.
4
+
5
+ ## Where Actions Appear
6
+
7
+ Actions show up in two places:
8
+
9
+ ### Row Action Menu (Table Mode)
10
+
11
+ In Table mode, the three-dot menu on each row includes a section for custom actions. Actions are separated from standard operations (view, edit, delete) by a divider.
12
+
13
+ ### Action Bar (Detail View)
14
+
15
+ In the record detail view, an "Actions" card displays all available actions as buttons. Each button shows the action name, and hovering reveals the description as a tooltip.
16
+
17
+ ## Action Dialog
18
+
19
+ Clicking an action opens a modal dialog with:
20
+
21
+ 1. **Header** — Action name with an icon (lightning bolt for standard, warning triangle for destructive, download for file responses)
22
+ 2. **Description** — The action's description text
23
+ 3. **Side effects warning** — If the action has `sideEffects: "sync"`, an amber warning banner appears: "This action has synchronous side effects (e.g., GL entries)."
24
+ 4. **Confirmation step** — If the action has `cms.confirm`, a confirmation message appears before the input form
25
+ 5. **Input fields** — Auto-generated from the action's `inputFields` schema
26
+ 6. **Execute button** — Submits the action. Shows "Executing..." while in progress.
27
+ 7. **Cancel button** — Closes the dialog without executing
28
+
29
+ ### Input Field Types
30
+
31
+ The dialog generates the appropriate input control for each field:
32
+
33
+ | Zod Type | Input Control | Notes |
34
+ |----------|--------------|-------|
35
+ | `string` | Text input | Free-text entry |
36
+ | `number` | Number input | Step 0.01, supports decimals |
37
+ | `boolean` | Checkbox | With label text |
38
+ | `array<string>` | Text input | Comma-separated values, split on save |
39
+
40
+ Required fields are marked with a red asterisk. Default values from the schema are pre-filled.
41
+
42
+ ### Example
43
+
44
+ Given this action definition:
45
+
46
+ ```typescript
47
+ actions: {
48
+ applyPayment: {
49
+ description: "Apply a payment to this invoice",
50
+ input: 'z.object({ amount: z.number(), reference: z.string().optional() })',
51
+ access: {
52
+ roles: ['admin', 'owner'],
53
+ record: { status: { equals: 'posted' } },
54
+ },
55
+ sideEffects: "sync",
56
+ cms: {
57
+ label: "Apply Payment",
58
+ icon: "dollar-sign",
59
+ confirm: "This will create GL entries. Continue?",
60
+ category: "payments",
61
+ successMessage: "Payment applied successfully",
62
+ order: 1,
63
+ },
64
+ },
65
+ }
66
+ ```
67
+
68
+ The CMS renders a dialog with:
69
+
70
+ - A number input for `amount` (required)
71
+ - A text input for `reference` (optional)
72
+ - A sync side effects warning
73
+ - A confirmation step with the custom message
74
+ - Only visible to admins and owners
75
+ - Only visible on records where `status === "posted"`
76
+
77
+ ## Access Filtering
78
+
79
+ Actions are filtered based on two criteria:
80
+
81
+ ### Role Check
82
+
83
+ The action's `access.roles` array is compared against the current user's role. If the user's role is not in the list, the action is hidden.
84
+
85
+ ### Record Condition
86
+
87
+ The action's `access.record` conditions are evaluated against the current record's data. Supported conditions:
88
+
89
+ | Operator | Example | Meaning |
90
+ |----------|---------|---------|
91
+ | `equals` | `{ status: { equals: 'pending' } }` | Field must equal value |
92
+ | `notEquals` | `{ status: { notEquals: 'void' } }` | Field must not equal value |
93
+ | `in` | `{ status: { in: ['pending', 'draft'] } }` | Field must be one of values |
94
+
95
+ All conditions must pass for the action to be visible. This means "approve" actions naturally disappear after a record is approved, and "void" actions only appear on voidable records.
96
+
97
+ ## CMS Metadata
98
+
99
+ Actions can include an optional `cms` property for enhanced CMS rendering. Actions without `cms` render with default behavior.
100
+
101
+ | Property | Type | Default | Purpose |
102
+ |----------|------|---------|---------|
103
+ | `label` | `string` | camelCase split | Display name override |
104
+ | `icon` | `string` | `"zap"` | Lucide icon name |
105
+ | `confirm` | `string \| boolean` | `false` | `true` = generic confirm, string = custom message |
106
+ | `destructive` | `boolean` | `false` | Red styling + requires confirmation |
107
+ | `category` | `string` | none | Group actions under a header |
108
+ | `hidden` | `boolean` | `false` | Hide from CMS entirely (API-only actions) |
109
+ | `successMessage` | `string` | none | Toast message after success |
110
+ | `onSuccess` | `"refresh" \| "redirect:list" \| "close"` | `"refresh"` | Behavior after successful execution |
111
+ | `order` | `number` | `0` | Sort priority (lower = first) |
112
+
113
+ ### Example with CMS metadata
114
+
115
+ ```typescript
116
+ // features/invoices/actions/post.ts
117
+ import { z } from "zod";
118
+ import { defineAction } from "../.quickback/define-action";
119
+
120
+ export default defineAction({
121
+ description: "Post this invoice to accounts receivable",
122
+ input: z.object({}),
123
+ access: { roles: ["owner", "admin"], record: { status: { equals: "draft" } } },
124
+ sideEffects: "sync",
125
+ cms: {
126
+ label: "Post Invoice",
127
+ icon: "send",
128
+ confirm: "This will post the invoice to AR and create GL entries. Continue?",
129
+ category: "lifecycle",
130
+ successMessage: "Invoice posted successfully",
131
+ onSuccess: "refresh",
132
+ order: 1,
133
+ },
134
+ async execute({ db, record }) {
135
+ // ... post invoice
136
+ return { ok: true };
137
+ },
138
+ });
139
+ ```
140
+
141
+ ### Hiding API-only actions
142
+
143
+ ```typescript
144
+ // features/invoices/actions/internal-recalc.ts
145
+ import { z } from "zod";
146
+ import { defineAction } from "../.quickback/define-action";
147
+
148
+ export default defineAction({
149
+ description: "Recalculate internal totals",
150
+ input: z.object({}),
151
+ access: { roles: ["owner"] },
152
+ cms: { hidden: true }, // Never shown in CMS
153
+ async execute({ db, record }) {
154
+ // ... recalc totals
155
+ return { ok: true };
156
+ },
157
+ });
158
+ ```
159
+
160
+ ## Destructive Actions
161
+
162
+ Actions are styled as destructive when either:
163
+
164
+ - The action's `cms.destructive` is `true`
165
+ - The action is named `void` or `delete` (legacy fallback)
166
+
167
+ Destructive actions receive:
168
+
169
+ - **Red text** in the row action menu
170
+ - **Warning triangle icon** (unless overridden by `cms.icon`)
171
+ - **Red execute button** in the dialog (using `bg-destructive` styling)
172
+ - **Automatic confirmation step** (unless `cms.confirm` is explicitly `false`)
173
+
174
+ This provides a visual cue that the action has permanent consequences.
175
+
176
+ ## Standalone Actions
177
+
178
+ Actions with `path:` set are standalone — not tied to a specific record. They appear in a separate section and don't receive a `recordId` when executed. The CMS passes `null` as the record ID for standalone actions.
179
+
180
+ ## File Response Actions
181
+
182
+ Actions with `responseType: "file"` show a download icon instead of the lightning bolt. When executed, the response is treated as a file download rather than a JSON result.
183
+
184
+ ## Execution Flow
185
+
186
+ 1. User clicks action in row menu or action bar
187
+ 2. Dialog opens with description, inputs, and warnings
188
+ 3. If `cms.confirm` is set, user sees confirmation step first
189
+ 4. User fills in required fields
190
+ 5. User clicks "Execute" (or "Confirm" after confirmation step)
191
+ 6. CMS calls `client.executeAction(table, actionName, recordId, input)`
192
+ 7. On success: `cms.successMessage` shown as toast (if set), then `cms.onSuccess` behavior
193
+ 8. On error: error message displayed in dialog
194
+
195
+ ## Next Steps
196
+
197
+ - **[Security](/stack/cms/security)** — Access conditions and role-based access
198
+ - **[Table Views](/stack/cms/table-views)** — Where actions appear in the UI
199
+ - **[Schema Format Reference](/stack/cms/schema-format)** — ActionMeta type definition
@@ -0,0 +1,479 @@
1
+ # Components Reference
2
+
3
+ The CMS is built from composable React components organized by function. Every component reads metadata from the schema registry and adapts its behavior based on the current role.
4
+
5
+ ## Layout
6
+
7
+ ### Sidebar
8
+
9
+ The main navigation sidebar. Reads the schema registry to build a collapsible feature-grouped table list.
10
+
11
+ ```typescript
12
+ interface SidebarProps {
13
+ // No props — reads schema registry directly
14
+ }
15
+ ```
16
+
17
+ | Behavior | Description |
18
+ |----------|-------------|
19
+ | Feature grouping | Tables grouped by feature with collapsible sections |
20
+ | Feature icons | Each feature gets a contextual icon (e.g., Calculator for accounting) |
21
+ | Active state | Current table highlighted with primary color |
22
+ | Internal filter | Tables with `internal: true` are hidden |
23
+ | Footer stats | Shows total feature and table counts |
24
+
25
+ ### Header
26
+
27
+ Top bar with tagline and role switcher.
28
+
29
+ ```typescript
30
+ interface HeaderProps {
31
+ // No props — renders tagline and RoleSwitcher
32
+ }
33
+ ```
34
+
35
+ ### RoleSwitcher
36
+
37
+ Dropdown to switch between `owner`, `admin`, and `member` roles. Available in demo mode. In live mode, the role is read from the authenticated session.
38
+
39
+ ```typescript
40
+ // Uses RoleContext internally
41
+ // Provides: role, setRole, session
42
+ ```
43
+
44
+ ## Table
45
+
46
+ ### DataTable
47
+
48
+ Standard browse table with clickable rows and sortable columns.
49
+
50
+ ```typescript
51
+ interface DataTableProps {
52
+ data: Record[];
53
+ columns: ColumnDef[];
54
+ onRowClick?: (row: Record) => void;
55
+ }
56
+ ```
57
+
58
+ | Prop | Description |
59
+ |------|-------------|
60
+ | `data` | Array of records to display |
61
+ | `columns` | Column definitions (built by `ColumnFactory`) |
62
+ | `onRowClick` | Handler when a row is clicked (navigates to detail view) |
63
+
64
+ ### SpreadsheetTable
65
+
66
+ Excel/Google Sheets-like editable table with cell selection and keyboard navigation.
67
+
68
+ ```typescript
69
+ interface SpreadsheetTableProps {
70
+ data: Record[];
71
+ columns: ColumnDef[];
72
+ onCellEdit: (recordId: string, field: string, value: unknown) => Promise<void>;
73
+ editableFields: Set<string>;
74
+ onFKSearch: (targetTable: string, query: string) => Promise<FKOption[]>;
75
+ }
76
+ ```
77
+
78
+ | Prop | Description |
79
+ |------|-------------|
80
+ | `data` | Array of records to display |
81
+ | `columns` | Column definitions |
82
+ | `onCellEdit` | Called when a cell value is saved (auto-saves on blur/Enter) |
83
+ | `editableFields` | Set of field names that can be edited (from guards) |
84
+ | `onFKSearch` | Async function for FK typeahead search |
85
+
86
+ ### Toolbar
87
+
88
+ Search bar, view selector, view mode toggle, and refresh button.
89
+
90
+ ```typescript
91
+ interface ToolbarProps {
92
+ table: TableMeta;
93
+ search: string;
94
+ onSearchChange: (search: string) => void;
95
+ onRefresh: () => void;
96
+ selectedView?: string;
97
+ onViewChange: (view: string | undefined) => void;
98
+ viewMode: "table" | "dataTable";
99
+ onViewModeChange: (mode: "table" | "dataTable") => void;
100
+ }
101
+ ```
102
+
103
+ | Prop | Description |
104
+ |------|-------------|
105
+ | `table` | Table metadata (used to build view dropdown) |
106
+ | `search` | Current search query |
107
+ | `onSearchChange` | Handler for search input changes |
108
+ | `onRefresh` | Refreshes the table data |
109
+ | `selectedView` | Currently selected view name (undefined = all fields) |
110
+ | `onViewChange` | Handler for view selection changes |
111
+ | `viewMode` | Current view mode |
112
+ | `onViewModeChange` | Handler for toggling between Table and Data Table |
113
+
114
+ ### Pagination
115
+
116
+ Page navigation controls with range indicator.
117
+
118
+ ```typescript
119
+ interface PaginationProps {
120
+ page: number;
121
+ pageSize: number;
122
+ total: number;
123
+ onPageChange: (page: number) => void;
124
+ }
125
+ ```
126
+
127
+ | Prop | Description |
128
+ |------|-------------|
129
+ | `page` | Current page number (1-indexed) |
130
+ | `pageSize` | Records per page |
131
+ | `total` | Total record count |
132
+ | `onPageChange` | Handler for page changes |
133
+
134
+ ### RowActions
135
+
136
+ Three-dot dropdown menu on each table row with view, edit, delete, and custom actions.
137
+
138
+ ```typescript
139
+ interface RowActionsProps {
140
+ table: TableMeta;
141
+ record: Record;
142
+ onDelete?: (id: string) => void;
143
+ onAction?: (action: ActionMeta, record: Record) => void;
144
+ }
145
+ ```
146
+
147
+ | Prop | Description |
148
+ |------|-------------|
149
+ | `table` | Table metadata (used for CRUD access checks and action filtering) |
150
+ | `record` | The row's record data |
151
+ | `onDelete` | Handler for delete action |
152
+ | `onAction` | Handler for custom action selection |
153
+
154
+ ### ColumnFactory
155
+
156
+ Utility function (not a component) that builds column definitions from table metadata.
157
+
158
+ ```typescript
159
+ function buildColumns(
160
+ table: TableMeta,
161
+ role: Role,
162
+ options?: { viewFields?: string[] }
163
+ ): ColumnDef[];
164
+ ```
165
+
166
+ Generates columns with appropriate formatters for each field type: dates, money, booleans, enums, FK references, masked values, and plain text. Respects view field projections when provided.
167
+
168
+ ## Record
169
+
170
+ ### RecordDetail
171
+
172
+ Grouped field display for a single record. Auto-groups fields by category (Identity, Contact, Financial, References, Settings, Dates, Audit).
173
+
174
+ ```typescript
175
+ interface RecordDetailProps {
176
+ table: TableMeta;
177
+ record: Record;
178
+ role: Role;
179
+ }
180
+ ```
181
+
182
+ | Prop | Description |
183
+ |------|-------------|
184
+ | `table` | Table metadata (columns, masking, validation) |
185
+ | `record` | The record data to display |
186
+ | `role` | Current user role (affects masking) |
187
+
188
+ ### FieldDisplay
189
+
190
+ Renders a single field value with appropriate formatting: masking, booleans, enums, FK links, dates, money, percentages, and numbers.
191
+
192
+ ```typescript
193
+ interface FieldDisplayProps {
194
+ column: ColumnMeta;
195
+ value: unknown;
196
+ role: Role;
197
+ masking?: Record<string, MaskingRule>;
198
+ validation?: Record<string, ValidationRule>;
199
+ }
200
+ ```
201
+
202
+ | Prop | Description |
203
+ |------|-------------|
204
+ | `column` | Column metadata (type, mode, name) |
205
+ | `value` | The raw value to display |
206
+ | `role` | Current role (for masking checks) |
207
+ | `masking` | Masking rules for the table |
208
+ | `validation` | Validation rules (used for enum detection) |
209
+
210
+ ### ActionBar
211
+
212
+ Card displaying available actions as buttons for the current record.
213
+
214
+ ```typescript
215
+ interface ActionBarProps {
216
+ table: TableMeta;
217
+ record: Record;
218
+ onAction: (action: ActionMeta) => void;
219
+ }
220
+ ```
221
+
222
+ | Prop | Description |
223
+ |------|-------------|
224
+ | `table` | Table metadata |
225
+ | `record` | Current record (used for access condition evaluation) |
226
+ | `onAction` | Handler when an action button is clicked |
227
+
228
+ ### RelatedRecords
229
+
230
+ Card showing incoming FK relationships with record counts. Lists tables that reference the current record.
231
+
232
+ ```typescript
233
+ interface RelatedRecordsProps {
234
+ table: TableMeta;
235
+ recordId: string;
236
+ }
237
+ ```
238
+
239
+ | Prop | Description |
240
+ |------|-------------|
241
+ | `table` | Table metadata (used to discover incoming FK relationships) |
242
+ | `recordId` | Current record ID (used to count related records) |
243
+
244
+ ## Form
245
+
246
+ ### AutoForm
247
+
248
+ Auto-generated create/edit form built from the table's guard configuration.
249
+
250
+ ```typescript
251
+ interface AutoFormProps {
252
+ table: TableMeta;
253
+ mode: "create" | "edit";
254
+ initialData?: Record;
255
+ onSubmit: (data: Record) => Promise<void>;
256
+ onCancel: () => void;
257
+ }
258
+ ```
259
+
260
+ | Prop | Description |
261
+ |------|-------------|
262
+ | `table` | Table metadata (guards, columns, validation) |
263
+ | `mode` | `"create"` uses createable fields, `"edit"` uses updatable fields |
264
+ | `initialData` | Pre-filled values for edit mode |
265
+ | `onSubmit` | Handler for form submission |
266
+ | `onCancel` | Handler for cancel button |
267
+
268
+ Features:
269
+
270
+ - Fields determined from guards (createable for create, updatable for edit)
271
+ - Immutable fields shown as disabled with lock icon
272
+ - Protected fields shown as disabled with "Updated via actions only" note
273
+ - Client-side validation from schema rules
274
+ - Boolean fields grouped in a "Settings" section
275
+ - Required fields marked with red asterisk
276
+
277
+ ### FieldInput
278
+
279
+ Single form input that adapts to the column type and validation rules.
280
+
281
+ ```typescript
282
+ interface FieldInputProps {
283
+ column: ColumnMeta;
284
+ validation?: ValidationRule;
285
+ value: unknown;
286
+ onChange: (value: unknown) => void;
287
+ error?: string;
288
+ disabled?: boolean;
289
+ }
290
+ ```
291
+
292
+ | Prop | Description |
293
+ |------|-------------|
294
+ | `column` | Column metadata (determines input type) |
295
+ | `validation` | Validation rules (enum values, min/max, email) |
296
+ | `value` | Current field value |
297
+ | `onChange` | Handler for value changes |
298
+ | `error` | Error message to display |
299
+ | `disabled` | Whether the input is disabled |
300
+
301
+ Renders as: text input, number input, email input, URL input, date picker, select dropdown (for enums), textarea (for long text), or checkbox (for booleans).
302
+
303
+ ## Actions
304
+
305
+ ### ActionDialog
306
+
307
+ Modal dialog for executing a custom action with auto-generated input fields.
308
+
309
+ ```typescript
310
+ interface ActionDialogProps {
311
+ action: ActionMeta;
312
+ record: Record;
313
+ tableName: string;
314
+ onClose: () => void;
315
+ onExecute: (input: Record) => Promise<void>;
316
+ }
317
+ ```
318
+
319
+ | Prop | Description |
320
+ |------|-------------|
321
+ | `action` | Action metadata (name, description, inputFields, sideEffects) |
322
+ | `record` | The record the action applies to |
323
+ | `tableName` | Table name (for context) |
324
+ | `onClose` | Handler to close the dialog |
325
+ | `onExecute` | Handler to execute the action with form data |
326
+
327
+ Features:
328
+
329
+ - Auto-generates input fields from action schema
330
+ - Destructive actions get red styling and warning icon
331
+ - File response actions get download icon
332
+ - Side effects warning banner for `sideEffects: "sync"`
333
+ - Loading state during execution
334
+ - Error display on failure
335
+
336
+ ## Pages
337
+
338
+ ### PageRenderer
339
+
340
+ Top-level component that receives a `PageMeta` object and delegates to the appropriate layout component.
341
+
342
+ ```typescript
343
+ interface PageRendererProps {
344
+ page: PageMeta;
345
+ }
346
+ ```
347
+
348
+ Currently supports the `split-panel` layout type. Falls back to an error message for unknown layout types.
349
+
350
+ ### SplitPanelLayout
351
+
352
+ Renders a two-panel layout with drag-and-drop support (via `@dnd-kit/core`), matching engine integration, and page action dialogs.
353
+
354
+ ```typescript
355
+ interface SplitPanelLayoutProps {
356
+ page: PageMeta;
357
+ }
358
+ ```
359
+
360
+ | Behavior | Description |
361
+ |----------|-------------|
362
+ | Panel rendering | Renders left and right `DataPanel` components side by side |
363
+ | Drag-and-drop | Enables DnD between panels based on panel `features` |
364
+ | Match scoring | Computes match suggestions using `computeMatches()` and passes scores to panels |
365
+ | Action trigger | Opens `PageActionDialog` when a record is dragged from one panel to another |
366
+ | Refresh | Refreshes both panels after a successful action |
367
+
368
+ ### DataPanel
369
+
370
+ A single panel within a page layout. Fetches data from the API, displays rows with column headers, and supports search.
371
+
372
+ ```typescript
373
+ interface DataPanelProps {
374
+ panel: PagePanel;
375
+ dataSource: PageDataSource;
376
+ matchScores?: Map<string, number>;
377
+ onDataLoaded?: (records: Record_[]) => void;
378
+ refreshKey?: number;
379
+ }
380
+ ```
381
+
382
+ | Prop | Description |
383
+ |------|-------------|
384
+ | `panel` | Panel metadata (id, title, position, features) |
385
+ | `dataSource` | Data source config (table, filters, sort, display columns) |
386
+ | `matchScores` | Map of record ID to best match score (for confidence badges) |
387
+ | `onDataLoaded` | Callback when records are fetched (used by parent for match computation) |
388
+ | `refreshKey` | Incrementing key to trigger a re-fetch |
389
+
390
+ ### PanelRow
391
+
392
+ A single row within a `DataPanel`. Integrates with `@dnd-kit` for drag-source and drop-target behavior.
393
+
394
+ ```typescript
395
+ interface PanelRowProps {
396
+ record: Record_;
397
+ columns: string[];
398
+ panelId: string;
399
+ features?: string[];
400
+ matchScore?: number;
401
+ }
402
+ ```
403
+
404
+ | Prop | Description |
405
+ |------|-------------|
406
+ | `record` | The record data for this row |
407
+ | `columns` | Column names to display |
408
+ | `panelId` | Parent panel ID (used for DnD context) |
409
+ | `features` | Panel features (`"drag-source"`, `"drop-target"`) |
410
+ | `matchScore` | Match confidence score (renders `ConfidenceBadge` when present) |
411
+
412
+ ### PageActionDialog
413
+
414
+ Modal dialog triggered by drag-and-drop. Resolves input mappings from source and target records and executes a page action.
415
+
416
+ ```typescript
417
+ interface PageActionDialogProps {
418
+ pageAction: PageAction;
419
+ sourceRecord: Record_;
420
+ targetRecord: Record_;
421
+ sourceDataSource: string;
422
+ targetDataSource: string;
423
+ onClose: () => void;
424
+ onSuccess: () => void;
425
+ }
426
+ ```
427
+
428
+ | Prop | Description |
429
+ |------|-------------|
430
+ | `pageAction` | The page action definition (table, action, inputMapping, label, icon, confirm) |
431
+ | `sourceRecord` | The dragged record |
432
+ | `targetRecord` | The drop-target record |
433
+ | `sourceDataSource` | Data source name for the source record |
434
+ | `targetDataSource` | Data source name for the target record |
435
+ | `onClose` | Close handler |
436
+ | `onSuccess` | Called after successful action execution (triggers panel refresh) |
437
+
438
+ ### ConfidenceBadge
439
+
440
+ Displays a match confidence score as a colored percentage badge.
441
+
442
+ ```typescript
443
+ interface ConfidenceBadgeProps {
444
+ score: number; // 0-1
445
+ }
446
+ ```
447
+
448
+ | Score Range | Color |
449
+ |-------------|-------|
450
+ | 80%+ | Green |
451
+ | 50-79% | Yellow |
452
+ | Below 50% | Orange |
453
+
454
+ ### computeMatches (utility)
455
+
456
+ Not a component — a utility function that runs the matching engine. Compares left and right record arrays using the page's matching rules and returns sorted match suggestions.
457
+
458
+ ```typescript
459
+ function computeMatches(
460
+ leftRecords: Record_[],
461
+ rightRecords: Record_[],
462
+ page: PageMeta
463
+ ): MatchSuggestion[];
464
+
465
+ interface MatchSuggestion {
466
+ leftId: string;
467
+ rightId: string;
468
+ score: number;
469
+ ruleScores: { rule: string; score: number }[];
470
+ }
471
+ ```
472
+
473
+ Returns an array of suggestions sorted by score (highest first). Only includes matches above the page's `confidenceThreshold`.
474
+
475
+ ## Next Steps
476
+
477
+ - **[Schema Format Reference](/stack/cms/schema-format)** — TypeScript types consumed by these components
478
+ - **[Table Views](/stack/cms/table-views)** — How DataTable and SpreadsheetTable are used
479
+ - **[Inline Editing](/stack/cms/inline-editing)** — SpreadsheetTable editing details