@antadesign/anta 0.1.1-dev.6 → 0.1.1-dev.8

package/README.md

@@ -29,12 +29,14 @@ Anta exposes four independent imports. Tokens + elements + the JSX layer are the
 
 | Import | Provides | Skip if… |
 |---|---|---|
-| `@antadesign/anta/tokens.css` | The CSS custom properties — `--bg-base`, `--text-1…5`, `--border-1…5`, the `.dark`-ancestor toggling, the base `font-size: 15px`. Also declares the `@layer base, anta, components, utilities;` cascade order. | You're applying your own design tokens at the same variable names. |
+| `@antadesign/anta/tokens.css` | The CSS custom properties — `--bg-1…5`, `--text-1…5`, `--border-1…5`, the `.dark`-ancestor toggling, the base `font-size: 15px`. Also declares the `@layer base, anta, components, utilities;` cascade order. | You're applying your own design tokens at the same variable names. |
 | `@antadesign/anta/reset.css` | Modern small reset (box-sizing, margin reset, replaced-element block, form-control font inheritance, text-wrap defaults) plus Anta's typography opinions for `h1-h6`, `strong`, `ul / ol / menu`, `a` / link states. Lives in `@layer anta`. | You already have a reset and don't want Anta's typography defaults. |
 | `@antadesign/anta/elements` | Side-effect import that registers `<a-progress>`, `<a-text>`, `<a-icon>` as custom elements *and* attaches their per-element CSS (also in `@layer anta`). | You're rendering Anta only on the server (no DOM) and never hydrating. |
 | `@antadesign/anta` | The JSX wrappers (`Progress`, `Text`, `Icon`) — typed React/Preact components that emit `<a-*>` tags. | You're writing the `<a-*>` elements by hand and don't need a JSX layer. |
 
-The chain matters: the per-element CSS that ships with `/elements` references variables like `var(--text-1)` and `var(--bg-base)`. Those variables are *only defined* by `tokens.css`. Skip the tokens import and the components render with whatever the surrounding cascade provides — usually nothing styled at all.
+The chain matters: the per-element CSS that ships with `/elements` references variables like `var(--text-1)` and `var(--bg-2)`. Those variables are *only defined* by `tokens.css`. Skip the tokens import and the components render with whatever the surrounding cascade provides — usually nothing styled at all.
+
+`@antadesign/anta/elements` registers **all** elements — convenient, but it includes every element's code (and deps). To keep your bundle lean, import only the elements you use from their per-element entry points instead: `import '@antadesign/anta/elements/a-tooltip'` registers just `<a-tooltip>` **and loads just its CSS**. Unused elements — and their dependencies, e.g. `lottie-web` (needed only by `<a-sticker-animated>`) — then never enter your bundle. See [Registering elements](#registering-elements).
 
 ### Cascade layers
 
@@ -70,6 +72,15 @@ The JSX wrappers (React components) as `Progress` render custom DOM elements as
 import '@antadesign/anta/elements'  // auto-registers all elements
 ```
 
+**Register only what you use.** `/elements` is the all-in-one convenience import. To trim your bundle, import the specific element entry points instead — each registers just that element and loads just its CSS:
+
+```ts
+import '@antadesign/anta/elements/a-tooltip'  // only <a-tooltip> + its CSS
+import '@antadesign/anta/elements/a-button'   // only <a-button> + its CSS
+```
+
+Both styles are side-effect imports (the act of importing registers the element), and both are idempotent and SSR-safe. The granular form keeps unused elements — and their dependencies, e.g. `lottie-web`, which only `<a-sticker-animated>` pulls in — out of your bundle.
+
 The cleanest pattern is a **static, synchronous import at your app's entry file** — outside any component, outside any hook:
 
 ```ts

package/dist/components/Button.d.ts

