@antadesign/anta 0.3.33 → 0.3.35

package/docs/components/slider.md

@@ -1,9 +1,79 @@
 # Slider
 
-**`Slider`** selects one number or an interval between two numbers. Pass a number
-for one thumb or a two-number tuple for two thumbs. Its label sits above the
-rail, and the value appears at the right side of the label row by default. Use
-`value` with `onValueChange` to control it, or `defaultValue` for uncontrolled use.
+`Slider` selects a number or an interval within a numeric range. Use it for
+settings such as volume, playback speed, or price limits when dragging helps
+people choose a value. Use a separate numeric input when precise text entry is
+also useful.
+
+Give every slider a visible `label` or an accessible name. A string label supplies
+the name; pair a rich label with `aria-label` or `aria-labelledby`.
+
+## Managing the value
+
+Pass `defaultValue` for an uncontrolled slider, or use `value` with
+`onValueChange` when the application owns the number. A controlled slider changes
+only when you update `value`. Turn off **Accept changes** in this example to see
+requests without applying them. **Reset to 35%** changes the application value
+without requesting another change.
+
+```tsx title="Accept or reject a requested value"
+import { useState } from 'preact/hooks'
+import { Button, Checkbox, Slider } from '@antadesign/anta'
+
+function SliderOwnershipDemo() {
+  const [value, setValue] = useState(35)
+  const [accept, setAccept] = useState(true)
+  const [requested, setRequested] = useState(35)
+
+  return (
+    <>
+      <Checkbox label="Accept changes" checked={accept} onStateChange={(_, { next }) => setAccept(next === true)} />
+      <Slider
+        label="Volume"
+        value={value}
+        valueSuffix="%"
+        onValueChange={(_, { value: next }) => {
+          setRequested(next)
+          if (accept) setValue(next)
+        }}
+      />
+      <Button onClick={() => setValue(35)}>Reset to 35%</Button>
+      <p>Applied: {value}%. Requested: {requested}%.</p>
+    </>
+  )
+}
+```
+
+`0` is a controlled numeric value. Omitting `value` or passing `undefined` selects
+uncontrolled use. Releasing control retains the last applied number until
+interaction or reset changes it. A numeric slider has no empty value.
+
+`onValueChange` reports requested values while dragging. `onValueCommit` reports
+the final request when the gesture ends, including cancellation or capture loss,
+and after each keyboard step. Its value can differ from the applied value when
+the application rejects a controlled request. `onInput` runs before
+`onValueChange`; `onChange` runs before `onValueCommit`. Cancel a keyboard or
+pointer default in `onKeyDown` or `onPointerDown`; the value notifications are
+noncancelable. See the prop reference for callback snapshots and reset behavior.
+
+## Forms
+
+Pass `name` to include the applied number in form submission. A range submits two
+entries under the same name; read them with `FormData.getAll(name)`. Disabled
+sliders submit nothing.
+
+Form reset restores an uncontrolled slider's `defaultValue`. Without one, it
+restores `min`, or `[min, max]` for a range. A changed uncontrolled reset emits
+both value callbacks. Controlled reset retains the application's value, and
+restoration does not overwrite a controlled value. Restoration of an uncontrolled
+value is silent.
+
+```tsx
+<form>
+  <Slider label="Brightness" name="brightness" defaultValue={60} valueSuffix="%" />
+  <Button type="reset">Reset brightness</Button>
+</form>
+```
 
 ## Relative dragging
 
@@ -17,7 +87,13 @@ dragging, as a native range input does.
 Releasing the pointer or losing pointer capture ends the drag. Moving back over
 the slider without pressing leaves its value unchanged.
 
-Arrow keys change by `step`. Home and End set the minimum and maximum. PageUp and PageDown move by one tenth of the range.
+Slider is horizontal. In inherited RTL, its minimum is at the right edge and
+horizontal pointer and arrow movement follow that direction. Up and Down still
+increase and decrease the value. Vertical orientation and readonly mode are not
+part of its API. The control reserves touch gestures for dragging.
+
+Arrow keys change by `step`. Home selects the minimum; End selects the nearest allowed
+step to the maximum. PageUp and PageDown move by one tenth of the range.
 
 ```tsx
 <Slider label="Relative drag" defaultValue={35} />
@@ -35,7 +111,7 @@ cross.
 
 `onValueChange` receives a number for a single-value slider and an ordered
 `[number, number]` tuple for a range slider. `onValueCommit` uses the same shape.
-Without `defaultValue`, a form reset selects the full `[min, max]` range.
+For an uncontrolled range without `defaultValue`, form reset selects `[min, max]`.
 
 ```tsx title="Controlled range"
 import { useState } from 'preact/hooks'
