@antadesign/anta 0.1.1-dev.8 → 0.2.1

package/README.md

@@ -10,7 +10,7 @@ This constraint shapes the architecture: the web components carry the core styli
 
 `@antadesign/anta` is an NPM package, so you can `npm install @antadesign/anta` or do that with `pnpm` / `bun`.
 
-Since Anta is in active development we suggest using the latest dev version: `"@antadesign/anta": "dev"` in your `package.json`. For production builds we suggest pinning to a stable version from npm.
+Use the latest version from npm, but **always pin an exact version** — `"@antadesign/anta": "0.2.0"` in your `package.json` — rather than a floating tag like `"latest"` or `"dev"`, which can change between installs.
 
 ### Usage
 
@@ -36,7 +36,7 @@ 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).
+`@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 any dependencies they pull in — then never enter your bundle. See [Registering elements](#registering-elements).
 
 ### Cascade layers
 
@@ -79,7 +79,7 @@ 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.
+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 any dependencies they pull 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:
 
@@ -125,6 +125,45 @@ import { h, Fragment } from 'preact'
 configure(h, Fragment)
 ```
 
+### TypeScript: typing raw `<a-*>` tags in JSX
+
+If you only use the JSX wrappers (`<Button>`, `<Progress>`, …) you need no setup — they're typed like any React component. This section is only for writing the raw `<a-*>` tags directly in JSX.
+
+**Option A (preferred)** — point your JSX types at anta in `tsconfig.json`:
+
+```jsonc
+{ "compilerOptions": { "jsx": "react-jsx", "jsxImportSource": "@antadesign/anta" } }
+```
+
+Every `a-*` tag type-checks, all standard HTML tags keep working, and importing anything from `@antadesign/stickers` adds the sticker tags automatically.
+
+**Option B** — if you can't change `jsxImportSource` (a shared tsconfig, Emotion's `@emotion/react` source, an older `@types/react` without the `React.JSX` namespace), merge anta's tag map into your JSX namespace yourself. Anta exports it as a standalone interface, `AntaIntrinsicElements` — and `@antadesign/stickers` exports the matching `StickerIntrinsicElements` — so it's a single `extends` in any `.d.ts` covered by your tsconfig:
+
+```ts
+import type { AntaIntrinsicElements } from '@antadesign/anta'
+import type { StickerIntrinsicElements } from '@antadesign/stickers' // only if you use stickers
+
+declare global {
+  namespace JSX {
+    interface IntrinsicElements extends AntaIntrinsicElements, StickerIntrinsicElements {}
+  }
+}
+```
+
+On modern `@types/react` (≥18) with `jsx: "react-jsx"`, the JSX namespace is module-scoped and the global declaration above is silently ignored — target the `react` module instead:
+
+```ts
+import type { AntaIntrinsicElements } from '@antadesign/anta'
+
+declare module 'react' {
+  namespace JSX {
+    interface IntrinsicElements extends AntaIntrinsicElements {}
+  }
+}
+```
+
+Either way the tags stay fully typed — unknown `a-*` tags and wrong prop types are still errors. New tags arrive automatically when you upgrade anta; there's no per-tag list to maintain.
+
 ### Raw web components (no JSX)
 
 ```html

package/dist/components/Button.js

@@ -38,12 +38,13 @@ const Button = ({
   children,
   ...rest
 }) => {
-  const isCustomTone = tone != null && !NAMED_TONES.has(tone);
-  const computedStyle = isCustomTone ? { ...style, ["--button-tone-source"]: tone } : style;
+  const toneAttr = tone || void 0;
+  const isCustomTone = toneAttr != null && !NAMED_TONES.has(toneAttr);
+  const computedStyle = isCustomTone ? { ...style, ["--button-tone-source"]: toneAttr } : style;
   const isIconOnly = icon != null && label == null && children == null && iconTrailing == null;
   const sharedAttrs = {
     priority,
-    tone,
+    tone: toneAttr,
     underline,
     // 'medium' (and unset) is the implicit default — emit no DOM attr.
     size: size && size !== "medium" ? size : void 0,

package/dist/components/Progress.module.css

@@ -1,5 +0,0 @@
-/*
- * Base layout is handled by the <a-progress> web component (display: block).
- * This module is reserved for conditional styles driven by JSX logic.
- * And in this case we usually start with .container style
- */

package/dist/components/Tag.d.ts

@@ -0,0 +1,55 @@
+import type { BaseProps } from "../general_types";
+import type { IconShape } from '../elements/a-icon.shapes';
+export interface TagProps extends BaseProps {
+    /** A short "key" shown before the value. When paired with `value` it
+     *  renders bold (weight 600), same color. On its own (no `value`) it's
+     *  treated as the tag's primary text and keeps the default styling. */
+    label?: string;
+    /** The tag's primary text — a status, count, version, duration, etc.
+     *  Rendered in the default color and weight, with no divider from the
+     *  label; the color + weight contrast does the separating. */
+    value?: string;
+    /** Semantic tone, or any literal CSS color (`'#ff1493'`, `'rebeccapurple'`)
+     *  for a one-off custom tone. Named tones map to the `--text-2-{tone}` /
+     *  `--bg-4-{tone}` palette; a custom color keeps its hue while lightness
+     *  and chroma are pinned. `'neutral'` (the default) is the gray tag —
+     *  the same as omitting `tone`.
+     *  @defaultValue neutral */
+    tone?: 'neutral' | 'brand' | 'info' | 'success' | 'warning' | 'critical' | (string & {});
+    /** Size variant. `small` = 16px tall, `medium` = 20px, `large` = 24px
+     *  (matching `Button`). Omit the attribute or pass `'medium'` for the
+     *  default — both render identically and emit no DOM attribute.
+     *  @defaultValue medium */
+    size?: 'small' | 'medium' | 'large';
+    /** Render in normal (mixed) case instead of the default uppercase
+     *  (keeps Anta's small body-text letter-spacing; uppercase tracks wider). */
+    nocaps?: boolean;
+    /** Leading icon shape. Sits flush before the label, scaled to the pill. */
+    icon?: IconShape;
+    /** Trailing icon shape. Renders last, after the value. */
+    iconTrailing?: IconShape;
+}
+/**
+ * Compact pill / chip for status, labels, and metadata.
+ *
+ * Renders an `<a-tag>` styled tag (no JS, no shadow DOM) — color and size
+ * come entirely from attributes. Content is composed from `icon`, `label`,
+ * `value`, and `iconTrailing` (like `<Button>`): `value` is the primary
+ * text (default styling) and `label`, when paired with a value, renders as
+ * a bold "key" before it (same color, no divider). Tabular figures are
+ * always on, so counts / versions / timers don't reflow. For an arbitrary
+ * multi-part tag, pass `children` instead — each segment after the first
+ * gets a hairline divider (the `label` + `value` pair is the no-divider
+ * exception).
+ *
+ * Requires `@antadesign/anta/elements` to be imported (client-side only)
+ * so the CSS ships with the page.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <Tag tone="success" label="Running" />
+ * <Tag tone="info" icon="hourglass" label="Build" value="2m 14s" />
+ * <Tag tone="brand" size="small" nocaps value="v2.1.0" />
+ * ```
+ */
+export declare const Tag: ({ icon, iconTrailing, label, value, tone, size, nocaps, className, style, children, ...rest }: TagProps) => any;