@@ -0,0 +1,113 @@
+import type { BaseProps } from "../general_types";
+import type { IconShape } from '../elements/a-icon.shapes';
+/** Always-allowed props, independent of content/submit/priority mode. */
+export type BaseButtonProps = {
+    /** Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
+     *  for a one-off custom tone. Primary uses the color as-is; secondary,
+     *  tertiary, and quaternary take its hue and pin lightness/chroma to the
+     *  brand curve so any input stays legible.
+     *  @defaultValue neutral */
+    tone?: 'neutral' | 'brand' | 'critical' | 'info' | 'success' | 'warning' | (string & {});
+    /** Size variant. small=24px, medium=28px, large=32px. Omit the
+     *  attribute or pass `'medium'` for the default — both render
+     *  identically and emit no DOM attribute.
+     *  @defaultValue medium */
+    size?: 'small' | 'medium' | 'large';
+    /** Show a rotating loading indicator. Blocks clicks. */
+    loading?: boolean;
+    /** Disable the button. */
+    disabled?: boolean;
+    /** Toggled-on / pressed state, e.g. for filter chips. */
+    selected?: boolean;
+    /** Click handler. */
+    onClick?: (e: any) => void;
+    /** Tab order. The button is keyboard-focusable by default (`0`) and
+     *  becomes `-1` automatically while `disabled` — `<a-button>` and
+     *  `<a role="button">` aren't focusable without an explicit tabindex.
+     *  @defaultValue 0 */
+    tabIndex?: number;
+};
+/** Content axis — slots render in this order inside the button:
+ *  `icon` → `label` → `children` → `iconTrailing`. Pass `icon` alone
+ *  for an icon-only button (the CSS detects this structurally via
+ *  `:has(> a-icon:only-child)` and gives the host square padding +
+ *  min-size pin). */
+export type ContentMode = {
+    /** Label text. Renders between the leading icon and `children`. */
+    label?: string;
+    /** Leading icon shape. When set alone (no `label`, no `iconTrailing`, no
+     *  `children`), the button renders as a square icon-only control and
+     *  the wrapper auto-supplies `aria-label={icon}` (override by passing
+     *  your own `aria-label`). */
+    icon?: IconShape;
+    /** Trailing icon shape. Renders after `children`, last in the slot order. */
+    iconTrailing?: IconShape;
+};
+/** Submit axis — anchors (href) don't carry form-submission props; buttons
+ *  don't carry anchor props. */
+export type SubmitMode = {
+    /** Renders as `<a role="button">` instead of `<a-button>`. */
+    href: string;
+    /** Anchor target. */
+    target?: string;
+    /** Anchor rel. */
+    rel?: string;
+    /** Anchor download attribute. Empty string / `true` triggers a download with the resource's default name; a string overrides the filename. */
+    download?: string | boolean;
+    /** Space-separated URLs the browser pings on navigation. */
+    ping?: string;
+    type?: never;
+    form?: never;
+} | {
+    href?: never;
+    target?: never;
+    rel?: never;
+    download?: never;
+    ping?: never;
+    /** Form submission type. */
+    type?: 'button' | 'submit' | 'reset';
+    /** Form id when the button isn't a descendant of its form. */
+    form?: string;
+};
+/** Priority axis — `underline` only on `tertiary` / `quaternary`,
+ *  `paddingless` only on `quaternary`. */
+export type PriorityMode = {
+    /** Visual emphasis.
+     *  @defaultValue secondary */
+    priority?: 'primary' | 'secondary';
+    underline?: never;
+    paddingless?: never;
+} | {
+    priority: 'tertiary';
+    /** Underline style. */
+    underline?: 'solid' | 'dashed' | 'dotted';
+    paddingless?: never;
+} | {
+    priority: 'quaternary';
+    /** Underline style. */
+    underline?: 'solid' | 'dashed' | 'dotted';
+    /** Drops outer padding to zero. */
+    paddingless?: boolean;
+};
+export type ButtonProps = BaseButtonProps & PriorityMode & ContentMode & SubmitMode & BaseProps;
+/**
+ * Action button.
+ *
+ * Renders an `<a-button>` web component (or `<a role="button">` when
+ * `href` is set) with the design system's tone × priority matrix applied
+ * via CSS attributes.
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only)
+ * to register the underlying custom element.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Button label="Save" onClick={save} />
+ * ```
+ *
+ * @example Anchor styled as a button
+ * ```tsx
+ * <Button href="/docs" target="_blank" label="Read the docs" />
+ * ```
+ */
+export declare const Button: ({ priority, tone, underline, icon, iconTrailing, paddingless, label, size, loading, disabled, selected, href, type, form, className, style, children, ...rest }: ButtonProps) => any;

package/dist/components/Button.js