@@ -78,15 +154,19 @@ thumb movement and keyboard controls stay the same.
 `valueDisplay="end"` is the default. Use `inline` for `Label: value`, `thumb` to keep a value above the thumb, or `none` to omit it. `valuePrefix` and `valueSuffix` add text to every live value display.
 
 ```tsx
-<Slider label="Volume" defaultValue={48} valueSuffix="%" />
-<Slider label="Volume" defaultValue={48} valueDisplay="inline" valueSuffix="%" />
-<Slider label="Volume" defaultValue={48} valueDisplay="thumb" valueSuffix="%" />
+<Slider label="End" defaultValue={48} valueSuffix="%" />
+<Slider label="Inline" defaultValue={48} valueDisplay="inline" valueSuffix="%" />
+<Slider label="Thumb" defaultValue={48} valueDisplay="thumb" valueSuffix="%" />
 ```
 
 ## Size, tones, and radius
 
 `size` follows the input height scale: 24px, 28px, and 32px. `trackSize` sets the thickness of both rail segments without changing the control height; numbers use pixels and strings accept CSS lengths. `thumbSize` controls the thumb diameter, and `thumbFill` fills it with its resolved border color. `tone` colors the filled rail. `thumbTone` separately colors the thumb stroke. The unfilled rail stays neutral. `round` shapes both the rail and thumb. Pass `true` for fully round corners or a number or CSS length for a shared custom radius.
 
+In the Antithesis theme, an omitted `thumbTone` follows the filled rail's color.
+Other themes keep the thumb neutral. Pass `thumbTone="neutral"` to keep a neutral
+thumb in every theme. The native range uses the same rule for `thumb-tone`.
+
 ```tsx
 <Slider size="small" tone="info" label="Small" defaultValue={32} />
 <Slider tone="brand" thumbTone="success" trackSize={4} thumbSize={20} thumbFill label="Medium, filled thumb" defaultValue={52} />
@@ -104,6 +184,7 @@ thumb movement and keyboard controls stay the same.
   max={2}
   step={0.25}
   defaultValue={1}
+  valueSuffix="×"
   markers={[
     { value: 0.5, label: '0.5×' },
     { value: 1, label: 'Normal' },
@@ -116,33 +197,47 @@ thumb movement and keyboard controls stay the same.
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `defaultValue?` | number \| SliderRangeValue | 0 | Initial uncontrolled value. |
+| `defaultValue?` | number \| SliderRangeValue | min | Initial uncontrolled value and form-reset baseline. Changes while pristine update the value; after interaction they affect the next reset. Without a default, scalar reset uses `min` and range reset uses `[min, max]`. |
 | `disabled?` | boolean | — | Disables pointer and keyboard interaction. |
 | `inverted?` | boolean | — | Fill the rail outside the selected value or range. |
 | `label?` | ReactNode | — | Visible field label, shown above the rail. A string supplies the slider's accessible name; give a rich label an explicit `aria-label`. |
 | `markers?` | SliderMarker[] | — | Compact text labels positioned below the rail. They do not add dots or ticks to the rail. |
-| `max?` | number | 100 | Highest permitted value. |
-| `min?` | number | 0 | Lowest permitted value. |
+| `max?` | number | 100 | Highest permitted value. A lower bound than `min` collapses the range to `min`. Nonfinite values use 100. |
+| `min?` | number | 0 | Lowest permitted value and step origin. Nonfinite values use 0. |
 | `name?` | string | — | Form field name. A range submits two values under this name. |
-| `onValueChange?` | (event, attrs) => void | — | Fires on every keyboard or pointer value change. |
-| `onValueCommit?` | (event, attrs) => void | — | Fires after a drag ends and after each keyboard value change. |
+| `onValueChange?` | (event, attrs) => void | — | Reports each distinct requested value during a drag and each keyboard step. `onInput` runs first. The snapshot contains the requested value and effective constraints; the element's `value` remains the applied value. Controlled sliders accept by updating `value` and reject by leaving it unchanged. Events are notifications; `preventDefault()` does not veto a value request. |
+| `onValueCommit?` | (event, attrs) => void | — | Reports the final requested value after a drag, cancellation, or capture loss, and after each keyboard step. `onChange` runs first. A drag ending at its starting value is silent. Controlled requests can commit without being accepted. Uncontrolled form reset emits both callbacks when it changes the value; state restoration and application updates are silent. |
 | `round?` | boolean \| number \| string | — | Fully round the rail and thumb. Pass a number (px) or CSS length string for a shared custom radius. |
 | `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=24px, medium=28px, large=32px tall. |
