@zeyos/zx 4.4.0 → 5.2.0

package/src/core/messages.js

@@ -0,0 +1,427 @@
+// @ts-check
+/**
+ * The library's default English catalogue: every message key a component resolves through
+ * `msg()`, mapped to the English text it shows when nothing else answers.
+ *
+ * `Component#msg()` asks, in order, the instance's own `msg` option, the host translator installed
+ * with `setTranslator()`, the component class's built-in `msg` defaults, this catalogue, and only
+ * then gives the key back. `translate()` asks the translator and then this catalogue. A host
+ * starting a locale copies this object and translates the values; keys are `component.key`,
+ * placeholders are `%1`, `%2`, … in the order the component passes its arguments.
+ *
+ * `tests/unit/messages.test.js` scans `src/` for every key a component asks for and fails when one
+ * has no entry here, or when an entry disagrees with the English fallback written beside the call.
+ * Three keys are deliberately absent, because something other than English must win when the
+ * translator has no answer: `tree.empty` and `finder.empty` fall back to the component's
+ * `emptyText` option, and `priority.medium` is probed before the older `priority.normal`.
+ */
+export const defaultMessages = Object.freeze({
+  'activityItem.actions': 'Actions for %1',
+  'activityItem.attachments': 'Attachments',
+  'activityItem.failed': 'Failed',
+  'activityItem.label': 'Activity',
+  'activityItem.metadata': 'Activity metadata',
+  'activityItem.pending': 'Sending…',
+  'activityItem.untitled': 'activity',
+
+  'appRail.subNavigation': '%1 sub-navigation',
+
+  'appSidebar.expand': 'Expand application sidebar',
+  'appSidebar.itemBadge': '%1 (%2)',
+  'appSidebar.minimize': 'Minimize application sidebar',
+  'appSidebar.presentation': 'Navigation layout',
+  'appSidebar.presentationCollapsed': 'Both menus collapsed',
+  'appSidebar.presentationCompact': 'Module menu collapsed',
+  'appSidebar.presentationExpanded': 'Both menus expanded',
+
+  'breadcrumb.label': 'Breadcrumb',
+  'breadcrumb.more': 'Show hidden levels',
+
+  'calendar.agenda': 'Agenda',
+  'calendar.allDay': 'All day',
+  'calendar.day': 'Day',
+  'calendar.dayEvent': '%1, %2 event',
+  'calendar.dayEvents': '%1, %2 events',
+  'calendar.editCancelled': 'Calendar edit cancelled.',
+  'calendar.editCommitted': '%1 updated.',
+  'calendar.editPreview': '%1, %2 to %3',
+  'calendar.label': 'Calendar',
+  'calendar.loading': 'Loading calendar…',
+  'calendar.month': 'Month',
+  'calendar.more': '+%1 more',
+  'calendar.moveStarted': 'Moving %1. Use arrow keys, Space to drop, or Escape to cancel.',
+  'calendar.new': 'New',
+  'calendar.next': 'Next period',
+  'calendar.noEvents': 'No events',
+  'calendar.previous': 'Previous period',
+  'calendar.resize': 'Resize %1',
+  'calendar.resizeStarted': 'Resizing %1. Use arrow keys, Space to drop, or Escape to cancel.',
+  'calendar.today': 'Today',
+  'calendar.viewSwitch': 'Calendar view',
+  'calendar.week': 'Week',
+  'calendar.weekNumber': 'Week %1',
+  'calendar.year': 'Year',
+
+  'card.actions': 'Card actions',
+
+  'cardView.groupEmpty': 'No records in this group.',
+  'cardView.label': 'Card view',
+  'cardView.sort': 'Sort',
+  'cardView.sortAscending': '%1 (ascending)',
+  'cardView.sortCards': 'Sort cards',
+  'cardView.sortDescending': '%1 (descending)',
+  'cardView.ungrouped': 'Ungrouped',
+  'cardView.unsorted': 'Unsorted',
+
+  'checklist.empty': 'No matches',
+  'checklist.label': 'Checklist',
+  'checklist.search': 'Search',
+
+  'dataFilter.all': 'All',
+  'dataFilter.clear': 'Clear',
+
+  'datePicker.calendar': 'Calendar',
+  'datePicker.chooseMonthYear': 'Choose month and year, %1',
+  'datePicker.nextMonth': 'Next month',
+  'datePicker.nextYear': 'Next year',
+  'datePicker.previousMonth': 'Previous month',
+  'datePicker.previousYear': 'Previous year',
+  'datePicker.week': 'Week %1',
+  'datePicker.weekNumber': 'Week number',
+
+  'daterange.choose': 'Choose date range',
+  'daterange.clear': 'Clear date range',
+  'daterange.day.end': 'range end',
+  'daterange.day.middle': 'in selected range',
+  'daterange.day.start': 'range start',
+  'daterange.label': 'Date range',
+  'daterange.nextMonth': 'Next month',
+  'daterange.night': '1 night',
+  'daterange.nights': '%1 nights',
+  'daterange.preset.last30': 'Last 30 days',
+  'daterange.preset.last7': 'Last 7 days',
+  'daterange.preset.lastMonth': 'Last month',
+  'daterange.preset.thisMonth': 'This month',
+  'daterange.preset.thisQuarter': 'This quarter',
+  'daterange.preset.thisYear': 'This year',
+  'daterange.preset.today': 'Today',
+  'daterange.preset.yesterday': 'Yesterday',
+  'daterange.presets': 'Date range presets',
+  'daterange.previousMonth': 'Previous month',
+  'daterange.status.empty': 'No date range selected',
+  'daterange.status.start': '%1 selected, choose an end date',
+  'daterange.week': 'Week %1',
+  'daterange.weekNumber': 'Week number',
+
+  'dialog.cancel': 'Cancel',
+  'dialog.close': 'Close',
+  'dialog.ok': 'OK',
+  'dialog.promptValue': 'Prompt value',
+  'dialog.typeToConfirm': 'Type %1 to confirm',
+
+  'field.float': 'Enter a valid number.',
+  'field.int': 'Enter a whole number.',
+  'field.unknown': 'Unknown field type: %1',
+
+  'filter.addFilter': 'Add filter',
+  'filter.addGroup': 'Add group',
+  'filter.addSubgroup': 'Add subgroup',
+  'filter.and': 'and',
+  'filter.apply': 'Apply filters',
+  'filter.booleanFalse': 'False',
+  'filter.booleanTrue': 'True',
+  'filter.choose': 'Choose…',
+  'filter.chooseField': 'Choose a field…',
+  'filter.chooseOperator': 'Choose an operator…',
+  'filter.choosePart': 'Choose %1…',
+  'filter.clear': 'Clear',
+  'filter.commaSeparated': 'Comma-separated values',
+  'filter.conditionNoun': 'Filter',
+  'filter.conditions': 'conditions',
+  'filter.field': 'Filter field',
+  'filter.fieldValue': '%1 value',
+  'filter.fieldValueAt': '%1 value %2',
+  'filter.filterNoun': 'filter',
+  'filter.groupLogic': 'Group filter logic',
+  'filter.groupNoun': 'Filter group',
+  'filter.inThisGroup': 'in this group',
+  'filter.matchAll': 'Match all',
+  'filter.matchAllConditions': 'Match all conditions',
+  'filter.matchAny': 'Match any',
+  'filter.matchAnyConditions': 'Match any conditions',
+  'filter.noValue': 'No value',
+  'filter.operator': 'Filter operator',
+  'filter.or': 'or',
+  'filter.relativeAmount': '%1: number of units',
+  'filter.relativeInvalid': 'Enter a whole number of days, weeks or months',
+  'filter.relativeUnit': '%1: unit',
+  'filter.remove': 'Remove %1',
+  'filter.removed': '%1 removed',
+  'filter.removeGroup': 'Remove group',
+  'filter.rootLogic': 'Root filter logic',
+  'filter.switchToAll': '%1 — switch to all',
+  'filter.switchToAny': '%1 — switch to any',
+  'filter.unavailable': 'Unavailable: %1',
+  'filter.unit.days': 'days',
+  'filter.unit.months': 'months',
+  'filter.unit.weeks': 'weeks',
+
+  'filterPanel.apply': 'Apply',
+  'filterPanel.clear': 'Clear all',
+  'filterPanel.empty': 'No filters are available here.',
+  'filterPanel.from': 'From',
+  'filterPanel.label': 'Filters',
+  'filterPanel.rangeFrom': '%1 from',
+  'filterPanel.rangeTo': '%1 to',
+  'filterPanel.to': 'To',
+  'filterPanel.unsupported': 'Unsupported filter type: %1',
+
+  'finder.loading': 'Loading…',
+  'finder.root': 'Root',
+
+  'form.float': 'Enter a valid number.',
+  'form.int': 'Enter a whole number.',
+  'form.required': 'This field is required.',
+
+  'launcher.back': 'Back to %1',
+  'launcher.close': 'Close launcher',
+  'launcher.empty': 'No results',
+  'launcher.hintBack': 'Back',
+  'launcher.hintClose': 'Close',
+  'launcher.hintMove': 'Move',
+  'launcher.hintOpen': 'Open',
+  'launcher.label': 'Launcher',
+  'launcher.loading': 'Searching…',
+  'launcher.pageEmpty': '%1, no results',
+  'launcher.pageLabel': 'Search %1',
+  'launcher.pagePlaceholder': 'Search',
+  'launcher.pageResult': '%1, 1 result',
+  'launcher.pageResults': '%1, %2 results',
+  'launcher.placeholder': 'Search applications and records',
+  'launcher.results': 'Launcher results',
+
+  'listToolbar.label': 'List controls',
+  'listToolbar.results': '%1 results',
+  'listToolbar.search': 'Search',
+  'listToolbar.toolBadge': '%1 (%2)',
+  'listToolbar.viewAuto': 'Auto',
+  'listToolbar.viewBoard': 'Board',
+  'listToolbar.viewCards': 'Cards',
+  'listToolbar.viewGallery': 'Gallery',
+  'listToolbar.viewList': 'List',
+  'listToolbar.views': 'View',
+  'listToolbar.viewTable': 'Table',
+
+  'message.close': 'Close message',
+  'message.closeTitle': 'Close',
+
+  'moduleBar.empty': 'No modules',
+  'moduleBar.filter': 'Filter modules',
+  'moduleBar.itemBadge': '%1 (%2)',
+  'moduleBar.label': 'Modules',
+  'moduleBar.more': 'All modules',
+
+  'monthPicker.chooseMonth': 'Choose month',
+  'monthPicker.nextYear': 'Next year',
+  'monthPicker.previousYear': 'Previous year',
+
+  'numberField.empty': 'Empty',
+
+  'pagination.empty': '0 of 0',
+  'pagination.label': 'Pagination',
+  'pagination.loaded': '%1 of %2',
+  'pagination.loadMore': 'Load more',
+  'pagination.next': 'Next page',
+  'pagination.page': 'Page %1',
+  'pagination.pageSize': 'Rows per page',
+  'pagination.previous': 'Previous page',
+  'pagination.summary': '%1–%2 of %3',
+
+  'panel.actions': 'Panel actions',
+  'panel.footerActions': 'Panel footer actions',
+
+  'permission.private': 'Private',
+  'permission.public': 'Public',
+
+  'priority.high': 'High',
+  'priority.highest': 'Highest',
+  'priority.low': 'Low',
+  'priority.lowest': 'Lowest',
+  'priority.none': 'No priority',
+  'priority.normal': 'Medium',
+
+  'questionnaire.counter': 'Question %1 of %2',
+  'questionnaire.edit': 'Edit',
+  'questionnaire.empty': 'There is nothing to answer.',
+  'questionnaire.next': 'Continue',
+  'questionnaire.noAnswer': 'Skipped',
+  'questionnaire.previous': 'Back',
+  'questionnaire.required': 'Choose an answer to continue.',
+  'questionnaire.requiredInput': 'Enter an answer to continue.',
+  'questionnaire.review': 'Review answers',
+  'questionnaire.reviewTitle': 'Check your answers',
+  'questionnaire.skip': 'Skip',
+  'questionnaire.submit': 'Submit',
+
+  'rating.count': '%1 ratings',
+  'rating.value': '%1 of %2',
+
+  'recordCard.actions': 'Actions for %1',
+  'recordCard.notSelected': 'Not selected',
+  'recordCard.select': 'Select %1',
+  'recordCard.selected': 'Selected',
+  'recordCard.untitled': 'record',
+
+  'recordView.fieldMoved': '%1 moved to position %2 of %3',
+  'recordView.fields': 'Fields',
+  'recordView.moveFieldDown': 'Move %1 down',
+  'recordView.moveFieldUp': 'Move %1 up',
+
+  'search.clear': 'Clear search',
+  'search.label': 'Search',
+  'search.submit': 'Submit search',
+  'search.submitTitle': 'Search',
+
+  'select.clear': 'Clear selection',
+  'select.empty': 'No matches',
+  'select.loading': 'Loading',
+  'select.none': 'No selection',
+  'select.toggle': 'Toggle options',
+
+  'sheet.resize': 'Resize sheet',
+
+  'statTile.down': 'down %1',
+  'statTile.loading': 'Loading',
+  'statTile.unchanged': 'no change',
+  'statTile.up': 'up %1',
+
+  'stepper.completed': 'Completed',
+  'stepper.counter': 'Step %1 of %2',
+  'stepper.current': 'Current step',
+  'stepper.error': 'Error',
+  'stepper.optional': 'Optional',
+
+  'tabbox.close': 'Close',
+
+  'table.collapseRow': 'Collapse %1',
+  'table.columns': 'Columns',
+  'table.empty': 'No records',
+  'table.label': 'Table',
+  'table.expandRow': 'Expand %1',
+  'table.invalid': 'Invalid value',
+  'table.more': 'Show %1 more',
+  'table.moveColumn': 'Move %1',
+  'table.moveRow': 'Move %1',
+  'table.row': 'row %1',
+  'table.selectAll': 'Select all rows',
+  'table.selectRow': 'Select %1',
+
+  'tagPicker.create': 'Create “%1”',
+  'tagPicker.empty': 'No matches',
+  'tagPicker.input': 'Add a value',
+  'tagPicker.loading': 'Loading…',
+  'tagPicker.remove': 'Remove %1',
+  'tagPicker.toggle': 'Toggle options',
+
+  'timebox.duration': 'Duration in hours and minutes',
+  'timebox.durationWithSeconds': 'Duration in hours, minutes, and seconds',
+  'timebox.hours': 'Hours',
+  'timebox.minutes': 'Minutes',
+  'timebox.seconds': 'Seconds',
+  'timebox.toggleSign': 'Toggle duration sign',
+
+  'timePicker.clock': 'Pick the time on a clock',
+  'timePicker.hour': 'Hour',
+  'timePicker.label': 'Time',
+  'timePicker.minute': 'Minute',
+  'timePicker.minutes': 'Minutes',
+  'timePicker.second': 'Second',
+  'timePicker.selectHour': 'Select the hour',
+  'timePicker.selectMinutes': 'Select the minutes',
+
+  'valueList.add': 'Add value',
+  'valueList.duplicate': 'This value already exists.',
+  'valueList.instructions': 'Press Enter to add. Focus a value and press Ctrl plus Left or Right to reorder.',
+  'valueList.invalid': 'This value is not valid.',
+  'valueList.removable': '%1. Press Delete to remove.',
+  'valueList.values': 'Values',
+
+  'viewSettings.add': 'Add',
+  'viewSettings.added': '%1 added at position %2 of %3',
+  'viewSettings.addField': 'Add %1',
+  'viewSettings.allShown': 'Every field is shown.',
+  'viewSettings.board': 'Board',
+  'viewSettings.canceled': 'Move canceled. %1 is back at position %2 of %3',
+  'viewSettings.chooseField': 'Choose a field',
+  'viewSettings.columns': 'Columns',
+  'viewSettings.dragging': '%1 picked up, position %2 of %3',
+  'viewSettings.dropped': '%1 dropped at position %2 of %3',
+  'viewSettings.emptyColumns': 'Show empty columns',
+  'viewSettings.fields': 'Fields',
+  'viewSettings.grabbed': '%1 picked up, position %2 of %3. Use the arrow keys to move it, Space to drop it, Escape to cancel.',
+  'viewSettings.group': 'Group by',
+  'viewSettings.hidden': 'Hidden (%1)',
+  'viewSettings.hiddenField': '%1 hidden',
+  'viewSettings.hide': 'Hide %1',
+  'viewSettings.instructions': 'Press Space to pick the field up, the arrow keys to move it, Space again to drop it, or Escape to cancel.',
+  'viewSettings.label': 'View settings',
+  'viewSettings.lastField': 'At least one field stays shown',
+  'viewSettings.locked': 'Always shown',
+  'viewSettings.moved': '%1 moved to position %2 of %3',
+  'viewSettings.noMatch': 'No hidden field matches “%1”.',
+  'viewSettings.none': 'None',
+  'viewSettings.reorder': 'Reorder %1',
+  'viewSettings.search': 'Find a field',
+  'viewSettings.shown': 'Shown (%1)',
+  'viewSettings.swimlanes': 'Swim lanes',
+  'viewSettings.typeBoolean': 'Checkbox',
+  'viewSettings.typeDate': 'Date',
+  'viewSettings.typeDatetime': 'Date and time',
+  'viewSettings.typeEmail': 'Email',
+  'viewSettings.typeEntity': 'Linked record',
+  'viewSettings.typeFile': 'File',
+  'viewSettings.typeImage': 'Image',
+  'viewSettings.typeMoney': 'Money',
+  'viewSettings.typeNumber': 'Number',
+  'viewSettings.typePriority': 'Priority',
+  'viewSettings.typeRating': 'Rating',
+  'viewSettings.typeSelect': 'Select',
+  'viewSettings.typeStatus': 'Status',
+  'viewSettings.typeTags': 'Tags',
+  'viewSettings.typeText': 'Text',
+  'viewSettings.typeTime': 'Time',
+  'viewSettings.typeUrl': 'URL',
+
+  'workspaceSwitcher.heading': 'Workspaces',
+  'workspaceSwitcher.label': 'Switch workspace: %1',
+  'workspaceSwitcher.labelEmpty': 'Switch workspace'
+});
+
+/**
+ * Keys renamed in 5.x, each mapped to the key it replaced. `Component#msg()` reads the old key
+ * second — after the new one, in the instance `msg` option and in the host translator alike — so a
+ * translation written against the old name keeps working for one more major version.
+ */
+export const legacyMessageKeys = Object.freeze({
+  'calendar.agenda': 'agenda',
+  'calendar.allDay': 'allDay',
+  'calendar.day': 'day',
+  'calendar.editCancelled': 'editCancelled',
+  'calendar.editCommitted': 'editCommitted',
+  'calendar.editPreview': 'editPreview',
+  'calendar.label': 'calendar',
+  'calendar.loading': 'loading',
+  'calendar.month': 'month',
+  'calendar.more': 'more',
+  'calendar.moveStarted': 'moveStarted',
+  'calendar.new': 'new',
+  'calendar.next': 'next',
+  'calendar.noEvents': 'noEvents',
+  'calendar.previous': 'previous',
+  'calendar.resize': 'resize',
+  'calendar.resizeStarted': 'resizeStarted',
+  'calendar.today': 'today',
+  'calendar.week': 'week',
+  'calendar.weekNumber': 'weekNumber',
+  'calendar.year': 'year'
+});

