@quickback-dev/cli 0.10.16 → 0.11.0

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 (253) 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.d.ts.map +1 -1
  5. package/dist/docs/content.js +15 -10
  6. package/dist/docs/content.js.map +1 -1
  7. package/dist/index.js +1 -1
  8. package/dist/index.js.map +1 -1
  9. package/dist/skill/SKILL.md +142 -1051
  10. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  11. package/dist/skill/docs/changelog.md +1225 -0
  12. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  17. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  18. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  19. package/dist/skill/docs/compiler/config/agents.md +144 -0
  20. package/dist/skill/docs/compiler/config/auth.md +109 -0
  21. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  22. package/dist/skill/docs/compiler/config/domains.md +149 -0
  23. package/dist/skill/docs/compiler/config/index.md +419 -0
  24. package/dist/skill/docs/compiler/config/output.md +338 -0
  25. package/dist/skill/docs/compiler/config/providers.md +248 -0
  26. package/dist/skill/docs/compiler/config/security.md +255 -0
  27. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  28. package/dist/skill/docs/compiler/config/variables.md +157 -0
  29. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  30. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  31. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  32. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  33. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  34. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  36. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  37. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  38. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  39. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  40. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  41. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  42. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  43. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  44. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  45. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  46. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  47. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  48. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  49. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  50. package/dist/skill/docs/compiler/index.md +85 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  64. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  65. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  66. package/dist/skill/docs/compiler/targets/index.md +47 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  69. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  70. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  71. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  72. package/dist/skill/docs/index.md +77 -0
  73. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  74. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  75. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  76. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  77. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  78. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  79. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  80. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  81. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  82. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  83. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  84. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  85. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  86. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  87. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  88. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  89. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  90. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  91. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  92. package/dist/skill/docs/stack/auth/index.md +64 -0
  93. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  94. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  95. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  96. package/dist/skill/docs/stack/auth/plugins/index.md +340 -0
  97. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  98. package/dist/skill/docs/stack/auth/security.md +455 -0
  99. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  100. package/dist/skill/docs/stack/cms/actions.md +199 -0
  101. package/dist/skill/docs/stack/cms/components.md +479 -0
  102. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  103. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  104. package/dist/skill/docs/stack/cms/index.md +158 -0
  105. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  106. package/dist/skill/docs/stack/cms/pages.md +275 -0
  107. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  108. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  109. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  110. package/dist/skill/docs/stack/cms/security.md +203 -0
  111. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  112. package/dist/skill/docs/stack/index.md +65 -0
  113. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  114. package/dist/skill/docs/stack/queues/index.md +56 -0
  115. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  116. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  117. package/dist/skill/docs/stack/realtime/index.md +73 -0
  118. package/dist/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  119. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  120. package/dist/skill/docs/stack/storage/index.md +17 -0
  121. package/dist/skill/docs/stack/storage/kv.md +204 -0
  122. package/dist/skill/docs/stack/storage/r2.md +232 -0
  123. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  124. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  125. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  126. package/dist/skill/docs/stack/vector/index.md +44 -0
  127. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  128. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  129. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  130. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  131. package/package.json +1 -1
  132. package/src/skill/SKILL.md +142 -1051
  133. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  134. package/src/skill/docs/changelog.md +1225 -0
  135. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  136. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  137. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  138. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  139. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  140. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  141. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  142. package/src/skill/docs/compiler/config/agents.md +144 -0
  143. package/src/skill/docs/compiler/config/auth.md +109 -0
  144. package/src/skill/docs/compiler/config/bindings.md +176 -0
  145. package/src/skill/docs/compiler/config/domains.md +149 -0
  146. package/src/skill/docs/compiler/config/index.md +419 -0
  147. package/src/skill/docs/compiler/config/output.md +338 -0
  148. package/src/skill/docs/compiler/config/providers.md +248 -0
  149. package/src/skill/docs/compiler/config/security.md +255 -0
  150. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  151. package/src/skill/docs/compiler/config/variables.md +157 -0
  152. package/src/skill/docs/compiler/definitions/access.md +445 -0
  153. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  154. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  155. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  156. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  157. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  158. package/src/skill/docs/compiler/definitions/index.md +219 -0
  159. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  160. package/src/skill/docs/compiler/definitions/read.md +220 -0
  161. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  162. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  163. package/src/skill/docs/compiler/definitions/views.md +292 -0
  164. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  165. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  166. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  167. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  168. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  169. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  170. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  171. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  172. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  173. package/src/skill/docs/compiler/index.md +85 -0
  174. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  176. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  177. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  178. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  179. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  186. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  187. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  188. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  189. package/src/skill/docs/compiler/targets/index.md +47 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  191. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  192. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  193. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  194. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  195. package/src/skill/docs/index.md +77 -0
  196. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  197. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  198. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  199. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  200. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  201. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  202. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  203. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  204. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  205. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  206. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  207. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  208. package/src/skill/docs/stack/account-ui/index.md +147 -0
  209. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  210. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  211. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  212. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  213. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  214. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  215. package/src/skill/docs/stack/auth/index.md +64 -0
  216. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  217. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  218. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  219. package/src/skill/docs/stack/auth/plugins/index.md +340 -0
  220. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  221. package/src/skill/docs/stack/auth/security.md +455 -0
  222. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  223. package/src/skill/docs/stack/cms/actions.md +199 -0
  224. package/src/skill/docs/stack/cms/components.md +479 -0
  225. package/src/skill/docs/stack/cms/connecting.md +199 -0
  226. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  227. package/src/skill/docs/stack/cms/index.md +158 -0
  228. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  229. package/src/skill/docs/stack/cms/pages.md +275 -0
  230. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  231. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  232. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  233. package/src/skill/docs/stack/cms/security.md +203 -0
  234. package/src/skill/docs/stack/cms/table-views.md +142 -0
  235. package/src/skill/docs/stack/index.md +65 -0
  236. package/src/skill/docs/stack/queues/handlers.md +317 -0
  237. package/src/skill/docs/stack/queues/index.md +56 -0
  238. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  239. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  240. package/src/skill/docs/stack/realtime/index.md +73 -0
  241. package/src/skill/docs/stack/realtime/partyserver-rooms.md +146 -0
  242. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  243. package/src/skill/docs/stack/storage/index.md +17 -0
  244. package/src/skill/docs/stack/storage/kv.md +204 -0
  245. package/src/skill/docs/stack/storage/r2.md +232 -0
  246. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  247. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  248. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  249. package/src/skill/docs/stack/vector/index.md +44 -0
  250. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  251. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  252. package/src/skill/docs/stack/webhooks/index.md +36 -0
  253. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -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
