@c9up/nebula 0.2.2 → 0.2.4

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 (116) hide show
  1. package/README.md +8 -7
  2. package/dist/atoms/Avatar.d.ts +14 -0
  3. package/dist/atoms/Avatar.js +46 -8
  4. package/dist/atoms/Checkbox.d.ts +1 -1
  5. package/dist/atoms/Checkbox.js +1 -1
  6. package/dist/atoms/Input.d.ts +5 -0
  7. package/dist/atoms/Input.js +1 -0
  8. package/dist/cli/add.d.ts +2 -0
  9. package/dist/cli/add.js +4 -1
  10. package/dist/cli/diff.d.ts +2 -0
  11. package/dist/cli/diff.js +4 -1
  12. package/dist/cli/projectConfig.d.ts +16 -0
  13. package/dist/cli/projectConfig.js +61 -0
  14. package/dist/console/AddCommand.js +6 -1
  15. package/dist/console/DiffCommand.js +6 -1
  16. package/dist/lib/children.d.ts +13 -8
  17. package/dist/lib/children.js +5 -0
  18. package/dist/lib/icons.d.ts +8 -0
  19. package/dist/lib/icons.js +8 -0
  20. package/dist/lib/image.js +12 -1
  21. package/dist/molecules/Breadcrumb.d.ts +11 -2
  22. package/dist/molecules/Breadcrumb.js +2 -2
  23. package/dist/molecules/InputOTP.d.ts +14 -0
  24. package/dist/molecules/InputOTP.js +71 -28
  25. package/dist/molecules/Pagination.d.ts +34 -2
  26. package/dist/molecules/Pagination.js +15 -6
  27. package/dist/molecules/PieceMap.d.ts +72 -0
  28. package/dist/molecules/PieceMap.js +78 -0
  29. package/dist/molecules/Resizable.d.ts +2 -0
  30. package/dist/molecules/Resizable.js +1 -1
  31. package/dist/molecules/index.d.ts +4 -3
  32. package/dist/molecules/index.js +2 -1
  33. package/dist/organisms/Calendar.d.ts +13 -0
  34. package/dist/organisms/Calendar.js +2 -2
  35. package/dist/organisms/Carousel.d.ts +8 -0
  36. package/dist/organisms/Carousel.js +8 -5
  37. package/dist/organisms/Combobox.d.ts +13 -0
  38. package/dist/organisms/Combobox.js +5 -2
  39. package/dist/organisms/Command.js +56 -8
  40. package/dist/organisms/DataTable.d.ts +23 -1
  41. package/dist/organisms/DataTable.js +57 -27
  42. package/dist/organisms/DatePicker.d.ts +7 -0
  43. package/dist/organisms/DatePicker.js +2 -1
  44. package/dist/organisms/DateRangePicker.d.ts +2 -0
  45. package/dist/organisms/DateRangePicker.js +2 -1
  46. package/dist/organisms/Dialog.d.ts +13 -3
  47. package/dist/organisms/Dialog.js +12 -5
  48. package/dist/organisms/Form.d.ts +15 -0
  49. package/dist/organisms/Form.js +10 -0
  50. package/dist/organisms/Questionnaire.d.ts +4 -0
  51. package/dist/organisms/Questionnaire.js +5 -2
  52. package/dist/organisms/Select.d.ts +25 -4
  53. package/dist/organisms/Select.js +116 -15
  54. package/dist/organisms/Sheet.d.ts +2 -0
  55. package/dist/organisms/Sheet.js +2 -1
  56. package/dist/organisms/Sidebar.d.ts +10 -2
  57. package/dist/organisms/Sidebar.js +62 -29
  58. package/dist/organisms/Sonner.d.ts +243 -0
  59. package/dist/organisms/Sonner.js +909 -0
  60. package/dist/organisms/Toaster.d.ts +11 -0
  61. package/dist/organisms/Toaster.js +34 -9
  62. package/dist/organisms/Tooltip.d.ts +4 -0
  63. package/dist/organisms/index.d.ts +8 -2
  64. package/dist/organisms/index.js +7 -1
  65. package/dist/primitives/dismissable.d.ts +11 -4
  66. package/dist/primitives/dismissable.js +8 -6
  67. package/dist/primitives/floating.d.ts +5 -1
  68. package/dist/primitives/floating.js +32 -2
  69. package/dist/primitives/menu.js +2 -1
  70. package/dist/primitives/modalSurface.js +70 -36
  71. package/dist/primitives/presence.js +8 -5
  72. package/dist/templates/SettingsLayout.d.ts +2 -0
  73. package/dist/templates/SettingsLayout.js +1 -1
  74. package/nebula.css +2 -2
  75. package/package.json +3 -3
  76. package/registry.json +26 -0
  77. package/src/atoms/Avatar.ts +54 -7
  78. package/src/atoms/Checkbox.ts +1 -1
  79. package/src/atoms/Input.ts +6 -0
  80. package/src/cli/add.ts +7 -1
  81. package/src/cli/diff.ts +7 -1
  82. package/src/cli/projectConfig.ts +71 -0
  83. package/src/console/AddCommand.ts +6 -1
  84. package/src/console/DiffCommand.ts +6 -1
  85. package/src/lib/children.ts +15 -7
  86. package/src/lib/icons.ts +28 -0
  87. package/src/lib/image.ts +13 -1
  88. package/src/molecules/Breadcrumb.ts +15 -4
  89. package/src/molecules/InputOTP.ts +88 -28
  90. package/src/molecules/Pagination.ts +50 -8
  91. package/src/molecules/PieceMap.ts +136 -0
  92. package/src/molecules/Resizable.ts +3 -1
  93. package/src/molecules/index.ts +17 -0
  94. package/src/organisms/Calendar.ts +16 -2
  95. package/src/organisms/Carousel.ts +17 -5
  96. package/src/organisms/Combobox.ts +18 -2
  97. package/src/organisms/Command.ts +66 -7
  98. package/src/organisms/DataTable.ts +95 -30
  99. package/src/organisms/DatePicker.ts +10 -2
  100. package/src/organisms/DateRangePicker.ts +4 -2
  101. package/src/organisms/Dialog.ts +17 -5
  102. package/src/organisms/Form.ts +21 -0
  103. package/src/organisms/Questionnaire.ts +10 -2
  104. package/src/organisms/Select.ts +140 -16
  105. package/src/organisms/Sheet.ts +5 -1
  106. package/src/organisms/Sidebar.ts +62 -23
  107. package/src/organisms/Sonner.ts +1366 -0
  108. package/src/organisms/Toaster.ts +38 -10
  109. package/src/organisms/Tooltip.ts +4 -0
  110. package/src/organisms/index.ts +30 -1
  111. package/src/primitives/dismissable.ts +16 -8
  112. package/src/primitives/floating.ts +40 -3
  113. package/src/primitives/menu.ts +2 -1
  114. package/src/primitives/modalSurface.ts +77 -40
  115. package/src/primitives/presence.ts +12 -9
  116. package/src/templates/SettingsLayout.ts +3 -1