@@ -0,0 +1,100 @@
+import { Fragment, jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+const NAMED_TONES = /* @__PURE__ */ new Set([
+  "brand",
+  "neutral",
+  "critical",
+  "info",
+  "success",
+  "warning"
+]);
+const wrapChildren = (kids) => {
+  if (kids == null) return kids;
+  const arr = Array.isArray(kids) ? kids : [kids];
+  return arr.map((child, i) => {
+    const t = typeof child;
+    if (t === "string" || t === "number") {
+      return /* @__PURE__ */ jsx("a-button-label", { children: child }, i);
+    }
+    return child;
+  });
+};
+const Button = ({
+  priority,
+  tone,
+  underline,
+  icon,
+  iconTrailing,
+  paddingless,
+  label,
+  size,
+  loading,
+  disabled,
+  selected,
+  href,
+  type,
+  form,
+  className,
+  style,
+  children,
+  ...rest
+}) => {
+  const isCustomTone = tone != null && !NAMED_TONES.has(tone);
+  const computedStyle = isCustomTone ? { ...style, ["--button-tone-source"]: tone } : style;
+  const isIconOnly = icon != null && label == null && children == null && iconTrailing == null;
+  const sharedAttrs = {
+    priority,
+    tone,
+    underline,
+    // 'medium' (and unset) is the implicit default — emit no DOM attr.
+    size: size && size !== "medium" ? size : void 0,
+    // Boolean attributes: emit a presence attribute (empty string) when on,
+    // omit when off — `attr=""` is the canonical boolean-attribute form and
+    // renders consistently across React / Preact. The CSS matches these by
+    // presence (`[disabled]`, not `[disabled="true"]`), so any present form
+    // works. (ARIA attributes below stay string-valued — ARIA needs "true".)
+    paddingless: paddingless ? "" : void 0,
+    loading: loading ? "" : void 0,
+    disabled: disabled ? "" : void 0,
+    selected: selected ? "" : void 0,
+    tabIndex: disabled ? -1 : 0,
+    "aria-disabled": disabled || loading ? "true" : void 0,
+    "aria-busy": loading ? "true" : void 0,
+    "aria-pressed": selected ? "true" : void 0,
+    // Icon-only buttons get an accessible name from the icon shape;
+    // consumer's own `aria-label` (via ...rest) wins by spread order.
+    "aria-label": isIconOnly ? icon : void 0,
+    class: className,
+    style: computedStyle
+  };
+  const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
+    icon && /* @__PURE__ */ jsx("a-icon", { shape: icon, "aria-hidden": "true" }),
+    label != null && /* @__PURE__ */ jsx("a-button-label", { children: label }),
+    wrapChildren(children),
+    iconTrailing && /* @__PURE__ */ jsx("a-icon", { shape: iconTrailing, "aria-hidden": "true" })
+  ] });
+  if (href != null) {
+    return /* @__PURE__ */ jsx(
+      "a",
+      {
+        href,
+        role: "button",
+        ...sharedAttrs,
+        ...rest,
+        children: inner
+      }
+    );
+  }
+  return /* @__PURE__ */ jsx(
+    "a-button",
+    {
+      type,
+      form,
+      ...sharedAttrs,
+      ...rest,
+      children: inner
+    }
+  );
+};
+export {
+  Button
+};

package/dist/components/Button.module.css

@@ -0,0 +1,2 @@
+/* Layout lives in src/elements/a-button.css. Stub kept for symmetry
+ * with the other wrappers and as a landing pad for wrapper-only styles. */

package/dist/components/Icon.d.ts

