@barqjs/aria 0.0.0-stage → 0.2.0-next.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 (76) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +293 -2
  3. package/package.json +347 -4
  4. package/src/breadcrumbs.tsx +296 -0
  5. package/src/button.tsx +342 -0
  6. package/src/calendar.tsx +1389 -0
  7. package/src/checkbox.tsx +570 -0
  8. package/src/collections.ts +976 -0
  9. package/src/color.ts +562 -0
  10. package/src/colorpicker.tsx +1478 -0
  11. package/src/combobox.tsx +2481 -0
  12. package/src/command.tsx +1184 -0
  13. package/src/date.ts +652 -0
  14. package/src/datefield.tsx +951 -0
  15. package/src/datepicker.tsx +556 -0
  16. package/src/dialog.tsx +890 -0
  17. package/src/disclosure.tsx +659 -0
  18. package/src/dom.ts +706 -0
  19. package/src/drawer.ts +674 -0
  20. package/src/focus.ts +1370 -0
  21. package/src/form.tsx +94 -0
  22. package/src/gridlist.tsx +563 -0
  23. package/src/i18n.ts +823 -0
  24. package/src/index.ts +1270 -0
  25. package/src/interactions/description.ts +73 -0
  26. package/src/interactions/flags.ts +35 -0
  27. package/src/interactions/focus-events.ts +218 -0
  28. package/src/interactions/focusable.ts +86 -0
  29. package/src/interactions/hover.ts +213 -0
  30. package/src/interactions/interact-outside.ts +123 -0
  31. package/src/interactions/keyboard.ts +105 -0
  32. package/src/interactions/listeners.ts +78 -0
  33. package/src/interactions/long-press.ts +160 -0
  34. package/src/interactions/modality.ts +416 -0
  35. package/src/interactions/move.ts +257 -0
  36. package/src/interactions/open-link.ts +193 -0
  37. package/src/interactions/press.ts +898 -0
  38. package/src/interactions/prevent-focus.ts +102 -0
  39. package/src/interactions/scroll-wheel.ts +43 -0
  40. package/src/interactions/text-selection.ts +77 -0
  41. package/src/interactions.ts +81 -0
  42. package/src/label.ts +128 -0
  43. package/src/link.tsx +381 -0
  44. package/src/listbox.tsx +721 -0
  45. package/src/live.ts +204 -0
  46. package/src/menu.tsx +2290 -0
  47. package/src/menubar.tsx +575 -0
  48. package/src/navigation.ts +735 -0
  49. package/src/numberfield.tsx +838 -0
  50. package/src/otp.ts +430 -0
  51. package/src/overlays.ts +1247 -0
  52. package/src/platform.ts +74 -0
  53. package/src/presence.ts +164 -0
  54. package/src/questionnaire.tsx +1712 -0
  55. package/src/radio.tsx +567 -0
  56. package/src/register-dom.ts +12 -0
  57. package/src/scroller.ts +1165 -0
  58. package/src/select.tsx +1665 -0
  59. package/src/selection.ts +1415 -0
  60. package/src/slider.tsx +1042 -0
  61. package/src/splitter.ts +1152 -0
  62. package/src/static-collection.ts +211 -0
  63. package/src/switch.tsx +186 -0
  64. package/src/table.tsx +0 -0
  65. package/src/tabs.tsx +1018 -0
  66. package/src/tag.tsx +452 -0
  67. package/src/textfield.tsx +417 -0
  68. package/src/toast.ts +658 -0
  69. package/src/toggle-input.tsx +48 -0
  70. package/src/toggle.ts +321 -0
  71. package/src/togglegroup.ts +365 -0
  72. package/src/toolbar.tsx +179 -0
  73. package/src/tooltip.tsx +657 -0
  74. package/src/utils.ts +758 -0
  75. package/src/validation.ts +447 -0
  76. package/src/virtualizer.tsx +674 -0