package/dist/components/Tag.js

@@ -0,0 +1,40 @@
+import { jsx, jsxs } from "@antadesign/anta/jsx-runtime";
+const NAMED_TONES = /* @__PURE__ */ new Set(["neutral", "brand", "info", "success", "warning", "critical"]);
+const Tag = ({
+  icon,
+  iconTrailing,
+  label,
+  value,
+  tone,
+  size,
+  nocaps,
+  className,
+  style,
+  children,
+  ...rest
+}) => {
+  const isCustomTone = tone != null && !NAMED_TONES.has(tone);
+  const computedStyle = isCustomTone ? { ...style, ["--tag-tone-source"]: tone } : style;
+  const hasValue = value != null;
+  return /* @__PURE__ */ jsxs(
+    "a-tag",
+    {
+      tone,
+      size: size && size !== "medium" ? size : void 0,
+      nocaps: nocaps ? "" : void 0,
+      class: className,
+      style: computedStyle,
+      ...rest,
+      children: [
+        icon && /* @__PURE__ */ jsx("a-icon", { shape: icon, "aria-hidden": "true" }),
+        label != null && (hasValue ? /* @__PURE__ */ jsx("a-tag-label", { children: label }) : /* @__PURE__ */ jsx("a-tag-value", { children: label })),
+        hasValue && /* @__PURE__ */ jsx("a-tag-value", { children: value }),
+        children,
+        iconTrailing && /* @__PURE__ */ jsx("a-icon", { shape: iconTrailing, "aria-hidden": "true" })
+      ]
+    }
+  );
+};
+export {
+  Tag
+};

package/dist/components/Text.d.ts

@@ -1,7 +1,9 @@
 import type { BaseProps } from "../general_types";
 export interface TextProps extends BaseProps {
-    /** Visual priority. Maps to text-1..text-5 (`primary` = text-1).
-     *  @defaultValue primary */
+    /** Visual priority. Maps to text-1..text-5 (`primary` = text-1, the
+     *  strongest). The default is `secondary` (text-2) — body text reads a
+     *  step softer than the strongest foreground; pass `primary` for emphasis.
+     *  @defaultValue secondary */
     priority?: 'primary' | 'secondary' | 'tertiary' | 'quaternary' | 'quinary';
     /** Color tint. Applies the matching `--text-{N}-{tone}` palette. */
     tone?: 'brand' | 'success' | 'critical' | 'warning' | 'info';

package/dist/components/Text.module.css

@@ -1,6 +0,0 @@
-/*
- * All Text layout — including truncation, the expandable fade mask,
- * and the chevron button — lives in the <a-text> web component's
- * shadow DOM. This module is reserved for any future JSX-driven
- * conditional styles.
- */

package/dist/components/Tooltip.d.ts

@@ -25,8 +25,10 @@ export interface TooltipProps extends BaseProps {
  * 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.
+ * leave, blur, Escape, or when the anchor scrolls away. On touch devices it
+ * opens on press-and-hold (a tap never surfaces it) and lingers briefly after
+ * release. 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.