@antadesign/anta 0.3.21 → 0.3.23

package/docs/components/steps.md

@@ -0,0 +1,324 @@
+# Steps
+
+Ordered process navigation built on [`Tabs`](./tabs.md). Use `Tabs` when the views
+are peers rather than phases in a flow.
+
+## State
+
+Each option needs a unique `value`, a `label`, and a `state`. `state`
+supplies the default marker, `value` controls selection, and `disabled`
+controls access.
+
+- `incomplete` — empty circle
+- `loading` — loader
+- `completed` — check
+- `error` — critical ×
+- `disabled` — incomplete marker by default
+
+```tsx
+const options = [
+  { value: 'completed', label: 'Completed', state: 'completed' },
+  { value: 'loading', label: 'Loading', state: 'loading' },
+  { value: 'error', label: 'Error', state: 'error' },
+  { value: 'incomplete', label: 'Incomplete', state: 'incomplete' },
+]
+
+<Steps fill defaultValue="loading" label="Task state" options={options}>
+  <TabPanel value="completed"><Text size="small">This work is complete and ready to use.</Text></TabPanel>
+  <TabPanel value="loading"><Text size="small">This work is currently running.</Text></TabPanel>
+  <TabPanel value="error"><Text size="small">Resolve this error before continuing.</Text></TabPanel>
+  <TabPanel value="incomplete"><Text size="small">This work has not started yet.</Text></TabPanel>
+</Steps>
+```
+
+An incomplete step can still be selected. Add `disabled` only when it is locked;
+disabled steps keep their layout space and use the incomplete marker by default.
+Pass `marker` or return a value from `renderMarker` to keep a custom marker. Use
+`loading` for work running in the background.
+
+## Priority
+
+`secondary` is the default: selected markers have a subtle fill inside their
+outline. `primary` fills the selected marker with its tone and uses a white icon,
+like a primary Button. Its 2px resting marker uses `border-3` and its 2px rail
+uses `border-3`; a completed, unselected marker keeps the primary fill at 80%
+without an outline. Its completed connector moves one step stronger to `border-2`.
+`tertiary` removes the marker stroke and makes its marker the icon size plus 2px on
+each side.
+
+```tsx
+<Steps
+  fill
+  priority="primary"
+  tone="brand"
+  defaultValue="review"
+  label="Deployment progress"
+  options={[
+    { value: 'build', label: 'Build', state: 'completed' },
+    { value: 'review', label: 'Review', state: 'loading' },
+    { value: 'deploy', label: 'Deploy', state: 'incomplete' },
+  ]}
+/>
+```
+
+## Tone
+
+Set `tone` on `Steps` to color every step's label, hint, and icon, plus active
+and completed markers. Inactive incomplete/loading marker rings stay neutral.
+Set `option.tone` when one step needs an override. Labels strengthen on hover and
+selection; hints stay at the muted `text-3` tone. In `secondary` and
+`tertiary`, the marker icon always matches the label's current color; a secondary
+marker's resting stroke uses the matching muted border tone. With every priority,
+the connector after a completed step is one border step stronger: `border-2` from
+the standard `border-3` rail. Error markers stay critical and gain a critical fill
+when selected.
+
+```tsx
+const options = [
+  { value: 'done', label: 'Done', hint: 'Complete', state: 'completed' },
+  { value: 'current', label: 'Validate', hint: 'Checking dependencies', state: 'loading' },
+  { value: 'review', label: 'Review', hint: 'Needs attention', state: 'incomplete', tone: 'warning' },
+  { value: 'deploy', label: 'Deploy', hint: 'Waiting', state: 'incomplete', tone: 'info' },
+  { value: 'error', label: 'Error', hint: 'Resolve before continuing', state: 'error' },
+]
+
+<Steps tone="brand" defaultValue="current" options={options} />
+```
+
+Labels and hints ellipsize within each step. Hovering or focusing a clipped step
+shows its full label and hint in a tooltip.
+
+Steps and option tones are `neutral` (default), `brand`, `info`, `success`,
+`warning`, and `critical`. Options inherit the Steps tone until `option.tone` is
+set. Omit the Steps tone, or pass an empty string, for neutral; set an option to
+`neutral` or an empty string to opt it out of an inherited tone.
+
+## Markers and hints
+
+Marker precedence is:
+
+1. `renderMarker(...)` result, unless it returns `undefined`
+2. `option.marker`
+3. Built-in marker from `state`
+
+Return `null` from `renderMarker` for an intentionally empty ring.
+
+A number marker is shown directly; an icon-shape string renders an `Icon`.
+`hint` adds secondary text.
+
+```tsx
+const options = [
+  { value: 'draft', label: 'Draft', hint: 'Saved', state: 'completed', marker: 1 },
+  { value: 'approval', label: 'Approval', hint: 'In review', state: 'loading', marker: 'hourglass' },
+  { value: 'publish', label: 'Publish', hint: 'Not started', state: 'incomplete', marker: 'send' },
+]
+
+<Steps defaultValue="approval" label="Publishing progress" options={options} />
+```
+
+Use `renderMarker` when a marker depends on the current step state. Its returned
+node wins; return `undefined` to fall back to `marker`, then the state marker.
+
+```tsx
+const options = [
+  { value: 'draft', label: 'Draft', state: 'completed', marker: 1 },
+  { value: 'approval', label: 'Approval', state: 'loading' },
+  { value: 'publish', label: 'Publish', state: 'incomplete', marker: 'send' },
+]
+
+<Steps
+  defaultValue="approval"
+  label="Publishing progress"
+  options={options}
+  renderMarker={(option, { selected }) =>
+    option.state === 'loading'
+      ? <Icon shape={selected ? 'refresh-ccw-dot' : 'hourglass'} />
+      : undefined
+  }
+/>
+```
+
+## Panels
+
+Add a [`TabPanel`](./tabs.md#panels) with the same `value` as its option. Panels stay
+mounted while inactive. Omit them when a router renders the content.
+
+## Selection
+
+Use `defaultValue` for uncontrolled selection. Use `value` and `onStateChange`
+when the application owns it.
+
+```tsx
+const options = [
+  { value: 'build', label: 'Build', state: 'completed' },
+  { value: 'setup', label: 'Setup', state: 'loading' },
+  { value: 'next', label: 'Next steps', state: 'incomplete' },
+]
+const [phase, setPhase] = useState('setup')
+
+<Steps
+  value={phase}
+  tone="brand"
+  options={options}
+  onStateChange={(_event, { next }) => next && setPhase(next)}
+/>
+```
+
+The application also owns state changes and decides when to enable future
+steps. `Steps` does not advance or complete them automatically.
+
+### Flow actions
+
+Place Back and Continue beside `Steps` so validation and side effects stay in the
+application.
+
+```tsx
+const options = [
+  { value: 'build', label: 'Build', state: 'completed' },
+  { value: 'setup', label: 'Setup', state: 'loading' },
+  { value: 'next', label: 'Next steps', state: 'incomplete' },
+]
+const [phase, setPhase] = useState('setup')
+const index = options.findIndex((option) => option.value === phase)
+
+<Steps
+  value={phase}
+  options={options}
+  onStateChange={(_event, { next }) => next && setPhase(next)}
+/>
+<Button label="Back" disabled={index === 0} onClick={() => setPhase(options[index - 1].value)} />
+<Button label="Continue" disabled={index === options.length - 1} onClick={() => setPhase(options[index + 1].value)} />
+```
+
+## Size
+
+`small`, `medium` (default), and `large` use 24px, 28px, and 32px markers.
+
+```tsx
+<Steps
+  size="small"
+  options={[
+    { value: 'build', label: 'Build', state: 'completed' },
+    { value: 'setup', label: 'Setup', state: 'loading' },
+    { value: 'next', label: 'Next steps', state: 'incomplete' },
+  ]}
+/>
+```
+
+## Orientation
+
+Horizontal steps scroll when needed. Vertical steps place the active panel before
+the next step.
+
+```tsx
+<Steps
+  orientation="vertical"
+  options={[
+    { value: 'build', label: 'Build', state: 'completed' },
+    { value: 'setup', label: 'Setup', state: 'loading' },
+    { value: 'next', label: 'Next steps', state: 'incomplete' },
+  ]}
+>
+  <TabPanel value="build"><Text size="small">Build output is ready.</Text></TabPanel>
+  <TabPanel value="setup"><Text size="small">Preparing the environment.</Text></TabPanel>
+  <TabPanel value="next"><Text size="small">Review the result.</Text></TabPanel>
+</Steps>
+```
+
+Pass `label` to name the tablist. Arrow keys follow the orientation; `Home` and
+`End` move to the edges; `Enter` and `Space` activate a focused step. Disabled
+steps are skipped.
+
+Markers and connectors are decorative. Put important state text in the active
+panel or an application-owned live region.
+
+## Events
+
+Events match [`Tabs`](./tabs.md#events).
+
+| Callback | When | Cancelable | Payload |
+|---|---|---|---|
+| `onStateChange(event, { next, prev })` | Before selection | Yes | Next and previous values |
+| `onChange(event)` | After selection | No | Native `change` event |
+| `onValueChange(event, { value })` | After selection | No | Selected value |
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `options` | StepOption[] | — | Ordered process phases. |
+| `priority?` | StepPriority | 'secondary' | Visual emphasis. Primary uses a solid selected marker and a stronger
+completed connector; secondary is the outlined default; tertiary is compact
+and borderless. |
+| `renderMarker?` | (option, state) => ReactNode | — | Builds a custom marker from a step and its current state. A returned node
+replaces `marker` and the built-in state marker; return `undefined` to use
+those fallbacks, or `null` for an empty ring. |
+| `tone?` | StepTone \| '' | 'neutral' | Tone applied to every step without its own `tone`. Error steps stay
+critical and disabled steps stay neutral. |
+
+For framework-free use, compose the same light DOM that `Steps` emits.
+`a-steps` and its `a-step-*` children are structural elements styled by the
+shipped Steps stylesheet. The [Tabs Web Component](./tabs.md#web-component) inside
+owns selection and panel behavior; markers, states, and tones stay in your markup.
+
+```js
+import '@antadesign/anta/elements'
+import '@antadesign/anta/components/Steps.css'
+```
+
+```html
+<div>
+  <a-steps>
+    <a-tabs role="tablist" aria-label="Setup progress" priority="secondary" default-state="setup" data-steps fill noslide>
+      <a-tab role="tab" value="build" tabindex="0" tone="success">
+        <a-step-marker aria-hidden="true"><a-icon shape="check"></a-icon></a-step-marker>
+        <a-step-desc><a-tab-label>Build</a-tab-label><a-step-hint>Complete</a-step-hint></a-step-desc>
+      </a-tab>
+      <a-tab role="tab" value="setup" tabindex="-1" tone="brand">
+        <a-step-marker aria-hidden="true"><a-loader></a-loader></a-step-marker>
+        <a-step-desc><a-tab-label>Setup</a-tab-label><a-step-hint>In progress</a-step-hint></a-step-desc>
+      </a-tab>
+      <a-tab role="tab" value="review" tabindex="-1">
+        <a-step-marker aria-hidden="true"><a-icon shape="circle-large"></a-icon></a-step-marker>
+        <a-step-desc><a-tab-label>Review</a-tab-label><a-step-hint>Waiting</a-step-hint></a-step-desc>
+      </a-tab>
+    </a-tabs>
+    <a-tabpanel role="tabpanel" value="build">Build output is ready.</a-tabpanel>
+    <a-tabpanel role="tabpanel" value="setup">Prepare the environment.</a-tabpanel>
+    <a-tabpanel role="tabpanel" value="review">Review the result.</a-tabpanel>
+  </a-steps>
+</div>
+```
+
+Use `priority`, `size`, and `orientation` first. Set `tone` on each option. Each
+option also accepts `className`, `style`, and `data-*` attributes. Markers are
+light DOM; connectors are pseudo-elements.
+
+**Dotted connector.** For horizontal steps, replace the connector's solid
+background with a dotted border:
+
+```css
+.dotted-steps a-tab:not(:last-child)::before {
+  height: 0;
+  background: none;
+  border-block-start: 2px dotted var(--border-2-brand);
+}
+```
+
+`className` on `Steps` applies to `a-steps`. `.dotted-steps` is only the demo
+scope; use your own selector when applying the rule.
+
+**Fill the container.** Pass `fill` to spread horizontal steps across their
+container. The connectors take the remaining space, placing the middle step in
+the middle and the last step at the far edge.
+
+```tsx
+<Steps
+  fill
+  defaultValue="review"
+  label="Deployment progress"
+  options={[
+    { value: 'build', label: 'Build', state: 'completed' },
+    { value: 'review', label: 'Review', state: 'loading' },
+    { value: 'deploy', label: 'Deploy', state: 'incomplete' },
+  ]}
+/>
+```

package/docs/components/tabs.md

@@ -6,6 +6,9 @@ A tablist for switching between views. The strip is data-driven: pass an
 selectable strip that emits the chosen value; add matching `<TabPanel>` children
 (see [Panels](#panels)) to show and hide the content too.
 
+Each option can also set `className`, `style`, and `data-*` attributes on its
+individual `<a-tab>`.
+
 ## Priority
 
 ```tsx
@@ -20,7 +23,7 @@ selectable strip that emits the chosen value; add matching `<TabPanel>` children
 - **`secondary`**: a filled tab, no track.
 - **`tertiary`**: an underline.
 
-## Tones
+## Tone
 
 Six named tones: `neutral` (default), `brand`, `info`, `success`, `warning`,
 `critical`. Any CSS color works for a one-off custom tone. The tone runs through the
@@ -326,6 +329,7 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | `defaultValue?` | string | — | Initial active value for the uncontrolled case. After first render `Tabs`
  owns selection itself. |
 | `disabled?` | boolean | — | Disable the whole strip. |
+| `fill?` | boolean | false | Makes horizontal tabs share the available inline space equally. |
 | `label?` | string | — | Accessible name for the tablist (`aria-label`). |
 | `noslide?` | boolean | — | Disable the sliding indicator. By default the selected-tab indicator animates
  between tabs (a single rectangle, via CSS anchor positioning); `noslide` paints it
@@ -341,7 +345,8 @@ so those suit an uncontrolled strip reacting to its own pick. **`onFocus`** /
 | `onValueChange?` | (event, attrs) => void | — | Like `onChange`, but with a `{ value }` snapshot as the 2nd argument. |
 | `options?` | TabOption[] | — | The tabs, as a data array (the strip's single source). Each entry is a
  `TabOption` (`value`, `label` or `children`, `icon`, `iconTrailing`, `tone`,
- `disabled`, `round`). |
+ `disabled`, `round`, `className`, `style`). `className` and `style` land on
+ that option's individual `<a-tab>`, not on the strip. |
 | `orientation?` | 'horizontal' \| 'vertical' | 'horizontal' | Layout + arrow-key axis. Horizontal ellipsizes labels when tabs overflow (scroll
  is opt-in via CSS); vertical stacks them. |
 | `priority?` | 'primary' \| 'secondary' \| 'tertiary' | 'primary' | Visual priority. `primary` is the raised pill on a recessed track (the
@@ -368,9 +373,11 @@ Use the web component directly when you are not using React or Preact and a nati
 Keep the tab strip and panels as siblings under one parent. Panels read the active
 value from `<a-tabs>`.
 
+Add `fill` to make horizontal tabs share the available width equally.
+
 ```html
 <div>
-  <a-tabs role="tablist" default-state="account">
+  <a-tabs role="tablist" default-state="account" fill>
     <a-tab role="tab" value="account" tabindex="0"><a-tab-label>Account</a-tab-label></a-tab>
     <a-tab role="tab" value="security" tabindex="-1"><a-tab-label>Security</a-tab-label></a-tab>
   </a-tabs>
@@ -438,12 +445,21 @@ scrollable.
 ```
 
 **Equal-width tabs.** By default tabs are sized to their labels (and compress only
-when the strip overflows). For a segmented-control look where every tab is the same
-width, let them fill the strip from a zero basis:
+when the strip overflows). Pass `fill` for a segmented-control look where every tab
+shares the strip width:
 
-```css
-.equal-tabs a-tabs { width: 100%; }
-.equal-tabs a-tab  { flex: 1 1 0; max-width: none; }
+```tsx
+<Tabs
+  fill
+  defaultValue="all"
+  label="Filter"
+  options={[
+    { value: 'all', label: 'All' },
+    { value: 'assigned', label: 'Assigned to me' },
+    { value: 'recent', label: 'Recent' },
+    { value: 'archived', label: 'Archived' },
+  ]}
+/>
 ```
 
 **Wrap labels.** Let long labels wrap so the tabs grow taller instead of truncating:

package/docs/components/tag.md

@@ -20,7 +20,7 @@ and tracks dark mode.
 <Tag allcaps priority="tertiary" tone="brand" label="Tertiary" />
 ```
 
-## Tones
+## Tone
 
 Omit `tone` for the neutral gray tag, or pick a semantic tone. Color
 comes from the theme tokens, so every tone tracks light and dark mode
@@ -74,7 +74,7 @@ versions, and timers don't reflow.
 ```tsx
 <Tag allcaps tone="success" icon="circle-check" label="Build" value="passed" />
 <Tag allcaps tone="info" icon="hourglass" label="Running" value="20m 16s" />
-<Tag allcaps icon="github-logo" label="Commit" value="4f90d13" />
+<Tag allcaps icon="history" label="Commit" value="4f90d13" />
 <Tag allcaps tone="warning" label="Retries" value="3" iconTrailing="refresh" />
 ```
 
@@ -113,7 +113,7 @@ Uppercase also tracks wider (0.08ch vs the default 0.02ch) and steps each size
 down 1px, since caps read larger than mixed case at the same size.
 
 ```tsx
-<Tag icon="github-logo" label="GitHub" value="v1.6.9" />
+<Tag icon="external-link" label="GitHub" value="v1.6.9" />
 <Tag allcaps label="Running" />
 ```
 

package/docs/components/tooltip.md

@@ -138,11 +138,11 @@ shows.
  (px) or a CSS length string for a custom radius. |
 | `truncatedOnly?` | boolean | — | Only show when the target is actually truncated (its text overflows and is
  ellipsized); a label that fits gets no tooltip. The check is a UI-thread
- layout read, re-measured on each show. By default it measures the nearest
- Anta ellipsizing label part (`<a-tab-label>` / `<a-button-label>`) inside
- the anchor, then the anchor itself — override with `truncatedSelector`. |
-| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element whose overflow
- decides whether a `truncatedOnly` tooltip shows. |
+ layout read, re-measured on each show. By default it measures every Anta
+ ellipsizing label part inside the anchor, then the anchor itself —
+ override with `truncatedSelector`. |
+| `truncatedSelector?` | string | — | CSS selector (resolved within the anchor) for the element or elements
+ whose overflow decides whether a `truncatedOnly` tooltip shows. |
 
 Use the web component directly when you are not using React or Preact and a native control does not fit.
 

package/docs/index.md

@@ -30,6 +30,7 @@ Anta is designed for a clean DOM. Prefer the props and attributes exposed by eac
 - [Switch](./components/switch.md)
 - [Slider](./components/slider.md)
 - [Tabs](./components/tabs.md)
+- [Steps](./components/steps.md)
 
 - [Expander](./components/expander.md)
 - [Menu](./components/menu.md)

package/docs/install-config.md

@@ -21,6 +21,21 @@ import { Progress } from '@antadesign/anta'
 <Progress value={42} label="Uploaded" hint="3 of 7" />
 ```
 
+### Full bundle
+
+For a single minified Anta runtime and stylesheet, use the bundle pair instead
+of the separate tokens, reset, elements, and JSX imports:
+
+```tsx
+import '@antadesign/anta/bundle.css'
+import { Progress } from '@antadesign/anta/bundle'
+
+<Progress value={42} label="Uploaded" hint="3 of 7" />
+```
+
+`bundle` registers every custom element and re-exports the JSX API. Its React
+peer dependency and Preact configuration are the same as the regular JSX entry.
+
 ### What you import (and why)
 
 Tokens, elements, and the JSX layer render a styled component. The reset is
@@ -32,6 +47,8 @@ recommended; the reference theme is optional.
 | `@antadesign/anta/reset.css` | A small reset plus Anta's focus, heading, list, and link typography in `@layer anta`. | You use another reset and typography. |
 | `@antadesign/anta/elements` | Registers every `<a-*>` element and its CSS. Per-element entries register one; see [Registering elements](#registering-elements). | You render only on the server or register elements individually. |
 | `@antadesign/anta` | Typed React/Preact wrappers such as `Progress`, `Text`, and `Icon`. | You write `<a-*>` elements directly. |
+| `@antadesign/anta/bundle.css` | One minified stylesheet containing tokens, reset, element, and JSX-wrapper styles. | You want granular CSS imports. |
+| `@antadesign/anta/bundle` | One minified ESM runtime that registers every `<a-*>` element and re-exports the JSX API. | You want granular JS imports. |
 | `@antadesign/anta/theme-anta.css` *(optional)* | The hand-tuned reference palette. Import last to replace the seed-derived default. | You want the seed-derived or your own palette. |
 
 Load `tokens.css` before element CSS. Elements read its variables; without it,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antadesign/anta",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -27,6 +27,10 @@
       "types": "./dist/elements/*.d.ts",
       "default": "./dist/elements/*.js"
     },
+    "./bundle": {
+      "types": "./dist/bundle.d.ts",
+      "default": "./dist/bundle.js"
+    },
     "./anta_helpers": {
       "types": "./dist/anta_helpers.d.ts",
       "default": "./dist/anta_helpers.js"
@@ -37,6 +41,7 @@
     },
     "./tokens.css": "./dist/tokens.css",
     "./reset.css": "./dist/reset.css",
+    "./bundle.css": "./dist/bundle.css",
     "./theme-anta.css": "./dist/theme-anta.css",
     "./generate-icons.mjs": "./dist/generate-icons.mjs",
     "./*": {
@@ -45,11 +50,12 @@
     }
   },
   "scripts": {
-    "build": "pnpm run build:js && pnpm run build:css && pnpm run build:types && pnpm run build:docs",
-    "build:dev": "pnpm run build:js && pnpm run build:css:dev && pnpm run build:types",
+    "build": "pnpm run build:js && pnpm run build:css && pnpm run build:bundle && pnpm run build:types && pnpm run build:docs",
+    "build:dev": "pnpm run build:js && pnpm run build:css:dev && pnpm run build:bundle && pnpm run build:types",
     "build:css": "esbuild $(find src -name '*.css') --minify --outdir=dist --outbase=src && cp scripts/generate-icons.mjs dist/",
     "build:css:dev": "find src -name '*.css' | while IFS= read -r f; do d=\"dist/${f#src/}\"; mkdir -p \"$(dirname \"$d\")\"; cp \"$f\" \"$d\"; done && cp scripts/generate-icons.mjs dist/",
     "build:js": "esbuild $(find src \\( -name '*.ts' -o -name '*.tsx' \\) ! -name '*.d.ts') --outdir=dist --outbase=src --jsx=automatic --jsx-import-source=@antadesign/anta --format=esm --target=ES2022 --loader:.css=global-css",
+    "build:bundle": "node scripts/build-bundle.mjs",
     "build:types": "tsc -p src/tsconfig.json",
     "build:docs": "pnpm --filter anta-site run docs:api && pnpm --filter anta-site run docs:pages && node scripts/generate-package-docs.mjs",
     "dev": "node scripts/dev.mjs",