@@ -5,7 +5,8 @@ export interface IconProps extends BaseProps {
      *  built-in icons plus any consumer-generated shapes (via the
      *  `IconShapes` interface module augmentation). */
     shape: IconShape;
-    /** Width and height in pixels. Defaults to `16`. */
+    /** Width and height in pixels.
+     *  @defaultValue 16 */
     size?: number;
     /** Accessible name for the icon. When set, the wrapper exposes
      *  `role="img"` and `aria-label={label}` so screen readers announce

package/dist/components/Progress.d.ts

@@ -2,9 +2,11 @@ import type { BaseProps } from "../general_types";
 export interface ProgressProps extends BaseProps {
     /** Current progress value. Negative values are clamped to 0. */
     value: number;
-    /** Upper bound of the range. Defaults to 100. */
+    /** Upper bound of the range.
+     *  @defaultValue 100 */
     max?: number;
-    /** Color variant. `'info'` applies a blue tint. */
+    /** Color variant. `'info'` applies a blue tint.
+     *  @defaultValue neutral */
     tone?: 'neutral' | 'info';
     /** Text label displayed after the percentage. */
     label?: string;

package/dist/components/Sticker.d.ts

@@ -0,0 +1,31 @@
+import type { BaseProps } from "../general_types";
+/** Base public props for stickers — shared by both static and animated.
+ *  Inherits `className` and `style` from `BaseProps`. The animated
+ *  variant (`StickerAnimated`) extends this with `paused`. */
+export interface StickerProps extends Omit<BaseProps, "children"> {
+    /** Edge length in pixels. Stickers are always square. Defaults to 256. */
+    size?: number;
+    label?: string;
+}
+/** ARIA attribute shape applied to sticker hosts — either meaningful
+ *  (`role="img"` + `aria-label`) or decorative (`aria-hidden="true"`). */
+export type StickerA11y = {
+    role?: string;
+    "aria-label"?: string;
+    "aria-hidden"?: "true";
+};
+/** Internal — supplied by the generated per-sticker module; the bound
+ *  SVG markup is the per-sticker payload. */
+interface StickerInternalProps extends StickerProps {
+    svg: string;
+}
+/**
+ * Internal renderer for static stickers. Generated `Sticker{Name}`
+ * exports under `@antadesign/anta/stickers` call this with their bound
+ * inline SVG markup. The `<a-sticker>` element renders the SVG into
+ * its shadow DOM; sizing is composed into the host's inline `style` as
+ * `--sticker-size` (the element doesn't mutate its own host — see the
+ * declarative-DOM rule in CLAUDE.md).
+ */
+export declare const Sticker: ({ svg, size, label, ...rest }: StickerInternalProps) => any;
+export {};

package/dist/components/Sticker.js

@@ -0,0 +1,17 @@
+import { jsx } from "@antadesign/anta/jsx-runtime";
+const Sticker = ({
+  svg,
+  size,
+  label,
+  ...rest
+}) => {
+  const a11y = label != null ? { role: "img", "aria-label": label } : { "aria-hidden": "true" };
+  const style = size != null ? {
+    ...rest.style,
+    ["--sticker-size"]: `${size}px`
+  } : rest.style;
+  return /* @__PURE__ */ jsx("a-sticker", { svg, ...a11y, ...rest, style });
+};
+export {
+  Sticker
+};

package/dist/components/StickerAnimated.d.ts

@@ -0,0 +1,23 @@
+import type { StickerProps } from "./Sticker";
+/** Public props for animated stickers — extends `StickerProps` with
+ *  `paused`. The static `Sticker` variant doesn't accept `paused`. */
+export interface StickerAnimatedProps extends StickerProps {
+    /** `true` freezes the animation at the current frame; a number freezes
+     *  at that time in seconds; omit (or `false`) to play. */
+    paused?: boolean | number;
+}
+/** Internal — the bound Lottie animation is supplied by the generated
+ *  per-sticker module as a JSON string. The element parses it once on
+ *  attribute set. */
+interface StickerAnimatedInternalProps extends StickerAnimatedProps {
+    animation: string;
+}
+/**
+ * Internal renderer for animated stickers. Generated
+ * `Sticker{Name}Animated` exports under `@antadesign/anta/stickers`
+ * call this with their bound Lottie JSON string. The
+ * `<a-sticker-animated>` element receives it as an attribute, parses
+ * it once, and drives a shadow-DOM canvas via dotLottie.
+ */
+export declare const StickerAnimated: ({ animation, size, paused, label, ...rest }: StickerAnimatedInternalProps) => any;
+export {};

package/dist/components/StickerAnimated.js

@@ -0,0 +1,28 @@
+import { jsx } from "@antadesign/anta/jsx-runtime";
+const StickerAnimated = ({
+  animation,
+  size,
+  paused,
+  label,
+  ...rest
+}) => {
+  const a11y = label != null ? { role: "img", "aria-label": label } : { "aria-hidden": "true" };
+  const pausedAttr = paused === true ? "" : typeof paused === "number" ? String(paused) : void 0;
+  const style = size != null ? {
+    ...rest.style,
+    ["--sticker-size"]: `${size}px`
+  } : rest.style;
+  return /* @__PURE__ */ jsx(
+    "a-sticker-animated",
+    {
+      animation,
+      paused: pausedAttr,
+      ...a11y,
+      ...rest,
+      style
+    }
+  );
+};
+export {
+  StickerAnimated
+};

package/dist/components/Text.d.ts

@@ -1,6 +1,7 @@
 import type { BaseProps } from "../general_types";
 export interface TextProps extends BaseProps {
-    /** Visual priority. Maps to text-1..text-5. Defaults to 'primary' (text-1). */
+    /** Visual priority. Maps to text-1..text-5 (`primary` = text-1).
+     *  @defaultValue primary */
     priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'quinary';
     /** Color tint. Applies the matching `--text-{N}-{tone}` palette. */
     tone?: 'brand' | 'success' | 'critical' | 'warning' | 'info';

package/dist/components/Title.d.ts

@@ -1,10 +1,12 @@
 import type { BaseProps } from "../general_types";
 export interface TitleProps extends BaseProps {
     /** Heading level, 1-6. Drives font-size, line-height, and vertical
-     *  rhythm. Also surfaced to assistive tech via `aria-level`. Defaults
-     *  to 2 (h1 is typically reserved for the page title). */
+     *  rhythm. Also surfaced to assistive tech via `aria-level`
+     *  (h1 is typically reserved for the page title).
+     *  @defaultValue 2 */
     level?: 1 | 2 | 3 | 4 | 5 | 6;
-    /** Visual priority. Maps to text-1..text-5. Defaults to 'primary' (text-1). */
+    /** Visual priority. Maps to text-1..text-5 (`primary` = text-1).
+     *  @defaultValue primary */
     priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'quinary';
     /** Color tint. Applies the matching `--text-{N}-{tone}` palette. */
     tone?: 'brand' | 'success' | 'critical' | 'warning' | 'info';
@@ -15,7 +17,7 @@ export interface TitleProps extends BaseProps {
  * Renders an `<a-title>` styled tag (no JS, no shadow DOM) with
  * `role="heading"` and `aria-level={level}` set by this wrapper for
  * accessibility. Children can be anything — text, icons, badges, links
- * — so there are no `leadingIcon` / `trailingIcon` props; just compose
+ * — so there are no `icon` / `iconTrailing` props; just compose
  * inside.
  *
  * Raw `<h1>`-`<h6>` get the same visual styling via `src/reset.css`,

package/dist/components/Tooltip.d.ts

@@ -0,0 +1,55 @@
+import type { BaseProps } from "../general_types";
+export interface TooltipProps extends BaseProps {
+    /** Tooltip content. Renders anything — text, markup, an icon + text.
+     *  Lives in the light DOM, so it's styleable with your own plain CSS. */
+    children?: React.ReactNode;
+    /** Show delay in milliseconds after hover / focus. Never use `0` — use
+     *  ~`50` for a near-instant tooltip (0 has caused issues in practice).
+     *  @defaultValue 250 */
+    delay?: number;
+    /** Which side of the anchor the bubble prefers. Auto-flips to the other
+     *  side when there isn't room.
+     *  @defaultValue bottom */
+    placement?: 'top' | 'bottom';
+    /** Pin the bubble under the anchor instead of following the cursor. */
+    static?: boolean;
+    /** Make the bubble hoverable and clickable — enables pointer events and
+     *  keeps it open while the cursor is over it, so its content (links,
+     *  buttons) can be interacted with. Implies `static` (an interactive
+     *  bubble can't follow the cursor). */
+    interactive?: boolean;
+}
+/**
+ * Tooltip — a small floating bubble that describes the element it's placed
+ * inside. Render `<Tooltip>` as a child of the element it annotates; it
+ * doesn't affect that element's layout.
+ *
+ * Shows on hover (after `delay`) and on keyboard focus; dismisses on mouse
+ * leave, blur, Escape, or when the anchor scrolls away. Follows the cursor
+ * by default — pass `static` to pin it under the anchor instead.
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only)
+ * to register the underlying custom element.
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { Tooltip } from '@antadesign/anta'
+ * import '@antadesign/anta/elements'
+ *
+ * <button>
+ *   Save
+ *   <Tooltip>Saves your work</Tooltip>
+ * </button>
+ * ```
+ *
+ * @example Pinned above, rich content
+ * ```tsx
+ * <span style={{ cursor: 'help' }}>
+ *   Status
+ *   <Tooltip placement="top" static>
+ *     <strong>Healthy</strong> — last checked 2m ago
+ *   </Tooltip>
+ * </span>
+ * ```
+ */
+export declare const Tooltip: ({ delay, placement, static: isStatic, interactive, className, children, ...rest }: TooltipProps) => any;

package/dist/components/Tooltip.js

@@ -0,0 +1,26 @@
+import { jsx } from "@antadesign/anta/jsx-runtime";
+const Tooltip = ({
+  delay,
+  placement,
+  static: isStatic,
+  interactive,
+  className,
+  children,
+  ...rest
+}) => {
+  return /* @__PURE__ */ jsx(
+    "a-tooltip",
+    {
+      delay: delay != null ? String(delay) : void 0,
+      placement: placement === "top" ? "top" : void 0,
+      static: isStatic ? "" : void 0,
+      interactive: interactive ? "" : void 0,
+      class: className,
+      ...rest,
+      children
+    }
+  );
+};
+export {
+  Tooltip
+};