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

package/README.md

@@ -36,6 +36,8 @@ Anta exposes four independent imports. Tokens + elements + the JSX layer are the
 
 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
 
 Anta's reset and element CSS live in `@layer anta`. `tokens.css` pre-declares an order of `@layer base, anta, components, utilities;`, which keeps Anta's defaults above any preflight resets (Tailwind's `@layer base`, Normalize, etc.) while letting your own `@layer components` rules and utility-class frameworks like Tailwind (`@layer utilities`) override Anta when you ask them to.
@@ -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/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
+};

package/dist/elements/a-button.d.ts

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-button.css";
 declare global {
     interface Document {
         hasKeyListenerForAButton?: boolean;

package/dist/elements/a-button.js

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-button.css";
 class AButtonElement extends HTMLElementBase {
   connectedCallback() {
     if (!document.hasKeyListenerForAButton) {
@@ -70,6 +71,7 @@ function register_a_button() {
     customElements.define("a-button", AButtonElement);
   }
 }
+register_a_button();
 export {
   AButtonElement,
   register_a_button

package/dist/elements/a-icon.d.ts

@@ -1,4 +1,6 @@
 import { HTMLElementBase } from '../anta_helpers';
+import './a-icon.css';
+import './a-icon.shapes.css';
 /**
  * `<a-icon shape="…">` — pure declarative icon element.
  *

package/dist/elements/a-icon.js

@@ -1,4 +1,6 @@
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-icon.css";
+import "./a-icon.shapes.css";
 class AIconElement extends HTMLElementBase {
 }
 function register_a_icon() {
@@ -7,6 +9,7 @@ function register_a_icon() {
     customElements.define("a-icon", AIconElement);
   }
 }
+register_a_icon();
 export {
   AIconElement,
   register_a_icon

package/dist/elements/a-progress.d.ts

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from '../anta_helpers';
+import './a-progress.css';
 export declare class AProgressElement extends HTMLElementBase {
     static observedAttributes: string[];
     indicator: HTMLDivElement;

package/dist/elements/a-progress.js

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-progress.css";
 class AProgressElement extends HTMLElementBase {
   static observedAttributes = ["value", "max", "tone"];
   indicator;
@@ -60,6 +61,7 @@ function register_a_progress() {
     customElements.define("a-progress", AProgressElement);
   }
 }
+register_a_progress();
 export {
   AProgressElement,
   register_a_progress

package/dist/elements/a-sticker-animated.d.ts

@@ -1,5 +1,6 @@
 import { type AnimationItem } from 'lottie-web';
 import { HTMLElementBase } from '../anta_helpers';
+import './a-sticker-animated.css';
 /**
  * `<a-sticker-animated>` — Lottie-driven sticker carrier.
  *

package/dist/elements/a-sticker-animated.js

@@ -1,5 +1,6 @@
 import lottie from "lottie-web";
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-sticker-animated.css";
 class AStickerAnimatedElement extends HTMLElementBase {
   static observedAttributes = ["animation", "paused"];
   container;
@@ -73,6 +74,7 @@ function register_a_sticker_animated() {
     customElements.define("a-sticker-animated", AStickerAnimatedElement);
   }
 }
+register_a_sticker_animated();
 export {
   AStickerAnimatedElement,
   register_a_sticker_animated

package/dist/elements/a-sticker.d.ts

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from '../anta_helpers';
+import './a-sticker.css';
 /**
  * `<a-sticker>` — static sticker carrier.
  *

package/dist/elements/a-sticker.js

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-sticker.css";
 class AStickerElement extends HTMLElementBase {
   static observedAttributes = ["svg"];
   container;
@@ -24,6 +25,7 @@ function register_a_sticker() {
     customElements.define("a-sticker", AStickerElement);
   }
 }
+register_a_sticker();
 export {
   AStickerElement,
   register_a_sticker

package/dist/elements/a-text.d.ts

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from '../anta_helpers';
+import './a-text.css';
 export declare class ATextElement extends HTMLElementBase {
     static observedAttributes: string[];
     private slotEl;

package/dist/elements/a-text.js

@@ -1,4 +1,5 @@
 import { HTMLElementBase } from "../anta_helpers";
+import "./a-text.css";
 const SHADOW_STYLE = `
   :host {
     display: block;
@@ -137,6 +138,7 @@ function register_a_text() {
     customElements.define("a-text", ATextElement);
   }
 }
+register_a_text();
 export {
   ATextElement,
   register_a_text

package/dist/elements/a-tooltip.css

@@ -0,0 +1,42 @@
+@layer anta {
+  /* Before the custom element upgrades on the client, <a-tooltip> is an
+     unknown inline element and its content would flash *inside the anchor*.
+     Hide it until defined; once defined this stops matching and the shadow
+     `:host { display: contents }` governs (content renders only in the
+     popover via the slot). */
+  a-tooltip:not(:defined) {
+    display: none;
+  }
+
+  /* Tooltip exposes only the box "chrome" that lives inside the shadow
+     popover and is therefore impossible to reach with plain consumer CSS.
+     The bubble's content is slotted light DOM, so its font / colour / size
+     are already styleable from the page — those are intentionally NOT
+     tokens. These custom properties inherit across the shadow boundary
+     into the popover container (see a-tooltip.ts). The host itself draws
+     nothing and stays out of layout (`:host { display: contents }` in the
+     shadow style). */
+  a-tooltip {
+    /* Frosted translucent surface (matches the legacy look): a mostly-
+       opaque white that, paired with the container's `backdrop-filter:
+       blur(8px)`, reads as a frosted bubble over the page. --bg-1 is
+       #ffffff in light / #000000 in dark, so this flips to a dark frost
+       automatically (alpha is dialed down in the .dark override). */
+    --tooltip-bg: color-mix(in oklch, var(--bg-1) 80%, transparent);
+    --tooltip-shadow:
+      0 1px 8px color-mix(in oklch, var(--text-1) 15%, transparent),
+      0 0 1px color-mix(in oklch, var(--text-1) 50%, transparent);
+    --tooltip-radius: 3px;
+    --tooltip-max-width: min(calc(100vw - 20px), 80ch);
+  }
+
+  /* Dark: a slightly more transparent black frost. A solid black cast shadow
+     for lift, plus an inset 1px white ring so the bubble's edge stays crisp
+     against dark page content. */
+  .dark a-tooltip {
+    --tooltip-bg: color-mix(in oklch, var(--bg-1) 70%, transparent);
+    --tooltip-shadow:
+      0 2px 16px color-mix(in oklch, black 70%, transparent),
+      inset 0 0 0 1px color-mix(in oklch, white 25%, transparent);
+  }
+}

package/dist/elements/a-tooltip.d.ts

@@ -0,0 +1,61 @@
+import { HTMLElementBase } from '../anta_helpers';
+import './a-tooltip.css';
+export declare class ATooltipElement extends HTMLElementBase {
+    static observedAttributes: string[];
+    /** Shadow-internal popover surface — the only thing we ever mutate. */
+    private container;
+    private anchor;
+    listening: boolean;
+    private shown;
+    private lastMouse?;
+    private debouncedShow?;
+    private teardown?;
+    private closeTimer?;
+    private fading;
+    private fadeTimer?;
+    private docMoveBound;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string): void;
+    /** (Re)build the show debounce with the CURRENT `delay` (rebuilt when the
+     *  `delay` attribute changes). Re-armed on each hover move (trailing), and
+     *  fed the latest cursor event, so it shows at the cursor and so moving back
+     *  onto an anchor after the tooltip was dismissed re-arms it. */
+    private makeDebouncedShow;
+    /** The element's OWN window / document. The class may be defined in a
+     *  different realm than the element lives in (e.g. 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.
+     *  Everything viewport- or document-scoped (clamping, scroll/key/move
+     *  listeners) must go through these so it's correct in any frame. */
+    private get view();
+    private get doc();
+    private get isInteractive();
+    /** Pinned under the anchor (no cursor-following). Interactive implies this —
+     *  you can't move into a bubble that's chasing the cursor. */
+    private get isStatic();
+    private get prefersTop();
+    private get delay();
+    private positionToTarget;
+    private positionToMouse;
+    private position;
+    show: (e?: MouseEvent) => void;
+    hide: () => void;
+    /** While shown, track the cursor even after it has left the anchor (during
+     *  the close delay). Cursor-following only — static/interactive bubbles
+     *  stay pinned. */
+    private onDocMove;
+    /** Hide after CLOSE_DELAY unless something cancels it first (re-enter, or
+     *  another tooltip claiming the slot). Lets the bubble bridge the gap to a
+     *  neighbouring anchor — and survive the trip into an interactive bubble. */
+    private scheduleHide;
+    private cancelHide;
+    private onKeyDown;
+    /** Open now if another tooltip is hot (skip delay), else (re)arm the delayed
+     *  show with the latest cursor event. */
+    private trigger;
+    setupListeners(): void;
+    teardownListeners(): void;
+}
+export declare function register_a_tooltip(): void;

package/dist/elements/a-tooltip.js

@@ -0,0 +1,411 @@
+import { HTMLElementBase } from "../anta_helpers";
+import { debounce } from "es-toolkit";
+import "./a-tooltip.css";
+const MARGIN = 4;
+const CURSOR_SIZE = 16;
+const PADDING_X = 8;
+const DEFAULT_DELAY = 250;
+const FADE_MS = 150;
+const GRACE_MS = 300;
+const CLOSE_DELAY = 120;
+let currentOpen = null;
+let graceTimer;
+function graceActive() {
+  return graceTimer !== void 0;
+}
+function isHot() {
+  return currentOpen !== null || graceActive();
+}
+function clearGrace() {
+  if (graceTimer !== void 0) {
+    clearTimeout(graceTimer);
+    graceTimer = void 0;
+  }
+}
+function claimOpen(el) {
+  if (currentOpen && currentOpen !== el) currentOpen.hide();
+  currentOpen = el;
+  clearGrace();
+}
+function releaseOpen(el) {
+  if (currentOpen !== el) return;
+  currentOpen = null;
+  clearGrace();
+  graceTimer = setTimeout(() => {
+    graceTimer = void 0;
+  }, GRACE_MS);
+}
+const anchorToTooltip = /* @__PURE__ */ new WeakMap();
+function handleIntersection(entries) {
+  for (const entry of entries) {
+    const tooltip = anchorToTooltip.get(entry.target);
+    if (!tooltip) continue;
+    if (!tooltip.listening && entry.isIntersecting) {
+      requestAnimationFrame(() => tooltip.setupListeners());
+    } else if (tooltip.listening && !entry.isIntersecting) {
+      requestAnimationFrame(() => tooltip.teardownListeners());
+    }
+  }
+}
+const lazyObserver = typeof IntersectionObserver !== "undefined" ? new IntersectionObserver(handleIntersection, { root: null, rootMargin: "0px", threshold: 0 }) : null;
+class ATooltipElement extends HTMLElementBase {
+  // Observe `delay` so changing it at runtime — e.g. the docs playground
+  // patches the attribute on the live element — rebuilds the show debounce
+  // with the new value instead of keeping the one captured at setup.
+  static observedAttributes = ["delay"];
+  /** Shadow-internal popover surface — the only thing we ever mutate. */
+  container;
+  anchor = null;
+  listening = false;
+  shown = false;
+  lastMouse;
+  debouncedShow;
+  teardown;
+  closeTimer;
+  fading = false;
+  fadeTimer;
+  docMoveBound = false;
+  constructor() {
+    super();
+    const shadow = this.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = `
+      :host { display: contents; }
+
+      .container {
+        --_dur: ${FADE_MS}ms;
+
+        position: fixed;
+        left: 0;
+        top: 0;
+        margin: 0;
+        box-sizing: border-box;
+        width: fit-content;
+        max-width: var(--tooltip-max-width, min(calc(100vw - 20px), 80ch));
+        max-height: calc(100vh - 20px);
+        overflow: clip;
+        pointer-events: none;
+        text-align: left;
+
+        background: var(--tooltip-bg, Canvas);
+        color: var(--text-1, CanvasText);
+        box-shadow: var(--tooltip-shadow, 0 1px 8px rgba(0, 0, 0, 0.2));
+        backdrop-filter: blur(8px);
+        padding: 5px 8px;
+        border: none;
+        border-radius: var(--tooltip-radius, 3px);
+        outline: none;
+
+        font-size: 14px;
+        line-height: 130%;
+        font-weight: 400;
+        white-space: break-spaces;
+        word-break: break-word;
+        overflow-wrap: break-word;
+
+        /* Clean enter/exit fade. allow-discrete keeps the bubble rendered
+           through its fade-out after hidePopover(), and @starting-style
+           gives every open a from-opacity:0 \u2014 so the first paint at a
+           not-yet-computed transform is invisible (no flash at a stale
+           spot), and re-appearing is always clean. */
+        opacity: 0;
+        transition:
+          opacity var(--_dur) ease,
+          overlay var(--_dur) ease allow-discrete,
+          display var(--_dur) ease allow-discrete;
+      }
+
+      .container:popover-open { opacity: 1; }
+
+      @starting-style {
+        .container:popover-open { opacity: 0; }
+      }
+
+      /* Interactive tooltips accept pointer events so their content (links,
+         buttons) is clickable; the default click-through bubble does not. */
+      :host([interactive]) .container { pointer-events: auto; }
+    `;
+    this.container = document.createElement("div");
+    this.container.className = "container";
+    this.container.setAttribute("popover", "manual");
+    this.container.setAttribute("role", "tooltip");
+    this.container.append(document.createElement("slot"));
+    this.container.addEventListener("mouseenter", () => {
+      if (this.isInteractive) this.cancelHide();
+    });
+    this.container.addEventListener("mouseleave", () => {
+      if (this.isInteractive && this.shown) this.scheduleHide();
+    });
+    shadow.append(style, this.container);
+  }
+  connectedCallback() {
+    const parent = this.parentElement;
+    if (!parent) return;
+    this.anchor = parent;
+    anchorToTooltip.set(parent, this);
+    lazyObserver?.observe(parent);
+  }
+  disconnectedCallback() {
+    this.hide();
+    if (this.fadeTimer !== void 0) {
+      clearTimeout(this.fadeTimer);
+      this.fadeTimer = void 0;
+    }
+    this.fading = false;
+    if (this.docMoveBound) {
+      this.doc.removeEventListener("mousemove", this.onDocMove);
+      this.docMoveBound = false;
+    }
+    this.teardownListeners();
+    if (this.anchor) {
+      if (anchorToTooltip.get(this.anchor) === this) {
+        anchorToTooltip.delete(this.anchor);
+        lazyObserver?.unobserve(this.anchor);
+      }
+      this.anchor = null;
+    }
+  }
+  attributeChangedCallback(name) {
+    if (name === "delay" && this.listening) this.makeDebouncedShow();
+  }
+  /** (Re)build the show debounce with the CURRENT `delay` (rebuilt when the
+   *  `delay` attribute changes). Re-armed on each hover move (trailing), and
+   *  fed the latest cursor event, so it shows at the cursor and so moving back
+   *  onto an anchor after the tooltip was dismissed re-arms it. */
+  makeDebouncedShow() {
+    this.debouncedShow?.cancel();
+    this.debouncedShow = debounce((e) => this.show(e), this.delay);
+  }
+  /** The element's OWN window / document. The class may be defined in a
+   *  different realm than the element lives in (e.g. 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.
+   *  Everything viewport- or document-scoped (clamping, scroll/key/move
+   *  listeners) must go through these so it's correct in any frame. */
+  get view() {
+    return this.ownerDocument?.defaultView ?? window;
+  }
+  get doc() {
+    return this.ownerDocument ?? document;
+  }
+  get isInteractive() {
+    return this.hasAttribute("interactive");
+  }
+  /** Pinned under the anchor (no cursor-following). Interactive implies this —
+   *  you can't move into a bubble that's chasing the cursor. */
+  get isStatic() {
+    return this.hasAttribute("static") || this.isInteractive;
+  }
+  get prefersTop() {
+    return this.getAttribute("placement") === "top";
+  }
+  get delay() {
+    const attr = this.getAttribute("delay");
+    if (attr == null) return DEFAULT_DELAY;
+    const n = parseInt(attr, 10);
+    return Number.isFinite(n) ? n : DEFAULT_DELAY;
+  }
+  // --- positioning (sets only the shadow container's own transform) ---
+  positionToTarget = () => {
+    requestAnimationFrame(() => {
+      if (!this.anchor || !this.shown) return;
+      const a = this.anchor.getBoundingClientRect();
+      const box = this.container.getBoundingClientRect();
+      const view = this.view;
+      const vw = view.innerWidth;
+      const vh = view.innerHeight;
+      let left = a.left;
+      if (left + box.width > vw) left = vw - box.width - MARGIN;
+      left = Math.max(MARGIN, left);
+      let top;
+      if (this.prefersTop) {
+        top = a.top - box.height - MARGIN;
+        if (top < MARGIN) top = a.bottom + MARGIN;
+      } else {
+        top = a.bottom + MARGIN;
+        if (top + box.height > vh) top = a.top - box.height - MARGIN;
+      }
+      top = Math.max(MARGIN, top);
+      this.container.style.transform = `translate(${Math.round(left)}px, ${Math.round(top)}px)`;
+    });
+  };
+  positionToMouse = (e) => {
+    requestAnimationFrame(() => {
+      if (!this.shown && !this.fading) return;
+      const box = this.container.getBoundingClientRect();
+      const view = this.view;
+      const vw = view.innerWidth;
+      const vh = view.innerHeight;
+      let left = e.clientX - PADDING_X;
+      if (left + box.width > vw) left = vw - box.width - MARGIN;
+      left = Math.max(MARGIN, left);
+      let top;
+      if (this.prefersTop) {
+        top = e.clientY - box.height - MARGIN * 2;
+        if (top < MARGIN) top = e.clientY + CURSOR_SIZE;
+      } else {
+        top = e.clientY + CURSOR_SIZE;
+        if (top + box.height > vh) top = e.clientY - box.height - MARGIN * 2;
+      }
+      top = Math.max(MARGIN, top);
+      this.container.style.transform = `translate(${Math.round(left)}px, ${Math.round(top)}px)`;
+    });
+  };
+  position(e) {
+    if (!this.isStatic && e) this.positionToMouse(e);
+    else this.positionToTarget();
+  }
+  // --- show / hide ---
+  show = (e) => {
+    if (!this.anchor) return;
+    this.cancelHide();
+    if (currentOpen && currentOpen !== this && this.anchor.contains(currentOpen.anchor)) {
+      return;
+    }
+    claimOpen(this);
+    if (!this.shown) {
+      this.shown = true;
+      this.fading = false;
+      if (this.fadeTimer !== void 0) {
+        clearTimeout(this.fadeTimer);
+        this.fadeTimer = void 0;
+      }
+      this.container.showPopover();
+      this.view.addEventListener("scroll", this.hide, { capture: true, passive: true });
+      this.doc.addEventListener("keydown", this.onKeyDown, true);
+      if (!this.docMoveBound) {
+        this.doc.addEventListener("mousemove", this.onDocMove);
+        this.docMoveBound = true;
+      }
+    }
+    this.position(e);
+  };
+  hide = () => {
+    this.cancelHide();
+    if (!this.shown) return;
+    this.shown = false;
+    this.container.hidePopover();
+    this.view.removeEventListener("scroll", this.hide, { capture: true });
+    this.doc.removeEventListener("keydown", this.onKeyDown, true);
+    this.fading = true;
+    if (this.fadeTimer !== void 0) clearTimeout(this.fadeTimer);
+    this.fadeTimer = setTimeout(() => {
+      this.fading = false;
+      this.fadeTimer = void 0;
+      if (this.docMoveBound) {
+        this.doc.removeEventListener("mousemove", this.onDocMove);
+        this.docMoveBound = false;
+      }
+    }, FADE_MS);
+    releaseOpen(this);
+  };
+  /** While shown, track the cursor even after it has left the anchor (during
+   *  the close delay). Cursor-following only — static/interactive bubbles
+   *  stay pinned. */
+  onDocMove = (e) => {
+    if ((this.shown || this.fading) && !this.isStatic) {
+      this.lastMouse = e;
+      this.positionToMouse(e);
+    }
+  };
+  /** Hide after CLOSE_DELAY unless something cancels it first (re-enter, or
+   *  another tooltip claiming the slot). Lets the bubble bridge the gap to a
+   *  neighbouring anchor — and survive the trip into an interactive bubble. */
+  scheduleHide = () => {
+    this.cancelHide();
+    this.closeTimer = setTimeout(() => {
+      this.closeTimer = void 0;
+      this.hide();
+    }, CLOSE_DELAY);
+  };
+  cancelHide() {
+    if (this.closeTimer !== void 0) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = void 0;
+    }
+  }
+  onKeyDown = (e) => {
+    if (e.key === "Escape") this.hide();
+  };
+  /** Open now if another tooltip is hot (skip delay), else (re)arm the delayed
+   *  show with the latest cursor event. */
+  trigger(e) {
+    if (isHot()) {
+      this.debouncedShow?.cancel();
+      this.show(e);
+    } else {
+      this.debouncedShow?.(e);
+    }
+  }
+  // --- lazy listener wiring (called by the intersection observer) ---
+  setupListeners() {
+    if (this.listening || !this.anchor) {
+      this.listening = true;
+      return;
+    }
+    const anchor = this.anchor;
+    const view = this.view;
+    const doc = this.doc;
+    this.makeDebouncedShow();
+    const onMouseMove = (e) => {
+      this.lastMouse = e;
+      if (this.shown) {
+        if (!this.isStatic) this.positionToMouse(e);
+      } else {
+        this.trigger(e);
+      }
+    };
+    const onLeave = () => {
+      this.debouncedShow?.cancel();
+      anchor.removeEventListener("mousemove", onMouseMove);
+      anchor.removeEventListener("mouseleave", onLeave);
+      anchor.removeEventListener("blur", onLeave);
+      view.removeEventListener("pagehide", onLeave);
+      doc.removeEventListener("visibilitychange", onLeave);
+      this.scheduleHide();
+    };
+    const onEnter = (e) => {
+      this.lastMouse = e;
+      anchor.addEventListener("mousemove", onMouseMove);
+      anchor.addEventListener("mouseleave", onLeave);
+      view.addEventListener("pagehide", onLeave);
+      doc.addEventListener("visibilitychange", onLeave);
+      this.trigger(e);
+    };
+    const onFocus = () => {
+      anchor.addEventListener("blur", onLeave);
+      view.addEventListener("pagehide", onLeave);
+      doc.addEventListener("visibilitychange", onLeave);
+      this.trigger();
+    };
+    anchor.addEventListener("mouseenter", onEnter);
+    anchor.addEventListener("focus", onFocus);
+    this.teardown = () => {
+      this.debouncedShow?.cancel();
+      anchor.removeEventListener("mousemove", onMouseMove);
+      anchor.removeEventListener("mouseenter", onEnter);
+      anchor.removeEventListener("mouseleave", onLeave);
+      anchor.removeEventListener("focus", onFocus);
+      anchor.removeEventListener("blur", onLeave);
+      view.removeEventListener("pagehide", onLeave);
+      doc.removeEventListener("visibilitychange", onLeave);
+      this.listening = false;
+    };
+    this.listening = true;
+  }
+  teardownListeners() {
+    this.teardown?.();
+    this.teardown = void 0;
+  }
+}
+function register_a_tooltip() {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get("a-tooltip")) {
+    customElements.define("a-tooltip", ATooltipElement);
+  }
+}
+register_a_tooltip();
+export {
+  ATooltipElement,
+  register_a_tooltip
+};

package/dist/elements/index.d.ts

@@ -1,14 +1,24 @@
-import './a-progress.css';
-import './a-text.css';
-import './a-title.css';
-import './a-icon.css';
-import './a-icon.shapes.css';
-import './a-button.css';
-import './a-sticker.css';
-import './a-sticker-animated.css';
+/**
+ * Barrel: registers ALL Anta custom elements (the convenience path).
+ *
+ * Each `a-{name}` module self-registers and imports its own CSS when loaded,
+ * so re-exporting them here (which evaluates each module) registers the whole
+ * set + injects every element's CSS. Importing this barrel for side effects —
+ * `import '@antadesign/anta/elements'` — gives you everything.
+ *
+ * For a SMALLER footprint, import just the element(s) you use instead:
+ *   import '@antadesign/anta/elements/a-tooltip'   // registers a-tooltip + its CSS, nothing else
+ * That granular path pulls in only that element's code (e.g. it won't drag in
+ * `lottie-web`, which only `a-sticker-animated` needs).
+ *
+ * Must only be imported client-side — registration is guarded against missing
+ * `customElements` (SSR), but there's no reason to load it server-side.
+ */
 export { AProgressElement, register_a_progress } from './a-progress';
 export { ATextElement, register_a_text } from './a-text';
 export { AIconElement, register_a_icon } from './a-icon';
 export { AButtonElement, register_a_button } from './a-button';
 export { AStickerElement, register_a_sticker } from './a-sticker';
 export { AStickerAnimatedElement, register_a_sticker_animated } from './a-sticker-animated';
+export { ATooltipElement, register_a_tooltip } from './a-tooltip';
+import './a-title.css';

package/dist/elements/index.js

@@ -1,31 +1,11 @@
-import { register_a_progress } from "./a-progress";
-import { register_a_text } from "./a-text";
-import { register_a_icon } from "./a-icon";
-import { register_a_button } from "./a-button";
-import { register_a_sticker } from "./a-sticker";
-import { register_a_sticker_animated } from "./a-sticker-animated";
-import "./a-progress.css";
-import "./a-text.css";
+import { AProgressElement, register_a_progress } from "./a-progress";
+import { ATextElement, register_a_text } from "./a-text";
+import { AIconElement, register_a_icon } from "./a-icon";
+import { AButtonElement, register_a_button } from "./a-button";
+import { AStickerElement, register_a_sticker } from "./a-sticker";
+import { AStickerAnimatedElement, register_a_sticker_animated } from "./a-sticker-animated";
+import { ATooltipElement, register_a_tooltip } from "./a-tooltip";
 import "./a-title.css";
-import "./a-icon.css";
-import "./a-icon.shapes.css";
-import "./a-button.css";
-import "./a-sticker.css";
-import "./a-sticker-animated.css";
-import { AProgressElement, register_a_progress as register_a_progress2 } from "./a-progress";
-import { ATextElement, register_a_text as register_a_text2 } from "./a-text";
-import { AIconElement, register_a_icon as register_a_icon2 } from "./a-icon";
-import { AButtonElement, register_a_button as register_a_button2 } from "./a-button";
-import { AStickerElement, register_a_sticker as register_a_sticker2 } from "./a-sticker";
-import { AStickerAnimatedElement, register_a_sticker_animated as register_a_sticker_animated2 } from "./a-sticker-animated";
-if (typeof customElements !== "undefined") {
-  register_a_progress();
-  register_a_text();
-  register_a_icon();
-  register_a_button();
-  register_a_sticker();
-  register_a_sticker_animated();
-}
 export {
   AButtonElement,
   AIconElement,
@@ -33,10 +13,12 @@ export {
   AStickerAnimatedElement,
   AStickerElement,
   ATextElement,
-  register_a_button2 as register_a_button,
-  register_a_icon2 as register_a_icon,
-  register_a_progress2 as register_a_progress,
-  register_a_sticker2 as register_a_sticker,
-  register_a_sticker_animated2 as register_a_sticker_animated,
-  register_a_text2 as register_a_text
+  ATooltipElement,
+  register_a_button,
+  register_a_icon,
+  register_a_progress,
+  register_a_sticker,
+  register_a_sticker_animated,
+  register_a_text,
+  register_a_tooltip
 };

package/dist/general_types.d.ts

@@ -76,7 +76,7 @@ export interface ATextAttributes extends BaseAttributes {
     /** Type scale. `small` = 13/16, `medium` (default) = 15/20, `large` = 17/24. */
     size?: 'small' | 'medium' | 'large';
     /** Render as inline-block instead of the default block. */
-    inline?: boolean | string;
+    inline?: boolean | '';
     /** Truncate to N lines with a trailing ellipsis. The attribute value
      *  carries the line count (e.g. `"1"`, `"3"`); the count is also
      *  available via the `--line-clamp` CSS custom property set inline. */
@@ -84,7 +84,7 @@ export interface ATextAttributes extends BaseAttributes {
     /** Marks the host as expandable when paired with `truncate`. Adds
      *  the fade-out mask; the JSX wrapper renders the chevron and owns
      *  the click/keyboard expansion logic. */
-    expandable?: boolean | string;
+    expandable?: boolean | '';
     /** ARIA disclosure state, mirrors the JSX wrapper's `expanded` flag. */
     'aria-expanded'?: boolean | 'true' | 'false';
 }
@@ -173,6 +173,25 @@ export interface AIconAttributes extends BaseAttributes {
     /** Hides decorative icons from screen readers. */
     'aria-hidden'?: 'true' | 'false' | boolean;
 }
+/**
+ * Attributes for the `<a-tooltip>` custom element. Placed as a child of the
+ * element it annotates (content as children). For the typed JSX wrapper use
+ * `Tooltip` from `@antadesign/anta`.
+ */
+export interface ATooltipAttributes extends BaseAttributes {
+    /** Show delay in milliseconds. Never use `0` — use ~`50`. Defaults to 250. */
+    delay?: number | string;
+    /** Preferred side; auto-flips when there's no room. Defaults to `'bottom'`. */
+    placement?: 'top' | 'bottom';
+    /** Pin under the anchor instead of following the cursor. Presence-based
+     *  (`''` on, omit off). */
+    static?: boolean | '';
+    /** Make the bubble hoverable/clickable (pointer events on, stays open while
+     *  hovered). Implies `static`. Presence-based (`''` on, omit off). */
+    interactive?: boolean | '';
+    /** HTML `id`. */
+    id?: string;
+}
 /**
  * Attributes for the `<a-button>` custom element. For the typed JSX
  * wrapper use `Button` from `@antadesign/anta`.
@@ -188,13 +207,13 @@ export interface AButtonAttributes extends BaseAttributes {
     size?: 'small' | 'medium' | 'large';
     /** Drop outer padding to zero. Only takes effect on `priority="quaternary"`.
      *  Presence-based: `''` (or any value) turns it on; omit to turn off. */
-    paddingless?: '' | 'true' | 'false' | boolean;
+    paddingless?: boolean | '';
     /** Loading state. Presence-based (`''` on, omit off). */
-    loading?: '' | 'true' | 'false' | boolean;
+    loading?: boolean | '';
     /** Disabled state. Presence-based (`''` on, omit off). */
-    disabled?: '' | 'true' | 'false' | boolean;
+    disabled?: boolean | '';
     /** Toggled-on / pressed state. Presence-based (`''` on, omit off). */
-    selected?: '' | 'true' | 'false' | boolean;
+    selected?: boolean | '';
     /** Submit/reset semantics. */
     type?: 'button' | 'submit' | 'reset';
     /** Associate with a form by id when not nested inside it. */

package/dist/index.d.ts

@@ -31,6 +31,8 @@ export { Sticker } from './components/Sticker';
 export type { StickerProps } from './components/Sticker';
 export { StickerAnimated } from './components/StickerAnimated';
 export type { StickerAnimatedProps } from './components/StickerAnimated';
+export { Tooltip } from './components/Tooltip';
+export type { TooltipProps } from './components/Tooltip';
 export type { BaseProps, BaseAttributes } from './general_types';
 export { configure } from './jsx-runtime';
 /**

package/dist/index.js

@@ -6,6 +6,7 @@ import { Button } from "./components/Button";
 import { ICON_SHAPES, ICON_SYNONYMS } from "./elements/a-icon.shapes";
 import { Sticker } from "./components/Sticker";
 import { StickerAnimated } from "./components/StickerAnimated";
+import { Tooltip } from "./components/Tooltip";
 import { configure } from "./jsx-runtime";
 export {
   Button,
@@ -17,5 +18,6 @@ export {
   StickerAnimated,
   Text,
   Title,
+  Tooltip,
   configure
 };

package/dist/jsx-runtime.d.ts

@@ -22,7 +22,7 @@ export declare function configure(jsx: JsxFunction, Fragment?: ComponentType): v
 export declare function jsx(type: ComponentType, props: Record<string, unknown> | null, key?: string | number): unknown;
 export declare function jsxs(type: ComponentType, props: Record<string, unknown> | null, key?: string | number): unknown;
 export { _Fragment as Fragment };
-import type { AProgressAttributes, ATextAttributes, ATitleAttributes, AIconAttributes, AButtonAttributes, AStickerAttributes, AStickerAnimatedAttributes, BaseAttributes } from './general_types';
+import type { AProgressAttributes, ATextAttributes, ATitleAttributes, AIconAttributes, AButtonAttributes, AStickerAttributes, AStickerAnimatedAttributes, ATooltipAttributes, BaseAttributes } from './general_types';
 export declare namespace JSX {
     type IntrinsicElements = React.JSX.IntrinsicElements & {
         'a-progress': AProgressAttributes;
@@ -37,5 +37,6 @@ export declare namespace JSX {
         'a-button-label': BaseAttributes;
         'a-sticker': AStickerAttributes;
         'a-sticker-animated': AStickerAnimatedAttributes;
+        'a-tooltip': ATooltipAttributes;
     };
 }

package/dist/reset.css

@@ -108,9 +108,14 @@
   /* Global link defaults. Hairline underline at 75% alpha;
      underline goes to currentColor (100%) and 1px on hover. Color
      comes from --link-color tokens, which auto-flip in dark mode.
-     Components or specific contexts (nav, headings, buttons)
-     should override as needed. */
-  a, a:link, a:visited {
+     `:not([role="button"])` excludes anchor-buttons (`<a role="button">`,
+     e.g. `<Button href>`): `a:link`/`a:visited` are pseudo-classes with the
+     same (0,1,1) specificity as `a[role="button"]`, so without the exclusion
+     they'd tie and win on source order, giving buttons link colour +
+     underline. Other contexts (nav, headings) still override as needed. */
+  a:not([role="button"]),
+  a:not([role="button"]):link,
+  a:not([role="button"]):visited {
     color: var(--link-color);
     text-decoration: underline;
     text-decoration-style: solid;
@@ -121,14 +126,14 @@
   /* Hover only on real-pointer devices — gating avoids the sticky hover
      color that lingers after a tap on touch screens. */
   @media (hover: hover) and (pointer: fine) {
-    a:hover {
+    a:not([role="button"]):hover {
       color: var(--link-color-hover);
       /* Underline color is left as the resting hairline (the base rule's
          `currentColor` mix) — only the thickness grows on hover. */
       text-decoration-thickness: 1px;
     }
   }
-  a:active {
+  a:not([role="button"]):active {
     text-decoration-color: color-mix(in srgb, currentColor 75%, transparent);
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antadesign/anta",
-  "version": "0.1.1-dev.7",
+  "version": "0.1.1-dev.8",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -64,6 +64,7 @@
   },
   "dependencies": {
     "clsx": "^2.1.0",
+    "es-toolkit": "^1.47.0",
     "lottie-web": "^5.13.0"
   },
   "peerDependencies": {