package/src/core/motion.js

@@ -0,0 +1,147 @@
+// @ts-check
+/**
+ * Motion as a setting, for the code that animates in script.
+ *
+ * CSS motion needs nothing from here: `tokens/global.css` sets every `--zx-dur-*` to 0ms and
+ * `base.css` stops animations and transitions both under the operating system's reduced-motion
+ * preference and inside any `data-zx-motion="reduced"` region. A chart engine's own tweening, a
+ * `requestAnimationFrame` loop, or `element.animate()` never sees those rules, so a component that
+ * moves things itself asks `prefersReducedMotion()` before it starts and `watchMotion()` for the
+ * moment the answer changes.
+ *
+ * There is no "full motion" value: a region can only ask for less. Someone who asked their system
+ * for reduced motion gets it whatever an application or a region says.
+ * @module zx/core/motion
+ */
+
+/** The attribute that marks a reduced-motion region. Its one meaningful value is `reduced`. */
+export const MOTION_ATTRIBUTE = 'data-zx-motion';
+
+const REDUCED_REGION = '[data-zx-motion="reduced"]';
+const REDUCED_QUERY = '(prefers-reduced-motion: reduce)';
+
+/**
+ * Whether motion should stop where `element` is: true under the operating system's reduced-motion
+ * preference, or when the element sits inside a `data-zx-motion="reduced"` region (the element
+ * itself included). The region check crosses shadow-root boundaries.
+ * @param {Element|null} [element] Where the motion would happen. Omitted, the document root is
+ *   asked — which answers for an application that sets the attribute on `<html>`.
+ * @returns {boolean}
+ */
+export function prefersReducedMotion(element) {
+  if (systemPrefersReducedMotion()) return true;
+  const target = element ?? globalThis.document?.documentElement ?? null;
+  return inReducedRegion(target);
+}
+
+/**
+ * @typedef {Object} WatchMotionOptions
+ * @property {AbortSignal} [signal] Stops watching when aborted, exactly as calling the returned
+ *   disposer does. A signal that is already aborted watches nothing.
+ * @property {boolean} [immediate=false] Also calls back once, synchronously, with the current
+ *   answer — convenient for a loop that starts or stays stopped in the same callback.
+ */
+
+/**
+ * Calls back whenever `prefersReducedMotion(element)` changes: when the operating-system preference
+ * flips, or when a `data-zx-motion` attribute is set, changed, or removed on the element or any
+ * ancestor (in the document, or in the shadow root the element lives in). The callback receives
+ * the new answer and runs only on a real change.
+ *
+ * Moving the element into or out of a reduced region is not observed — ask
+ * `prefersReducedMotion()` again after re-parenting.
+ * @param {Element|null} element Where the motion happens. Null watches the document root.
+ * @param {(reduced: boolean) => void} fn Receives `true` when motion must stop, `false` when it may
+ *   run again.
+ * @param {WatchMotionOptions} [options={}]
+ * @returns {() => void} Disposer: stops watching. Safe to call more than once.
+ */
+export function watchMotion(element, fn, options = {}) {
+  if (typeof fn !== 'function') throw new TypeError('watchMotion requires a callback');
+  const { signal, immediate = false } = options;
+  if (signal?.aborted) return () => {};
+
+  let current = prefersReducedMotion(element);
+  let stopped = false;
+
+  const check = () => {
+    if (stopped) return;
+    const next = prefersReducedMotion(element);
+    if (next === current) return;
+    current = next;
+    fn(next);
+  };
+
+  const media = typeof globalThis.matchMedia === 'function' ? globalThis.matchMedia(REDUCED_QUERY) : null;
+  media?.addEventListener?.('change', check);
+
+  // One observer over every tree the element's ancestry passes through: the document, and each
+  // shadow root on the way up. The attribute filter keeps it to the one attribute that matters.
+  const observer = typeof MutationObserver === 'function' ? new MutationObserver(check) : null;
+  if (observer) {
+    for (const root of treesAbove(element)) {
+      observer.observe(root, { attributes: true, attributeFilter: [MOTION_ATTRIBUTE], subtree: true });
+    }
+  }
+
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    media?.removeEventListener?.('change', check);
+    observer?.disconnect();
+    signal?.removeEventListener('abort', stop);
+  };
+  signal?.addEventListener('abort', stop, { once: true });
+
+  if (immediate) fn(current);
+  return stop;
+}
+
+/** @returns {boolean} Whether the operating system asks for reduced motion. */
+function systemPrefersReducedMotion() {
+  return typeof globalThis.matchMedia === 'function' && globalThis.matchMedia(REDUCED_QUERY).matches;
+}
+
+/**
+ * @param {Element|null} element
+ * @returns {boolean} Whether the element is inside a reduced region, across shadow boundaries.
+ */
+function inReducedRegion(element) {
+  /** @type {Element|null} */
+  let node = element;
+  while (node && typeof node.closest === 'function') {
+    if (node.closest(REDUCED_REGION)) return true;
+    const root = node.getRootNode?.();
+    node = isShadowRoot(root) ? root.host : null;
+  }
+  return false;
+}
+
+/**
+ * The trees a region attribute could be set in: the shadow roots on the element's way up, and the
+ * document element.
+ * @param {Element|null} element
+ * @returns {Node[]}
+ */
+function treesAbove(element) {
+  const trees = [];
+  /** @type {Element|null} */
+  let node = element;
+  while (node && typeof node.getRootNode === 'function') {
+    const root = node.getRootNode();
+    if (!isShadowRoot(root)) break;
+    trees.push(root);
+    node = root.host;
+  }
+  const documentElement = (element?.ownerDocument ?? globalThis.document)?.documentElement;
+  if (documentElement) trees.push(documentElement);
+  return trees;
+}
+
+/**
+ * @param {unknown} node
+ * @returns {node is ShadowRoot}
+ */
+function isShadowRoot(node) {
+  return Boolean(node) && /** @type {Node} */ (node).nodeType === 11 && 'host' in /** @type {object} */ (node);
+}

