@antadesign/anta 0.3.27 → 0.3.29

package/NOTICES.md

@@ -1,6 +1,6 @@
 # Third-party notices
 
-The Anta design system bundles icons derived from third-party
+The Anta design system bundles code and icons derived from third-party
 projects. Their original copyright and license texts are reproduced
 below as required by those licenses.
 
@@ -277,3 +277,34 @@ Some of the Blueprint-derived SVGs in this package have been modified
 `currentColor`, and renamed to follow Anta's icon-naming conventions);
 these modifications are themselves released under the Apache License,
 Version 2.0.
+
+---
+
+## Tabbable
+
+Panel uses [Tabbable](https://github.com/focus-trap/tabbable) to determine
+keyboard focus order. The bundled runtime includes it under the MIT license:
+
+```
+The MIT License (MIT)
+
+Copyright (c) 2015 David Clark
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

package/dist/anta_helpers.d.ts

@@ -62,6 +62,9 @@ export declare const IS_MAC: boolean;
  *  bulk-select rows (`Select` multiple, `SelectFaceted` multiple facets). Shared
  *  so the wording stays identical across both. */
 export declare const ISOLATE_HINT: string;
+/** The accelerator hint is secondary guidance shown while traversing a menu, so
+ *  wait longer than Tooltip's general 300ms default before surfacing it. */
+export declare const ISOLATE_HINT_DELAY = 700;
 /** Parse an open/closed `state` / `default-state` attribute — the shared
  *  open-state vocabulary (`a-dialog`, `a-expander`, …). Anything but the literal
  *  `'open'` is `'closed'`, so an absent / malformed attribute reads closed. Kept
@@ -80,6 +83,10 @@ export declare function installDismissTrigger(host: HTMLElement, attr: string, o
 /** The six named tones every toned component shares. Anything else is a literal
  *  CSS color the element resolves through its `--{component}-tone-source` var. */
 export declare const NAMED_TONES: Set<string>;
+/** Omits the neutral default from JSX-generated DOM. Use only where an absent
+ * tone is equivalent to neutral; per-child tones keep an explicit `neutral`
+ * value when it resets an inherited group tone. */
+export declare function neutralToneAttr<T extends string>(tone: T | undefined): T | undefined;
 /**
  * Inline-style helper for a custom (non-named) tone: hands the literal color to
  * the element via `varName` (e.g. `--radio-tone-source`) so the element's CSS
@@ -151,6 +158,19 @@ export declare function setMenuPresence(p: MenuPresence | null): void;
 export declare function isMenuOpen(): boolean;
 /** True if `node` sits inside the open menu system. */
 export declare function isInsideOpenMenu(node: Node): boolean;
+/** Internal element protocol used by a popup to associate itself and its active
+ * item with an Anta-owned focus target without serializing cross-root IDs. */
+export declare const SYNC_POPUP_ARIA: unique symbol;
+export interface PopupAriaRelations {
+    source: Element;
+    controls?: Element | null;
+    activeDescendant?: Element | null;
+    clear?: boolean;
+}
+export interface PopupAriaReceiver extends Element {
+    [SYNC_POPUP_ARIA](relations: PopupAriaRelations): void;
+}
+export declare function isPopupAriaReceiver(element: Element | null): element is PopupAriaReceiver;
 /**
  * `HTMLElement` in browsers, a noop class in Node/Worker environments.
  * Use this as the base for custom element classes so importing the
@@ -174,6 +194,8 @@ export declare class HTMLElementBase extends NativeHTMLElement {
     /** This element's own document (the iframe's document when nested). */
     protected get doc(): Document;
 }
+/** Apply default accessible names and descriptions through element references. */
+export declare function applyAccessibilityRelations(internals: ElementInternals | undefined, labels: Element[], descriptions: Element[]): void;
 /**
  * Base for a coordinated presentational child — one option in a control whose
  * parent owns the selection (`<a-radio>` in `<a-radio-group>`, `<a-tab>` in
@@ -224,5 +246,8 @@ export declare class SelectableChildElement extends HTMLElementBase {
     get value(): string;
     set value(v: string);
     protected applyState(on: boolean): void;
+    /** Give subclasses name/description relationships to their light-DOM content
+     * without exposing IDs or the shared ElementInternals instance. */
+    protected applyAccessibilityRelations(labels: Element[], descriptions: Element[]): void;
 }
 export {};

package/dist/anta_helpers.js

@@ -38,6 +38,7 @@ function finiteNumber(value, fallback) {
 }
 const IS_MAC = typeof navigator !== "undefined" && /Mac|iPhone|iPad/i.test(navigator.userAgent || "");
 const ISOLATE_HINT = IS_MAC ? "\u2325+Click to select only this" : "Alt+Click to select only this";
+const ISOLATE_HINT_DELAY = 700;
 function parseOpenState(v) {
   return v === "open" ? "open" : "closed";
 }
@@ -57,6 +58,9 @@ const NAMED_TONES = /* @__PURE__ */ new Set([
   "warning",
   "critical"
 ]);
+function neutralToneAttr(tone) {
+  return tone && tone !== "neutral" ? tone : void 0;
+}
 function toneStyle(tone, varName, base) {
   return tone != null && !NAMED_TONES.has(tone) ? { ...base, [varName]: tone } : base;
 }
@@ -102,6 +106,10 @@ function isMenuOpen() {
 function isInsideOpenMenu(node) {
   return menuPresence?.contains(node) ?? false;
 }
+const SYNC_POPUP_ARIA = Symbol("anta.sync-popup-aria");
+function isPopupAriaReceiver(element) {
+  return element != null && typeof element[SYNC_POPUP_ARIA] === "function";
+}
 const NativeHTMLElement = typeof HTMLElement !== "undefined" ? HTMLElement : class {
 };
 class HTMLElementBase extends NativeHTMLElement {
@@ -114,6 +122,16 @@ class HTMLElementBase extends NativeHTMLElement {
     return this.ownerDocument ?? document;
   }
 }
+function applyAccessibilityRelations(internals, labels, descriptions) {
+  if (!internals) return;
+  try {
+    if ("ariaLabelledByElements" in internals)
+      internals.ariaLabelledByElements = labels;
+    if ("ariaDescribedByElements" in internals)
+      internals.ariaDescribedByElements = descriptions;
+  } catch {
+  }
+}
 class SelectableChildElement extends HTMLElementBase {
   static observedAttributes = ["selected"];
   /** ARIA property this element reflects selection into. Subclass sets it. */
@@ -163,14 +181,22 @@ class SelectableChildElement extends HTMLElementBase {
     else this.internals?.states?.delete("selected");
     this.internals[this.ariaProp] = on ? "true" : "false";
   }
+  /** Give subclasses name/description relationships to their light-DOM content
+   * without exposing IDs or the shared ElementInternals instance. */
+  applyAccessibilityRelations(labels, descriptions) {
+    applyAccessibilityRelations(this.internals, labels, descriptions);
+  }
 }
 export {
   HTMLElementBase,
   ISOLATE_HINT,
+  ISOLATE_HINT_DELAY,
   IS_MAC,
   NAMED_TONES,
+  SYNC_POPUP_ARIA,
   SelectableChildElement,
   anchorRect,
+  applyAccessibilityRelations,
   cssLength,
   customEventHandler,
   finiteNumber,
@@ -178,8 +204,10 @@ export {
   installDismissTrigger,
   isInsideOpenMenu,
   isMenuOpen,
+  isPopupAriaReceiver,
   lengthStyle,
   nativeStateChange,
+  neutralToneAttr,
   optionPresentationAttrs,
   parseOpenState,
   roundAttr,

package/dist/box-observation.d.ts

@@ -0,0 +1,8 @@
+import type { BoxMeasurement } from './box-types';
+/** Resolves the same observation vocabulary for JSX handlers and raw attributes. */
+export declare function boxObservation(value: string | null): {
+    fields: Set<keyof BoxMeasurement>;
+    context: boolean;
+    content: boolean;
+    scroll: boolean;
+};

package/dist/box-observation.js

@@ -0,0 +1,41 @@
+const groups = {
+  width: ["width"],
+  height: ["height"],
+  size: ["width", "height"],
+  overflow: [
+    "clientWidth",
+    "clientHeight",
+    "scrollWidth",
+    "scrollHeight",
+    "overflowX",
+    "overflowY",
+    "clippedX",
+    "clippedY",
+    "scrollableX",
+    "scrollableY"
+  ],
+  edges: ["hiddenStartX", "hiddenEndX", "hiddenStartY", "hiddenEndY"],
+  scroll: ["scrollLeft", "scrollTop"]
+};
+const measurementFields = new Set(Object.values(groups).flat());
+function boxObservation(value) {
+  const fields = /* @__PURE__ */ new Set();
+  let context = false;
+  const tokens = value === "" ? ["all"] : value?.trim().split(/\s+/) ?? [];
+  for (const token of tokens) {
+    if (token === "all") {
+      for (const field of measurementFields) fields.add(field);
+      context = true;
+    } else if (token === "context") {
+      context = true;
+    } else if (Object.hasOwn(groups, token)) {
+      for (const field of groups[token]) fields.add(field);
+    }
+  }
+  const content = [...fields].some((field) => field !== "width" && field !== "height");
+  const scroll = [...groups.scroll, ...groups.edges].some((field) => fields.has(field));
+  return { fields, context, content, scroll };
+}
+export {
+  boxObservation
+};

package/dist/box-types.d.ts

@@ -152,6 +152,8 @@ export interface BoxMeasurement {
     hiddenStartY: boolean;
     hiddenEndY: boolean;
 }
+/** Independent Box observation selections, from resize signals to scroll tracking. */
+export type BoxObservation = 'width' | 'height' | 'size' | 'context' | 'overflow' | 'edges' | 'scroll' | 'all';
 /** Box observation events include changed fields and a complete current snapshot. */
 export interface BoxChange<T> {
     changed: Partial<T>;