@crombolo/extension 0.60.0 → 0.61.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@crombolo/extension",
3
- "version": "0.60.0",
3
+ "version": "0.61.0",
4
4
  "description": "What an extension's server half is written against: route, the host's capabilities and its own tables. It runs in a Deno process of its own, apart from the CMS.",
5
5
  "license": "MIT",
6
6
  "author": "Crombolo",
@@ -25,17 +25,18 @@
25
25
  "exports": {
26
26
  ".": "./src/index.ts",
27
27
  "./channel": "./src/channel.ts",
28
- "./runner": "./src/runner.ts"
28
+ "./runner": "./src/runner.ts",
29
+ "./screens": "./src/screens.ts"
29
30
  },
30
31
  "files": [
31
32
  "src",
32
33
  "NOTICE"
33
34
  ],
34
35
  "dependencies": {
35
- "@crombolo/common": "0.60.0",
36
- "@crombolo/core": "0.60.0",
37
- "@crombolo/data": "0.60.0",
38
- "@crombolo/render": "0.60.0",
36
+ "@crombolo/common": "0.61.0",
37
+ "@crombolo/core": "0.61.0",
38
+ "@crombolo/data": "0.61.0",
39
+ "@crombolo/render": "0.61.0",
39
40
  "kysely": "0.29.6"
40
41
  },
41
42
  "publishConfig": {
package/src/channel.ts CHANGED
@@ -123,7 +123,9 @@ export async function encode(
123
123
  if (typeof (value as { then?: unknown }).then === 'function')
124
124
  return encode(await (value as PromiseLike<unknown>), hooks, key, seen)
125
125
  if (seen.has(value)) return undefined
126
- seen.add(value)
126
+ // Its own ancestors only: an array's items are encoded at once, so siblings that share
127
+ // an object must not see each other's, or the second loses it as if it were a cycle.
128
+ seen = new Set(seen).add(value)
127
129
  try {
128
130
  if (value instanceof Date) return { $date: value.toISOString() }
129
131
  if (value instanceof URL) return { $url: value.href }
package/src/index.ts CHANGED
@@ -12,6 +12,7 @@ import { sectionKey } from '@crombolo/core/sections'
12
12
  import type { BundleStep, BundleTables, ShapeOf } from './types.ts'
13
13
 
14
14
  export * from '@crombolo/common'
15
+ export * from './screens.ts'
15
16
  export type * from './types.ts'
16
17
 
17
18
  /** Declares the extension's own tables, built when the CMS starts it. */
package/src/runner.ts CHANGED
@@ -71,6 +71,8 @@ export interface ExtensionDescription {
71
71
  middleware: boolean
72
72
  /** Its components (story 312), each with the layout alias it suggests. */
73
73
  components: { name: string; layout?: string }[]
74
+ /** Its screens (story 323), each with the actions its buttons may name. */
75
+ screens: { id: string; actions: string[] }[]
74
76
  }
75
77
 
76
78
  /** A component as the factory declares it: its render function, or its module. */
@@ -134,6 +136,14 @@ function describe(bundle: Bundle): ExtensionDescription {
134
136
  ? { layout: component.layout }
135
137
  : {}),
136
138
  })),
139
+ screens: Object.entries((bundle.screens ?? {}) as Record<string, Bundle>)
140
+ .filter(([, screen]) => typeof screen?.view === 'function')
141
+ .map(([id, screen]) => ({
142
+ id,
143
+ actions: Object.entries(screen.actions ?? {})
144
+ .filter(([, action]) => typeof action === 'function')
145
+ .map(([name]) => name),
146
+ })),
137
147
  }
138
148
  }
139
149
 
@@ -394,6 +404,18 @@ export async function run(module: Record<string, unknown>, exportName: string):
394
404
  })
395
405
  return renderToString(render(context) as Child)
396
406
  }
