@linxin666/dsh-pet 0.4.10 → 0.4.12

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 (58) hide show
  1. package/README.i18n.yaml +2 -2
  2. package/README.md +1 -1
  3. package/README.zh.md +4 -4
  4. package/lib/client.js +1137 -352
  5. package/lib/client.js.map +1 -1
  6. package/lib/index.js +32 -0
  7. package/lib/types/client/PetPreview.d.ts +12 -0
  8. package/lib/types/client/PetPreview.d.ts.map +1 -0
  9. package/lib/types/client/PetPreview.js +32 -0
  10. package/lib/types/client/PetSettingsCard.d.ts +46 -3
  11. package/lib/types/client/PetSettingsCard.d.ts.map +1 -1
  12. package/lib/types/client/PetSettingsCard.js +96 -11
  13. package/lib/types/client/PluginSettingsCard.d.ts +131 -17
  14. package/lib/types/client/PluginSettingsCard.d.ts.map +1 -1
  15. package/lib/types/client/PluginSettingsCard.js +158 -37
  16. package/lib/types/client/RangeBubble.d.ts +47 -0
  17. package/lib/types/client/RangeBubble.d.ts.map +1 -0
  18. package/lib/types/client/RangeBubble.js +107 -0
  19. package/lib/types/client/SegmentGroup.d.ts +29 -0
  20. package/lib/types/client/SegmentGroup.d.ts.map +1 -0
  21. package/lib/types/client/SegmentGroup.js +81 -0
  22. package/lib/types/client/index.d.ts.map +1 -1
  23. package/lib/types/client/index.js +9 -28
  24. package/lib/types/client/locales.d.ts +36 -44
  25. package/lib/types/client/locales.d.ts.map +1 -1
  26. package/lib/types/client/locales.js +36 -44
  27. package/lib/types/client/settings-form.d.ts +79 -41
  28. package/lib/types/client/settings-form.d.ts.map +1 -1
  29. package/lib/types/client/settings-form.js +96 -36
  30. package/lib/types/client/settings-registration.d.ts +15 -0
  31. package/lib/types/client/settings-registration.d.ts.map +1 -0
  32. package/lib/types/client/settings-registration.js +24 -0
  33. package/lib/types/client/web-extension-contract.d.ts +32 -0
  34. package/lib/types/client/web-extension-contract.d.ts.map +1 -0
  35. package/lib/types/client/web-extension-contract.js +6 -0
  36. package/lib/types/client/web-extension-page.d.ts +51 -0
  37. package/lib/types/client/web-extension-page.d.ts.map +1 -0
  38. package/lib/types/client/web-extension-page.js +122 -0
  39. package/lib/types/registry.d.ts.map +1 -1
  40. package/lib/types/registry.js +35 -0
  41. package/package.json +1 -1
  42. package/src/client/PetPreview.tsx +51 -0
  43. package/src/client/PetSettingsCard.test.tsx +78 -22
  44. package/src/client/PetSettingsCard.tsx +252 -115
  45. package/src/client/PluginSettingsCard.tsx +369 -108
  46. package/src/client/RangeBubble.tsx +163 -0
  47. package/src/client/SegmentGroup.tsx +92 -0
  48. package/src/client/index.ts +9 -27
  49. package/src/client/locales.ts +36 -44
  50. package/src/client/settings-card.module.css +493 -91
  51. package/src/client/settings-form.ts +116 -49
  52. package/src/client/settings-registration.test.ts +79 -0
  53. package/src/client/settings-registration.ts +34 -0
  54. package/src/client/settings-section.module.css +182 -0
  55. package/src/client/web-extension-contract.ts +35 -0
  56. package/src/client/web-extension-page.ts +150 -0
  57. package/src/registry.test.ts +121 -1
  58. package/src/registry.ts +37 -0
