@asteby/metacore-runtime-react 53.4.1 → 53.6.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 (68) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +73 -0
  3. package/dist/index.d.ts +2 -0
  4. package/dist/index.d.ts.map +1 -1
  5. package/dist/index.js +4 -0
  6. package/dist/setup/addon-config-surface.d.ts +119 -0
  7. package/dist/setup/addon-config-surface.d.ts.map +1 -0
  8. package/dist/setup/addon-config-surface.js +662 -0
  9. package/dist/setup/connector-blocks-model.d.ts +79 -0
  10. package/dist/setup/connector-blocks-model.d.ts.map +1 -0
  11. package/dist/setup/connector-blocks-model.js +96 -0
  12. package/dist/setup/connector-blocks.d.ts +48 -0
  13. package/dist/setup/connector-blocks.d.ts.map +1 -0
  14. package/dist/setup/connector-blocks.js +132 -0
  15. package/dist/setup/connector-form-model.d.ts +40 -0
  16. package/dist/setup/connector-form-model.d.ts.map +1 -0
  17. package/dist/setup/connector-form-model.js +76 -0
  18. package/dist/setup/flow-model.d.ts +49 -0
  19. package/dist/setup/flow-model.d.ts.map +1 -0
  20. package/dist/setup/flow-model.js +124 -0
  21. package/dist/setup/health-card.d.ts +25 -0
  22. package/dist/setup/health-card.d.ts.map +1 -0
  23. package/dist/setup/health-card.js +21 -0
  24. package/dist/setup/index.d.ts +13 -0
  25. package/dist/setup/index.d.ts.map +1 -0
  26. package/dist/setup/index.js +15 -0
  27. package/dist/setup/messages.d.ts +15 -0
  28. package/dist/setup/messages.d.ts.map +1 -0
  29. package/dist/setup/messages.js +320 -0
  30. package/dist/setup/records-table.d.ts +24 -0
  31. package/dist/setup/records-table.d.ts.map +1 -0
  32. package/dist/setup/records-table.js +80 -0
  33. package/dist/setup/setup-flow.d.ts +30 -0
  34. package/dist/setup/setup-flow.d.ts.map +1 -0
  35. package/dist/setup/setup-flow.js +277 -0
  36. package/dist/setup/setup-form-step.d.ts +20 -0
  37. package/dist/setup/setup-form-step.d.ts.map +1 -0
  38. package/dist/setup/setup-form-step.js +173 -0
  39. package/dist/setup/step-status-badge.d.ts +12 -0
  40. package/dist/setup/step-status-badge.d.ts.map +1 -0
  41. package/dist/setup/step-status-badge.js +21 -0
  42. package/dist/setup/tone.d.ts +8 -0
  43. package/dist/setup/tone.d.ts.map +1 -0
  44. package/dist/setup/tone.js +33 -0
  45. package/dist/setup/types.d.ts +130 -0
  46. package/dist/setup/types.d.ts.map +1 -0
  47. package/dist/setup/types.js +1 -0
  48. package/package.json +9 -5
  49. package/src/__tests__/addon-config-surface.test.tsx +260 -0
  50. package/src/__tests__/connector-blocks.test.tsx +302 -0
  51. package/src/__tests__/setup-components.test.tsx +147 -0
  52. package/src/__tests__/setup-flow-model.test.ts +117 -0
  53. package/src/__tests__/setup-flow.test.tsx +424 -0
  54. package/src/index.ts +29 -0
  55. package/src/setup/addon-config-surface.tsx +1426 -0
  56. package/src/setup/connector-blocks-model.ts +163 -0
  57. package/src/setup/connector-blocks.tsx +341 -0
  58. package/src/setup/connector-form-model.ts +115 -0
  59. package/src/setup/flow-model.ts +156 -0
  60. package/src/setup/health-card.tsx +131 -0
  61. package/src/setup/index.ts +35 -0
  62. package/src/setup/messages.ts +334 -0
  63. package/src/setup/records-table.tsx +186 -0
  64. package/src/setup/setup-flow.tsx +562 -0
  65. package/src/setup/setup-form-step.tsx +342 -0
  66. package/src/setup/step-status-badge.tsx +47 -0
  67. package/src/setup/tone.ts +44 -0
  68. package/src/setup/types.ts +147 -0