-| `step?` | number | 1 | Smallest keyboard and drag increment. |
+| `step?` | number | 1 | Smallest keyboard and drag increment. Nonpositive and nonfinite values use 1. Page keys move by at least one step, or one tenth of the range. |
 | `thumbFill?` | boolean | false | Fill the thumb with its resolved border color. This follows `thumbTone` and interactive states. |
 | `thumbSize?` | number \| string | 16 | Diameter of the thumb. Numbers use pixels; strings are CSS lengths. Keep it at least as large as `trackSize`. |
-| `thumbTone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the thumb stroke. Pass a named tone or a literal CSS color for a one-off custom tone. Omit it to keep the thumb neutral. |
+| `thumbTone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' (the Antithesis theme follows `tone`) | Color of the thumb stroke. Pass a named tone or a literal CSS color for a one-off custom tone. An explicit `neutral` keeps the thumb neutral in every theme. |
 | `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Color of the filled rail. Pass a named tone or a literal CSS color for a one-off custom tone. The unfilled rail stays neutral. |
 | `trackClick?` | 'drag-only' \| 'jump' | 'drag-only' | Controls what happens when the rail is pressed. `drag-only` starts dragging from the current value. `jump` first moves to the pressed position. |
 | `trackSize?` | number \| string | 2 | Thickness of both rail segments. Numbers use pixels; strings are CSS lengths. Keep it no larger than the thumb diameter. |
-| `value?` | number \| SliderRangeValue | — | Controlled value. A pair of numbers selects a range. Update it from `onValueChange`. |
+| `value?` | number \| SliderRangeValue | — | Controlled numeric value. A pair selects a range, ordered low to high. Omit or pass `undefined` for uncontrolled use; `0` stays controlled. Runtime `null` is treated as omission; it is not a controlled empty value. Takes precedence over `defaultValue`, including on form reset. Values are clamped to the bounds and rounded to a step measured from `min`. Releasing control retains the last applied value. There is no empty numeric state. |
 | `valueDisplay?` | 'end' \| 'inline' \| 'thumb' \| 'none' | 'end' | Where the live value appears. `end` puts it at the right edge of the label row. `inline` renders `Label: value`. `thumb` keeps it above the thumb. |
 | `valuePrefix?` | string | — | Text inserted before the live numeric value, such as `$`. |
 | `valueSuffix?` | string | — | Text inserted after the live numeric value, such as `%` or `°C`. |
 
 ## Web Component
 
-Use `<a-slider>` when you are not using React or Preact. Add its `role` and accessible name yourself, then register it from `@antadesign/anta/elements`.
+Use `<a-slider>` with `value` for a controlled value or `defaultvalue` for an
+uncontrolled initial value. Reading the `value` property returns the applied
+number or sorted pair. `input` and `change` events carry request snapshots in
+`event.detail`; accept a controlled request by assigning `event.detail.value` to
+the `value` property. Application updates are silent. See
+[Install and configure](../install-config.md) for imports and hydration setup.
+
+Setting the `value` property reflects the controlled `value` attribute. Removing
+that attribute, or assigning `null` or `undefined` to the property, releases
+control and retains the last applied number. Assigning `defaultValue` reflects
+`defaultvalue`. Uncontrolled interaction, reset, and restoration never rewrite
+these attributes. The applied value stays in internal state and form submission.
+
+Add `tabindex="0"` to a scalar slider, and supply its accessible name. The element
+provides the default slider or group role through `ElementInternals`.
 
 For a range, separate the two numbers with a space in `value` or `defaultvalue`.
 Use `role="group"` and give the range an accessible name. Each thumb receives
@@ -192,7 +287,29 @@ as `Slider`. In raw HTML, `round` needs a CSS length such as `"4px"`; JSX
 
 ## Styling
 
-`Slider` renders an `<a-slider>` with a circular thumb. `tone` and `thumbTone` accept named or custom CSS colors; custom values use the public `--slider-tone-source` and `--slider-thumb-tone-source` knobs. Use `round` to shape the rail and thumb together. Target its shadow parts to change their presentation without taking on the interaction code: `::part(thumb)` customizes the thumb’s surface and stroke. The element exposes `header`, `label`, `value`, `control`, `track`, `fill`, `thumb`, `thumb-value`, `markers`, and `extras`.
+`Slider` renders an `<a-slider>` with a circular thumb. `tone` and `thumbTone` accept named or custom CSS colors; custom values use the public `--slider-tone-source` and `--slider-thumb-tone-source` knobs. Use `round` to shape the rail and thumb together. Target its shadow parts to change their presentation without taking on the interaction code: `::part(thumb)` customizes the thumb’s surface and stroke. Existing parts remain available: `header`, `label`, `value`, `control`, `track`,
+`fill`, `thumb`, `thumb-value`, `markers`, and `extras`. `thumb-1` and `thumb-2`
+identify physical thumbs and retain their identity when crossing. Additional parts
+include `rail-area`, `inline-value`, `end-value`, `value-separator`, `value-affix`,
+`fill-start`, `fill-end`, `thumb-value-1`, and `thumb-value-2`.
+
+Defaults load from external CSS, including styles for these shadow parts. Place
+consumer overrides in `components`, `utilities`, or unlayered CSS; earlier `base`
+rules lose to Anta defaults. Load Slider CSS in the same root as the host when
+rendering inside a consumer shadow root. Existing part names may have additional
+tokens, so use `[part~="thumb"]` for shadow queries.
+
+Public host states describe applied presentation: `range`, `dragging`,
+`pointer-focus`, `thumb-1-active`, and `thumb-2-active`. The active-thumb states
+identify the most recently focused or pressed physical thumb. Region states
+`has-header`, `has-markers`, `has-extras`, `has-fill`, `has-fill-end`,
+`has-thumb-value`, and `has-thumb-value-end` indicate visible regions, including
+coincident range bubbles.
+
+Custom colors, radius, sizing, marker positions, and application `style` props can
+serialize inline style attributes during SSR. Under `style-src-attr 'none'`, use
+external consumer CSS for those values; see [CSP guidance](../install-config.md#content-security-policy).
+Default external styling does not remove that separate inline-style constraint.
 
 ```css
 /* The class is only for the demo. Use your own selector. */