@@ -1,15 +1,22 @@
1
- // Generated by scripts/sync-shared.mjs from shared/client/settings/PluginSettingsCard.tsx. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
2
1
  /**
3
2
  * Family-shared chrome for plugin settings cards: a disclosure header naming
4
- * the plugin and what its settings govern, the controls inside, and the save
5
- * that writes them. Renders nothing while the namespace is unavailable — a
3
+ * the plugin and what its settings govern, the controls inside, and the line
4
+ * that reports a refused write. A pick is written the moment it is made and a
5
+ * typed value after a pause, so the card has no save button and nothing waits
6
+ * on the reader. Renders nothing while the namespace is unavailable — a
6
7
  * deployment that does not compose the owning plugin should show no trace of
7
8
  * it. Inlined into each consumer's client bundle; mirrors the official
8
9
  * ui-plugin-config PluginCard in a self-contained slice.
10
+ *
11
+ * Every field inside the body is one settings row: the label and its hint on
12
+ * the left, the control on the right, a hairline between two rows; a narrow
13
+ * card stacks the control under the text (settings-card.module.css).
9
14
  */
10
15
 
11
- import { useCallback, useEffect, useLayoutEffect, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
16
+ import { createContext, useCallback, useContext, useEffect, useLayoutEffect, useRef, useState, type KeyboardEvent, type ReactNode } from 'react'
12
17
  import type { CardShell } from './settings-form.ts'
18
+ import { RangeBubble } from './RangeBubble.tsx'
19
+ import { SegmentGroup } from './SegmentGroup.tsx'
13
20
  import css from './settings-card.module.css'
14
21
 
15
22
  /** Copy keys the card chrome itself reads; every consumer locale carries this shared vocabulary. */
@@ -17,14 +24,17 @@ export const CARD_COPY_KEYS = [
17
24
  'settings.collapse',
18
25
  'settings.expand',
19
26
  'settings.notExposed',
20
- 'settings.unsaved',
21
27
  'settings.readOnly',
22
28
  'settings.saveFailed',
23
- 'settings.discard',
24
- 'settings.save',
25
- 'settings.saving',
26
29
  ] as const
27
30
 
31
+ /**
32
+ * What a text field inside a card reaches without its plugin wiring it: write
33
+ * the pending draft now (Enter, leaving the field) or put it back (Escape).
34
+ * Picks need neither; they are written the moment they are made.
35
+ */
36
+ const CardApply = createContext<{ commit(): void, revert(): void } | null>(null)
37
+
28
38
  /** Copy key the card chrome itself reads. */
29
39
  export type CardCopyKey = (typeof CARD_COPY_KEYS)[number]
30
40
 
@@ -41,12 +51,40 @@ export interface PluginSettingsCardProps<TKey extends string = string> {
41
51
  descriptionKey: TKey
42
52
  /** Optional rich header description rendered instead of the plain t(descriptionKey) text (the plain text stays as the tooltip). */
43
53
  descriptionNode?: ReactNode
44
- /** The card's form state: availability, writability, and what a save would do. */
54
+ /**
55
+ * Locale key of the full sentence behind a shortened description: when
56
+ * present, the header's native `title` takes this text while the visible
57
+ * line keeps `descriptionKey`/`descriptionNode`, so a compact card can
58
+ * compress the sentence without keeping a second visible copy of it.
59
+ * Defaults to the description key.
60
+ */
61
+ descriptionTitleKey?: TKey
62
+ /**
63
+ * Optional leading mark identifying the plugin. A card without one keeps the
64
+ * plain official header shape, so the chrome stays a readable sibling of the
65
+ * built-in PluginCard wherever a family plugin lands in the official bundle
66
+ * seat.
67
+ */
68
+ icon?: ReactNode
69
+ /** The card's form state: availability, writability, and how the last write went. */
45
70
  state: CardShell
46
- /** Write every staged edit. */
71
+ /** Write every pending draft now: a text field's Enter or blur. */
47
72
  onSave: () => void
48
- /** Drop every staged edit. */
73
+ /** Drop every pending draft: a text field's Escape. */
49
74
  onDiscard: () => void
75
+ /**
76
+ * Id applied to the card's title element, so a header control (an immediate
77
+ * toggle in `headerAction`) can name itself through `aria-labelledby`
78
+ * instead of repeating the title as a string.
79
+ */
80
+ titleId?: string
81
+ /**
82
+ * Render the header only, with no body region. A card whose whole setting is
83
+ * the header control (a switch whose explanation is the description) has no
84
+ * controls to lay out below it, and an empty body would draw a divider line
85
+ * with nothing under it.
86
+ */
87
+ headerOnly?: boolean
50
88
  /**
51
89
  * Render the controls expanded on arrival (still collapsible). Defaults to
52
90
  * true: promoted first-level sections show their settings immediately.
@@ -59,19 +97,43 @@ export interface PluginSettingsCardProps<TKey extends string = string> {
59
97
  */
60
98
  alwaysOpen?: boolean
61
99
  /**
62
- * Hide the save/discard footer: cards whose body applies its own changes
63
- * immediately (an embedded external settings section) have no staged
64
- * edits, so the footer would sit there permanently disabled.
100
+ * Hide the line under the body that reports a refused write: a card whose
101
+ * body applies its own changes (an embedded external settings section)
102
+ * reports its own failures.
65
103
  */
66
104
  hideFooter?: boolean
105
+ /**
106
+ * Optional control rendered at the header's trailing edge, before the
107
+ * chevron. A card whose setting is one immediate flip (it
108
+ * applies outside the card's form) puts its ToggleSwitch here, so the control
109
+ * is reachable without opening the card and matches a plugin card's shape.
110
+ */
111
+ headerAction?: ReactNode
67
112
  /** Render children even when the settings namespace is not exposed by the host. */
68
113
  renderChildrenWhenNotExposed?: boolean
69
114
  /** Hide the 'not exposed' warning banner when the settings namespace is not exposed. */
70
115
  hideNotExposedNotice?: boolean
116
+ /**
117
+ * Compact chrome for a topic card rendered inside another card's body: a
118
+ * smaller title, a tighter header and body inset, and a one-line description
119
+ * whose full text stays on the header's own title. Defaults to the
120
+ * first-level chrome, which is unchanged.
121
+ */
122
+ density?: 'nested'
71
123
  /** The plugin's controls. */
72
124
  children: ReactNode
73
125
  }
74
126
 
127
+ /** Length of the body's disclosure motion; it matches `--settings-card-motion` on the card root. */
128
+ const BODY_MOTION_MS = 180
129
+
130
+ /**
131
+ * Lifecycle of one card body. `collapsed` is the mounted-but-closed frame the
132
+ * enter leg starts from, `entering` and `closing` are the two moving legs, and
133
+ * `shown` is the settled open body, which releases its clipping box.
134
+ */
135
+ type BodyPhase = 'hidden' | 'collapsed' | 'entering' | 'shown' | 'closing'
136
+
75
137
  /**
76
138
  * Render one plugin settings card.
77
139
  * @param props - the plugin's copy keys, its form state, and its controls.
@@ -80,22 +142,57 @@ export interface PluginSettingsCardProps<TKey extends string = string> {
80
142
  export function PluginSettingsCard<TKey extends string = string>(props: PluginSettingsCardProps<TKey>) {
81
143
  const [open, setOpen] = useState(props.defaultOpen ?? true)
82
144
  const { state, alwaysOpen } = props
145
+ const expanded = alwaysOpen === true || open
146
+ const [bodyPhase, setBodyPhase] = useState<BodyPhase>(expanded ? 'shown' : 'hidden')
147
+ const bodyRef = useRef<HTMLDivElement | null>(null)
148
+ // Enter and leave run the same pair: a body that should open is mounted
149
+ // closed for one frame so its transition has a state to leave, and a closing
150
+ // one stays mounted until its leg has run.
151
+ useLayoutEffect(() => {
152
+ if (expanded) {
153
+ if (bodyPhase === 'hidden') setBodyPhase('collapsed')
154
+ else if (bodyPhase === 'collapsed') {
155
+ const node = bodyRef.current
156
+ if (node !== null) void node.offsetHeight
157
+ setBodyPhase('entering')
158
+ } else if (bodyPhase === 'closing') setBodyPhase('entering')
159
+ return
160
+ }
161
+ if (bodyPhase === 'collapsed') setBodyPhase('hidden')
162
+ else if (bodyPhase === 'entering' || bodyPhase === 'shown') setBodyPhase('closing')
163
+ }, [expanded, bodyPhase])
164
+ useEffect(() => {
165
+ if (bodyPhase !== 'entering' && bodyPhase !== 'closing') return
166
+ const timer = setTimeout(() => {
167
+ setBodyPhase(bodyPhase === 'entering' ? 'shown' : 'hidden')
168
+ }, BODY_MOTION_MS)
169
+ return () => { clearTimeout(timer) }
170
+ }, [bodyPhase])
83
171
  if (!state.available) return null
84
172
  const title = props.t(props.titleKey)
85
173
  const description = props.t(props.descriptionKey)
86
- const blocked = !state.dirty || state.invalid || state.saving
87
- const expanded = alwaysOpen === true || open
88
- const cardClass = expanded ? `${css.cardOpen} ${css.card}` : css.card
174
+ const descriptionTitle = props.descriptionTitleKey === undefined ? description : props.t(props.descriptionTitleKey)
175
+ const baseClass = expanded ? `${css.cardOpen} ${css.card}` : css.card
176
+ const cardClass = props.density === 'nested' ? `${baseClass} ${css.cardNested}` : baseClass
177
+ /** The body region both legs share; a hidden phase renders nothing at all. */
178
+ const bodyRegion = (content: ReactNode) => bodyPhase === 'hidden'
179
+ ? null
180
+ : (
181
+ <div className={css.disclosure} data-state={bodyPhase} ref={bodyRef}>
182
+ <div className={css.body}>{content}</div>
183
+ </div>
184
+ )
89
185
  // With alwaysOpen the nav entry already provides the selection, so the
90
186
  // header is a static title row instead of a disclosure button.
91
187
  const header = alwaysOpen === true
92
188
  ? (
93
189
  <div className={css.headerStatic}>
190
+ {props.icon !== undefined ? <span className={css.mark} aria-hidden="true">{props.icon}</span> : null}
94
191
  <span className={css.headText}>
95
- <span className={css.name} title={title}>{title}</span>
96
- <span className={css.description} title={description}>{props.descriptionNode ?? description}</span>
192
+ <span className={css.name} id={props.titleId} title={title}>{title}</span>
193
+ <span className={css.description} title={descriptionTitle}>{props.descriptionNode ?? description}</span>
97
194
  </span>
98
- {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
195
+ {props.headerAction !== undefined ? <span className={css.headerAction}>{props.headerAction}</span> : null}
99
196
  </div>
100
197
  )
101
198
  : (
@@ -106,11 +203,12 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
106
203
  aria-label={`${props.t(open ? 'settings.collapse' : 'settings.expand')}: ${title}`}
107
204
  onClick={() => { setOpen(!open) }}
108
205
  >
206
+ {props.icon !== undefined ? <span className={css.mark} aria-hidden="true">{props.icon}</span> : null}
109
207
  <span className={css.headText}>
110
- <span className={css.name} title={title}>{title}</span>
111
- <span className={css.description} title={description}>{props.descriptionNode ?? description}</span>
208
+ <span className={css.name} id={props.titleId} title={title}>{title}</span>
209
+ <span className={css.description} title={descriptionTitle}>{props.descriptionNode ?? description}</span>
112
210
  </span>
113
- {state.dirty ? <span className={css.pending} title={props.t('settings.unsaved')}>{props.t('settings.unsaved')}</span> : null}
211
+ {props.headerAction !== undefined ? <span className={css.headerAction}>{props.headerAction}</span> : null}
114
212
  <svg
115
213
  width="14"
116
214
  height="14"
@@ -135,54 +233,31 @@ export function PluginSettingsCard<TKey extends string = string>(props: PluginSe
135
233
  return (
136
234
  <li className={cardClass}>
137
235
  {header}
138
- {expanded
139
- ? (
140
- <div className={css.body}>
141
- {showNotice ? <p className={css.notExposed} role="status">{props.t('settings.notExposed')}</p> : null}
142
- </div>
143
- )
144
- : null}
236
+ {bodyRegion(showNotice ? <p className={css.notExposed} role="status">{props.t('settings.notExposed')}</p> : null)}
145
237
  </li>
146
238
  )
147
239
  }
240
+ // A header-only card has no body region at all: the divider would otherwise
241
+ // sit above an empty box.
242
+ const bodyVisible = props.headerOnly !== true
148
243
  return (
149
244
  <li className={cardClass}>
150
245
  {header}
151
- {expanded
152
- ? (
153
- <div className={css.body}>
246
+ {bodyVisible
247
+ ? bodyRegion(
248
+ <>
154
249
  {!state.writable ? <p className={css.readOnly} role="status">{props.t('settings.readOnly')}</p> : null}
155
- {props.children}
156
- {props.hideFooter === true
157
- ? null
158
- : (
159
- <div className={css.footer}>
160
- {state.failed
161
- ? (
162
- <p className={css.failed} role="status">
163
- {props.t('settings.saveFailed')}{state.failedReason ? ' - ' + state.failedReason : ''}
164
- </p>
165
- )
166
- : null}
167
- <button
168
- type="button"
169
- className={css.discard}
170
- disabled={!state.dirty || state.saving}
171
- onClick={props.onDiscard}
172
- >
173
- {props.t('settings.discard')}
174
- </button>
175
- <button
176
- type="button"
177
- className={css.save}
178
- disabled={blocked}
179
- onClick={props.onSave}
180
- >
181
- {props.t(!state.saving ? 'settings.save' : 'settings.saving')}
182
- </button>
183
- </div>
184
- )}
185
- </div>
250
+ <CardApply.Provider value={{ commit: props.onSave, revert: props.onDiscard }}>
251
+ {props.children}
252
+ </CardApply.Provider>
253
+ {props.hideFooter !== true && state.failed
254
+ ? (
255
+ <p className={css.failed} role="status">
256
+ {props.t('settings.saveFailed')}{state.failedReason ? ' - ' + state.failedReason : ''}
257
+ </p>
258
+ )
259
+ : null}
260
+ </>,
186
261
  )
187
262
  : null}
188
263
  </li>
@@ -197,9 +272,15 @@ export interface FieldProps {
197
272
  label: string
198
273
  /** One-line explanation rendered under the control. */
199
274
  hint: string
275
+ /**
276
+ * Full sentence behind the visible hint, exposed as the paragraph's native
277
+ * `title` so a card can shorten the line without losing the text. Omitted:
278
+ * the paragraph carries no title attribute at all.
279
+ */
280
+ hintTitle?: string
200
281
  /** Draft text this control renders. */
201
282
  text: string
202
- /** True when saving would leave a user-layer entry for this field. */
283
+ /** True when the field holds a user-layer entry over the inherited value. */
203
284
  overridden: boolean
204
285
  /** True when the draft is not a value this field accepts. */
205
286
  invalid: boolean
@@ -211,19 +292,52 @@ export interface FieldProps {
211
292
  invalidLabel: string
212
293
  /** Disables every control (read-only document, or an unavailable namespace). */
213
294
  disabled: boolean
214
- /** Stage draft text. */
295
+ /** Take new draft text; the card writes it as the field's entry rule says. */
215
296
  onEdit: (text: string) => void
216
- /** Stage a clear so the field re-inherits the composition layer. */
297
+ /** Clear the field at once so it re-inherits the composition layer. */
217
298
  onReset: () => void
218
299
  }
219
300
 
220
- /** A staged value field. `numeric` only hints the keypad: which drafts a field accepts is decided by its spec. */
301
+ /**
302
+ * A typed value field. Its draft is written after a pause in typing, at once on
303
+ * Enter or when focus leaves, and Escape puts the stored value back. `numeric`
304
+ * only hints the keypad: which drafts a field accepts is decided by its spec.
305
+ * A field given a `range` also offers the coarse slider bubble: dragging fills
306
+ * the draft live and releasing writes it.
307
+ */
221
308
  export function ValueField(props: FieldProps & {
222
309
  /** Hints a numeric keypad without narrowing what the control accepts. */
223
310
  numeric?: boolean
224
311
  /** Placeholder shown while the draft is empty. */
225
312
  placeholder?: string
313
+ /** Bounds of a numeric field, for the coarse slider; the spec still judges every draft. */
314
+ range?: { min: number, max: number, step: number }
226
315
  }) {
316
+ const apply = useContext(CardApply)
317
+ const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
318
+ if (apply === null || (event.key !== 'Enter' && event.key !== 'Escape')) return
319
+ event.preventDefault()
320
+ if (event.key === 'Enter') apply.commit()
321
+ else apply.revert()
322
+ event.currentTarget.blur()
323
+ }
324
+ const input = (
325
+ <input
326
+ id={props.id}
327
+ className={props.invalid ? css.inputInvalid : css.input}
328
+ type="text"
329
+ {...props.numeric === true ? { inputMode: 'numeric' as const } : {}}
330
+ {...props.invalid ? { 'aria-invalid': true } : {}}
331
+ value={props.text}
332
+ placeholder={props.placeholder ?? ''}
333
+ disabled={props.disabled}
334
+ onChange={(event) => { props.onEdit(event.target.value) }}
335
+ onKeyDown={onKeyDown}
336
+ onBlur={() => { apply?.commit() }}
337
+ />
338
+ )
339
+ const { range } = props
340
+ const typed = Number(props.text)
227
341
  return (
228
342
  <div className={css.field}>
229
343
  <div className={css.head}>
@@ -244,18 +358,26 @@ export function ValueField(props: FieldProps & {
244
358
  )
245
359
  : null}
246
360
  </div>
247
- <input
248
- id={props.id}
249
- className={props.invalid ? css.inputInvalid : css.input}
250
- type="text"
251
- {...props.numeric === true ? { inputMode: 'numeric' as const } : {}}
252
- {...props.invalid ? { 'aria-invalid': true } : {}}
253
- value={props.text}
254
- placeholder={props.placeholder ?? ''}
255
- disabled={props.disabled}
256
- onChange={(event) => { props.onEdit(event.target.value) }}
257
- />
258
- <p className={props.invalid ? css.invalid : css.hint}>
361
+ {range === undefined
362
+ ? input
363
+ : (
364
+ <RangeBubble
365
+ min={range.min}
366
+ max={range.max}
367
+ step={range.step}
368
+ value={props.text.trim() === '' || Number.isNaN(typed) ? range.min : typed}
369
+ label={`${props.label} ${range.min}–${range.max}`}
370
+ disabled={props.disabled}
371
+ onInput={(value) => { props.onEdit(String(value)) }}
372
+ onCommit={(value) => {
373
+ props.onEdit(String(value))
374
+ apply?.commit()
375
+ }}
376
+ >
377
+ {input}
378
+ </RangeBubble>
379
+ )}
380
+ <p className={props.invalid ? css.invalid : css.hint} title={props.hintTitle}>
259
381
  {props.invalid ? props.invalidLabel : props.hint}
260
382
  </p>
261
383
  </div>
@@ -282,8 +404,8 @@ const SELECT_CLOSE_MS = 100
282
404
  * renders the legacy native `<select>` untouched, so element-level skin
283
405
  * selectors keep working; under the default appearance it renders a
284
406
  * self-drawn `role="listbox"` popup whose open/close is transition-animated.
285
- * Staged cards reach it through BooleanField/ChoiceField; immediate-apply
286
- * editors (the side-card prefs) bind it directly through onEdit.
407
+ * Cards reach it through BooleanField/ChoiceField; editors outside a card
408
+ * (the side-card prefs) bind it directly through onEdit.
287
409
  * 双模式下拉框:皮肤激活时用原生 select,默认外观用自绘动画弹层。
288
410
  */
289
411
  export function SelectField(props: {
@@ -466,7 +588,56 @@ export function SelectField(props: {
466
588
  )
467
589
  }
468
590
 
469
- /** A staged boolean field: 继承 / 开 / 关. */
591
+ /**
592
+ * A visible segmented group for a small set of mutually exclusive values.
593
+ * Every option stays on screen, so inherit/on/off and short enum fields take
594
+ * one click without opening a popup. The pressed option carries the group's
595
+ * sliding highlight and `aria-pressed`; the group takes the field label as its
596
+ * accessible name.
597
+ */
598
+ export function SegmentField(props: {
599
+ id: string
600
+ label: string
601
+ options: ReadonlyArray<SelectOption>
602
+ value: string
603
+ disabled: boolean
604
+ invalid: boolean
605
+ onEdit: (text: string) => void
606
+ }) {
607
+ return (
608
+ <SegmentGroup
609
+ id={props.id}
610
+ role="group"
611
+ aria-label={props.label}
612
+ aria-invalid={props.invalid || undefined}
613
+ >
614
+ {props.options.map((option, index) => {
615
+ const active = option.value === props.value
616
+ return (
617
+ <button
618
+ key={option.value}
619
+ type="button"
620
+ className={css.segment}
621
+ aria-pressed={active}
622
+ disabled={props.disabled}
623
+ data-active={active ? '' : undefined}
624
+ data-segment-index={index}
625
+ onClick={() => {
626
+ if (!active) props.onEdit(option.value)
627
+ }}
628
+ >
629
+ {option.label}
630
+ </button>
631
+ )
632
+ })}
633
+ </SegmentGroup>
634
+ )
635
+ }
636
+
637
+ /** How a small single-choice field presents its options. */
638
+ export type FieldPresentation = 'select' | 'segment'
639
+
640
+ /** A boolean field: 继承 / 开 / 关. */
470
641
  export function BooleanField(props: FieldProps & {
471
642
  /** Copy for the inherit option. */
472
643
  inheritLabel: string
@@ -474,11 +645,16 @@ export function BooleanField(props: FieldProps & {
474
645
  onLabel: string
475
646
  /** Copy for the off option. */
476
647
  offLabel: string
648
+ /** Defaults to the visible segments: the three answers always fit on one row. */
649
+ presentation?: FieldPresentation
477
650
  }) {
651
+ const segmented = props.presentation !== 'select'
478
652
  return (
479
653
  <div className={css.field}>
480
654
  <div className={css.head}>
481
- <label className={css.label} htmlFor={props.id}>{props.label}</label>
655
+ {segmented
656
+ ? <span className={css.label}>{props.label}</span>
657
+ : <label className={css.label} htmlFor={props.id}>{props.label}</label>}
482
658
  {props.overridden
483
659
  ? (
484
660
  <span className={css.badges}>
@@ -495,34 +671,61 @@ export function BooleanField(props: FieldProps & {
495
671
  )
496
672
  : null}
497
673
  </div>
498
- <SelectField
499
- id={props.id}
500
- options={[
501
- { value: '', label: props.inheritLabel },
502
- { value: 'true', label: props.onLabel },
503
- { value: 'false', label: props.offLabel },
504
- ]}
505
- value={props.text}
506
- disabled={props.disabled}
507
- invalid={props.invalid}
508
- onEdit={props.onEdit}
509
- />
510
- <p className={css.hint}>{props.hint}</p>
674
+ {segmented
675
+ ? (
676
+ <SegmentField
677
+ id={props.id}
678
+ label={props.label}
679
+ options={[
680
+ { value: '', label: props.inheritLabel },
681
+ { value: 'true', label: props.onLabel },
682
+ { value: 'false', label: props.offLabel },
683
+ ]}
684
+ value={props.text}
685
+ disabled={props.disabled}
686
+ invalid={props.invalid}
687
+ onEdit={props.onEdit}
688
+ />
689
+ )
690
+ : (
691
+ <SelectField
692
+ id={props.id}
693
+ options={[
694
+ { value: '', label: props.inheritLabel },
695
+ { value: 'true', label: props.onLabel },
696
+ { value: 'false', label: props.offLabel },
697
+ ]}
698
+ value={props.text}
699
+ disabled={props.disabled}
700
+ invalid={props.invalid}
701
+ onEdit={props.onEdit}
702
+ />
703
+ )}
704
+ <p className={css.hint} title={props.hintTitle}>{props.hint}</p>
511
705
  </div>
512
706
  )
513
707
  }
514
708
 
515
- /** A staged enumerated field rendered as a select. */
709
+ /** An enumerated field, selecting or segmenting its small choice set. */
516
710
  export function ChoiceField(props: FieldProps & {
517
711
  /** Copy for the inherit option (draft text is the empty string). */
518
712
  inheritLabel: string
519
713
  /** Choices rendered in order; `value` is the draft/stored text. */
520
714
  choices: ReadonlyArray<{ value: string; label: string }>
715
+ /**
716
+ * Visible segmented options for a short fixed set; defaults to the compact
717
+ * select, which also suits a list whose length follows the deployment.
718
+ */
719
+ presentation?: FieldPresentation
521
720
  }) {
721
+ const segmented = props.presentation === 'segment'
722
+ const options = [{ value: '', label: props.inheritLabel }, ...props.choices]
522
723
  return (
523
724
  <div className={css.field}>
524
725
  <div className={css.head}>
525
- <label className={css.label} htmlFor={props.id}>{props.label}</label>
726
+ {segmented
727
+ ? <span className={css.label}>{props.label}</span>
728
+ : <label className={css.label} htmlFor={props.id}>{props.label}</label>}
526
729
  {props.overridden
527
730
  ? (
528
731
  <span className={css.badges}>
@@ -539,17 +742,75 @@ export function ChoiceField(props: FieldProps & {
539
742
  )
540
743
  : null}
541
744
  </div>
542
- <SelectField
543
- id={props.id}
544
- options={[{ value: '', label: props.inheritLabel }, ...props.choices]}
545
- value={props.text}
546
- disabled={props.disabled}
547
- invalid={props.invalid}
548
- onEdit={props.onEdit}
549
- />
550
- <p className={props.invalid ? css.invalid : css.hint}>
745
+ {segmented
746
+ ? (
747
+ <SegmentField
748
+ id={props.id}
749
+ label={props.label}
750
+ options={options}
751
+ value={props.text}
752
+ disabled={props.disabled}
753
+ invalid={props.invalid}
754
+ onEdit={props.onEdit}
755
+ />
756
+ )
757
+ : (
758
+ <SelectField
759
+ id={props.id}
760
+ options={options}
761
+ value={props.text}
762
+ disabled={props.disabled}
763
+ invalid={props.invalid}
764
+ onEdit={props.onEdit}
765
+ />
766
+ )}
767
+ <p className={props.invalid ? css.invalid : css.hint} title={props.hintTitle}>
551
768
  {props.invalid ? props.invalidLabel : props.hint}
552
769
  </p>
553
770
  </div>
554
771
  )
555
772
  }
773
+
774
+ /**
775
+ * A boolean toggle drawn as a switch track, for a setting that is only on or
776
+ * off and applies on flip. It is a real button with
777
+ * `role="switch"` and `aria-checked`, so keyboard and assistive activation
778
+ * arrive as a click and the state is announced instead of inferred from a
779
+ * checkbox tick.
780
+ *
781
+ * The thumb bounces across only once the reader has pressed this switch: the
782
+ * press writes the mark that arms the bounce, so a page opening, a TAB
783
+ * switching back or a value arriving from elsewhere draws every thumb at rest.
784
+ */
785
+ export function ToggleSwitch(props: {
786
+ /** Id of the element naming the switch (the card's title). */
787
+ labelledBy?: string
788
+ /** Accessible name when no element labels it. */
789
+ ariaLabel?: string
790
+ /** Current state. */
791
+ checked: boolean
792
+ /** Disables the switch while a write is in flight or the Host refuses writes. */
793
+ disabled?: boolean
794
+ /** Called with the requested next state. */
795
+ onChange: (next: boolean) => void
796
+ }) {
797
+ const [moved, setMoved] = useState(false)
798
+ return (
799
+ <button
800
+ type="button"
801
+ className={css.toggle}
802
+ role="switch"
803
+ aria-checked={props.checked}
804
+ aria-labelledby={props.labelledBy}
805
+ aria-label={props.labelledBy === undefined ? props.ariaLabel : undefined}
806
+ disabled={props.disabled}
807
+ data-moved={moved ? '' : undefined}
808
+ onClick={() => {
809
+ setMoved(true)
810
+ props.onChange(!props.checked)
811
+ }}
812
+ >
813
+ <span className={css.toggleTrack}><span className={css.toggleThumb} /></span>
814
+ </button>
815
+ )
816
+ }