@@ -0,0 +1,199 @@
1
+ # Connecting
2
+
3
+ The CMS supports two modes: **demo mode** for development and testing, and **live mode** for connecting to a real Quickback API.
4
+
5
+ ## Demo Mode
6
+
7
+ When no `VITE_QUICKBACK_API_URL` is set, the CMS runs in demo mode:
8
+
9
+ - Uses a **mock API client** backed by `localStorage`
10
+ - Loads seed data from JSON files in `data/mock/`
11
+ - Provides a **role switcher** in the header to test owner/admin/member access
12
+ - Simulates authentication sessions without a real backend
13
+
14
+ Demo mode is useful for prototyping your schema, testing guard behavior across roles, and verifying masking rules before deploying.
15
+
16
+ ```bash title=".env.development"
17
+ # No VITE_QUICKBACK_API_URL — CMS runs in demo mode
18
+ ```
19
+
20
+ ### Mock Data
21
+
22
+ Place JSON files in `data/mock/` matching your table names:
23
+
24
+ ```
25
+ data/mock/
26
+ contact.json # Array of contact records
27
+ project.json # Array of project records
28
+ invoice.json # Array of invoice records
29
+ _meta.json # Mock session and org metadata
30
+ ```
31
+
32
+ Each file contains an array of records. The mock client loads them on startup and persists changes to `localStorage`.
33
+
34
+ ### Role Switcher
35
+
36
+ In demo mode, the header displays a role switcher dropdown allowing you to switch between `owner`, `admin`, and `member` roles in real time. This lets you verify:
37
+
38
+ - Which CRUD buttons appear per role
39
+ - Which form fields are editable
40
+ - Which masking rules apply
41
+ - Which actions are available
42
+ - Which views are accessible
43
+
44
+ ## Live Mode
45
+
46
+ Set `VITE_QUICKBACK_API_URL` to connect to a real Quickback API:
47
+
48
+ ```bash title=".env.production"
49
+ VITE_QUICKBACK_API_URL=https://api.example.com
50
+ ```
51
+
52
+ In live mode, the CMS:
53
+
54
+ - Reads the **Better Auth session** from cookies
55
+ - Fetches the user's **organization membership** and role
56
+ - Makes real API calls to the Quickback backend for all CRUD operations
57
+ - Applies server-side security (firewall, guards, masking) in addition to client-side UI filtering
58
+
59
+ ## API Client Interface
60
+
61
+ The CMS communicates with the backend through a standard interface:
62
+
63
+ ```typescript
64
+ interface IApiClient {
65
+ list(table: string, params?: ListParams): Promise<ListResult>;
66
+ get(table: string, id: string): Promise<Record | null>;
67
+ create(table: string, data: Record): Promise<Record>;
68
+ update(table: string, id: string, data: Partial<Record>): Promise<Record>;
69
+ delete(table: string, id: string): Promise<void>;
70
+ executeAction(
71
+ table: string,
72
+ actionName: string,
73
+ recordId: string | null,
74
+ input: Record
75
+ ): Promise<Record>;
76
+ listView(
77
+ table: string,
78
+ viewName: string,
79
+ params?: ListParams
80
+ ): Promise<ListResult>;
81
+ }
82
+ ```
83
+
84
+ ### List Parameters
85
+
86
+ ```typescript
87
+ interface ListParams {
88
+ page?: number;
89
+ pageSize?: number;
90
+ sort?: string;
91
+ order?: "asc" | "desc";
92
+ search?: string;
93
+ filters?: Record<string, unknown>;
94
+ }
95
+ ```
96
+
97
+ ### List Result
98
+
99
+ ```typescript
100
+ interface ListResult {
101
+ data: Record[];
102
+ total: number;
103
+ page: number;
104
+ pageSize: number;
105
+ }
106
+ ```
107
+
108
+ Both the mock client and the live client implement this same interface. The CMS code is identical in both modes — only the underlying transport changes.
109
+
110
+ > **Server-Side Security**
111
+ >
112
+ > In live mode, all four Quickback security layers (firewall, CRUD access, guards, masking) are enforced server-side. The CMS hides unauthorized UI elements as a convenience, but the API rejects unauthorized requests regardless.
113
+
114
+
115
+ ## How the Client is Created
116
+
117
+ The CMS auto-creates the API client based on configuration:
118
+
119
+ 1. **No `VITE_QUICKBACK_API_URL`** — Instantiates the mock client, loads seed data from `data/mock/`, and uses `localStorage` for persistence.
120
+ 2. **`VITE_QUICKBACK_API_URL` is set** — Instantiates the live client, reads the auth session cookie, and makes fetch requests to the Quickback API using the standard REST endpoints (`/api/v1/{table}`).
121
+
122
+ The client is provided via React context (`ApiClientContext`) and available throughout the component tree.
123
+
124
+ ## Embedded Mode (Recommended)
125
+
126
+ Set `cms: true` in your config to embed the CMS directly in your compiled Worker:
127
+
128
+ ```typescript title="quickback/quickback.config.ts"
129
+ export default defineConfig({
130
+ name: "my-app",
131
+ cms: true,
132
+ // ...providers
133
+ });
134
+ ```
135
+
136
+ When you run `quickback compile`, the CLI:
137
+ 1. Builds the CMS SPA from source and places assets in `src/apps/cms/`
138
+ 2. Adds `[assets]` config to `wrangler.toml` with `run_worker_first = true`
139
+ 3. Generates Worker routing to serve the CMS SPA
140
+
141
+ Run `wrangler dev` and the CMS is served at `/cms/`. API routes (`/api/*`, `/auth/*`, etc.) pass through to your Hono app. Same origin — no CORS, auth cookies work naturally. On a custom domain, the CMS is served at root (`/`).
142
+
143
+ ### Custom CMS Domain
144
+
145
+ Optionally serve the CMS on a separate subdomain:
146
+
147
+ ```typescript
148
+ cms: { domain: "cms.example.com" }
149
+ ```
150
+
151
+ This adds a custom domain route to `wrangler.toml`. Both `api.example.com` and `cms.example.com` point to the same Worker. The compiler auto-configures hostname-based routing and cross-subdomain cookies.
152
+
153
+ CMS access defaults to `access: "admin"` — only `user.role === "admin"` (the Better Auth platform-admin tier) can reach `/cms/*`. Non-admin authenticated users are redirected to `/account/profile`. The gate is enforced at multiple layers:
154
+
155
+ - **Account UI** hides the "Go to CMS" button for non-admins.
156
+ - **CMS SPA shell** — the Worker returns `403` (or redirects unauthenticated requests to login) before serving `index.html` to a non-admin. A non-admin who types the CMS URL directly cannot load the app.
157
+ - **`/api/v1/schema`** returns `403 Admin access required` to non-admin callers, so schema metadata can't be scraped by hitting the API directly.
158
+ - **`custom_view` CRUD** is gated on `userRole: ["admin"]` rather than org membership, so saved views can't be listed or modified without admin rights.
159
+ - **In-SPA gate** — if any earlier layer is bypassed, the SPA still redirects the user to `/account/profile`.
160
+
161
+ Your resource CRUD endpoints (the ones generated for your features) are unaffected — they continue to use the per-resource `crud.access.roles` you defined.
162
+
163
+ To allow any authenticated user to access the CMS, opt out explicitly:
164
+
165
+ ```typescript
166
+ cms: { access: "user" }
167
+ ```
168
+
169
+ See [Multi-Domain Architecture](/compiler/config/domains) for details on multi-domain routing.
170
+
171
+ ## Multi-Tenant vs Single-Tenant
172
+
173
+ The CMS supports two authentication modes depending on your project's organization configuration.
174
+
175
+ ### Multi-Tenant (Default)
176
+
177
+ In multi-tenant mode, the CMS gates access behind organization membership:
178
+
179
+ 1. User logs in via Better Auth session
180
+ 2. CMS fetches the user's organization memberships
181
+ 3. If the user belongs to multiple organizations, an **org selector** is displayed
182
+ 4. Once an org is selected, the user's role within that org determines their CMS permissions
183
+
184
+ This is the default behavior for all Quickback projects.
185
+
186
+ ### Single-Tenant Mode
187
+
188
+ When your project disables organizations (`features.organizations: false` in config), the compiler sets `singleTenant: true` in the schema registry. In this mode:
189
+
190
+ - No org gate or org selector is shown
191
+ - The user's role is read directly from `user.role` on the session
192
+ - All data is unscoped (no `organizationId` filtering)
193
+
194
+ Single-tenant mode is useful for internal tools, personal projects, or apps that don't need multi-org isolation.
195
+
196
+ ## Next Steps
197
+
198
+ - **[Table Views](/stack/cms/table-views)** — Browse and Data Table view modes
199
+ - **[Security](/stack/cms/security)** — How roles, guards, and masking work in the CMS
@@ -0,0 +1,39 @@
1
+ # Dashboard
2
+
3
+ The CMS dashboard is the home page you see when opening the admin interface. It provides an at-a-glance overview of your entire schema and quick navigation to any table.
4
+
5
+ ## Stats Grid
6
+
7
+ The top of the dashboard displays aggregate statistics across your entire schema:
8
+
9
+ | Stat | Description |
10
+ |------|-------------|
11
+ | **Tables** | Total non-internal tables (excludes join tables and system tables) |
12
+ | **Columns** | Total columns across all tables |
13
+ | **Actions** | Total custom actions across all tables |
14
+ | **Views** | Total named views across all tables |
15
+ | **Masked Fields** | Total fields with masking rules |
16
+
17
+ ## Feature Cards
18
+
19
+ Below the stats grid, the dashboard displays a card for each feature group. Each card lists the feature's tables with metadata:
20
+
21
+ - **Column count** — number of columns in the table
22
+ - **Action count** — number of custom actions (shown with a lightning icon)
23
+ - **View count** — number of named views (shown with an eye icon)
24
+ - **Mask count** — number of masked fields (shown with a shield icon)
25
+
26
+ Clicking a table name navigates directly to that table's browse view.
27
+
28
+ ## Role Context
29
+
30
+ The dashboard shows the current user's role. In demo mode, this reflects the role selected in the role switcher. In live mode, it shows the role from the authenticated session.
31
+
32
+ ## Internal Tables
33
+
34
+ Tables marked as `internal: true` in the schema registry (those without a `defineTable()` resource config) are excluded from the dashboard. These are typically join tables or system tables that don't need direct admin access.
35
+
36
+ ## Next Steps
37
+
38
+ - **[Table Views](/stack/cms/table-views)** — Browse and Data Table view modes
39
+ - **[Custom Pages](/stack/cms/pages)** — Multi-panel pages with matching and drag-drop