package/docs/components/steps.md

@@ -208,7 +208,8 @@ const index = options.findIndex((option) => option.value === phase)
 ## Orientation
 
 Horizontal steps scroll when needed. Vertical steps place the active panel before
-the next step.
+the next step. This layout uses external CSS and needs no inline style attributes
+under a strict [Content Security Policy](../install-config.md#content-security-policy).
 
 ```tsx
 <Steps
@@ -288,8 +289,10 @@ shipped Steps stylesheet. The [Tabs Web Component](./tabs.md#web-component) insi
 owns selection and panel behavior; markers, states, and tones stay in your markup.
 
 ```js
-import '@antadesign/anta/elements'
-import '@antadesign/anta/components/Steps.css'
+import '@antadesign/anta/elements/a-steps'
+import '@antadesign/anta/elements/a-tabs'
+import '@antadesign/anta/elements/a-tab'
+import '@antadesign/anta/elements/a-tabpanel'
 ```
 
 ```html

package/docs/components/switch.md

@@ -2,7 +2,8 @@
 
 Switches change a single setting immediately. Use a checkbox when people select one or more values to submit together.
 
-The `Switch` wrapper renders a form-associated `<a-switch>` element. It works uncontrolled with `defaultChecked`, or controlled with `checked` and `onStateChange`.
+Use `defaultChecked` for an initial setting, or pair `checked` with
+`onStateChange` when the application controls the setting.
 
 ## Tone
 
@@ -121,10 +122,9 @@ Use **`onStateChange`** to intercept a toggle or drive a controlled switch. Use
 
 ## Accessibility
 
-The wrapper sets `role="switch"`, and the element keeps `aria-checked` in sync
-with the current value. Its light-DOM label supplies the accessible name and its
-hint supplies the accessible description through `ElementInternals`; no generated
-IDs are needed. For a label-less switch, pass `aria-label`.
+The label names the switch for screen readers, and the hint supplies its
+description. Without a visible label, pass `aria-label`. Screen readers
+announce the current state.
 
 Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
 
@@ -150,10 +150,9 @@ Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w
 
 ## Web Component
 
-Use the web component directly when you are not using React or Preact and a native control does not fit.
-
-The focusable host carries the state. Label and hint are light-DOM children that
-the element exposes as its accessible name and description.
+Use `<a-switch>` directly outside JSX. Set `role="switch"` and `tabindex="0"`
+for keyboard access. Its label and hint supply the accessible name and
+description.
 
 ```html
 <a-switch role="switch" tabindex="0" name="updates" default-state="checked">