407
+ case 'screen': {
408
+ const screen = Object.hasOwn(bundle.screens ?? {}, frame.screen as string)
409
+ ? bundle.screens[frame.screen as string]
410
+ : undefined
411
+ const handler = frame.action
412
+ ? Object.hasOwn(screen?.actions ?? {}, frame.action as string)
413
+ ? screen.actions[frame.action as string]
414
+ : undefined
415
+ : screen?.view
416
+ if (typeof handler !== 'function') throw new Error('No such screen or action.')
417
+ return handler(context)
418
+ }
397
419
  case 'backfill': {
398
420
  const step = bundle.tables?.steps.find(
399
421
  (candidate: { name: string }) => candidate.name === frame.name,
@@ -462,7 +484,13 @@ export async function run(module: Record<string, unknown>, exportName: string):
462
484
  const waiter = pending.get(frame.id as number)
463
485
  pending.delete(frame.id as number)
464
486
  if (!waiter) break
465
- if (frame.error) waiter.reject(errorFrom(frame.error as { name: string; message: string }))
487
+ // An error the host threw arrives encoded, so a refusal keeps its message and its name.
488
+ if (frame.error)
489
+ waiter.reject(
490
+ '$error' in (frame.error as object) || '$outcome' in (frame.error as object)
491
+ ? (decode(frame.error) as Error)
492
+ : errorFrom(frame.error as { name: string; message: string }),
493
+ )
466
494
  else waiter.resolve(frame.value)
467
495
  break
468
496
  }
package/src/screens.ts ADDED
@@ -0,0 +1,275 @@
1
+ /**
2
+ * A screen an extension describes and the back office draws (story 323): data
3
+ * only, from a small catalogue, so no markup or script of the extension's
4
+ * reaches the page. docs/extensions.md, "Screens".
5
+ */
6
+
7
+ /** A value a form holds, or a plain object an action is sent. */
8
+ export type ScreenValue =
9
+ | string
10
+ | number
11
+ | boolean
12
+ | null
13
+ | readonly string[]
14
+ /** A list field's rows. */
15
+ | readonly Readonly<Record<string, string | number | boolean | null>>[]
16
+
17
+ export type ScreenValues = Readonly<Record<string, ScreenValue>>
18
+
19
+ /** When a field shows, or a hint applies, from the form's current values. */
20
+ export interface Condition {
21
+ field: string
22
+ equals?: ScreenValue
23
+ oneOf?: readonly ScreenValue[]
24
+ notEmpty?: boolean
25
+ }
26
+
27
+ export type ButtonLook = 'primary' | 'secondary' | 'danger'
28
+
29
+ export interface Button {
30
+ type: 'button'
31
+ label: string
32
+ /** The action of the screen it calls. */
33
+ action: string
34
+ /** Sent with the action, such as a row's key. */
35
+ input?: Readonly<Record<string, ScreenValue>>
36
+ look?: ButtonLook
37
+ /** Asked in the back office's own dialog before the action is called. */
38
+ confirm?: string
39
+ /** Sends the enclosing form's values with the action, once they pass its rules. */
40
+ submit?: boolean
41
+ disabled?: boolean
42
+ }
43
+
44
+ /** A search box in the toolbar: its text is sent as `input.query`. */
45
+ export interface Search {
46
+ type: 'search'
47
+ action: string
48
+ placeholder?: string
49
+ value?: string
50
+ }
51
+
52
+ export type Cell =
53
+ | { type: 'text'; text: string }
54
+ | { type: 'code'; text: string }
55
+ | {
56
+ type: 'tag'
57
+ text: string
58
+ look?: 'default' | 'primary' | 'secondary' | 'positive' | 'danger'
59
+ }
60
+ | { type: 'link'; text: string; href: string }
61
+ | { type: 'date'; value: string }
62
+
63
+ export interface Row {
64
+ key: string
65
+ cells: readonly Cell[]
66
+ actions?: readonly Button[]
67
+ }
68
+
69
+ export interface Table {
70
+ type: 'table'
71
+ columns: readonly string[]
72
+ rows: readonly Row[]
73
+ }
74
+
75
+ interface FieldBase {
76
+ name: string
77
+ label: string
78
+ hint?: string
79
+ hints?: readonly { when: Condition; text: string }[]
80
+ visibleWhen?: Condition
81
+ required?: boolean
82
+ placeholder?: string
83
+ /** Drawn disabled and never sent back: the site's code sets it, or the person may not change it. */
84
+ readOnly?: boolean
85
+ }
86
+
87
+ export type Field =
88
+ | (FieldBase & {
89
+ kind: 'text'
90
+ multiline?: boolean
91
+ pattern?: string
92
+ minLength?: number
93
+ maxLength?: number
94
+ })
95
+ | (FieldBase & { kind: 'number'; min?: number; max?: number; step?: number })
96
+ | (FieldBase & { kind: 'boolean' })
97
+ | (FieldBase & { kind: 'choice'; options: readonly { value: string; label: string }[] })
98
+ | (FieldBase & { kind: 'page' })
99
+ | (FieldBase & { kind: 'media' })
100
+ | (FieldBase & { kind: 'member' })
101
+ /** Never sent back filled: the field starts empty, and is sent only when typed. */
102
+ | (FieldBase & { kind: 'secret' })
103
+ /**
104
+ * Rows of sub-fields, added and removed in the browser and sent as an array
105
+ * of objects (story 329). A sub-field is any kind but a list, a picker or a secret.
106
+ */
107
+ | (FieldBase & {
108
+ kind: 'list'
109
+ fields: readonly ListSubField[]
110
+ addLabel?: string
111
+ min?: number
112
+ max?: number
113
+ })
114
+
115
+ /** What a list's rows may hold. */
116
+ export type ListSubField = Extract<Field, { kind: 'text' | 'number' | 'boolean' | 'choice' }>
117
+
118
+ export interface Form {
119
+ type: 'form'
120
+ title?: string
121
+ fields: readonly Field[]
122
+ values: ScreenValues
123
+ actions: readonly Button[]
124
+ }
125
+
126
+ export interface Notice {
127
+ type: 'notice'
128
+ text: string
129
+ }
130
+
131
+ export interface Problem {
132
+ type: 'problem'
133
+ text: string
134
+ }
135
+
136
+ export interface Empty {
137
+ type: 'empty'
138
+ title: string
139
+ text?: string
140
+ actions?: readonly Button[]
141
+ }
142
+
143
+ export interface Progress {
144
+ type: 'progress'
145
+ label?: string
146
+ /** 0 to 100; without one the bar is indeterminate. */
147
+ value?: number
148
+ }
149
+
150
+ export interface Tab {
151
+ id: string
152
+ label: string
153
+ /** No tabs inside a tab. */
154
+ body: readonly Exclude<Node, Tabs>[]
155
+ }
156
+
157
+ export interface Tabs {
158
+ type: 'tabs'
159
+ tabs: readonly Tab[]
160
+ }
161
+
162
+ export type Node = Table | Form | Button | Notice | Problem | Empty | Tabs | Progress
163
+
164
+ export interface Screen {
165
+ type: 'screen'
166
+ title: string
167
+ toolbar?: readonly (Button | Search)[]
168
+ body: readonly Node[]
169
+ }
170
+
171
+ /** What a screen's view or action answers: the screen, the state to keep, a notice. */
172
+ export interface ScreenResult<State = Record<string, unknown>> {
173
+ screen: Screen
174
+ state?: State
175
+ notice?: string
176
+ }
177
+
178
+ /** A view or an action may answer the screen alone. */
179
+ export type ScreenAnswer<State = Record<string, unknown>> = Screen | ScreenResult<State>
180
+
181
+ export const screen = (
182
+ title: string,
183
+ body: readonly Node[],
184
+ options: { toolbar?: readonly (Button | Search)[] } = {},
185
+ ): Screen => ({ type: 'screen', title, body, ...options })
186
+
187
+ export const table = (columns: readonly string[], rows: readonly Row[]): Table => ({
188
+ type: 'table',
189
+ columns,
190
+ rows,
191
+ })
192
+
193
+ export const row = (key: string, cells: readonly Cell[], actions?: readonly Button[]): Row => ({
194
+ key,
195
+ cells,
196
+ ...(actions ? { actions } : {}),
197
+ })
198
+
199
+ export const cell = {
200
+ text: (text: string): Cell => ({ type: 'text', text }),
201
+ code: (text: string): Cell => ({ type: 'code', text }),
202
+ tag: (text: string, look?: Extract<Cell, { type: 'tag' }>['look']): Cell => ({
203
+ type: 'tag',
204
+ text,
205
+ ...(look ? { look } : {}),
206
+ }),
207
+ link: (text: string, href: string): Cell => ({ type: 'link', text, href }),
208
+ date: (value: string | Date): Cell => ({
209
+ type: 'date',
210
+ value: value instanceof Date ? value.toISOString() : value,
211
+ }),
212
+ }
213
+
214
+ type FieldOf<K extends Field['kind']> = Extract<Field, { kind: K }>
215
+ type FieldOptions<K extends Field['kind']> = Omit<FieldOf<K>, 'kind' | 'name' | 'label'>
216
+
217
+ const fieldOf =
218
+ <K extends Field['kind']>(kind: K) =>
219
+ (name: string, label: string, options: FieldOptions<K> = {} as FieldOptions<K>): FieldOf<K> =>
220
+ ({ kind, name, label, ...options }) as FieldOf<K>
221
+
222
+ export const field = {
223
+ text: fieldOf('text'),
224
+ number: fieldOf('number'),
225
+ boolean: fieldOf('boolean'),
226
+ choice: (
227
+ name: string,
228
+ label: string,
229
+ options: FieldOf<'choice'>['options'],
230
+ rest: Omit<FieldOptions<'choice'>, 'options'> = {},
231
+ ): FieldOf<'choice'> => ({ kind: 'choice', name, label, options, ...rest }),
232
+ page: fieldOf('page'),
233
+ media: fieldOf('media'),
234
+ member: fieldOf('member'),
235
+ secret: fieldOf('secret'),
236
+ list: (
237
+ name: string,
238
+ label: string,
239
+ fields: readonly ListSubField[],
240
+ rest: Omit<FieldOptions<'list'>, 'fields'> = {},
241
+ ): FieldOf<'list'> => ({ kind: 'list', name, label, fields, ...rest }),
242
+ }
243
+
244
+ export const form = (
245
+ fields: readonly Field[],
246
+ values: ScreenValues,
247
+ actions: readonly Button[],
248
+ options: { title?: string } = {},
249
+ ): Form => ({ type: 'form', fields, values, actions, ...options })
250
+
251
+ export const button = (
252
+ label: string,
253
+ action: string,
254
+ options: Omit<Button, 'type' | 'label' | 'action'> = {},
255
+ ): Button => ({ type: 'button', label, action, ...options })
256
+
257
+ export const search = (action: string, options: Omit<Search, 'type' | 'action'> = {}): Search => ({
258
+ type: 'search',
259
+ action,
260
+ ...options,
261
+ })
262
+
263
+ export const notice = (text: string): Notice => ({ type: 'notice', text })
264
+ export const problem = (text: string): Problem => ({ type: 'problem', text })
265
+ export const empty = (title: string, options: Omit<Empty, 'type' | 'title'> = {}): Empty => ({
266
+ type: 'empty',
267
+ title,
268
+ ...options,
269
+ })
270
+ export const progress = (options: Omit<Progress, 'type'> = {}): Progress => ({
271
+ type: 'progress',
272
+ ...options,
273
+ })
274
+ export const tab = (id: string, label: string, body: Tab['body']): Tab => ({ id, label, body })
275
+ export const tabs = (list: readonly Tab[]): Tabs => ({ type: 'tabs', tabs: list })
package/src/types.ts CHANGED
@@ -26,6 +26,9 @@ export type {
26
26
  BundleRedirects,
27
27
  BundleRoute,
28
28
  BundleRouteContext,
29
+ BundleScreen,
30
+ BundleScreenContext,
31
+ BundleScreenHandler,
29
32
  BundleSection,
30
33
  BundleStep,
31
34
  BundleTables,