package/src/core/overlay-host.js

@@ -1,22 +1,96 @@
 import { resolveElement } from './dom.js';
 
-const SCOPE_SELECTOR = '.zx-scope, [data-zx-theme], [data-zx-density], [data-zx-preset]';
+const SCOPE_SELECTOR = '.zx-scope, [data-zx-theme], [data-zx-preset]';
+
+/**
+ * Open dialogs an anchored overlay must live inside. A modal one makes everything outside its
+ * subtree inert, and a focus-trapping one sends Tab back into itself, so a panel parked outside
+ * either could be seen but never used. `:popover-open` is the floating non-modal Sheet.
+ */
+const DIALOG_SELECTOR = 'dialog:modal, dialog[open], dialog:popover-open';
 
 /**
  * Finds the closest styling scope for a top-layer element.
  *
  * Popovers and dialogs escape clipping even when their DOM parent is inside an application shell,
- * so keeping them below that parent preserves inherited theme, density, material, and product
+ * so keeping them below that parent preserves inherited theme, preset, material, and product
  * token overrides without sacrificing top-layer behaviour. The document body remains the safe
  * fallback for unscoped applications.
  *
+ * Never answers a dialog: this is where a dialog itself, or anything at rest, belongs.
+ *
  * @param {Element|string|null} [source=null] Element or selector whose styling scope should own the overlay.
  * @returns {Element}
  */
