@antadesign/anta 0.3.18 → 0.3.19

package/docs/components/slider.md

@@ -0,0 +1,142 @@
+# Slider
+
+**`Slider`** selects one numeric value from a range. Its label sits above the rail, and the value appears at the label row’s right edge by default. It works controlled with `value` and `onValueChange`, or uncontrolled with `defaultValue`.
+
+## Relative dragging
+
+Pressing the rail starts a grab from its current value. Moving right increases the value; moving left decreases it. The thumb does not jump to the press position. This is the default `trackClick="drag-only"` behaviour.
+
+Set `trackClick="jump"` for the conventional range-input interaction, where pressing the rail first moves the thumb to that position.
+
+Arrow keys change by `step`. Home and End set the minimum and maximum. PageUp and PageDown move by one tenth of the range.
+
+```tsx
+<Slider label="Relative drag" defaultValue={35} />
+<Slider label="Jump on press" defaultValue={35} trackClick="jump" />
+```
+
+## Value placement
+
+`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="%" />
+```
+
+## 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 colour. `tone` colours the filled rail. `thumbTone` separately colours 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.
+
+```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} />
+<Slider size="large" tone="success" round={4} label="Large, 4px corners" defaultValue={72} />
+```
+
+## Markers
+
+`markers` places compact, muted labels below the rail. Values at or below `min` align left; values at or above `max` align right. Markers do not add dots or ticks to the rail.
+
+```tsx
+<Slider
+  label="Playback speed"
+  min={0.5}
+  max={2}
+  step={0.25}
+  defaultValue={1}
+  markers={[
+    { value: 0.5, label: '0.5×' },
+    { value: 1, label: 'Normal' },
+    { value: 2, label: '2×' },
+  ]}
+/>
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `defaultValue?` | number | 0 | Initial uncontrolled value. |
+| `disabled?` | boolean | — | Disables pointer and keyboard interaction. |
+| `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. |
+| `name?` | string | — | Form field name. The current numeric value submits 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. |
+| `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. |
+| `thumbFill?` | boolean | false | Fill the thumb with its resolved border colour. This follows `thumbTone`
+and interactive states. |
+| `thumbSize?` | number \| string | 18 | 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' | Colour of the thumb stroke. Pass a named tone or a literal CSS colour for a
+one-off custom tone. Omit it to keep the thumb neutral. |
+| `tone?` | 'neutral' \| 'brand' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'neutral' | Colour of the filled rail. Pass a named tone or a literal CSS colour for a
+one-off custom tone. The unfilled rail stays neutral. |
+| `trackClick?` | 'drag-only' \| 'jump' | 'drag-only' | Track press behaviour. `drag-only` starts a relative grab from the current
+value; `jump` first moves to the press 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 | — | Controlled value. Update it from `onValueChange`. |
+| `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`. |
+
+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`.
+
+```html
+<a-slider
+  role="slider"
+  tabindex="0"
+  aria-label="Volume"
+  name="volume"
+  defaultvalue="50"
+  track-size="4px"
+  thumb-fill
+  thumb-size="20px"
+  value-suffix="%"
+>
+  <span slot="label">Volume</span>
+</a-slider>
+```
+
+### Native HTML range input
+
+Add `data-anta` to a native range input for Anta's rail, fill, thumb, and focus
+treatment while retaining the browser's form, keyboard, and pointer behavior.
+
+Use `size="small"` or `"large"` for the 24px and 32px control sizes.
+`track-size` accepts a CSS length and changes both rail segments. `tone`,
+`thumb-tone`, `thumb-fill`, `thumb-size`, and `round` use the same attributes
+as `Slider`. In raw HTML, `round` needs a CSS length such as `"4px"`; JSX
+`round={4}` remains a numeric pixel value.
+
+```html
+<input data-anta type="range" min="0" max="100" value="48" aria-label="Native range">
+<input data-anta type="range" min="0" max="100" value="32" size="small" tone="info" aria-label="Small info native range">
+<input data-anta type="range" min="0" max="100" value="52" tone="brand" thumb-tone="success" track-size="4px" thumb-fill thumb-size="20px" aria-label="Brand native range with a large filled success thumb">
+<input data-anta type="range" min="0" max="100" value="72" size="large" tone="success" round="4px" aria-label="Large rounded success native range">
+```
+
+## Styling
+
+`Slider` renders an `<a-slider>` with a circular thumb. `tone` and `thumbTone` accept named or custom CSS colours; 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)` customises the thumb’s surface and stroke. The element exposes `header`, `label`, `value`, `control`, `track`, `fill`, `thumb`, `thumb-value`, `markers`, and `extras`.
+
+```css
+/* The class is only for the demo. Use your own selector. */
+.warm-slider::part(fill) { background: #e5484d; }
+.warm-slider::part(thumb) {
+  background: #fff7ed;
+  border-color: #e5484d;
+  border-radius: 4px;
+}
+```

package/docs/components/switch.md

@@ -0,0 +1,198 @@
+# Switch
+
+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`.
+
+## Tone
+
+`tone` colours the whole control: the checked track, plus the unchecked track border and thumb. Six named tones are available, or pass any CSS color for a custom tone. The label and hint stay neutral.
+
+```tsx
+<Switch defaultChecked tone="neutral" label="Neutral" />
+<Switch defaultChecked tone="brand" label="Brand" />
+<Switch defaultChecked tone="critical" label="Critical" />
+<Switch defaultChecked tone="mediumaquamarine" label="Custom color" />
+```
+
+## Selected-only tone
+
+`toneSelected` colours the checked track only. The unchecked track and thumb stay neutral until the switch is on. Use it when a resting tinted control could imply a validation state. It accepts the same values as `tone`.
+
+```tsx
+<Switch toneSelected="brand" label="Off stays neutral" />
+<Switch defaultChecked toneSelected="critical" label="Checked track tinted" />
+```
+
+## Colouring the text
+
+There is no text-tone prop. To tint the label, set `color` on the switch with a theme-aware `--text-N-{tone}` token; to tint the hint, target `a-switch-hint`. Pair either with `tone` or `toneSelected` to colour the whole control.
+
+```css
+/* The class is only for the demo — use your own selector. */
+a-switch.toned-text { color: var(--text-1-critical); }
+a-switch.toned-text a-switch-hint { color: var(--text-3-critical); }
+```
+
+## Size
+
+Three sizes scale the track, thumb, and label together: `small` (26×16px track), `medium` (30×18px, the default), and `large` (34×20px).
+
+```tsx
+<Switch defaultChecked size="small" label="Small" />
+<Switch defaultChecked label="Medium" />
+<Switch defaultChecked size="large" label="Large" />
+```
+
+## Round or square
+
+Switches are fully rounded by default. Pass `round` with a number (pixels) or CSS length to set the track radius; the thumb radius is 3px smaller. Pass `round={0}` for square track corners.
+
+```tsx
+<Switch defaultChecked round={6} label="6px round" />
+<Switch defaultChecked round={2} label="2px round" />
+<Switch defaultChecked round={0} label="Square" />
+```
+
+## Label & hint
+
+Pass a plain label through `label`, or pass richer label content as children. Add `hint` for a secondary line beneath. `labelPosition="start"` places the label and hint before the control visually while source order remains stable. For a label-less switch, pass `aria-label`.
+
+```tsx
+<Switch defaultChecked label="Email notifications" hint="Weekly digest, never marketing." />
+<Switch defaultChecked label="Automatic updates" labelPosition="start" />
+```
+
+## States
+
+Switches are either unchecked or checked.
+
+```tsx
+<Switch label="Unchecked" />
+<Switch defaultChecked label="Checked" />
+```
+
+## Disabled
+
+The `disabled` attribute dims the switch and removes it from the tab order.
+
+```tsx
+<Switch disabled label="Disabled" />
+<Switch disabled defaultChecked label="Disabled checked" />
+```
+
+## Controlled
+
+Uncontrolled by default: pass `defaultChecked` and read the value from `onStateChange` or at form submit. Make it controlled with `checked` and `onStateChange` to drive it from your store.
+
+```tsx
+const [enabled, setEnabled] = useState(false)
+
+<Switch
+  checked={enabled}
+  onStateChange={(_e, { next }) => setEnabled(next)}
+  label="Enable notifications"
+/>
+```
+
+`onStateChange` fires before the element applies a user toggle, with `(event, { next, prev })`. Call `event.preventDefault()` to veto an uncontrolled change. A controlled switch with no `onStateChange` is read-only.
+
+## Events
+
+Three callbacks, in firing order:
+
+| Callback | When | Cancelable | Payload |
+|---|---|---|---|
+| `onStateChange(e, { next, prev })` | **before** the toggle applies | ✅ `e.preventDefault()` vetoes | next / previous boolean |
+| `onChange(e)` | **after** it applies | — | native `change` event |
+| `onValueChange(e, attrs)` | **after** it applies | — | `{ checked, name, value }` |
+
+Use **`onStateChange`** to intercept a toggle or drive a controlled switch. Use **`onValueChange`** when you only need the new form value.
+
+```tsx
+<Switch
+  name="notifications"
+  onValueChange={(_e, { checked }) => saveNotificationPreference(checked)}
+  label="Email notifications"
+/>
+```
+
+## Accessibility
+
+The wrapper sets `role="switch"` and keeps `aria-checked` in sync with the current value. It derives the accessible name from `label` or text children. For a label-less switch, pass `aria-label`.
+
+Space toggles the switch. It follows the [WAI-ARIA switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/).
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `checked?` | boolean | — | Controlled checked value. In controlled mode, update this in `onStateChange`. |
+| `defaultChecked?` | boolean | false | Initial checked value for an uncontrolled switch. |
+| `disabled?` | boolean | — | Disables interaction and removes the switch from the tab order. |
+| `hint?` | ReactNode | — | Secondary text rendered under the label. It does not become part of the
+accessible name. |
+| `label?` | string | — | Visible, stable label for the setting. Use `children` for richer label content. |
+| `labelPosition?` | 'start' \| 'end' | 'end' | Put the visible label before or after the control. Grid layout changes only
+the visual order, preserving DOM/source order for assistive technologies. |
+| `name?` | string | — | Form field name. A checked switch submits `value` under this name. |
+| `onChange?` | (event) => void | — | Native post-apply `change` event. |
+| `onStateChange?` | (event, detail) => void | — | Fired before a user toggle applies. Call `event.preventDefault()` to veto an
+uncontrolled change; controlled consumers accept by updating `checked`. |
+| `onValueChange?` | (event, attrs) => void | — | Post-apply callback with the new form-relevant value snapshot. |
+| `round?` | boolean \| number \| string | — | Fully round the thumb and track. Pass a `number` (px) or CSS length string
+for a custom track radius; the thumb radius is 3px smaller. |
+| `size?` | 'small' \| 'medium' \| 'large' | 'medium' | Size variant. small=26×16px, medium=30×18px, large=34×20px. |
+| `tone?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Colour of the track and thumb. A tinted tone also colours the unchecked
+track border and thumb; use `toneSelected` to colour only the checked track. |
+| `toneSelected?` | 'brand' \| 'neutral' \| 'info' \| 'success' \| 'warning' \| 'critical' \| (string & {}) | 'brand' | Like `tone`, but applies only while the switch is checked. The unchecked
+track and thumb stay neutral. If both are set, `tone` colours the unchecked
+state and `toneSelected` colours the checked track. |
+| `value?` | string | "on" | Value submitted while checked. |
+
+Use this when you are not using the React or Preact wrapper and a native HTML control does not fit: construct the equivalent Anta web component from the elements below.
+
+The focusable host carries the state. Label and hint are light-DOM children.
+
+```html
+<a-switch role="switch" tabindex="0" name="updates" default-state="checked">
+  <a-switch-label>Email updates</a-switch-label>
+  <a-switch-hint>Product and security notices.</a-switch-hint>
+</a-switch>
+```
+
+Reach for the props first: **`tone`** colours the checked track plus the unchecked chrome, while **`toneSelected`** colours only the checked track. Both accept any CSS color; **`size`** scales the control, label, and hint. The focus ring is the global [`--focus-ring`](../colors.md#focus-ring).
+
+```tsx
+<Switch tone="#e0457b" defaultChecked label="Custom colour" />
+```
+
+`<a-switch>` is light DOM. The **track is `::before`**, the **thumb is `::after`**, and the label / hint are `a-switch-label` / `a-switch-hint` children. Target them with plain CSS. The classes below are only for the demos.
+
+```css
+a-switch.strong-label {
+  color: var(--text-1-brand);
+  font-weight: 700;
+}
+
+/* A CSS-only check / × in the free part of the track. */
+a-switch.track-marks::before {
+  display: flex;
+  align-items: center;
+  font-size: 10px;
+  font-weight: 700;
+  line-height: 1;
+}
+a-switch.track-marks:state(checked)::before {
+  content: "✓";
+  justify-content: flex-start;
+  padding-inline-start: 4px;
+  color: var(--switch-thumb);
+}
+a-switch.track-marks:not(:state(checked))::before {
+  content: "×";
+  justify-content: flex-end;
+  padding-inline-end: 4px;
+  color: var(--switch-track-off-stroke);
+}
+```