@cdx-ui/components 0.2.3 → 0.2.4

package/docs/components/slider/content.md

@@ -0,0 +1,423 @@
+# Slider (https://design.candescent.com/docs/components/slider)
+
+Resources: [Figma](https://www.figma.com/design/0lEVMVlLj8ZS4fgItr3pmd/%E2%AD%90-Forge-DS--Components?node-id=11500-17763), [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/inputs-slider--default)
+
+A compound component with sub-components for the rail, track fill, thumb, optional value popup, and step marks.
+
+```tsx
+import { Slider } from '@cdx-ui/components';
+```
+
+## Basic
+
+```tsx
+import { useState } from 'react';
+import { Slider } from '@cdx-ui/components';
+
+export default function SliderBasicDemo() {
+  const [value, setValue] = useState(55);
+
+  return (
+    <Slider
+      value={value}
+      onChange={setValue}
+      min={0}
+      max={100}
+      step={1}
+      accessibilityLabel="Volume"
+    >
+      <Slider.Rail>
+        <Slider.Track />
+      </Slider.Rail>
+      <Slider.Thumb>
+        <Slider.Popup />
+      </Slider.Thumb>
+    </Slider>
+  );
+}
+```
+
+## Range
+
+Use array `value` / `defaultValue` and `onChange` for a two-thumb range. Set an explicit `index` on each `Slider.Thumb` and provide per-thumb `accessibilityLabel` values (for example, minimum and maximum price).
+
+```tsx
+import { useState } from 'react';
+import { Slider } from '@cdx-ui/components';
+
+export default function SliderRangeDemo() {
+  const [value, setValue] = useState<number[]>([200, 800]);
+
+  return (
+    <Slider
+      value={value}
+      onChange={setValue}
+      min={0}
+      max={1000}
+      step={10}
+      accessibilityLabel="Price range"
+    >
+      <Slider.Rail>
+        <Slider.Track />
+      </Slider.Rail>
+      <Slider.Thumb index={0} accessibilityLabel="Minimum price">
+        <Slider.Popup />
+      </Slider.Thumb>
+      <Slider.Thumb index={1} accessibilityLabel="Maximum price">
+        <Slider.Popup />
+      </Slider.Thumb>
+    </Slider>
+  );
+}
+```
+
+## With marks
+
+Add `Slider.MarkerGroup` with a `Slider.Marker` child; marks are placed at each `step` interval.
+
+```tsx
+import { useState } from 'react';
+import { Box, Slider } from '@cdx-ui/components';
+
+export default function SliderWithMarksDemo() {
+  const [value, setValue] = useState(50);
+  const [rangeValue, setRangeValue] = useState<number[]>([20, 70]);
+
+  return (
+    <Box className="w-full gap-10">
+      <Slider
+        value={value}
+        onChange={setValue}
+        min={0}
+        max={100}
+        step={10}
+        accessibilityLabel="Volume"
+      >
+        <Slider.Rail>
+          <Slider.Track />
+        </Slider.Rail>
+        <Slider.Thumb>
+          <Slider.Popup />
+        </Slider.Thumb>
+        <Slider.MarkerGroup>
+          <Slider.Marker />
+        </Slider.MarkerGroup>
+      </Slider>
+      <Slider
+        value={rangeValue}
+        onChange={setRangeValue}
+        min={0}
+        max={100}
+        step={10}
+        accessibilityLabel="Volume range"
+      >
+        <Slider.Rail>
+          <Slider.Track />
+        </Slider.Rail>
+        <Slider.Thumb index={0} accessibilityLabel="Minimum volume">
+          <Slider.Popup />
+        </Slider.Thumb>
+        <Slider.Thumb index={1} accessibilityLabel="Maximum volume">
+          <Slider.Popup />
+        </Slider.Thumb>
+        <Slider.MarkerGroup>
+          <Slider.Marker />
+        </Slider.MarkerGroup>
+      </Slider>
+    </Box>
+  );
+}
+```
+
+## Vertical
+
+Use `orientation="vertical"`. The thumb travels along the rail from bottom to top. Single-value, range, and step marks all work the same way as they do horizontally.
+
+```tsx
+import { useState } from 'react';
+import { Box, Slider } from '@cdx-ui/components';
+
+export default function SliderVerticalDemo() {
+  const [value, setValue] = useState(40);
+  const [rangeValue, setRangeValue] = useState<number[]>([25, 75]);
+  const [steppedValue, setSteppedValue] = useState(60);
+
+  return (
+    <Box className="h-56 flex-row items-center gap-12">
+      <Slider
+        orientation="vertical"
+        value={value}
+        onChange={setValue}
+        min={0}
+        max={100}
+        accessibilityLabel="Level"
+      >
+        <Slider.Rail>
+          <Slider.Track />
+        </Slider.Rail>
+        <Slider.Thumb>
+          <Slider.Popup />
+        </Slider.Thumb>
+      </Slider>
+      <Slider
+        orientation="vertical"
+        value={rangeValue}
+        onChange={setRangeValue}
+        min={0}
+        max={100}
+        accessibilityLabel="Level range"
+      >
+        <Slider.Rail>
+          <Slider.Track />
+        </Slider.Rail>
+        <Slider.Thumb index={0} accessibilityLabel="Minimum level">
+          <Slider.Popup />
+        </Slider.Thumb>
+        <Slider.Thumb index={1} accessibilityLabel="Maximum level">
+          <Slider.Popup />
+        </Slider.Thumb>
+      </Slider>
+      <Slider
+        orientation="vertical"
+        value={steppedValue}
+        onChange={setSteppedValue}
+        min={0}
+        max={100}
+        step={10}
+        accessibilityLabel="Stepped level"
+      >
+        <Slider.Rail>
+          <Slider.Track />
+        </Slider.Rail>
+        <Slider.Thumb>
+          <Slider.Popup />
+        </Slider.Thumb>
+        <Slider.MarkerGroup>
+          <Slider.Marker />
+        </Slider.MarkerGroup>
+      </Slider>
+    </Box>
+  );
+}
+```
+
+## With field
+
+Compose with `Field` and `Field.Label` for a labeled slider. Set `accessibilityLabel` on `Slider` to match the visible label text.
+
+```tsx
+import { useState } from 'react';
+import { Field, Slider } from '@cdx-ui/components';
+
+export default function SliderWithFieldDemo() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <Field className="w-full">
+      <Field.Label>Image Size</Field.Label>
+      <Slider
+        value={value}
+        onChange={setValue}
+        min={0}
+        max={100}
+        step={1}
+        accessibilityLabel="Image Size"
+      >
+        <Slider.Rail>
+          <Slider.Track />
+        </Slider.Rail>
+        <Slider.Thumb>
+          <Slider.Popup />
+        </Slider.Thumb>
+      </Slider>
+    </Field>
+  );
+}
+```
+
+## With icons
+
+Decorative icons on each end — a common volume or intensity control pattern. Mark icons `aria-hidden` because the slider exposes the value via `accessibilityLabel`.
+
+```tsx
+import { useState } from 'react';
+import { Box, Icon, Slider } from '@cdx-ui/components';
+import { VolumeDown, VolumeUp } from '@cdx-ui/icons';
+
+export default function SliderWithIconsDemo() {
+  const [value, setValue] = useState(50);
+
+  return (
+    <Box className="w-full flex-row items-center gap-3">
+      <Icon as={VolumeDown} color="secondary" className="shrink-0" aria-hidden />
+      <Box className="min-w-0 flex-1">
+        <Slider
+          value={value}
+          onChange={setValue}
+          min={0}
+          max={100}
+          step={1}
+          accessibilityLabel="Volume"
+        >
+          <Slider.Rail>
+            <Slider.Track />
+          </Slider.Rail>
+          <Slider.Thumb>
+            <Slider.Popup />
+          </Slider.Thumb>
+        </Slider>
+      </Box>
+      <Icon as={VolumeUp} color="secondary" className="shrink-0" aria-hidden />
+    </Box>
+  );
+}
+```
+
+## Disabled
+
+```tsx
+import { Slider } from '@cdx-ui/components';
+
+export default function SliderDisabledDemo() {
+  return (
+    <Slider isDisabled defaultValue={30} min={0} max={100} accessibilityLabel="Disabled volume">
+      <Slider.Rail>
+        <Slider.Track />
+      </Slider.Rail>
+      <Slider.Thumb>
+        <Slider.Popup />
+      </Slider.Thumb>
+    </Slider>
+  );
+}
+```
+
+## API
+
+### Slider
+
+Root container that manages value, range (`min`/`max`/`step`), orientation, and disabled state. On web the root is a grouping element (`role="group"`); each `Slider.Thumb` is the focusable slider control.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `orientation?` | `'horizontal' \| 'vertical'` | — | — |
+| `min?` | `number` | ``0`` | Minimum selectable value. |
+| `max?` | `number` | ``100`` | Maximum selectable value. |
+| `step?` | `number` | ``1`` | Increment used to snap value updates and generate automatic `Slider.MarkerGroup` marks. |
+| `isDisabled?` | `boolean` | ``false`` | Disables pointer, keyboard, and screen reader interaction. |
+| `value?` | `number \| readonly number[]` | — | — |
+| `defaultValue?` | `number \| readonly number[]` | — | Initial uncontrolled value. Defaults to `min`. Initial uncontrolled thumb values. |
+| `onChange?` | `((value: number) => void) \| ((value: number[]) => void)` | — | Called while the value changes. Called while any thumb value changes. |
+| `onChangeComplete?` | `((value: number) => void) \| ((value: number[]) => void)` | — | Called when a pointer, keyboard, or screen reader interaction completes. |
+| `color?` | `'action' \| 'danger' \| 'warning' \| 'success' \| 'info'` | ``action`` | Semantic color token for the track fill and thumb border. |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+| Attribute          | Values                     | Description                                 |
+| ------------------ | -------------------------- | ------------------------------------------- |
+| `data-orientation` | `horizontal` \| `vertical` | Slider axis                                 |
+| `data-disabled`    | `true` \| `false`          | Disabled state                              |
+| `data-dragging`    | `true` \| `false`          | Active drag state                           |
+| `data-hover`       | `true` \| `false`          | Whether a thumb is hovered (web)            |
+| `data-focus`       | `true` \| `false`          | Whether a thumb is focused                  |
+| `data-values`      | string                     | Comma-separated thumb values (e.g. `20,80`) |
+| `data-min`         | string                     | Minimum value                               |
+| `data-max`         | string                     | Maximum value                               |
+
+## Sub-components
+
+### Slider.Rail
+
+Full track background and hit area for tap and drag interactions. Accepts `Slider.Track` as a child for the filled portion.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Slider.Track
+
+Filled portion of the rail that reflects the current value and semantic `color` token. Width (horizontal) or height (vertical) is computed automatically.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Slider.Thumb
+
+Draggable thumb control. Pass `index` for range sliders (`0` for the first thumb, `1` for the second). Each thumb is individually focusable with `role="slider"` on web and `accessibilityRole="adjustable"` on native. Compose optional `Slider.Popup` as a child to show a value tooltip on hover, focus, or drag.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | Either children or a render prop that receives a boolean reflecting whether the component is currently pressed. |
+| `index?` | `number` | — | Zero-based thumb index. Defaults to `0` for single-value sliders. |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`PressableProps`](https://reactnative.dev/docs/pressable#props).
+
+### Slider.Popup
+
+Optional value tooltip rendered inside `Slider.Thumb`. Omit when no tooltip is needed. Defaults to the formatted numeric value; pass `children` for a custom label.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Slider.MarkerGroup
+
+Optional container for step marks along the rail. When a single template `Slider.Marker` (without `value`) is provided, the group clones it at each `step` interval between `min` and `max`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### Slider.Marker
+
+Individual step mark. For single-value sliders, marks at or below the current value render filled. For ranges, marks inside `[values[0], values[n-1]]` render filled. Omit `value` for auto step cloning inside `Slider.MarkerGroup`.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `ReactNode` | — | — |
+| `asChild?` | `boolean` | — | — |
+| `value?` | `number` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+## Anatomy
+
+| `data-slot`           | Element                                    |
+| --------------------- | ------------------------------------------ |
+| `slider`              | Root container                             |
+| `slider-rail`         | Full track background and interaction area |
+| `slider-track`        | Filled track segment                       |
+| `slider-thumb`        | Draggable value control                    |
+| `slider-popup`        | Optional value tooltip                     |
+| `slider-marker-group` | Step marks container                       |
+| `slider-marker`       | Individual step mark                       |
+
+## Accessibility
+
+On web, the root uses `role="group"` and each thumb uses `role="slider"` with value bounds derived from its neighbours. Arrow keys adjust the focused thumb; Home and End move it to its current bounds.
+
+On native, each thumb uses `accessibilityRole="adjustable"` and responds to increment and decrement actions. Its numeric `accessibilityValue` is normalized to 0–100 while `text` announces the formatted value.
+
+Give each thumb a distinct `accessibilityLabel` in range sliders. The root label names the group. The rail, track, marks, and popup are hidden from the accessibility tree.

package/docs/components/stack/content.md

@@ -0,0 +1,161 @@
+# Stack (https://design.candescent.com/docs/components/stack)
+
+Resources: [Storybook](https://victorious-wave-0daadf00f.6.azurestaticapps.net/?path=/story/layout-vstack--default)
+
+`HStack` and `VStack` arrange children along the horizontal or vertical axis.
+
+```tsx
+import { HStack, VStack } from '@cdx-ui/components';
+```
+
+## Horizontal stack
+
+Use `HStack` to arrange related content in a row.
+
+```tsx
+import { Box, HStack, Text } from '@cdx-ui/components';
+
+export default function StackHorizontalDemo() {
+  return (
+    <HStack space="md">
+      <Box className="rounded-lg border border-stroke-secondary bg-surface-secondary px-4 py-3">
+        <Text>Checking</Text>
+      </Box>
+      <Box className="rounded-lg border border-stroke-secondary bg-surface-secondary px-4 py-3">
+        <Text>Savings</Text>
+      </Box>
+      <Box className="rounded-lg border border-stroke-secondary bg-surface-secondary px-4 py-3">
+        <Text>Credit</Text>
+      </Box>
+    </HStack>
+  );
+}
+```
+
+## Vertical stack
+
+Use `VStack` to arrange related content in a column.
+
+```tsx
+import { Box, Text, VStack } from '@cdx-ui/components';
+
+export default function StackVerticalDemo() {
+  return (
+    <VStack space="md" className="w-full max-w-sm">
+      <Box className="rounded-lg border border-stroke-secondary bg-surface-secondary px-4 py-3">
+        <Text>Account details</Text>
+      </Box>
+      <Box className="rounded-lg border border-stroke-secondary bg-surface-secondary px-4 py-3">
+        <Text>Transfer settings</Text>
+      </Box>
+      <Box className="rounded-lg border border-stroke-secondary bg-surface-secondary px-4 py-3">
+        <Text>Notifications</Text>
+      </Box>
+    </VStack>
+  );
+}
+```
+
+## Spacing
+
+Use `space` to apply a token-based gap between children. Both components support `xs` through `6xl`.
+
+```tsx
+import { Box, HStack, Text, VStack } from '@cdx-ui/components';
+
+const SPACES = ['xs', 'md', 'xl', '3xl'] as const;
+
+export default function StackSpacingDemo() {
+  return (
+    <VStack space="lg">
+      {SPACES.map((space) => (
+        <VStack key={space} space="xs">
+          <Text size="sm" color="secondary">
+            {space}
+          </Text>
+          <HStack space={space}>
+            <Box className="size-8 rounded-md bg-surface-action-strong" />
+            <Box className="size-8 rounded-md bg-surface-action-strong" />
+            <Box className="size-8 rounded-md bg-surface-action-strong" />
+          </HStack>
+        </VStack>
+      ))}
+    </VStack>
+  );
+}
+```
+
+## Reversed order
+
+Set `reversed` to reverse the visual order of children along the stack axis. Source and screen-reader order remain unchanged.
+
+```tsx
+import { Box, HStack, Text, VStack } from '@cdx-ui/components';
+
+// The on-strong text class is allowed because this demo paints the surface itself. See "Text on a
+// colored surface" on the Styling and customization page.
+function NumberedItem({ children }: { children: string }) {
+  return (
+    <Box className="size-10 items-center justify-center rounded-lg bg-surface-action-strong">
+      <Text className="text-content-action-on-strong">{children}</Text>
+    </Box>
+  );
+}
+
+export default function StackReversedDemo() {
+  return (
+    <VStack space="lg">
+      <VStack space="xs">
+        <Text size="sm" color="secondary">
+          Default
+        </Text>
+        <HStack space="sm">
+          <NumberedItem>1</NumberedItem>
+          <NumberedItem>2</NumberedItem>
+          <NumberedItem>3</NumberedItem>
+        </HStack>
+      </VStack>
+      <VStack space="xs">
+        <Text size="sm" color="secondary">
+          Reversed
+        </Text>
+        <HStack space="sm" reversed>
+          <NumberedItem>1</NumberedItem>
+          <NumberedItem>2</NumberedItem>
+          <NumberedItem>3</NumberedItem>
+        </HStack>
+      </VStack>
+    </VStack>
+  );
+}
+```
+
+## API
+
+`HStack` and `VStack` share the same layout props and inherit React Native `ViewProps`.
+
+### HStack
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `ref?` | `React.Ref<View>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| `space?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl'` | — | Token-based gap between children. |
+| `reversed?` | `boolean` | `false` | Reverses the visual order of children along the stack axis. Source order and screen-reader order stay unchanged. |
+| `key?` | `React.Key \| null` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).
+
+### VStack
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className?` | `string` | — | — |
+| `children?` | `React.ReactNode` | — | — |
+| `ref?` | `React.Ref<View>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
+| `space?` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl' \| '6xl'` | — | Token-based gap between children. |
+| `reversed?` | `boolean` | `false` | Reverses the visual order of children along the stack axis. Source order and screen-reader order stay unchanged. |
+| `key?` | `React.Key \| null` | — | — |
+
+Inherits all [`ViewProps`](https://reactnative.dev/docs/view#props).