@antadesign/anta 0.3.26 → 0.3.28

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
@@ -76,6 +80,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

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) {
@@ -45,6 +57,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;
 }
@@ -160,12 +175,15 @@ export {
   SelectableChildElement,
   anchorRect,
   cssLength,
+  customEventHandler,
+  finiteNumber,
   hasChildren,
   installDismissTrigger,
   isInsideOpenMenu,
   isMenuOpen,
   lengthStyle,
   nativeStateChange,
+  neutralToneAttr,
   optionPresentationAttrs,
   parseOpenState,
   roundAttr,

package/dist/box-types.d.ts

@@ -152,7 +152,7 @@ export interface BoxMeasurement {
     hiddenStartY: boolean;
     hiddenEndY: boolean;
 }
-/** Every Box event includes just the changed fields and a complete current snapshot. */
+/** Box observation events include changed fields and a complete current snapshot. */
 export interface BoxChange<T> {
     changed: Partial<T>;
     current: T;