@antadesign/anta 0.1.1-dev.5 → 0.1.1-dev.7

package/README.md

@@ -29,12 +29,12 @@ 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.
 
 ### Cascade layers
 
@@ -49,6 +49,19 @@ If you need a different order, declare it in your *own* CSS file that loads **be
 
 CSS custom properties (the `:root { --… }` declarations in `tokens.css`) stay unlayered so they take effect everywhere unconditionally.
 
+> **Gotcha: unlayered hard resets defeat Anta's element rules.**
+>
+> A snippet like this in your global CSS — common copy-paste from older reset guides — silently overrides every element rule Anta ships:
+>
+> ```css
+> *, *::before, *::after { box-sizing: border-box; }
+> * { margin: 0; }
+> ```
+>
+> Unlayered styles **always** beat layered ones in the cascade, regardless of specificity. So `* { margin: 0 }` outranks Anta's `caption { margin-bottom: 0.25em }`, `p { margin: 0 0 1em }`, `ul / ol` padding, and any other per-element default Anta provides — even though those use stronger selectors.
+>
+> If you're importing `@antadesign/anta/reset.css`, Anta already does the same universal `box-sizing` and margin reset, *inside* `@layer anta`. The element-level rules sitting on top are intentionally polite defaults — sensible out of the box, trivially overridable when you want something else (any rule in `@layer components` / `@layer utilities`, or any unlayered rule of your own that targets specific elements, wins automatically). **Delete the duplicate hard reset from your global CSS** so those defaults can apply. If you want to keep your own reset, wrap it in `@layer base { … }` so it sits below `anta` in the declared order and Anta's rules still win element-by-element.
+
 ## Registering elements
 
 The JSX wrappers (React components) as `Progress` render custom DOM elements as `<a-progress>`. The custom elements themselves must be registered with the browser **before** they appear in the DOM, and registration only works where `HTMLElement` exists — i.e. the UI thread of a real browser. **Node.js (SSR) and Worker threads don't have `HTMLElement`**, so the import is harmless in those environments: it does nothing — registration is skipped silently and the class uses a stand-in base instead of crashing — though it might extend your worker's bundle size a bit.

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,9 +1,13 @@
 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';
+    /** Type scale. `small` = 13/16, `medium` = 15/20, `large` = 17/24.
+     *  @defaultValue medium */
+    size?: 'small' | 'medium' | 'large';
     /** Render as inline-block instead of the default block element. */
     inline?: boolean;
     /** Truncate with a trailing ellipsis. `true` (or `1`) clamps to a
@@ -39,4 +43,4 @@ export interface TextProps extends BaseProps {
  * <Text truncate={3} expandable>…long paragraph…</Text>
  * ```
  */
-export declare const Text: ({ priority, tone, inline, truncate, expandable, className, style, children, ...rest }: TextProps) => any;
+export declare const Text: ({ priority, tone, size, inline, truncate, expandable, className, style, children, ...rest }: TextProps) => any;

package/dist/components/Text.js

@@ -1,5 +1,5 @@
 import { jsx } from "@antadesign/anta/jsx-runtime";
-const Text = ({ priority, tone, inline, truncate, expandable, className, style, children, ...rest }) => {
+const Text = ({ priority, tone, size, inline, truncate, expandable, className, style, children, ...rest }) => {
   const lineCount = typeof truncate === "number" ? truncate : truncate ? 1 : null;
   const computedStyle = lineCount != null ? { ...style, ["--line-clamp"]: lineCount } : style;
   return /* @__PURE__ */ jsx(
@@ -7,6 +7,7 @@ const Text = ({ priority, tone, inline, truncate, expandable, className, style,
     {
       priority,
       tone,
+      size,
       inline: inline ? "" : void 0,
       truncate: lineCount != null ? String(lineCount) : void 0,
       expandable: expandable && truncate ? "" : void 0,

package/dist/components/Title.d.ts

@@ -0,0 +1,43 @@
+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`
+     *  (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 (`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';
+}
+/**
+ * Block-level heading with level 1-6, priority, and tone.
+ *
+ * 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 `icon` / `iconTrailing` props; just compose
+ * inside.
+ *
+ * Raw `<h1>`-`<h6>` get the same visual styling via `src/reset.css`,
+ * so use a real heading tag if SEO matters and you don't need the
+ * `tone` / `priority` props.
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only)
+ * so the CSS ships with the page.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Title level={1}>Page title</Title>
+ * <Title level={2} tone="brand">Section</Title>
+ * ```
+ *
+ * @example With children beyond text
+ * ```tsx
+ * <Title level={3}>
+ *   <Icon shape="bookmark" /> Saved items
+ * </Title>
+ * ```
+ */
+export declare const Title: ({ level, priority, tone, className, style, children, ...rest }: TitleProps) => any;

package/dist/components/Title.js

@@ -0,0 +1,20 @@
+import { jsx } from "@antadesign/anta/jsx-runtime";
+const Title = ({ level = 2, priority, tone, className, style, children, ...rest }) => {
+  return /* @__PURE__ */ jsx(
+    "a-title",
+    {
+      level: String(level),
+      priority,
+      tone,
+      role: "heading",
+      "aria-level": level,
+      class: className,
+      style,
+      ...rest,
+      children
+    }
+  );
+};
+export {
+  Title
+};