@@ -0,0 +1,342 @@
1
+ import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
2
+ import { Loader2 } from 'lucide-react'
3
+ import {
4
+ Button,
5
+ Input,
6
+ Label,
7
+ Select,
8
+ SelectContent,
9
+ SelectItem,
10
+ SelectTrigger,
11
+ SelectValue,
12
+ Switch,
13
+ Textarea,
14
+ } from '@asteby/metacore-ui/primitives'
15
+ import { cn } from '@asteby/metacore-ui/lib'
16
+ import { evaluateVisibleWhen, getVisibleWhen } from '../dynamic-form-schema'
17
+ import { groupFieldsBySection } from '../form-layout'
18
+ import { FieldSection, WizardProgress } from '../form-layout-ui'
19
+ import { useSetupT } from './messages'
20
+ import type { SetupField, SetupStepDef, SetupStepState } from './types'
21
+
22
+ export type AutosaveState = 'idle' | 'saving' | 'saved' | 'error'
23
+
24
+ const AUTOSAVE_MS = 800
25
+
26
+ function initialValues(fields: SetupField[], saved?: Record<string, unknown>): Record<string, unknown> {
27
+ const out: Record<string, unknown> = {}
28
+ for (const f of fields) {
29
+ if (f.write_only || f.type === 'secret') continue
30
+ if (saved && f.key in saved) out[f.key] = saved[f.key]
31
+ else if (f.default !== undefined) out[f.key] = f.default
32
+ else if (f.type === 'select' && f.options?.length) out[f.key] = f.options[0].value
33
+ }
34
+ return out
35
+ }
36
+
37
+ const isWriteOnly = (f: SetupField) => !!f.write_only || f.type === 'secret'
38
+ const isEmpty = (v: unknown) => v == null || (typeof v === 'string' && v.trim() === '')
39
+
40
+ export interface SetupFormStepProps {
41
+ step: SetupStepDef
42
+ state?: SetupStepState
43
+ busy?: boolean
44
+ /** Draft autosave; absent → no autosave and no indicator. */
45
+ onAutosave?: (values: Record<string, unknown>) => Promise<void>
46
+ /** Final submit: the dirty values (secrets only when typed). */
47
+ onSubmit: (values: Record<string, unknown>) => void | Promise<void>
48
+ }
49
+
50
+ /**
51
+ * Form step of a setup flow. Sections / wizard sub-steps come from the shared
52
+ * `form-layout` grouping and `form-layout-ui` chrome (the same ones model
53
+ * forms use). `write_only` fields are never read back: the input stays empty
54
+ * and an empty value keeps the stored one. Edits autosave (debounced) and the
55
+ * save state is visible and announced.
56
+ */
57
+ export function SetupFormStep({ step, state, busy, onAutosave, onSubmit }: SetupFormStepProps) {
58
+ const t = useSetupT()
59
+ const fields = step.fields ?? []
60
+ const [values, setValues] = useState<Record<string, unknown>>(() => initialValues(fields, state?.values))
61
+ const [stored, setStored] = useState<Set<string>>(() => new Set(state?.stored_keys ?? []))
62
+ const [errors, setErrors] = useState<Record<string, string>>({})
63
+ const [autosave, setAutosave] = useState<AutosaveState>('idle')
64
+ const [stepIdx, setStepIdx] = useState(0)
65
+ const dirty = useRef<Set<string>>(new Set())
66
+ const [dirtyTick, setDirtyTick] = useState(0)
67
+ const idPrefix = useId()
68
+ const formRef = useRef<HTMLFormElement>(null)
69
+ const valuesRef = useRef(values)
70
+ valuesRef.current = values
71
+
72
+ // Server values arrive (resume / refetch): fill what the person has not touched.
73
+ useEffect(() => {
74
+ if (!state?.values) return
75
+ setValues((prev) => {
76
+ const next = { ...prev }
77
+ for (const [k, v] of Object.entries(state.values!)) if (!dirty.current.has(k)) next[k] = v
78
+ return next
79
+ })
80
+ }, [state?.values])
81
+ useEffect(() => {
82
+ if (state?.stored_keys) setStored(new Set(state.stored_keys))
83
+ }, [state?.stored_keys])
84
+
85
+ const setValue = (key: string, v: unknown) => {
86
+ setValues((p) => ({ ...p, [key]: v }))
87
+ dirty.current.add(key)
88
+ setDirtyTick((n) => n + 1)
89
+ if (errors[key]) setErrors(({ [key]: _d, ...rest }) => rest)
90
+ }
91
+
92
+ const payloadFor = useCallback(
93
+ (keys: Iterable<string>) => {
94
+ const out: Record<string, unknown> = {}
95
+ const v = valuesRef.current
96
+ for (const k of keys) {
97
+ const f = fields.find((x) => x.key === k)
98
+ if (!f) continue
99
+ if (isWriteOnly(f) && isEmpty(v[k])) continue
100
+ out[k] = v[k]
101
+ }
102
+ return out
103
+ },
104
+ [fields],
105
+ )
106
+
107
+ // Debounced autosave of what changed.
108
+ useEffect(() => {
109
+ if (!onAutosave || dirty.current.size === 0) return
110
+ // Write-only fields (secrets) never autosave: a half-typed secret would be
111
+ // stored truncated. They travel only in the explicit submit.
112
+ const snapshot = new Set(
113
+ [...dirty.current].filter((k) => {
114
+ const f = fields.find((x) => x.key === k)
115
+ return !!f && !isWriteOnly(f)
116
+ }),
117
+ )
118
+ if (snapshot.size === 0) return
119
+ const id = setTimeout(async () => {
120
+ const payload = payloadFor(snapshot)
121
+ if (Object.keys(payload).length === 0) return
122
+ setAutosave('saving')
123
+ try {
124
+ await onAutosave(payload)
125
+ for (const k of snapshot) dirty.current.delete(k)
126
+ setAutosave('saved')
127
+ } catch {
128
+ setAutosave('error')
129
+ }
130
+ }, AUTOSAVE_MS)
131
+ return () => clearTimeout(id)
132
+ // eslint-disable-next-line react-hooks/exhaustive-deps
133
+ }, [dirtyTick])
134
+
135
+ const visible = useMemo(
136
+ () => fields.filter((f) => evaluateVisibleWhen(getVisibleWhen(f), values)),
137
+ [fields, values],
138
+ )
139
+ const layout = step.form_layout
140
+ const groups = useMemo(() => groupFieldsBySection(visible, layout, values), [visible, layout, values])
141
+ const stepMode = layout?.mode === 'steps' && groups.length > 1
142
+ const idx = Math.min(stepIdx, Math.max(0, groups.length - 1))
143
+ const shown = stepMode ? [groups[idx]] : groups
144
+
145
+ const labelOf = (f: SetupField) =>
146
+ f.label ?? f.key.replace(/[_-]+/g, ' ').replace(/\b\w/g, (m) => m.toUpperCase())
147
+
148
+ const submit = async () => {
149
+ const errs: Record<string, string> = {}
150
+ for (const f of visible) {
151
+ if (!f.required || f.type === 'boolean') continue
152
+ if (isWriteOnly(f) && stored.has(f.key)) continue
153
+ if (f.default != null && f.default !== '') continue
154
+ if (isEmpty(values[f.key])) errs[f.key] = t('form.field_required')
155
+ }
156
+ setErrors(errs)
157
+ const missing = Object.keys(errs)
158
+ if (missing.length > 0) {
159
+ const first = fields.find((f) => f.key === missing[0])
160
+ if (stepMode && first) {
161
+ const gi = groups.findIndex((g) => g.fields.some((x) => (x as SetupField).key === first.key))
162
+ if (gi >= 0) setStepIdx(gi)
163
+ }
164
+ window.setTimeout(
165
+ () => formRef.current?.querySelector<HTMLElement>(`[id="${idPrefix}-${missing[0]}"]`)?.focus(),
166
+ 30,
167
+ )
168
+ return
169
+ }
170
+ const keys = new Set<string>([...dirty.current, ...visible.filter((f) => !isWriteOnly(f)).map((f) => f.key)])
171
+ await onSubmit(payloadFor(keys))
172
+ }
173
+
174
+ const missingList = Object.keys(errors).map((k) => labelOf(fields.find((f) => f.key === k)!)).join(', ')
175
+
176
+ return (
177
+ <form
178
+ ref={formRef}
179
+ className='flex flex-col gap-4'
180
+ noValidate
181
+ onSubmit={(e) => {
182
+ e.preventDefault()
183
+ void submit()
184
+ }}
185
+ >
186
+ {stepMode ? (
187
+ <WizardProgress
188
+ groups={groups}
189
+ stepIndex={idx}
190
+ stepLabel={t('form.step')}
191
+ onStepClick={(i) => setStepIdx(i)}
192
+ />
193
+ ) : null}
194
+
195
+ {shown.map((g) => (
196
+ <FieldSection key={g.key} group={g}>
197
+ <div className='flex flex-col gap-3'>
198
+ {(g.fields as SetupField[]).map((f) => (
199
+ <FieldControl
200
+ key={f.key}
201
+ field={f}
202
+ idPrefix={idPrefix}
203
+ label={labelOf(f)}
204
+ value={values[f.key]}
205
+ stored={stored.has(f.key)}
206
+ error={errors[f.key]}
207
+ onChange={(v) => setValue(f.key, v)}
208
+ />
209
+ ))}
210
+ </div>
211
+ </FieldSection>
212
+ ))}
213
+
214
+ {missingList ? (
215
+ <p role='alert' className='text-sm text-destructive'>
216
+ {t('form.missing', { fields: missingList })}
217
+ </p>
218
+ ) : null}
219
+
220
+ <div className='flex flex-wrap items-center justify-between gap-3'>
221
+ <p
222
+ role='status'
223
+ aria-live='polite'
224
+ className={cn('text-xs', autosave === 'error' ? 'text-destructive' : 'text-muted-foreground')}
225
+ >
226
+ {autosave === 'saving'
227
+ ? t('form.saving')
228
+ : autosave === 'saved'
229
+ ? t('form.saved')
230
+ : autosave === 'error'
231
+ ? t('form.save_error')
232
+ : ''}
233
+ </p>
234
+ <div className='flex gap-2'>
235
+ {stepMode && idx > 0 ? (
236
+ <Button type='button' variant='outline' onClick={() => setStepIdx(idx - 1)}>
237
+ {t('form.back')}
238
+ </Button>
239
+ ) : null}
240
+ {stepMode && idx < groups.length - 1 ? (
241
+ <Button type='button' onClick={() => setStepIdx(idx + 1)}>
242
+ {t('form.next')}
243
+ </Button>
244
+ ) : (
245
+ <Button type='submit' disabled={busy}>
246
+ {busy ? <Loader2 className='mr-2 h-4 w-4 animate-spin motion-reduce:animate-none' aria-hidden='true' /> : null}
247
+ {step.action_label ?? t('form.continue')}
248
+ </Button>
249
+ )}
250
+ </div>
251
+ </div>
252
+ </form>
253
+ )
254
+ }
255
+
256
+ function FieldControl({
257
+ field,
258
+ idPrefix,
259
+ label,
260
+ value,
261
+ stored,
262
+ error,
263
+ onChange,
264
+ }: {
265
+ field: SetupField
266
+ idPrefix: string
267
+ label: string
268
+ value: unknown
269
+ stored: boolean
270
+ error?: string
271
+ onChange: (v: unknown) => void
272
+ }) {
273
+ const t = useSetupT()
274
+ const id = `${idPrefix}-${field.key}`
275
+ const secret = isWriteOnly(field)
276
+ const describedBy = [field.description ? `${id}-help` : '', error ? `${id}-error` : '', secret && stored ? `${id}-stored` : '']
277
+ .filter(Boolean)
278
+ .join(' ')
279
+ const common = { id, 'aria-invalid': error ? true : undefined, 'aria-describedby': describedBy || undefined } as const
280
+ return (
281
+ <div className='flex flex-col gap-1'>
282
+ <Label htmlFor={id}>
283
+ {label}
284
+ {field.required ? <span className='text-destructive' aria-hidden='true'> *</span> : null}
285
+ </Label>
286
+ {field.type === 'boolean' ? (
287
+ <Switch id={id} checked={!!value} onCheckedChange={(c) => onChange(c)} aria-describedby={describedBy || undefined} />
288
+ ) : field.type === 'select' && field.options?.length ? (
289
+ <Select value={String(value ?? '')} onValueChange={(v) => onChange(v)}>
290
+ <SelectTrigger {...common}>
291
+ <SelectValue placeholder={t('form.choose')} />
292
+ </SelectTrigger>
293
+ <SelectContent>
294
+ {field.options.map((o) => (
295
+ <SelectItem key={o.value} value={o.value}>
296
+ {o.label}
297
+ </SelectItem>
298
+ ))}
299
+ </SelectContent>
300
+ </Select>
301
+ ) : field.type === 'textarea' ? (
302
+ <Textarea {...common} value={String(value ?? '')} placeholder={field.placeholder} onChange={(e) => onChange(e.target.value)} />
303
+ ) : (
304
+ <Input
305
+ {...common}
306
+ type={secret ? 'password' : field.type === 'number' ? 'number' : 'text'}
307
+ autoComplete={secret ? 'new-password' : 'off'}
308
+ data-1p-ignore={secret ? true : undefined}
309
+ data-lpignore={secret ? 'true' : undefined}
310
+ spellCheck={false}
311
+ placeholder={secret && stored ? '••••••••' : field.placeholder}
312
+ value={String(value ?? '')}
313
+ className={cn(error && 'border-destructive')}
314
+ onChange={(e) =>
315
+ onChange(
316
+ field.type === 'number'
317
+ ? e.target.value === ''
318
+ ? undefined
319
+ : Number(e.target.value)
320
+ : e.target.value,
321
+ )
322
+ }
323
+ />
324
+ )}
325
+ {field.description ? (
326
+ <p id={`${id}-help`} className='text-xs text-muted-foreground'>
327
+ {field.description}
328
+ </p>
329
+ ) : null}
330
+ {secret && stored ? (
331
+ <p id={`${id}-stored`} className='text-xs text-muted-foreground'>
332
+ {t('form.stored')}
333
+ </p>
334
+ ) : null}
335
+ {error ? (
336
+ <p id={`${id}-error`} role='alert' className='text-xs text-destructive'>
337
+ {error}
338
+ </p>
339
+ ) : null}
340
+ </div>
341
+ )
342
+ }
@@ -0,0 +1,47 @@
1
+ import { AlertTriangle, Circle, CheckCircle2, Loader2, Lock, XCircle } from 'lucide-react'
2
+ import { cn } from '@asteby/metacore-ui/lib'
3
+ import { useSetupT } from './messages'
4
+ import { STEP_TONE, TONE_BADGE } from './tone'
5
+ import type { StepStatus } from './types'
6
+
7
+ const ICONS = {
8
+ pending: Circle,
9
+ running: Loader2,
10
+ ok: CheckCircle2,
11
+ warn: AlertTriangle,
12
+ error: XCircle,
13
+ blocked: Lock,
14
+ } as const
15
+
16
+ export interface StepStatusBadgeProps {
17
+ status: StepStatus
18
+ /** Overrides the localized label. */
19
+ label?: string
20
+ /** Icon only (the label stays available to screen readers). */
21
+ compact?: boolean
22
+ className?: string
23
+ }
24
+
25
+ /** Pill with icon + text for a step status; the text is always present for a11y. */
26
+ export function StepStatusBadge({ status, label, compact, className }: StepStatusBadgeProps) {
27
+ const t = useSetupT()
28
+ const known = status in ICONS ? status : 'pending'
29
+ const Icon = ICONS[known]
30
+ const text = label ?? t(`status.${known}`)
31
+ return (
32
+ <span
33
+ data-status={known}
34
+ className={cn(
35
+ 'inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-xs font-medium',
36
+ TONE_BADGE[STEP_TONE[known]],
37
+ className,
38
+ )}
39
+ >
40
+ <Icon
41
+ aria-hidden='true'
42
+ className={cn('h-3.5 w-3.5 shrink-0', known === 'running' && 'animate-spin motion-reduce:animate-none')}
43
+ />
44
+ <span className={cn(compact && 'sr-only')}>{text}</span>
45
+ </span>
46
+ )
47
+ }
@@ -0,0 +1,44 @@
1
+ // Visual tones shared by the badges, record rows and health metrics. Classes
2
+ // are literal strings (Tailwind scans them) with light + dark variants; the
3
+ // meaning is never carried by colour alone (every tone also has an icon/text).
4
+ import type { MetricTone, RecordStatus, StepStatus } from './types'
5
+
6
+ export type Tone = 'neutral' | 'info' | 'good' | 'warn' | 'bad'
7
+
8
+ export const TONE_BADGE: Record<Tone, string> = {
9
+ neutral: 'border-border bg-muted text-muted-foreground',
10
+ info: 'border-sky-500/30 bg-sky-500/10 text-sky-700 dark:text-sky-300',
11
+ good: 'border-emerald-500/30 bg-emerald-500/10 text-emerald-700 dark:text-emerald-300',
12
+ warn: 'border-amber-500/40 bg-amber-500/10 text-amber-800 dark:text-amber-300',
13
+ bad: 'border-destructive/40 bg-destructive/10 text-destructive',
14
+ }
15
+
16
+ export const TONE_TEXT: Record<Tone, string> = {
17
+ neutral: 'text-foreground',
18
+ info: 'text-sky-700 dark:text-sky-300',
19
+ good: 'text-emerald-700 dark:text-emerald-300',
20
+ warn: 'text-amber-800 dark:text-amber-300',
21
+ bad: 'text-destructive',
22
+ }
23
+
24
+ export const STEP_TONE: Record<StepStatus, Tone> = {
25
+ pending: 'neutral',
26
+ running: 'info',
27
+ ok: 'good',
28
+ warn: 'warn',
29
+ error: 'bad',
30
+ blocked: 'neutral',
31
+ }
32
+
33
+ export const RECORD_TONE: Record<RecordStatus, Tone> = {
34
+ ok: 'good',
35
+ missing: 'bad',
36
+ wrong_value: 'bad',
37
+ propagating: 'info',
38
+ pending: 'neutral',
39
+ error: 'bad',
40
+ }
41
+
42
+ export function metricTone(t: MetricTone | undefined): Tone {
43
+ return t === 'good' ? 'good' : t === 'warn' ? 'warn' : t === 'bad' ? 'bad' : 'neutral'
44
+ }
@@ -0,0 +1,147 @@
1
+ // Wire shapes for `contributions.setup` / `contributions.health` and the
2
+ // adapter the host provides to drive a setup flow. Pure types: importing this
3
+ // file costs nothing at runtime.
4
+ import type { FormLayout } from '../form-layout'
5
+ import type { VisibleWhen } from '../types'
6
+
7
+ export type StepStatus = 'pending' | 'running' | 'ok' | 'warn' | 'error' | 'blocked'
8
+ export type SetupStepKind = 'check' | 'form' | 'action' | 'records' | 'custom'
9
+
10
+ /** What the "fix" button of a diagnostic does. Exactly one is expected. */
11
+ export interface SetupFix {
12
+ label?: string
13
+ /** Runs a server action on the step (`runStep(step, { action })`). */
14
+ action?: string
15
+ /** Opens a link (http(s) or an app-relative path). */
16
+ url?: string
17
+ /** Jumps to another step of the flow. */
18
+ step?: string
19
+ }
20
+
21
+ export type DiagnosticSeverity = 'info' | 'warn' | 'error'
22
+
23
+ export interface SetupDiagnostic {
24
+ code?: string
25
+ severity?: DiagnosticSeverity
26
+ message: string
27
+ detail?: string
28
+ fix?: SetupFix
29
+ }
30
+
31
+ export type RecordStatus = 'ok' | 'missing' | 'wrong_value' | 'propagating' | 'pending' | 'error'
32
+
33
+ /** One row of a records step (typically a DNS record to publish). */
34
+ export interface SetupRecord {
35
+ id?: string
36
+ type: string
37
+ name: string
38
+ value: string
39
+ status?: RecordStatus
40
+ /** Human explanation for the row's state. */
41
+ diagnostic?: string | SetupDiagnostic
42
+ /** What the server actually found, when it differs. */
43
+ found?: string
44
+ ttl?: number
45
+ priority?: number
46
+ }
47
+
48
+ export type SetupFieldType = 'text' | 'secret' | 'number' | 'boolean' | 'select' | 'textarea'
49
+
50
+ export interface SetupField {
51
+ key: string
52
+ type?: SetupFieldType
53
+ label?: string
54
+ description?: string
55
+ placeholder?: string
56
+ required?: boolean
57
+ /** Value is never read back from the server; empty input keeps the stored one. */
58
+ write_only?: boolean
59
+ default?: unknown
60
+ options?: { value: string; label: string }[]
61
+ /** `form_layout` section this field belongs to. */
62
+ section?: string
63
+ visible_when?: VisibleWhen
64
+ }
65
+
66
+ export interface SetupStepDef {
67
+ key: string
68
+ kind: SetupStepKind
69
+ title: string
70
+ description?: string
71
+ depends_on?: string[]
72
+ optional?: boolean
73
+ /** kind=form */
74
+ fields?: SetupField[]
75
+ form_layout?: FormLayout
76
+ /** kind=action / check / records: label of the main button. */
77
+ action_label?: string
78
+ /** kind=custom: federated slot name (default `setup.<flow>.<step>`). */
79
+ slot?: string
80
+ }
81
+
82
+ export interface SetupFlowDef {
83
+ key?: string
84
+ title?: string
85
+ description?: string
86
+ steps: SetupStepDef[]
87
+ }
88
+
89
+ export interface SetupStepState {
90
+ key: string
91
+ status: StepStatus
92
+ message?: string
93
+ diagnostics?: SetupDiagnostic[]
94
+ records?: SetupRecord[]
95
+ /** Non-secret saved values (kind=form). */
96
+ values?: Record<string, unknown>
97
+ /** write_only fields that already hold a stored value. */
98
+ stored_keys?: string[]
99
+ /** Server hint: poll again after this many seconds. */
100
+ retry_after_s?: number
101
+ skipped?: boolean
102
+ updated_at?: string
103
+ }
104
+
105
+ export interface SetupFlowState {
106
+ steps: SetupStepState[] | Record<string, SetupStepState>
107
+ /** Server's own verdict; otherwise derived from the steps. */
108
+ completed?: boolean
109
+ }
110
+
111
+ export interface RunStepInput {
112
+ values?: Record<string, unknown>
113
+ action?: string
114
+ }
115
+
116
+ /** What the host plugs in. The server owns the state; the UI is resumable. */
117
+ export interface SetupFlowClient {
118
+ getState(): Promise<SetupFlowState>
119
+ /** May answer the new step state, the whole flow state, or nothing (then the state is re-read). */
120
+ runStep(key: string, input?: RunStepInput): Promise<SetupStepState | SetupFlowState | void>
121
+ skipStep(key: string): Promise<SetupStepState | SetupFlowState | void>
122
+ /** Autosave of a form step's draft (non-final). Absent → no autosave. */
123
+ saveStep?(key: string, values: Record<string, unknown>): Promise<void>
124
+ /** Push channel (SSE/WS). Returns the unsubscribe. Polling still covers a missed push. */
125
+ subscribe?(onState: (state: SetupFlowState) => void): () => void
126
+ }
127
+
128
+ // ─── Health ─────────────────────────────────────────────────────────────────
129
+ export type HealthStatus = 'ok' | 'warn' | 'error' | 'unknown'
130
+ export type MetricTone = 'neutral' | 'good' | 'warn' | 'bad'
131
+
132
+ export interface HealthMetric {
133
+ key: string
134
+ label: string
135
+ value: string | number
136
+ unit?: string
137
+ tone?: MetricTone
138
+ hint?: string
139
+ }
140
+
141
+ export interface HealthIssue {
142
+ id?: string
143
+ severity: DiagnosticSeverity
144
+ message: string
145
+ detail?: string
146
+ fix?: SetupFix
147
+ }