+export function overlayScope(source = null) {
+  return scopeOf(contextOf(source));
+}
+
+/**
+ * Finds the element an anchored overlay should live in while it is open.
+ *
+ * A source inside an open `<dialog>` — modal, focus-trapping, or a floating non-modal Sheet — is
+ * hosted by that dialog: the panel still rises into the top layer above it, and being in its
+ * subtree is what keeps the panel out of `showModal()`'s inertness and inside a focus trap's
+ * reach. Anywhere else the answer is the nearest styling scope, as `overlayScope()` gives it.
+ *
+ * Without a source the focused element supplies the scope, and no dialog is chosen: what is
+ * being hosted then is not anchored to the focused element, only themed by it.
+ *
+ * @param {Element|string|null} [source=null] Element or selector the overlay is anchored to.
+ * @returns {Element}
+ */
 export function overlayHost(source = null) {
-  const context = source == null
+  const context = contextOf(source);
+  return (source == null ? null : openDialogOf(context)) ?? scopeOf(context);
+}
+
+/**
+ * Like `overlayHost()`, but declines to guess for a source that is not in the document yet.
+ *
+ * A component created before its anchor is connected cannot know which themed region the anchor
+ * will end up in: the anchor's ancestors are not there yet, so `overlayHost()` would answer
+ * `<body>`, outside every `[data-zx-theme]` and `.zx-scope`. This returns null instead, so the
+ * overlay can stay detached until it first opens and resolve its host with `overlayHost()` then,
+ * when the anchor is in place. The focused-element default (`source` null) is always connected and
+ * resolves exactly as `overlayHost()` does.
+ *
+ * @param {Element|string|null} [source=null] Element or selector whose styling scope should own the overlay.
+ * @param {{dialog?: boolean}} [options={}] `dialog: false` answers the styling scope only, as
+ *   `overlayScope()` does — where a closed panel rests until it opens.
+ * @returns {Element|null} The host, or null while the source is not connected to the document.
+ */
+export function connectedOverlayHost(source = null, options = {}) {
+  const host = options.dialog === false ? overlayScope : overlayHost;
+  if (source == null) return host(null);
+  const context = resolveElement(source);
+  return context?.isConnected ? host(context) : null;
+}
+
+/**
+ * The open dialog an element sits in, or null.
+ * @param {Element|null|undefined} element
+ * @returns {Element|null}
+ */
+export function openDialogOf(element) {
+  if (!element || typeof element.closest !== 'function') return null;
+  try {
+    return element.closest(DIALOG_SELECTOR);
+  } catch {
+    // A browser without `:modal` or `:popover-open` still knows an open dialog by its attribute.
+    return element.closest('dialog[open]');
+  }
+}
+
+/** @param {Element|string|null} source @returns {Element|null} */
+function contextOf(source) {
+  return source == null
     ? (document.activeElement instanceof Element ? document.activeElement : null)
     : resolveElement(source);
+}
+
+/** @param {Element|null} context @returns {Element} */
+function scopeOf(context) {
   const scope = context?.closest?.(SCOPE_SELECTOR) ?? null;
   if (!scope || scope === document.documentElement || scope === document.body) return document.body;
   return scope;