@zeyos/zx 4.4.0 → 5.2.0

package/dist/types/core/messages.d.ts

@@ -0,0 +1,382 @@
+/**
+ * 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 declare const defaultMessages: Readonly<{
+    '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 declare const legacyMessageKeys: Readonly<{
+    '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/dist/types/core/motion.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 declare const MOTION_ATTRIBUTE = "data-zx-motion";
+/**
+ * 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 declare function prefersReducedMotion(element?: Element | null): boolean;
+export type WatchMotionOptions = {
+    /**
+     * Stops watching when aborted, exactly as calling the returned
+     * disposer does. A signal that is already aborted watches nothing.
+     */
+    signal?: AbortSignal;
+    /**
+     * Also calls back once, synchronously, with the current
+     * answer — convenient for a loop that starts or stays stopped in the same callback.
+     */
+    immediate?: boolean;
+};
+/**
+ * @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 declare function watchMotion(element: Element | null, fn: (reduced: boolean) => void, options?: WatchMotionOptions): () => void;

package/dist/types/core/overlay-host.d.ts

@@ -2,11 +2,52 @@
  * 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 declare function overlayScope(source?: Element | string | null): Element;
+/**
+ * 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 declare function overlayHost(source?: Element | string | null): Element;
+/**
+ * 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 declare function connectedOverlayHost(source?: Element | string | null, options?: {
+    dialog?: boolean;
+}): Element | null;
+/**
+ * The open dialog an element sits in, or null.
+ * @param {Element|null|undefined} element
+ * @returns {Element|null}
+ */
+export declare function openDialogOf(element: Element | null | undefined): Element | null;