@@ -1,6 +1,11 @@
1
1
  /**
2
2
  * Toaster — transient notifications.
3
3
  *
4
+ * @deprecated shadcn has deprecated its `toast` component in favour of
5
+ * `sonner`, and so does nebula: use `organisms/Sonner.ts` (`nebula add
6
+ * sonner`), whose `Toaster` and `toast` follow sonner's API. This one stays
7
+ * until apps have moved.
8
+ *
4
9
  * shadcn ships two: `sonner`, which wraps a third-party library, and `toast`,
5
10
  * its own, built on Base UI. nebula keeps it in-house with zero dependencies
6
11
  * and follows the SECOND — the shape is the same: one region mounted once near
@@ -36,7 +41,7 @@
36
41
  * single most common complaint about the pattern.
37
42
  */
38
43
 
39
- import { component, html, signal } from "@c9up/aurora";
44
+ import { component, html, onMount, signal } from "@c9up/aurora";
40
45
  import type { Child } from "../lib/children.js";
41
46
  import { cn } from "../lib/cn.js";
42
47
  import { LoaderIcon, XIcon } from "../lib/icons.js";
@@ -180,6 +185,9 @@ function show(options: ToastOptions): ToastId {
180
185
  } else {
181
186
  id = options.id;
182
187
  }
