@antadesign/anta 0.3.34 → 0.3.35

package/LICENSE.md

@@ -1,4 +1,17 @@
-MIT License
+# Licensing scope
+
+The MIT license below applies to Anta except for the Antithesis theme in
+`src/theme-antithesis.css`, its built copy `dist/theme-antithesis.css`
+(exported as `@antadesign/anta/theme-antithesis.css`), and copies or
+modifications of that theme. The theme is licensed separately under
+[the Antithesis theme license](./theme-antithesis-license.md): noncommercial use is
+free, and commercial use requires prior written permission from Antithesis
+Operations LLC. That exception does not restrict rights already granted in
+earlier MIT-licensed copies of the theme.
+
+Third-party notices and licenses appear in [NOTICES.md](./NOTICES.md).
+
+## MIT License
 
 Copyright (c) 2026 Antithesis
 

package/README.md

@@ -5,6 +5,15 @@ design tokens, declarative web components, and typed JSX wrappers. Use the same
 components in React, Preact via compat, plain HTML, and custom JSX runtimes via
 `configure()`.
 
+## License
+
+Anta is [MIT licensed](./LICENSE.md), with one exception: the Antithesis theme
+(`@antadesign/anta/theme-antithesis.css`) is copyright Antithesis Operations LLC
+and has a [separate license](./theme-antithesis-license.md). Noncommercial use is
+free. Commercial use of the theme requires prior written permission through
+the [Antithesis contact page](https://antithesis.com/company/contact/).
+Antune and the default styles remain available under MIT.
+
 ## Documentation for coding agents
 
 The package includes version-matched Markdown documentation. Start with the

package/dist/anta_helpers.d.ts

@@ -1,6 +1,14 @@
+import { HTMLElementBase } from './element-base';
+export { HTMLElementBase } from './element-base';
 import type { IconShape } from "./elements/a-icon.shapes";
 import type { OptionPresentationProps } from "./general_types";
+/** @internal Check the native Node brand across realms without reading a document. */
+export declare function isDOMNode(value: unknown): value is Node;
 export declare function hasChildren(children: React.ReactNode): boolean;
+/** @internal Mirror selection for declarative rendering, retaining the latest
+ * controlled value when ownership is released. Update the mirror only for
+ * accepted uncontrolled changes. */
+export declare function useSelectionMirror(value: string | undefined, defaultValue?: string): readonly [string | undefined, (next: string | ((prev: string | undefined) => string | undefined) | undefined) => void];
 /**
  * Select the safe presentation attributes from a data-rendered option. Option
  * objects often carry application data, so wrappers must never spread them onto
@@ -48,6 +56,10 @@ export declare function wrapLabel(kids: React.ReactNode, tag: string): React.Rea
 export type StateChangeEvent<D> = CustomEvent<D> | {
     nativeEvent: CustomEvent<D>;
 };
+/** @internal Return the raw event from native or renderer-wrapped callbacks. */
+export declare function unwrapNativeEvent<E extends object>(event: E | {
+    nativeEvent: E;
+}): E;
 export declare function nativeStateChange<D>(e: StateChangeEvent<D>): {
     event: CustomEvent<D>;
     detail?: D;
@@ -59,6 +71,11 @@ export declare function customEventHandler<D>(handler?: (event: CustomEvent<D>,
 export declare function finiteNumber(value: string | number | null, fallback: number): number;
 /** Normalize the JSX `truncate` shorthand to a positive CSS line count. */
 export declare function lineClamp(truncate: boolean | number | undefined): number | undefined;
+/** Leave candidate navigation and confirmation with the input method, including
+ * browsers that report the final composing key only through legacy code 229. */
+export declare function isComposingKey(event: Pick<KeyboardEvent, 'isComposing' | 'keyCode'> | {
+    nativeEvent: Pick<KeyboardEvent, 'isComposing' | 'keyCode'>;
+}): boolean;
 /** Leave modified navigation to the browser, OS, or text field. Shift+Tab remains focus navigation. */
 export declare function isModifiedNavigationKey(event: Pick<KeyboardEvent, 'key' | 'altKey' | 'ctrlKey' | 'metaKey' | 'shiftKey'>): boolean;
 export declare const IS_MAC: boolean;
@@ -146,21 +163,22 @@ export declare function anchorRect(el: Element): DOMRect;
  * (Menu and tooltip are both top-layer popovers, stacked by show order, so a
  * tooltip opened while a menu is up would paint over it — z-index can't reorder
  * the top layer.) Decoupled on purpose: neither element imports the other, and
- * if `a-menu` never loads the provider stays null and every tooltip shows.
+ * if `a-menu` never loads there are no providers and tooltips remain available.
  */
 export interface MenuPresence {
     /** Is any `a-menu` open? */
-    isOpen(): boolean;
+    isOpen(doc?: Document): boolean;
     /** Is `node` inside the open menu system — a menu surface, a slotted item, or
      *  an open trigger? (A tooltip there is a menu-item tooltip and still shows,
      *  above the menu.) */
     contains(node: Node): boolean;
 }
-/** `a-menu` registers its live open-state provider here (once, on load). */
-export declare function setMenuPresence(p: MenuPresence | null): void;
-/** True while any `a-menu` is open. */
-export declare function isMenuOpen(): boolean;
-/** True if `node` sits inside the open menu system. */
+/** Register every compiled provider; a later unused class must not replace the
+ * provider belonging to the class retained by the custom-element registry. */
+export declare function setMenuPresence(p: MenuPresence | null, doc?: Document | undefined): void;
+/** True while a menu is open in this document. */
+export declare function isMenuOpen(doc?: Document | undefined): boolean;
+/** True if `node` sits inside an open menu in its document. */
 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. */
@@ -175,29 +193,18 @@ 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
- * module in a non-DOM environment doesn't throw on `extends HTMLElement`.
- * Instantiation in non-DOM environments still fails, but no consumer
- * should be doing that.
- */
-declare const NativeHTMLElement: typeof HTMLElement;
-/**
- * Base for Anta custom elements. Adds realm-correct `view` / `doc` getters:
- * the class may be defined in one realm while the element lives in another
- * (the docs playground renders into an iframe but reuses the parent page's
- * element class), so the module-global `window` / `document` can point at the
- * wrong frame. Anything viewport- or document-scoped — clamping,
- * `getComputedStyle`, scroll / key / pointer listeners — must go through these
- * so it's correct in any frame. Shared by a-tooltip and a-menu.
- */
-export declare class HTMLElementBase extends NativeHTMLElement {
-    /** This element's own window (the iframe's window when nested). */
-    protected get view(): Window & typeof globalThis;
-    /** This element's own document (the iframe's document when nested). */
-    protected get doc(): Document;
+/** Internal Text-to-Button protocol. The receiver publishes accessibility
+ * defaults through its own ElementInternals without changing authored DOM. */
+export declare const SYNC_TEXT_TOGGLE: unique symbol;
+export interface TextToggleAria {
+    source: Element;
+    expanded?: boolean;
+    clear?: boolean;
 }
+export interface TextToggleReceiver extends Element {
+    [SYNC_TEXT_TOGGLE](state: TextToggleAria): void;
+}
+export declare function isTextToggleReceiver(element: Element | null): element is TextToggleReceiver;
 /** Apply default accessible names and descriptions through element references. */
 export declare function applyAccessibilityRelations(internals: ElementInternals | undefined, labels: Element[], descriptions: Element[]): void;
 /**
@@ -254,4 +261,13 @@ export declare class SelectableChildElement extends HTMLElementBase {
      * without exposing IDs or the shared ElementInternals instance. */
     protected applyAccessibilityRelations(labels: Element[], descriptions: Element[]): void;
 }
-export {};
+/** @internal Project value inputs through HTML attributes in every renderer.
+ * HTML attribute names are case-insensitive. `VALUE` avoids React's property
+ * assignment and Preact's special live-value comparison/removal, while producing
+ * the ordinary `value` attribute in the DOM and parsed SSR HTML. In particular,
+ * an empty-string option stays distinct from removing controlled ownership.
+ * Keep this projection serializable for server and worker renderers. */
+export declare const valueAttributes: (value: string | undefined, defaultValue?: string) => {
+    VALUE: string | undefined;
+    defaultvalue: string | undefined;
+};

package/dist/anta_helpers.js

@@ -1,7 +1,26 @@
-import { jsx, useState, useMemo } from "./jsx-runtime";
+import { HTMLElementBase } from "./element-base";
+import { HTMLElementBase as HTMLElementBase2 } from "./element-base";
+import { jsx, useState, useMemo, useOptionalClientLayoutEffect } from "./jsx-runtime";
+function isDOMNode(value) {
+  if (typeof Node === "undefined" || value == null || typeof value !== "object") return false;
+  try {
+    return Node.prototype.isSameNode.call(value, value);
+  } catch {
+    return false;
+  }
+}
 function hasChildren(children) {
   return Array.isArray(children) ? children.length > 0 : children != null;
 }
+function useSelectionMirror(value, defaultValue) {
+  const [internalValue, setInternalValue] = useState(value ?? defaultValue);
+  const [lastValue, setLastValue] = useState(value);
+  if (value !== lastValue) {
+    setLastValue(value);
+    if (value !== void 0) setInternalValue(value);
+  }
+  return [value !== void 0 ? value : internalValue, setInternalValue];
+}
 function optionPresentationAttrs(option, menu = false) {
   const attrs = {};
   for (const [name, value] of Object.entries(option)) {
@@ -20,8 +39,11 @@ function wrapLabel(kids, tag) {
     return child;
   });
 }
+function unwrapNativeEvent(event) {
+  return "nativeEvent" in event ? event.nativeEvent : event;
+}
 function nativeStateChange(e) {
-  const event = "nativeEvent" in e ? e.nativeEvent : e;
+  const event = unwrapNativeEvent(e);
   return { event, detail: event?.detail, isOwn: !event || event.target === event.currentTarget };
 }
 function customEventHandler(handler) {
@@ -41,6 +63,10 @@ function lineClamp(truncate) {
   return lines != null && lines >= 1 ? lines : void 0;
 }
 const NAVIGATION_KEYS = /* @__PURE__ */ new Set(["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Home", "End", "PageUp", "PageDown", "Tab"]);
+function isComposingKey(event) {
+  const native = unwrapNativeEvent(event);
+  return native.isComposing || native.keyCode === 229;
+}
 function isModifiedNavigationKey(event) {
   return NAVIGATION_KEYS.has(event.key) && (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey && event.key !== "Tab");
 }
@@ -52,10 +78,16 @@ function parseOpenState(v) {
 }
 function installDismissTrigger(host, attr, onDismiss) {
   host.addEventListener("click", (e) => {
-    const target = e.target;
-    if (!(target instanceof Element)) return;
-    const trigger = target.closest(`[${attr}]`);
-    if (trigger && trigger.closest(host.localName) === host) onDismiss();
+    let triggered = false;
+    for (const target of e.composedPath()) {
+      const element = target;
+      if (element.nodeType !== 1) continue;
+      if (element.localName === host.localName) {
+        if (element === host && (triggered || element.hasAttribute(attr))) onDismiss();
+        return;
+      }
+      if (element.hasAttribute(attr)) triggered = true;
+    }
   });
 }
 const NAMED_TONES = /* @__PURE__ */ new Set([
@@ -90,6 +122,7 @@ const COPY_FEEDBACK_MS = 2e3;
 function useCopyFeedback(icon, tone, onCopied) {
   const [status, setStatus] = useState("idle");
   const box = useMemo(() => ({ timer: void 0 }), []);
+  useOptionalClientLayoutEffect(() => () => clearTimeout(box.timer), [box]);
   const handleCopied = (ok) => {
     clearTimeout(box.timer);
     setStatus(ok ? "ok" : "fail");
@@ -104,31 +137,28 @@ function anchorRect(el) {
   const fn = el.getAnchorRect;
   return typeof fn === "function" ? fn.call(el) : el.getBoundingClientRect();
 }
-let menuPresence = null;
-function setMenuPresence(p) {
-  menuPresence = p;
+const MENU_PRESENCE = /* @__PURE__ */ Symbol.for("anta.menu-presence");
+function setMenuPresence(p, doc = typeof document === "undefined" ? void 0 : document) {
+  if (!doc) return;
+  const providers = doc[MENU_PRESENCE] ??= /* @__PURE__ */ new Set();
+  if (p) providers.add(p);
+  else providers.clear();
 }
-function isMenuOpen() {
-  return menuPresence?.isOpen() ?? false;
+function isMenuOpen(doc = typeof document === "undefined" ? void 0 : document) {
+  if (!doc) return false;
+  return [...doc[MENU_PRESENCE] ?? []].some((provider) => provider.isOpen(doc));
 }
 function isInsideOpenMenu(node) {
-  return menuPresence?.contains(node) ?? false;
+  const doc = node.ownerDocument;
+  return doc != null && [...doc[MENU_PRESENCE] ?? []].some((provider) => provider.contains(node));
 }
-const SYNC_POPUP_ARIA = /* @__PURE__ */ Symbol("anta.sync-popup-aria");
+const SYNC_POPUP_ARIA = /* @__PURE__ */ Symbol.for("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 {
-  /** This element's own window (the iframe's window when nested). */
-  get view() {
-    return this.ownerDocument?.defaultView ?? window;
-  }
-  /** This element's own document (the iframe's document when nested). */
-  get doc() {
-    return this.ownerDocument ?? document;
-  }
+const SYNC_TEXT_TOGGLE = /* @__PURE__ */ Symbol.for("anta.sync-text-toggle");
+function isTextToggleReceiver(element) {
+  return element != null && typeof element[SYNC_TEXT_TOGGLE] === "function";
 }
 function applyAccessibilityRelations(internals, labels, descriptions) {
   if (!internals) return;
@@ -195,13 +225,18 @@ class SelectableChildElement extends HTMLElementBase {
     applyAccessibilityRelations(this.internals, labels, descriptions);
   }
 }
+const valueAttributes = (value, defaultValue) => ({
+  VALUE: value,
+  defaultvalue: value === void 0 ? defaultValue : void 0
+});
 export {
-  HTMLElementBase,
+  HTMLElementBase2 as HTMLElementBase,
   ISOLATE_HINT,
   ISOLATE_HINT_DELAY,
   IS_MAC,
   NAMED_TONES,
   SYNC_POPUP_ARIA,
+  SYNC_TEXT_TOGGLE,
   SelectableChildElement,
   anchorRect,
   applyAccessibilityRelations,
@@ -210,10 +245,13 @@ export {
   finiteNumber,
   hasChildren,
   installDismissTrigger,
+  isComposingKey,
+  isDOMNode,
   isInsideOpenMenu,
   isMenuOpen,
   isModifiedNavigationKey,
   isPopupAriaReceiver,
+  isTextToggleReceiver,
   lengthStyle,
   lineClamp,
   nativeStateChange,
@@ -224,6 +262,9 @@ export {
   roundStyle,
   setMenuPresence,
   toneStyle,
+  unwrapNativeEvent,
   useCopyFeedback,
+  useSelectionMirror,
+  valueAttributes,
   wrapLabel
 };