@antadesign/anta 0.3.25 → 0.3.27

package/README.md

@@ -7,34 +7,32 @@ components in React, Preact via compat, plain HTML, and custom JSX runtimes via
 
 ## Documentation for coding agents
 
-Start with [`./docs/index.md`](./docs/index.md). This path is relative to the
-root of the installed Anta package, not to the consuming application.
-
-This package includes version-specific documentation inside the installed npm
-package.
-
-Example:
-
-```text
-node_modules/
-└── @antadesign/
-    └── anta/
-        ├── README.md
-        ├── docs/
-        │   ├── index.md
-        │   ├── install-config.md
-        │   ├── theming.md
-        │   └── components/
-        │       ├── button.md
-        │       ├── dialog.md
-        │       └── ...
-        └── dist/
+The package includes version-matched Markdown documentation. Start with the
+[documentation index](./docs/index.md) and open the pages relevant to your task.
+Agents with filesystem access can read these files offline.
+
+### AI setup
+
+Append this section to your application's agent instruction file, such as
+`AGENTS.md`, `CLAUDE.md`, or your tool's equivalent. Keep existing project rules:
+
+```md
+## Anta
+
+Before Anta UI work, read
+`node_modules/@antadesign/anta/docs/index.md`
+and the pages relevant to the task.
+Verify component names, imports, props, and event signatures against the
+installed documentation and TypeScript declarations. Do not infer Anta APIs
+from similarly named components in other libraries.
 ```
 
-When working with Anta components:
+The path is relative to the application directory where Anta is installed.
+Adjust it for your workspace or package-manager layout. Installing Anta does
+not modify your agent configuration.
+
+If a documented type differs from the installed `.d.ts` declarations, use the
+declarations for the installed API.
 
-1. Read `./docs/index.md` from the installed `@antadesign/anta` package.
-2. Open only the documentation relevant to the component or feature you are using.
-3. Do **not** guess component names, props, or behavior from similarly named component libraries (e.g. MUI, Chakra UI, Radix UI, Mantine, shadcn/ui, Ant Design, etc.).
-4. Use the installed package's TypeScript declarations (`*.d.ts`) as the source of truth for the installed package version.
-5. If the Markdown documentation and TypeScript declarations disagree, prefer the TypeScript declarations, as they always correspond to the installed version.
+For tools without local file access, provide the [web documentation index](https://anta.design/llms.txt)
+and your installed Anta version. Web documentation may describe a newer release.

package/dist/anta_helpers.d.ts

@@ -53,6 +53,10 @@ export declare function nativeStateChange<D>(e: StateChangeEvent<D>): {
     detail?: D;
     isOwn: boolean;
 };
+/** Adapt a callback to native or renderer-wrapped custom events with non-null detail. */
+export declare function customEventHandler<D>(handler?: (event: CustomEvent<D>, detail: D) => void): ((input: StateChangeEvent<D>) => void) | undefined;
+/** Parse a finite number, falling back for missing, empty, or invalid values. */
+export declare function finiteNumber(value: string | number | null, fallback: number): number;
 export declare const IS_MAC: boolean;
 /** Default row hint teaching the Alt/⌥-click "select only this" accelerator on
  *  bulk-select rows (`Select` multiple, `SelectFaceted` multiple facets). Shared

package/dist/anta_helpers.js

@@ -24,6 +24,18 @@ function nativeStateChange(e) {
   const event = "nativeEvent" in e ? e.nativeEvent : e;
   return { event, detail: event?.detail, isOwn: !event || event.target === event.currentTarget };
 }
+function customEventHandler(handler) {
+  if (!handler) return void 0;
+  return (input) => {
+    const { event, detail } = nativeStateChange(input);
+    if (detail != null) handler(event, detail);
+  };
+}
+function finiteNumber(value, fallback) {
+  if (value == null || value === "") return fallback;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : 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";
 function parseOpenState(v) {
@@ -119,7 +131,7 @@ class SelectableChildElement extends HTMLElementBase {
     if (name === "selected") this.applyState(this.hasAttribute("selected"));
   }
   get selected() {
-    return this.internals?.states.has("selected") ?? false;
+    return this.internals?.states?.has("selected") ?? false;
   }
   /**
    * Live selection, held off the DOM as `:state(selected)` (mirrored to `ariaProp`).
@@ -147,8 +159,8 @@ class SelectableChildElement extends HTMLElementBase {
   }
   applyState(on) {
     if (!this.internals) return;
-    if (on) this.internals.states.add("selected");
-    else this.internals.states.delete("selected");
+    if (on) this.internals?.states?.add("selected");
+    else this.internals?.states?.delete("selected");
     this.internals[this.ariaProp] = on ? "true" : "false";
   }
 }
@@ -160,6 +172,8 @@ export {
   SelectableChildElement,
   anchorRect,
   cssLength,
+  customEventHandler,
+  finiteNumber,
   hasChildren,
   installDismissTrigger,
   isInsideOpenMenu,

package/dist/box-types.d.ts

@@ -0,0 +1,161 @@
+/** Display modes supplied by `Box`. The element is a real light-DOM CSS box,
+ * so every other layout property remains ordinary CSS on the host. */
+export type BoxDisplay = 'block' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'inline-grid';
+/** Color mode resolved from the closest `.light` or `.dark` ancestor. */
+export type BoxMode = 'light' | 'dark';
+/** Operating-system family. Anta deliberately does not expose a user-agent string. */
+export type BoxOS = 'android' | 'ios' | 'linux' | 'macos' | 'windows' | 'unknown';
+/** Browser family. */
+export type BoxBrowser = 'chrome' | 'edge' | 'firefox' | 'opera' | 'safari' | 'unknown';
+/** Primary pointing-device capability reported by the browser. */
+export type BoxPointer = 'fine' | 'coarse' | 'none';
+/** Current state that affects a box's rendering or interaction decisions. */
+/**
+ * Distance from the box's border edge to its content edge, in CSS pixels.
+ *
+ * Not derivable from `BoxMeasurement`: `width` / `height` are the border box and
+ * `clientWidth` / `clientHeight` are the padding box, so neither the padding nor
+ * the border thickness can be recovered from them. Add a padding and its border
+ * to place content relative to the border box.
+ */
+export interface BoxInset {
+    paddingTop: number;
+    paddingRight: number;
+    paddingBottom: number;
+    paddingLeft: number;
+    borderTop: number;
+    borderRight: number;
+    borderBottom: number;
+    borderLeft: number;
+}
+/**
+ * The box's resolved text style, shaped to configure a canvas 2D context.
+ *
+ * Assign `shorthand` to `ctx.font` **first**: Chromium and Firefox reset
+ * `fontStretch`, `fontVariantCaps`, `fontKerning` and `textRendering` when
+ * `font` is assigned, so setting those before it loses them.
+ */
+export interface BoxFont {
+    /** CSS `font` shorthand, assembled here because every engine returns an empty
+     * string for the computed shorthand. `stretch` and `variantCaps` are left out
+     * of it deliberately: a percentage `font-stretch` makes every engine reject
+     * the whole string and fall back to `10px sans-serif`. Apply those through
+     * `ctx.fontStretch` / `ctx.fontVariantCaps` after setting `ctx.font`. */
+    shorthand: string;
+    /** Resolved family list, quoted as the engine reports it. */
+    family: string;
+    /** Font size in CSS pixels. */
+    size: number;
+    /** Numeric weight, 1-1000. */
+    weight: number;
+    /** `normal`, `italic`, or an `oblique <angle>`. */
+    style: string;
+    /** Computed `font-stretch`, a percentage such as `88%`. Canvas: `ctx.fontStretch`. */
+    stretch: string;
+    /** Line height in CSS pixels, or `null` when it computes to `normal`. Canvas
+     * ignores line height in `ctx.font`; this is for laying text out yourself. */
+    lineHeight: number | null;
+    /** A length, never `normal` - `normal` is reported as `0px`, which is what
+     * `ctx.letterSpacing` accepts. */
+    letterSpacing: string;
+    /** Same normalization as `letterSpacing`. Canvas: `ctx.wordSpacing`. */
+    wordSpacing: string;
+    /** Resolved text color. Canvas: `ctx.fillStyle`. */
+    color: string;
+    /** Canvas 2D consumes neither of these. They are here for text you measure or
+     * draw some other way. */
+    featureSettings: string;
+    variationSettings: string;
+    /** Canvas: `ctx.fontKerning`. */
+    kerning: string;
+    /** Canvas: `ctx.fontVariantCaps`. */
+    variantCaps: string;
+    /** Canvas: `ctx.textRendering`, which WebKit does not implement. */
+    textRendering: string;
+    /** Canvas: `ctx.direction`. */
+    direction: string;
+}
+export interface BoxContext {
+    /** Closest scoped Anta mode. A local `.light` can override a dark document. */
+    mode: BoxMode;
+    /** Mode on `<html>`, independent of an enclosing local scope. */
+    globalMode: BoxMode;
+    /** Browser / operating-system color preference, independent of Anta classes. */
+    systemAppearance: BoxMode;
+    /** Whether focus is on the box or any of its descendants, read from the
+     * native `:focus-within`. For CSS, use that pseudo-class directly; this field
+     * is for logic that cannot query the DOM. */
+    focusWithin: boolean;
+    /** Operating-system family. */
+    os: BoxOS;
+    /** Operating-system major version, or `0` when the browser withholds it.
+     * Browsers freeze this: every engine reports macOS as `10.15.7` and Windows 11
+     * as `10.0`, so only Android and iOS carry a real number. Treat it as a hint,
+     * never as a gate. */
+    osVersion: number;
+    /** Browser family. */
+    browser: BoxBrowser;
+    /** Browser major version, or `0` when unknown. Minor and patch digits are
+     * frozen by every engine, so only the major number is reported. */
+    browserVersion: number;
+    /** Whether the browser reports a mobile device. */
+    mobile: boolean;
+    /** Most precise available primary pointer. */
+    pointer: BoxPointer;
+    /** Whether ordinary hover interaction is available. */
+    hover: boolean;
+    /** Whether the reader asks for reduced motion. */
+    reducedMotion: boolean;
+    /** `window.devicePixelRatio`: CSS pixels per device pixel. `1` on a standard
+     * display, `2` on most Retina screens, and a fraction under OS or browser
+     * zoom. Live — it re-reports on zoom and when the window moves to a monitor
+     * with a different density. */
+    devicePixelRatio: number;
+    /** Resolved text style, ready to hand to a canvas 2D context. */
+    font: BoxFont;
+    /** Padding and border widths, for placing content inside the border box. */
+    inset: BoxInset;
+    /** Resolved `background-color`. Needed when the box's content is drawn
+     * somewhere else — an offscreen canvas, a worker, an export — where the box's
+     * own background is not behind it. */
+    backgroundColor: string;
+}
+/** Current box dimensions and its content-overflow state. */
+export interface BoxMeasurement {
+    /** Border-box width and height in CSS pixels. */
+    width: number;
+    height: number;
+    /** Padding-box dimensions, matching the browser's `clientWidth` / `clientHeight`. */
+    clientWidth: number;
+    clientHeight: number;
+    /** Full scrollable-content dimensions, matching `scrollWidth` / `scrollHeight`. */
+    scrollWidth: number;
+    scrollHeight: number;
+    /** Content exceeds the padding box on this axis, regardless of CSS overflow. */
+    overflowX: boolean;
+    overflowY: boolean;
+    /** The exceeded content is visually clipped on this axis. */
+    clippedX: boolean;
+    clippedY: boolean;
+    /** The exceeded content can be scrolled by the reader on this axis. */
+    scrollableX: boolean;
+    scrollableY: boolean;
+    /** Current scroll offset, matching `scrollLeft` / `scrollTop`. */
+    scrollLeft: number;
+    scrollTop: number;
+    /** Clipped content sits past this specific edge, in logical writing-mode
+     * terms. A clipped box that has not been scrolled hides content past its end
+     * edge only; scroll it to the end and the hidden content moves to the start.
+     * These drive the `fade` mask. */
+    hiddenStartX: boolean;
+    hiddenEndX: boolean;
+    hiddenStartY: boolean;
+    hiddenEndY: boolean;
+}
+/** Box observation events include changed fields and a complete current snapshot. */
+export interface BoxChange<T> {
+    changed: Partial<T>;
+    current: T;
+}
+export type BoxContextChange = BoxChange<BoxContext>;
+export type BoxMeasurementChange = BoxChange<BoxMeasurement>;