188
+ // No document: the server, rendering one request in a process shared by
189
+ // every user. Kept here, the toast would reach the next user's markup.
190
+ if (typeof document === "undefined") return id;
183
191
  const variant = options.variant ?? "default";
184
192
  const entry: ActiveToast = { ...options, id, variant };
185
193
  queue([...queue(), entry]);
@@ -230,13 +238,18 @@ function optionsOf(message: ToastMessage): Omit<ToastOptions, "id"> {
230
238
  return { title: message };
231
239
  }
232
240
 
241
+ /** A stage given as a function of the outcome, rather than as the message. */
242
+ function isMessageOf<T>(
243
+ message: ToastMessage | ((value: T) => ToastMessage),
244
+ ): message is (value: T) => ToastMessage {
245
+ return typeof message === "function";
246
+ }
247
+
233
248
  function resolveMessage<T>(
234
249
  message: ToastMessage | ((value: T) => ToastMessage),
235
250
  value: T,
236
251
  ): Omit<ToastOptions, "id"> {
237
- if (typeof message === "function") {
238
- return optionsOf((message as (v: T) => ToastMessage)(value));
239
- }
252
+ if (isMessageOf(message)) return optionsOf(message(value));
240
253
  return optionsOf(message);
241
254
  }
242
255
 