@@ -0,0 +1,1247 @@
1
+ /**
2
+ * Overlays: dialogs, popovers, menus, tooltips.
3
+ *
4
+ * Four problems, none of which the platform solves for a `<div>` positioned
5
+ * over the page:
6
+ *
7
+ * - Dismissal. Escape closes the TOP overlay, not every open one, and an
8
+ * interaction outside closes it only if the interaction both began and ended
9
+ * outside.
10
+ * - The rest of the page. A modal must be hidden from a screen reader, or the
11
+ * virtual cursor walks straight out of it into content the user cannot see.
12
+ * `aria-hidden` on everything else is the only mechanism that works, and it
13
+ * has to keep working as the page changes underneath.
14
+ * - Scrolling. `overflow: hidden` on the root is enough everywhere except iOS
15
+ * WebKit, which scrolls anyway in four distinct situations.
16
+ * - Position. A popover has to flip when it would go off screen, shift to stay
17
+ * inside its boundary, and cap its own height rather than overflow.
18
+ */
19
+
20
+ import {
21
+ type Accessor,
22
+ createContext,
23
+ createEffect,
24
+ getContext,
25
+ getOwner,
26
+ install,
27
+ provide,
28
+ createSignal,
29
+ untrack,
30
+ } from "@barqjs/core";
31
+ import { isServer } from "@barqjs/web";
32
+ import {
33
+ addEvent,
34
+ contains,
35
+ isScrollable,
36
+ ownerDocument,
37
+ ownerWindow,
38
+ propagationTargets,
39
+ scrollParents,
40
+ setStyle,
41
+ targetElement,
42
+ TOP_LAYER_ATTRIBUTE,
43
+ } from "./dom.ts";
44
+ import { resizeObserver } from "@barqjs/primitives/observers";
45
+
46
+ import { focusWithin } from "./interactions/focus-events.ts";
47
+ import { interactOutside } from "./interactions/interact-outside.ts";
48
+ import type { ElementRef } from "./interactions/press.ts";
49
+ import { isIOS, isWebKit } from "./platform.ts";
50
+ import {
51
+ access,
52
+ chain,
53
+ clamp,
54
+ controllable,
55
+ id,
56
+ mergeProps,
57
+ type DOMProps,
58
+ type MaybeAccessor,
59
+ } from "./utils.ts";
60
+
61
+ // ---------------------------------------------------------------------------
62
+ // Open state
63
+ // ---------------------------------------------------------------------------
64
+
65
+ /**
66
+ * Do something for as long as an overlay is open, and undo it after.
67
+ *
68
+ * `read` is where the open state and anything else that matters is READ, and
69
+ * `apply` is what is done about the answer; what `apply` returns undoes it
70
+ * before the next answer and on disposal.
71
+ *
72
+ * The two are apart on purpose. A tracked effect reads inside its own first
73
+ * run, and that run can fall in the same pass as a write made by an effect
74
+ * before it: it then sees the value from before the write and is never woken
75
+ * for the one after. An overlay opened from `onSettled` is exactly that, a
76
+ * welcome popover or a dialog restored from the URL, and it stayed closed
77
+ * while its owner's signal said open. A read made here is part of the graph,
78
+ * which is kept consistent across that pass.
79
+ */
80
+ export function followOpen<T>(read: () => T, apply: (value: T) => (() => void) | undefined): void {
81
+ // `apply` measures and reads refs as they are at that moment, on purpose:
82
+ // what it depends on is what `read` returned.
83
+ createEffect(read, (value) => untrack(() => apply(value)));
84
+ }
85
+
86
+ export interface OverlayTriggerStateOptions {
87
+ isOpen?: MaybeAccessor<boolean | undefined>;
88
+ defaultOpen?: MaybeAccessor<boolean | undefined>;
89
+ onOpenChange?: (isOpen: boolean) => void;
90
+ }
91
+
92
+ /**
93
+ * Every member is a PROPERTY rather than a method, because every one of them
94
+ * is handed on detached: `onClose={state.close}` and `onOpenChange={setOpen}`
95
+ * are the idiom this whole layer is built around. Method shorthand would
96
+ * declare a `this` that no implementation here has and no caller could keep.
97
+ */
98
+ export interface OverlayTriggerState {
99
+ isOpen: Accessor<boolean>;
100
+ setOpen: (isOpen: boolean) => void;
101
+ open: () => void;
102
+ close: () => void;
103
+ toggle: () => void;
104
+ }
105
+
106
+ /** Whether an overlay is open, controlled or not. */
107
+ export function overlayTriggerState(options: OverlayTriggerStateOptions = {}): OverlayTriggerState {
108
+ const [isOpen, setOpen] = controllable<boolean>(
109
+ () => access(options.isOpen),
110
+ () => access(options.defaultOpen) ?? false,
111
+ options.onOpenChange,
112
+ );
113
+
114
+ return {
115
+ isOpen,
116
+ setOpen,
117
+ open: () => setOpen(true),
118
+ close: () => setOpen(false),
119
+ toggle: () => setOpen(!isOpen()),
120
+ };
121
+ }
122
+
123
+ export interface OverlayTriggerOptions {
124
+ /** What the trigger opens. */
125
+ type: "dialog" | "menu" | "listbox" | "tree" | "grid";
126
+ }
127
+
128
+ export interface OverlayTriggerResult {
129
+ triggerProps: DOMProps;
130
+ overlayProps: DOMProps;
131
+ }
132
+
133
+ /**
134
+ * The trigger and the overlay it opens, wired together.
135
+ *
136
+ * `aria-haspopup` is only written for a menu and a listbox: screen readers
137
+ * announce every other value as "menu", which is worse than saying nothing.
138
+ */
139
+ export function overlayTrigger(
140
+ options: OverlayTriggerOptions,
141
+ state: OverlayTriggerState,
142
+ ): OverlayTriggerResult {
143
+ const overlayId = id();
144
+
145
+ const hasPopup =
146
+ options.type === "menu" ? true : options.type === "listbox" ? "listbox" : undefined;
147
+
148
+ return {
149
+ triggerProps: {
150
+ "aria-haspopup": hasPopup,
151
+ "aria-expanded": () => state.isOpen(),
152
+ "aria-controls": () => (state.isOpen() ? overlayId() : undefined),
153
+ onPress: () => state.toggle(),
154
+ },
155
+ overlayProps: { id: overlayId },
156
+ };
157
+ }
158
+
159
+ // ---------------------------------------------------------------------------
160
+ // Where an overlay is rendered
161
+ // ---------------------------------------------------------------------------
162
+
163
+ /**
164
+ * Where overlays below this point are portalled to.
165
+ *
166
+ * `null` means the default, which is `document.body`. A container is asked for
167
+ * rather than held, because the element it names may not exist yet when the
168
+ * provider runs — the root popover's own container is exactly that case.
169
+ */
170
+ export type PortalTarget = () => Element | null;
171
+
172
+ const PortalTargetContext = createContext<PortalTarget | null>(null);
173
+
174
+ /**
175
+ * Send every overlay below here somewhere other than the body.
176
+ *
177
+ * For an application that renders inside a shadow root, a fullscreen element,
178
+ * or a container it styles: an overlay portalled to the body would leave that
179
+ * subtree and lose the styles, the theme and the containing block with it.
180
+ */
181
+ export function providePortalTarget(target: PortalTarget | null): void {
182
+ const owner = getOwner();
183
+ if (owner !== null) install(owner, PortalTargetContext, () => target);
184
+ }
185
+
186
+ /**
187
+ * Build `children` with every overlay inside them sent to `target`.
188
+ *
189
+ * {@link providePortalTarget} installs on whatever scope is current, which is
190
+ * right in a component that owns one and wrong in one that does not: there it
191
+ * lands on the surrounding scope and the siblings read it too.
192
+ */
193
+ export function withPortalTarget(target: PortalTarget | null, children: () => unknown): unknown {
194
+ return provide(PortalTargetContext, () => target, children);
195
+ }
196
+
197
+ /** The portal target in scope, if one was provided. */
198
+ export function usePortalTarget(): PortalTarget | null {
199
+ return getContext(PortalTargetContext) ?? null;
200
+ }
201
+
202
+ /**
203
+ * The element an overlay should be portalled into.
204
+ *
205
+ * `null` on the server and before the document exists, which is the signal to
206
+ * render nothing rather than to render in the wrong place.
207
+ */
208
+ export function portalContainer(target: PortalTarget | null): Element | null {
209
+ const given = target?.() ?? null;
210
+ if (given !== null) return given;
211
+ if (isServer || typeof document === "undefined") return null;
212
+ return document.body;
213
+ }
214
+
215
+ // ---------------------------------------------------------------------------
216
+ // Dismissal
217
+ // ---------------------------------------------------------------------------
218
+
219
+ /**
220
+ * Every open overlay, innermost last.
221
+ *
222
+ * Escape and an outside press act on the last one only: a menu inside a dialog
223
+ * must close the menu, leaving the dialog open.
224
+ */
225
+ const openOverlays: ElementRef[] = [];
226
+
227
+ export interface OverlayOptions {
228
+ isOpen?: MaybeAccessor<boolean | undefined>;
229
+ onClose?: () => void;
230
+ /** Close when the user interacts outside. @default false */
231
+ isDismissable?: MaybeAccessor<boolean | undefined>;
232
+ /** Close when focus leaves. */
233
+ shouldCloseOnBlur?: MaybeAccessor<boolean | undefined>;
234
+ /** @default false */
235
+ isKeyboardDismissDisabled?: MaybeAccessor<boolean | undefined>;
236
+ /**
237
+ * Hear Escape wherever focus is, not only inside the overlay.
238
+ *
239
+ * For an overlay that never takes focus: a hover card opened from the
240
+ * keyboard leaves focus on its trigger, which is outside it, and a handler
241
+ * on the overlay alone would never hear the key.
242
+ *
243
+ * @default false
244
+ */
245
+ shouldCloseOnEscapeAnywhere?: MaybeAccessor<boolean | undefined>;
246
+ /** Veto a dismissal for an interaction with a particular element. */
247
+ shouldCloseOnInteractOutside?: (element: Element) => boolean;
248
+ /**
249
+ * What counts as INSIDE, when that is more than the overlay itself.
250
+ *
251
+ * A submenu is portalled into its root popover's container rather than into
252
+ * the body, so the whole group is one overlay as far as an outside press and
253
+ * `aria-hidden` are concerned. Without this a press on a submenu item is a
254
+ * press outside the menu that opened it.
255
+ *
256
+ * @default the overlay's own element
257
+ */
258
+ groupRef?: ElementRef;
259
+ }
260
+
261
+ export interface OverlayResult {
262
+ overlayProps: DOMProps;
263
+ underlayProps: DOMProps;
264
+ }
265
+
266
+ /** Dismissal behaviour for one overlay. */
267
+ export function overlay(options: OverlayOptions, ref: ElementRef): OverlayResult {
268
+ let lastTopMost: ElementRef | undefined;
269
+ const inside: ElementRef = options.groupRef ?? ref;
270
+
271
+ // Not on the server, where the effects of a render still run: the stack is
272
+ // module state, and a request that opened an overlay would leave it there
273
+ // for every request after.
274
+ if (!isServer) {
275
+ followOpen(
276
+ () => access(options.isOpen) === true,
277
+ (isOpen) => {
278
+ if (!isOpen || openOverlays.includes(ref)) return undefined;
279
+ openOverlays.push(ref);
280
+ return () => {
281
+ const at = openOverlays.indexOf(ref);
282
+ if (at >= 0) openOverlays.splice(at, 1);
283
+ };
284
+ },
285
+ );
286
+ }
287
+
288
+ const isTopMost = (): boolean => openOverlays[openOverlays.length - 1] === ref;
289
+
290
+ const hide = (): void => {
291
+ if (isTopMost()) options.onClose?.();
292
+ };
293
+
294
+ const shouldClose = (element: Element | null): boolean => {
295
+ if (options.shouldCloseOnInteractOutside === undefined) return true;
296
+ return element !== null && options.shouldCloseOnInteractOutside(element);
297
+ };
298
+
299
+ interactOutside({
300
+ ref: inside,
301
+ // The server has no document to hear a press on.
302
+ isDisabled: () =>
303
+ isServer || access(options.isDismissable) !== true || access(options.isOpen) !== true,
304
+ onInteractOutsideStart: (event) => {
305
+ lastTopMost = openOverlays[openOverlays.length - 1];
306
+ if (shouldClose(targetElement(event)) && isTopMost()) event.stopPropagation();
307
+ },
308
+ onInteractOutside: (event) => {
309
+ if (shouldClose(targetElement(event))) {
310
+ if (isTopMost()) event.stopPropagation();
311
+ // Only if this overlay was the top one when the press BEGAN: a press
312
+ // that started while a menu was open must not close the dialog the
313
+ // menu was in once the menu has gone.
314
+ if (lastTopMost === ref) hide();
315
+ }
316
+ lastTopMost = undefined;
317
+ },
318
+ });
319
+
320
+ const { focusWithinProps } = focusWithin({
321
+ isDisabled: () => access(options.shouldCloseOnBlur) !== true,
322
+ onBlurWithin: (event) => {
323
+ // A null `relatedTarget` means focus went to the body: switching tabs,
324
+ // or a VoiceOver quirk. An outside PRESS is handled above; this is only
325
+ // for focus genuinely moving elsewhere.
326
+ const related = event.relatedTarget as Element | null;
327
+ if (related === null) return;
328
+ if (shouldClose(related)) options.onClose?.();
329
+ },
330
+ });
331
+
332
+ const onKeyDown = (event: KeyboardEvent): void => {
333
+ if (event.key !== "Escape") return;
334
+ if (access(options.isKeyboardDismissDisabled) === true) return;
335
+ event.stopPropagation();
336
+ event.preventDefault();
337
+ hide();
338
+ };
339
+
340
+ if (!isServer) {
341
+ followOpen(
342
+ () => access(options.isOpen) === true && access(options.shouldCloseOnEscapeAnywhere) === true,
343
+ (listens) => {
344
+ if (!listens) return undefined;
345
+ const doc = ownerDocument(access(ref));
346
+ const onDocumentKeyDown = (event: KeyboardEvent): void => {
347
+ // Inside the overlay its own handler has already answered, and an
348
+ // overlay further up the stack is the one Escape belongs to.
349
+ if (event.defaultPrevented || !isTopMost()) return;
350
+ onKeyDown(event);
351
+ };
352
+ doc.addEventListener("keydown", onDocumentKeyDown);
353
+ return () => doc.removeEventListener("keydown", onDocumentKeyDown);
354
+ },
355
+ );
356
+ }
357
+
358
+ return {
359
+ overlayProps: mergeProps(focusWithinProps, { onKeyDown }),
360
+ underlayProps: {},
361
+ };
362
+ }
363
+
364
+ /**
365
+ * Close when the trigger scrolls out from under the overlay.
366
+ *
367
+ * A popover anchored to something that has scrolled away is pointing at
368
+ * nothing. Scrolling inside a field is ignored: a combobox input scrolls its
369
+ * own text when the caret moves, which is not the page moving.
370
+ */
371
+ export function closeOnScroll(options: {
372
+ triggerRef: ElementRef;
373
+ isOpen?: MaybeAccessor<boolean | undefined>;
374
+ onClose?: (() => void) | null;
375
+ }): void {
376
+ if (isServer) return;
377
+
378
+ followOpen(
379
+ () =>
380
+ access(options.isOpen) !== true || options.onClose === null
381
+ ? null
382
+ : ((access(options.triggerRef) as Element | null) ?? null),
383
+ (trigger) => {
384
+ if (trigger === null) return undefined;
385
+
386
+ const onScroll = (event: Event): void => {
387
+ const target = targetElement(event);
388
+ // A scroller elsewhere in the page does not move the trigger.
389
+ if (target !== null && !contains(target, trigger)) return;
390
+ if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement) return;
391
+ options.onClose?.();
392
+ };
393
+
394
+ return addEvent(propagationTargets(trigger), "scroll", onScroll, true);
395
+ },
396
+ );
397
+ }
398
+
399
+ // ---------------------------------------------------------------------------
400
+ // Hiding the rest of the page
401
+ // ---------------------------------------------------------------------------
402
+
403
+ const supportsInert = typeof HTMLElement !== "undefined" && "inert" in HTMLElement.prototype;
404
+
405
+ /** How many overlays are hiding each element, so nesting unwinds correctly. */
406
+ const hiddenCounts = new WeakMap<Element, number>();
407
+
408
+ interface HideObserver {
409
+ visible: Set<Element>;
410
+ hidden: Set<Element>;
411
+ observe(): void;
412
+ disconnect(): void;
413
+ }
414
+
415
+ const hideStack: HideObserver[] = [];
416
+
417
+ function isAlwaysVisible(node: Element): boolean {
418
+ const data = (node as HTMLElement).dataset;
419
+ return data?.barqLiveAnnouncer === "true" || node.hasAttribute(TOP_LAYER_ATTRIBUTE);
420
+ }
421
+
422
+ /**
423
+ * Hide everything except `targets` from assistive technology.
424
+ *
425
+ * A `MutationObserver` keeps it true as the page changes: a toast rendered
426
+ * while a dialog is open would otherwise be readable by a screen reader that
427
+ * is supposed to be trapped inside the dialog.
428
+ *
429
+ * Returns the undo.
430
+ */
431
+ export function ariaHideOutside(
432
+ targets: Element[],
433
+ options: { root?: Element; shouldUseInert?: boolean } = {},
434
+ ): () => void {
435
+ if (isServer || typeof MutationObserver === "undefined") return () => {};
436
+
437
+ const view = ownerWindow(targets[0]);
438
+ const root = options.root ?? ownerDocument(targets[0]).body;
439
+ const useInert = options.shouldUseInert === true && supportsInert;
440
+
441
+ const visible = new Set<Element>(targets);
442
+ const hidden = new Set<Element>();
443
+
444
+ const isHidden = (element: Element): boolean =>
445
+ useInert && element instanceof view.HTMLElement
446
+ ? element.inert
447
+ : element.getAttribute("aria-hidden") === "true";
448
+
449
+ const setHidden = (element: Element, value: boolean): void => {
450
+ if (useInert && element instanceof view.HTMLElement) {
451
+ element.inert = value;
452
+ return;
453
+ }
454
+ if (value) {
455
+ element.setAttribute("aria-hidden", "true");
456
+ return;
457
+ }
458
+ element.removeAttribute("aria-hidden");
459
+ if (element instanceof view.HTMLElement) element.inert = false;
460
+ };
461
+
462
+ const hide = (node: Element): void => {
463
+ const count = hiddenCounts.get(node) ?? 0;
464
+ // Already hidden by the page itself: leave it alone entirely, so the undo
465
+ // does not reveal something that was never ours.
466
+ if (isHidden(node) && count === 0) return;
467
+ if (count === 0) setHidden(node, true);
468
+ hidden.add(node);
469
+ hiddenCounts.set(node, count + 1);
470
+ };
471
+
472
+ const walk = (from: Element): void => {
473
+ for (const element of from.querySelectorAll(
474
+ `[data-barq-live-announcer], [${TOP_LAYER_ATTRIBUTE}]`,
475
+ )) {
476
+ visible.add(element);
477
+ }
478
+
479
+ const accept = (node: Element): number => {
480
+ // `aria-hidden` is inherited, so a child of a hidden node needs nothing.
481
+ // `role="row"` is the exception: iOS VoiceOver ignores `aria-hidden` on
482
+ // a row, so its cells have to be hidden individually.
483
+ if (
484
+ hidden.has(node) ||
485
+ visible.has(node) ||
486
+ (node.parentElement !== null &&
487
+ hidden.has(node.parentElement) &&
488
+ node.parentElement.getAttribute("role") !== "row")
489
+ ) {
490
+ return NodeFilter.FILTER_REJECT;
491
+ }
492
+
493
+ // An ancestor of a target stays visible, but its other children do not.
494
+ for (const target of visible) {
495
+ if (contains(node, target)) return NodeFilter.FILTER_SKIP;
496
+ }
497
+
498
+ return NodeFilter.FILTER_ACCEPT;
499
+ };
500
+
501
+ const verdict = accept(from);
502
+ if (verdict === NodeFilter.FILTER_ACCEPT) hide(from);
503
+ if (verdict === NodeFilter.FILTER_REJECT) return;
504
+
505
+ const walker = ownerDocument(from).createTreeWalker(from, NodeFilter.SHOW_ELEMENT, {
506
+ acceptNode: accept,
507
+ });
508
+ let node = walker.nextNode();
509
+ while (node !== null) {
510
+ hide(node as Element);
511
+ node = walker.nextNode();
512
+ }
513
+ };
514
+
515
+ // A previous call's observer stops watching while this one is on top.
516
+ hideStack[hideStack.length - 1]?.disconnect();
517
+
518
+ walk(root);
519
+
520
+ const observer = new MutationObserver((changes) => {
521
+ for (const change of changes) {
522
+ if (change.type !== "childList") continue;
523
+ if (!change.target.isConnected) continue;
524
+ if ([...visible, ...hidden].some((node) => contains(node, change.target))) continue;
525
+
526
+ for (const node of change.addedNodes) {
527
+ if (node instanceof Element && isAlwaysVisible(node)) visible.add(node);
528
+ else if (node instanceof Element) walk(node);
529
+ }
530
+ }
531
+ });
532
+
533
+ observer.observe(root, { childList: true, subtree: true });
534
+
535
+ const entry: HideObserver = {
536
+ visible,
537
+ hidden,
538
+ observe: () => observer.observe(root, { childList: true, subtree: true }),
539
+ disconnect: () => observer.disconnect(),
540
+ };
541
+ hideStack.push(entry);
542
+
543
+ return () => {
544
+ observer.disconnect();
545
+
546
+ for (const node of hidden) {
547
+ const count = hiddenCounts.get(node);
548
+ if (count === undefined) continue;
549
+ if (count === 1) {
550
+ setHidden(node, false);
551
+ hiddenCounts.delete(node);
552
+ } else {
553
+ hiddenCounts.set(node, count - 1);
554
+ }
555
+ }
556
+
557
+ const at = hideStack.indexOf(entry);
558
+ if (at === hideStack.length - 1) {
559
+ hideStack.pop();
560
+ hideStack[hideStack.length - 1]?.observe();
561
+ } else if (at >= 0) {
562
+ hideStack.splice(at, 1);
563
+ }
564
+ };
565
+ }
566
+
567
+ /** Keep an element visible to assistive technology inside the current overlay. */
568
+ export function keepVisible(element: Element): (() => void) | undefined {
569
+ const entry = hideStack[hideStack.length - 1];
570
+ if (entry === undefined || entry.visible.has(element)) return undefined;
571
+ entry.visible.add(element);
572
+ return () => entry.visible.delete(element);
573
+ }
574
+
575
+ // ---------------------------------------------------------------------------
576
+ // Preventing scroll
577
+ // ---------------------------------------------------------------------------
578
+
579
+ let scrollLocks = 0;
580
+ let releaseScroll: (() => void) | null = null;
581
+
582
+ /**
583
+ * Stop the page scrolling behind a modal.
584
+ *
585
+ * `overflow: hidden` on the root is enough everywhere but iOS WebKit, where
586
+ * the page still scrolls when the toolbars are collapsed, when the keyboard is
587
+ * up, when an input is focused, and when the keyboard's next/previous buttons
588
+ * move between fields. Each needs its own answer.
589
+ */
590
+ export function preventScroll(
591
+ options: { isDisabled?: MaybeAccessor<boolean | undefined> } = {},
592
+ ): void {
593
+ if (isServer) return;
594
+
595
+ followOpen(
596
+ () => access(options.isDisabled) !== true,
597
+ (locks) => {
598
+ if (!locks) return undefined;
599
+
600
+ scrollLocks++;
601
+ if (scrollLocks === 1) {
602
+ releaseScroll = isIOS() && isWebKit() ? preventScrollWebKitIOS() : preventScrollStandard();
603
+ }
604
+
605
+ return () => {
606
+ scrollLocks--;
607
+ if (scrollLocks === 0) {
608
+ releaseScroll?.();
609
+ releaseScroll = null;
610
+ }
611
+ };
612
+ },
613
+ );
614
+ }
615
+
616
+ function preventScrollStandard(): () => void {
617
+ const root = document.documentElement;
618
+ const scrollbarWidth = window.innerWidth - root.clientWidth;
619
+
620
+ // `scrollbar-gutter` where it exists, because padding does not hold a fixed
621
+ // element in place and the gutter does.
622
+ const compensate =
623
+ scrollbarWidth > 0
624
+ ? "scrollbarGutter" in root.style
625
+ ? setStyle(root, "scrollbar-gutter", "stable")
626
+ : setStyle(root, "padding-right", `${scrollbarWidth}px`)
627
+ : () => {};
628
+
629
+ return chain(compensate, setStyle(root, "overflow", "hidden"));
630
+ }
631
+
632
+ function preventScrollWebKitIOS(): () => void {
633
+ // Also what tells `scrollIntoViewport` to scroll only the scroll parents.
634
+ const restoreOverflow = setStyle(document.documentElement, "overflow", "hidden");
635
+
636
+ let scroller: Element | null = null;
637
+ let allowTouchMove = false;
638
+
639
+ const onTouchStart = (event: Event): void => {
640
+ const touch = event as TouchEvent;
641
+ const target = targetElement(touch);
642
+ if (target === null) return;
643
+
644
+ scroller = isScrollable(target) ? target : (scrollParents(target, true)[0] ?? null);
645
+ allowTouchMove = false;
646
+
647
+ // Adjusting a text selection, dragging a slider and moving a selection
648
+ // handle are all touch moves the user meant.
649
+ const selection = ownerWindow(target).getSelection();
650
+ if (selection !== null && !selection.isCollapsed && selection.containsNode(target, true)) {
651
+ allowTouchMove = true;
652
+ }
653
+ if (touch.composedPath().some((el) => el instanceof HTMLInputElement && el.type === "range")) {
654
+ allowTouchMove = true;
655
+ }
656
+ if (
657
+ target instanceof HTMLInputElement &&
658
+ target.selectionStart !== null &&
659
+ target.selectionEnd !== null &&
660
+ target.selectionStart < target.selectionEnd &&
661
+ ownerDocument(target).activeElement === target
662
+ ) {
663
+ allowTouchMove = true;
664
+ }
665
+ };
666
+
667
+ const onTouchMove = (event: Event): void => {
668
+ const touch = event as TouchEvent;
669
+ if (touch.touches.length === 2 || allowTouchMove) return;
670
+
671
+ if (scroller === null || scroller === document.documentElement || scroller === document.body) {
672
+ touch.preventDefault();
673
+ return;
674
+ }
675
+
676
+ // `overscroll-behavior: contain` should stop the chain to the page, and
677
+ // does not when the element does not actually overflow.
678
+ if (
679
+ scroller.scrollHeight === scroller.clientHeight &&
680
+ scroller.scrollWidth === scroller.clientWidth
681
+ ) {
682
+ touch.preventDefault();
683
+ }
684
+ };
685
+
686
+ // Injected as a stylesheet because iOS 26 requires it to be in effect before
687
+ // the touchstart, which a property set in the handler is not.
688
+ const style = document.createElement("style");
689
+ style.textContent = "@layer{*{overscroll-behavior:contain}}";
690
+ document.head.prepend(style);
691
+
692
+ const removeEvents = chain(
693
+ addEvent(document, "touchstart", onTouchStart, { passive: false, capture: true }),
694
+ addEvent(document, "touchmove", onTouchMove, { passive: false, capture: true }),
695
+ );
696
+
697
+ return () => {
698
+ restoreOverflow();
699
+ removeEvents();
700
+ style.remove();
701
+ };
702
+ }
703
+
704
+ // ---------------------------------------------------------------------------
705
+ // Positioning
706
+ // ---------------------------------------------------------------------------
707
+
708
+ export type Placement =
709
+ | "top"
710
+ | "top start"
711
+ | "top end"
712
+ | "bottom"
713
+ | "bottom start"
714
+ | "bottom end"
715
+ | "left"
716
+ | "left top"
717
+ | "left bottom"
718
+ | "right"
719
+ | "right top"
720
+ | "right bottom"
721
+ | "start"
722
+ | "start top"
723
+ | "start bottom"
724
+ | "end"
725
+ | "end top"
726
+ | "end bottom";
727
+
728
+ export type Axis = "top" | "bottom" | "left" | "right";
729
+
730
+ /** Which edge of the trigger an overlay hangs off, as Radix and Base UI name it. */
731
+ export type Side = "top" | "right" | "bottom" | "left" | "inline-start" | "inline-end";
732
+
733
+ /** Where along that edge it sits. */
734
+ export type Align = "start" | "center" | "end";
735
+
736
+ /**
737
+ * The {@link Placement} a side and an alignment name.
738
+ *
739
+ * Two vocabularies for one position: `side="bottom" align="start"` is
740
+ * `"bottom start"`, and `side="right" align="end"` is `"right bottom"`, because
741
+ * a placement names the cross axis by the edge it lines up with.
742
+ */
743
+ export function placementFor(side: Side, align: Align = "center"): Placement {
744
+ const main = side === "inline-start" ? "start" : side === "inline-end" ? "end" : side;
745
+ if (align === "center") return main;
746
+ if (main === "top" || main === "bottom") return `${main} ${align}`;
747
+ return `${main} ${align === "start" ? "top" : "bottom"}`;
748
+ }
749
+
750
+ /** The alignment a {@link Placement} asks for, in the other vocabulary. */
751
+ export function alignOf(placement: Placement): Align {
752
+ const cross = placement.split(" ")[1];
753
+ if (cross === "start" || cross === "top") return "start";
754
+ if (cross === "end" || cross === "bottom") return "end";
755
+ return "center";
756
+ }
757
+
758
+ export interface PositionOptions {
759
+ /** The element the overlay is anchored to. */
760
+ targetRef: ElementRef;
761
+ /**
762
+ * A box in client coordinates to place against, instead of the target's own.
763
+ *
764
+ * A context menu is anchored to the point the pointer was at, which is not
765
+ * an element and has no box to measure. `targetRef` stays whatever that
766
+ * point was inside, so scrolling the region away still closes the overlay
767
+ * and a resize there still re-places it.
768
+ */
769
+ targetRect?: MaybeAccessor<AnchorRect | null | undefined>;
770
+ /** The overlay itself. */
771
+ overlayRef: ElementRef;
772
+ /** What the overlay must stay inside. @default the viewport */
773
+ boundaryRef?: ElementRef;
774
+ /** Which side, and how the cross axis aligns. @default "bottom" */
775
+ placement?: MaybeAccessor<Placement | undefined>;
776
+ /** Distance from the target, along the main axis. @default 0 */
777
+ offset?: MaybeAccessor<number | undefined>;
778
+ /** Distance along the cross axis. @default 0 */
779
+ crossOffset?: MaybeAccessor<number | undefined>;
780
+ /** Flip to the opposite side when there is no room. @default true */
781
+ shouldFlip?: MaybeAccessor<boolean | undefined>;
782
+ /** Keep this far from the boundary's edges. @default 12 */
783
+ containerPadding?: MaybeAccessor<number | undefined>;
784
+ /** The arrow element, so it can be centred on the target. */
785
+ arrowRef?: ElementRef;
786
+ isOpen?: MaybeAccessor<boolean | undefined>;
787
+ onClose?: () => void;
788
+ /** Text direction, for `start` and `end` placements. @default "ltr" */
789
+ direction?: MaybeAccessor<"ltr" | "rtl" | undefined>;
790
+ }
791
+
792
+ export interface PositionResult {
793
+ /** Style for the overlay: absolute position and a maximum height. */
794
+ overlayProps: DOMProps;
795
+ /** Style for the arrow: its offset along the cross axis. */
796
+ arrowProps: DOMProps;
797
+ /** Where the overlay ended up, which may not be where it was asked to go. */
798
+ placement: Accessor<Axis>;
799
+ /** Re-measure and re-place. */
800
+ update(): void;
801
+ }
802
+
803
+ /** A box in client coordinates: what an overlay is placed against. */
804
+ export interface AnchorRect {
805
+ top: number;
806
+ left: number;
807
+ width: number;
808
+ height: number;
809
+ }
810
+
811
+ type Box = AnchorRect;
812
+
813
+ const OPPOSITE: Record<Axis, Axis> = {
814
+ top: "bottom",
815
+ bottom: "top",
816
+ left: "right",
817
+ right: "left",
818
+ };
819
+
820
+ function resolveAxis(placement: Placement, direction: "ltr" | "rtl"): [Axis, string] {
821
+ const [side, align = "center"] = placement.split(" ") as [string, string?];
822
+ if (side === "start") return [direction === "rtl" ? "right" : "left", align];
823
+ if (side === "end") return [direction === "rtl" ? "left" : "right", align];
824
+ // `start` and `end` under or over a trigger are its inline edges, so they
825
+ // trade places with the text direction.
826
+ if (direction === "rtl" && (side === "top" || side === "bottom")) {
827
+ return [side, align === "start" ? "end" : align === "end" ? "start" : align];
828
+ }
829
+ return [side as Axis, align];
830
+ }
831
+
832
+ function boxOf(element: Element): Box {
833
+ const rect = element.getBoundingClientRect();
834
+ return { top: rect.top, left: rect.left, width: rect.width, height: rect.height };
835
+ }
836
+
837
+ /**
838
+ * Width and height before any transform.
839
+ *
840
+ * `getBoundingClientRect` reports what is PAINTED, which for anything mid-
841
+ * animation is the wrong number to place it by.
842
+ */
843
+ function layoutSize(element: Element): { width: number; height: number } {
844
+ const html = element as HTMLElement;
845
+ return html.offsetWidth > 0 || html.offsetHeight > 0
846
+ ? { width: html.offsetWidth, height: html.offsetHeight }
847
+ : boxOf(element);
848
+ }
849
+
850
+ function place(
851
+ target: Box,
852
+ panel: Box,
853
+ axis: Axis,
854
+ align: string,
855
+ offset: number,
856
+ cross: number,
857
+ ): {
858
+ top: number;
859
+ left: number;
860
+ } {
861
+ let top = 0;
862
+ let left = 0;
863
+
864
+ if (axis === "top" || axis === "bottom") {
865
+ top = axis === "top" ? target.top - panel.height - offset : target.top + target.height + offset;
866
+ if (align === "start") left = target.left;
867
+ else if (align === "end") left = target.left + target.width - panel.width;
868
+ else left = target.left + target.width / 2 - panel.width / 2;
869
+ left += cross;
870
+ } else {
871
+ left =
872
+ axis === "left" ? target.left - panel.width - offset : target.left + target.width + offset;
873
+ if (align === "top" || align === "start") top = target.top;
874
+ else if (align === "bottom" || align === "end") top = target.top + target.height - panel.height;
875
+ else top = target.top + target.height / 2 - panel.height / 2;
876
+ top += cross;
877
+ }
878
+
879
+ return { top, left };
880
+ }
881
+
882
+ function fits(
883
+ position: { top: number; left: number },
884
+ panel: Box,
885
+ boundary: Box,
886
+ padding: number,
887
+ ): boolean {
888
+ return (
889
+ position.top >= boundary.top + padding &&
890
+ position.left >= boundary.left + padding &&
891
+ position.top + panel.height <= boundary.top + boundary.height - padding &&
892
+ position.left + panel.width <= boundary.left + boundary.width - padding
893
+ );
894
+ }
895
+
896
+ /**
897
+ * Place an overlay next to its trigger.
898
+ *
899
+ * The order is: try the requested side; flip to the opposite side if it does
900
+ * not fit and flipping is allowed; then shift along the cross axis to stay
901
+ * inside the boundary; then cap the height to what is left. Shifting after
902
+ * flipping rather than instead of it is what keeps a popover pointing at its
903
+ * trigger rather than sliding across the screen.
904
+ */
905
+ export function overlayPosition(options: PositionOptions): PositionResult {
906
+ const [position, setPosition] = createSignal<{
907
+ top: number;
908
+ left: number;
909
+ maxHeight: number;
910
+ maxWidth: number;
911
+ targetWidth: number;
912
+ targetHeight: number;
913
+ originX: number;
914
+ originY: number;
915
+ }>({
916
+ top: 0,
917
+ left: 0,
918
+ maxHeight: Number.POSITIVE_INFINITY,
919
+ maxWidth: Number.POSITIVE_INFINITY,
920
+ targetWidth: 0,
921
+ targetHeight: 0,
922
+ originX: 0,
923
+ originY: 0,
924
+ });
925
+ const [arrowOffset, setArrowOffset] = createSignal<number | undefined>(undefined);
926
+ const [resolvedAxis, setResolvedAxis] = createSignal<Axis>("bottom");
927
+
928
+ const update = (): void => {
929
+ const target = access(options.targetRef) ?? null;
930
+ const rect = access(options.targetRect) ?? null;
931
+ const element = access(options.overlayRef) as Element | null;
932
+ if (element === null || access(options.isOpen) === false) return;
933
+ const targetBox = rect ?? (target === null ? null : boxOf(target));
934
+ if (targetBox === null) return;
935
+
936
+ const boundaryElement = access(options.boundaryRef ?? undefined) as Element | null;
937
+ const view = ownerWindow(element);
938
+ const boundary: Box =
939
+ boundaryElement !== null && boundaryElement !== undefined
940
+ ? boxOf(boundaryElement)
941
+ : { top: 0, left: 0, width: view.innerWidth, height: view.innerHeight };
942
+
943
+ // The overlay's LAYOUT size, not its painted one. Every overlay here enters
944
+ // with `zoom-in-95`, so the first measurement caught it at 95% — a 288px
945
+ // popover measured 274 and was centred on that, then finished its animation
946
+ // 7px off its trigger and stayed there. A transform on the thing being
947
+ // placed must not decide where it goes.
948
+ const overlayBox = { top: 0, left: 0, ...layoutSize(element) };
949
+ const offset = access(options.offset) ?? 0;
950
+ const cross = access(options.crossOffset) ?? 0;
951
+ const padding = access(options.containerPadding) ?? 12;
952
+ const direction = access(options.direction) ?? "ltr";
953
+
954
+ const [start, align] = resolveAxis(access(options.placement) ?? "bottom", direction);
955
+ let axis = start;
956
+ let placed = place(targetBox, overlayBox, axis, align, offset, cross);
957
+
958
+ if (!fits(placed, overlayBox, boundary, padding) && access(options.shouldFlip) !== false) {
959
+ const flipped = place(targetBox, overlayBox, OPPOSITE[axis], align, offset, cross);
960
+ if (fits(flipped, overlayBox, boundary, padding)) {
961
+ axis = OPPOSITE[axis];
962
+ placed = flipped;
963
+ }
964
+ }
965
+
966
+ // Shift along the cross axis, never the main one: moving along the main
967
+ // axis would detach the overlay from its trigger.
968
+ if (axis === "top" || axis === "bottom") {
969
+ placed.left = Math.min(
970
+ Math.max(placed.left, boundary.left + padding),
971
+ boundary.left + boundary.width - overlayBox.width - padding,
972
+ );
973
+ } else {
974
+ placed.top = Math.min(
975
+ Math.max(placed.top, boundary.top + padding),
976
+ boundary.top + boundary.height - overlayBox.height - padding,
977
+ );
978
+ }
979
+
980
+ const maxHeight =
981
+ axis === "top"
982
+ ? targetBox.top - offset - boundary.top - padding
983
+ : axis === "bottom"
984
+ ? boundary.top + boundary.height - padding - (targetBox.top + targetBox.height + offset)
985
+ : boundary.height - padding * 2;
986
+
987
+ // The same question along the other axis. A menu placed to the RIGHT has
988
+ // the space between its trigger and the boundary edge to grow into, and a
989
+ // popup asked to fill the available width has no other way to know it: the
990
+ // overlay is portalled to the body, so a percentage resolves against the
991
+ // page rather than against anything to do with the trigger.
992
+ const maxWidth =
993
+ axis === "left"
994
+ ? targetBox.left - offset - boundary.left - padding
995
+ : axis === "right"
996
+ ? boundary.left + boundary.width - padding - (targetBox.left + targetBox.width + offset)
997
+ : boundary.width - padding * 2;
998
+
999
+ // Where the overlay grows FROM: the point on its own edge nearest the
1000
+ // trigger, so a scale animation appears to come out of the control that
1001
+ // opened it rather than out of the overlay's own middle. After a cross-axis
1002
+ // shift the two are no longer aligned, which is why this is measured from
1003
+ // the trigger's centre and not from the overlay's.
1004
+ const originX =
1005
+ axis === "right"
1006
+ ? 0
1007
+ : axis === "left"
1008
+ ? overlayBox.width
1009
+ : clamp(targetBox.left + targetBox.width / 2 - placed.left, 0, overlayBox.width);
1010
+ const originY =
1011
+ axis === "bottom"
1012
+ ? 0
1013
+ : axis === "top"
1014
+ ? overlayBox.height
1015
+ : clamp(targetBox.top + targetBox.height / 2 - placed.top, 0, overlayBox.height);
1016
+
1017
+ // The overlay is positioned relative to the page, so the scroll offset is
1018
+ // part of the answer.
1019
+ setPosition({
1020
+ top: placed.top + view.scrollY,
1021
+ left: placed.left + view.scrollX,
1022
+ maxHeight: Math.max(0, maxHeight),
1023
+ maxWidth: Math.max(0, maxWidth),
1024
+ targetWidth: targetBox.width,
1025
+ targetHeight: targetBox.height,
1026
+ originX,
1027
+ originY,
1028
+ });
1029
+ setResolvedAxis(axis);
1030
+
1031
+ const arrow = access(options.arrowRef ?? undefined) as Element | null;
1032
+ if (arrow !== null && arrow !== undefined) {
1033
+ // The same reason, and one more: an arrow is a rotated square, so
1034
+ // `getBoundingClientRect` reports the box the rotation sweeps out — 14.1px
1035
+ // for a 10px arrow — which centred it 2px off its trigger.
1036
+ const arrowBox = layoutSize(arrow);
1037
+ // Centred on the TARGET, not on the overlay: after a shift the two are
1038
+ // no longer aligned, and the arrow has to keep pointing at the trigger.
1039
+ if (axis === "top" || axis === "bottom") {
1040
+ const centre = targetBox.left + targetBox.width / 2 - placed.left;
1041
+ setArrowOffset(
1042
+ Math.min(Math.max(centre - arrowBox.width / 2, 0), overlayBox.width - arrowBox.width),
1043
+ );
1044
+ } else {
1045
+ const centre = targetBox.top + targetBox.height / 2 - placed.top;
1046
+ setArrowOffset(
1047
+ Math.min(Math.max(centre - arrowBox.height / 2, 0), overlayBox.height - arrowBox.height),
1048
+ );
1049
+ }
1050
+ }
1051
+ };
1052
+
1053
+ if (!isServer) {
1054
+ const onChange = (): void => update();
1055
+ const whileOpen = (ref: ElementRef): Element | null =>
1056
+ access(options.isOpen) === false ? null : (access(ref) as Element | null);
1057
+
1058
+ // The FIRST measurement is taken the moment the ref resolves, which is
1059
+ // before the browser has laid the overlay out: a popover measured 275px
1060
+ // wide, was centred on that, and then rendered at 288px, sitting 7px off
1061
+ // its trigger until something else forced a resize. Observing both boxes
1062
+ // re-places it once the real sizes exist, and again whenever the content
1063
+ // grows.
1064
+ resizeObserver(() => whileOpen(options.targetRef), onChange);
1065
+ resizeObserver(() => whileOpen(options.overlayRef), onChange);
1066
+
1067
+ followOpen(
1068
+ // Everything the placement is computed from, so it is recomputed when the
1069
+ // refs resolve and whenever one of the answers changes. A fresh array
1070
+ // each time: any of them moving is a reason to place again.
1071
+ () =>
1072
+ access(options.isOpen) === false
1073
+ ? null
1074
+ : [
1075
+ access(options.targetRef),
1076
+ access(options.targetRect),
1077
+ access(options.overlayRef),
1078
+ access(options.boundaryRef ?? undefined),
1079
+ access(options.arrowRef ?? undefined),
1080
+ access(options.placement),
1081
+ access(options.offset),
1082
+ access(options.crossOffset),
1083
+ access(options.shouldFlip),
1084
+ access(options.containerPadding),
1085
+ access(options.direction),
1086
+ ],
1087
+ (measured) => {
1088
+ if (measured === null) return undefined;
1089
+ update();
1090
+
1091
+ const view = window;
1092
+ view.addEventListener("resize", onChange);
1093
+ view.addEventListener("scroll", onChange, true);
1094
+
1095
+ return () => {
1096
+ view.removeEventListener("resize", onChange);
1097
+ view.removeEventListener("scroll", onChange, true);
1098
+ };
1099
+ },
1100
+ );
1101
+ }
1102
+
1103
+ closeOnScroll({
1104
+ triggerRef: options.targetRef,
1105
+ isOpen: options.isOpen,
1106
+ onClose: options.onClose ?? null,
1107
+ });
1108
+
1109
+ return {
1110
+ overlayProps: {
1111
+ style: () => {
1112
+ const current = position();
1113
+ return {
1114
+ position: "absolute",
1115
+ top: `${current.top}px`,
1116
+ left: `${current.left}px`,
1117
+ // On the POSITIONER, which is the positioned element. A popup's own
1118
+ // `z-index` does nothing, because the popup is static — so an overlay
1119
+ // portalled to the body painted in document order and lost to any
1120
+ // page chrome that had a stacking context of its own. Measured on the
1121
+ // gallery: a picker's menu opened underneath the card that owns it.
1122
+ // 50 is what Radix and Base UI both put on theirs.
1123
+ zIndex: 50,
1124
+ maxHeight: Number.isFinite(current.maxHeight) ? `${current.maxHeight}px` : undefined,
1125
+ // What the trigger measures, for an overlay that wants to match it.
1126
+ // A listbox under a combobox is the case: `width: 100%` resolves
1127
+ // against the PORTAL container, which is the body, so a popover asked
1128
+ // to be as wide as its trigger came out as wide as the page.
1129
+ "--barq-trigger-width": `${current.targetWidth}px`,
1130
+ "--barq-trigger-height": `${current.targetHeight}px`,
1131
+ // And what the overlay has to grow into, for one that sizes itself
1132
+ // rather than its trigger. `max-height` above is the same number,
1133
+ // applied; this is the number, for a rule that wants to compute with
1134
+ // it — `w-[calc(var(--available-width)-1.5rem)]` is shadcn's.
1135
+ //
1136
+ // Left UNSET until there is a measurement rather than defaulted to
1137
+ // something plausible: an undefined `var()` makes the declaration
1138
+ // invalid at computed-value time, so the rule reading it falls back
1139
+ // to `width: auto`, which is what an unmeasured overlay should be. A
1140
+ // stand-in number would size it wrongly and look deliberate.
1141
+ ...(Number.isFinite(current.maxWidth)
1142
+ ? { "--barq-available-width": `${current.maxWidth}px` }
1143
+ : {}),
1144
+ ...(Number.isFinite(current.maxHeight)
1145
+ ? { "--barq-available-height": `${current.maxHeight}px` }
1146
+ : {}),
1147
+ "--barq-transform-origin": `${current.originX}px ${current.originY}px`,
1148
+ };
1149
+ },
1150
+ },
1151
+ arrowProps: {
1152
+ style: () => {
1153
+ const offset = arrowOffset();
1154
+ if (offset === undefined) return {};
1155
+ const axis = resolvedAxis();
1156
+ return axis === "top" || axis === "bottom"
1157
+ ? { position: "absolute", left: `${offset}px` }
1158
+ : { position: "absolute", top: `${offset}px` };
1159
+ },
1160
+ "data-placement": resolvedAxis,
1161
+ },
1162
+ placement: resolvedAxis,
1163
+ update,
1164
+ };
1165
+ }
1166
+
1167
+ // ---------------------------------------------------------------------------
1168
+ // Modal
1169
+ // ---------------------------------------------------------------------------
1170
+
1171
+ export interface ModalOverlayOptions extends OverlayOptions {
1172
+ /** Let the page scroll behind the modal. @default false */
1173
+ isScrollDisabled?: MaybeAccessor<boolean | undefined>;
1174
+ /** Nothing outside is hidden from assistive technology, and it is not marked modal. */
1175
+ isNonModal?: MaybeAccessor<boolean | undefined>;
1176
+ }
1177
+
1178
+ export interface ModalOverlayResult extends OverlayResult {
1179
+ modalProps: DOMProps;
1180
+ }
1181
+
1182
+ /**
1183
+ * A modal: the page behind it is inert, unscrollable, and invisible to a
1184
+ * screen reader.
1185
+ */
1186
+ export function modalOverlay(
1187
+ options: ModalOverlayOptions,
1188
+ state: OverlayTriggerState,
1189
+ ref: ElementRef,
1190
+ ): ModalOverlayResult {
1191
+ const { overlayProps, underlayProps } = overlay(
1192
+ { ...options, isOpen: state.isOpen, onClose: state.close },
1193
+ ref,
1194
+ );
1195
+
1196
+ preventScroll({
1197
+ isDisabled: () => !state.isOpen() || access(options.isScrollDisabled) === true,
1198
+ });
1199
+
1200
+ followOpen(
1201
+ () =>
1202
+ state.isOpen() && access(options.isNonModal) !== true
1203
+ ? ((access(ref) as Element | null) ?? null)
1204
+ : null,
1205
+ (element) => (element === null ? undefined : ariaHideOutside([element])),
1206
+ );
1207
+
1208
+ return {
1209
+ modalProps: { "data-barq-modal": () => access(options.isNonModal) !== true || undefined },
1210
+ overlayProps,
1211
+ underlayProps,
1212
+ };
1213
+ }
1214
+
1215
+ /**
1216
+ * A button that closes the overlay, rendered at its end and visible only to a
1217
+ * screen reader.
1218
+ *
1219
+ * iOS VoiceOver has no way out of a popover otherwise: the user swipes to the
1220
+ * last element and the next swipe leaves the overlay without closing it.
1221
+ */
1222
+ export function dismissButtonProps(onDismiss: () => void): DOMProps {
1223
+ return {
1224
+ tabIndex: -1,
1225
+ "aria-label": "Dismiss",
1226
+ style: {
1227
+ width: "1px",
1228
+ height: "1px",
1229
+ position: "absolute",
1230
+ overflow: "hidden",
1231
+ clip: "rect(0 0 0 0)",
1232
+ clipPath: "inset(50%)",
1233
+ whiteSpace: "nowrap",
1234
+ border: "0",
1235
+ padding: "0",
1236
+ margin: "-1px",
1237
+ },
1238
+ onClick: onDismiss,
1239
+ };
1240
+ }
1241
+
1242
+ export { TOP_LAYER_ATTRIBUTE };
1243
+
1244
+ /** Mark a subtree as being above every overlay: a toast region. */
1245
+ export function topLayerProps(): DOMProps {
1246
+ return { [TOP_LAYER_ATTRIBUTE]: true };
1247
+ }