@@ -244,6 +257,8 @@ function resolveMessage<T>(
244
257
  * Raise a toast. Returns its id, which `dismiss` accepts.
245
258
  *
246
259
  * Callable from anywhere — no component, no context, no handle.
260
+ *
261
+ * @deprecated Use `toast` from `organisms/Sonner.ts`, shadcn's current toaster.
247
262
  */
248
263
  export const toast = {
249
264
  show,
@@ -327,6 +342,8 @@ const variantClasses: Record<ToastVariant, string> = {
327
342
  export interface ToasterProps {
328
343
  /** Which corner. Default `"bottom-right"`. */
329
344
  position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
345
+ /** The dismiss cross's accessible name, as sonner names the prop. */
346
+ closeButtonAriaLabel?: string;
330
347
  class?: Reactive<string>;
331
348
  }
332
349
 
@@ -343,9 +360,20 @@ const positionClasses: Record<NonNullable<ToasterProps["position"]>, string> = {
343
360
  * `data-nebula-live` marks it as exempt from the `aria-hidden` sweep a modal
344
361
  * performs over its siblings — a toast raised while a dialog is open still has
345
362
  * to be announced.
363
+ *
364
+ * @deprecated Use `Toaster` from `organisms/Sonner.ts`, shadcn's current toaster.
346
365
  */
347
366
  export const Toaster = component<ToasterProps>((props) => {
348
367
  const position = props.position ?? "bottom-right";
368
+ const closeLabel = props.closeButtonAriaLabel ?? "Dismiss notification";
369
+ const render = (entry: ActiveToast): Child => renderToast(entry, closeLabel);
370
+ // Empty until mounted, so the server's markup carries no toast and the
371
+ // browser adopts the same empty region before filling it.
372
+ const adopted = signal(false);
373
+ onMount(() => {
374
+ adopted(true);
375
+ });
376
+ const shown = (): readonly ActiveToast[] => (adopted() ? queue() : []);
349
377
 
350
378
  return html`<div
351
379
  data-slot="toaster"
@@ -361,20 +389,20 @@ export const Toaster = component<ToasterProps>((props) => {
361
389
  >
362
390
  <div role="status" aria-live="polite" aria-atomic="false" class="contents">
363
391
  ${() =>
364
- queue()
392
+ shown()
365
393
  .filter((entry) => entry.variant !== "error")
366
- .map(renderToast)}
394
+ .map(render)}
367
395
  </div>
368
396
  <div role="alert" aria-live="assertive" aria-atomic="false" class="contents">
369
397
  ${() =>
370
- queue()
398
+ shown()
371
399
  .filter((entry) => entry.variant === "error")
372
- .map(renderToast)}
400
+ .map(render)}
373
401
  </div>
374
402
  </div>`;
375
403
  });
376
404
 
377
- function renderToast(entry: ActiveToast): Child {
405
+ function renderToast(entry: ActiveToast, closeLabel: string): Child {
378
406
  return html`<div
379
407
  data-slot="toast"
380
408
  data-variant="${entry.variant}"
@@ -412,7 +440,7 @@ function renderToast(entry: ActiveToast): Child {
412
440
  }
413
441
  <button
414
442
  type="button"
415
- aria-label="Dismiss notification"
443
+ aria-label="${closeLabel}"
416
444
  class="opacity-60 transition-opacity hover:opacity-100"
417
445
  @click="${() => dismiss(entry.id)}"
418
446
  >${XIcon({ class: "size-4" })}</button>
@@ -294,6 +294,10 @@ export interface TooltipContentProps {
294
294
  /** Which edge of the trigger to sit on. Flips when there is no room. */
295
295
  side?: Side;
296
296
  align?: Align;
297
+ /**
298
+ * Gap past the arrow, in px. `0`, as upstream: the arrow's own length is
299
+ * added by the positioner, the way Radix's popper adds it.
300
+ */
297
301
  sideOffset?: number;
298
302
  class?: Reactive<string>;
299
303
  }
@@ -37,6 +37,7 @@ export {
37
37
  addDays,
38
38
  addMonths,
39
39
  Calendar,
40
+ type CalendarLabels,
40
41
  type CalendarProps,
41
42
  type DateRange,
42
43
  isSameDay,
@@ -120,7 +121,12 @@ export {
120
121
  type ContextMenuTriggerProps,
121
122
  } from "./ContextMenu.js";
122
123
  export { type Column, DataTable, type DataTableProps } from "./DataTable.js";
123
- export { DatePicker, type DatePickerProps, toISODate } from "./DatePicker.js";
124
+ export {
125
+ DatePicker,
126
+ type DatePickerLabels,
127
+ type DatePickerProps,
128
+ toISODate,
129
+ } from "./DatePicker.js";
124
130
  export {
125
131
  DateRangePicker,
126
132
  type DateRangePickerProps,
@@ -385,6 +391,29 @@ export {
385
391
  sidebarState,
386
392
  useSidebar,
387
393
  } from "./Sidebar.js";
394
+ /**
395
+ * shadcn's `sonner`. Its file exports `Toaster` and `toast`, as upstream; the
396
+ * barrel renames them because the deprecated `Toaster` below still owns those
397
+ * names until apps have moved — `nebula add sonner` gives the file itself.
398
+ */
399
+ export {
400
+ type Action as SonnerAction,
401
+ type ExternalToast,
402
+ type Offset as SonnerOffset,
403
+ type Position as SonnerPosition,
404
+ type PromiseData as SonnerPromiseData,
405
+ type PromiseExtendedResult as SonnerPromiseExtendedResult,
406
+ type PromiseResult as SonnerPromiseResult,
407
+ type ToastClassnames,
408
+ Toaster as Sonner,
409
+ type ToasterProps as SonnerProps,
410
+ type ToastIcons,
411
+ type ToastId as SonnerToastId,
412
+ type ToastOptions as SonnerToastOptions,
413
+ type ToastT,
414
+ type ToastType,
415
+ toast as sonnerToast,
416
+ } from "./Sonner.js";
388
417
  export {
389
418
  Toaster,
390
419
  type ToasterProps,
@@ -9,8 +9,8 @@
9
9
  *
10
10
  * So layers live in one stack and the rules are applied once, globally:
11
11
  *
12
- * - **Escape** reaches only the topmost layer that accepts it. That is what
13
- * makes Escape close a submenu first and its parent menu second.
12
+ * - **Escape** reaches only the topmost layer, skipping those that pass it
13
+ * through. One that refuses it dismisses nothing below.
14
14
  * - **Pointer outside** walks the stack top-down and stops at the first layer
15
15
  * the event landed inside. Layers above it close, layers below it stay. A
16
16
  * click in a parent menu therefore closes the submenu and nothing else.
@@ -35,8 +35,15 @@ export interface DismissableOptions {
35
35
  * immediately reopen on click.
36
36
  */
37
37
  exclude?: () => ReadonlyArray<HTMLElement | null | undefined>;
38
- /** Escape dismisses this layer when it is topmost. Default `true`. */
39
- escapeKey?: boolean;
38
+ /**
39
+ * Escape dismisses this layer when it is topmost. Default `true`.
40
+ *
41
+ * `false` refuses it: while this layer is on top, Escape dismisses nothing,
42
+ * as a Radix layer that prevents its `onEscapeKeyDown`. `"passthrough"`
43
+ * hands it to the layer below, for a surface that is part of the one under
44
+ * it — a submenu, whose Escape closes the whole menu.
45
+ */
46
+ escapeKey?: boolean | "passthrough";
40
47
  /** A pointer press outside dismisses. Default `true`. */
41
48
  outsidePointer?: boolean;
42
49
  /** Focus moving outside dismisses. Default `false`. */
@@ -110,13 +117,14 @@ function stopListeningIfIdle(): void {
110
117
  function onKeyDown(event: KeyboardEvent): void {
111
118
  if (event.key !== "Escape") return;
112
119
 
113
- // Topmost layer that accepts Escape — not simply the topmost layer. A
114
- // Tooltip stacked over a Popover opts out, and Escape must then reach the
115
- // Popover rather than being swallowed.
120
+ // The topmost layer decides, past the ones that pass Escape through. One
121
+ // that refuses it stops here: falling through would close the sheet behind
122
+ // a dialog that has to be answered.
116
123
  for (let i = stack.length - 1; i >= 0; i -= 1) {
117
124
  const layer = stack[i];
118
125
  if (layer === undefined) continue;
119
- if (layer.escapeKey === false) continue;
126
+ if (layer.escapeKey === "passthrough") continue;
127
+ if (layer.escapeKey === false) return;
120
128
  event.stopPropagation();
121
129
  layer.onDismiss("escape");
122
130
  return;
@@ -55,7 +55,11 @@ export interface PositionOptions {
55
55
  flip?: boolean;
56
56
  /** Slide along the cross axis to stay on screen. Default `true`. */
57
57
  shift?: boolean;
58
- /** Arrow size in px; centres the arrow and keeps it off the corners. */
58
+ /**
59
+ * Arrow size in px; centres the arrow and keeps it off the corners. It is
60
+ * also added to `offset`, so the surface stands an arrow's length away
61
+ * from the anchor (the arrow is square, so its width is its height).
62
+ */
59
63
  arrowSize?: number;
60
64
  /**
61
65
  * Mirror the placement for a right-to-left writing direction.
@@ -105,7 +109,10 @@ export function resolvePosition(
105
109
  viewport: Viewport,
106
110
  options: PositionOptions = {},
107
111
  ): Position {
108
- const offset = options.offset ?? DEFAULT_OFFSET;
112
+ // The arrow stands in the gap, so the gap starts past it — Radix's popper
113
+ // offsets by `sideOffset + arrowHeight` for the same reason. That is why
114
+ // shadcn's `sideOffset = 0` still leaves the arrow clear of the trigger.
115
+ const offset = (options.offset ?? DEFAULT_OFFSET) + (options.arrowSize ?? 0);
109
116
  const padding = options.padding ?? DEFAULT_PADDING;
110
117
  const requested = options.placement ?? "bottom";
111
118
  const [physicalSide, physicalAlign] = splitPlacement(requested);
@@ -360,6 +367,32 @@ export interface AutoPositionOptions extends PositionOptions {
360
367
  onPositioned?: (position: Position) => void;
361
368
  }
362
369
 
370
+ /**
371
+ * The surface's size as laid out, before any transform.
372
+ *
373
+ * `getBoundingClientRect()` includes transforms, and every surface opens under
374
+ * `zoom-in-95`: measured on its first frame it is 5% short, and one placed on
375
+ * the `top` side lands that much too low, over the control that opened it. A
376
+ * transform never changes layout, so the `ResizeObserver` would not correct it
377
+ * afterwards either. floating-ui reads the same two sources in the same order
378
+ * (`getCssDimensions`): the computed size, which keeps sub-pixel widths, and
379
+ * the integer offset size when the two disagree.
380
+ */
381
+ function layoutRect(element: HTMLElement): Rect {
382
+ const box = element.getBoundingClientRect();
383
+ const css = getComputedStyle(element);
384
+ let width = Number.parseFloat(css.width) || 0;
385
+ let height = Number.parseFloat(css.height) || 0;
386
+ if (
387
+ Math.round(width) !== element.offsetWidth ||
388
+ Math.round(height) !== element.offsetHeight
389
+ ) {
390
+ width = element.offsetWidth;
391
+ height = element.offsetHeight;
392
+ }
393
+ return { x: box.x, y: box.y, width, height };
394
+ }
395
+
363
396
  export interface AutoPosition {
364
397
  /** Recompute and rewrite the styles now. */
365
398
  update(): void;
@@ -390,7 +423,7 @@ export function autoPosition(
390
423
  floating.style.width = `${anchorRect.width}px`;
391
424
  }
392
425
 
393
- const floatingRect = floating.getBoundingClientRect();
426
+ const floatingRect = layoutRect(floating);
394
427
  const position = resolvePosition(
395
428
  anchorRect,
396
429
  floatingRect,
@@ -427,6 +460,10 @@ export function autoPosition(
427
460
  floating.setAttribute("data-align", position.align);
428
461
 
429
462
  const arrowEl = options.arrow?.();
463
+ // The arrow's `data-[side=…]` classes read the arrow's OWN attribute, so it
464
+ // is written here on every placement: without it none of them applied and
465
+ // the arrow sat in the text, and a flip has to turn it around.
466
+ arrowEl?.setAttribute("data-side", position.side);
430
467
  if (arrowEl && position.arrow) {
431
468
  const { x, y } = position.arrow;
432
469
  arrowEl.style.position = "absolute";
@@ -403,7 +403,8 @@ export function wireMenu(
403
403
  element: () => element,
404
404
  exclude: () => [trigger, panel],
405
405
  onDismiss: () => closeSubmenusFrom(0),
406
- escapeKey: false,
406
+ // Escape in a submenu closes the whole menu, as Radix's does.
407
+ escapeKey: "passthrough",
407
408
  });
408
409
 
409
410
  const inner = wireMenu(element, {
@@ -63,25 +63,59 @@ export interface ModalSurfaceOptions {
63
63
  onClosed?: () => void;
64
64
  }
65
65
 
66
+ interface Armed {
67
+ readonly layer: DismissableLayer;
68
+ readonly trap: FocusTrap;
69
+ readonly restoreSiblings: () => void;
70
+ }
71
+
66
72
  interface Live {
67
73
  readonly mount: Portal;
68
74
  /** Carries `data-state`; the exit animation is watched here. */
69
75
  readonly element: HTMLElement;
70
- readonly layer: DismissableLayer;
71
- readonly trap: FocusTrap;
76
+ readonly panel: HTMLElement;
72
77
  readonly unlock: () => void;
73
- readonly restoreSiblings: () => void;
78
+ /** What makes it modal: `null` once closed, through its exit. */
79
+ armed: Armed | null;
74
80
  cancelExit: (() => void) | null;
75
81
  }
76
82
 
77
83
  export function modalSurface(options: ModalSurfaceOptions): void {
78
84
  let live: Live | null = null;
79
85
 
86
+ function arm(host: HTMLElement, panel: HTMLElement): Armed {
87
+ const restoreSiblings = hideSiblingsFrom(host);
88
+ const trap = focusTrap(panel, {
89
+ initialFocus: () => options.initialFocus?.(panel) ?? null,
90
+ returnFocus: options.returnFocus,
91
+ });
92
+ const layer = dismissable({
93
+ element: () => panel,
94
+ onDismiss: options.onClose,
95
+ escapeKey: options.dismissOnEscape !== false,
96
+ outsidePointer: options.dismissOnOutside !== false,
97
+ outsideFocus: false,
98
+ });
99
+ return { layer, trap, restoreSiblings };
100
+ }
101
+
102
+ function disarm(current: Live): void {
103
+ const armed = current.armed;
104
+ if (armed === null) return;
105
+ current.armed = null;
106
+ armed.layer.remove();
107
+ armed.trap.release();
108
+ armed.restoreSiblings();
109
+ }
110
+
80
111
  function show(): void {
81
112
  if (live !== null) {
113
+ // Reopened while its exit was still playing: the same node comes
114
+ // back, and it is a modal again, not a panel the page reads through.
82
115
  live.cancelExit?.();
83
116
  live.cancelExit = null;
84
117
  live.element.setAttribute("data-state", "open");
118
+ if (live.armed === null) live.armed = arm(live.mount.host, live.panel);
85
119
  return;
86
120
  }
87
121
 
@@ -95,28 +129,13 @@ export function modalSurface(options: ModalSurfaceOptions): void {
95
129
 
96
130
  const panel = options.panel?.(element) ?? element;
97
131
  const unlock = options.lockScroll === false ? () => {} : lockScroll();
98
- const restoreSiblings = hideSiblingsFrom(mount.host);
99
-
100
- const trap = focusTrap(panel, {
101
- initialFocus: () => options.initialFocus?.(panel) ?? null,
102
- returnFocus: options.returnFocus,
103
- });
104
-
105
- const layer = dismissable({
106
- element: () => panel,
107
- onDismiss: options.onClose,
108
- escapeKey: options.dismissOnEscape !== false,
109
- outsidePointer: options.dismissOnOutside !== false,
110
- outsideFocus: false,
111
- });
112
132
 
113
133
  live = {
114
134
  mount,
115
135
  element,
116
- layer,
117
- trap,
136
+ panel,
118
137
  unlock,
119
- restoreSiblings,
138
+ armed: arm(mount.host, panel),
120
139
  cancelExit: null,
121
140
  };
122
141
  options.onOpened?.(panel);
@@ -124,11 +143,9 @@ export function modalSurface(options: ModalSurfaceOptions): void {
124
143
 
125
144
  function hide(): void {
126
145
  const current = live;
127
- if (current === null) return;
146
+ if (current === null || current.armed === null) return;
128
147
 
129
- current.layer.remove();
130
- current.trap.release();
131
- current.restoreSiblings();
148
+ disarm(current);
132
149
  current.element.setAttribute("data-state", "closed");
133
150
  options.onClosed?.();
134
151
 
@@ -146,9 +163,7 @@ export function modalSurface(options: ModalSurfaceOptions): void {
146
163
  if (current === null) return;
147
164
  live = null;
148
165
  current.cancelExit?.();
149
- current.layer.remove();
150
- current.trap.release();
151
- current.restoreSiblings();
166
+ disarm(current);
152
167
  current.unlock();
153
168
  current.mount.close();
154
169
  }
@@ -165,35 +180,57 @@ export function modalSurface(options: ModalSurfaceOptions): void {
165
180
  });
166
181
  }
167
182
 
183
+ /** How many open modals hide each node; it is shown again at zero. */
184
+ const hiddenBy = new WeakMap<Element, number>();
185
+ /** Nodes that were already `aria-hidden` when the first modal reached them. */
186
+ const hiddenBefore = new WeakSet<Element>();
187
+
168
188
  /**
169
189
  * Hide everything except the overlay from assistive technology.
170
190
  *
171
- * Marks each sibling of the portal host, and restores exactly what was there
172
- * before — an element that was *already* `aria-hidden` for its own reasons
173
- * must stay that way after the dialog closes, so the previous value is saved
174
- * rather than the attribute simply removed.
191
+ * Marks each sibling of the portal host. Counted per node, as the
192
+ * `aria-hidden` package Radix modals use does: stacked modals hide the same
193
+ * page, and they close in any order — a confirm that closes its parent sheet
194
+ * before itself is enough — so a node is shown again only when the last
195
+ * modal hiding it lets go. A node the application had hidden itself is never
196
+ * touched.
197
+ *
198
+ * Only siblings of the host, not the whole page: a second modal hides the
199
+ * first one's host along with the page, and shows it again when it closes.
175
200
  *
176
- * Only siblings of the host, not the whole page: a second modal opening over
177
- * the first must not hide it, and it will not, because it appends its own host
178
- * after the first one and only touches what is beside it.
201
+ * The returned release runs once, however many paths reach it.
179
202
  */
180
203
  function hideSiblingsFrom(host: HTMLElement): () => void {
181
204
  const parent = host.parentElement;
182
205
  if (parent === null) return () => {};
183
206
 
184
- const saved: Array<[Element, string | null]> = [];
207
+ const hidden: Element[] = [];
185
208
  for (const sibling of parent.children) {
186
209
  if (sibling === host) continue;
187
210
  // A live region announcing outside the dialog (a toast) is deliberate.
188
211
  if (sibling.hasAttribute("data-nebula-live")) continue;
189
- saved.push([sibling, sibling.getAttribute("aria-hidden")]);
190
- sibling.setAttribute("aria-hidden", "true");
212
+ const count = (hiddenBy.get(sibling) ?? 0) + 1;
213
+ hiddenBy.set(sibling, count);
214
+ hidden.push(sibling);
215
+ const attribute = sibling.getAttribute("aria-hidden");
216
+ const alreadyHidden = attribute !== null && attribute !== "false";
217
+ if (count === 1 && alreadyHidden) hiddenBefore.add(sibling);
218
+ if (!alreadyHidden) sibling.setAttribute("aria-hidden", "true");
191
219
  }
192
220
 
221
+ let released = false;
193
222
  return (): void => {
194
- for (const [element, previous] of saved) {
195
- if (previous === null) element.removeAttribute("aria-hidden");
196
- else element.setAttribute("aria-hidden", previous);
223
+ if (released) return;
224
+ released = true;
225
+ for (const element of hidden) {
226
+ const count = (hiddenBy.get(element) ?? 1) - 1;
227
+ if (count > 0) {
228
+ hiddenBy.set(element, count);
229
+ continue;
230
+ }
231
+ hiddenBy.delete(element);
232
+ if (!hiddenBefore.has(element)) element.removeAttribute("aria-hidden");
233
+ hiddenBefore.delete(element);
197
234
  }
198
235
  };
199
236
  }
@@ -408,19 +408,22 @@ function containsKeyframes(rules: CSSRuleList, name: string): boolean {
408
408
  for (const rule of Array.from(rules)) {
409
409
  if (isKeyframesNamed(rule, name)) return true;
410
410
  // `cssRules` on a group rule (media, supports, layer); absent on others.
411
- const nested = Reflect.get(rule, "cssRules");
412
- if (
413
- nested !== null &&
414
- typeof nested === "object" &&
415
- typeof Reflect.get(nested, "length") === "number" &&
416
- containsKeyframes(nested as CSSRuleList, name)
417
- ) {
418
- return true;
419
- }
411
+ const nested: unknown = Reflect.get(rule, "cssRules");
412
+ if (isRuleList(nested) && containsKeyframes(nested, name)) return true;
420
413
  }
421
414
  return false;
422
415
  }
423
416
 
417
+ /** A `CSSRuleList`, read structurally: not every DOM exposes the class. */
418
+ function isRuleList(value: unknown): value is CSSRuleList {
419
+ return (
420
+ typeof value === "object" &&
421
+ value !== null &&
422
+ typeof Reflect.get(value, "length") === "number" &&
423
+ typeof Reflect.get(value, "item") === "function"
424
+ );
425
+ }
426
+
424
427
  /**
425
428
  * Are all the animations this element declares actually defined?
426
429
  *
@@ -26,6 +26,8 @@ export interface SettingsLayoutProps {
26
26
  title: Child;
27
27
  description?: Child;
28
28
  sections: readonly SettingsSection[];
29
+ /** The section list's accessible name. Default `"Settings sections"`. */
30
+ navLabel?: string;
29
31
  children?: Slot;
30
32
  class?: Reactive<string>;
31
33
  }
@@ -46,7 +48,7 @@ export const SettingsLayout = component<SettingsLayoutProps>((props) => {
46
48
  <div class="flex flex-col gap-8 md:flex-row md:gap-12">
47
49
  <nav
48
50
  data-slot="settings-nav"
49
- aria-label="Settings sections"
51
+ aria-label="${props.navLabel ?? "Settings sections"}"
50
52
  class="flex gap-2 overflow-x-auto md:w-48 md:shrink-0 md:flex-col md:overflow-visible"
51
53
  >
52
54
  ${props.sections.map(