# plocks — Complete Documentation

Every documentation page concatenated in full: component and chart pages with
their props, sub-components and every example, hook pages with their type
definitions, the guides, and the FAQ. Nothing here is truncated.

For an index of the same content as individually fetchable pages, use https://plocks.dev/llms.txt.
For one file sized to a context window, use https://plocks.dev/llms-small.txt.

Every example is a complete module that imports from the published packages (@plocks/ui, @plocks/brands, @plocks/carousel, @plocks/charts, @plocks/code, @plocks/dates, @plocks/emoji-picker, @plocks/media, @plocks/qrcode, @plocks/spotlight).

Install: `npm install @plocks/ui` — separate packages, installed alongside it: `@plocks/brands`, `@plocks/carousel`, `@plocks/charts`, `@plocks/code`, `@plocks/dates`, `@plocks/emoji-picker`, `@plocks/media`, `@plocks/qrcode`, `@plocks/spotlight`. A component page's Import line names the package it comes from.
Version: generated from the `main` branch — `@plocks/ui` 0.2.0, `@plocks/brands` 0.2.0, `@plocks/carousel` 0.2.0, `@plocks/charts` 0.2.0, `@plocks/code` 0.2.0, `@plocks/dates` 0.2.0, `@plocks/emoji-picker` 0.2.0, `@plocks/media` 0.2.0, `@plocks/qrcode` 0.2.0, `@plocks/spotlight` 0.2.0. The branch can be ahead of the latest npm release; if an API here is missing from your installed version, check the changelog: https://github.com/platform-blocks/plocks/tree/main/changelog
Website: https://plocks.dev • GitHub: https://github.com/platform-blocks/plocks • npm: https://www.npmjs.com/package/@plocks/ui

**Conventions**

- Import from the package root: `import { Button, Row, useToast } from '@plocks/ui'`. Some components live in their own package — `@plocks/dates`, `@plocks/charts`, `@plocks/code`, `@plocks/media`, `@plocks/carousel`, `@plocks/spotlight`, `@plocks/brands`, `@plocks/qrcode`, `@plocks/emoji-picker` — installed alongside `@plocks/ui`; each page's Import line names the package.
- Wrap the app once in `<PlocksProvider>` (theme, color scheme, overlays, i18n). `useToast()` and `useDialog()` render through `<ToastProvider>` / `<DialogProvider>` — mount those inside it before calling them. Theming: https://plocks.dev/llms/guides/theming.md
- Lay out with `Block` in place of `View`, `Row` / `Column` for flex stacks (`gap`, `align`, `justify`, `wrap`), and `Grid` + `GridItem` for columns. `Row` and `Column` are documented on the Flex page.
- Most components take the shared style props — spacing (`m`, `p`, `mx`, `py`, …), sizing (`w`, `h`, `fullWidth`, …), `radius`, `shadow` — form inputs share the field props (`label`, `description`, `error`, `helperText`, `required`, …) and charts the chart props. Component pages list their own props and name the shared groups they accept; the groups are defined once here: https://plocks.dev/llms/guides/shared-props.md
- `size`, spacing, `radius` and `shadow` take the tokens `xs` `sm` `md` `lg` `xl` `2xl` `3xl` (default `md`) or a number. `color` takes a palette name (`primary`, `secondary`, `tertiary`, `success`, `warning`, `error`, `gray`), a shade (`'primary.6'`), or any CSS color.
- `Button` is neutral by default — use `variant="filled"` for the primary action. Events use React Native names: `onPress`, `onChange`, never `onClick`.
- `<Icon name="…">` accepts only names in the built-in Tabler registry — do not guess one: https://plocks.dev/llms/guides/icons.md
- Every example is a complete module: real imports from the published packages and an exported `Demo` component. Fixtures it imports (`./data`) are shown beneath it.

**Choosing between similar components**

- On/off or pick-one input: `Switch` for a setting that applies immediately; `Checkbox` for a choice submitted with a form; `ControlField` wraps either (or `Radio`) in a labelled, pressable row; `SegmentedControl` for 2–5 exclusive options shown inline; `RadioGroup` for a vertical list; `Select` for a long list in a dropdown; `AutoComplete` when the list is searched or loaded async; `ToggleGroup` for toolbar-style single or multi selection.
- Tabular data: `Table` for static semantic markup; `DataTable` for sorting, filtering, pagination and row selection; `DataList` for label/value pairs.
- Dates and times: `DatePickerInput` / `TimePickerInput` for a form field that opens a picker; `DatePicker` / `TimePicker` for an inline panel; `Calendar` for a full month grid; `MiniCalendar` for a compact month view; `MonthPicker` / `YearPicker` for coarser choices.
- Colors: `ColorInput` for a hex field plus palette; `ColorPicker` for a swatch button that opens a palette, with no text field; `ColorSwatch` to display a color.
- Floating and transient UI: `Tooltip` for a non-interactive hint; `Popover` for interactive content anchored to a trigger; `Menu` for a list of actions; `ContextMenu` for right-click / long-press; `Dialog` for modal, confirmation or bottom-sheet content; `Toast` (via `useToast()`) for a transient notice; `Alert` for a message that stays inline.
- Loading states: `Loader` for a spinner; `Skeleton` for placeholders shaped like the content; `Progress` (linear) or `Ring` (radial) for measurable progress; `LoadingOverlay` to block a region while work runs.
- Labels and markers: `Badge` for a status, category or count; `Chip` for a tag the user selects, presses or removes; `Indicator` for a dot or count pinned to the corner of another element.
- Containers: `Block` for plain layout; `Card` for a content card (six variants); `Surface` for an elevation level without card chrome; `Space` for a fixed gap where margins do not fit.
- Text: `Text` for body copy and inline variants; `Title` for semantic headings (`order={1..6}`); `Highlight` to mark matches in a string; `GradientText` / `ShimmerText` for decorative emphasis.
- Actions and navigation: `Button` for actions; `IconButton` for icon-only actions (needs `accessibilityLabel`); `Link` for navigation; `Menu` for several related actions behind one trigger; `Tabs`, `Stepper`, `Pagination`, `Breadcrumbs` and `NavTree` for moving between views.

================================================================================

# GUIDES

<!-- source: https://plocks.dev/llms/guides/getting-started.md -->

# Getting started

Install plocks, wire up the provider, and render your first component.

Docs: https://plocks.dev/getting-started

**Prerequisites:**

- [Node.js 20.19.4 or newer](https://nodejs.org/en/download) — An active LTS release (22.x or 24.x) is the safest choice
- [npm 10 or newer](https://www.npmjs.com) — Bundled with Node.js

## Install with npm

Add [@plocks/ui](https://www.npmjs.com/package/@plocks/ui) to your React Native or Expo project:

```bash
npm install @plocks/ui
```

Date pickers, charts, code blocks, media players, the carousel, Spotlight, brand logos, QR codes and emoji picking are separate packages — @plocks/dates, @plocks/charts, @plocks/code, @plocks/media, @plocks/carousel, @plocks/spotlight, @plocks/brands, @plocks/qrcode and @plocks/emoji-picker. Install the ones you use.

## Install the peer dependencies

plocks builds on a handful of packages your app provides. On Expo, install them with expo install so the versions match your SDK:

```bash
npx expo install \
    react-native-reanimated \
    react-native-safe-area-context \
    react-native-svg
```

## Set up the provider

Wrap your root component with PlocksProvider to enable theming:

`App.tsx`

```tsx
import { PlocksProvider } from '@plocks/ui';
import { YourApp } from './YourApp';

export function Demo() {
  return (
    <PlocksProvider>
      <YourApp />
    </PlocksProvider>
  );
}
```

## Verify the install

Render a component to confirm everything is wired up:

`TestComponent.tsx`

```tsx
import { Text, Button, Block } from '@plocks/ui';

export function Demo() {
  return (
    <Button
      title='It works!'
      variant='filled'
      onPress={() => console.log('Success!')}
    />
  )
}
```

## Templates

Start a project from a template with the command below — it asks where to put the project and which template to use (pass `--template expo-min` after `--` to skip the question). Or open a template on GitHub and click "Use this template". Every template ships with plocks, its peer dependencies, and the provider already set up.

```bash
npm create plocks@latest
```

- [expo-template](https://github.com/platform-blocks/expo-template) — Full-featured Expo Router app targeting iOS, Android, and web — dark mode, testing, and linting wired up. (Expo, iOS, Android, Web)

  ```bash
  npm create plocks@latest -- --template expo
  ```
- [expo-min-template](https://github.com/platform-blocks/expo-min-template) — Minimal Expo app — a single screen with the provider set up and nothing else to delete. (Expo, Minimal)

  ```bash
  npm create plocks@latest -- --template expo-min
  ```
- [universal-template](https://github.com/platform-blocks/universal-template) — Cross-platform Expo app with statically rendered web output — one codebase shipping native apps and a real website. (Expo, iOS, Android, Web, Static web)

  ```bash
  npm create plocks@latest -- --template universal
  ```
- [native-template](https://github.com/platform-blocks/native-template) — iOS and Android only — no web configuration, for teams shipping mobile apps exclusively. (Expo, iOS, Android)

  ```bash
  npm create plocks@latest -- --template native
  ```
- [web-template](https://github.com/platform-blocks/web-template) — React Native Web only — plocks components in a web-first single-page app. (Web, React Native Web)

  ```bash
  npm create plocks@latest -- --template web
  ```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/guides/theming.md -->

# Theming

Every component reads one theme object, provided by `PlocksProvider`. Two complete themes ship with the library — `DEFAULT_THEME` (light) and `DARK_THEME` — and by default the provider follows the operating system's color scheme.

## Color scheme

`colorSchemeMode` picks the scheme: `'auto'` (the default) follows the OS, `'light'` and `'dark'` force one. For a user-controlled switch pass `themeModeConfig`; `useThemeMode()` then returns `{ mode, setMode, cycleMode, actualColorScheme }` anywhere below the provider, and throws without it. The chosen mode persists to `localStorage` on web; on native pass `persistence: { get, set }` backed by a synchronous store.

`App.tsx`

```tsx
import { Button, PlocksProvider, type ThemeModeConfig, useThemeMode } from '@plocks/ui';

const themeModeConfig: ThemeModeConfig = { initialMode: 'auto' };

function ThemeToggle() {
  const { mode, cycleMode } = useThemeMode();
  return <Button onPress={cycleMode}>Theme: {mode}</Button>;
}

export default function App() {
  return (
    <PlocksProvider themeModeConfig={themeModeConfig}>
      <ThemeToggle />
    </PlocksProvider>
  );
}
```

## Custom theme

Pass `theme` to change tokens. A partial override is merged onto the built-in theme of the current scheme, so light/dark switching keeps working; an override with an explicit `colorScheme` pins that scheme; a `{ light, dark }` pair gives each scheme its own override. Color ramps have ten shades with the base color at index 5 — light ramps run lightest to darkest, dark ramps darkest to lightest — so a brand palette needs one ramp per scheme. Keep the theme object stable (a module constant or `useMemo`): resolved themes are cached per object.

`App.tsx`

```tsx
import type { ReactNode } from 'react';
import { DARK_THEME, DEFAULT_THEME, PlocksProvider, createTheme } from '@plocks/ui';

const theme = {
  light: createTheme({
    colors: {
      ...DEFAULT_THEME.colors,
      primary: ['#F5F3FF', '#EDE9FE', '#DDD6FE', '#C4B5FD', '#A78BFA', '#7C3AED', '#6D28D9', '#5B21B6', '#4C1D95', '#2E1065'],
    },
  }),
  dark: createTheme({
    colors: {
      ...DARK_THEME.colors,
      primary: ['#1E1033', '#2E1065', '#4C1D95', '#5B21B6', '#6D28D9', '#7C3AED', '#8B5CF6', '#A78BFA', '#C4B5FD', '#DDD6FE'],
    },
  }),
};

export default function App({ children }: { children: ReactNode }) {
  return <PlocksProvider theme={theme}>{children}</PlocksProvider>;
}
```

## Reading tokens

`useTheme()` returns the active `PlocksTheme` — outside a provider it quietly returns `DEFAULT_THEME`. Prefer component props (`color`, `bg`, `p`, `radius`) over reading tokens; reach for the theme when styling your own primitives. `theme.spacing`, `theme.radii` and `theme.fontSizes` hold CSS pixel strings such as `'16px'`, not numbers.

`Callout.tsx`

```tsx
import { Block, Text, useTheme } from '@plocks/ui';

export function Callout({ children }: { children: string }) {
  const theme = useTheme();
  return (
    <Block p="md" style={{ backgroundColor: theme.backgrounds.subtle, borderColor: theme.backgrounds.border, borderWidth: 1 }}>
      <Text style={{ color: theme.text.secondary }}>{children}</Text>
    </Block>
  );
}
```

## Elevation

Express depth with `Surface` rather than hand-picked backgrounds: `level={0..3}` runs page → resting content (cards, panels) → floating content (menus, popovers) → screen-level content (dialogs, sheets, toasts), and `raised` takes the enclosing Surface's level plus one. Light mode shows elevation mostly with shadow, dark mode with a lighter fill and a hairline border.

## Provider props

`PlocksProvider` also mounts the overlay layer, i18n, direction, haptics, reduced motion and a safe-area provider; each has an opt-out below.

```ts
export interface PlocksProviderProps {
  /** Your application */
  children: React.ReactNode;

  /**
   * Custom theme. Either:
   * - a partial override — merged onto the built-in theme of the CURRENT color
   *   scheme, so it keeps light/dark switching (`colorSchemeMode`, OS setting);
   *   in a nested provider, merged onto the parent's theme (see `inherit`);
   * - an override with an explicit `colorScheme` — pins that scheme;
   * - a `{ light, dark }` pair — each side merged onto the matching built-in
   *   theme and picked by the current scheme.
   *
   * Keep the object stable (module constant or memoized): resolved themes are
   * cached per object.
   */
  theme?: PlocksThemeOverride | PlocksThemePair;

  /**
   * Nested providers: merge a partial `theme` onto the parent provider's theme
   * (default) rather than onto the built-in one.
   */
  inherit?: boolean;

  /**
   * Whether to inject CSS variables. The root provider writes them to `:root`;
   * a nested one only when given its own `cssVariablesSelector`.
   */
  withCSSVariables?: boolean;

  /**
   * Render `text` / `backgrounds` / `surfaces` as CSS `var()` references instead
   * of literal colors (web only, opt-in).
   *
   * Pair it with `createThemeColorVariablesCss` inlined in the document head:
   * statically rendered markup then answers to `prefers-color-scheme` on its
   * own, so a prerendered page is already in the reader's scheme at first paint
   * rather than after hydration. Off by default — the rewritten values are CSS
   * strings, so anything that hands a theme color to a non-CSS consumer (SVG
   * attributes, Animated interpolation) has to read `literalColors` instead.
   */
  colorsAsCssVariables?: boolean;

  /** CSS selector where variables should be applied */
  cssVariablesSelector?: string;

  /**
   * Color scheme mode:
   * - 'auto': automatically follows OS preference
   * - 'light': force light mode
   * - 'dark': force dark mode
   *
   * Default `'auto'` at the root; a nested provider follows its parent's scheme.
   */
  colorSchemeMode?: 'auto' | 'light' | 'dark';

  /** Root provider only. Whether to enable overlay system (menus, tooltips, etc.) */
  withOverlays?: boolean;

  /** Root provider only. Inject the global web CSS (keyboard focus ring, text-input reset). */
  withGlobalCSS?: boolean;

  /**
   * Root provider only. Mount a `SafeAreaProvider` so Dialog, the dropdown
   * sheets and AppShell keep clear of the notch and the home indicator. Skipped
   * when one is already above (Expo Router's, or your own), so you rarely need
   * to set this — pass `false` to leave the tree without one.
   */
  withSafeAreaProvider?: boolean;

  /**
   * Root provider only. Persist and switch the color-scheme mode; read and set
   * it with `useThemeMode()`.
   */
  themeModeConfig?: ThemeModeConfig;

  /** Root provider only. i18n: initial active locale */
  locale?: string;
  /** Root provider only. i18n: fallback locale */
  fallbackLocale?: string;
  /** Root provider only. i18n: resources map */
  i18nResources?: I18nResources;

  /** Direction context configuration (pass false to opt out at the root) */
  direction?: false | DirectionProviderConfig;
  /** Root provider only. Haptics context configuration (pass false to opt out) */
  haptics?: false | HapticsProviderConfig;

  /**
   * Reduced motion for every library animation:
   * - `'system'` (default at the root): follow the OS setting
   * - `true` / `false`: force it on / off (e.g. an in-app setting, screenshots)
   * Omitted in a nested provider: inherit the parent's setting.
   */
  reducedMotion?: ReducedMotionSetting;
}
```

## Theme object

`useTheme()` returns a `PlocksTheme` with these top-level groups:

- `primaryColor` — Primary color used for buttons, links, etc.
- `colorScheme` — Color scheme
- `designTokens` — Design tokens for consistent styling
- `colors` — Colors palette
- `text` — Semantic text colors
- `backgrounds` — Semantic background & surface colors
- `literalColors` — The literal colors behind `text`, `backgrounds` and `surfaces` when those have been rewritten to CSS `var()` references for the web — see `withCssVariableColors`.
- `surfaces` — Elevation ladder consumed by `Surface` (and, through it, Card, Menu, Popover, Dialog…).
- `textRoles` — Typography for titles and group labels (see `TextRoleName`), read through `resolveTextRole` and `Text`'s `textRole` prop.
- `states` — Semantic interactive state colors
- `fontFamily` — Font family
- `fontFamilyMono` — Monospace font family (code, kbd, tabular numbers).
- `controlSizes` — The control-size table used by Button, IconButton, Input and every other fixed-height control — read it through `getControlSize(theme, size)`.
- `zIndices` — Stacking layers for overlays and sticky chrome — read through `getZIndex(theme, layer)`.
- `fontSizes` — Font sizes - extended with new size system
- `spacing` — Spacing values - extended with new size system
- `radii` — Border radius values - extended with new size system
- `shadows` — Shadows
- `breakpoints` — Breakpoints for responsive design
- `motion` — Motion tokens for animations
- `components` — Component default props and styles (override point)
- `other` — Any additional custom theme properties (see `PlocksThemeOther`)

## Types

```ts
export interface PlocksThemePair {
  light?: PlocksThemeOverride;
  dark?: PlocksThemeOverride;
}

export interface ThemeModeConfig {
  /** Initial color scheme mode */
  initialMode?: ColorSchemeMode;
  /** Custom persistence functions (optional) */
  persistence?: {
    get: () => ColorSchemeMode | null;
    set: (mode: ColorSchemeMode) => void;
  };
  /** Custom DOM manipulation (web only, optional) */
  domConfig?: {
    selector: string;
    lightClass: string;
    darkClass: string;
    attribute: string;
  };
}

// Returned by useThemeMode()
interface ThemeModeContextValue {
  mode: ColorSchemeMode;
  setMode: (mode: ColorSchemeMode) => void;
  cycleMode: () => void;
  actualColorScheme: 'light' | 'dark'; // resolved value (no 'auto')
}

export function useTheme(): PlocksTheme;

export function useThemeMode(): ThemeModeContextValue;

export function createTheme(themeOverride: PlocksThemeOverride): PlocksThemeOverride;
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/guides/shared-props.md -->

# Shared props and tokens

Component pages list each component's own props, then name the shared groups it also accepts in one line — "Also accepts the shared props — field (…), spacing (…), …". The groups are defined here once.

## Style props

Every component takes the style props — spacing (`m`, `px`, …) and box props (`w`, `h`, `miw`, `maw`, `mih`, `mah`, `bg`, `opacity`) — plus the visibility props and `style` / `testID` (the base group). They apply to the component's root. Many also take `radius` and `shadow`. Values are theme tokens or numbers: `p="md"`, `mt={12}`, `w="full"`, `bg="subtle"`. Horizontal spacing (`ml`, `pl`, …) follows the leading and trailing edges, so it flips in right-to-left layouts. Each prop has only its short name — there is no `maxWidth` or `backgroundColor` spelling.

```tsx
import { Card, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Card p="lg" mt="md" radius="lg" shadow="sm" w="full" maw={480} bg="subtle">
      <Text fw={600} c="dimmed">Spacing, size, background, radius and shadow come from the shared style props.</Text>
    </Card>
  );
}
```

```ts
export interface SpacingProps {
  /** Margin on all sides */
  m?: SpacingValue;
  /** Margin top */
  mt?: SpacingValue;
  /** Margin on the trailing edge (right in LTR, left in RTL) */
  mr?: SpacingValue;
  /** Margin bottom */
  mb?: SpacingValue;
  /** Margin on the leading edge (left in LTR, right in RTL) */
  ml?: SpacingValue;
  /** Margin horizontal (both inline edges) */
  mx?: SpacingValue;
  /** Margin vertical (top and bottom) */
  my?: SpacingValue;

  /** Padding on all sides */
  p?: SpacingValue;
  /** Padding top */
  pt?: SpacingValue;
  /** Padding on the trailing edge (right in LTR, left in RTL) */
  pr?: SpacingValue;
  /** Padding bottom */
  pb?: SpacingValue;
  /** Padding on the leading edge (left in LTR, right in RTL) */
  pl?: SpacingValue;
  /** Padding horizontal (both inline edges) */
  px?: SpacingValue;
  /** Padding vertical (top and bottom) */
  py?: SpacingValue;
}

export interface BoxProps {
  /** Width */
  w?: DimensionProp;
  /** Height */
  h?: DimensionProp;
  /** Minimum width */
  miw?: DimensionProp;
  /** Maximum width */
  maw?: DimensionProp;
  /** Minimum height */
  mih?: DimensionProp;
  /** Maximum height */
  mah?: DimensionProp;
  /**
   * Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`,
   * `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade
   * syntax, or any CSS color.
   */
  bg?: ThemeColor;
  /** Opacity, `0`–`1` */
  opacity?: number;
}

export interface BorderRadiusProps {
  /** Border radius value - supports size tokens, numbers, and special values */
  radius?: RadiusValue;
}

export interface ShadowProps {
  /** Shadow value - supports size tokens and 'none' */
  shadow?: ShadowValue;
}

export interface VisibilityProps {
  /** Do not render in the light color scheme. */
  lightHidden?: boolean;
  /** Do not render in the dark color scheme. */
  darkHidden?: boolean;
  /** Do not render when the viewport is at least this breakpoint wide (`width >= theme.breakpoints[bp]`). */
  hiddenFrom?: BreakpointToken;
  /** Render only when the viewport is at least this breakpoint wide. */
  visibleFrom?: BreakpointToken;
}

export type BaseProps<S = ViewStyle> = StyleProps &
  VisibilityProps & {
    /** Style for the root element — merged last, after the component's own styles. */
    style?: StyleProp<S>;
    /** Test identifier for the root element. */
    testID?: string;
  };
```

`DimensionProp` is a number (dp / px), a percentage such as `'50%'`, `'auto'`, `'full'` (100%), or on web any CSS length.

## Field props

Form inputs — `Input`, `Select`, `Checkbox`, `Radio`, `Switch`, the pickers and the rest — share one field frame: label, description, error and helper text wired to the control for assistive technology. Text inputs add the text-field group (`value`, `onChangeText`, `placeholder`, `clearable`, sections). Inside a `Form.Field`, value, change handler and error are injected for you.

```ts
export interface FieldBaseProps<S = ViewStyle> extends BaseProps<S>, LayoutProps, DisclaimerSupport {
  /** Label rendered above (or beside) the control. */
  label?: React.ReactNode;
  /** Short description rendered under the label. */
  description?: React.ReactNode;
  /** Error message. Marks the field invalid and is announced to assistive technology. */
  error?: React.ReactNode;
  /** Helper text rendered under the control when there is no error. */
  helperText?: React.ReactNode;
  /** Marks the field required (announced; shows an asterisk unless `withAsterisk` is false). */
  required?: boolean;
  /** Show the required asterisk. Defaults to `required`. */
  withAsterisk?: boolean;
  disabled?: boolean;
  readOnly?: boolean;
  size?: SizeValue;
  radius?: RadiusValue;
  variant?: FieldVariant;
  /** Field name for form integration. */
  name?: string;
  /** Overrides the accessible name composed from `label`. */
  accessibilityLabel?: string;
  accessibilityHint?: string;
  /** Identifier used with KeyboardManagerProvider to request refocus. */
  keyboardFocusId?: string;
  /** Props applied to the label `<Text>`. */
  labelProps?: Omit<TextProps, 'children'>;
  /** Props applied to the description `<Text>`. */
  descriptionProps?: Omit<TextProps, 'children'>;
  onFocus?: () => void;
  onBlur?: () => void;
}

export interface TextFieldBaseProps<S = ViewStyle> extends FieldBaseProps<S> {
  value?: string;
  defaultValue?: string;
  onChangeText?: (text: string) => void;
  placeholder?: string;
  /** Falls back to `theme.text.muted`. */
  placeholderTextColor?: string;
  /** Show a clear button while the field has a value. */
  clearable?: boolean;
  clearButtonLabel?: string;
  onClear?: () => void;
  /** Debounce delay for validation, in milliseconds. */
  debounceMs?: number;
  /** Called when Enter is pressed. */
  onEnter?: () => void;
  startSection?: React.ReactNode;
  endSection?: React.ReactNode;
  startSectionProps?: Omit<ViewProps, 'children'>;
  endSectionProps?: Omit<ViewProps, 'children'>;
}

export interface DisclaimerSupport {
  disclaimer?: React.ReactNode;
  disclaimerProps?: Omit<DisclaimerProps, 'children'>;
}
```

## Chart props

Every chart in `@plocks/charts` accepts the chart group (size, title, legend, tooltip, animation and accessibility options) and the chart event callbacks, on top of its own data props.

```ts
export interface BaseChartProps extends SpacingProps {
  /**
   * Chart width in px. Omit it and the chart fills the box it is placed in,
   * redrawing when that box changes. A number is honoured up to the width the
   * container can actually give it — a chart never draws wider than its slot.
   */
  w?: number;
  /** Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. */
  h?: number;
  /**
   * Height as a fraction of the resolved width (`width / height`), used when
   * `height` is omitted. `2` keeps the chart twice as wide as it is tall at
   * every container size.
   */
  aspectRatio?: number;
  /** Upper bound on the resolved width. Useful for radial charts in wide columns. */
  maw?: number;
  /** Lower bound on the resolved width. */
  miw?: number;
  /** Upper bound on a height derived from `aspectRatio`. */
  mah?: number;
  /** Lower bound on a height derived from `aspectRatio`. */
  mih?: number;
  /** Chart test ID for testing */
  testID?: string;
  /** Additional styles */
  style?: any;
  /** Accessibility label surfaced to assistive tech */
  accessibilityLabel?: string;
  /** Accessibility hint describing chart interaction */
  accessibilityHint?: string;
  /** Accessibility role override */
  accessibilityRole?: string;
  /** Whether the chart container is accessible */
  accessible?: boolean;
  /** Platform specific accessibility importance */
  importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants';
  /** Animation duration in ms */
  animationDuration?: number;
  /** Animation easing function */
  animationEasing?: string;
  /** Whether chart is disabled */
  disabled?: boolean;
  /** Chart title */
  title?: string;
  /** Chart subtitle */
  subtitle?: string;
  /** If false, chart expects a parent interaction provider (shared context). */
  useOwnInteractionProvider?: boolean;
  /** Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). */
  suppressPopover?: boolean;
}

export interface ChartInteractionCallbacks<TData = ChartDataPoint> {
  /** Called when chart is tapped/clicked */
  onPress?: (event: ChartInteractionEvent<TData>) => void;
  /** Called when data point is selected */
  onDataPointPress?: (dataPoint: TData, event: ChartInteractionEvent<TData>) => void;
}
```

The option types those props take — a chart's own data types are on its page:

```ts
export interface ChartDataPoint {
  /** Unique identifier for the data point */
  id?: string | number;
  /** X-axis value */
  x: number;
  /** Y-axis value */
  y: number;
  /** Optional label */
  label?: string;
  /** Optional color override */
  color?: string;
  /** Optional size override */
  size?: number;
  /** Custom data for interactions */
  data?: any;
}

export interface ChartAxis {
  /** Show axis line */
  show?: boolean;
  /** Axis color */
  color?: string;
  /** Axis thickness */
  thickness?: number;
  /** Show tick marks */
  showTicks?: boolean;
  /** Tick positions (auto-calculated if not provided) */
  ticks?: number[];
  /** Tick color */
  tickColor?: string;
  /** Tick length */
  tickLength?: number;
  /** Show labels */
  showLabels?: boolean;
  /** Label formatter */
  labelFormatter?: (value: number) => string;
  /** Label color */
  labelColor?: string;
  /** Label font size */
  labelFontSize?: number;
  /** Axis title */
  title?: string;
  /** Title color */
  titleColor?: string;
  /** Title font size */
  titleFontSize?: number;
}

export interface ChartGrid {
  /** Show grid */
  show?: boolean;
  /** Grid color */
  color?: string;
  /** Grid line thickness */
  thickness?: number;
  /** Grid line style */
  style?: 'solid' | 'dashed' | 'dotted';
  /** Show major grid lines */
  showMajor?: boolean;
  /** Show minor grid lines */
  showMinor?: boolean;
  /** Major grid positions */
  majorLines?: number[];
  /** Minor grid positions */
  minorLines?: number[];
}

export interface ChartLegend {
  /** Show legend */
  show?: boolean;
  /** Legend position */
  position?: 'top' | 'bottom' | 'left' | 'right';
  /** Legend alignment */
  align?: 'start' | 'center' | 'end';
  /** Legend items (auto-generated if not provided) */
  items?: ChartLegendItem[];
  /** Legend item color */
  textColor?: string;
  /** Legend item font size */
  fontSize?: number;
}

export interface ChartTooltip<TData = ChartDataPoint> {
  /** Show tooltip on hover/press */
  show?: boolean;
  /** Tooltip formatter */
  formatter?: (dataPoint: TData) => string | React.ReactNode;
  /** Tooltip background color */
  backgroundColor?: string;
  /** Tooltip text color */
  textColor?: string;
  /** Tooltip font size */
  fontSize?: number;
  /** Tooltip border radius */
  borderRadius?: number;
  /** Tooltip padding */
  padding?: number;
}

export interface ChartAnimation {
  /** Animation duration */
  duration?: number;
  /** Animation delay */
  delay?: number;
  /** Animation easing */
  easing?: string;
  /** Animation type */
  type?: 'fade' | 'scale' | 'slide' | 'draw' | 'drawOn' | 'spiral' | 'bounce' | 'elastic' | 'wave';
  /** Stagger animation for multiple elements */
  stagger?: number;
}

export interface ChartAnnotation {
  /** Unique identifier for the annotation */
  id: string | number;
  /** Visual shape used to render the annotation */
  shape: ChartAnnotationShape;
  /** X coordinate for point or vertical-line annotations */
  x?: number;
  /** Y coordinate for point or horizontal-line annotations */
  y?: number;
  /** Starting x coordinate for range or box annotations */
  x1?: number;
  /** Ending x coordinate for range or box annotations */
  x2?: number;
  /** Starting y coordinate for range or box annotations */
  y1?: number;
  /** Ending y coordinate for range or box annotations */
  y2?: number;
  /** Label displayed near the annotation */
  label?: string;
  /** Stroke or outline color used for the annotation */
  color?: string;
  /** Fill color used for the annotation */
  backgroundColor?: string;
  /** Overall opacity of the annotation */
  opacity?: number;
  /** Stroke width for line-based annotations */
  lineWidth?: number;
  /** Dashed stroke pattern for the annotation */
  dashArray?: number[];
  /** Font size for any annotation text */
  fontSize?: number;
  /** Text color for the annotation label */
  textColor?: string;
  /** Arbitrary additional data associated with the annotation */
  data?: any;
}

export type ChartFill = string | ChartGradient;
```

## Token types

```ts
/** Size tokens, smallest to largest (also exported as `ComponentSize`). */
export type SizeToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl';

/** `SizeValue` is the same type. A number is read in px. */
export type ComponentSizeValue = SizeToken | number;

export type SpacingValue = SizeToken | 'auto' | '0' | number;

export type DimensionProp = number | 'auto' | 'full' | `${number}%` | (string & {});

export type RadiusValue = SizeToken | 'none' | 'full' | number;

export type ShadowValue =
  | SizeValue
  | 'none';

export type ThemeColorToken =
  | 'primary'
  | 'secondary'
  | 'tertiary'
  | 'success'
  | 'warning'
  | 'error'
  | 'gray';

export type ThemeColor = ThemeColorToken | (string & {});

export type BreakpointToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/guides/icons.md -->

# Icons

`@plocks/ui@0.2.0` registers 216 icons by default,
using bundled Tabler-derived glyphs. These are the only strings `name`
accepts out of the box — anything else renders nothing, so **do not guess an
icon name**; pick one from this list or pass a component instead.

```tsx
import { Icon, IconButton } from '@plocks/ui';

<Icon name="check" size="sm" />
<IconButton icon="trash" onPress={remove} accessibilityLabel="Delete" />

// Not in the registry? Pass any icon component or element instead:
import { IconRocket } from '@tabler/icons-react-native';
<IconButton icon={IconRocket} onPress={launch} accessibilityLabel="Launch" />
```

There is no public API for registering additional names —
`registerIcon` / `registerIcons` exist in the source but are not exported
from the package root or from `@plocks/ui/Icon`. Pass a component
for anything outside this list.

## Names

accordion, alert-circle, alignCenter, alignJustify, alignLeft, alignRight, arrow-down, arrow-left, arrow-right, arrow-up, arrowDown, arrowLeft, arrowRight, arrowUp, autocomplete, avatar, badge, bar-chart, bell, block, bluetooth, bold, bolt, bone, bookmark, breadcrumbs, button, calendar, camera, card, carousel, cart, chart-area, chart-bar, chart-donut, chart-heatmap, chart-line, chart-pie, chart-scatter, chart-sparkline, chat, check, chevron-down, chevron-left, chevron-right, chevron-up, chevronDown, chevronLeft, chevronRight, chevrons-up-down, chevronUp, chip, circle, clock, close, code, cog, color, colors, compress, container, contrast, copy, database, datatable, delete, dialog, divider, dots, download, edit, ellipsis, ellipsis-h, email, emoji, error, exclamation, expand, external-link, eye, eyeOff, file, filter, flag, flex, folder, font, form, funnel, gallery, globe, grid, guitar, heading, headphones, heart, highlight, home, hook, image, image-off, indicator, info, input, italic, keyboard, keycap, knob, knobs, layer-mask, layers, line-chart, linechart, link, list, listOrdered, listUnordered, loader, loading, location, lock, mail, map, markdown, masonry, menu, message, message-circle, mic, microphone, minus, moon, music, number, package, paddingFrame, pagination, palette, paper, pause, person, phone, piano, pin, plan, play, plus, popover, progress, progress-shield, qrcode, question, quote, radio, rating, record, redo, refresh, repeat, richtext, rocket, rotate, save, search, select, selector-vertical, selectorVertical, settings, share, sheild, shop, slider, smile, sort, sparkles, speedometer, splitTrack, spoiler, spotlight, star, stepper, stop, strikethrough, success, sun, support, switch, table, tableofcontents, tabs, target, text, textarea, timeline, times, title, toast, toggle, toggleOff, toggleOn, tooltip, trash, tree, tuning, underline, undo, upload, user, volume-off, volume-up, volumeOff, warning, waveform, web, wifi, x

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/guides/accessibility.md -->

# Accessibility at plocks

Inclusive design is a baseline requirement across the plocks library and documentation site. This page gathers the guardrails, utilities, and testing practices that help us meet WCAG 2.1 AA expectations for keyboard, screen reader, low-vision, and motion-sensitive users.

Docs: https://plocks.dev/accessibility

## Keyboard & Focus Management

plocks is fully operable without a mouse. Focus order mirrors visual layout and shortcuts are discoverable and customizable.

- Every interactive component participates in a predictable tab order and preserves visible focus outlines across light and dark themes.
- Dialogs, Spotlights, Dropdowns, and Menus trap focus while open and restore it to the triggering control when they close.
- Scoped and global keyboard shortcuts are defined with `useHotkeys` / `useGlobalHotkeys`, with optional `aria-live` announcements for critical actions.

## Assistive Technology Semantics

Components expose reliable roles, names, and states so VoiceOver, TalkBack, NVDA, and other assistive tools can correctly interpret the UI.

- Buttons, links, inputs, and composite widgets expose consistent `accessibilityRole`, `accessibilityLabel`, and `aria-*` attributes on web and native platforms.
- Spotlight and navigation lists announce active options while you move with the arrow keys or screen-reader rotor.
- Semantic heading structure is enforced through typography variants and `useTitleRegistration`, ensuring the documentation table of contents mirrors the DOM outline.

## Visual Accessibility

Color, typography, and spacing tokens are engineered for clarity, even under high contrast, zoom, or theme overrides.

- The design tokens maintain WCAG AA contrast ratios (4.5:1 or higher) for body text and interactive states in both color schemes.
- Highlight backgrounds adapt automatically to surrounding foreground colors, so inline emphasis remains legible on both dark and light surfaces.
- Component spacing, typography scales, and layout primitives support dynamic type and zoom without breaking line wraps or truncating controls.

## Motion, Audio, & Sensory Preferences

Micro-interactions respect user comfort and can be tuned or disabled globally.

- Animations, shimmer effects, and transitions read the system `prefers-reduced-motion` flag using `usePrefersReducedMotion`, gracefully disabling non-essential motion.
- Tactile interactions use the `useHaptics` hook and can be toggled off centrally for users who prefer silent interactions.
- Auditory cues route through the `SoundProvider`, allowing global enable/disable controls and volume adjustments.

## Design & QA Workflow

Accessibility is woven into the release checklist with dedicated reviews and automated tooling.

- WCAG 2.1 AA alignment drives our component acceptance criteria and manual review checklists.
- ARIA Authoring Practices are referenced for complex widgets such as accordions, tabs, and tree views.
- Testing flows incorporate keyboard-only walkthroughs, VoiceOver / TalkBack smoke tests, and contrast analysis with tooling like Axe and Lighthouse.

## Applying Accessible APIs

Components forward platform accessibility props, letting you layer contextual hints or ARIA attributes without losing built-in behaviour.

```tsx
import { Button, useSpotlightToggle } from '@plocks/ui';

export function AccessibleSearchTrigger() {
  const { open } = useSpotlightToggle();

  return (
    <Button
      onPress={open}
      icon="spotlight"
      accessibilityLabel="Open command palette"
      accessibilityHint="Press to search components, pages, and actions"
    >
      Command Palette
    </Button>
  );
}
```

Have an accessibility request or need help auditing a flow? Open an issue on GitHub or ask in Discord so we can collaborate on an inclusive solution.

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/guides/localization.md -->

# Localization

plocks ships a lightweight i18n layer. Provide locale resource objects, wrap your app with I18nProvider, then translate via the tx prop or the useI18n hook.

Docs: https://plocks.dev/localization

## Create resource files

Create JSON resource files per locale.

`resources.ts`

```tsx
import en from './locales/en/common.json';
import fr from './locales/fr/common.json';
import es from './locales/es/common.json';

export const resources = {
  en: { translation: en },
  fr: { translation: fr },
  es: { translation: es }
};
```

## Wrap the app in I18nProvider

Wrap your app in the I18nProvider component.

`App.tsx`

```tsx
import { I18nProvider } from '@plocks/ui';
import { resources } from './resources';

export function App() {
  return (
    <I18nProvider initial={{ resources, locale: 'en', fallbackLocale: 'en' }}>
      <Root />
    </I18nProvider>
  );
}
```

## Translate and switch locales

Switch locales by calling setLocale('fr') etc. Components re-render automatically.

`Greeting.tsx`

```tsx
import { Alert, Text, ToggleButton, ToggleGroup, useI18n } from '@plocks/ui';

const LOCALES = ['en', 'fr', 'es'];

function Greeting() {
  const { t, setLocale, locale } = useI18n();
  return (
    <>
      <ToggleGroup
        value={locale}
        exclusive
        required
        onChange={(next) => { if (typeof next === 'string') setLocale(next); }}
      >
        {LOCALES.map((l) => (
          <ToggleButton key={l} value={l}>{l.toUpperCase()}</ToggleButton>
        ))}
      </ToggleGroup>
      <Alert icon='globe'>
        <Text tx='localization.helloWorld' />
      </Alert>
      <Text tx='localization.exampleGreeting' txParams={{ name: 'Ada' }} />
      <Text>{t('localization.current', { locale })}</Text>
    </>
  );
}
```

## Notes

- Use <Text tx="localization.exampleGreeting" txParams={{ name: 'Ada' }} /> to render translated copy.
- Or call const { t, setLocale, locale } = useI18n(); then t('localization.exampleGreeting', { name: 'Ada' }).
- Use formatDate / formatNumber / formatRelativeTime helpers for localized formatting.
- Missing keys fall back to fallbackLocale then return the key name (configurable via onMissingKey).

--------------------------------------------------------------------------------

# COMPONENTS

<!-- source: https://plocks.dev/llms/components/Accordion.md -->

# Accordion

The Accordion component groups related content into expandable sections.

## Metadata

- Import: `import { Accordion } from '@plocks/ui';`
- Tags: collapse, expand, panel, ui, content-grouping
- Docs: https://plocks.dev/components/Accordion
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Accordion

## Props

- `items` (required): AccordionItem[] — Ordered list of items to render. The `key` for each item must be unique.
- `type`: 'single' | 'multiple' = 'single' — Expansion behavior. 'single' ensures only one item can be expanded at a time; 'multiple' allows independent expansion.
- `defaultExpanded`: string[] = [] — Initial expanded item keys (uncontrolled). Ignored when `expanded` is provided. For `type="single"` only the first key is used at initialization.
- `expanded`: string[] — Controlled set of expanded item keys. Provide alongside `onExpandedChange`.
- `onExpandedChange`: (expanded: string[]) => void — Called when the expanded keys change (both controlled & uncontrolled flows).
- `onItemToggle`: OnAccordionToggle — Per-item toggle event with rich metadata. Fires after state resolution.
- `variant`: 'default' | 'separated' | 'bordered' = 'default' — Visual variant style preset.
- `size`: SizeValue = 'md' — Size scale controlling paddings, font sizes, and icon dimensions.
- `color`: ThemeColor = undefined — Brand accent applied to the expanded item (title, chevron, and a subtle surface tint). Opt-in — when unset, the open state stays neutral and reads from the bolded title and rotated chevron alone.
- `showChevron`: boolean = true — Whether to render the chevron affordance.
- `chevronPosition`: 'start' | 'end' = 'end' — Chevron placement relative to the header text.
- `density`: 'comfortable' | 'compact' | 'spacious' = 'comfortable' — Space efficiency / vertical density preset.
- `radius`: RadiusValue — Corner radius of the `separated` items / `bordered` frame: a radius token, px number, `'none'` or `'full'`.
- `headerStyle`: StyleProp<ViewStyle> — Header row style override applied to each item.
- `contentStyle`: StyleProp<ViewStyle> — Collapsible content container style override.
- `headerTextStyle`: StyleProp<TextStyle> — Text style applied to the header label.
- `titleProps`: Omit<TextProps, 'children'> — Override props applied to each item's header `<Text>` (style, fw, ff, size, c). Applies to every item in the accordion.
- `persistKey`: string — Explicit persistence key. If omitted, an automatic hash key will be generated when uncontrolled.
- `autoPersist`: boolean = true — Enables persistence of expanded state (uncontrolled only) across remounts in-process.
- `animated`: AccordionAnimationProp = true — Enables animation or accepts a config object for custom durations & easing.
- `transitionDuration`: number = 220 — Length of the expand/collapse transition (chevron spin + panel height) in ms. Takes precedence over `animated`; `0` renders state changes instantly. Always 0 when the user prefers reduced motion.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface AccordionItem {
  /**
   * Unique identifier for the item. Must be stable across renders.
   */
  key: string;
  /**
   * Header label rendered in the item trigger row.
   */
  title: string;
  /**
   * Collapsible body content shown when the item is expanded.
   */
  content: ReactNode;
  /**
   * Disables user interaction and visually indicates the item is inactive.
   */
  disabled?: boolean;
  /**
   * Optional decorative or status icon rendered alongside the title.
   */
  icon?: ReactNode;
  /**
   * Overrides the accordion-level `color` for this item's expanded emphasis
   * (title, chevron, and surface tint). Lets a single accordion mix accents.
   */
  color?: ThemeColor;
}

export type OnAccordionToggle = (detail: AccordionToggleDetail) => void;

export type AccordionAnimationProp = boolean | { duration?: number; easing?: (t: number) => number };

export interface AccordionToggleDetail {
  itemKey: string;
  expanded: boolean;
  expandedKeys: string[];
  type: AccordionType;
  variant: AccordionVariant | undefined;
}
```

## Examples

### Basics

Allow only one item to open at a time by setting `type="single"` and passing an items array.

```tsx
import { Accordion } from '@plocks/ui';
import { faqItems } from '../data';

export function Demo() {
  return <Accordion type="single" items={faqItems} />;
}
```

`data.ts`

```ts
import React from 'react';
import { Text } from '@plocks/ui';
import type { AccordionItemType } from '@plocks/ui';

// Wrap body copy in <Text> without JSX so this stays a plain `.ts` data module
// (a `.tsx` sibling would be picked up as its own demo by the docs generator).
const body = (text: string) => React.createElement(Text, { size: 'sm' }, text);

export const faqItems: AccordionItemType[] = [
  {
    key: 'foundation',
    title: 'What is plocks?',
    content: body('A cross-platform design system for shipping polished React Native apps faster.'),
  },
  {
    key: 'benefits',
    title: 'Why use an accordion?',
    content: body('Keep dense guidance scannable while letting readers expand only what they need.'),
  },
  {
    key: 'next-steps',
    title: 'How do I get started?',
    content: body('Install the package, drop the provider at the root, and follow the onboarding checklist.'),
  },
];

export const knowledgeBase: AccordionItemType[] = [
  {
    key: 'collaboration',
    title: 'Invite collaborators',
    content: body('Share the project with teammates to co-author docs and keep decisions centralized.'),
  },
  {
    key: 'appearance',
    title: 'Customize the theme',
    content: body('Extend the default theme tokens with your brand colors and typography.'),
  },
  {
    key: 'automation',
    title: 'Automate release notes',
    content: body('Connect the changelog generator to auto-publish updates on every tag.'),
  },
];

export const onboardingSteps: AccordionItemType[] = [
  {
    key: 'create-project',
    title: 'Create a project',
    content: body('Spin up a workspace and invite your teammates.'),
  },
  {
    key: 'import-assets',
    title: 'Import assets',
    content: body('Upload icons, typography, and spacing tokens.'),
  },
];

export const statusItems: AccordionItemType[] = [
  {
    key: 'info',
    title: 'Informational',
    color: 'primary',
    content: body('Set `color` per item to accent its expanded panel.'),
  },
  {
    key: 'healthy',
    title: 'All systems healthy',
    color: 'success',
    content: body('The title and chevron pick up the color while open.'),
  },
  {
    key: 'review',
    title: 'Needs review',
    color: 'warning',
    content: body('Collapsed items stay neutral.'),
  },
  {
    key: 'failed',
    title: 'Build failed',
    color: 'error',
    content: body('Use error to emphasize failures.'),
  },
];

export const setupSteps: AccordionItemType[] = [
  {
    key: 'install',
    title: 'Install the package',
    content: body('Run `npm install @plocks/ui` in your workspace.'),
  },
  {
    key: 'provider',
    title: 'Wrap your app in providers',
    content: body('Add ThemeProvider, ToastProvider, and DialogProvider at the root.'),
  },
  {
    key: 'compose',
    title: 'Compose your first screen',
    content: body('Drop in fields, buttons, and feedback components from the library.'),
  },
];
```

### Multiple Expansion

Control the `expanded` keys to keep several accordion items open at the same time.

```tsx
import { useState } from 'react';
import { Accordion } from '@plocks/ui';
import { knowledgeBase } from '../data';

export function Demo() {
  const [expandedKeys, setExpandedKeys] = useState<string[]>(['collaboration']);

  return (
    <Accordion
      type="multiple"
      expanded={expandedKeys}
      onExpandedChange={setExpandedKeys}
      items={knowledgeBase}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Visual Variants

Switch between `default`, `separated`, and `bordered` variants to adjust emphasis.

```tsx
import { Accordion, Block, Text } from '@plocks/ui';
import { onboardingSteps } from '../data';

const variants = ['default', 'separated', 'bordered'] as const;

export function Demo() {
  return (
    <Block>
      {variants.map((variant) => (
        <Block key={variant}>
          <Text size="xs" fw="600" c="muted" tt="uppercase" lts={1}>
            {variant}
          </Text>
          <Accordion type="single" variant={variant} items={onboardingSteps} />
        </Block>
      ))}
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Accent Colors

Accent each expanded panel with a theme palette — `primary`, `secondary`, `tertiary`, `success`, `warning`, `error`, or `gray`. Set `color` on the accordion for a uniform accent, or per item to mix accents in a single accordion. Collapsed items stay neutral so only the open panel is highlighted.

```tsx
import { Accordion } from '@plocks/ui';
import { statusItems } from '../data';

export function Demo() {
  return (
    <Accordion
      type="multiple"
      variant="separated"
      defaultExpanded={['healthy']}
      items={statusItems}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Title customization

`titleProps` accepts any `<Text>` props (`ff`, `fw`, `lts`, `tt`, `size`, `c`, `style`) and applies them to every item header in the accordion. The existing `headerTextStyle` escape hatch still works and can be combined.

```tsx
import { Accordion } from '@plocks/ui';
import { setupSteps } from '../data';

export function Demo() {
  return (
    <Accordion
      items={setupSteps}
      titleProps={{ tt: 'uppercase', lts: 1, fw: '700', size: 'sm' }}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ActionBar.md -->

# ActionBar

Use ActionBar for actions that apply to selected content. It stays pinned while the page scrolls.

## Metadata

- Import: `import { ActionBar } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/ActionBar
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ActionBar

## Props

- `children`: React.ReactNode — Actions rendered in the bar.
- `opened` (required): boolean — Controls visibility.
- `onClose`: () => void — Called by the close button or Escape when enabled.
- `closeOnEscape`: boolean = false — Let Escape dismiss this bar once layers above it close. @default false
- `keepMounted`: boolean = false — Preserve the hidden bar in the tree. @default false
- `withinPortal`: boolean = true — Render at the application root. @default true
- `position`: { top?: number; bottom?: number; start?: number; end?: number } = { bottom: 24 } — Logical viewport insets. @default { bottom: 24 }
- `radius`: RadiusValue = 'md' — Corner radius. @default 'md'
- `shadow`: ShadowToken = 'md' — Surface shadow. @default 'md'
- `withBorder`: boolean = true — Draw a border. @default true
- `zIndex`: number — Stack order.
- `transition`: 'pop' | 'slide-up' | 'fade' = 'pop' — Entrance effect. @default 'pop'
- `transitionDuration`: number = 200 — Animation duration in ms. @default 200
- `aria-label`: string = 'Actions' — Accessible group label. @default 'Actions'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ActionBarDivider, ActionBarCloseButton } from '@plocks/ui';`

### ActionBarDivider

- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ActionBarCloseButton

- `accessibilityLabel`: string
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ActionBar.CloseButton

- `accessibilityLabel`: string
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ActionBar.Divider

- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Open the bar when selection is active; CloseButton calls `onClose`.

```tsx
import { useState } from 'react';
import { ActionBar, Block, Button, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Block fullWidth>
      <Button onPress={() => setOpened(true)}>Select items</Button>
      <ActionBar opened={opened} onClose={() => setOpened(false)}>
        <Text>3 selected</Text>
        <ActionBar.Divider />
        <Button size="sm">Delete</Button>
        <ActionBar.CloseButton />
      </ActionBar>
    </Block>
  );
}
```

### Placement and Escape

Use logical viewport insets to place the bar and `closeOnEscape` to dismiss it with Escape.

```tsx
import { useState } from 'react';
import { ActionBar, Block, Button, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Block fullWidth>
      <Button onPress={() => setOpened(true)}>Show top bar</Button>
      <ActionBar
        opened={opened}
        onClose={() => setOpened(false)}
        position={{ top: 24, end: 24 }}
        transition="slide-up"
        closeOnEscape
      >
        <Text>Top end</Text>
        <ActionBar.CloseButton />
      </ActionBar>
    </Block>
  );
}
```

### Icon Buttons

IconButton actions can be grouped with dividers and tooltips.

```tsx
import { useState } from 'react';
import { ActionBar, Block, Button, IconButton, Tooltip } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Block fullWidth>
      <Button onPress={() => setOpened(true)}>Show actions</Button>
      <ActionBar opened={opened} onClose={() => setOpened(false)}>
        <Tooltip label="Archive">
          <IconButton icon="archive" accessibilityLabel="Archive" variant="ghost" />
        </Tooltip>
        <ActionBar.Divider />
        <Tooltip label="Delete">
          <IconButton icon="trash" accessibilityLabel="Delete" variant="ghost" />
        </Tooltip>
        <ActionBar.CloseButton />
      </ActionBar>
    </Block>
  );
}
```

### Transitions

`transition` changes how the bar enters and leaves.

```tsx
import { useState } from 'react';
import { ActionBar, Block, Button, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Block fullWidth>
      <Button onPress={() => setOpened(true)}>Show slide transition</Button>
      <ActionBar
        opened={opened}
        onClose={() => setOpened(false)}
        transition="slide-up"
        transitionDuration={300}
      >
        <Text>Sliding actions</Text>
        <ActionBar.CloseButton />
      </ActionBar>
    </Block>
  );
}
```

### Keep Mounted

`keepMounted` preserves child state while the bar is hidden.

```tsx
import { useState } from 'react';
import { ActionBar, Block, Button, Checkbox } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <Block fullWidth>
      <Button onPress={() => setOpened((value) => !value)}>Toggle bar</Button>
      <ActionBar opened={opened} onClose={() => setOpened(false)} keepMounted>
        <Checkbox label="Keep this choice" />
      </ActionBar>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Alert.md -->

# Alert

Alert displays prominent messages with severity styles and optional actions.

## Metadata

- Import: `import { Alert } from '@plocks/ui';`
- Tags: alert, notice, notification, message, status, feedback, callout
- Docs: https://plocks.dev/components/Alert
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Alert

## Props

- `variant`: 'light' | 'filled' | 'outline' | 'subtle' = 'light'
- `color`: ThemeColor = 'primary' — Accent color. Without a `severity`, `error` / `warning` colors also make the alert urgent (`role="alert"`); every other color is a polite `role="status"`.
- `severity`: 'info' | 'success' | 'warning' | 'error' — Severity helper — sets the color, the default icon, and the live-region urgency: `error` / `warning` render `role="alert"` (and are announced on mount on native), `info` / `success` render `role="status"`. Prefer it over `color` when the alert carries a status.
- `title`: string
- `children`: React.ReactNode
- `icon`: React.ReactNode | string | null | false
- `fullWidth`: boolean = false
- `withCloseButton`: boolean = false
- `closeButtonLabel`: string = 'Close' — Accessible name of the close button. @default 'Close'
- `onClose`: () => void
- `radius`: RadiusValue = 'md' — Corner radius: theme radius token, px, `'none'` or `'full'`. @default 'md'
- `titleProps`: Omit<TextProps, 'children'> — Override props applied to the title `<Text>` (style, fw, ff, size, c).
- `bodyProps`: Omit<TextProps, 'children'> — Override props applied to the body `<Text>` (the `children` content).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Use `severity` to set it — it picks the matching color and icon automatically.

```tsx
import { Alert, Block } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Alert severity="info" title="Heads up">
        Use alerts to highlight contextual information inline with page content.
      </Alert>
      <Alert severity="success" title="Profile saved">
        Your changes were stored successfully.
      </Alert>
      <Alert severity="error" title="Connection issue">
        Retry the action or check the status page for outages.
      </Alert>
    </Block>
  );
}
```

### Variants

Compare light, outline, filled, and subtle variants to match alert prominence to the message.

```tsx
import { Alert, Block } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Alert variant="light" color="primary" title="Light">
        Balanced background and border treatment for inline notes.
      </Alert>
      <Alert variant="outline" color="success" title="Outline">
        Subtle emphasis without increasing background contrast.
      </Alert>
      <Alert variant="filled" color="warning" title="Filled">
        High-contrast option for urgent messaging.
      </Alert>
      <Alert variant="subtle" color="error" title="Subtle">
        No background color, but tinted icon and text.
      </Alert>
    </Block>
  );
}
```

### Dismissible

Add `withCloseButton` and handle `onClose` to let users dismiss an alert.

```tsx
import { useState } from 'react';
import { Alert, Button } from '@plocks/ui';

export function Demo() {
  const [visible, setVisible] = useState(true);

  if (!visible) {
    return (
      <Button variant="outline" onPress={() => setVisible(true)}>
        Show alert
      </Button>
    );
  }

  return (
    <Alert
      severity="warning"
      title="Draft warning"
      withCloseButton
      onClose={() => setVisible(false)}
    >
      Your draft is missing a title. Resolve before publishing.
    </Alert>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/AppShell.md -->

# AppShell

AppShell arranges an app’s header, navigation, aside, footer, and mobile navigation in a responsive frame.

## Metadata

- Import: `import { AppShell } from '@plocks/ui';`
- Docs: https://plocks.dev/components/AppShell
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/AppShell

## Props

- `layout`: 'default' | 'alt' = 'default' — `'default'`: the header spans the full width and the navbar/aside sit below it. `'alt'`: the navbar and aside span the full height and the header sits between them. @default 'default'
- `header`: HeaderConfig
- `navbar`: NavbarConfig
- `aside`: AsideConfig
- `footer`: FooterConfig
- `bottomNav`: BottomNavConfig
- `showHeader`: boolean = true
- `layoutSections`: LayoutVisibilityConfig — Toggle rendering of individual autoLayout sections
- `autoLayout`: boolean — Enable AppShell auto-composition. When true, AppShell will render its own Header/Navbar/Main/Footer/BottomBar using the provided content props instead of relying on children.
- `headerContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Header when autoLayout is enabled
- `navbarContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Navbar when autoLayout is enabled
- `asideContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Aside when autoLayout is enabled
- `footerContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Footer when autoLayout is enabled
- `bottomNavItems`: BottomAppBarItem[] — Items for a mobile bottom navigation bar when autoLayout is enabled
- `bottomNavProps`: Partial<BottomAppBarProps> — Additional props forwarded to BottomAppBar in autoLayout mode (items overridden by bottomNavItems)
- `mobileMenu`: MobileMenuConfig
- `cssGeometry`: boolean = false — Take the shell's geometry from CSS custom properties rather than from the breakpoint the JavaScript resolved. Web only, and a contract: the app must inline the stylesheet `createAppShellCss` builds from the same config. It exists for statically rendered apps, where the prerender has no viewport to measure and every guess it makes lands as a layout shift and a hydration mismatch on first paint. See `shellCssVars.ts`.
- `statusBar`: StatusBarConfig
- `padding`: ResponsiveSize = no padding — Padding inside the main content area: a spacing token (`'md'`), px number, or a per-breakpoint object. @default no padding
- `withBorder`: boolean = true — Default `withBorder` for every section. @default true
- `zIndex`: number = each section's `theme.zIndices` layer — Stacking order for every section that doesn't set its own. @default each section's `theme.zIndices` layer
- `transitionDuration`: number = 200 — Navbar/content transition length in ms (`0` = instant). Reduced motion forces `0`. @default 200
- `transitionTimingFunction`: string = a cubic ease-in-out — CSS timing function for the navbar/content transitions: `'linear'`, `'ease'`, `'ease-in'`, `'ease-out'`, `'ease-in-out'` or `'cubic-bezier(…)'`.
- `disabled`: boolean = false
- `children` (required): React.ReactNode
- `withSafeArea`: boolean = true
- `maxContentWidth`: number | string — Maximum width for main content area to prevent stretching on wide screens
- `centerContent`: boolean — Center content when maxContentWidth is set
- `tableOfContents`: React.ReactNode — Optional table of contents rendered at the end side of the main content
- `hideTableOfContentsOnMobile`: boolean = true — Hide the table of contents automatically on mobile breakpoints
- `tableOfContentsWidth`: number | string = 280 — Custom width for the table of contents column
- `tableOfContentsWithBorder`: boolean = true — Toggle border between content and table of contents
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { AppShellHeader, AppShellNavbar, AppShellAside, AppShellFooter, AppShellBottomNav, AppShellMain, AppShellSection, BottomAppBar, StatusBarManager, AppLayoutProvider, AppLayoutRenderer, MobileMenu } from '@plocks/ui';`

### AppShellHeader

- `children` (required): React.ReactNode
- `withBorder`: boolean = AppShell `withBorder` — Draw the hairline between this section and the content. @default AppShell `withBorder`
- `zIndex`: number — Stacking order; wins over the section config and the theme layer.
- `accessibilityLabel`: string — Accessible name of the section's landmark.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### AppShellNavbar

- `drawerMode`: boolean — Force the overlay drawer (`true`) or the inline rail (`false`). Defaults to the drawer below `navbar.breakpoint`.
- `accessibilityLabel`: string = 'Main' — Accessible name of the navigation landmark. @default 'Main'
- `children` (required): React.ReactNode
- `withBorder`: boolean = AppShell `withBorder` — Draw the hairline between this section and the content. @default AppShell `withBorder`
- `zIndex`: number — Stacking order; wins over the section config and the theme layer.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### AppShellAside

- `children` (required): React.ReactNode
- `withBorder`: boolean = AppShell `withBorder` — Draw the hairline between this section and the content. @default AppShell `withBorder`
- `zIndex`: number — Stacking order; wins over the section config and the theme layer.
- `accessibilityLabel`: string — Accessible name of the section's landmark.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### AppShellFooter

- `children` (required): React.ReactNode
- `withBorder`: boolean = AppShell `withBorder` — Draw the hairline between this section and the content. @default AppShell `withBorder`
- `zIndex`: number — Stacking order; wins over the section config and the theme layer.
- `accessibilityLabel`: string — Accessible name of the section's landmark.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### AppShellBottomNav

- `children`: React.ReactNode — Content pinned to the bottom edge of the shell.
- `withBorder`: boolean
- `zIndex`: number
- `accessibilityLabel`: string — Accessible name of the navigation landmark.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### AppShellMain

- `children` (required): React.ReactNode
- `id`: string — Element id (DOM `id` on web, `nativeID` on native).
- `role`: Role = 'main' — Landmark role. @default 'main'
- `maw`: number | string — Maximum width of the content column inside the main area (the area itself still fills the space between the chrome), to prevent stretching on wide screens.
- `centerContent`: boolean — Center content when `maw` is set
- `tableOfContents`: React.ReactNode — Table of contents content to show at the end side of the content
- `hideTocOnMobile`: boolean — Hide table of contents on mobile
- `tocWidth`: number | string — Width of the table of contents sidebar
- `tocWithBorder`: boolean — Add border to table of contents
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### AppShellSection

- `children` (required): React.ReactNode
- `grow`: boolean — Take the remaining space of the navbar/aside.
- `withScrollArea`: boolean — Scroll the section's content when it overflows.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### BottomAppBar

- `items`: BottomAppBarItem[] — Structured items definition for standard navigation bar
- `activeKey`: string — Currently active item key
- `onItemPress`: (key: string) => void — Callback when an item is pressed (fires after per-item onPress)
- `showLabels`: boolean — Show labels under icons (default true). Items are still named for screen readers when hidden.
- `variant`: 'solid' | 'surface' | 'elevated' | 'translucent' — Visual variant
- `elevation`: number = 4 — Shadow strength for the `elevated` variant (Android-style elevation, 0–24). @default 4
- `fab`: React.ReactNode — Optional floating action button rendered centered & elevated
- `children`: React.ReactNode — Content pinned to the bottom edge of the shell.
- `withBorder`: boolean
- `zIndex`: number
- `accessibilityLabel`: string — Accessible name of the navigation landmark.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### StatusBarManager

- `children`: React.ReactNode
- `style`: 'auto' | 'light' | 'dark'
- `backgroundColor`: string
- `translucent`: boolean
- `hidden`: boolean

### AppLayoutProvider

- `blueprint` (required): AppLayoutBlueprint
- `value`: AppLayoutRuntimeOverrides
- `children` (required): React.ReactNode

### AppLayoutRenderer

- `children` (required): React.ReactNode

### MobileMenu

- `opened`: boolean — Whether the menu is open.
- `onClose` (required): () => void — Called when the menu asks to close (backdrop press, Escape, Android back).
- `children`: React.ReactNode
- `config`: MobileMenuConfig
- `accessibilityLabel`: string = 'Menu' — Accessible name of the menu dialog. @default 'Menu'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useAppShell(): AppShellContextValue` — Returns the full state of the enclosing `AppShell` — resolved section sizes, navbar open/collapsed/rail flags, the current `breakpoint` and `isMobile`, and the `openNavbar` / `closeNavbar` / `toggleNavbar` controls — and throws when called outside an `AppShell`.
- `useAppShellApi(): AppShellApi` — Returns just the enclosing `AppShell`'s navbar controls (`openNavbar`, `closeNavbar`, `toggleNavbar`) — for menu buttons and links that drive the navbar without re-rendering on layout changes — and throws when called outside an `AppShell`.
- `useAppShellLayout(): AppShellLayoutValue` — Returns just the enclosing `AppShell`'s resolved section sizes (`headerHeight`, `navbarWidth`, `asideWidth`, `footerHeight`, `bottomNavHeight`) — for content that has to position itself around the shell chrome — and throws when called outside an `AppShell`.
- `useBreakpoint(): Breakpoint` — Returns the current breakpoint name, from the theme's breakpoint table (`theme.breakpoints`, or a `BreakpointProvider` override): `base` below `xs` (480), then `xs`, `sm` (576), `md` (768), `lg` (992), `xl` (1200).
- `useNavbarHover(): boolean` — Returns `true` while the pointer is over the `AppShell` navbar rail (web, with `navbar.expandOnHover` on) and `false` otherwise, including outside an `AppShell` — for navbar content that should show its labels only while the collapsed rail is hover-expanded.
- `useAppLayoutContext(): AppLayoutProviderValue` — Returns the enclosing `AppLayoutProvider`'s value — the `defineAppLayout` `blueprint` plus the resolved `runtime` (`query`, `pathname`, `navigation`, `platform`, `meta`) — for custom renderers that read the layout the way `AppLayoutRenderer` does, and throws when called outside an `AppLayoutProvider`.

## Types

```ts
export interface HeaderConfig {
  height: ResponsiveSize;
  /** Hide the header: `AppShell.Header` renders nothing and reserves no height. @default false */
  collapsed?: boolean;
  /**
   * Whether the main content starts below the header. `false` lets content run
   * underneath it (e.g. a translucent header over a hero image). @default true
   */
  offset?: boolean;
  /** Stacking order of `AppShell.Header`. @default theme.zIndices.header */
  zIndex?: number;
}

export interface NavbarConfig {
  width: ResponsiveSize;
  /**
   * Narrowest viewport at which the navbar is an inline rail (web). Below it the
   * navbar is an overlay drawer. Native apps always use the drawer. @default 'md'
   */
  breakpoint?: Breakpoint;
  /**
   * Initial state. `mobile: false` starts the drawer open; `desktop: true`
   * starts the desktop navbar collapsed to its rail (`startCollapsedDesktop`
   * takes precedence). The state resets when the viewport crosses `breakpoint`.
   */
  collapsed?: {
    mobile?: boolean;
    desktop?: boolean;
  };
  /**
   * Stacking order of the inline rail. @default theme.zIndices.sticky
   * (The drawer uses `theme.zIndices.overlay`, above the header; set
   * `AppShell.Navbar zIndex` to override both.)
   */
  zIndex?: number;
  collapsedWidth?: number;
  expandOnHover?: boolean;
  /**
   * When paired with `expandOnHover`, hovering the collapsed rail pushes the
   * main content aside (flexing the page) instead of overlaying it.
   * Defaults to `false` (overlay) to preserve existing behavior.
   */
  expandOnHoverPush?: boolean;
  /**
   * Auto-expand the navbar (start open, not a collapsed rail) once the viewport
   * reaches this breakpoint or wider, e.g. `'xl'`. Overrides
   * `startCollapsedDesktop` at/above the breakpoint; smaller desktops keep the
   * collapsed-with-hover behavior.
   */
  autoExpandBreakpoint?: Breakpoint;
  startCollapsedDesktop?: boolean;
}

export interface AsideConfig {
  width: ResponsiveSize;
  /** Narrowest viewport at which `collapsed.desktop` applies; below it `collapsed.mobile` does. @default 'md' */
  breakpoint?: Breakpoint;
  collapsed?: {
    /** @default true */
    mobile?: boolean;
    /** @default false */
    desktop?: boolean;
  };
  /** Stacking order of `AppShell.Aside`. @default theme.zIndices.sticky */
  zIndex?: number;
}

export interface FooterConfig {
  height: ResponsiveSize;
  /** Hide the footer: `AppShell.Footer` renders nothing and reserves no height. @default false */
  collapsed?: boolean;
  /** Whether the main content ends above the footer. `false` lets content run underneath it. @default true */
  offset?: boolean;
  /** Stacking order of `AppShell.Footer`. @default theme.zIndices.sticky */
  zIndex?: number;
}

export interface BottomNavConfig {
  height: ResponsiveSize;
  /** Only show the bottom navigation at mobile widths (and on native). @default true */
  showOnlyMobile?: boolean;
  /** Hide the bottom navigation. @default false */
  collapsed?: boolean;
  /** Stacking order of `AppShell.BottomNav`. @default theme.zIndices.sticky */
  zIndex?: number;
}

export interface LayoutVisibilityConfig {
  header?: boolean;
  navbar?: boolean;
  aside?: boolean;
  footer?: boolean;
  bottomNav?: boolean;
}

export interface BottomAppBarItem {
  key: string;
  label: string;
  icon: React.ReactNode;
  activeIcon?: React.ReactNode;
  badgeCount?: number;
  onPress?: () => void; // per-item override
}

export interface BottomAppBarProps extends AppShellBottomNavProps {
  /** Structured items definition for standard navigation bar */
  items?: BottomAppBarItem[];
  /** Currently active item key */
  activeKey?: string;
  /** Callback when an item is pressed (fires after per-item onPress) */
  onItemPress?: (key: string) => void;
  /** Show labels under icons (default true). Items are still named for screen readers when hidden. */
  showLabels?: boolean;
  /** Visual variant */
  variant?: 'solid' | 'surface' | 'elevated' | 'translucent';
  /** Shadow strength for the `elevated` variant (Android-style elevation, 0–24). @default 4 */
  elevation?: number;
  /** Optional floating action button rendered centered & elevated */
  fab?: React.ReactNode;
}
```

## Examples

### Basics

Arrange a header and page content inside a responsive app frame.

```tsx
import { AppShell, Block, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth h={240}>
      <AppShell
        header={{ height: 48 }}
        headerContent={<Text p="sm">App header</Text>}
        autoLayout
        withSafeArea={false}
      >
        <Block p="md">
          <Text>Page content</Text>
        </Block>
      </AppShell>
    </Block>
  );
}
```

### Enhanced

```tsx
import { AppShell, Block, Text } from '@plocks/ui';

const sampleTOC = (
  <Block>
    <Text variant="h6" mb="sm">Contents</Text>
    <Text size="sm" style={{ paddingLeft: 0 }}>Introduction</Text>
    <Text size="sm" style={{ paddingLeft: 12 }}>Getting Started</Text>
    <Text size="sm" style={{ paddingLeft: 12 }}>Installation</Text>
    <Text size="sm" style={{ paddingLeft: 24 }}>NPM Package</Text>
    <Text size="sm" style={{ paddingLeft: 24 }}>Yarn Setup</Text>
    <Text size="sm" style={{ paddingLeft: 12 }}>Configuration</Text>
    <Text size="sm" style={{ paddingLeft: 0 }}>Components</Text>
    <Text size="sm" style={{ paddingLeft: 12 }}>AppShell</Text>
    <Text size="sm" style={{ paddingLeft: 12 }}>Layout System</Text>
    <Text size="sm" style={{ paddingLeft: 0 }}>Examples</Text>
  </Block>
);

export function Demo() {
  return (
    <AppShell
      header={{ height: 60 }}
      navbar={{ 
        width: 280, 
        breakpoint: 'md',
        collapsed: { mobile: true }
      }}
      autoLayout
      headerContent={() => (
        <Text variant="h4" style={{ padding: 16 }}>
          Documentation
        </Text>
      )}
      navbarContent={() => (
        <Block p="md">
          <Text variant="h6">Navigation</Text>
          <Text size="sm">Getting Started</Text>
          <Text size="sm">Components</Text>
          <Text size="sm">Examples</Text>
          <Text size="sm">API Reference</Text>
        </Block>
      )}
      maxContentWidth={960}
      tableOfContents={sampleTOC}
      tableOfContentsWidth={280}
      hideTableOfContentsOnMobile
      centerContent
    >
      <Block p="lg">
        <Text variant="h1">Main Content with TOC</Text>
        <Text>
          This demonstrates the enhanced AppShell with max width constraints 
          and a table of contents sidebar. The main content area has a maximum 
          width and is centered, while the table of contents appears on the right 
          on desktop screens.
        </Text>
        <Text>
          The layout is fully responsive - on mobile devices, the table of contents 
          is hidden by default to preserve screen space.
        </Text>
        <Text variant="h2">Features</Text>
        <Text>
          • Max width constraint for better readability on wide screens
        </Text>
        <Text>
          • Table of contents sidebar with responsive behavior
        </Text>
        <Text>
          • Configurable through AppShell or AppShellMain props
        </Text>
        <Text>
          • Seamless integration with existing AppShell layout system
        </Text>
      </Block>
    </AppShell>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/AudioPlayer.md -->

# AudioPlayer

AudioPlayer combines audio playback controls with a seekable waveform.

## Metadata

- Import: `import { AudioPlayer } from '@plocks/media';`
- Install: `npm install @plocks/media` — a separate package from `@plocks/ui`
- Status: beta
- Tags: audio, player, waveform, media, playback
- Docs: https://plocks.dev/components/AudioPlayer
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/media/src/components/AudioPlayer

## Props

- `source`: string | number | { uri: string } — Audio source - can be URL, local file, or asset
- `peaks`: number[] — Pre-computed waveform peaks (optional - placeholder peaks are generated if not provided)
- `w`: number = 300 — Waveform width in px — not the player's, which fills its parent. @default 300
- `h`: number = 60 — Waveform height in px. @default 60
- `autoPlay`: boolean — Whether to auto-play when loaded
- `loop`: boolean — Whether to loop the audio
- `volume`: number — Initial volume (0-1)
- `rate`: number — Playback rate (0.5-2.0)
- `showControls`: boolean — Whether to show player controls
- `controls`: AudioPlayerControls — Which controls to display; merged over the defaults.
- `controlsPosition`: 'top' | 'bottom' | 'overlay' | 'none' — Where the controls sit: above or below the waveform, laid over it, or hidden. Metadata renders above the waveform for `overlay` and `none`.
- `onLoad`: (data: AudioLoadData) => void — Called when audio is loaded and ready
- `onPlaybackStateChange`: (state: PlaybackState) => void — Called when playback state changes
- `onProgress`: (data: ProgressData) => void — Called during playback with current time
- `onEnd`: () => void — Called when playback finishes
- `onError`: (error: AudioError) => void — Called on playback error
- `generateWaveform`: boolean — Draw placeholder peaks when `peaks` is omitted. expo-audio can't analyze a file up front, so pass measured `peaks` when the waveform's shape matters.
- `waveformOptions`: { samples?: number; } — Placeholder waveform options
- `showTime`: boolean — Show time labels
- `timeFormat`: 'mm:ss' | 'hh:mm:ss' | 'relative' — Time format: `mm:ss`, `hh:mm:ss`, or `relative` (elapsed / `-remaining`).
- `showMetadata`: boolean — Show audio metadata
- `metadata`: AudioMetadata — Audio metadata
- `enableKeyboardShortcuts`: boolean = true — Keyboard shortcuts while the waveform (seek slider) has focus (web): Space play/pause, J / L skip back / forward, M mute. Arrow keys, Page Up/Down and Home/End seek. @default true
- `keyboardShortcuts`: KeyboardShortcuts — Override the shortcut keys (`KeyboardEvent.key` values, case-insensitive).
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Waveform` props (`color` `size` `barWidth` `barGap` `strokeWidth` `gradientColors` `progressColor` `interactive` `onSeek` `onDragStart` `onDrag` `onDragEnd` `accessibilityLabel` `accessibilityHint` `minBarHeight` `normalize` `fullWidth` `maxVisibleBars` `showProgressLine` `progressLineStyle` `showTimeStamps` `timeStampInterval` `loading` `error` `loadingProgress` `selection` `onSelectionChange` `showRMS` `rmsData` `markers` `enablePerformanceMonitoring` `onPerformanceMetrics`): https://plocks.dev/llms/components/Waveform.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface AudioPlayerControls {
  /** Play / pause button. @default true */
  playPause?: boolean;
  /** Skip back / forward 10 seconds buttons. @default true */
  skip?: boolean;
  /** Mute / unmute button. @default true */
  volume?: boolean;
  /** Playback speed button (cycles 0.5x–2x). @default false */
  speed?: boolean;
  /** The seekable waveform. @default true */
  waveform?: boolean;
}

export interface AudioLoadData {
  duration: number;
  sampleRate: number;
  channels: number;
  bitrate?: number;
  format?: string;
  peaks?: number[];
}

export interface PlaybackState {
  isPlaying: boolean;
  isLoading: boolean;
  isBuffering: boolean;
  currentTime: number;
  duration: number;
  volume: number;
  rate: number;
  loop: boolean;
}

export interface ProgressData {
  currentTime: number;
  duration: number;
  progress: number; // 0-1
  position: number; // 0-1 for waveform
  /** Always 0: expo-audio doesn't report buffered ranges. */
  buffered: number;
}

export interface AudioError {
  code: string;
  message: string;
  details?: unknown;
}

export interface AudioMetadata {
  title?: string;
  artist?: string;
  album?: string;
  artwork?: string;
  duration?: number;
  genre?: string;
  year?: number;
}

export interface KeyboardShortcuts {
  /** @default ' ' (Space) */
  playPause?: string;
  /** @default 'l' */
  skipForward?: string;
  /** @default 'j' */
  skipBackward?: string;
  volumeUp?: string;
  volumeDown?: string;
  /** @default 'm' */
  mute?: string;
}
```

## Examples

### Basics

Point `source` at a URL or a bundled clip and pass its `peaks` to draw the real waveform; the player handles loading, play/pause, seeking and progress. Playback requires `expo-audio`; without it the controls render but report a missing-module error.

```tsx
import { AudioPlayer } from '@plocks/media';
import { Block } from '@plocks/ui';

const MELODY_PEAKS = [
  0.765, 0.683, 0.598, 0.528, 0.464, 0.407, 0.36, 0.316, 0.277, 0.243, 0.949, 0.876,
  0.776, 0.698, 0.592, 0.533, 0.477, 0.407, 0.365, 0.323, 0.528, 0.922, 0.851, 0.738,
  0.643, 0.569, 0.489, 0.438, 0.383, 0.34, 0.297, 0.954, 0.885, 0.798, 0.693, 0.606,
  0.525, 0.468, 0.41, 0.354, 0.308, 0.925, 0.919, 0.828, 0.727, 0.64, 0.557, 0.474,
  0.415, 0.376, 0.338, 0.297, 0.997, 0.869, 0.775, 0.667, 0.595, 0.51, 0.444, 0.408,
  0.356, 0.316, 1, 0.872, 0.786, 0.691, 0.619, 0.555, 0.483, 0.4, 0.359, 0.322,
  0.288, 0.941, 0.835, 0.748, 0.661, 0.588, 0.506, 0.439, 0.39, 0.342, 0.306, 0.272,
  0.238, 0.203, 0.148, 0.13, 0.114, 0.101, 0.088, 0.078, 0.068, 0.06, 0.053, 0.047,
];

export function Demo() {
  return (
    <Block fullWidth>
      <AudioPlayer
        source={require('../../../../assets/sounds/melody.mp3')}
        peaks={MELODY_PEAKS}
        fullWidth
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/AutoComplete.md -->

# AutoComplete

Provide search functionality with suggestions, supporting single/multi-select, async data loading, and rich content display.

## Metadata

- Import: `import { AutoComplete } from '@plocks/ui';`
- Tags: input, search, typeahead, autocomplete, suggestions
- Docs: https://plocks.dev/components/AutoComplete
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/AutoComplete

## Props

- `testID`: string — Test identifier, forwarded to the underlying text input (the field's focusable element); the root gets `${testID}-root`.
- `data`: AutoCompleteOption[] = EMPTY_OPTIONS — Data source for suggestions
- `onSearch`: (query: string) => Promise<AutoCompleteOption[]> — Async data fetcher
- `minSearchLength`: number = 2 — Minimum characters to trigger search
- `searchDelay`: number = 300 — Debounce delay for `onSearch`, in ms (local `data` filters immediately).
- `renderItem`: ( item: AutoCompleteOption, index: number, options: { query: string; onSelect: (item: AutoCompleteOption) => void; isHighlighted?: boolean; isSelected?: boolean; } ) => React.ReactNode — Custom item renderer (the row stays an accessible option).
- `onSelect`: (item: AutoCompleteOption) => void — Selection handler
- `renderValue`: ( item: AutoCompleteOption, context: { focused: boolean; clear: () => void; } ) => React.ReactNode — Custom renderer for the selected option shown inside the single-select input. When provided and an option is selected, the returned node is overlaid on the text field while it is not focused (focusing the field reveals the editable text so the query can be changed). Ignored in multiSelect mode — use `renderSelectedValue` for chips there.
- `maxSuggestions`: number = 10 — Maximum number of suggestions to display (0 = no limit).
- `showSuggestionsOnFocus`: boolean = true — Whether to show suggestions on focus (default: true)
- `renderEmptyState`: () => React.ReactNode — Custom empty state component
- `renderLoadingState`: () => React.ReactNode — Custom loading state component
- `filter`: (item: AutoCompleteOption, query: string) => boolean = defaultFilter — Filter function for local data
- `highlightMatches`: boolean = true — Whether to highlight matching text
- `highlightColor`: string — Text color for the matched substring when `highlightMatches` is on. Defaults to the theme's link (accent text) color.
- `highlightBackgroundColor`: string = 'transparent' — Background color painted behind the matched substring (default: transparent — the match is distinguished by color and weight).
- `suggestionsStyle`: StyleProp<ViewStyle> — Styles for the suggestions surface.
- `suggestionItemStyle`: StyleProp<ViewStyle> — Styles for each suggestion row.
- `groupLabelProps`: Omit<TextProps, 'children'> — Override props for each group header `<Text>` (style, weight, size, color, uppercase…). Headers use the theme's `sectionLabel` text role by default.
- `multiSelect`: boolean = false — Enable multi-select mode
- `selectedValues`: AutoCompleteOption[] = EMPTY_OPTIONS — Selected values for multi-select mode
- `renderSelectedValue`: ( item: AutoCompleteOption, index: number, context: { onRemove: () => void; disabled: boolean; isFocused: boolean; inputValue: string; source: 'input' | 'modal'; } ) => React.ReactNode — Custom renderer for each selected value chip in multi-select mode
- `selectedValuesContainerStyle`: StyleProp<ViewStyle> — Optional style override for the selected values container
- `selectedValueChipProps`: Partial<ChipProps> — Additional props applied to the default Chip renderer for selected values
- `refocusAfterSelect`: boolean — Controls whether the input regains focus after selecting an option
- `freeSolo`: boolean = false — Whether to allow free-form input (Enter commits the typed text as an option)
- `displayProperty`: 'label' | 'value' = 'label' — Which field of the selected option is written into the input: its human-readable `label`, or its `value`.
- `useModal`: boolean — Present suggestions in a modal sheet (true) or an anchored dropdown (false). Default: sheet on native and small screens, dropdown on desktop web.
- `textInputProps`: Omit<TextInputProps, 'value' | 'onChangeText' | 'placeholder'> — Additional TextInput props
- `placement`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom-start' — Placement preference for the suggestions dropdown (default: 'bottom-start')
- `fallbackPlacements`: PlacementType[] = DEFAULT_FALLBACK_PLACEMENTS — Placements to try when the preferred one doesn't fit.
- `offset`: number = 4 — Gap between the field and the dropdown, px (default: 4)
- `flip`: boolean = true — Enable flipping to opposite side when dropdown would go off-screen (default: true)
- `shift`: boolean = false — Enable shifting within bounds when dropdown would go off-screen (default: false)
- `boundary`: number = 12 — Distance from viewport edges in pixels (default: 12)
- `autoReposition`: boolean = true — Enable automatic repositioning on scroll/resize (default: true)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface AutoCompleteOption {
  label: string;
  value: string;
  group?: string;
  disabled?: boolean;
  /** Additional data for the option (free-form; read it back in `renderItem` / `onSelect`). */
  data?: unknown;
}
```

## Examples

### Basics

Simple auto-complete. Start typing to filter the list. Selecting an option fills the input.

```tsx
import { AutoComplete, Block } from '@plocks/ui';

const sports = [
  { label: 'Football', value: 'football' },
  { label: 'Basketball', value: 'basketball' },
  { label: 'Soccer', value: 'soccer' },
  { label: 'Baseball', value: 'baseball' },
  { label: 'Tennis', value: 'tennis' },
  { label: 'Golf', value: 'golf' },
  { label: 'Swimming', value: 'swimming' },
  { label: 'Volleyball', value: 'volleyball' },
  { label: 'Cricket', value: 'cricket' },
  { label: 'Rugby', value: 'rugby' },
  { label: 'Softball', value: 'softball' },
  { label: 'Hockey', value: 'hockey' },
];

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Choose a sport"
        placeholder="Search for a sport..."
        data={sports}
        minSearchLength={1}
        fullWidth
      />
    </Block>
  );
}
```

### Multi-select tags

Tap an item to add or remove it. Selected genres render as removable chips.

```tsx
import { useState } from 'react';
import { AutoComplete, Block } from '@plocks/ui';
import type { AutoCompleteOption } from '@plocks/ui';

const genres = [
  { label: 'Pop', value: 'pop' },
  { label: 'Rock', value: 'rock' },
  { label: 'Hip Hop', value: 'hiphop' },
  { label: 'Jazz', value: 'jazz' },
  { label: 'Classical', value: 'classical' },
  { label: 'Electronic', value: 'electronic' },
  { label: 'Country', value: 'country' },
  { label: 'R&B', value: 'rnb' },
];

export function Demo() {
  const [selectedGenres, setSelectedGenres] = useState<AutoCompleteOption[]>([]);

  const handleToggle = (option: AutoCompleteOption) => {
    const isSelected = selectedGenres.some((genre) => genre.value === option.value);

    setSelectedGenres((current) =>
      isSelected
        ? current.filter((genre) => genre.value !== option.value)
        : [...current, option],
    );
  };

  return (
    <Block fullWidth>
      <AutoComplete
        label="Music genres"
        placeholder="Search genres..."
        data={genres}
        onSelect={handleToggle}
        multiSelect
        selectedValues={selectedGenres}
        minSearchLength={0}
        fullWidth
      />
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on AutoComplete.

```tsx
import { Column, AutoComplete } from '@plocks/ui';

const options = ['Apple', 'Banana', 'Cherry'].map(value => ({ label: value, value: value.toLowerCase() }));

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <AutoComplete key={variant} variant={variant} label={`${variant} variant`} data={options} placeholder="Choose a fruit" />
      ))}
    </Column>
  );
}
```

### Select-Like Behavior

Behaves like a Select: the field is non-editable (`editable={false}`), so it can't be typed into or filtered. Tapping opens the full option list (`filter={() => true}`) and the value is chosen from it.

```tsx
import { AutoComplete, Block } from '@plocks/ui';

const countries = [
  { label: 'United States', value: 'us' },
  { label: 'Canada', value: 'ca' },
  { label: 'United Kingdom', value: 'uk' },
  { label: 'Germany', value: 'de' },
  { label: 'France', value: 'fr' },
  { label: 'Italy', value: 'it' },
  { label: 'Spain', value: 'es' },
  { label: 'Netherlands', value: 'nl' },
  { label: 'Australia', value: 'au' },
  { label: 'Japan', value: 'jp' },
  { label: 'South Korea', value: 'kr' },
  { label: 'Brazil', value: 'br' },
  { label: 'Mexico', value: 'mx' },
  { label: 'India', value: 'in' },
  { label: 'China', value: 'cn' },
];

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Country"
        placeholder="Select a country..."
        data={countries}
        maxSuggestions={countries.length}
        editable={false}
        caretHidden
        filter={() => true}
        highlightMatches={false}
        fullWidth
      />
    </Block>
  );
}
```

### Async auto-complete

Performs a debounced search against a simulated API before returning matches.

```tsx
import { AutoComplete, Block } from '@plocks/ui';

const languages = [
  { label: 'JavaScript', value: 'javascript' },
  { label: 'TypeScript', value: 'typescript' },
  { label: 'Python', value: 'python' },
  { label: 'Java', value: 'java' },
  { label: 'C++', value: 'cpp' },
  { label: 'C#', value: 'csharp' },
  { label: 'Go', value: 'go' },
  { label: 'Rust', value: 'rust' },
  { label: 'Swift', value: 'swift' },
  { label: 'Kotlin', value: 'kotlin' },
];

const searchLanguages = async (query: string) => {
  await new Promise((resolve) => setTimeout(resolve, 400));

  const normalized = query.toLowerCase();
  return languages.filter((language) => language.label.toLowerCase().includes(normalized));
};

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Search programming languages"
        placeholder="Start typing..."
        onSearch={searchLanguages}
        fullWidth
      />
    </Block>
  );
}
```

### Free Solo

Suggests fruits while still accepting custom values.

```tsx
import { AutoComplete, Block } from '@plocks/ui';

const fruits = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Orange', value: 'orange' },
  { label: 'Grape', value: 'grape' },
  { label: 'Mango', value: 'mango' },
  { label: 'Pineapple', value: 'pineapple' },
];

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Favorite fruit"
        placeholder="Type anything..."
        data={fruits}
        freeSolo
        minSearchLength={0}
        fullWidth
      />
    </Block>
  );
}
```

### Free Solo (multi-select)

Suggests fruits but lets you add any custom value as a tag — press Enter to add what you typed.

```tsx
import { useState } from 'react';
import { AutoComplete, Block } from '@plocks/ui';
import type { AutoCompleteOption } from '@plocks/ui';

const fruits = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Orange', value: 'orange' },
  { label: 'Grape', value: 'grape' },
  { label: 'Mango', value: 'mango' },
  { label: 'Pineapple', value: 'pineapple' },
];

export function Demo() {
  const [selected, setSelected] = useState<AutoCompleteOption[]>([]);

  const handleToggle = (option: AutoCompleteOption) => {
    const isSelected = selected.some((item) => item.value === option.value);

    setSelected((current) =>
      isSelected
        ? current.filter((item) => item.value !== option.value)
        : [...current, option],
    );
  };

  return (
    <Block fullWidth>
      <AutoComplete
        label="Favorite fruits"
        placeholder="Type a fruit and press Enter..."
        data={fruits}
        onSelect={handleToggle}
        freeSolo
        multiSelect
        selectedValues={selected}
        minSearchLength={0}
        fullWidth
      />
    </Block>
  );
}
```

### Grouped suggestions

Countries are organized by region to make large lists easier to scan.

```tsx
import { AutoComplete, Block } from '@plocks/ui';

const countries = [
  { label: 'United States', value: 'us', group: 'North America' },
  { label: 'Canada', value: 'ca', group: 'North America' },
  { label: 'Mexico', value: 'mx', group: 'North America' },
  { label: 'United Kingdom', value: 'uk', group: 'Europe' },
  { label: 'Germany', value: 'de', group: 'Europe' },
  { label: 'France', value: 'fr', group: 'Europe' },
  { label: 'Japan', value: 'jp', group: 'Asia' },
  { label: 'India', value: 'in', group: 'Asia' },
  { label: 'Australia', value: 'au', group: 'Oceania' },
  { label: 'Brazil', value: 'br', group: 'South America' },
];

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Search countries"
        placeholder="Search for a country..."
        data={countries}
        minSearchLength={1}
        fullWidth
      />
    </Block>
  );
}
```

### Rich Content

Pass `renderItem` to lay out each suggestion and `renderValue` to draw the chosen option inside the field; `refocusAfterSelect={false}` blurs the field on select so that value shows right away.

```tsx
import { AutoComplete, Block, Column, Icon, MenuItemButton, Row, Text } from '@plocks/ui';

interface RichSportOption {
  label: string;
  value: string;
  emoji: string;
  color: string;
  price: number;
  duration: string;
}

const sports: RichSportOption[] = [
  { label: 'Soccer', value: 'soccer', emoji: '⚽', color: '#22c55e', price: 75.5, duration: '90 min' },
  { label: 'Basketball', value: 'basketball', emoji: '🏀', color: '#f97316', price: 120.0, duration: '48 min' },
  { label: 'Football', value: 'football', emoji: '🏈', color: '#92400e', price: 180.0, duration: '60 min' },
  { label: 'Volleyball', value: 'volleyball', emoji: '🏐', color: '#fbbf24', price: 60.0, duration: 'Best of 5' },
  { label: 'Baseball', value: 'baseball', emoji: '⚾', color: '#ef4444', price: 85.0, duration: '9 innings' },
  { label: 'Golf', value: 'golf', emoji: '⛳', color: '#15803d', price: 110.0, duration: '4 hrs' },
];

const tint = (hex: string, alpha: string) => `${hex}${alpha}`;

const renderTile = (sport: RichSportOption, size: number) => (
  <Block
    w={size}
    h={size}
    radius="lg"
    align="center"
    justify="center"
    bg={tint(sport.color, '26')}
    borderWidth={1}
    borderColor={tint(sport.color, '59')}
  >
    <Text size={size >= 40 ? 'xl' : 'md'}>{sport.emoji}</Text>
  </Block>
);

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Search sports"
        placeholder="Search sports..."
        data={sports}
        refocusAfterSelect={false}
        renderItem={(item, _index, helpers) => {
          const sport = item as RichSportOption;

          return (
            <MenuItemButton
              rounded={false}
              compact
              fullWidth
              active={helpers.isHighlighted || helpers.isSelected}
              onPress={() => helpers.onSelect(sport)}
              style={{ alignItems: 'stretch', gap: 0 }}
            >
              <Row align="center" gap="md" px="md" py="sm" fullWidth>
                {renderTile(sport, 40)}

                <Column grow={1} gap="xs">
                  <Text size="sm" fw="semibold" numberOfLines={1}>
                    {sport.label}
                  </Text>
                  <Text size="xs" c="secondary" numberOfLines={1}>
                    {sport.duration}
                  </Text>
                </Column>

                <Column align="flex-end" gap="xs">
                  <Text size="sm" fw="semibold">
                    ${sport.price.toFixed(2)}
                  </Text>
                  <Text size="xs" c="secondary">
                    avg ticket
                  </Text>
                </Column>

                {helpers.isSelected ? (
                  <Icon name="check" size={16} stroke={3} color={sport.color} />
                ) : (
                  <Block w={16} />
                )}
              </Row>
            </MenuItemButton>
          );
        }}
        renderValue={(item) => {
          const sport = item as RichSportOption;

          return (
            <Row align="center" gap="sm" grow={1}>
              {renderTile(sport, 24)}
              <Text size="sm" fw="semibold">{sport.label}</Text>
              <Text size="xs" c="secondary">
                {sport.duration}
              </Text>
              <Block grow={1} />
              <Text size="sm" fw="semibold">
                ${sport.price.toFixed(2)}
              </Text>
            </Row>
          );
        }}
        minSearchLength={1}
        fullWidth
      />
    </Block>
  );
}
```

### Highlight colours

`highlightMatches` bolds and tints the part of each suggestion that matches what you typed. Pass `highlightColor` (a CSS color or a palette shade such as `'highlight.8'`) to change that tint, and optionally `highlightBackgroundColor` to fill behind it.

```tsx
import { AutoComplete, Block } from '@plocks/ui';

const fruits = [
  { label: 'Apple', value: 'apple' },
  { label: 'Banana', value: 'banana' },
  { label: 'Cherry', value: 'cherry' },
  { label: 'Date', value: 'date' },
  { label: 'Elderberry', value: 'elderberry' },
  { label: 'Fig', value: 'fig' },
  { label: 'Grape', value: 'grape' },
  { label: 'Honeydew', value: 'honeydew' },
];

export function Demo() {
  return (
    <Block fullWidth>
      <AutoComplete
        label="Search fruits"
        placeholder="Type to search fruits..."
        data={fruits}
        highlightColor="highlight.8"
        minSearchLength={0}
        fullWidth
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Avatar.md -->

# Avatar

Displays user profile images, initials, or icons.

## Metadata

- Import: `import { Avatar } from '@plocks/ui';`
- Tags: avatar, profile, user, image, initials
- Docs: https://plocks.dev/components/Avatar
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Avatar

## Props

- `size`: ComponentSizeValue = 'md' — Size of the avatar: a token or the diameter in px
- `src`: string | ImageSourcePropType — Image for the avatar: a remote URL string or a bundled asset (`require('./avatar.png')`)
- `fallback`: React.ReactNode — Fallback shown when no image is provided: initials string or a custom React node (e.g. an icon).
- `bg`: ColorProp = theme.text.muted — Fill of the avatar circle — not the root, which also holds the label. Resolves like every `bg`: a palette name is its subtle tint, `'primary.5'` a shade.
- `textColor`: ColorProp = a readable color on the background — Text color for the fallback initials. @default a readable color on the background
- `online`: boolean — Whether to show online status indicator
- `indicatorColor`: ColorProp — Color override for the status indicator
- `accessibilityLabel`: string — Accessible name of the avatar ("Jane Doe"). The avatar is an image with this name; without it, it is decorative.
- `label`: React.ReactNode — Primary label displayed beside the avatar (string or custom React node)
- `description`: React.ReactNode — Secondary description/subtext under the label
- `gap`: number = 8 — Spacing between avatar and text block (px)
- `showText`: boolean = true — Force horizontal layout off (set false to hide label/description wrapper)
- `fallbackProps`: Omit<TextProps, 'children'> — Override props applied to the fallback initials `<Text>` (style, fw, ff, size, c).
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the adjacent label `<Text>` (only when `label` is a string).
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the secondary description `<Text>` (only when `description` is a string).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { AvatarGroup } from '@plocks/ui';`

### AvatarGroup

- `children` (required): React.ReactNode
- `limit`: number — Show at most this many avatars, then a `+N` surplus avatar.
- `spacing`: number = -8 — Overlap between avatars (negative px). @default -8
- `size`: ComponentSizeValue
- `bordered`: boolean — Whether to add borders around avatars for separation
- `surplusTooltip`: string — When `limit` hides avatars, wrap the `+N` surplus indicator in a Tooltip with this label.
- `surplusLabel`: string = `${N} more` — Accessible name of the surplus avatar. @default `${N} more`
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Illustrates loading an avatar image with a reliable initials fallback for offline scenarios.

```tsx
import { Avatar } from '@plocks/ui';

export function Demo() {
  return (
    <Avatar
      src={require('../../../../assets/avatars/avatar-1.png')}
      fallback="JD"
      size="xl"
    />
  );
}
```

### Sizes

Choose a `size` token (`xs` through `3xl`) to scale the avatar.

```tsx
import { Avatar, Row } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Avatar key={size} size={size} fallback={size} />
      ))}
    </Row>
  );
}
```

### Icon

Render any `<Icon>` inside an avatar by passing it to the `fallback` prop.

```tsx
import { Avatar, Icon, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" align="center">
      <Avatar
        fallback={<Icon name="user" color="white" />}
        bg="#6366f1"
      />
      <Avatar
        fallback={<Icon name="camera" color="white" />}
        bg="#10b981"
      />
      <Avatar
        fallback={<Icon name="bell" color="white" />}
        bg="#f59e0b"
      />
      <Avatar
        fallback={<Icon name="settings" color="white" />}
        bg="#ef4444"
      />
    </Row>
  );
}
```

### Colors

Preview semantic color tokens and custom hex backgrounds applied to avatar fallbacks.

```tsx
import { Avatar, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Avatar fallback="PR" bg="primary.5" />
      <Avatar fallback="SU" bg="success.5" />
      <Avatar fallback="WA" bg="warning.5" />
      <Avatar fallback="ER" bg="error.5" />
      <Avatar fallback="AB" bg="#FF6B6B" />
    </Row>
  );
}
```

### Groups

Showcases how `AvatarGroup` overlaps avatars by default to conserve space.

```tsx
import { Avatar, AvatarGroup } from '@plocks/ui';

const TEAM = [
  { id: 1, initials: 'SJ', color: '#FF6B6B' },
  { id: 2, initials: 'MC', color: '#4ECDC4' },
  { id: 3, initials: 'ER', color: '#45B7D1' },
  { id: 4, initials: 'DL', color: '#96CEB4' },
  { id: 5, initials: 'KP', color: '#FFEAA7' },
  { id: 6, initials: 'TW', color: '#DDA0DD' },
  { id: 7, initials: 'AB', color: '#FFB6C1' }
];

export function Demo() {
  return (
    <AvatarGroup>
      {TEAM.map(({ id, initials, color }) => (
        <Avatar key={id} fallback={initials} bg={color} />
      ))}
    </AvatarGroup>
  );
}
```

### Overflow

Set `limit` to cap visible avatars and show the remaining count. Pass `surplusTooltip` to reveal who's hidden on hover.

```tsx
import { Avatar, AvatarGroup } from '@plocks/ui';

const TEAM = [
  { id: 1, name: 'Sarah Johnson', initials: 'SJ', color: '#FF6B6B' },
  { id: 2, name: 'Marcus Chen', initials: 'MC', color: '#4ECDC4' },
  { id: 3, name: 'Elena Ruiz', initials: 'ER', color: '#45B7D1' },
  { id: 4, name: 'David Lee', initials: 'DL', color: '#96CEB4' },
  { id: 5, name: 'Kira Patel', initials: 'KP', color: '#FFEAA7' },
  { id: 6, name: 'Tom Ward', initials: 'TW', color: '#DDA0DD' },
  { id: 7, name: 'Aisha Bello', initials: 'AB', color: '#FFB6C1' }
];

const LIMIT = 3;

export function Demo() {
  const hidden = TEAM.slice(LIMIT).map((member) => member.name);

  return (
    <AvatarGroup limit={LIMIT} surplusTooltip={hidden.join(', ')}>
      {TEAM.map(({ id, initials, color }) => (
        <Avatar key={id} fallback={initials} bg={color} />
      ))}
    </AvatarGroup>
  );
}
```

### Status indicator

Demonstrates the `online` presence indicator, including custom `indicatorColor` overrides for alternate states.

```tsx
import { Avatar, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="xl" wrap="wrap">
      <Avatar
        src={require('../../../../assets/avatars/avatar-1.png')}
        label="Josh"
        description="Online"
        online
      />
      <Avatar
        src={require('../../../../assets/avatars/avatar-3.png')}
        label="Mike"
        description="Focus time"
        online
        indicatorColor="#f59e0b"
      />
      <Avatar
        src={require('../../../../assets/avatars/avatar-4.png')}
        label="Tori"
        description="Offline"
      />
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/BackgroundImage.md -->

# BackgroundImage

BackgroundImage places content over an image-filled container.

## Metadata

- Import: `import { BackgroundImage } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/BackgroundImage
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/BackgroundImage

## Props

- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `translateY`: number — Small visual offset without affecting surrounding layout.
- `rotate`: string — Rotation around the block center, such as `"45deg"`.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `start`: number | string — Start inset (logical: left in LTR, right in RTL)
- `end`: number | string — End inset (logical: right in LTR, left in RTL)
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Plus the `Block` props (`children` `className` `onPress` `onLongPress` `onPressIn` `onPressOut` `onMouseEnter` `onMouseLeave` `disabled`): https://plocks.dev/llms/components/Block.md

Plus the `Image` props (`src` `source` `alt` `resizeMode`): https://plocks.dev/llms/components/Image.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

BackgroundImage places content over an image-filled container.

```tsx
import { BackgroundImage, Text } from '@plocks/ui';

const image =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAALklEQVR42mNITvsIR409P+CIAasokMuAVRQqgSkKksAqiiKB5goGrKJQCawuBgC2Wnfh+zNA9wAAAABJRU5ErkJggg==';

export function Demo() {
  return (
    <BackgroundImage
      src={image}
      alt="Abstract color field"
      h={140}
      p="md"
      justify="center"
      radius="lg"
    >
      <Text fw="bold">Content over an image</Text>
    </BackgroundImage>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Badge.md -->

# Badge

Badge displays a compact status or count on a parent element.

## Metadata

- Import: `import { Badge } from '@plocks/ui';`
- Tags: chip, tag, badge, label, removable
- Docs: https://plocks.dev/components/Badge
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Badge

## Props

- `children` (required): React.ReactNode
- `size`: ComponentSizeValue — Size token (the badge renders well below a control of the same size), or height in px.
- `variant`: 'filled' | 'outline' | 'light' | 'subtle' | 'gradient' = 'subtle'
- `v`: 'filled' | 'outline' | 'light' | 'subtle' | 'gradient' — Shorthand alias for `variant`. `variant` wins when both are set.
- `color`: ColorProp — Badge color. A palette token, `'primary.6'` shade syntax, or any CSS color.
- `c`: ColorProp — Shorthand alias for `color`, resolved identically. `color` wins when both are set.
- `onPress`: () => void — Makes the badge a button.
- `startSection`: React.ReactNode — Content (usually an icon) before the label.
- `endSection`: React.ReactNode — Content (usually an icon) after the label.
- `onRemove`: () => void — Show a remove (×) button that calls this.
- `removePosition`: 'left' | 'right' — Which side the remove button sits on (`left`/`right` follow the reading direction).
- `removeButtonLabel`: string = `Remove <label>` — Accessible name of the remove button. @default `Remove <label>`
- `disabled`: boolean
- `textStyle`: StyleProp<TextStyle>
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the inner label `<Text>` (style, fw, ff, size, c).
- `radius`: RadiusValue = 'full' — Corner radius. @default 'full'
- `shadow`: ShadowToken — Drop shadow token. Badges are flat by default.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Wrap any label in a Badge to render a compact tag — the default `filled` variant and `primary` color apply automatically.

```tsx
import { Badge, Row } from '@plocks/ui'

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Badge>New</Badge>
      <Badge>Beta</Badge>
      <Badge>v1.0</Badge>
    </Row>
  )
}
```

### Semantic colors

Set `c` to tokens such as `primary`, `success`, `warning`, `error`, or `gray` to align Badges with semantic meaning instead of hard-coded hex values.

```tsx
import { Badge, Row } from '@plocks/ui'

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Badge c="primary">Primary</Badge>
      <Badge c="success">Success</Badge>
      <Badge c="warning">Warning</Badge>
      <Badge c="error">Error</Badge>
      <Badge c="gray">Gray</Badge>
    </Row>
  )
}
```

### Size scale

Adjust the `size` prop (`xs` through `3xl`, or a number) to match the density of the surrounding UI.

```tsx
import { Badge, Block, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Badge size={size}>Badge</Badge>
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Variant styles

Pick a `variant` like `filled`, `outline`, `light`, `subtle`, or `gradient` when you need to shift emphasis without changing the Badge content.

```tsx
import { Badge, Row } from '@plocks/ui'

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Badge variant="filled">Filled</Badge>
      <Badge variant="outline">Outline</Badge>
      <Badge variant="light">Light</Badge>
      <Badge variant="subtle">Subtle</Badge>
      <Badge variant="gradient">Gradient</Badge>
    </Row>
  )
}
```

### Shadow depth

Use the `shadow` prop (`none` through `xl`) to raise a Badge when it needs extra emphasis over surrounding UI.

```tsx
import { Badge, Row } from '@plocks/ui'

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Badge shadow="none">No Shadow</Badge>
      <Badge shadow="xs">XS Shadow</Badge>
      <Badge shadow="sm">SM Shadow</Badge>
      <Badge shadow="md">MD Shadow</Badge>
      <Badge shadow="lg">LG Shadow</Badge>
      <Badge shadow="xl">XL Shadow</Badge>
    </Row>
  )
}
```

### Prop aliases

`v` is shorthand for `variant`, so you can write more compact JSX without losing any functionality.

```tsx
import { Badge, Block, Row } from '@plocks/ui'

const badges = [
  { label: 'Primary Filled', variant: 'filled', color: 'primary' },
  { label: 'Secondary Outline', variant: 'outline', color: 'secondary' },
  { label: 'Success Light', variant: 'light', color: 'success' },
  { label: 'Warning Subtle', variant: 'subtle', color: 'warning' },
] as const

export function Demo() {
  return (
    <Block>
      <Row gap="sm" wrap="wrap">
        {badges.map((badge) => (
          <Badge key={`full-${badge.label}`} variant={badge.variant} c={badge.color}>
            {badge.label}
          </Badge>
        ))}
      </Row>

      <Row gap="sm" wrap="wrap">
        {badges.map((badge) => (
          <Badge key={`alias-${badge.label}`} v={badge.variant} c={badge.color}>
            {badge.label}
          </Badge>
        ))}
      </Row>
    </Block>
  )
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Block.md -->

# Block

Block is a layout primitive for building styled views.

## Metadata

- Import: `import { Block } from '@plocks/ui';`
- Tags: layout, building-block, polymorphic, foundational
- Docs: https://plocks.dev/components/Block
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Block

## Props

- `children`: React.ReactNode — Child elements to render inside the block
- `component`: React.ElementType — A custom component to render instead of `View`. It receives the resolved `style` and every other forwarded prop. HTML tag names (`'div'`, `'button'`, …) render a `View` — use `role` for semantics.
- `className`: string — Custom className, forwarded to a custom `component` only (web).
- `onPress`: PressableProps['onPress'] — Render an interactive Pressable root when supplied.
- `onLongPress`: PressableProps['onLongPress']
- `onPressIn`: PressableProps['onPressIn']
- `onPressOut`: PressableProps['onPressOut']
- `onMouseEnter`: () => void — Web pointer entry on the rendered root.
- `onMouseLeave`: () => void — Web pointer exit on the rendered root.
- `disabled`: PressableProps['disabled']
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `translateY`: number — Small visual offset without affecting surrounding layout.
- `rotate`: string — Rotation around the block center, such as `"45deg"`.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `start`: number | string — Start inset (logical: left in LTR, right in RTL)
- `end`: number | string — End inset (logical: right in LTR, left in RTL)
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Build a card with `bg`, `p` and `radius`, share a row with `grow` and a fixed `w`, and render button-style actions with `component`, all on `Block` without custom stylesheets.

```tsx
import { Block, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block w="100%" maw={420}>
      <Block bg="#111827" radius="lg" p="lg">
        <Text fw="semibold" c="white">
          Release summary
        </Text>
        <Text size="sm" c="rgba(255,255,255,0.75)">
          Version 2.4 is live in every region.
        </Text>
      </Block>

      <Block direction="row">
        <Block grow bg="#2563eb" radius="md" p="md">
          <Text fw="semibold" c="white">
            Velocity
          </Text>
          <Text size="sm" c="rgba(255,255,255,0.8)">
            42 points
          </Text>
        </Block>
        <Block w={140} bg="#f9fafb" radius="md" p="md">
          <Text fw="semibold">Backlog</Text>
          <Text size="sm" c="muted">
            18 items
          </Text>
        </Block>
      </Block>

      <Block direction="row">
        <Block component="button" bg="#2563eb" radius="md" px="lg" py="sm">
          <Text c="white" fw="semibold">
            Create project
          </Text>
        </Block>
        <Block
          component="button"
          radius="md"
          px="lg"
          py="sm"
          borderWidth={1}
          borderColor="#2563eb"
        >
          <Text c="#2563eb" fw="semibold">
            View roadmap
          </Text>
        </Block>
      </Block>
    </Block>
  );
}
```

### bg shorthand

`bg` resolves through the theme. Pass a palette name (`'primary'`, `'success'`) for a subtle tint (shade-1), a `'palette.shade'` like `'primary.6'` for a specific shade, a theme-background key (`'surface'`, `'subtle'`, `'elevated'`), or any CSS color string. The same resolver powers `<Card bg=...>`.

```tsx
import { Block, Row, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="sm" wrap="wrap">
      <Block bg="primary" p="sm" radius="md">
        <Text>primary</Text>
      </Block>
      <Block bg="success" p="sm" radius="md">
        <Text>success</Text>
      </Block>
      <Block bg="warning" p="sm" radius="md">
        <Text>warning</Text>
      </Block>
      <Block bg="error" p="sm" radius="md">
        <Text>error</Text>
      </Block>
      <Block bg="primary.6" p="sm" radius="md">
        <Text c="white">primary.6</Text>
      </Block>
      <Block bg="gray.2" p="sm" radius="md">
        <Text>gray.2</Text>
      </Block>
      <Block bg="surface" p="sm" radius="md" borderWidth={1} borderColor="#ddd">
        <Text>surface</Text>
      </Block>
      <Block bg="subtle" p="sm" radius="md">
        <Text>subtle</Text>
      </Block>
      <Block bg="#a855f7" p="sm" radius="md">
        <Text c="white">#a855f7</Text>
      </Block>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Blockquote.md -->

# Blockquote

Blockquote highlights a quotation or important passage.

## Metadata

- Import: `import { Blockquote } from '@plocks/ui';`
- Tags: blockquote, text, typography
- Docs: https://plocks.dev/components/Blockquote
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Blockquote

## Props

- `children` (required): React.ReactNode — Core content
- `variant`: 'default' | 'testimonial' | 'featured' | 'minimal' — Styling
- `size`: SizeValue — Quote text size. Quotes read two steps up the theme's font scale (`md` → `fontSizes.xl`).
- `color`: string
- `quoteIcon`: string | React.ReactNode — Quote icon
- `quoteIconPosition`: 'top-left' | 'top-center' | 'bottom-right' | 'none' — Glyph position. `left` / `right` are the leading / trailing corners (mirrored in RTL).
- `quoteIconSize`: SizeValue — Glyph size token (`lg` = 32px with the default theme) or px.
- `author`: BlockquoteAuthor — Author attribution
- `links`: BlockquoteLinks — Social/profile links
- `date`: Date | string — Metadata
- `rating`: BlockquoteRating
- `source`: BlockquoteSource — Brand/source
- `verified`: boolean — Verification
- `verifiedTooltip`: string
- `alignment`: 'left' | 'center' | 'right' — Layout
- `attributionAlignment`: 'left' | 'center' | 'right' — Which side the attribution block (avatar, name, source, meta) sits on. Defaults to `'right'`, or `'center'` when `alignment` is `'center'`.
- `border`: boolean
- `shadow`: boolean
- `onPress`: () => void — Makes the whole quote a button.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface BlockquoteAuthor {
  name: string;
  title?: string;
  organization?: string;
  /** Remote avatar URL, or a bundled asset from `require('./avatar.png')` */
  avatar?: string | ImageSourcePropType;
  avatarFallback?: string;
}

export interface BlockquoteLinks {
  website?: string;
  twitter?: string;
  linkedin?: string;
  [key: string]: string | undefined;
}

export interface BlockquoteRating {
  value: number;
  max?: number;
  showValue?: boolean;
}

export interface BlockquoteSource {
  name: string;
  /**
   * Icon registry name, or any node — e.g. a logo from `@plocks/brands`:
   * `icon: <BrandIcon brand="x" size="sm" />`.
   */
  icon?: string | React.ReactNode;
  logo?: string;
  url?: string;
}
```

## Examples

### Basics

Frames a simple pull quote with author details.

```tsx
import { Blockquote } from '@plocks/ui';

const AUTHOR = {
  name: 'Jamie Ortega',
  title: 'Principal Product Designer',
};

export function Demo() {
  return (
    <Blockquote author={AUTHOR}>
      The Blockquote component keeps editorial typography consistent so our brand voice always feels elevated.
    </Blockquote>
  );
}
```

### Testimonial card

Full-fidelity testimonial with avatar, organization, rating, verified badge, and shadow.

```tsx
import { Blockquote } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';

export function Demo() {
  return (
    <Blockquote
      variant="testimonial"
      author={{
        name: 'Priya Shah',
        title: 'CTO',
        organization: 'Northwind Labs',
        avatar: require('../../../../assets/avatars/avatar-2.png'),
      }}
      rating={{ value: 5, max: 5, showValue: true }}
      source={{
        name: 'Google Business',
        icon: <BrandIcon brand="google" size="sm" />,
      }}
      date="2024-06-12"
      verified
    >
      plocks helped us ship an entirely new settings experience in a single sprint. The components feel native on every platform.
    </Blockquote>
  );
}
```

### Social proof

Maps social-style quotes into `Blockquote` with avatars, verification, and network metadata.

```tsx
import { Block, Blockquote } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';

export function Demo() {
  return (
    <Block>
      <Blockquote
        variant="minimal"
        author={{
          name: '@futureshaper',
          avatar: require('../../../../assets/avatars/avatar-3.png'),
        }}
        source={{
          name: 'X (Twitter)',
          icon: <BrandIcon brand="x" size="sm" />,
          url: 'https://x.com/plocks_ui',
        }}
        date="3h"
        verified
      >
        The future is going to be wild 🚀
      </Blockquote>

      <Blockquote
        variant="testimonial"
        author={{
          name: 'Jordan Reeves',
          title: 'Developer Advocate',
          avatar: require('../../../../assets/avatars/avatar-1.png'),
        }}
        source={{
          name: 'LinkedIn',
          icon: <BrandIcon brand="linkedin" size="sm" />,
        }}
        date="1 day ago"
      >
        Just finished testing the new plocks UI library. The component quality and developer experience is outstanding!
      </Blockquote>

      <Blockquote
        variant="testimonial"
        author={{
          name: 'Sasha Lin',
          title: 'Staff Engineer',
        }}
        source={{
          name: 'GitHub',
          icon: <BrandIcon brand="github" size="sm" />,
        }}
        rating={{ value: 5, max: 5, showValue: true }}
        verified
      >
        This library has saved us countless hours of development time. Clean API, great documentation, and excellent TypeScript support.
      </Blockquote>
    </Block>
  );
}
```

### Attribution side

Attribution sits on the right by default. Use `attributionAlignment` to move the avatar, name, and metadata to the left or center it under the quote.

```tsx
import { Block, Blockquote, Text } from '@plocks/ui';

import { AUTHOR, QUOTE, SOURCE } from './data';

export function Demo() {
  return (
    <Block>
      <Block>
        <Text variant="h5" fw="semibold">
          Right (default)
        </Text>
        <Blockquote
          variant="testimonial"
          shadow
          author={AUTHOR}
          source={SOURCE}
        >
          {QUOTE}
        </Blockquote>
      </Block>

      <Block>
        <Text variant="h5" fw="semibold">
          Left
        </Text>
        <Blockquote
          variant="testimonial"
          shadow
          attributionAlignment="left"
          author={AUTHOR}
          source={SOURCE}
        >
          {QUOTE}
        </Blockquote>
      </Block>

    </Block>
  );
}
```

`data.ts`

```ts
export const AUTHOR = {
  name: 'Priya Shah',
  title: 'CTO',
  organization: 'Northwind Labs',
  avatar: require('../../../../assets/avatars/avatar-2.png'),
};

export const SOURCE = { name: 'G2', brand: 'google' as const };

export const QUOTE =
  'The components feel native on every platform, so we stopped maintaining three separate design systems.';
```

### Variants overview

Renders each preset to compare layout, alignment, and metadata options.

```tsx
import { Block, Blockquote, Text } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';

export function Demo() {
  return (
    <Block>
      <Block>
        <Text variant="h5" fw="semibold">
          Default
        </Text>
        <Blockquote author={{ name: 'Anonymous' }}>
          The best way to predict the future is to create it.
        </Blockquote>
      </Block>

      <Block>
        <Text variant="h5" fw="semibold">
          Testimonial
        </Text>
        <Blockquote
          variant="testimonial"
          author={{
            name: 'Sarah Johnson',
            title: 'Marketing Director',
            avatar: require('../../../../assets/avatars/avatar-4.png'),
          }}
          rating={{ value: 4, max: 5 }}
          shadow
        >
          Great experience with this service. The team was professional and delivered quality results.
        </Blockquote>
      </Block>

      <Block>
        <Text variant="h5" fw="semibold">
          Featured
        </Text>
        <Blockquote
          variant="featured"
          alignment="center"
          author={{
            name: 'Albert Einstein',
            title: 'Theoretical Physicist',
          }}
        >
          Imagination is more important than knowledge.
        </Blockquote>
      </Block>

      <Block>
        <Text variant="h5" fw="semibold">
          Minimal
        </Text>
        <Blockquote
          variant="minimal"
          quoteIconPosition="none"
          author={{ name: '@username' }}
          source={{ name: 'X (Twitter)', icon: <BrandIcon brand="x" size="sm" /> }}
          date="2 hours ago"
        >
          Just discovered this amazing new feature! 🚀
        </Blockquote>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/BrandButton.md -->

# BrandButton

The BrandButton component renders a branded pressable for any platform in the brand icon registry.

## Metadata

- Import: `import { BrandButton } from '@plocks/brands';`
- Install: `npm install @plocks/brands` — a separate package from `@plocks/ui`
- Tags: action, pressable, interactive, badge, app-store
- Docs: https://plocks.dev/components/BrandButton
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/brands/src/components/BrandButton

## Props

- `brand` (required): BrandPlatform — The brand/platform to style the button for
- `variant`: 'default' | 'filled' | 'light' | 'subtle' | 'secondary' | 'outline' | 'ghost' | 'gradient' | 'link' | 'none' | 'plain' = 'plain' — Visual variant. @default 'plain'
- `iconPosition`: 'left' | 'right' | 'start' | 'end' = 'left' — Side of the label the brand icon sits on (`left`/`right` follow the reading direction).
- `iconVariant`: 'full' | 'mono' — Icon variant: 'full' for multi-color, 'mono' for single-color outline
- `icon`: React.ReactNode — Override the default brand icon
- `title`: string — Button text. Omit when rendering a store badge.
- `color`: string — Override icon color (overrides brand default colors)
- `primaryText`: string — Badge lead-in line, e.g. "Download on the" / "Listen on". Supplying this or `secondaryText` switches the component to the two-line store-badge layout, where `variant`, `loading` and `fullWidth` do not apply.
- `secondaryText`: string — Badge headline, e.g. "App Store" / "Spotify"
- `borderColor`: string — Badge shell border color (badge layout only)
- `darkMode`: boolean — Force the badge's dark-mode styling instead of following the theme
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Button` props (`children` `onPress` `onPressIn` `onPressOut` `onHoverIn` `onHoverOut` `onLongPress` `onLayout` `size` `disabled` `loading` `loadingTitle` `fullWidth` `textColor` `tooltip` `transitionDuration` `accessibilityLabel` `accessibilityHint` `labelProps`): https://plocks.dev/llms/components/Button.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type BrandPlatform = BrandName;
```

## Examples

### Basics

Basic Button usage with a title prop.

```tsx
import { BrandButton } from '@plocks/brands';

export function Demo() {
  return (
    <BrandButton
      brand="google"
      title="Continue with Google"
    />
  );
}
```

### App Store Badges

Built in support for App Store badges

```tsx
import { BrandButton } from '@plocks/brands';
import { Flex } from '@plocks/ui';

export function Demo() {
  return (
    <Flex>
      <BrandButton
        brand="app-store"
        primaryText="Download on the"
        secondaryText="App Store"
      />
      <BrandButton
        brand="google-play"
        primaryText="Get it on"
        secondaryText="Google Play"
      />
    </Flex>
  );
}
```

### Variants

Compare the plain brand treatment with Button-style visual variants.

```tsx
import { Column } from '@plocks/ui';
import { BrandButton } from '@plocks/brands';

const variants = ['plain', 'default', 'filled', 'light', 'outline', 'ghost'] as const;

export function Demo() {
  return (
    <Column gap="sm" align="flex-start">
      {variants.map(variant => (
        <BrandButton key={variant} brand="google" title={`Continue with Google · ${variant}`} variant={variant} />
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/BrandIcon.md -->

# BrandIcon

Common brand logos rendered as SVG.

## Metadata

- Import: `import { BrandIcon } from '@plocks/brands';`
- Install: `npm install @plocks/brands` — a separate package from `@plocks/ui`
- Tags: brand, logo, icon, svg
- Docs: https://plocks.dev/components/BrandIcon
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/brands/src/components/BrandIcon

## Props

- `brand` (required): BrandName — Brand name from the registry.
- `size`: SizeValue = 'md' — Size token or px.
- `color`: string — Override all colors with a single color (brand logos otherwise keep their official colors).
- `variant`: 'full' | 'mono' — Icon variant - 'full' for multi-color, 'mono' for single-color with clipping
- `label`: string — Accessible name. A labelled brand icon is announced as an image; without a label it is decorative (hidden from assistive technology).
- `accessibilityLabel`: string — Alias of `label`.
- `decorative`: boolean — Hide the icon from assistive technology. Defaults to `true` unless a `label` is given — a logo next to (or inside) labelled content adds only noise.
- `invertInDarkMode`: boolean = false — Whether to automatically invert black colors in dark mode
- `colorScheme`: 'light' | 'dark' — Force color scheme for testing (overrides automatic detection)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

High-quality brand icons with multi-color support, mono variants, and automatic dark mode theming.

```tsx
import { Row } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';
import { SAMPLE_BRANDS } from '../data';

export function Demo() {
  return (
    <Row align="center" gap="md" wrap="wrap">
      {SAMPLE_BRANDS.map((brand) => (
        <BrandIcon key={brand} brand={brand} size="xl" />
      ))}
    </Row>
  );
}
```

`data.ts`

```ts
import type { BrandName } from '@plocks/brands';

export const FEATURED_BRANDS: BrandName[] = [
  'google',
  'facebook',
  'apple',
  'github',
  'x',
  'microsoft',
  'linkedin',
  'discord',
  'slack',
  'chrome',
  'openai',
  'spotify',
  'youtube'
];

export const SAMPLE_BRANDS: BrandName[] = FEATURED_BRANDS.slice(0, 6);

export const DARK_MODE_BRANDS: BrandName[] = ['apple', 'github', 'x'];
```

### Colors & Mono

Authentic brand palettes plus custom single-color overrides — passing `color` implies `variant="mono"`, so the two never need to be set together.

```tsx
import { Block, Row, Text } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';

export function Demo() {
  return (
    <Block>
      <Block>
        <Text variant="small" c="secondary">
          Authentic brand palettes
        </Text>
        <Row align="center" gap="md" wrap="wrap">
          <BrandIcon brand="google" size="xl" />
          <BrandIcon brand="facebook" size="xl" />
          <BrandIcon brand="apple" size="xl" />
          <BrandIcon brand="github" size="xl" />
          <BrandIcon brand="x" size="xl" />
        </Row>
      </Block>

      <Block>
        <Text variant="small" c="secondary">
          Custom blue
        </Text>
        <Row align="center" gap="md" wrap="wrap">
          <BrandIcon brand="google" size="xl" color="#1976D2" />
          <BrandIcon brand="facebook" size="xl" color="#1976D2" />
          <BrandIcon brand="apple" size="xl" color="#1976D2" />
          <BrandIcon brand="github" size="xl" color="#1976D2" />
          <BrandIcon brand="x" size="xl" color="#1976D2" />
        </Row>
      </Block>

      <Block>
        <Text variant="small" c="secondary">
          Custom red
        </Text>
        <Row align="center" gap="md" wrap="wrap">
          <BrandIcon brand="google" size="xl" color="#D32F2F" />
          <BrandIcon brand="facebook" size="xl" color="#D32F2F" />
          <BrandIcon brand="apple" size="xl" color="#D32F2F" />
          <BrandIcon brand="github" size="xl" color="#D32F2F" />
          <BrandIcon brand="x" size="xl" color="#D32F2F" />
        </Row>
      </Block>
    </Block>
  );
}
```

### Variants

Full preserves the brand colors; mono uses a single supplied color.

```tsx
import { Column, Row, Text } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';

export function Demo() {
  return (
    <Column gap="md">
      <Row align="center" gap="sm"><BrandIcon brand="google" variant="full" size="xl" /><Text>Full color</Text></Row>
      <Row align="center" gap="sm"><BrandIcon brand="google" variant="mono" color="royalblue" size="xl" /><Text>Monochrome</Text></Row>
    </Column>
  );
}
```

### Sizes

Size presets from small through extra large for consistent placement.

```tsx
import { Block, Row, Text } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';
import type { BrandIconProps } from '@plocks/brands';

const SIZES: BrandIconProps['size'][] = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'];

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={String(size)} align="center">
          <BrandIcon brand="google" size={size} />
          <Text variant="small">{String(size)}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Dark Mode Support

Supported logos automatically invert for dark themes.

```tsx
import { Row } from '@plocks/ui';
import { BrandIcon } from '@plocks/brands';
import { DARK_MODE_BRANDS } from '../data';

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {DARK_MODE_BRANDS.map((brand) => (
        <BrandIcon key={brand} brand={brand} size="xl" />
      ))}
    </Row>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### All Available Brands

Complete collection of every supported brand icon, laid out with `Grid` so the column count adapts from 3 on narrow screens up to 8 on wide ones.

```tsx
import { Block, Grid, GridItem, Text } from '@plocks/ui';
import { BrandIcon, brandNames } from '@plocks/brands';

export function Demo() {
  return (
    <Grid columns={{ base: 3, sm: 4, md: 6, lg: 8 }} gap="md" fullWidth>
      {brandNames.map((brand) => (
        <GridItem key={brand} span={1}>
          <Block align="center">
            <BrandIcon brand={brand} size={36} />
            <Text ta="center" size={10}>
              {brand}
            </Text>
          </Block>
        </GridItem>
      ))}
    </Grid>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Breadcrumbs.md -->

# Breadcrumbs

Breadcrumbs displays the path to the current page as navigation links.

## Metadata

- Import: `import { Breadcrumbs } from '@plocks/ui';`
- Tags: navigation, breadcrumb, path, hierarchy
- Docs: https://plocks.dev/components/Breadcrumbs
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Breadcrumbs

## Props

- `items` (required): BreadcrumbItem[] — Array of breadcrumb items
- `separator`: ReactNode = '/' — Custom separator between breadcrumbs (string, icon, or any React component). Hidden from assistive technology.
- `maxItems`: number — Maximum number of items to show (will collapse middle items)
- `size`: SizeValue = 'md' — Size of the breadcrumbs: a font-size token or a px font size. @default 'md'
- `showIcons`: boolean = true — Whether to show icons
- `textStyle`: StyleProp<TextStyle> — Custom text styles
- `separatorStyle`: StyleProp<ViewStyle> — Custom separator styles
- `accessibilityLabel`: string = 'Breadcrumb' — Accessible name of the navigation landmark. @default 'Breadcrumb'
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to each item's label `<Text>` (style, fw, ff, size, c).
- `separatorProps`: Omit<TextProps, 'children'> — Override props applied to the separator `<Text>` when it's a string.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface BreadcrumbItem {
  /** The label text for the breadcrumb */
  label: string;

  /**
   * The href/path for navigation. On web an item with `href` and no `onPress`
   * renders as a real link; with `onPress`, the press handler does the routing.
   */
  href?: string;

  /** Custom icon to display before the label (decorative) */
  icon?: ReactNode;

  /** Press handler for the breadcrumb item */
  onPress?: () => void;

  /** Whether this breadcrumb is disabled */
  disabled?: boolean;
}
```

## Examples

### Basics

Simple breadcrumb trail showing the current page within a product hierarchy.

```tsx
import { Breadcrumbs } from '@plocks/ui';

const ITEMS = [
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Electronics', href: '/products/electronics' },
  { label: 'Smartphones' },
];

export function Demo() {
  return <Breadcrumbs items={ITEMS} />;
}
```

### Separators

Shows how to replace the default slash with characters or React nodes via the `separator` prop.

```tsx
import { Block, Breadcrumbs, Icon } from '@plocks/ui';

const ITEMS = [
  { label: 'Home', href: '/' },
  { label: 'Category', href: '/category' },
  { label: 'Subcategory', href: '/category/subcategory' },
  { label: 'Product' },
];

export function Demo() {
  return (
    <Block>
      <Breadcrumbs items={ITEMS} />
      <Breadcrumbs items={ITEMS} separator=">" />
      <Breadcrumbs items={ITEMS} separator={<Icon name="chevron-right" size={14} />} />
      <Breadcrumbs items={ITEMS} separator="•" />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Button.md -->

# Button

A flexible interactive button element supporting variants, sizes, icons, loading state, and full-width layout.

## Metadata

- Import: `import { Button } from '@plocks/ui';`
- Tags: action, pressable, interactive
- Docs: https://plocks.dev/components/Button
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Button

## Props

- `title`: string — Button text content - can be provided via title prop or children
- `children`: React.ReactNode — Button text content - alternative to title prop
- `onPress`: () => void — Called when the button is pressed
- `onPressIn`: () => void — Called when the button press starts (for immediate feedback)
- `onPressOut`: () => void — Called when the button press ends
- `onHoverIn`: () => void — Called when the button is hovered (web/desktop only)
- `onHoverOut`: () => void — Called when the button is no longer hovered (web/desktop only)
- `onLongPress`: () => void — Called when the button is long-pressed
- `onLayout`: (event: LayoutChangeEvent) => void — Called when the button layout is calculated
- `variant`: 'default' | 'filled' | 'light' | 'subtle' | 'secondary' | 'outline' | 'ghost' | 'gradient' | 'link' | 'none' = 'default' — Button visual variant. `default` is a neutral button — a recessed fill with a visible border and body text — so an unstyled `<Button>` never claims the accent color. A solid primary fill is opt-in via `filled`.
- `color`: ColorProp — Theme color the button is tinted with. A palette token (`primary`, `success`, `error`, …), `'primary.6'` shade syntax, or any raw CSS/hex color. Applies to the color-bearing variants (`filled`, `light`, `subtle`, `outline`, `gradient`) and to the text of `ghost`/`link`. Defaults to `primary`. `secondary` stays neutral by design.
- `size`: SizeValue — Button size: a size token, or a number (the control height in px).
- `disabled`: boolean — Whether the button is disabled
- `loading`: boolean — Whether button is in loading state (shows loader, sets `aria-busy`)
- `loadingTitle`: string — Text to show when loading (if not provided, shows empty text but maintains original width)
- `fullWidth`: boolean — Whether button should fill the full width of its parent container. Buttons size to their content by default; `fullWidth`, an explicit `w`, or a flex value in `style` makes them fill instead.
- `textColor`: ColorProp — Explicit text color override (else derived automatically from variant & color)
- `icon`: React.ReactNode — Icon to show in the center (for icon-only buttons). Icon-only buttons need an accessible name: pass `accessibilityLabel`, or a `tooltip` (used as the name).
- `startSection`: React.ReactNode — Content (usually an icon) before the label.
- `endSection`: React.ReactNode — Content (usually an icon) after the label.
- `tooltip`: TooltipPropValue — Tooltip shown on hover/focus — wraps the button in a `Tooltip`. Pass a string for the common case, or a config object to tune the tooltip: `tooltip={{ label: 'Long explanation…', maw: 320, withArrow: true }}`. For an icon-only button without `accessibilityLabel`, the tooltip text is also the button's accessible name.
- `transitionDuration`: number = 110 — Length of the press / pulse / hover transitions in ms. `0` applies each state instantly (no scale animation). Always 0 under reduced motion.
- `accessibilityLabel`: string — Accessible name. Defaults to the button's text; icon-only buttons fall back to the tooltip text.
- `accessibilityHint`: string — Accessibility hint for screen readers (native)
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the inner label `<Text>` (style, weight, ff, size, color).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Label a button with `title` (or children) and pass `onPress` to run its action.

```tsx
import { Button } from '@plocks/ui';

export function Demo() {
  return <Button title="Launch mission" />;
}
```

### Colors

Pair `color` with a color-bearing variant (`filled`, `light`, `subtle`, `outline`, `gradient`) to align actions with brand intent. The default variant is neutral chrome and ignores `color`.

```tsx
import { Button, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Button variant="filled" color="primary">Primary</Button>
      <Button variant="filled" color="secondary">Secondary</Button>
      <Button variant="filled" color="success">Success</Button>
      <Button variant="filled" color="warning">Warning</Button>
      <Button variant="filled" color="error">Error</Button>
    </Row>
  );
}
```

### Loading state

Set `loading` to swap the label for a spinner and block presses. Add `loadingTitle` to keep text beside the spinner.

```tsx
import { Button, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Button loading>Submit application</Button>
      <Button loading loadingTitle="Submitting…">
        Submit application
      </Button>
    </Row>
  );
}
```

### Variants

Preview the available button variants to match the desired emphasis level.

```tsx
import { Button, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Button variant="default">Default</Button>
      <Button variant="filled">Filled</Button>
      <Button variant="light">Light</Button>
      <Button variant="subtle">Subtle</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="outline">Outline</Button>
      <Button variant="gradient">Gradient</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="none">Text only</Button>
    </Row>
  );
}
```

### Sizes

Preview the available button size tokens for different density requirements.

```tsx
import { Button, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap" align="flex-end">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
      <Button size="xl">Extra large</Button>
    </Row>
  );
}
```

### Localized labels

Switch locales at runtime and render translated button copy with `useI18n` helpers.

```tsx
import { Button, Flex, Select, useI18n } from '@plocks/ui';

const LOCALES = [
  { label: 'English', value: 'en' },
  { label: 'Español', value: 'es' },
  { label: 'Français', value: 'fr' },
];

export function Demo() {
  const { t, locale, setLocale } = useI18n();

  return (
    <Flex>
      <Select
        options={LOCALES}
        value={locale}
        onChange={(value) => { if (value) setLocale(value); }}
      />
      <Button title={t('button.demo.submit')} />
    </Flex>
  );
}
```

### Tooltips

Add contextual hints to buttons with `tooltip` and optional placement overrides.

```tsx
import { Button, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Button tooltip="Save your current work.">Save</Button>
      <Button tooltip={{ label: 'Permanently delete this item.', position: 'bottom' }}>
        Delete
      </Button>
      <Button tooltip={{ label: 'Download the file to your device.', position: 'left' }}>
        Download
      </Button>
      <Button tooltip={{ label: 'Get help and support resources.', position: 'right' }}>
        Help
      </Button>
    </Row>
  );
}
```

### Width

Buttons hug their label by default. Set `w` to a pixel or percentage width, or `fullWidth` to fill the container.

```tsx
import { Block, Button } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Button>Default width</Button>
      <Button w={200}>Fixed width (200)</Button>
      <Button w="50%">Half width (50%)</Button>
      <Button fullWidth>Full width</Button>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Calendar.md -->

# Calendar

Calendar displays a month grid for choosing dates.

## Metadata

- Import: `import { Calendar } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/Calendar
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/Calendar

## Props

- `level`: 'month' | 'year' | 'decade' — View control
- `defaultLevel`: 'month' | 'year' | 'decade' = 'month'
- `onLevelChange`: (level: CalendarLevel) => void
- `date`: Date — Date management
- `defaultDate`: Date
- `onDateChange`: (date: Date) => void
- `value`: CalendarValue — Value handling (for selection)
- `onChange`: (value: CalendarValue) => void
- `type`: 'single' | 'multiple' | 'range' = 'single'
- `minDate`: Date — Constraints
- `maxDate`: Date
- `excludeDate`: (date: Date) => boolean
- `locale`: string — Locale for month / weekday names and the day cells' accessible names. Default `'en-US'`.
- `firstDayOfWeek`: 0 | 1 | 2 | 3 | 4 | 5 | 6 = 0
- `weekendDays`: number[] = DEFAULT_WEEKEND_DAYS
- `withCellSpacing`: boolean — Display options
- `hideOutsideDates`: boolean = false
- `hideWeekdays`: boolean = false
- `highlightToday`: boolean = true
- `numberOfMonths`: number = 1
- `getDayProps`: (date: Date) => Partial<DayProps> — Customization
- `renderDay`: (date: Date) => React.ReactNode
- `size`: SizeValue = 'md'
- `fullWidth`: boolean = false — Stretch to fill the container instead of sizing to the day grid. Default `false`.
- `static`: boolean — Static mode: the calendar only displays — navigation, day selection, hover previews and keyboard focus are all off.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type CalendarLevel = 'month' | 'year' | 'decade';

export type CalendarValue = Date | Date[] | [Date | null, Date | null] | null;

export interface DayProps
  extends Omit<PressableProps, 'style' | 'children' | 'disabled'> {
  date: Date;

  // States
  selected?: boolean;
  inRange?: boolean;
  firstInRange?: boolean;
  lastInRange?: boolean;
  previewed?: boolean;
  previewedInRange?: boolean;
  previewedFirstInRange?: boolean;
  previewedLastInRange?: boolean;
  weekend?: boolean;
  outside?: boolean;
  today?: boolean;
  disabled?: boolean;

  // Styling
  size?: SizeValue;
  style?: StyleProp<ViewStyle>;

  /** Locale for the cell's accessible name (the full date). Default: the runtime locale. */
  locale?: string;

  // Custom content
  children?: React.ReactNode;
}
```

## Examples

### Basics

Bind `value` and `onChange` to local state to capture the selected day while `highlightToday` keeps the current date visually distinct.

```tsx
import { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { Calendar } from '@plocks/dates';

const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });

export function Demo() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());

  return (
    <Block fullWidth>
      <Calendar
        value={selectedDate}
        onChange={(date) => setSelectedDate(date as Date | null)}
        highlightToday
      />
      <Text size="sm" c="secondary">
        Selected date: {selectedDate ? formatter.format(selectedDate) : 'none'}
      </Text>
    </Block>
  );
}
```

### Date constraints

Set `minDate` and `maxDate` to keep navigation inside the current month while still allowing the calendar to show surrounding weeks.

```tsx
import { useMemo, useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { Calendar } from '@plocks/dates';

const monthFormatter = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });

export function Demo() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());

  const { minDate, maxDate, monthLabel } = useMemo(() => {
    const today = new Date();
    const start = new Date(today.getFullYear(), today.getMonth(), 1);
    const end = new Date(today.getFullYear(), today.getMonth() + 1, 0);
    return { minDate: start, maxDate: end, monthLabel: monthFormatter.format(start) };
  }, []);

  return (
    <Block fullWidth>
      <Calendar
        value={selectedDate}
        onChange={(date) => setSelectedDate(date as Date | null)}
        minDate={minDate}
        maxDate={maxDate}
        highlightToday
      />
      <Text size="sm" c="secondary">
        Selected date: {selectedDate ? dateFormatter.format(selectedDate) : 'none'}
      </Text>
      <Text size="xs" c="secondary">
        Only dates in {monthLabel} are enabled.
      </Text>
    </Block>
  );
}
```

### Multiple selection

Switch `type="multiple"` to let teammates flag several event days at once; the component returns an array you can format for summaries or badges.

```tsx
import { useMemo, useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { Calendar } from '@plocks/dates';

const formatter = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' });

export function Demo() {
  const [selectedDates, setSelectedDates] = useState<Date[]>([]);

  const summary = useMemo(() => {
    if (selectedDates.length === 0) return 'No dates picked yet.';
    if (selectedDates.length === 1) {
      return `1 date picked: ${formatter.format(selectedDates[0])}`;
    }
    return `${selectedDates.length} dates picked: ${selectedDates.map((date) => formatter.format(date)).join(', ')}`;
  }, [selectedDates]);

  return (
    <Block fullWidth>
      <Calendar
        type="multiple"
        value={selectedDates}
        onChange={(dates) => setSelectedDates(dates as Date[])}
        highlightToday
      />
      <Text size="sm" c="secondary">
        {summary}
      </Text>
    </Block>
  );
}
```

### Range selection

Use `type="range"` to capture a start and end date for bookings or sprints; the component returns a tuple you can translate into summaries or validation.

```tsx
import { useMemo, useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { Calendar } from '@plocks/dates';

const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });

export function Demo() {
  const [selectedRange, setSelectedRange] = useState<[Date | null, Date | null]>([null, null]);

  const summary = useMemo(() => {
    const [start, end] = selectedRange;
    if (!start) {
      return 'No dates selected yet.';
    }
    if (!end) {
      return `Start date chosen: ${formatter.format(start)} — pick an end date.`;
    }
    return `${formatter.format(start)} → ${formatter.format(end)}`;
  }, [selectedRange]);

  return (
    <Block fullWidth>
      <Calendar
        type="range"
        value={selectedRange}
        onChange={(range) => setSelectedRange(range as [Date | null, Date | null])}
        highlightToday
      />
      <Text size="sm" c="secondary">
        {summary}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Card.md -->

# Card

The Card component provides a flexible container for displaying content.

## Metadata

- Import: `import { Card } from '@plocks/ui';`
- Tags: card, container, content, layout
- Docs: https://plocks.dev/components/Card
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Card

## Props

- `children`: React.ReactNode — children optional to reduce noisy TS errors during composition
- `variant`: 'outline' | 'filled' | 'elevated' | 'subtle' | 'ghost' | 'gradient' — Visual variant. Each variant sets its own background + default shadow. - `filled` (default) — surface background - `outline` — transparent + border - `elevated` — surface with a stronger shadow - `subtle` — subtle background + soft border - `ghost` — transparent until pressed - `gradient` — primary-palette gradient overlay
- `withBorder`: boolean — Add a 1px border on top of *any* variant. Composes with `variant="elevated"` etc. without forcing you into the `outline` variant.
- `borderColor`: string — Custom border color. When set, implies `withBorder` if `borderWidth` isn't 0.
- `borderWidth`: number — Custom border width in px. Defaults to 1 when `withBorder` or `borderColor` is set.
- `flex`: number — Layout of a card in a flex row or positioned board.
- `shrink`: number
- `position`: ViewStyle['position']
- `top`: ViewStyle['top']
- `left`: ViewStyle['left']
- `zIndex`: number
- `borderTopWidth`: number
- `borderTopColor`: string
- `borderStyle`: ViewStyle['borderStyle']
- `clip`: boolean — Clip children to the card's radius. Turn this on when a `Card.Section` carries full-bleed content (image, code surface) that would otherwise square off the card's rounded corners. Off by default so overlays that escape the card — menus, popovers, tooltips — keep working.
- `padding`: SizeValue — Internal padding. Accepts a size token (`'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'`) or a pixel number.
- `onPress`: () => void — Makes the card a button (or the given `role`); it is focusable and activates with Enter/Space on web.
- `disabled`: boolean — Disables `onPress` and marks the card `aria-disabled`.
- `onContextMenu`: (event: WebMouseEvent) => void — Web-only: context-menu (right-click) handler.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Compose card content with spacing primitives and a primary action for quick scenarios.

```tsx
import { Block, Button, Card, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Card p="lg" radius="lg" shadow="md" maw={320}>
      <Block>
        <Block>
          <Text variant="small" c="muted">
            Upcoming match
          </Text>
          <Text variant="h6">Falcons at Bears</Text>
        </Block>
        <Text c="muted">
          Kickoff is set for 7:30 PM with rain in the forecast. Review the lineup and
          travel logistics before departure.
        </Text>
        <Button size="sm" variant="filled">
          View itinerary
        </Button>
      </Block>
    </Card>
  );
}
```

### Variants

Tour the available card `variant` treatments to pick the right surface style for your layout.

```tsx
import { Block, Card, Text } from '@plocks/ui';

const VARIANTS = ['filled', 'outline', 'elevated', 'subtle', 'ghost', 'gradient'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {VARIANTS.map((variant) => (
        <Card key={variant} variant={variant} p="lg" radius="lg">
          <Text c={variant === 'gradient' ? 'white' : undefined}>{variant}</Text>
        </Card>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Carousel.md -->

# Carousel

The Carousel component displays a series of content in a horizontal scrollable view with optional navigation dots and controls.

## Metadata

- Import: `import { Carousel } from '@plocks/carousel';`
- Install: `npm install @plocks/carousel` — a separate package from `@plocks/ui`
- Tags: carousel, slider, gallery, swipe
- Docs: https://plocks.dev/components/Carousel
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/carousel/src/components/Carousel

## Props

- `children` (required): React.ReactNode[] — Array of carousel slide elements
- `orientation`: 'horizontal' | 'vertical' — Orientation of the carousel
- `showArrows`: boolean — Show navigation arrow buttons
- `showDots`: boolean — Show navigation dots
- `autoPlay`: boolean — Advance slides automatically. A pause / play button is shown whenever autoplay is on; autoplay pauses while the carousel is hovered or has focus, and starts paused when the user prefers reduced motion (they can press play).
- `autoPlayInterval`: number — Autoplay interval in ms
- `autoPlayPauseOnTouch`: boolean = true — Pause autoplay while the carousel is being touched. @default true
- `loop`: boolean — Enable looping
- `itemsPerPage`: number — Number of visible items per page
- `slidesToScroll`: number — Number of slides to advance per snap (defaults to itemsPerPage for backwards compatibility)
- `align`: 'start' | 'center' | 'end' — Align the visible slides within the viewport when there is extra space
- `containScroll`: false | 'trimSnaps' | 'keepSnaps' — Contain leading/trailing space by trimming or keeping snap points
- `startIndex`: number — Initial slide index to show on mount
- `dragFree`: boolean — Allow momentum scrolling without forced snaps
- `skipSnaps`: boolean — Permit gestures to skip over multiple snap points (default true)
- `dragThreshold`: number — Drag distance (in px) required before a swipe is committed
- `duration`: number — Duration (ms) for programmatic scroll animations
- `transitionDuration`: number — Slide transition length in ms. Cross-component spelling that takes precedence over `duration`; `0` jumps between slides with no animation (and also stills the pagination dots).
- `breakpoints`: Record<string, Partial<CarouselProps>> — Embla-style breakpoint overrides applied via media queries
- `slideSize`: number | string | { base?: number | string; xs?: number | string; sm?: number | string; md?: number | string; lg?: number | string; xl?: number | string; } — Explicit slide size. Accepts: - percentage string: e.g. "70%" - fraction (0..1) number: 0.7 -> 70% of container - absolute pixel number (>1) When provided it overrides width derived from itemsPerPage. itemsPerPage still controls cloning + pagination grouping.
- `slideGap`: ResponsiveSize — Responsive gap between slides (overrides itemGap). Accepts spacing token string or number or responsive map.
- `itemGap`: number — Gap between slides in pixels
- `h`: number = 200 (horizontal) — Height of the slides in px — the dots below them are extra. A vertical carousel's dots sit beside the slides, so there it sizes the root.
- `onSlideChange`: (index: number) => void — Callback fired when the active slide changes
- `accessibilityLabel`: string = 'Carousel' — Accessible name of the carousel region. @default 'Carousel'
- `itemStyle`: StyleProp<ViewStyle> — Style override applied to each slide item
- `snapToItem`: boolean — Enable snapping to individual items
- `arrowPosition`: 'inside' | 'outside' = 'inside' — Arrows over the slides (`inside`) or beside them (`outside`, which insets the slides to make room). @default 'inside'
- `arrowSize`: ComponentSizeValue — Size of the navigation arrow buttons
- `dotSize`: ComponentSizeValue — Size of the navigation dots
- `scrollEnabled`: boolean = true — Enable or disable swipe gestures (arrows, dots and autoplay still work). @default true
- `reducedMotion`: boolean — Shorten slide transitions and keep autoplay paused. Defaults to the user's reduced-motion preference (`useReducedMotion()`); pass a boolean to override.
- `windowSize`: number — Number of logical pages to render for virtualization
- `w`: DimensionProp — Width
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Enable `autoPlay` and `loop` on `Carousel` to rotate a small set of slides without custom pagination controls.

```tsx
import { Block, Text } from '@plocks/ui';
import { Carousel } from '@plocks/carousel';

const slides = ['#4C1D95', '#155E75', '#166534'];

export function Demo() {
  return (
    <Carousel h={200} loop autoPlay autoPlayInterval={4500} showDots>
      {slides.map((bg, index) => (
        <Block key={bg} bg={bg} radius="lg" h="full" align="center" justify="center">
          <Text variant="h3" c="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Vertical orientation

Set `orientation="vertical"` to rotate content along the Y-axis while keeping arrow and dot controls aligned for keyboard and touch users. Vertical carousels size to their container, so give the carousel an explicit `h`.

```tsx
import { Block, Text } from '@plocks/ui';
import { Carousel } from '@plocks/carousel';

const slides = ['#DC2626', '#2563EB', '#0F766E'];

export function Demo() {
  return (
    <Carousel
      orientation="vertical"
      h={280}
      loop
      autoPlay
      autoPlayInterval={4500}
      showArrows
      showDots
    >
      {slides.map((bg, index) => (
        <Block key={bg} bg={bg} radius="lg" h="full" align="center" justify="center">
          <Text variant="h3" c="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Image overlay

Layer an absolutely positioned `Block` with a semi-transparent `bg` on top of each slide to keep text and buttons readable on photography.

```tsx
import { Block, Image, Text } from '@plocks/ui';
import { Carousel } from '@plocks/carousel';

const scenes = [
  { title: 'Mountain escape', src: require('../../../../assets/images/scene-mountains.png') },
  { title: 'Forest retreat', src: require('../../../../assets/images/scene-forest.png') },
  { title: 'Desert journey', src: require('../../../../assets/images/scene-desert.png') },
];

export function Demo() {
  return (
    <Carousel h={280} loop showArrows showDots>
      {scenes.map(({ title, src }) => (
        <Block key={title} h="full" radius="lg" style={{ overflow: 'hidden' }}>
          <Image src={src} w="100%" h="100%" resizeMode="cover" />
          <Block
            position="absolute"
            top={0}
            right={0}
            bottom={0}
            left={0}
            bg="rgba(15,23,42,0.45)"
            p="lg"
            justify="flex-end"
          >
            <Text variant="h3" c="white">
              {title}
            </Text>
          </Block>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Multiple slides

Combine `itemsPerPage` with the Embla-style `breakpoints` prop to show more slides as the viewport grows. Keep `slidesToScroll={1}` so only one card advances at a time, even when desktop layouts show multiple slides side-by-side.

```tsx
import { Block, Text } from '@plocks/ui';
import { Carousel } from '@plocks/carousel';

const slides = ['#1D4ED8', '#0F766E', '#C026D3', '#B45309', '#7C3AED'];

export function Demo() {
  return (
    <Carousel
      h={180}
      loop
      showDots
      slideGap={12}
      itemsPerPage={1}
      slidesToScroll={1}
      breakpoints={{
        '@media (min-width: 768px)': { itemsPerPage: 2 },
        '@media (min-width: 1200px)': { itemsPerPage: 4 },
      }}
    >
      {slides.map((bg, index) => (
        <Block key={bg} bg={bg} radius="lg" h="full" align="center" justify="center">
          <Text variant="h4" c="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Performance tuning

Pair `windowSize` with `reducedMotion` to keep large or data-heavy carousels responsive while still exposing arrow navigation.

```tsx
import { Block, Text } from '@plocks/ui';
import { Carousel } from '@plocks/carousel';

const slides = ['#1E3A8A', '#047857', '#9333EA', '#B91C1C', '#B45309', '#0F766E'];

export function Demo() {
  return (
    <Carousel h={180} loop showArrows windowSize={3} reducedMotion slideGap={12}>
      {slides.map((bg, index) => (
        <Block key={bg} bg={bg} radius="lg" h="full" align="center" justify="center">
          <Text variant="h4" c="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Drag & motion

Tune the interaction model with `dragFree`, `skipSnaps`, `dragThreshold`, and `duration` to match Embla-style motion control.

```tsx
import { Block, Text } from '@plocks/ui';
import { Carousel } from '@plocks/carousel';

function slides(colors: string[]) {
  return colors.map((bg, index) => (
    <Block key={bg} bg={bg} radius="lg" h="full" align="center" justify="center">
      <Text variant="h4" c="white">
        Slide {index + 1}
      </Text>
    </Block>
  ));
}

export function Demo() {
  return (
    <Block fullWidth gap="lg">
      <Text variant="h5">Free momentum (dragFree)</Text>
      <Carousel h={160} dragFree itemsPerPage={2} slideGap={12}>
        {slides(['#0EA5E9', '#6366F1', '#8B5CF6', '#A855F7'])}
      </Carousel>

      <Text variant="h5">Locked snaps (skipSnaps off)</Text>
      <Carousel
        h={160}
        itemsPerPage={2}
        slidesToScroll={1}
        skipSnaps={false}
        dragThreshold={45}
        duration={650}
        slideGap={12}
      >
        {slides(['#F97316', '#EA580C', '#C2410C', '#9A3412'])}
      </Carousel>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Cascader.md -->

# Cascader

Only leaves are selected by default. Set `changeOnSelect` to allow intermediate levels.

## Metadata

- Import: `import { Cascader } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Cascader
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Cascader

## Props

- `data` (required): CascaderOption[]
- `value`: string[] | null
- `defaultValue`: string[] | null
- `onChange`: (path: string[] | null, options: CascaderOption[]) => void
- `placeholder`: string = 'Select…'
- `changeOnSelect`: boolean = false
- `allowDeselect`: boolean = true
- `closeOnSelect`: boolean = !allowDeselect
- `expandTrigger`: 'click' | 'hover' = 'click'
- `safeAreaPolygon`: boolean | { buffer?: number } = true — Protect diagonal pointer travel into the child column; buffer is in pixels. @default true
- `withColumns`: boolean = true
- `maxDisplayedLevels`: number = 3
- `previousLevelsControlLabel`: string = 'Previous levels'
- `nextLevelsControlLabel`: string = 'Next levels'
- `searchable`: boolean = false
- `filter`: (query: string, path: CascaderOption[]) => boolean
- `renderSearchOption`: (path: CascaderOption[]) => React.ReactNode
- `searchValue`: string
- `defaultSearchValue`: string
- `onSearchChange`: (query: string) => void
- `nothingFoundMessage`: React.ReactNode = 'Nothing found'
- `openOnFocus`: boolean = false
- `separator`: string = ' / '
- `formatValue`: (path: CascaderOption[]) => string
- `columnWidth`: number = 180
- `maxDropdownHeight`: number = 260
- `renderOption`: (option: CascaderOption, level: number) => React.ReactNode
- `withCheckIcon`: boolean = true
- `checkIconPosition`: 'start' | 'end' = 'end'
- `clearable`: boolean = false
- `dropdownOpened`: boolean
- `defaultDropdownOpened`: boolean
- `onDropdownOpen`: () => void
- `onDropdownClose`: () => void
- `position`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom-start'
- `offset`: number = 6
- `dropdownWidth`: number | 'target' = 'target'
- `startSection`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface CascaderOption { value: string; label?: string; children?: CascaderOption[]; disabled?: boolean }
```

## Examples

### Basics

Drill through columns to select a city, or search the full path.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" placeholder="Choose a city" data={data} searchable />
    </Block>
  );
}
```

### Flat Paths

`withColumns={false}` lists full paths in one column.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} withColumns={false} />
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on Cascader.

```tsx
import { Column, Cascader } from '@plocks/ui';

const options = [{ value: 'us', label: 'United States', children: [{ value: 'nyc', label: 'New York' }] }];

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <Cascader key={variant} variant={variant} label={`${variant} variant`} data={options} placeholder="Choose a city" />
      ))}
    </Column>
  );
}
```

### Select Intermediate Levels

`changeOnSelect` allows a parent path to be selected.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} changeOnSelect />
    </Block>
  );
}
```

### Hover Expansion

`expandTrigger="hover"` opens the next column on hover. `safeAreaPolygon` keeps that column open during diagonal pointer travel.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} expandTrigger="hover" />
    </Block>
  );
}
```

### Maximum Displayed Levels

`maxDisplayedLevels` limits the simultaneous columns.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader
        label="Location"
        data={data}
        maxDisplayedLevels={2}
        defaultValue={['europe', 'france', 'paris']}
      />
    </Block>
  );
}
```

### Search Paths

Search switches to a list of matching full paths.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} searchable />
    </Block>
  );
}
```

### Nothing Found

Search displays a fallback when there are no matches.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader
        label="Location"
        data={data}
        searchable
        nothingFoundMessage="No matching locations"
      />
    </Block>
  );
}
```

### Formatted Value

`formatValue` customizes the selected path shown in the trigger.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader
        label="Location"
        data={data}
        defaultValue={['europe', 'france', 'paris']}
        formatValue={(path) => path.map((item) => item.label).join(' → ')}
      />
    </Block>
  );
}
```

### Column Width

`columnWidth` changes the width of each level.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} columnWidth={220} />
    </Block>
  );
}
```

### Clearable

`clearable` adds a control to remove the selected path.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader
        label="Location"
        data={data}
        defaultValue={['europe', 'france', 'paris']}
        clearable
      />
    </Block>
  );
}
```

### Disabled Options

Disabled options stay visible but cannot be selected.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      { value: 'france', label: 'France', disabled: true },
      { value: 'germany', label: 'Germany' },
    ],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} />
    </Block>
  );
}
```

### Custom Option

`renderOption` customizes each column entry.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader
        label="Location"
        data={data}
        renderOption={(option) => `${option.label ?? option.value} →`}
      />
    </Block>
  );
}
```

### Read Only

A read-only field displays its path without opening.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader
        label="Location"
        data={data}
        readOnly
        defaultValue={['europe', 'france', 'paris']}
      />
    </Block>
  );
}
```

### Error State

`error` links validation feedback to the field.

```tsx
import { Block, Cascader } from '@plocks/ui';

const data = [
  {
    value: 'europe',
    label: 'Europe',
    children: [
      {
        value: 'france',
        label: 'France',
        children: [
          { value: 'paris', label: 'Paris' },
          { value: 'lyon', label: 'Lyon' },
        ],
      },
    ],
  },
  {
    value: 'asia',
    label: 'Asia',
    children: [{ value: 'japan', label: 'Japan', children: [{ value: 'tokyo', label: 'Tokyo' }] }],
  },
];
export function Demo() {
  return (
    <Block fullWidth>
      <Cascader label="Location" data={data} error="Choose a location" />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Checkbox.md -->

# Checkbox

Checkbox lets users select options individually or in a group.

## Metadata

- Import: `import { Checkbox } from '@plocks/ui';`
- Tags: checkbox, input, form, selection, toggle
- Docs: https://plocks.dev/components/Checkbox
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Checkbox

## Props

- `checked`: boolean — Controlled checked state.
- `defaultChecked`: boolean = false — Initial checked state for uncontrolled usage.
- `onChange`: (checked: boolean) => void — Called with the next checked state.
- `indeterminate`: boolean = false — Mixed state for partial selections (`aria-checked="mixed"`). Pressing it checks the box.
- `color`: ThemeColor — Indicator color: a palette token (`'success'`), `'primary.6'` shade syntax, or any CSS color.
- `icon`: React.ReactNode — Icon shown when checked.
- `indeterminateIcon`: React.ReactNode — Icon shown when indeterminate.
- `labelPosition`: CheckboxLabelPosition = 'right' — Label position relative to the box. `left` / `right` follow the reading direction (`right` = after the box). Default `'right'`.
- `transitionDuration`: number = 160 — Length of the check/uncheck animation in ms; the fill and mark phases scale against it. `0` applies the state instantly. Always 0 under reduced motion.
- `children`: React.ReactNode — Label content (alternative to `label`; wins when both are set).
- `id`: string — Base id: the control gets it, the label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type CheckboxLabelPosition = ChoiceLabelPosition;
```

## Examples

### Basics

Controlled checkbox example with a helper message that reacts to user selection.

```tsx
import { useState } from 'react';
import { Block, Checkbox } from '@plocks/ui';

export function Demo() {
  const [checked, setChecked] = useState(false);

  return (
    <Block w={600}>
      <Checkbox
        label="Accept terms and conditions"
        description={checked ? 'Thanks! You can proceed to the next step.' : 'Check the box to continue.'}
        checked={checked}
        onChange={setChecked}
      />
    </Block>
  );
}
```

### Sizes

Choose a `size` token (`xs` through `3xl`) to scale the checkbox.

```tsx
import { Block, Checkbox, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Checkbox accessibilityLabel={`Checkbox ${size}`} size={size} defaultChecked />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Colors

Pass a semantic `color` token (`primary`, `secondary`, `success`, `warning`, `error`) to match the checkbox accent to the message intent.

```tsx
import { Block, Checkbox } from '@plocks/ui';

const COLORS = ['primary', 'secondary', 'success', 'warning', 'error'] as const;

export function Demo() {
  return (
    <Block>
      {COLORS.map((color) => (
        <Checkbox key={color} color={color} label={color} defaultChecked />
      ))}
    </Block>
  );
}
```

### States

Highlight enabled, disabled, required, and error states to cover validation scenarios.

```tsx
import { Block, Checkbox } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Checkbox label="Enabled" defaultChecked />
      <Checkbox label="Disabled" disabled />
      <Checkbox label="Required" required defaultChecked />
      <Checkbox label="With error" error="Selection required" />
    </Block>
  );
}
```

### Indeterminate

Demonstrates a parent checkbox that toggles a group and reflects partial selection with `indeterminate`.

```tsx
import { useState } from 'react';
import { Block, Checkbox } from '@plocks/ui';

const ITEMS = [
  { id: 1, label: 'Email notifications' },
  { id: 2, label: 'SMS alerts' },
  { id: 3, label: 'Push notifications' },
];

export function Demo() {
  const [selected, setSelected] = useState<number[]>([1]);
  const allIds = ITEMS.map((item) => item.id);
  const allChecked = selected.length === ITEMS.length;
  const someChecked = selected.length > 0 && !allChecked;

  const toggleAll = () => {
    setSelected((current) => (current.length === ITEMS.length ? [] : allIds));
  };

  const toggleItem = (id: number) => {
    setSelected((current) =>
      current.includes(id) ? current.filter((itemId) => itemId !== id) : [...current, id]
    );
  };

  return (
    <Block>
      <Checkbox
        label="Select all"
        checked={allChecked}
        indeterminate={someChecked}
        onChange={toggleAll}
      />
      <Block pl="md">
        {ITEMS.map(({ id, label }) => (
          <Checkbox
            key={id}
            label={label}
            checked={selected.includes(id)}
            onChange={() => toggleItem(id)}
          />
        ))}
      </Block>
    </Block>
  );
}
```

### Descriptions

Use `description` for supporting copy under the label, and pair it with `error` to surface validation details.

```tsx
import { Block, Checkbox } from '@plocks/ui';

export function Demo() {
  return (
    <Block style={{ maxWidth: 400 }}>
      <Checkbox
        label="Receive product updates"
        description="Get occasional emails about new features and improvements."
      />
      <Checkbox
        label="Accept terms of service"
        description="Required before creating an account."
        error="Please accept to continue."
        required
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Chip.md -->

# Chip

Chip displays a compact item that can represent a value, choice, or action.

## Metadata

- Import: `import { Chip } from '@plocks/ui';`
- Tags: chip, tag, badge, label, removable
- Docs: https://plocks.dev/components/Chip
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Chip

## Props

- `children` (required): React.ReactNode
- `size`: SizeValue — Size token; the chip renders one step smaller than a control of the same size.
- `variant`: 'filled' | 'outline' | 'light' | 'subtle' | 'surface' | 'gradient' — Visual style (of the checked state, for a selectable chip). `surface` is the neutral option — it fills from the theme's background tokens instead of the `color` palette, sitting one step darker than the surface behind it (input tokens, filter pills). Ignores `color`.
- `color`: ColorProp — Theme palette name, `'primary.6'` shade syntax, or CSS color. Not used by the `surface` variant.
- `onPress`: () => void — Makes the chip a button.
- `pressed`: boolean — Pressed state for a button chip, exposed as `aria-pressed` on web.
- `checked`: boolean — Checked state. Setting `checked`, `defaultChecked` or `onChange` makes the chip selectable: a checkbox (`aria-checked`) that toggles on press.
- `defaultChecked`: boolean — Initial checked state (uncontrolled selectable chip).
- `onChange`: (checked: boolean) => void — Called with the next checked state when a selectable chip is pressed.
- `uncheckedVariant`: 'filled' | 'outline' | 'light' | 'subtle' | 'surface' | 'gradient' = 'outline' — Variant of an unchecked selectable chip. @default 'outline'
- `dot`: boolean — Show a small leading status dot. Defaults to the chip's resolved text color.
- `dotColor`: ColorProp — Override the dot color (any CSS/theme color string). Only used when `dot` is set.
- `startSection`: React.ReactNode — Content (usually an icon) before the label.
- `endSection`: React.ReactNode — Content (usually an icon) after the label.
- `onRemove`: () => void — Show a remove (×) button that calls this.
- `removePosition`: 'left' | 'right' — Which side the remove button sits on (`left`/`right` follow the reading direction).
- `removeButtonLabel`: string = `Remove <label>` — Accessible name of the remove button. @default `Remove <label>`
- `disabled`: boolean
- `textStyle`: StyleProp<TextStyle>
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the inner label `<Text>` (style, fw, ff, size, c).
- `radius`: RadiusValue = 'full' — Corner radius. @default 'full'
- `shadow`: ShadowToken — Drop shadow token. Chips are flat by default.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Wrap any label in a Chip to render a compact tag — the default `filled` variant and `primary` color apply automatically.

```tsx
import { Chip, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Chip>Design</Chip>
      <Chip>Engineering</Chip>
      <Chip>Research</Chip>
    </Row>
  );
}
```

### Semantic colors

Map the `color` prop to semantic tokens like `primary`, `success`, `warning`, `error`, or `gray` so Chips inherit your design system palette without inline styles.

```tsx
import { Chip, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Chip color="primary">Primary</Chip>
      <Chip color="success">Success</Chip>
      <Chip color="warning">Warning</Chip>
      <Chip color="error">Error</Chip>
      <Chip color="gray">Gray</Chip>
    </Row>
  );
}
```

### Size scale

Select a `size` from `xs` through `3xl` to match the Chip density with the surrounding controls.

```tsx
import { Block, Chip, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Chip size={size}>Chip</Chip>
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Variant styles

Choose a `variant` such as `filled`, `outline`, `light`, `subtle`, or `gradient` to adjust visual weight without changing the Chip label or color. `surface` is the neutral option: it fills from the theme's background tokens instead of the `color` palette, landing one step darker than whatever it sits on in both light and dark. That recessed read makes it the right pick for input tokens, filter pills, and other chrome that shouldn't look like a status color.

```tsx
import { Chip, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Chip variant="filled">Filled</Chip>
      <Chip variant="outline">Outline</Chip>
      <Chip variant="light">Light</Chip>
      <Chip variant="subtle">Subtle</Chip>
      <Chip variant="surface">Surface</Chip>
      <Chip variant="gradient">Gradient</Chip>
    </Row>
  );
}
```

### Status dot

Add a leading status dot with the `dot` prop. It defaults to the chip's resolved text color; override it with `dotColor`.

```tsx
import { Block, Chip, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Row gap="xs" wrap="wrap" align="center">
        <Chip variant="filled" color="success" dot>Active</Chip>
        <Chip variant="light" color="warning" dot>Pending</Chip>
        <Chip variant="outline" color="error" dot>Failed</Chip>
        <Chip variant="subtle" color="gray" dot>Draft</Chip>
      </Row>
      <Row gap="xs" wrap="wrap" align="center">
        <Chip variant="light" color="gray" dotColor="#22C55E" dot>Online</Chip>
        <Chip variant="light" color="gray" dotColor="#F59E0B" dot>Away</Chip>
        <Chip variant="light" color="gray" dotColor="#EF4444" dot>Busy</Chip>
      </Row>
    </Block>
  );
}
```

### Shadow depth

Use the `shadow` prop from `none` to `xl` when a Chip needs extra elevation to stand out from nearby content.

```tsx
import { Chip, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap={8} wrap="wrap">
      <Chip shadow="none">No Shadow</Chip>
      <Chip shadow="xs">XS Shadow</Chip>
      <Chip shadow="sm">SM Shadow</Chip>
      <Chip shadow="md">MD Shadow</Chip>
      <Chip shadow="lg">LG Shadow</Chip>
      <Chip shadow="xl">XL Shadow</Chip>
    </Row>
  );
}
```

### Removable tags

Provide an `onRemove` handler to turn Chips into editable tags; the component renders a dismiss icon and calls your callback with no extra wiring.

```tsx
import { useState } from 'react';
import { Chip, Row } from '@plocks/ui';

export function Demo() {
  const [tags, setTags] = useState(['Soccer', 'Basketball', 'Tennis']);

  return (
    <Row gap={8} wrap="wrap">
      {tags.map((tag) => (
        <Chip key={tag} onRemove={() => setTags((current) => current.filter((t) => t !== tag))}>
          {tag}
        </Chip>
      ))}
    </Row>
  );
}
```

### Selectable

Pass `checked` + `onChange` (or `defaultChecked`) to make chips selectable. Each chip is a checkbox for assistive technology (`aria-checked`, Space toggles); unchecked chips render in `uncheckedVariant` (`outline` by default).

```tsx
import { useState } from 'react';
import { Chip, Row, Text, Block } from '@plocks/ui';

const TOPICS = ['React', 'React Native', 'Expo', 'TypeScript'];

export function Demo() {
  const [selected, setSelected] = useState<string[]>(['Expo']);

  const toggle = (topic: string) =>
    setSelected((current) => (current.includes(topic) ? current.filter((t) => t !== topic) : [...current, topic]));

  return (
    <Block>
      <Row gap="sm" wrap="wrap">
        {TOPICS.map((topic) => (
          <Chip key={topic} checked={selected.includes(topic)} onChange={() => toggle(topic)}>
            {topic}
          </Chip>
        ))}
      </Row>
      <Text size="xs" c="secondary">
        Selected: {selected.join(', ') || 'none'}
      </Text>
    </Block>
  );
}
```

### Theme Matrix

```tsx
import { Block, Card, Chip, DARK_THEME, DEFAULT_THEME, PlocksProvider, Row, Text } from '@plocks/ui';
import type { ChipProps } from '@plocks/ui';

const VARIANTS: NonNullable<ChipProps['variant']>[] = ['filled', 'outline', 'light', 'subtle', 'gradient'];

const ROWS = [
  { color: 'primary', label: 'Primary' },
  { color: 'secondary', label: 'Secondary' },
  { color: 'success', label: 'Success' },
  { color: 'warning', label: 'Warning' },
  { color: 'error', label: 'Error' },
  { color: 'gray', label: 'Gray' },
  { color: '#7C3AED', label: 'Custom' },
];

const LABEL_W = 78;
const CELL_W = 104;

function Matrix() {
  return (
    <Block>
      <Row gap="xs" align="center">
        <Text style={{ width: LABEL_W }}> </Text>
        {VARIANTS.map((variant) => (
          <Text key={variant} size="xs" c="muted" ta="center" style={{ width: CELL_W }}>
            {variant}
          </Text>
        ))}
      </Row>

      {ROWS.map(({ color, label }) => (
        <Row key={color} gap="xs" align="center">
          <Text size="xs" c="muted" style={{ width: LABEL_W }}>
            {label}
          </Text>
          {VARIANTS.map((variant) => (
            <Row key={variant} justify="center" style={{ width: CELL_W }}>
              <Chip variant={variant} color={color} size="sm">
                {label}
              </Chip>
            </Row>
          ))}
        </Row>
      ))}
    </Block>
  );
}

function Panel({ theme, title }: { theme: typeof DEFAULT_THEME; title: string }) {
  return (
    <PlocksProvider theme={theme} inherit={false}>
      <Card
        withBorder
        padding="lg"
        radius="lg"
        style={{ flexGrow: 1, flexShrink: 1, flexBasis: 380, minWidth: 300 }}
      >
        <Block fullWidth>
          <Text fw="600">{title}</Text>
          <Matrix />
        </Block>
      </Card>
    </PlocksProvider>
  );
}

export function Demo() {
  return (
    <Row gap="md" wrap="wrap" align="stretch">
      <Panel theme={DEFAULT_THEME} title="Light surface" />
      <Panel theme={DARK_THEME} title="Dark surface" />
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/CodeBlock.md -->

# CodeBlock

CodeBlock displays source code with syntax highlighting and optional copy controls.

## Metadata

- Import: `import { CodeBlock } from '@plocks/code';`
- Install: `npm install @plocks/code` — a separate package from `@plocks/ui`
- Tags: code, syntax, formatting, developer, github
- Docs: https://plocks.dev/components/CodeBlock
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/code/src/components/CodeBlock

## Props

- `language`: string = 'tsx' — Optional language for syntax highlighting
- `children`: string — Source to display. Optional when `files` is provided.
- `files`: CodeBlockFile[] — The block's source files. One entry renders its name as a header label; several render as switchable tabs. `children` is ignored while `files` is set, and a lone entry may omit `code` to keep using `children`.
- `defaultFile`: string — File name that starts active (uncontrolled). Defaults to the first file.
- `activeFile`: string — Active file name (controlled). Pair with `onFileChange`.
- `onFileChange`: (fileName: string) => void — Fired when the reader switches tabs
- `title`: string — Optional title displayed above the code block
- `showLineNumbers`: boolean = false — Show line numbers in the code block
- `highlight`: boolean = true — Enable syntax highlighting
- `fullWidth`: boolean = true — Make the code block take the full width of its container
- `radius`: RadiusValue = DEFAULT_CODE_RADIUS — Corner radius of the code surface (size token or px). Set `'none'` to sit flush inside a bordered container such as `Card.Section`.
- `withBorder`: boolean = true — Draw the code surface's 1px border. Defaults to `true`.
- `showCopyButton`: boolean = true — Show a copy button (accessible name "Copy code", "Copied" after a successful copy, which is also announced to screen readers).
- `onCopy`: (code: string) => void — Callback after the copy button copied the code
- `textStyle`: StyleProp<TextStyle> — Custom styles for the code text
- `titleStyle`: StyleProp<TextStyle> — Custom styles for the title text
- `highlightLines`: Array<string | number> — Lines to highlight, e.g. ["1", "3-5"] or [1, 3]
- `spoiler`: boolean = false — Show a spoiler for the code block
- `spoilerMaxHeight`: number = 160 — Maximum height for the spoiler, if exceeded a "Show More" button appears
- `variant`: 'code' | 'terminal' | 'hacker' = 'code' — Visual variant: default code styling, terminal emulation, or hacker theme
- `promptSymbol`: string = '$' — Optional prompt prefix for terminal variant (ignored if lines already prefixed)
- `githubUrl`: string — GitHub URL for the source shown here. Adds an edit button beside the copy button that opens it. Per-file URLs (`files[].githubUrl`) win over this one, so a multi-file block points each tab at its own source.
- `fileHeader`: boolean = false — Render the file name in a detached bar above the panel instead of inline inside it. Single-file blocks only — tabs always sit inside the panel.
- `colors`: CodeBlockColorOverrides — Override base colors (background, text, highlights)
- `wrap`: boolean = true — Control whether long lines wrap (defaults to true). Set to false to enable horizontal scrolling instead.
- `ff`: string — Custom font family for the code text (overrides `theme.fontFamilyMono`)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface CodeBlockFile {
  /** File name shown on the tab, e.g. `data.ts` */
  name: string;
  /** Source displayed while this file is active. Falls back to `children`. */
  code?: string;
  /** Highlighting language. Inferred from the file extension when omitted. */
  language?: string;
  /** Replaces the extension-derived tab icon */
  icon?: React.ReactNode;
  /** Lines to highlight for this file only */
  highlightLines?: Array<string | number>;
  /**
   * GitHub URL for this file, opened by the header's edit button while this tab
   * is active. Falls back to the block-level `githubUrl` when omitted.
   */
  githubUrl?: string;
}

export interface CodeBlockColorOverrides {
  /** Background color (hex, rgb, or theme token like `primary.6`) */
  background?: string;
  /** Border/accent color (hex/rgb/theme token) */
  border?: string;
  /** Override text/token colors. Accepts a single color, an array, or a token map. */
  text?: CodeBlockTextPalette;
  /** Highlight colors for emphasized lines */
  highlight?: {
    background?: string;
  };
}

export type CodeBlockTextPalette =
  | string
  | string[]
  | Partial<Record<CodeBlockToken, string>>;
```

## Examples

### Basics

Default CodeBlock showing a single snippet with automatic language detection and copy controls.

```tsx
import { Block } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const sample = `import { View, Text } from 'react-native';

export function HelloWorld() {
  return (
    <View>
      <Text>Hello, World!</Text>
    </View>
  );
}`;

export function Demo() {
  return (
    <Block fullWidth>
      <CodeBlock>{sample}</CodeBlock>
    </Block>
  );
}
```

### Interactive

Pass `onCopy` to run your own feedback after the copy button copies the code.

```tsx
import { useState } from 'react';

import { Block, Text } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const sampleCode = `const greeting = "Hello, World!";
console.log(greeting);

// A simple function
function add(a, b) {
  return a + b;
}

const result = add(5, 3);
console.log(\`5 + 3 = \${result}\`);`;

export function Demo() {
  const [copiedLength, setCopiedLength] = useState<number | null>(null);

  return (
    <Block fullWidth>
      <CodeBlock
        language="javascript"
        title="Interactive copy example"
        onCopy={(code) => setCopiedLength(code.length)}
      >
        {sampleCode}
      </CodeBlock>
      {copiedLength !== null && (
        <Text size="xs" c="success">
          Copied {copiedLength} characters to the clipboard.
        </Text>
      )}
    </Block>
  );
}
```

### File tabs

Pass `files` to show one source per tab. Each tab carries its language's logo where one exists (TypeScript, CSS) and a glyph otherwise, and highlighting follows the active file's language — `data.ts` highlights as TypeScript even though the block's `language` is `tsx`.

```tsx
import { Block } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const FILES = [
  {
    name: 'index.tsx',
    code: `import { Blockquote } from '@plocks/ui';

import { AUTHOR, QUOTE } from './data';

export function Demo() {
  return <Blockquote author={AUTHOR}>{QUOTE}</Blockquote>;
}`,
  },
  {
    name: 'data.ts',
    code: `export const AUTHOR = {
  name: 'Priya Shah',
  title: 'CTO',
  organization: 'Northwind Labs',
};

export const QUOTE = 'The components feel native on every platform.';`,
  },
  {
    name: 'quote.css',
    code: `.quote {
  border-left: 4px solid var(--primary-5);
  padding: 16px 20px;
}`,
  },
  {
    name: 'theme.json',
    code: `{
  "primaryColor": "blue",
  "defaultRadius": "md"
}`,
  },
];

export function Demo() {
  return (
    <Block fullWidth>
      <CodeBlock files={FILES} />
    </Block>
  );
}
```

### GitHub

Surface GitHub shortcuts alongside copy controls across variants using the `githubUrl` prop.

```tsx
import { Block, Text } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const componentExample = `import { View, Text } from 'react-native';

export function HelloWorld() {
  return (
    <View>
      <Text>Hello, World!</Text>
    </View>
  );
}`;

const inlineExample = `// This code has both copy and GitHub buttons
export function MyComponent() {
  return <div>Hello with GitHub button!</div>;
}`;

const terminalExample = `$ npm install @plocks/ui
$ npm start
Server running on http://localhost:3000`;

const floatingExample = `// Floating buttons example (no title)
export function FloatingExample() {
  return <span>Hover to see buttons</span>;
}`;

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text size="sm" fw="semibold">
          Basic component
        </Text>
        <CodeBlock
          title="Basic component"
          githubUrl="https://github.com/platform-blocks/plocks/blob/main/packages/ui/src/components/Button/Button.tsx"
        >
          {componentExample}
        </CodeBlock>
      </Block>

      <Block>
        <Text size="sm" fw="semibold">
          File name and language
        </Text>
        <CodeBlock
          files={[{ name: 'example.tsx' }]}
          githubUrl="https://github.com/platform-blocks/plocks/blob/main/packages/ui/src/components/Text/Text.tsx"
        >
          {inlineExample}
        </CodeBlock>
      </Block>

      <Block>
        <Text size="sm" fw="semibold">
          Terminal variant
        </Text>
        <CodeBlock
          variant="terminal"
          title="Terminal example"
          githubUrl="https://github.com/platform-blocks/plocks/blob/main/apps/docs/eas-build-post-install.sh"
        >
          {terminalExample}
        </CodeBlock>
      </Block>

      <Block>
        <Text size="sm" fw="semibold">
          Floating controls
        </Text>
        <CodeBlock githubUrl="https://github.com/platform-blocks/plocks/blob/main/packages/code/src/components/CodeBlock/CodeBlock.tsx">
          {floatingExample}
        </CodeBlock>
      </Block>
    </Block>
  );
}
```

### Languages

Examples highlighting TypeScript, JSON, and Markdown syntax rendering in CodeBlock.

```tsx
import { Block } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const tsxExample = `interface Props {
  title: string;
  onPress?: () => void;
}

export function Button({ title, onPress }: Props) {
  return (
    <TouchableOpacity onPress={onPress}>
      <Text>{title}</Text>
    </TouchableOpacity>
  );
}`;

const jsonExample = `{
  "name": "my-app",
  "version": "1.0.0",
  "dependencies": {
    "react": "^18.2.0",
    "react-native": "^0.72.0"
  },
  "scripts": {
    "start": "expo start",
    "build": "expo build"
  }
}`;

const markdownExample = `# Getting Started

This is a **markdown** example with \`inline code\`.

## Features

- Syntax highlighting
- Multiple languages
- Copy functionality

> Blockquote with *emphasis* and **bold** text.`;

export function Demo() {
  return (
    <Block fullWidth>
      <CodeBlock language="tsx" title="React component">
        {tsxExample}
      </CodeBlock>
      <CodeBlock language="json" title="Package configuration">
        {jsonExample}
      </CodeBlock>
      <CodeBlock language="markdown" title="Documentation">
        {markdownExample}
      </CodeBlock>
    </Block>
  );
}
```

### Features

Add a `title` and `showLineNumbers` for a labeled, numbered block, or set `showCopyButton={false}` to hide the copy button.

```tsx
import { Block } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const fibonacciExample = `function fibonacci(n) {
  if (n <= 1) {
    return n;
  }
  return fibonacci(n - 1) + fibonacci(n - 2);
}

// Calculate the 10th Fibonacci number
const result = fibonacci(10);
console.log(\`Fibonacci(10) = \${result}\`);`;

const disabledCopyExample = `// This example has the copy button disabled
const message = "Hello, World!";
console.log(message);`;

export function Demo() {
  return (
    <Block fullWidth>
      <CodeBlock title="With title and line numbers" showLineNumbers>
        {fibonacciExample}
      </CodeBlock>
      <CodeBlock title="No copy button" showCopyButton={false}>
        {disabledCopyExample}
      </CodeBlock>
    </Block>
  );
}
```

### Variants

Compare the default, terminal, and hacker themes available through the variant prop.

```tsx
import { Block, Text } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const sampleCode = `function hackTheMatrix() {
  const matrix = generateMatrix();
  console.log('Entering the matrix...');

  for (let i = 0; i < matrix.length; i += 1) {
    matrix[i].decrypt();
  }

  return 'Welcome to the real world.';
}`;

const terminalCode = `$ npm install @plocks/ui
$ cd my-app
$ npm start
Server running on port 3000`;

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text size="sm" fw="semibold">
          Default code block
        </Text>
        <CodeBlock language="javascript" title="matrix.js">
          {sampleCode}
        </CodeBlock>
      </Block>

      <Block>
        <Text size="sm" fw="semibold">
          Terminal variant
        </Text>
        <CodeBlock variant="terminal" title="Terminal">
          {terminalCode}
        </CodeBlock>
      </Block>

      <Block>
        <Text size="sm" fw="semibold">
          Hacker variant
        </Text>
        <CodeBlock variant="hacker" language="javascript" title="hack.exe">
          {sampleCode}
        </CodeBlock>
      </Block>
    </Block>
  );
}
```

### Highlighting

Use highlightLines for single lines or ranges to draw attention to important snippets.

```tsx
import { Block } from '@plocks/ui';
import { CodeBlock } from '@plocks/code';

const sample = `import { View, Text } from 'react-native';

interface User {
  id: number;
  name: string; // highlighted
  active: boolean;
}

export function UserCard({ user }: { user: User }) {
  if (!user.active) {
    return null; // early return highlighted
  }
  return (
    <View style={{ padding: 8 }}>
      <Text>{user.name}</Text>
    </View>
  );
}

// Utility function (range highlighted)
export function filterActive(users: User[]) {
  return users.filter((u) => u.active);
}`;

export function Demo() {
  return (
    <Block fullWidth>
      <CodeBlock title="Highlighted lines" showLineNumbers highlightLines={['5', '11', '20-23']}>
        {sample}
      </CodeBlock>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Collapse.md -->

# Collapse

Displays content that can be revealed or hidden with an animation.

## Metadata

- Import: `import { Collapse } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Collapse
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Collapse

## Props

- `isCollapsed` (required): boolean — Whether the content is collapsed (hidden). `false` reveals/expands it.
- `children` (required): ReactNode — Content to show/hide
- `duration`: number = 300 — Animation duration in milliseconds
- `transitionDuration`: number = 300 — Duration (ms) of the height transition. Cross-component spelling that takes precedence over `duration`; `0` snaps open/closed with no animation. Always 0 when the user prefers reduced motion.
- `timing`: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' = 'ease-out' — Animation timing function
- `contentStyle`: StyleProp<ViewStyle> — Style for the content wrapper
- `onAnimationStart`: () => void — Callback fired when animation starts. Safe to pass inline — a new function identity does not restart the animation.
- `onAnimationEnd`: () => void — Callback fired when animation completes. Safe to pass inline.
- `easing`: (value: number) => number — Custom easing function overriding the timing preset. On iOS/Android it must be a Reanimated worklet (e.g. `Easing.bezier(...)` from `react-native-reanimated`); a plain JS function is ignored there (the `timing` preset is used instead, with a dev warning). Web accepts any function.
- `animateOnMount`: boolean = false — Whether to animate on initial mount
- `collapsedHeight`: number = 0 — Custom height when collapsed (useful for partial reveals)
- `fadeContent`: boolean = true — Whether to fade content in/out along with height animation
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Basic usage of the Collapse component to show and hide content with animation.

```tsx
import { Block, Button, Collapse, Text } from '@plocks/ui';
import { useState } from 'react';
export function Demo() {
  const [isCollapsed, setIsCollapsed] = useState(false);
  return (
    <Block>
      <Button onPress={() => setIsCollapsed(!isCollapsed)}>
        {isCollapsed ? 'Show' : 'Hide'}
      </Button>
      <Collapse isCollapsed={isCollapsed}>
        <Text>
          This is some content inside the Collapse component. It will be shown or hidden based on the isCollapsed prop.
        </Text>
      </Collapse>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ColorInput.md -->

# ColorInput

ColorInput combines a hex field with a palette of preset colors.

## Metadata

- Import: `import { ColorInput } from '@plocks/ui';`
- Docs: https://plocks.dev/components/ColorInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ColorInput

## Props

- `value`: string — Current color value in hex format (e.g., "#ff0000")
- `defaultValue`: string — Default color value for uncontrolled usage
- `onChange`: (color: string) => void — Called with the new color: a complete hex while typing, the normalized `#RRGGBB` form on blur / submit / swatch selection, and `''` when cleared.
- `showPreview`: boolean — Whether to show the color preview
- `showInput`: boolean — Whether to show the hex input
- `swatches`: string[] — Predefined color swatches to show
- `swatchLabels`: Record<string, string> — Readable names for the swatches, keyed by color (e.g. `{ '#FF6B6B': 'Coral' }`). Defaults to the color string.
- `withSwatches`: boolean — Whether to show the swatch dropdown (and its toggle button)
- `placement`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' — Dropdown placement
- `flip`: boolean — Whether to flip placement when no space
- `shift`: boolean — Whether to shift position to stay in viewport
- `boundary`: number — Minimum distance between the dropdown and the viewport edges, in pixels
- `offset`: number — Offset from anchor element in pixels
- `autoReposition`: boolean — Whether to automatically reposition on resize/scroll
- `fallbackPlacements`: PlacementType[] — Fallback placements to try
- `keyboardAvoidance`: boolean — Whether dropdown should avoid the on-screen keyboard when visible
- `previewStyle`: StyleProp<ViewStyle> — Custom style for the preview
- `inputStyle`: StyleProp<ViewStyle> — Custom style for the input box (the bordered frame around preview, hex text and buttons)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Variants

Compare the default, filled, outline, and unstyled field shells on ColorInput.

```tsx
import { Column, ColorInput } from '@plocks/ui';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <ColorInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Choose a color" />
      ))}
    </Column>
  );
}
```

### Basics

Color field with a hex input, live preview and preset swatches.

```tsx
import { useState } from 'react';
import { Block, ColorInput, Text } from '@plocks/ui';

export function Demo() {
  const [color, setColor] = useState('#FF6B6B');

  return (
    <Block fullWidth>
      <ColorInput
        value={color}
        onChange={setColor}
        label="Favorite color"
        placeholder="Select a color"
        clearable
        fullWidth
      />
      <Text size="sm" c="secondary">
        Selected: {color || 'none'}
      </Text>
    </Block>
  );
}
```

### Custom Swatches

Color field with custom swatch palettes.

```tsx
import { useState } from 'react';
import { Block, ColorInput, Text } from '@plocks/ui';

export function Demo() {
  const [color1, setColor1] = useState('#2196F3');
  const [color2, setColor2] = useState('#4CAF50');
  const [color3, setColor3] = useState('#FF9800');
  
  const blueSwatches = [
    '#E3F2FD', '#BBDEFB', '#90CAF9', '#64B5F6', '#42A5F5',
    '#2196F3', '#1E88E5', '#1976D2', '#1565C0', '#0D47A1',
  ];

  const greenSwatches = [
    '#E8F5E8', '#C8E6C9', '#A5D6A7', '#81C784', '#66BB6A',
    '#4CAF50', '#43A047', '#388E3C', '#2E7D32', '#1B5E20',
  ];

  return (
    <Block fullWidth>
      <Block fullWidth>
        <Text size="sm" fw="semibold">
          Custom blue palette
        </Text>
        <ColorInput
          value={color1}
          onChange={setColor1}
          swatches={blueSwatches}
          label="Blue shades"
          fullWidth
        />
      </Block>

      <Block fullWidth>
        <Text size="sm" fw="semibold">
          Custom green palette
        </Text>
        <ColorInput
          value={color2}
          onChange={setColor2}
          swatches={greenSwatches}
          label="Green shades"
          fullWidth
        />
      </Block>

      <Block fullWidth>
        <Text size="sm" fw="semibold">
          Without swatches
        </Text>
        <ColorInput
          value={color3}
          onChange={setColor3}
          withSwatches={false}
          label="Hex input only"
          fullWidth
        />
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ColorPicker.md -->

# ColorPicker

ColorPicker opens a compact palette for choosing a preset color.

## Metadata

- Import: `import { ColorPicker } from '@plocks/ui';`
- Docs: https://plocks.dev/components/ColorPicker
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ColorPicker

## Props

- `value`: string — Current color value in hex format (controlled)
- `defaultValue`: string = '' — Initial color value for uncontrolled usage
- `onChange`: (color: string) => void — Callback fired when a swatch is selected
- `swatches`: string[] = DEFAULT_SWATCHES — Preset colors to choose from
- `swatchLabels`: Record<string, string> — Readable names for the swatches, keyed by color (e.g. `{ '#FF6B6B': 'Coral' }`). Defaults to the color string.
- `size`: number = 28 — Size of the trigger + swatches in pixels
- `columns`: number = 5 — Number of swatches per row in the popover
- `disabled`: boolean = false — Whether the picker is disabled
- `accessibilityLabel`: string = `Color <value>`, or 'Select a color' with no value — Accessible name of the trigger. @default `Color <value>`, or 'Select a color' with no value
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

ColorPicker opens a compact palette for choosing a preset color.

```tsx
import { useState } from 'react';
import { Block, ColorPicker, Row, Text } from '@plocks/ui';

export function Demo() {
  const [color, setColor] = useState('#4ECDC4');

  return (
    <Block>
      <Row gap="sm" align="center">
        <ColorPicker value={color} onChange={setColor} />
        <Text size="sm" c="secondary">
          Selected: {color}
        </Text>
      </Row>

      <Block>
        <Text size="sm" fw="semibold">
          Larger, custom swatches
        </Text>
        <ColorPicker
          defaultValue="#5F27CD"
          size={36}
          columns={4}
          swatches={['#0F172A', '#5F27CD', '#54A0FF', '#4ECDC4', '#96CEB4', '#FECA57', '#F8B500', '#FF6B6B']}
        />
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ColorSwatch.md -->

# ColorSwatch

A simple square component for displaying colors, designed as a building block for color pickers and palette interfaces.

## Metadata

- Import: `import { ColorSwatch } from '@plocks/ui';`
- Tags: color, swatch, palette, picker
- Docs: https://plocks.dev/components/ColorSwatch
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ColorSwatch

## Props

- `color` (required): string — The color value to display (hex, rgb, hsl, etc.)
- `size`: number = 32 — Size of the swatch in pixels
- `selected`: boolean — Whether the swatch is selected/active
- `disabled`: boolean = false — Whether the swatch is disabled (not pressable, `aria-disabled`)
- `onPress`: () => void — Callback when swatch is pressed. Makes the swatch interactive.
- `showBorder`: boolean = true — Show a border around the swatch
- `borderColor`: string — Custom border color (defaults to theme color)
- `borderWidth`: number = 1 — Border width in pixels
- `borderRadius`: number = 4 — Border radius in pixels
- `showCheckmark`: boolean = true — Show a checkmark when selected
- `checkmarkColor`: string — Custom checkmark color (defaults to a readable color on `color`)
- `accessibilityLabel`: string — Accessible name. Interactive swatches default to `Color <color>`; a non-interactive swatch is only exposed (as an image) when this is set.
- `accessibilityHint`: string — Extra native accessibility hint.
- `role`: 'button' | 'radio' | 'option' = 'button' — Role of an interactive swatch (see {@link ColorSwatchRole}). @default 'button'
- `onFocus`: () => void — Focus handler of an interactive swatch.
- `onBlur`: () => void — Blur handler of an interactive swatch.
- `onKeyDown`: (event: WebKeyboardEvent) => void — Web only: key handler of an interactive swatch (roving focus in swatch groups).
- `tabIndex`: 0 | -1 — Web only: tab order of an interactive swatch (`-1` keeps it out of the Tab sequence).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

A simple square component for displaying colors, designed as a building block for color pickers and palette interfaces.

```tsx
import React, { useState } from 'react';
import { Flex, Text, ColorSwatch } from '@plocks/ui';

const colors = [
  '#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7',
  '#DDA0DD', '#98D8C8', '#F7DC6F', '#BB8FCE', '#85C1E9'
];

export function Demo() {
  const [selectedColor, setSelectedColor] = useState<string>('#FF6B6B');

  return (
    <Flex direction="column" gap={16} p={16} style={{ maxWidth: 400 }}>
      <Text fw="semibold" size="md">Basic Color Swatches</Text>
      
      <Flex direction="column" gap={8}>
        <Text size="sm">Click to select a color:</Text>
        <Flex direction="row" gap={8} wrap="wrap">
          {colors.map(color => (
            <ColorSwatch
              key={color}
              color={color}
              size={40}
              selected={selectedColor === color}
              onPress={() => setSelectedColor(color)}
            />
          ))}
        </Flex>
        <Text size="xs" c="secondary">
          Selected: {selectedColor}
        </Text>
      </Flex>

      <Flex direction="column" gap={8}>
        <Text size="sm">Different sizes:</Text>
        <Flex direction="row" gap={8} align="center">
          <ColorSwatch color="#FF6B6B" size={24} />
          <ColorSwatch color="#4ECDC4" size={32} />
          <ColorSwatch color="#45B7D1" size={48} />
          <ColorSwatch color="#96CEB4" size={64} />
        </Flex>
      </Flex>

      <Flex direction="column" gap={8}>
        <Text size="sm">Without borders:</Text>
        <Flex direction="row" gap={8}>
          {colors.slice(0, 5).map(color => (
            <ColorSwatch
              key={color}
              color={color}
              size={32}
              showBorder={false}
            />
          ))}
        </Flex>
      </Flex>

      <Flex direction="column" gap={8}>
        <Text size="sm">Disabled state:</Text>
        <Flex direction="row" gap={8}>
          {colors.slice(0, 3).map(color => (
            <ColorSwatch
              key={color}
              color={color}
              size={32}
              disabled
            />
          ))}
        </Flex>
      </Flex>
    </Flex>
  );
}
```

### Advanced

```tsx
import { useState } from 'react';
import { Flex, Text, ColorSwatch } from '@plocks/ui';

export function Demo() {
  const [selectedColor, setSelectedColor] = useState<string>('#E74C3C');

  return (
    <Flex direction="column" gap={20} p={16} >
      <Flex direction="column" gap={8}>
        <Text size="sm">Grayscale palette:</Text>
        <Flex direction="row" gap={2}>
          {[
            '#000000', '#1a1a1a', '#333333', '#4d4d4d', '#666666',
            '#808080', '#999999', '#b3b3b3', '#cccccc', '#e6e6e6', '#ffffff'
          ].map(color => (
            <ColorSwatch
              key={color}
              color={color}
              borderRadius={2}
              selected={selectedColor === color}
              onPress={() => setSelectedColor(color)}
            />
          ))}
        </Flex>
      </Flex>

      <Flex direction="column" gap={8}>
        <Text size="sm">Large display swatch:</Text>
        <Flex direction="row" align="center" gap={16}>
          <ColorSwatch 
            color={selectedColor} 
            size={80} 
            borderRadius={8}
            showCheckmark={false}
          />
          <Flex direction="column" gap={4}>
            <Text fw="semibold">{selectedColor}</Text>
            <Text size="xs" c="secondary">Click any swatch above to change</Text>
          </Flex>
        </Flex>
      </Flex>
    </Flex>
  );
}
```

### Palette

```tsx
import React, { useState } from 'react';
import { Flex, Text, ColorSwatch } from '@plocks/ui';

export function Demo() {
  const [selectedColor, setSelectedColor] = useState<string>('#E74C3C');

  const colorPalettes = {
    'Material Colors': [
      '#F44336', '#E91E63', '#9C27B0', '#673AB7', '#3F51B5',
      '#2196F3', '#03A9F4', '#00BCD4', '#009688', '#4CAF50',
      '#8BC34A', '#CDDC39', '#FFEB3B', '#FFC107', '#FF9800',
      '#FF5722', '#795548', '#9E9E9E', '#607D8B', '#000000'
    ],
    'Pastel Colors': [
      '#FFB3BA', '#FFDFBA', '#FFFFBA', '#BAFFC9', '#BAE1FF',
      '#C5B3FF', '#FFB3E6', '#FFD1DC', '#E6E6FA', '#F0E68C'
    ],
    'Dark Colors': [
      '#2C3E50', '#34495E', '#7F8C8D', '#95A5A6', '#BDC3C7',
      '#1ABC9C', '#16A085', '#27AE60', '#229954', '#E74C3C'
    ]
  };

  return (
    <Flex direction="column" gap={20} p={16} style={{ maxWidth: 600 }}>
      <Text fw="semibold" size="md">Color Palette Builder</Text>
      
      <Flex direction="column" gap={8}>
        <Text size="sm">Selected Color: {selectedColor}</Text>
        <ColorSwatch 
          color={selectedColor} 
          size={60} 
          borderRadius={8}
          showCheckmark={false}
        />
      </Flex>

      {Object.entries(colorPalettes).map(([paletteName, colors]) => (
        <Flex key={paletteName} direction="column" gap={8}>
          <Text fw="medium" size="sm">{paletteName}</Text>
          <Flex direction="row" gap={6} wrap="wrap">
            {colors.map(color => (
              <ColorSwatch
                key={color}
                color={color}
                size={32}
                selected={selectedColor === color}
                onPress={() => setSelectedColor(color)}
                borderRadius={paletteName === 'Pastel Colors' ? 16 : 4}
              />
            ))}
          </Flex>
        </Flex>
      ))}

      <Flex direction="column" gap={8}>
        <Text fw="medium" size="sm">Custom Styles Examples</Text>
        <Flex direction="row" gap={12} wrap="wrap">
          <Flex direction="column" gap={4} align="center">
            <ColorSwatch 
              color={selectedColor} 
              size={40} 
              borderRadius={20}
              borderWidth={3}
              borderColor="#FFD700"
            />
            <Text size="xs">Round Gold</Text>
          </Flex>

          <Flex direction="column" gap={4} align="center">
            <ColorSwatch 
              color={selectedColor} 
              size={40} 
              showBorder={false}
              showCheckmark={false}
            />
            <Text size="xs">No Border</Text>
          </Flex>

          <Flex direction="column" gap={4} align="center">
            <ColorSwatch 
              color={selectedColor} 
              size={40} 
              borderRadius={0}
              checkmarkColor="#FFD700"
            />
            <Text size="xs">Square</Text>
          </Flex>
        </Flex>
      </Flex>
    </Flex>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ComboboxPopover.md -->

# ComboboxPopover

Use a ref-forwarding child inside Target. On phones the list opens in a centered dialog.

## Metadata

- Import: `import { ComboboxPopover } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/ComboboxPopover
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ComboboxPopover

## Props

- `multiple`: false | true = false — Allow several values.
- `value`: string | null | string[] — Controlled value. `null` = nothing selected. Controlled values.
- `defaultValue`: string | null | string[] — Initial value when uncontrolled. Initial values when uncontrolled.
- `onChange`: ((value: string | null, option: ComboboxPopoverOption<TItem> | null) => void) | ((value: string[], options: ComboboxPopoverOption<TItem>[]) => void) — Called with the new value and its option (`null, null` when deselected). Called with the new values and their options, in selection order.
- `allowDeselect`: boolean = true — Pressing the selected option again clears the value. @default true
- `children` (required): ReactNode — Content holding exactly one `ComboboxPopover.Target`.
- `data` (required): ComboboxPopoverData<TItem> — Options: strings, `{ value, label?, disabled? }` objects (extra fields allowed) or `{ group, items }` groups.
- `searchable`: boolean = false — Adds a search input at the top of the dropdown that filters the options.
- `searchValue`: string — Controlled search text.
- `defaultSearchValue`: string — Initial search text when uncontrolled.
- `onSearchChange`: (search: string) => void — Called with the new search text (typing, and `''` when the dropdown closes).
- `searchPlaceholder`: string = 'Search…' — Placeholder and accessible name of the search input. @default 'Search…'
- `filter`: ComboboxPopoverFilter<TItem> — Custom filter / sort, applied while `searchable`. Receives parsed options and groups; the default keeps options whose label contains the search text (case-insensitive).
- `limit`: number = Infinity — Maximum number of options shown at once, applied while `searchable`.
- `nothingFoundMessage`: ReactNode — Shown when no option matches (or `data` is empty). Without it, a dropdown with nothing to show doesn't open.
- `withCheckIcon`: boolean = true — Show a check mark on selected options. @default true
- `checkIconPosition`: 'start' | 'end' = 'start' — Side of the label the check mark sits on. @default 'start'
- `withAlignedLabels`: boolean = false — Reserve the check mark's slot on every option, so unchecked labels line up with checked ones. @default false
- `renderOption`: (input: ComboboxPopoverRenderOptionInput<TItem>) => ReactNode — Replaces an option's content (the row stays an accessible, selectable option named by its label).
- `maxDropdownHeight`: number = 260 — Maximum height of the option list before it scrolls, px. @default 260
- `selectFirstOptionOnDropdownOpen`: boolean = false — Highlight the first option when the dropdown opens, instead of the selected one. @default false
- `onOptionSubmit`: (value: string) => void — Called with an option's value when it is chosen (press, Enter or Space), before `onChange`.
- `dropdownOpened`: boolean — Controlled open state of the dropdown.
- `defaultDropdownOpened`: boolean = false — Initial open state when uncontrolled. @default false
- `onDropdownOpen`: () => void — Called when the dropdown asks to open (target press or key).
- `onDropdownClose`: () => void — Called when the dropdown asks to close (selection, Escape, outside press, Tab).
- `position`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom-start' — Placement relative to the target, written for LTR (mirrored in RTL). @default 'bottom-start'
- `offset`: number = 6 — Gap between target and dropdown, px. @default 6
- `dropdownWidth`: number | 'target' = 'target' — Dropdown width: a number, or `'target'` — at least as wide as the target. @default 'target'
- `strategy`: 'absolute' | 'fixed' | 'portal' — 'fixed' (web default): viewport-fixed; 'absolute'; 'portal' (native default): rendered in an RN Modal at the app root. Phones use a sheet instead.
- `size`: SizeValue = 'sm' — Size of the option rows and search input. @default 'sm'
- `disabled`: boolean = false — Disables the target; the dropdown never opens. @default false
- `aria-label`: string — Accessible name of the option list (and of the phone sheet). Defaults to the target labelling it (web).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ComboboxPopoverTarget } from '@plocks/ui';`

### ComboboxPopoverTarget

- `children` (required): ReactElement — One element that accepts a ref (a `Button`, `Pressable`, …). It becomes the dropdown's anchor and receives `onPress`, `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` and (web) the opening keys.

### ComboboxPopover.Target

- `children` (required): ReactElement — One element that accepts a ref (a `Button`, `Pressable`, …). It becomes the dropdown's anchor and receives `onPress`, `aria-haspopup="listbox"`, `aria-expanded`, `aria-controls` and (web) the opening keys.

## Types

```ts
export type ComboboxPopoverOption<TItem extends ComboboxPopoverItem = ComboboxPopoverItem> = TItem & {
  label: string;
};

export interface ComboboxPopoverItem {
  /** Value reported by `onChange` / `onOptionSubmit`; unique across `data`. */
  value: string;
  /** Text shown in the dropdown and matched by the search. @default value */
  label?: string;
  /** Rendered but not selectable, and skipped by the arrow keys. */
  disabled?: boolean;
}
```

## Examples

### Basics

Attach an option list to any ref-forwarding trigger. Search filters labels.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

export function Demo() {
  return (
    <ComboboxPopover data={['Apple', 'Banana', 'Cherry', 'Date']} searchable>
      <ComboboxPopover.Target>
        <Button>Select fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Multiple Selection

`multiple` keeps the list open while options are toggled.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} multiple defaultValue={['Apple']}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Disabled Options

Disabled entries stay visible and are skipped by selection.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = [{ value: 'Apple' }, { value: 'Banana', disabled: true }, { value: 'Cherry' }];

export function Demo() {
  return (
    <ComboboxPopover data={data}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Groups

Group headings organize related options.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = [
  { group: 'Fruit', items: ['Apple', 'Banana'] },
  { group: 'Vegetables', items: ['Carrot', 'Pea'] },
];

export function Demo() {
  return (
    <ComboboxPopover data={data}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Searchable

Typing filters options by their labels.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} searchable>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Custom Sort

`filter` can sort the parsed options after filtering.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} searchable filter={({ options }) => [...options].reverse()}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Limit Results

`limit` caps the number of matching options.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} searchable limit={3}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Nothing Found

Show a message when no options match the search.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} searchable nothingFoundMessage="No fruit matches">
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Check Icon Position

Move the selected check mark to the end of each row.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} defaultValue="Apple" checkIconPosition="end" withAlignedLabels>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Disallow Deselect

`allowDeselect={false}` keeps a selected option selected on a second press.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} defaultValue="Apple" allowDeselect={false}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Custom Option

`renderOption` replaces row content while retaining option semantics.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} renderOption={({ option }) => option.label.toUpperCase()}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Dropdown Position

`position` chooses the side of the target.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} position="top-start">
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Dropdown Width

Use a numeric `dropdownWidth` instead of matching the target.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];

export function Demo() {
  return (
    <ComboboxPopover data={data} dropdownWidth={320}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Large Data

The dropdown scrolls when the data exceeds its height.

```tsx
import { Button, ComboboxPopover } from '@plocks/ui';

const data = Array.from({ length: 100 }, (_, index) => `Option ${index + 1}`);

export function Demo() {
  return (
    <ComboboxPopover data={data} maxDropdownHeight={180}>
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

### Controlled Dropdown

`dropdownOpened` lets the parent own open state.

```tsx
import { useState } from 'react';
import { Button, ComboboxPopover } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <ComboboxPopover
      data={['Apple', 'Banana']}
      dropdownOpened={opened}
      onDropdownOpen={() => setOpened(true)}
      onDropdownClose={() => setOpened(false)}
    >
      <ComboboxPopover.Target>
        <Button>Choose fruit</Button>
      </ComboboxPopover.Target>
    </ComboboxPopover>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ContextMenu.md -->

# ContextMenu

ContextMenu shows actions for a target on right-click or long-press.

## Metadata

- Import: `import { ContextMenu } from '@plocks/ui';`
- Tags: menu, context, rightclick, longpress, actions
- Docs: https://plocks.dev/components/ContextMenu
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ContextMenu

## Props

- `children` (required): (props: ContextMenuTriggerProps) => ReactNode — Render prop for the trigger: spread the given props onto it.
- `items` (required): ContextMenuItem[]
- `closeOnSelect`: boolean = true — Close after selection. @default true
- `longPressDelay`: number = 350 — Long press duration (ms) for native. @default 350
- `mah`: number = 280 — Menu max height before the items scroll (not the root's). @default 280
- `onOpen`: () => void — Called when menu opens
- `onClose`: () => void — Called when menu closes
- `opened`: boolean — Controlled open state.
- `defaultOpened`: boolean = false — Initial open state when uncontrolled. @default false
- `position`: { x: number; y: number } — Controlled position (web: viewport coordinates; native: page coordinates).
- `aria-label`: string = 'Context menu' — Accessible name of the menu. @default 'Context menu'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface ContextMenuTriggerProps {
  /** Web: right-click, or the keyboard ContextMenu key. */
  onContextMenu: (event: WebMouseEvent) => void;
  /** Native long-press timer start. */
  onPressIn: (event: GestureResponderEvent) => void;
  /** Native long-press timer cancel. */
  onPressOut: () => void;
  /** Web keyboard: Shift+F10 / ContextMenu key. */
  onKeyDown?: (event: WebKeyboardEvent) => void;
  /** Screen readers: "long press" and a labelled "Open menu" action. */
  accessibilityActions: ReadonlyArray<AccessibilityActionInfo>;
  onAccessibilityAction: (event: AccessibilityActionEvent) => void;
  /** Web: `menu` — the trigger opens one. */
  'aria-haspopup'?: 'menu';
}

export interface ContextMenuItem {
  id: string;
  label: string;
  icon?: ReactNode;
  disabled?: boolean;
  danger?: boolean;
  onSelect?: () => void;
}
```

## Examples

### Basics

Wrap any trigger element with `ContextMenu` and pass an `items` array. The menu opens on right-click (web) or long-press (mobile); the `children` render prop receives the handlers to spread onto your trigger.

```tsx
import { Card, ContextMenu, Text } from '@plocks/ui';

const ITEMS = [
  { id: 'copy', label: 'Copy' },
  { id: 'rename', label: 'Rename' },
  { id: 'delete', label: 'Delete', danger: true },
];

export function Demo() {
  return (
    <ContextMenu items={ITEMS}>
      {(triggerProps) => (
        <Card {...triggerProps} padding="2xl">
          <Text>Right-click or long-press me</Text>
        </Card>
      )}
    </ContextMenu>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ControlField.md -->

# ControlField

ControlField combines a label, description, and a control (Switch, Checkbox, or Radio) into a single pressable row.

## Metadata

- Import: `import { ControlField } from '@plocks/ui';`
- Tags: control, field, checkbox, switch, radio, toggle, form, selection, row
- Docs: https://plocks.dev/components/ControlField
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ControlField

## Props

- `checked`: boolean — Controlled on/selected state.
- `defaultChecked`: boolean — Initial state for uncontrolled usage.
- `onChange`: (checked: boolean) => void — Called with the next state.
- `disabled`: boolean — Disables the row.
- `required`: boolean — Marks the field required (asterisk on the label, announced).
- `variant`: 'checkbox' | 'radio' | 'switch' — Which built-in control renders in the indicator slot. Default `'switch'`.
- `label`: React.ReactNode — Primary label.
- `description`: React.ReactNode — Supporting text shown beneath the label.
- `error`: React.ReactNode — Error shown below the row; marks the field invalid. `true` marks it invalid without a message.
- `color`: ThemeColor — Indicator color: a palette token, `'primary.6'` shade syntax, or any CSS color.
- `size`: SizeValue — Indicator + label size. Inherits from `ControlField.Group`.
- `indicatorPosition`: 'left' | 'right' — Which side the indicator sits on (logical: `right` = end). Default `'right'`.
- `control`: React.ReactElement<{ checked?: boolean; disabled?: boolean }> — Custom control element used instead of the built-in `variant` indicator. `checked` / `disabled` are injected automatically when not already set.
- `labelProps`: Omit<TextProps, 'children'> — Props applied to the label `<Text>`.
- `descriptionProps`: Omit<TextProps, 'children'> — Props applied to the description `<Text>`.
- `children`: React.ReactNode — Compound composition. When provided, children replace the built-in label/description/indicator layout. Use `ControlField.Label`, `ControlField.Description`, `ControlField.Indicator` and `ControlField.Error`.
- `accessibilityLabel`: string — Accessible name when there is no visible text label (overrides the label).
- `accessibilityHint`: string — Extra native hint.
- `id`: string — Base id: the row gets it, the label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ControlFieldGroup } from '@plocks/ui';`

### ControlFieldGroup

- `children` (required): React.ReactNode — ControlField rows.
- `variant`: 'default' | 'bordered' | 'flush' — Surface treatment. - `default` — filled surface, no border - `bordered` — filled surface with a hairline border - `flush` — no surface; just the dividers between rows
- `dividers`: boolean — Insert a divider between rows. Defaults to `true`.
- `insetDividers`: boolean — Inset the divider from the leading edge to align under the row content.
- `radius`: RadiusValue — Corner radius token or pixel value. Defaults to `lg`.
- `size`: SizeValue — Default size applied to every child field (and the row padding scale).
- `title`: React.ReactNode — Optional section title rendered above the surface.
- `titleProps`: Omit<TextProps, 'children'> — Override props for the title `<Text>`; the theme's `sectionLabel` text role by default.
- `footer`: React.ReactNode — Optional footer/help text rendered below the surface.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ControlField.Description

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Text` props (`tx` `txParams` `variant` `textRole` `size` `c` `fw` `ta` `lh` `lts` `tt` `fs` `td` `ff` `flex` `shrink` `position` `top` `right` `bottom` `left` `as` `selectable` `onPress` `onLayout` `value` `numberOfLines` `ellipsizeMode` `id` `nativeID`): https://plocks.dev/llms/components/Text.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ControlField.Group

- `children` (required): React.ReactNode — ControlField rows.
- `variant`: 'default' | 'bordered' | 'flush' — Surface treatment. - `default` — filled surface, no border - `bordered` — filled surface with a hairline border - `flush` — no surface; just the dividers between rows
- `dividers`: boolean — Insert a divider between rows. Defaults to `true`.
- `insetDividers`: boolean — Inset the divider from the leading edge to align under the row content.
- `radius`: RadiusValue — Corner radius token or pixel value. Defaults to `lg`.
- `size`: SizeValue — Default size applied to every child field (and the row padding scale).
- `title`: React.ReactNode — Optional section title rendered above the surface.
- `titleProps`: Omit<TextProps, 'children'> — Override props for the title `<Text>`; the theme's `sectionLabel` text role by default.
- `footer`: React.ReactNode — Optional footer/help text rendered below the surface.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ControlField.Indicator

- `variant`: 'checkbox' | 'radio' | 'switch' — Override the field's variant for this indicator.
- `children`: React.ReactElement<{ checked?: boolean; disabled?: boolean }> — Custom control element (checked/disabled injected from context).
- `style`: StyleProp<ViewStyle>
- `testID`: string

### ControlField.Label

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Text` props (`tx` `txParams` `variant` `textRole` `size` `c` `fw` `ta` `lh` `lts` `tt` `fs` `td` `ff` `flex` `shrink` `position` `top` `right` `bottom` `left` `as` `selectable` `onPress` `onLayout` `value` `numberOfLines` `ellipsizeMode` `id` `nativeID`): https://plocks.dev/llms/components/Text.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useControlField(): ControlFieldContextValue` — Returns the enclosing `ControlField`'s state (`checked`, `onChange`, `disabled`, `invalid`, `required`, `size`, `ids`, …) for custom controls and compound parts, and throws outside a `<ControlField>` — use `useControlFieldContext()` for a non-throwing read.
- `useControlFieldContext(): ControlFieldContextValue | null` — Returns the enclosing `ControlField`'s state, or `null` outside one — the non-throwing variant of `useControlField()`, for controls that also work on their own.
- `useControlFieldGroup(): ControlFieldGroupContextValue | null` — Returns the shared config of the enclosing `ControlField.Group` (its default `size` for child rows), or `null` outside a group — never throws.

## Examples

### Basics

A controlled switch row — the whole row is a single tap target.

```tsx
import { useState } from 'react';
import { ControlField } from '@plocks/ui';

export function Demo() {
  const [enabled, setEnabled] = useState(true);

  return (
    <ControlField
      label="Push notifications"
      description="Get notified when something happens"
      checked={enabled}
      onChange={setEnabled}
    />
  );
}
```

### Checkbox with validation

A consent row using the `checkbox` variant. When left unchecked the field shows an error message below the row.

```tsx
import { useState } from 'react';
import { ControlField } from '@plocks/ui';

export function Demo() {
  const [agreed, setAgreed] = useState(false);

  return (
    <ControlField
      variant="checkbox"
      indicatorPosition="left"
      label="I agree to the Terms of Service"
      description="You must accept before continuing"
      required
      checked={agreed}
      onChange={setAgreed}
      error={!agreed ? 'This field is required' : undefined}
    />
  );
}
```

### Variants

Compare the switch, checkbox, and radio indicators inside the same pressable field row.

```tsx
import { Column, ControlField } from '@plocks/ui';

const variants = ['switch', 'checkbox', 'radio'] as const;

export function Demo() {
  return (
    <Column gap="sm" fullWidth>
      {variants.map(variant => (
        <ControlField key={variant} variant={variant} label={`${variant} control`} description="Tap the row to change its value" defaultChecked={variant === 'switch'} />
      ))}
    </Column>
  );
}
```

### Custom control

Compose the row explicitly with `ControlField.Indicator` to drop in a custom control — here a warning-colored checkbox.

```tsx
import { useState } from 'react';
import { Block, Checkbox, ControlField } from '@plocks/ui';

export function Demo() {
  const [subscribed, setSubscribed] = useState(false);

  return (
    <ControlField checked={subscribed} onChange={setSubscribed}>
      <Block style={{ flex: 1 }} fullWidth={false}>
        <ControlField.Label>Subscribe to newsletter</ControlField.Label>
        <ControlField.Description>
          One email a week, unsubscribe anytime
        </ControlField.Description>
      </Block>
      <ControlField.Indicator>
        <Checkbox color="warning" />
      </ControlField.Indicator>
    </ControlField>
  );
}
```

### Grouped surface

Wrap rows in `ControlField.Group` to get an iOS-style settings surface — a rounded, filled background with hairline dividers between rows. The group can carry an optional title and footer, and sets a shared size for its children.

```tsx
import { useState } from 'react';
import { ControlField } from '@plocks/ui';

export function Demo() {
  const [wifi, setWifi] = useState(true);
  const [bluetooth, setBluetooth] = useState(false);
  const [airplane, setAirplane] = useState(false);

  return (
    <ControlField.Group
      variant="bordered"
      title="Connectivity"
      footer="Airplane mode disables all wireless radios."
    >
      <ControlField label="Wi-Fi" checked={wifi} onChange={setWifi} />
      <ControlField
        label="Bluetooth"
        checked={bluetooth}
        onChange={setBluetooth}
      />
      <ControlField
        label="Airplane mode"
        description="Turn off all connections"
        checked={airplane}
        onChange={setAirplane}
      />
    </ControlField.Group>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/CopyButton.md -->

# CopyButton

Small utility component for copying text values to the clipboard with optional toast feedback. Used inside components like `CodeBlock` and `QRCode` to standardize UX.

## Metadata

- Import: `import { CopyButton } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/CopyButton
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/CopyButton

## Props

- `value` (required): string — The text to copy to clipboard
- `onCopy`: (value: string) => void — Called with the value once it has been copied (not when copying failed)
- `onCopyError`: (error: Error) => void — Called when copying failed (no clipboard access, permission denied, …)
- `iconOnly`: boolean = true — Icon-only control (the default). `false` renders a button with the icon and the `label` text.
- `label`: string = 'Copy' — Accessible name (and visible text when `iconOnly={false}`). @default 'Copy'
- `copiedLabel`: string = 'Copied' — Label / announcement once the value is copied. @default 'Copied'
- `toastTitle`: string = 'Copied to clipboard' — Title for the toast (web)
- `toastMessage`: string — Detailed message for the toast (web)
- `size`: ComponentSizeValue = 'md' — Visual size token, or the control height in px
- `disableToast`: boolean = false — Disable the "copied to clipboard" toast (the copy is then announced to screen readers instead)
- `tooltip`: TooltipPropValue — Tooltip text, or a full Tooltip config (`{ label, maw, … }`). Icon-only controls default to the label.
- `tooltipPosition`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Where the tooltip opens — including the automatic "Copy" / "Copied" one. An explicit `position` in the object form of `tooltip` wins.
- `mode`: 'button' | 'icon' = 'button' — Presentation: a button (default) or a bare icon with no chrome
- `buttonVariant`: 'none' | 'default' | 'secondary' | 'ghost' | 'filled' | 'outline' | 'gradient' = 'secondary' — Button variant in button mode
- `iconName`: string = 'copy' — Icon name to display (defaults to copy)
- `copiedIconName`: string = 'check' — Icon name to display after copy (default check)
- `iconColor`: ColorProp — Base icon color
- `copiedIconColor`: ColorProp — Copied state icon color (default: the success palette)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Icon-only copy button with default toast feedback.

```tsx
import { CopyButton } from '@plocks/ui';

export function Demo() {
  return <CopyButton value="ABCD-1234" />;
}
```

### Labeled

Copy control showing label text instead of icon-only presentation.

```tsx
import { CopyButton } from '@plocks/ui';

export function Demo() {
  return <CopyButton value="sk_live_1a2b3c4d5e6f7g8h9i10" iconOnly={false} label="Copy Key" />;
}
```

### Long Value

Values of any length are copied in full; the confirmation toast shows only its title and doesn't echo the copied text.

```tsx
import { CopyButton } from '@plocks/ui';

const longToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.long.payload.value.with.many.sections.and.characters.for.demo.purposes.only';

export function Demo() {
  return <CopyButton value={longToken} iconOnly={false} label="Copy Token" />;
}
```

### No Toast

Copy control with toast notifications disabled.

```tsx
import { CopyButton } from '@plocks/ui';

export function Demo() {
  return <CopyButton value="hunter2" iconOnly={false} disableToast />;
}
```

### Sizes

Scale the copy affordance with the `size` prop, from `xs` through `3xl`.

```tsx
import { Block, CopyButton, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <CopyButton size={size} value="@plocks/ui" />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/DataList.md -->

# DataList

DataList displays label and value pairs in an aligned list.

## Metadata

- Import: `import { DataList } from '@plocks/ui';`
- Tags: datalist, description, definition, key-value, label, value, details
- Docs: https://plocks.dev/components/DataList
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/DataList

## Props

- `children`: ReactNode — `DataList.Item` children. Ignored when `data` is provided.
- `data`: DataListDataItem[] — Shorthand for rendering items without composing `DataList.Item` manually
- `orientation`: 'horizontal' | 'vertical' — Layout direction of each label/value pair
- `withDivider`: boolean — Render a divider between items
- `size`: ComponentSizeValue — Controls font size and spacing (theme font-size / spacing tokens, or a px font size)
- `spacing`: ComponentSizeValue | number — Override the vertical gap between items (theme spacing token or px)
- `labelWidth`: number | string — Width of the label column in horizontal orientation (px or percentage)
- `labelColor`: string — Override the label text color for all items
- `valueColor`: string — Override the value text color for all items
- `dividerColor`: string — Override the divider color when `withDivider` is set
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### DataList.Item

- `children`: ReactNode — Item content. Compose with `DataList.ItemLabel` / `DataList.ItemValue`.
- `label`: ReactNode — Shorthand label content (rendered when `children` is not provided)
- `value`: ReactNode — Shorthand value content (rendered when `children` is not provided)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### DataList.ItemLabel

- `children`: ReactNode
- `c`: string — Override the label text color
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### DataList.ItemValue

- `children`: ReactNode
- `c`: string — Override the value text color
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface DataListDataItem {
  /** Label / term content */
  label: ReactNode;
  /** Value / definition content */
  value: ReactNode;
}
```

## Examples

### Basics

Compose `DataList.Item` with `DataList.ItemLabel` and `DataList.ItemValue` to render aligned label/value pairs.

```tsx
import { DataList } from '@plocks/ui';

export function Demo() {
  return (
    <DataList>
      <DataList.Item>
        <DataList.ItemLabel>Name</DataList.ItemLabel>
        <DataList.ItemValue>John Doe</DataList.ItemValue>
      </DataList.Item>
      <DataList.Item>
        <DataList.ItemLabel>Email</DataList.ItemLabel>
        <DataList.ItemValue>john@example.com</DataList.ItemValue>
      </DataList.Item>
      <DataList.Item>
        <DataList.ItemLabel>Role</DataList.ItemLabel>
        <DataList.ItemValue>Software Engineer</DataList.ItemValue>
      </DataList.Item>
    </DataList>
  );
}
```

### Vertical Orientation

Set `orientation="vertical"` to stack each label above its value — useful for longer values or narrow layouts.

```tsx
import { DataList } from '@plocks/ui';

export function Demo() {
  return (
    <DataList orientation="vertical">
      <DataList.Item>
        <DataList.ItemLabel>Shipping address</DataList.ItemLabel>
        <DataList.ItemValue>2825 Winding Way, Providence, RI 02908</DataList.ItemValue>
      </DataList.Item>
      <DataList.Item>
        <DataList.ItemLabel>Tracking number</DataList.ItemLabel>
        <DataList.ItemValue>1Z 999 AA1 01 2345 6784</DataList.ItemValue>
      </DataList.Item>
      <DataList.Item>
        <DataList.ItemLabel>Estimated delivery</DataList.ItemLabel>
        <DataList.ItemValue>July 12, 2026</DataList.ItemValue>
      </DataList.Item>
    </DataList>
  );
}
```

### Dividers & Aligned Labels

Enable `withDivider` to separate items with a border, and set `labelWidth` to keep the value column aligned.

```tsx
import { DataList } from '@plocks/ui';

export function Demo() {
  return (
    <DataList withDivider labelWidth={120}>
      <DataList.Item>
        <DataList.ItemLabel>Plan</DataList.ItemLabel>
        <DataList.ItemValue>Pro (annual)</DataList.ItemValue>
      </DataList.Item>
      <DataList.Item>
        <DataList.ItemLabel>Seats</DataList.ItemLabel>
        <DataList.ItemValue>12 of 20 used</DataList.ItemValue>
      </DataList.Item>
      <DataList.Item>
        <DataList.ItemLabel>Renews</DataList.ItemLabel>
        <DataList.ItemValue>January 1, 2027</DataList.ItemValue>
      </DataList.Item>
    </DataList>
  );
}
```

### Sizes

Use the `size` prop (`xs`–`3xl`, or a number) to scale font size and spacing together.

```tsx
import { Block, DataList, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" c="secondary">{size}</Text>
          <DataList size={size} labelWidth={90}>
            <DataList.Item label="Status" value="Active" />
            <DataList.Item label="Region" value="us-east-1" />
          </DataList>
        </Block>
      ))}
    </Block>
  );
}
```

### Data Prop Shorthand

Skip the composition and pass a `data` array of `{ label, value }` objects to render items automatically.

```tsx
import { DataList } from '@plocks/ui';

const details = [
  { label: 'Order', value: '#SS-10428' },
  { label: 'Placed', value: 'July 3, 2026' },
  { label: 'Total', value: '$248.00' },
  { label: 'Payment', value: 'Visa •••• 4242' },
];

export function Demo() {
  return <DataList data={details} withDivider labelWidth={100} />;
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/DataTable.md -->

# DataTable

DataTable displays tabular data with sorting, pagination, selection, and editable cells.

## Metadata

- Import: `import { DataTable } from '@plocks/ui';`
- Docs: https://plocks.dev/components/DataTable
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/DataTable

## Props

- `id`: string — Stable id for user preference persistence
- `data` (required): T[] — Data rows
- `columns` (required): DataTableColumn<T>[] — Column definitions
- `loading`: boolean = false — Loading state
- `error`: string | null = null — Error message (when defined overrides table body)
- `emptyMessage`: string = 'No data available' — Message to display when there is no data
- `searchable`: boolean = true — Enable global search input
- `searchPlaceholder`: string = 'Search...' — Placeholder text for global search
- `searchValue`: string — Controlled global search value
- `onSearchChange`: (value: string) => void — Global search change handler
- `sortBy`: DataTableSort[] = NO_SORT — Current sorting state
- `onSortChange`: (sort: DataTableSort[]) => void — Sorting change callback
- `filters`: DataTableFilter[] = NO_FILTERS — Active column filters
- `onFilterChange`: (filters: DataTableFilter[]) => void — Filter change callback
- `showColumnFilters`: boolean = false — Render an always-visible filter row directly beneath the column headers. Each `filterable` column gets an inline control — a text input for text/number/date columns and a dropdown for `select`/`boolean` columns (options auto-derived from the data when `filterOptions` is omitted). This is separate from the per-header filter popover and can be used alongside it.
- `pagination`: DataTablePagination — Pagination state
- `onPaginationChange`: (pagination: DataTablePagination) => void — Pagination change handler
- `manualPagination`: boolean = false — Server-side (manual) pagination for API-backed tables. When true the `data` prop is treated as the already-fetched current page: the table performs no client-side slicing, filtering, sorting, or search, and uses `pagination.total` as the authoritative row count for the page count and "X-Y of N" summary. The sort / filter / search controls still fire their respective callbacks so you can refetch — use them in controlled mode (`sortBy`+`onSortChange`, `filters`+`onFilterChange`, `searchValue`+ `onSearchChange`). Requires `pagination.total` to be set.
- `paginationProps`: Omit<PaginationProps, 'value' | 'defaultValue' | 'current' | 'total' | 'onChange'> — Props forwarded to the underlying `Pagination` component in the footer (e.g. `siblings`, `boundaries`, `variant`, `size`, `color`, `showFirst`, `showPrevNext`, `labels`). Values here override the DataTable defaults, so you can also disable the built-in total (`showTotal={false}`) or size changer (`showSizeChanger={false}`).
- `selectable`: boolean = false — Enable row selection
- `showColumnMenu`: boolean = true — Show the per-column options menu in each header.
- `selectedRows`: DataTableRowId[] — Selected row identifiers (controlled). Leave undefined to let the table manage selection itself; `onSelectionChange` fires in both modes.
- `onSelectionChange`: (selected: DataTableRowId[]) => void — Selection change handler
- `getRowId`: (row: T, index: number) => DataTableRowId = defaultGetRowId — Stable row ID; required for selection, expansion, and edit mode.
- `onRowClick`: (row: T, index: number) => void — Row activation handler: fires when a body cell is pressed / clicked, or activated with Enter / Space from the keyboard (web). In edit mode an editable cell starts editing instead.
- `editMode`: boolean = false — Whether table is in edit mode
- `onEditModeChange`: (editMode: boolean) => void — Edit mode toggle callback
- `onCellEdit`: (rowIndex: number, columnKey: string, newValue: DataTableValue, rowId: DataTableRowId, row: T) => void — Commit cell edit. The index is the current visible index; rowId and row identify the record.
- `bulkActions`: DataTableBulkAction<T>[] = NO_BULK_ACTIONS — Bulk action definitions
- `variant`: 'default' | 'striped' | 'bordered' = 'default' — Visual table variant
- `density`: 'compact' | 'normal' | 'comfortable' = 'normal' — Row density
- `h`: number — Height of the table frame in px; the body scrolls inside it. The toolbar and pagination sit outside it, so it does not size the root.
- `virtual`: boolean = false — Enable FlashList-powered virtualization for large datasets. The list is bounded by `h` (420 by default), so only the visible rows mount.
- `enableColumnResizing`: boolean = false — Enable interactive column resizing
- `rowFeatureToggle`: (row: T, index: number) => DataTableRowFeatures | null | undefined — Per-row feature overrides
- `initialHiddenColumns`: string[] = NO_KEYS — Initially hidden column keys
- `onColumnVisibilityChange`: (hidden: string[]) => void — Called with the hidden column keys whenever the set changes (not on mount).
- `showColumnVisibilityManager`: boolean = true — Show built-in column visibility manager button
- `rowsPerPageOptions`: number[] = DEFAULT_PAGE_SIZES — Pagination size choices
- `showRowsPerPageControl`: boolean = true — Show rows-per-page selector
- `rowActions`: (row: T, index: number) => DataTableRowAction<T>[] — Per-row action icon buttons (renders trailing actions column when provided)
- `actionsColumnWidth`: number = 100 — Width of the actions column
- `striped`: boolean — Force striped row backgrounds regardless of variant
- `headerBackgroundColor`: string — Header row background. Defaults to `theme.backgrounds.subtle`.
- `enhancedLoading`: boolean = true — Show skeleton rows while `loading` (default). `false` shows a single "Loading…" row instead.
- `enhancedEmptyState`: boolean = true — Show the illustrated empty state (icon, title and `emptyMessage`) — default. `false` shows `emptyMessage` as a plain row.
- `hoverColor`: string — Row hover fill. Defaults to `theme.backgrounds.hover`.
- `enhancedSelection`: boolean = true — Draw an accent bar on the leading edge of selected rows (default). `false` marks selection with the row fill only.
- `showRowDividers`: boolean — Horizontal hairlines between rows. Defaults to on for `variant="bordered"` and off otherwise; set explicitly to override either way. `rowBorderWidth` takes precedence when provided.
- `borderColor`: string — Default color for the outer border, row dividers and column dividers (each can still be overridden by its own `*BorderColor` prop).
- `hoverHighlight`: boolean = true — Enable simple row background hover highlight
- `fullWidth`: boolean = true — Make table take full width of container
- `rowBorderWidth`: number — Row border width. Overrides `showRowDividers` / the variant default, including at 0.
- `rowBorderColor`: string — Custom row border color
- `rowBorderStyle`: 'solid' | 'dashed' | 'dotted' = 'solid' — Row border style
- `columnBorderWidth`: number — Vertical rules between columns, off unless set — `variant="bordered"` only draws row dividers and the outer border. The rule spans the header, filter row, body, and group/footer rows.
- `columnBorderColor`: string — Custom column border color
- `columnBorderStyle`: 'solid' | 'dashed' | 'dotted' = 'solid' — Column border style
- `showOuterBorder`: boolean = true — Whether to show outer border around entire table. Defaults to `true`.
- `outerBorderWidth`: number = 1 — Outer border width
- `outerBorderColor`: string — Outer border color
- `expandableRowRender`: (row: T, index: number) => React.ReactNode — Function to render expanded row content
- `initialExpandedRows`: DataTableRowId[] = NO_EXPANDED — Initially expanded row identifiers
- `expandedRows`: DataTableRowId[] — Controlled expanded rows
- `onExpandedRowsChange`: (expanded: DataTableRowId[]) => void — Expanded rows change handler
- `allowMultipleExpanded`: boolean = true — Allow multiple rows to be expanded at once
- `expandIcon`: React.ReactNode — Custom expand/collapse icons
- `collapseIcon`: React.ReactNode
- `headerTextProps`: Omit<TextProps, 'children'> — Override props applied to every column header `<Text>` (style, weight, ff, size, color).
- `cellTextProps`: Omit<TextProps, 'children'> — Override props applied to default-rendered cell text (cells without a custom `cell` renderer).
- `ariaLabel`: string — Accessible name for the table, exposed as `aria-label` (screen readers announce it when entering the table). No name is set when omitted.
- `exportable`: boolean = false — Show a CSV export button in the toolbar. Exports the current view (filtered + sorted, all pages) using the visible columns.
- `exportFileName`: string = 'data.csv' — File name for the downloaded CSV (default: "data.csv").
- `onExport`: (csv: string, rows: T[]) => void — Called with the generated CSV string and the exported rows. When provided it replaces the built-in web download (use it to handle export on native or to post the data elsewhere).
- `enableColumnReordering`: boolean = false — Enable drag-to-reorder of column headers (web).
- `columnOrder`: string[] — Controlled column order (array of column keys).
- `onColumnOrderChange`: (order: string[]) => void — Called with the new key order after a drag-reorder.
- `groupBy`: string — Group rows by this column key. Renders a collapsible group-header row before each group (showing the value, count, and per-column aggregates). Grouping spans all filtered rows, so client pagination is bypassed while active, and it is not applied in `virtual` mode.
- `groupsDefaultExpanded`: boolean = true — Whether groups start expanded (default: true).
- `renderGroupHeader`: (info: DataTableGroupHeaderInfo<T>) => React.ReactNode — Custom renderer for the group-header label cell.
- `showFooterTotals`: boolean = false — Render a footer row with grand-total aggregates for aggregate columns.
- `footerLabel`: string = 'Total' — Label shown in the first cell of the footer totals row (default: "Total").
- `w`: DimensionProp — Width
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface DataTableColumn<T = DataTableValue> {
  /** Unique identifier for the column */
  key: string;
  /** Display header for the column */
  header: React.ReactNode;
  /** Accessor function or key path */
  accessor: keyof T | ((row: T) => DataTableValue);
  /** Custom cell renderer */
  cell?: (value: DataTableValue, row: T, index: number) => React.ReactNode;
  /** Whether column is sortable */
  sortable?: boolean;
  /** Optional custom comparison function overriding default sorting */
  compare?: (a: DataTableValue, b: DataTableValue, rowA: T, rowB: T) => number;
  /** Whether column is filterable */
  filterable?: boolean;
  /** Filter type for this column */
  filterType?: FilterType;
  /** Filter options for select filter type */
  filterOptions?: Array<{ label: string; value: DataTableValue }>;
  /** Preferred width */
  width?: number | string;
  /** Minimum width */
  minWidth?: number;
  /** Maximum width */
  maxWidth?: number;
  /** Whether the user can resize this column */
  resizable?: boolean;
  /** Whether cells in this column are editable (when table in edit mode) */
  editable?: boolean;
  /** Validation function returning an error message or null */
  validate?: (value: DataTableValue) => string | null;
  /** Data type for formatting & validation */
  dataType?: ColumnDataType;
  /**
   * Content alignment. `left` / `right` are the leading / trailing edges, so
   * they follow the layout direction in RTL.
   */
  align?: 'left' | 'center' | 'right';
  /**
   * Pin the column during horizontal scroll (web). `left` pins it to the
   * leading edge and `right` to the trailing edge (mirrored in RTL).
   */
  sticky?: 'left' | 'right';
  /**
   * Aggregation for this column, shown in group-header rows (per group) and the
   * footer totals row (grand total). Numeric results are formatted with the
   * column's `dataType`; pass a function for custom aggregates.
   */
  aggregate?: AggregateType<T>;
  /** Custom formatter for this column's aggregate value. */
  aggregateFormat?: (value: number | string) => React.ReactNode;
}

export interface DataTableSort {
  column: string;
  direction: SortDirection;
}

export interface DataTableFilter {
  column: string;
  value: DataTableValue;
  operator: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'contains' | 'startsWith' | 'endsWith';
}

export interface DataTablePagination {
  page: number;
  pageSize: number;
  total: number;
}

export type DataTableRowId = string | number;

export type DataTableValue = any;

export interface DataTableBulkAction<T = DataTableValue> {
  /** Unique key */
  key: string;
  /** Button label */
  label: string;
  /** Optional icon */
  icon?: React.ReactNode;
  /** Action invoked with selected row ids & full data */
  action: (selectedRows: DataTableRowId[], data: T[]) => void;
}

export interface DataTableRowFeatures {
  selectable?: boolean;
  editable?: boolean;
  sortable?: boolean;
  filterable?: boolean;
  searchable?: boolean;
}
```

## Examples

### Basics

Define columns, feed the dataset, and let `DataTable` handle search, sorting, and pagination out of the box.

```tsx
import { useState } from 'react';
import { DataTable } from '@plocks/ui';
import type { DataTableColumn, DataTablePagination, DataTableSort } from '@plocks/ui';

import { people, type Person } from '../data';

const columns: DataTableColumn<Person>[] = [
  { key: 'name', header: 'Name', accessor: 'name', sortable: true },
  { key: 'email', header: 'Email', accessor: 'email', sortable: true, minWidth: 200 },
  { key: 'title', header: 'Role', accessor: 'title', sortable: true },
  { key: 'department', header: 'Department', accessor: 'department', sortable: true, minWidth: 160 },
];

export function Demo() {
  const [sortBy, setSortBy] = useState<DataTableSort[]>([]);
  const [pagination, setPagination] = useState<DataTablePagination>({
    page: 1,
    pageSize: 5,
    total: people.length,
  });

  return (
    <DataTable
      data={people}
      columns={columns}
      sortBy={sortBy}
      onSortChange={setSortBy}
      pagination={pagination}
      onPaginationChange={setPagination}
      searchable
      searchPlaceholder="Search teammates"
    />
  );
}
```

`data.ts`

```ts
/**
 * Shared fixtures for the DataTable demos.
 *
 * `Person` is deliberately wider than any single demo needs: each demo picks the
 * columns that illustrate its feature, so one directory of people can stand in
 * for a team roster, an access-control list, and a payroll table at once.
 */

export type Person = {
  id: number;
  name: string;
  email: string;
  /** Job title — what the person does. */
  title: string;
  /** Access level — what the person may do. Drives the select-filter demos. */
  role: 'Admin' | 'Editor' | 'Viewer';
  department: 'Engineering' | 'Design' | 'Marketing' | 'Sales';
  team: string;
  location: string;
  phone: string;
  startDate: string;
  lastLogin: string;
  status: 'active' | 'inactive' | 'pending';
  remote: boolean;
  salary: number;
  /** 1–5 review score, for demos that render a numeric cell. */
  performance: number;
};

export const people: Person[] = [
  { id: 1, name: 'Dana Moss', email: 'dana@example.com', title: 'Staff Engineer', role: 'Admin', department: 'Engineering', team: 'Platform', location: 'Berlin', phone: '+49 30 1234567', startDate: '2019-04-02', lastLogin: '2025-03-04', status: 'active', remote: true, salary: 148_000, performance: 4.7 },
// … 95 more lines — full file: https://github.com/platform-blocks/plocks/blob/main/packages/ui/src/components/DataTable/demos/data.ts
```

### Column Filters

Mark columns `filterable` and set `filterType` to pick the control: an input for `text`/`number`/`date`, a dropdown for `select`/`boolean` (options auto-derived from the data when `filterOptions` is omitted). `showColumnFilters` renders those controls as a persistent row under the headers; omit it to keep them in each header's filter menu.

```tsx
import { useState } from 'react';
import { DataTable } from '@plocks/ui';
import type { DataTableColumn, DataTableFilter } from '@plocks/ui';

import { departmentFilterOptions, people, statusFilterOptions, type Person } from '../data';

const columns: DataTableColumn<Person>[] = [
  // text → inline text input
  { key: 'name', header: 'Name', accessor: 'name', sortable: true, filterable: true, filterType: 'text' },
  // select with explicit options → dropdown
  {
    key: 'department',
    header: 'Department',
    accessor: 'department',
    sortable: true,
    filterable: true,
    filterType: 'select',
    filterOptions: departmentFilterOptions,
  },
  {
    key: 'status',
    header: 'Status',
    accessor: 'status',
    sortable: true,
    filterable: true,
    filterType: 'select',
    filterOptions: statusFilterOptions,
  },
  // boolean → Yes / No / All dropdown
  { key: 'remote', header: 'Remote', accessor: 'remote', filterable: true, filterType: 'boolean', cell: (v) => (v ? 'Yes' : 'No') },
  // number → inline numeric input
  {
    key: 'salary',
    header: 'Salary',
    accessor: 'salary',
    sortable: true,
    filterable: true,
    filterType: 'number',
    dataType: 'currency',
    align: 'right',
  },
];

export function Demo() {
  const [filters, setFilters] = useState<DataTableFilter[]>([]);

  return (
    <DataTable
      data={people}
      columns={columns}
      filters={filters}
      onFilterChange={setFilters}
      showColumnFilters
      searchable={false}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Variants

Compare the default, striped, and bordered table treatments using the same rows.

```tsx
import { Column, DataTable, Text } from '@plocks/ui';

const rows = [
  { id: 1, name: 'Avery', role: 'Designer' },
  { id: 2, name: 'Jordan', role: 'Engineer' },
];
const columns = [
  { key: 'name', header: 'Name', accessor: 'name' as const },
  { key: 'role', header: 'Role', accessor: 'role' as const },
];
const variants = ['default', 'striped', 'bordered'] as const;

export function Demo() {
  return (
    <Column gap="lg" fullWidth>
      {variants.map(variant => (
        <Column key={variant} gap="xs" fullWidth>
          <Text fw="semibold">{variant}</Text>
          <DataTable data={rows} columns={columns} variant={variant} />
        </Column>
      ))}
    </Column>
  );
}
```

### Row Selection

Set `selectable` and wire `selectedRows` / `onSelectionChange` to track checked rows. Pass a stable `getRowId` so selection survives sorting and paging; the table requires it for selection.

```tsx
import { useState } from 'react';
import { Block, DataTable, Text } from '@plocks/ui';
import type { DataTableColumn, DataTablePagination } from '@plocks/ui';

import { people, type Person } from '../data';

const columns: DataTableColumn<Person>[] = [
  { key: 'name', header: 'Name', accessor: 'name', sortable: true },
  { key: 'email', header: 'Email', accessor: 'email', sortable: true, minWidth: 200 },
  { key: 'role', header: 'Role', accessor: 'role', sortable: true },
];

export function Demo() {
  const [pagination, setPagination] = useState<DataTablePagination>({
    page: 1,
    pageSize: 5,
    total: people.length,
  });
  const [selectedRows, setSelectedRows] = useState<(string | number)[]>([]);

  return (
    <Block fullWidth>
      <Text size="sm" c={selectedRows.length ? 'primary' : 'muted'}>
        {selectedRows.length ? `${selectedRows.length} selected` : 'No rows selected'}
      </Text>

      <DataTable
        data={people}
        columns={columns}
        pagination={pagination}
        onPaginationChange={setPagination}
        selectable
        selectedRows={selectedRows}
        onSelectionChange={setSelectedRows}
        getRowId={(row) => row.id}
        searchable={false}
      />
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Rich Cells

Combine avatars, chips, and status cues inside custom `cell` renderers to create a readable, on-brand table.

```tsx
import { Avatar, Chip, DataTable, Text } from '@plocks/ui';
import type { DataTableColumn } from '@plocks/ui';

import { people, type Person } from '../data';

const rows = people.slice(0, 5);

const columns: DataTableColumn<Person>[] = [
  {
    key: 'name',
    header: 'Teammate',
    accessor: 'name',
    sortable: true,
    cell: (_value, row) => (
      <Avatar
        size="sm"
        fallback={row.name
          .split(' ')
          .map((part) => part[0])
          .join('')}
        label={<Text fw="semibold">{row.name}</Text>}
        description={<Text variant="small" c="muted">{row.title}</Text>}
        gap={8}
      />
    ),
  },
  {
    key: 'team',
    header: 'Team',
    accessor: 'team',
    sortable: true,
    cell: (value) => (
      <Chip size="xs" color="primary" variant="light">
        {value}
      </Chip>
    ),
  },
  {
    key: 'status',
    header: 'Status',
    accessor: 'status',
    sortable: true,
    cell: (value: Person['status']) => (
      <Text
        c={value === 'inactive' ? 'error' : value === 'pending' ? 'warning' : 'success'}
        fw="semibold"
      >
        {value.charAt(0).toUpperCase() + value.slice(1)}
      </Text>
    ),
  },
  {
    key: 'performance',
    header: 'Score',
    accessor: 'performance',
    sortable: true,
    align: 'right',
    cell: (value) => <Text fw="semibold">{value.toFixed(1)}</Text>,
  },
];

export function Demo() {
  return (
    <DataTable
      data={rows}
      columns={columns}
      density="comfortable"
      variant="striped"
      searchable={false}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Expandable Rows

Provide `expandedRows`, update them via `onExpandedRowsChange`, and use `expandableRowRender` to reveal supporting context.

```tsx
import { useState } from 'react';
import { Block, DataTable, Text } from '@plocks/ui';
import type { DataTableColumn } from '@plocks/ui';

import { projects, type Project } from '../data';

const columns: DataTableColumn<Project>[] = [
  { key: 'name', header: 'Project', accessor: 'name', sortable: true },
  { key: 'owner', header: 'Owner', accessor: 'owner', sortable: true },
  {
    key: 'budget',
    header: 'Budget',
    accessor: 'budget',
    align: 'right',
    sortable: true,
    dataType: 'currency',
  },
];

export function Demo() {
  const [expandedRows, setExpandedRows] = useState<(string | number)[]>([projects[0].id]);

  return (
    <DataTable
      data={projects}
      columns={columns}
      getRowId={(row) => row.id}
      expandedRows={expandedRows}
      onExpandedRowsChange={setExpandedRows}
      expandableRowRender={(project) => (
        <Block p="md">
          <Text c="muted">{project.summary}</Text>
        </Block>
      )}
      searchable={false}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Grouping & Totals

Set `groupBy` to a column key to group rows under collapsible group-header rows. Add `aggregate` (`sum`, `avg`, `min`, `max`, `count`, or a function) to any column to show its per-group total in the group header, and set `showFooterTotals` for a grand-total footer row aligned to the same columns. Grouping spans all filtered rows, so client pagination is bypassed while it is active.

```tsx
import { DataTable } from '@plocks/ui';
import type { DataTableColumn } from '@plocks/ui';

import { sales as rows, type Sale } from '../data';

const columns: DataTableColumn<Sale>[] = [
  { key: 'region', header: 'Region', accessor: 'region' },
  { key: 'rep', header: 'Rep', accessor: 'rep', aggregate: 'count' },
  { key: 'product', header: 'Product', accessor: 'product' },
  { key: 'units', header: 'Units', accessor: 'units', dataType: 'number', align: 'right', aggregate: 'sum' },
  { key: 'revenue', header: 'Revenue', accessor: 'revenue', dataType: 'currency', align: 'right', aggregate: 'sum' },
];

export function Demo() {
  return (
    <DataTable
      data={rows}
      columns={columns}
      groupBy="region"
      showFooterTotals
      footerLabel="All regions"
      searchable={false}
      showColumnVisibilityManager={false}
    />
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Fixed height & sticky columns

Pass a fixed `h` to cap the table's size — the header row stays pinned while the body scrolls, so a long list fits a constrained panel without paginating. Pin columns to the edges with `sticky: 'left'` or `sticky: 'right'` so they stay put while the rest scroll horizontally; give each pinned column an explicit numeric `width` so its frozen offset lines up. Sticky positioning is web-only (a no-op on native).

```tsx
import { DataTable } from '@plocks/ui';
import type { DataTableColumn } from '@plocks/ui';

type Server = {
  id: number;
  host: string;
  region: string;
  cpu: string;
  memory: string;
  uptime: string;
  status: 'healthy' | 'degraded' | 'offline';
};

const REGIONS = ['us-east-1', 'us-west-2', 'eu-west-1', 'ap-south-1'];
const STATUSES: Server['status'][] = ['healthy', 'degraded', 'offline'];

const rows: Server[] = Array.from({ length: 40 }, (_, i) => ({
  id: i + 1,
  host: `node-${String(i + 1).padStart(2, '0')}.cluster.internal`,
  region: REGIONS[i % REGIONS.length],
  cpu: `${((i * 7) % 90) + 5}%`,
  memory: `${((i * 13) % 80) + 10}%`,
  uptime: `${(i % 30) + 1}d`,
  status: STATUSES[i % STATUSES.length],
}));

const columns: DataTableColumn<Server>[] = [
  // Pinned left, so the host stays visible while the rest scroll horizontally.
  { key: 'host', header: 'Host', accessor: 'host', sticky: 'left', width: 240, sortable: true },
  { key: 'region', header: 'Region', accessor: 'region', width: 160, sortable: true },
  { key: 'cpu', header: 'CPU', accessor: 'cpu', width: 120, align: 'right', sortable: true },
  { key: 'memory', header: 'Memory', accessor: 'memory', width: 120, align: 'right', sortable: true },
  { key: 'uptime', header: 'Uptime', accessor: 'uptime', width: 120, align: 'right' },
  { key: 'status', header: 'Status', accessor: 'status', sticky: 'right', width: 140, sortable: true },
];

export function Demo() {
  return (
    <DataTable
      data={rows}
      columns={columns}
      getRowId={(row) => row.id}
      h={320}
      fullWidth={false}
      searchable={false}
    />
  );
}
```

### Server-side pagination

Set `manualPagination` when the data comes from a paginated API. The `data` prop is treated as the already-fetched current page — the table does no client-side slicing, filtering, or sorting — and `pagination.total` drives the page count and "X-Y of N" summary. The sort, filter, search, and page controls still fire their callbacks (`onSortChange`, `onFilterChange`, `onSearchChange`, `onPaginationChange`) so you can refetch. Pair it with `loading` to show the skeleton during each fetch.

```tsx
import { useEffect, useState } from 'react';
import { DataTable } from '@plocks/ui';
import type { DataTableColumn, DataTablePagination, DataTableSort } from '@plocks/ui';

type Order = {
  id: number;
  customer: string;
  product: string;
  amount: number;
};

// Pretend this table lives on a server; the component only ever sees one page.
const DB: Order[] = Array.from({ length: 137 }, (_, i) => ({
  id: i + 1,
  customer: `Customer ${String(i + 1).padStart(3, '0')}`,
  product: ['Starter', 'Pro', 'Team', 'Enterprise'][i % 4],
  amount: Math.round(((i * 37) % 900) + 100),
}));

// Simulate an API endpoint: GET /orders?page&pageSize&sort
function fetchOrders(
  page: number,
  pageSize: number,
  sort?: DataTableSort
): Promise<{ rows: Order[]; total: number }> {
  return new Promise((resolve) => {
    setTimeout(() => {
      const sorted = [...DB];
      if (sort?.direction) {
        sorted.sort((a, b) => {
          const av = a[sort.column as keyof Order];
          const bv = b[sort.column as keyof Order];
          const cmp = typeof av === 'number' && typeof bv === 'number' ? av - bv : String(av).localeCompare(String(bv));
          return sort.direction === 'desc' ? -cmp : cmp;
        });
      }
      const start = (page - 1) * pageSize;
      resolve({ rows: sorted.slice(start, start + pageSize), total: DB.length });
    }, 500);
  });
}

const columns: DataTableColumn<Order>[] = [
  { key: 'id', header: 'Order', accessor: 'id', sortable: true, dataType: 'number' },
  { key: 'customer', header: 'Customer', accessor: 'customer', sortable: true },
  { key: 'product', header: 'Plan', accessor: 'product', sortable: true },
  { key: 'amount', header: 'Amount', accessor: 'amount', sortable: true, dataType: 'currency' },
];

export function Demo() {
  const [rows, setRows] = useState<Order[]>([]);
  const [loading, setLoading] = useState(true);
  const [sortBy, setSortBy] = useState<DataTableSort[]>([]);
  const [pagination, setPagination] = useState<DataTablePagination>({ page: 1, pageSize: 10, total: 0 });

  // Refetch whenever the page, page size, or sort changes.
  useEffect(() => {
    let cancelled = false;
    setLoading(true);
    fetchOrders(pagination.page, pagination.pageSize, sortBy[0]).then((res) => {
      if (cancelled) return;
      setRows(res.rows);
      setPagination((p) => (p.total === res.total ? p : { ...p, total: res.total }));
      setLoading(false);
    });
    return () => {
      cancelled = true;
    };
  }, [pagination.page, pagination.pageSize, sortBy]);

  return (
    <DataTable
      data={rows}
      columns={columns}
      loading={loading}
      manualPagination
      pagination={pagination}
      onPaginationChange={setPagination}
      sortBy={sortBy}
      onSortChange={setSortBy}
      getRowId={(row) => row.id}
      searchable={false}
    />
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/DatePicker.md -->

# DatePicker

DatePicker renders an inline calendar focused on keyboard-friendly, accessible selection flows.

## Metadata

- Import: `import { DatePicker } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/DatePicker
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/DatePicker

## Props

- `value`: CalendarValue — Selected value; type depends on `type` prop
- `defaultValue`: CalendarValue — Initial value for uncontrolled usage
- `onChange`: (value: CalendarValue) => void — Called when value changes
- `type`: 'single' | 'multiple' | 'range' = 'single' — Selection behavior
- `calendarProps`: Partial<CoreCalendarProps> — Pass-through customization for underlying Calendar
- `accessibilityLabel`: string — Accessible name of the inline calendar, exposed as a `group` around it (every day stays individually reachable by screen readers).
- `accessibilityHint`: string — Extra description of the inline calendar (native `accessibilityHint`).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { Month, Day } from '@plocks/dates';`

### Month

- `month` (required): Date
- `value`: CalendarValue — Selection
- `onChange`: (value: CalendarValue) => void
- `type`: 'single' | 'multiple' | 'range'
- `hoveredDate`: Date | null
- `onDayHover`: (date: Date) => void
- `onDayHoverEnd`: () => void
- `minDate`: Date — Constraints
- `maxDate`: Date
- `excludeDate`: (date: Date) => boolean
- `firstDayOfWeek`: number — Display
- `weekendDays`: number[]
- `hideOutsideDates`: boolean
- `hideWeekdays`: boolean
- `highlightToday`: boolean
- `withCellSpacing`: boolean
- `getDayProps`: (date: Date) => Partial<DayProps> — Customization
- `renderDay`: (date: Date) => React.ReactNode
- `size`: SizeValue
- `locale`: string
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Day

- `date` (required): Date
- `selected`: boolean — States
- `inRange`: boolean
- `firstInRange`: boolean
- `lastInRange`: boolean
- `previewed`: boolean
- `previewedInRange`: boolean
- `previewedFirstInRange`: boolean
- `previewedLastInRange`: boolean
- `weekend`: boolean
- `outside`: boolean
- `today`: boolean
- `disabled`: boolean
- `size`: SizeValue — Styling
- `style`: StyleProp<ViewStyle>
- `locale`: string — Locale for the cell's accessible name (the full date). Default: the runtime locale.
- `children`: React.ReactNode — Custom content

## Examples

### Basics

Standard single date selection with label and placeholder text.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePicker } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <Block fullWidth>
      <DatePicker
        value={value}
        onChange={(next) => setValue(next as Date | null)}
        calendarProps={{ numberOfMonths: 1, highlightToday: true }}
      />
      <Text size="sm" c="secondary">
        {value ? `Selected: ${value.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Date Range Picker

Select a range of dates with start and end date selection.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePicker } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null] | null>(null);

  const start = value?.[0];
  const end = value?.[1];

  return (
    <Block fullWidth>
      <DatePicker
        type="range"
        value={value}
        onChange={(next) => setValue(next as [Date | null, Date | null] | null)}
        calendarProps={{ numberOfMonths: 2, withCellSpacing: true }}
      />
      <Text size="sm" c="secondary">
        {start && end
          ? `${start.toLocaleDateString()} – ${end.toLocaleDateString()}`
          : 'Select a start and end date'}
      </Text>
    </Block>
  );
}
```

### Date Validation

Date picker with validation rules and error handling for invalid selections.

```tsx
import React, { useMemo, useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePicker } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  const [inlineError, setInlineError] = useState('');

  const today = useMemo(() => {
    const date = new Date();
    date.setHours(0, 0, 0, 0);
    return date;
  }, []);

  const handleChange = (next: Date | [Date | null, Date | null] | Date[] | null) => {
    const dateValue = next as Date | null;
    setValue(dateValue);
    setInlineError(dateValue && dateValue < today ? 'Date cannot be in the past' : '');
  };

  return (
    <Block fullWidth>
      <DatePicker
        value={value}
        onChange={handleChange}
        calendarProps={{ minDate: today, highlightToday: true }}
      />
      <Text size="sm" c={inlineError ? 'error' : 'secondary'}>
        {inlineError || 'Only dates today or later are enabled'}
      </Text>
    </Block>
  );
}
```

### Multiple Dates Selection

Select multiple independent dates for events or availability.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePicker } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date[]>([]);

  return (
    <Block fullWidth>
      <DatePicker
        type="multiple"
        value={value}
        onChange={(next) => setValue((next as Date[]) ?? [])}
        calendarProps={{ numberOfMonths: 2, withCellSpacing: true }}
      />
      <Text size="sm" c="secondary">
        {value.length > 0
          ? value.map((date) => date.toLocaleDateString()).join(', ')
          : 'Select one or more dates'}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/DatePickerInput.md -->

# DatePickerInput

DatePickerInput opens a calendar from a form field to select a date.

## Metadata

- Import: `import { DatePickerInput } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/DatePickerInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/DatePickerInput

## Props

- `value`: CalendarValue — Selected value; type depends on `type` prop
- `defaultValue`: CalendarValue — Initial value for uncontrolled usage
- `onChange`: (value: CalendarValue) => void — Called when value changes
- `type`: 'single' | 'multiple' | 'range' = 'single' — Selection behavior
- `calendarProps`: Partial<CoreCalendarProps> — Pass-through customization for underlying Calendar
- `displayFormat`: string = 'MMMM d — Format string for displaying value in the input (tokens: yyyy, yy, MMMM, MMM, MM, M, dd, d).
- `dropdownType`: 'modal' | 'popover' = 'modal' — `modal` (default): a centered sheet. `popover`: a dropdown anchored to the field on desktop web (the sheet on native and small screens).
- `closeOnSelect`: boolean = true for `single` — Close the picker after a selection completes. @default true for `single`
- `modalTitle`: string — Title of the picker sheet / name of the popover. Defaults by `type` ("Select date", …).
- `onOpen`: () => void — Called when the picker opens.
- `onClose`: () => void — Called when the picker closes.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

DatePickerInput opens a calendar from a form field to select a date.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePickerInput } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <Block fullWidth>
      <DatePickerInput
        value={value}
        onChange={(next) => setValue(next as Date | null)}
        placeholder="Select a date"
        label="Date"
        clearable
        fullWidth
      />
      <Text size="sm" c="secondary">
        {value ? `Selected: ${value.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on DatePickerInput.

```tsx
import { Column } from '@plocks/ui';
import { DatePickerInput } from '@plocks/dates';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <DatePickerInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Choose a date" />
      ))}
    </Column>
  );
}
```

### Multiple

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePickerInput } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date[]>([]);

  return (
    <Block fullWidth>
      <DatePickerInput
        type="multiple"
        value={value}
        onChange={(next) => setValue((next as Date[]) || [])}
        label="Multiple dates"
        placeholder="Select dates"
        fullWidth
      />
      <Text size="sm" c="secondary">
        {value.length > 0
          ? `Selected: ${value.map((date) => date.toLocaleDateString()).join(', ')}`
          : 'Select one or more dates'}
      </Text>
    </Block>
  );
}
```

### Range

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePickerInput } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<[Date | null, Date | null] | null>(null);

  return (
    <Block fullWidth>
      <DatePickerInput
        type="range"
        value={value}
        onChange={(next) => setValue((next as [Date | null, Date | null]) || null)}
        label="Date range"
        placeholder="Select range"
        closeOnSelect
        fullWidth
      />
      <Text size="sm" c="secondary">
        {value && value[0] && value[1]
          ? `${value[0].toLocaleDateString()} – ${value[1].toLocaleDateString()}`
          : 'Select a start and end date'}
      </Text>
    </Block>
  );
}
```

### Validation

```tsx
import React, { useMemo, useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { DatePickerInput } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(null);
  const [error, setError] = useState<string | undefined>();

  const today = useMemo(() => {
    const date = new Date();
    date.setHours(0, 0, 0, 0);
    return date;
  }, []);

  const handleChange = (next: Date | [Date | null, Date | null] | Date[] | null) => {
    const dateValue = next as Date | null;
    setValue(dateValue);

    if (dateValue && dateValue < today) {
      setError('Date cannot be in the past');
    } else {
      setError(undefined);
    }
  };

  return (
    <Block fullWidth>
      <DatePickerInput
        value={value}
        onChange={handleChange}
        placeholder="Select a future date"
        label="Future date"
        error={error}
        clearable
        fullWidth
        calendarProps={{
          minDate: today,
          highlightToday: true,
        }}
      />
      <Text size="sm" c="secondary">
        Past dates show the validation state
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Dialog.md -->

# Dialog

The Dialog component presents content above the app, supporting focus trapping, scroll locking, and multiple presentation styles (modal, confirmation, bottom sheet).

## Metadata

- Import: `import { Dialog } from '@plocks/ui';`
- Status: experimental
- Tags: modal, dialog, overlay, sheet
- Docs: https://plocks.dev/components/Dialog
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Dialog

## Props

- `opened`: boolean = false — Whether the dialog is shown.
- `variant`: 'modal' | 'bottomsheet' | 'fullscreen' = 'modal' — Presentation style of the dialog. @default 'modal'
- `title`: string | null — Title shown in the header; also the dialog's accessible name.
- `accessibilityLabel`: string — Accessible name when there is no `title`.
- `children` (required): ReactNode — Dialog body content.
- `closable`: boolean = true — Allows the user to close the dialog via the close button, Escape and Android back. @default true
- `backdrop`: boolean = true — Whether to render the dimming backdrop behind the dialog. @default true
- `backdropClosable`: boolean = true — Whether tapping the backdrop should close the dialog. @default true
- `shouldClose`: boolean = false — Triggers the close animation when set to true.
- `onClose`: () => void — Called when the dialog requests to close (after the exit transition).
- `w`: number — Optional explicit width for the dialog content (modal/bottomsheet).
- `h`: number — Optional explicit height for the dialog content.
- `radius`: number — Corner radius for the dialog container (bottom sheet rounds top corners only).
- `style`: StyleProp<ViewStyle> — Style overrides for the dialog body.
- `showHeader`: boolean = true — Whether to paint the header area with the dialog surface. @default true
- `bottomSheetSwipeZone`: 'container' | 'handle' | 'none' = 'container' — Controls which part of the bottom sheet responds to swipe-to-dismiss gestures
- `transitionDuration`: number = 300 — Length of the open/close transition in ms; the built-in timings scale against a 300ms baseline. `0` shows and dismisses the dialog instantly. Always 0 under reduced motion.
- `titleProps`: Omit<TextProps, 'children'> — Override props applied to the title `<Text>` (style, weight, ff, size, color).
- `closeButtonLabel`: string = 'Close dialog' — Accessible label of the close button. @default 'Close dialog'
- `autoFocus`: DialogAutoFocus = false — Where focus lands when the dialog opens. See {@link DialogAutoFocus}.
- `trapFocus`: boolean = true — Keep Tab focus cycling inside the dialog while it is open (web). Focus always returns to the previously focused element when it closes.
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { DialogProvider, DialogRenderer } from '@plocks/ui';`

`DialogProvider`, `DialogRenderer` have no props interface of their own.

## Related hooks

- `useDialog(): DialogContextValue` — Returns the nearest `DialogProvider`'s full dialog API — the open `dialogs` list plus `openDialog`, `closeDialog`, `removeDialog` and `closeAllDialogs` — and never throws: outside a provider it returns a global bridge that queues calls until one mounts.
- `useDialogApi()` — Returns just the dialog actions (`openDialog`, `closeDialog`, `removeDialog`, `closeAllDialogs`) of the nearest `DialogProvider` without subscribing to the dialog list, so opening a dialog doesn't re-render the caller; outside a provider it returns a bridge that queues calls until one mounts.
- `useDialogs()` — Returns the nearest `DialogProvider`'s open dialogs (`DialogConfig[]`, in the order they were opened) and re-renders when the list changes — for custom dialog renderers and "is anything open?" checks; outside a provider it returns a non-reactive snapshot (empty when none is mounted) instead of throwing.
- `useSimpleDialog()` — Returns one-call dialog helpers — `modal`, `bottomSheet`, `fullScreen` and `confirm` (each returns the new dialog's id) plus `close(id)` and `closeAll()` — for opening common dialogs without building a `DialogConfig`; like `useDialog()` it never throws, but a `DialogProvider` with a `DialogRenderer` inside must be mounted for anything to show.

## Types

```ts
export type DialogAutoFocus = boolean | RefObject<DialogFocusable | null>;

export interface DialogFocusable {
  focus?: () => void;
}
```

## Examples

### Basics

Call `openDialog` with `variant: 'modal'` to show a titled dialog and wire action buttons to `closeDialog` when the user makes a choice.

```tsx
import { Block, Button, Row, Text, useDialog } from '@plocks/ui';

export function Demo() {
  const { openDialog, closeDialog } = useDialog();

  const showBasicDialog = () => {
    const dialogId = openDialog({
      variant: 'modal',
      title: 'Basic Dialog',
      content: (
        <Block>
          <Text>This is a basic modal dialog with theme-aware styling.</Text>
          <Row gap="sm" justify="flex-end" mt="sm">
            <Button variant="secondary" onPress={() => closeDialog(dialogId)}>
              Cancel
            </Button>
            <Button variant="filled" onPress={() => closeDialog(dialogId)}>
              OK
            </Button>
          </Row>
        </Block>
      )
    });
  };

  return (
    <Button onPress={showBasicDialog}>Open Basic Dialog</Button>
  );
}
```

### Bottom Sheet

Switch the dialog `variant` to `'bottomsheet'` to get swipe-to-dismiss behavior and retain full control with `closeDialog` handlers.

```tsx
import { Block, Button, Text, useDialog } from '@plocks/ui';

export function Demo() {
  const { openDialog, closeDialog } = useDialog();

  const showBottomSheetDialog = () => {
    const dialogId = openDialog({
      variant: 'bottomsheet',
      content: (
        <Block>
          <Text>This dialog slides up from the bottom with theme-aware styling.</Text>
          <Button variant="subtle" onPress={() => closeDialog(dialogId)}>
            Close
          </Button>
        </Block>
      )
    });
  };

  return (
    <Button onPress={showBottomSheetDialog}>Open Bottom Sheet</Button>
  );
}
```

### Variants

Open the modal, bottom sheet, and fullscreen presentations to compare their placement and dismissal.

```tsx
import { Button, Row, Text, useDialog } from '@plocks/ui';

const variants = ['modal', 'bottomsheet', 'fullscreen'] as const;

export function Demo() {
  const { openDialog } = useDialog();
  return (
    <Row gap="sm" wrap="wrap">
      {variants.map(variant => (
        <Button key={variant} variant="light" onPress={() => openDialog({
          variant,
          title: `${variant} dialog`,
          content: <Text>Dialog content in the {variant} presentation.</Text>,
        })}>
          Open {variant}
        </Button>
      ))}
    </Row>
  );
}
```

### Confirmation

Pair `variant: 'modal'` with a destructive button (`color="error"`) to confirm irreversible actions before calling your business logic.

```tsx
import { Block, Button, Row, Text, useDialog } from '@plocks/ui';

export function Demo() {
  const { openDialog, closeDialog } = useDialog();

  const showConfirmationDialog = () => {
    const dialogId = openDialog({
      variant: 'modal',
      title: 'Confirm Action',
      content: (
        <Block>
          <Text>Are you sure you want to delete this item?</Text>
          <Text size="sm" c="secondary">
            This action cannot be undone.
          </Text>
          <Row gap="sm" justify="flex-end" mt="sm">
            <Button variant="subtle" onPress={() => closeDialog(dialogId)}>
              Cancel
            </Button>
            <Button variant="filled" color="error" onPress={() => closeDialog(dialogId)}>
              Delete
            </Button>
          </Row>
        </Block>
      )
    });
  };

  return (
    <Button onPress={showConfirmationDialog}>Show Confirmation</Button>
  );
}
```

### Form Dialog

Embed inputs in the dialog `content`, collect values via controlled callbacks, and validate before resolving the promise or calling `closeDialog`.

```tsx
import { useRef } from 'react';
import { TextInput } from 'react-native';

import { Block, Button, Input, Row, useDialog } from '@plocks/ui';

export function Demo() {
  const { openDialog, closeDialog } = useDialog();
  const nameRef = useRef<TextInput>(null);

  const showFormDialog = () => {
    const formData = { name: '', email: '' };

    const dialogId = openDialog({
      variant: 'modal',
      title: 'Create Account',
      // Focus the name field once the open transition settles. `autoFocus: true`
      // picks the first focusable field automatically, but only on web — a ref
      // works on every platform.
      autoFocus: nameRef,
      content: (
        <Block>
          <Input
            inputRef={nameRef}
            placeholder="Your name"
            label="Name"
            onChangeText={(text) => {
              formData.name = text;
            }}
          />

          <Input
            placeholder="your@email.com"
            label="Email"
            keyboardType="email-address"
            onChangeText={(text) => {
              formData.email = text;
            }}
          />

          <Row gap="sm" justify="flex-end" mt="sm">
            <Button variant="secondary" onPress={() => closeDialog(dialogId)}>
              Cancel
            </Button>
            <Button
              variant="filled"
              onPress={() => {
                if (!formData.name || !formData.email) return;
                closeDialog(dialogId);
              }}
            >
              Create account
            </Button>
          </Row>
        </Block>
      )
    });
  };

  return (
    <Button onPress={showFormDialog}>Open Form Dialog</Button>
  );
}
```

### Title customization

`titleProps` accepts any `<Text>` props (`ff`, `fw`, `lts`, `tt`, `size`, `c`, `style`) and applies them to the dialog header without changing the rest of the chrome. The same prop is also accepted by `openDialog({ titleProps })` for imperative dialogs.

```tsx
import { Block, Button, Text, useDialog, type DialogConfig } from '@plocks/ui';

export function Demo() {
  const { openDialog } = useDialog();

  const open = (titleProps: DialogConfig['titleProps']) => {
    openDialog({
      variant: 'modal',
      title: 'Welcome aboard',
      titleProps,
      content: <Text>Dialog title styled via `titleProps`.</Text>,
    });
  };

  return (
    <Block>
      <Button onPress={() => open(undefined)}>Default</Button>
      <Button
        onPress={() =>
          open({
            tt: 'uppercase',
            lts: 1.5,
            fw: '700',
            size: 'sm',
          })
        }
      >
        Uppercase tracked
      </Button>
      <Button
        onPress={() =>
          open({
            ff: 'Georgia, serif',
            size: 'xl',
            fw: '600',
          })
        }
      >
        Serif headline
      </Button>
      <Button
        onPress={() =>
          open({
            c: 'primary',
            fw: '700',
            ff: 'monospace',
          })
        }
      >
        Brand-coloured monospace
      </Button>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Divider.md -->

# Divider

Divider separates content with a line or optional label.

## Metadata

- Import: `import { Divider } from '@plocks/ui';`
- Tags: divider, separator, line, section
- Docs: https://plocks.dev/components/Divider
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Divider

## Props

- `orientation`: 'horizontal' | 'vertical' — Layout direction of the line. `'horizontal'` spans width; `'vertical'` spans height. Defaults to `'horizontal'`.
- `variant`: 'solid' | 'dashed' | 'dotted' | 'gradient' — Visual style of the line. `'gradient'` fades transparent → color → transparent. Defaults to `'solid'`.
- `color`: ThemeColor — Line color. Accepts the named tokens `'border'` / `'subtle'` / `'muted'`, a palette name (`'success'` → a shade well below the accent, so a tinted rule still reads as chrome), `'primary.6'` shade syntax, or any CSS color. Defaults to `'border'`.
- `size`: SizeValue | number — Thickness of the divider (default 1). Accepts a size token or pixel value.
- `label`: React.ReactNode — Optional content rendered in the middle of the line. A string label is also the separator's accessible name.
- `labelPosition`: 'left' | 'center' | 'right' — Where the `label` sits along the line. `'left'` / `'right'` are the leading / trailing ends, so they mirror in right-to-left layouts. Defaults to `'center'`.
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>` (only when `label` is a string).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Insert horizontal dividers between sections to separate content; switch the `variant` prop to toggle between solid and dashed lines.

```tsx
import { Block, Divider, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Text variant="p" fw="medium">
        Q1 Highlights
      </Text>
      <Text variant="p">Revenue grew 12% year over year.</Text>
      <Divider />
      <Text variant="p">Customer retention improved across every region.</Text>
      <Divider variant="dashed" />
      <Text variant="p">Product roadmap updates will ship next quarter.</Text>
    </Block>
  );
}
```

### Color Variants

Set `color` to a line token (`border`, `subtle`, `muted`), a palette name like `primary` or `error`, or any CSS color. It defaults to `border`.

```tsx
import { Block, Divider, Text } from '@plocks/ui';

const COLORS = ['border', 'subtle', 'muted', 'gray', 'primary', 'secondary', 'success', 'warning', 'error'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {COLORS.map((color) => (
        <Block key={color} fullWidth>
          <Text variant="small" c="secondary">{color}</Text>
          <Divider color={color} />
        </Block>
      ))}
    </Block>
  );
}
```

### Gradient & opacity

The `gradient` variant fades transparent → color → transparent, perfect for breaking up sections without a hard edge. The `opacity` prop is a shorthand for `style={{ opacity }}` — combine it with `color` to dial in subtle separators.

```tsx
import { Block, Divider, Text } from '@plocks/ui';

const OPACITIES = [1, 0.5, 0.25];

export function Demo() {
  return (
    <Block fullWidth>
      <Block fullWidth>
        <Text variant="small" c="secondary">gradient</Text>
        <Divider variant="gradient" color="primary" />
      </Block>
      {OPACITIES.map((opacity) => (
        <Block key={opacity} fullWidth>
          <Text variant="small" c="secondary">opacity {opacity}</Text>
          <Divider color="primary" opacity={opacity} />
        </Block>
      ))}
    </Block>
  );
}
```

### Labeled Dividers

Provide a `label` node and adjust `labelPosition` plus `color` to separate form sections with contextual dividers.

```tsx
import { Block, Chip, Divider, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Text variant="p">Sign in with email</Text>
      <Divider label="or" />
      <Text variant="p">Continue with social accounts</Text>

      <Divider
        label={<Chip size="sm" variant="outline">Settings</Chip>}
        labelPosition="left"
        color="secondary"
      />
      <Text variant="p">Manage notification preferences</Text>

      <Divider label="Advanced options" labelPosition="right" color="primary" />
      <Text variant="p">Invite admins or export account data</Text>
    </Block>
  );
}
```

### Vertical Dividers

Switch `orientation="vertical"` to separate horizontal layouts like navigation and add `label` or `color` when you need emphasis.

```tsx
import { Block, Divider, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block align="center" wrap="wrap" direction="row" h={100}>
      <Text variant="p">Home</Text>
      <Divider orientation="vertical" />
      <Text variant="p">Fixtures</Text>
      <Divider orientation="vertical" color="primary" />
      <Text variant="p">Standings</Text>
      <Divider orientation="vertical" label="Live" color="warning" />
      <Text variant="p">Highlights</Text>
    </Block>
  );
}
```

### Sizes

Demonstrates how the `size` prop accepts both numeric values and spacing tokens so you can dial in subtle, comfortable, or bold divider weights.

```tsx
import { Block, Divider, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {SIZES.map((size) => (
        <Block key={size} fullWidth>
          <Text variant="small" c="secondary">{size}</Text>
          <Divider size={size} />
        </Block>
      ))}

      <Block fullWidth>
        <Text variant="small" c="secondary">1 (numeric)</Text>
        <Divider size={1} />
      </Block>
    </Block>
  );
}
```

### Variants

Showcase solid, dashed, and dotted dividers in both horizontal and vertical layouts to highlight how each variant can communicate different section breaks.

```tsx
import { Block, Divider, Text } from '@plocks/ui';

const VARIANTS = ['solid', 'dashed', 'dotted', 'gradient'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {VARIANTS.map((variant) => (
        <Block key={variant} fullWidth>
          <Text variant="small" c="secondary">{variant}</Text>
          <Divider variant={variant} />
        </Block>
      ))}

      <Block direction="row" align="center" wrap="wrap">
        <Text variant="small" fw="medium">
          Published
        </Text>
        <Divider orientation="vertical" variant="solid" style={{ height: 48 }} />
        <Text variant="small" fw="medium">
          Drafts
        </Text>
        <Divider orientation="vertical" variant="dashed" style={{ height: 48 }} />
        <Text variant="small" fw="medium">
          Scheduled
        </Text>
        <Divider orientation="vertical" variant="dotted" style={{ height: 48 }} />
        <Text variant="small" fw="medium">
          Archived
        </Text>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/EmojiPicker.md -->

# EmojiPicker

EmojiPicker lets users browse and select Unicode emoji.

## Metadata

- Import: `import { EmojiPicker } from '@plocks/emoji-picker';`
- Install: `npm install @plocks/emoji-picker` — a separate package from `@plocks/ui`
- Status: beta
- Tags: emoji, reactions, chat, picker, search
- Docs: https://plocks.dev/components/EmojiPicker
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/emoji-picker/src/components/EmojiPicker

## Props

- `onSelect` (required): (selection: EmojiPickerSelection) => void — Called with the selected Unicode emoji and its metadata.
- `emojis`: readonly EmojiPickerItem[] = DEFAULT_EMOJIS — Replace the built-in Unicode catalog with app-specific emoji.
- `categoryLabels`: Record<string, string> — Labels for custom category keys.
- `skinTone`: 0 | 1 | 2 | 3 | 4 | 5 — Current skin tone; omit for internal state. 0 means the emoji's default appearance.
- `defaultSkinTone`: 0 | 1 | 2 | 3 | 4 | 5 = 0
- `onSkinToneChange`: (tone: EmojiSkinTone) => void
- `recent`: readonly string[] — Most recently selected Unicode strings; omit for internal session recents.
- `defaultRecent`: readonly string[] = []
- `onRecentChange`: (recent: string[]) => void
- `maxRecent`: number = 24 — Maximum number of recent emoji to retain. @default 24
- `searchPlaceholder`: string = 'Search emoji'
- `emptyText`: string = 'No emoji found'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface EmojiPickerSelection {
  id: string;
  emoji: string;
  name: string;
  category: string;
  skinTone: EmojiSkinTone;
}

export interface EmojiPickerItem {
  id: string;
  emoji: string;
  name: string;
  category: string;
  keywords?: readonly string[];
  /** Unicode variants ordered light through dark; use null for an unavailable tone. */
  skins?: readonly (string | null)[];
}

export type EmojiSkinTone = 0 | 1 | 2 | 3 | 4 | 5;
```

## Examples

### Basics

Pick an emoji to append it to a message. The picker provides Unicode text; the app owns the message state.

```tsx
import { useState } from 'react';
import { Block, Input, Text } from '@plocks/ui';
import { EmojiPicker } from '@plocks/emoji-picker';

export function Demo() {
  const [message, setMessage] = useState('That looks great ');
  return (
    <Block gap="md" w="100%" maw={430}>
      <EmojiPicker w="100%" onSelect={({ emoji }) => setMessage(value => value + emoji)} />
      <Input label="Message" value={message} onChangeText={setMessage} />
      <Text c="muted" size="sm">Search, switch categories, or choose a skin tone before selecting.</Text>
    </Block>
  );
}
```

### Reaction set

Replace the catalog with a small set of reactions and supply a custom category label.

```tsx
import { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { EmojiPicker } from '@plocks/emoji-picker';
import type { EmojiPickerItem } from '@plocks/emoji-picker';

const REACTIONS: EmojiPickerItem[] = [
  { id: 'love', emoji: '❤️', name: 'Love', category: 'reactions', keywords: ['heart', 'like'] },
  { id: 'laugh', emoji: '😂', name: 'Laugh', category: 'reactions', keywords: ['funny'] },
  { id: 'wow', emoji: '😮', name: 'Wow', category: 'reactions', keywords: ['surprised'] },
  { id: 'sad', emoji: '😢', name: 'Sad', category: 'reactions' },
  { id: 'celebrate', emoji: '🎉', name: 'Celebrate', category: 'reactions', keywords: ['party'] },
];

export function Demo() {
  const [reaction, setReaction] = useState('❤️');
  return (
    <Block gap="md" w="100%" maw={430}>
      <EmojiPicker w="100%" h={290} emojis={REACTIONS} categoryLabels={{ reactions: 'Reactions' }} onSelect={({ emoji }) => setReaction(emoji)} />
      <Text>Selected reaction: {reaction}</Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/EmojiPickerInput.md -->

# EmojiPickerInput

EmojiPickerInput opens an emoji picker from a form field and stores the selected Unicode emoji.

## Metadata

- Import: `import { EmojiPickerInput } from '@plocks/emoji-picker';`
- Install: `npm install @plocks/emoji-picker` — a separate package from `@plocks/ui`
- Status: beta
- Tags: emoji, input, picker, form
- Docs: https://plocks.dev/components/EmojiPickerInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/emoji-picker/src/components/EmojiPickerInput

## Props

- `value`: string | null — Selected Unicode emoji. Pass null to show the placeholder.
- `defaultValue`: string | null
- `onChange`: (emoji: string | null, selection: EmojiPickerSelection | null) => void — Called on selection and when cleared; metadata is null when cleared.
- `onSelect`: (selection: EmojiPickerSelection) => void — Called only when an emoji is selected.
- `pickerProps`: Omit<EmojiPickerProps, 'onSelect'> — Props forwarded to the picker, except its selection callback.
- `closeOnSelect`: boolean = true — Close the panel after selection. @default true
- `dropdownType`: 'popover' | 'modal' = 'popover' — Desktop presentation; native and narrow screens use a sheet. @default 'popover'
- `modalTitle`: string = 'Select emoji'
- `onOpen`: () => void
- `onClose`: () => void
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Pick an emoji from the field or clear the selection.

```tsx
import { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { EmojiPickerInput } from '@plocks/emoji-picker';

export function Demo() {
  const [emoji, setEmoji] = useState<string | null>(null);

  return (
    <Block gap="sm" w="100%" maw={360}>
      <EmojiPickerInput label="Reaction" placeholder="Choose an emoji" value={emoji} onChange={setEmoji} clearable />
      <Text c="muted" size="sm">Selected: {emoji ?? 'None'}</Text>
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on EmojiPickerInput.

```tsx
import { Column } from '@plocks/ui';
import { EmojiPickerInput } from '@plocks/emoji-picker';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <EmojiPickerInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Choose a reaction" />
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/EmptyState.md -->

# EmptyState

Use shorthand content for a simple placeholder, or compound members for custom layout and actions.

## Metadata

- Import: `import { EmptyState } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/EmptyState
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/EmptyState

## Props

- `icon`: React.ReactNode — Illustration or icon shown before the message.
- `title`: React.ReactNode — Short empty-state title.
- `description`: React.ReactNode — Supporting description.
- `children`: React.ReactNode — Compound content, rendered after shorthand content.
- `align`: 'center' | 'start' | 'end' = 'center' — Content arrangement. @default 'center'
- `variant`: 'filled' | 'light' — Colored indicator treatment.
- `color`: ColorProp = 'primary' — Indicator accent. @default 'primary'
- `withIndicatorBackground`: boolean = false — Adds a neutral circular indicator background. @default false
- `size`: 'xs' | 'sm' | 'md' | 'lg' | 'xl' = 'md' — Scale of indicator, spacing, and text. @default 'md'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { EmptyStateIndicator, EmptyStateTitle, EmptyStateDescription, EmptyStateActions } from '@plocks/ui';`

### EmptyStateIndicator

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyStateTitle

- `children`: React.ReactNode
- `order`: 1 | 2 | 3 | 4 | 5 | 6 — Heading level. Without it the title is plain text.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyStateDescription

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyStateActions

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyState.Actions

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyState.Description

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyState.Indicator

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### EmptyState.Title

- `children`: React.ReactNode
- `order`: 1 | 2 | 3 | 4 | 5 | 6 — Heading level. Without it the title is plain text.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Use `icon`, `title`, and `description` for a simple placeholder.

```tsx
import { Block, EmptyState, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <EmptyState
        icon={<Icon name="search" />}
        title="No results"
        description="Try a different search."
      />
    </Block>
  );
}
```

### Compound Content

Compound members let you add actions and expose the title as a heading.

```tsx
import { Block, Button, EmptyState, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <EmptyState>
        <EmptyState.Indicator>
          <Icon name="search" />
        </EmptyState.Indicator>
        <EmptyState.Title order={2}>Nothing here yet</EmptyState.Title>
        <EmptyState.Description>Add your first item.</EmptyState.Description>
        <EmptyState.Actions>
          <Button>Add item</Button>
        </EmptyState.Actions>
      </EmptyState>
    </Block>
  );
}
```

### Indicator Variants

`variant`, `color`, and `size` change the indicator treatment and overall scale.

```tsx
import { Block, EmptyState, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <EmptyState
        icon={<Icon name="search" />}
        title="No results"
        variant="light"
        color="primary"
        size="lg"
      />
    </Block>
  );
}
```

### Alignment

`align` positions the indicator and text at the logical start or end.

```tsx
import { Block, EmptyState, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <EmptyState
        align="start"
        icon={<Icon name="search" />}
        title="No matches"
        description="Try another filter."
      />
    </Block>
  );
}
```

### Indicator Background

`withIndicatorBackground` adds a neutral circle around the icon.

```tsx
import { Block, EmptyState, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <EmptyState withIndicatorBackground icon={<Icon name="search" />} title="Nothing found" />
    </Block>
  );
}
```

### Sizes

`size` scales the indicator, spacing, and typography.

```tsx
import { Block, EmptyState, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <EmptyState size="xs" icon={<Icon name="search" />} title="Small placeholder" />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/FileInput.md -->

# FileInput

The FileInput component provides a user-friendly interface for file uploads with drag-and-drop functionality, file validation, and preview capabilities.

## Metadata

- Import: `import { FileInput } from '@plocks/ui';`
- Docs: https://plocks.dev/components/FileInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/FileInput

## Props

- `id`: string — Id of the picker button; label/error ids derive from it. Generated when omitted.
- `variant`: 'standard' | 'dropzone' | 'compact' — File input variant
- `placeholder`: string — Prompt text: the picker button's text (`standard`, `compact`) or the drop zone's main line (`dropzone`). Defaults to "Choose File(s)" / "Upload" / "Drag and drop files here".
- `accept`: string[] — Accepted file types (MIME types like `image/*`, or extensions like `.pdf`)
- `multiple`: boolean — Multiple file selection
- `maxSize`: number — Maximum file size in bytes
- `maxFiles`: number — Maximum number of files
- `onUpload`: (files: FileInputFile[], helpers: FileUploadHelpers) => Promise<void> — Upload handler, called with the newly added valid files. Report progress with `helpers.onProgress(fileId, percent)`; reject to mark them failed.
- `onProgress`: (fileId: string, progress: number) => void — Upload progress callback (from `helpers.onProgress` or the built-in uploader)
- `onFilesChange`: (files: FileInputFile[]) => void — Called with the full list when files are added or removed
- `onFileRemove`: (fileId: string) => void — File remove handler
- `PreviewComponent`: React.ComponentType<{ file: FileInputFile; onRemove: () => void }> — Custom renderer for each file in the list
- `children`: React.ReactNode — Custom drop zone content (`variant="dropzone"`)
- `showFileList`: boolean — Whether to show file list
- `enableDragDrop`: boolean — Whether to enable drag and drop (web; default on web)
- `validateFile`: (file: FileInputSource) => string | null — Custom validation: return an error message, or null when the file is fine
- `imagePreview`: { enabled?: boolean; maxWidth?: number; maxHeight?: number; quality?: number; } — Image preview settings
- `uploadSettings`: FileInputUploadSettings — Built-in multipart uploader, used when there is no `onUpload`
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface FileInputFile {
  /** File object or document picker asset */
  file: FileInputSource;
  /** Unique identifier */
  id: string;
  /** File name */
  name: string;
  /** File size in bytes */
  size: number;
  /** MIME type */
  type: string;
  /** Native file URI (if available) */
  uri?: string;
  /** Preview URL (for images) */
  previewUrl?: string;
  /** Upload progress (0-100) */
  progress?: number;
  /** Upload status */
  status?: 'pending' | 'uploading' | 'success' | 'error';
  /** Error message if validation or upload failed */
  error?: string;
}

export interface FileUploadHelpers {
  /** Report upload progress (0-100) for one file; updates the list and calls `onProgress`. */
  onProgress: (fileId: string, progress: number) => void;
}

export type FileInputSource = File | DocumentPickerAssetLike;

export interface FileInputUploadSettings {
  /** Upload URL (required for the built-in uploader) */
  url?: string;
  /** HTTP method */
  method?: 'POST' | 'PUT';
  /** Additional headers */
  headers?: Record<string, string>;
  /** Form field name for files (default `'file'`) */
  fieldName?: string;
  /** Additional form data */
  formData?: Record<string, string>;
}

export interface DocumentPickerAssetLike {
  uri?: string | null;
  name?: string | null;
  size?: number | null;
  mimeType?: string | null;
  type?: string | null;
  file?: File;
  fileCopyUri?: string | null;
  [key: string]: unknown;
}
```

## Examples

### Basics

Simple file input with helper text and multiple file selection.

```tsx
import { Block, FileInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <FileInput
        label="Upload files"
        helperText="Choose files from your device"
        multiple
        fullWidth
      />
    </Block>
  );
}
```

### Dropzone

Drag-and-drop dropzone variant with native fallback instructions and selected file list.

```tsx
import { Block, FileInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <FileInput
        variant="dropzone"
        multiple
        helperText="Drag & drop on desktop or tap to browse on mobile"
        fullWidth
      />
    </Block>
  );
}
```

### File Type Restrictions

Configure different file inputs with MIME filters, extension lists, and size limits.

```tsx
import { Block, FileInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <FileInput
        label="Images only"
        accept={['image/*']}
        helperText="Only image files are allowed"
        multiple
        fullWidth
      />
      <FileInput
        label="Documents only"
        accept={['.pdf', '.doc', '.docx', '.txt']}
        helperText="PDF, Word documents, and text files only"
        multiple
        fullWidth
      />
      <FileInput
        label="Videos (max 50MB)"
        accept={['video/*']}
        maxSize={50 * 1024 * 1024}
        helperText="Video files up to 50MB"
        fullWidth
      />
    </Block>
  );
}
```

### Image Preview

Image upload with preview thumbnails and remove functionality.

```tsx
import { Block, FileInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <FileInput
        label="Upload images"
        accept={['image/*']}
        helperText="Add images to see inline previews"
        multiple
        fullWidth
      />
    </Block>
  );
}
```

### Size Variants

Different size variants and customization options.

```tsx
import { Block, FileInput } from '@plocks/ui';

const sizes = [
  { label: 'Small', size: 'sm' as const },
  { label: 'Medium (default)', size: 'md' as const },
  { label: 'Large', size: 'lg' as const },
];

export function Demo() {
  return (
    <Block fullWidth>
      {sizes.map(({ label, size }) => (
        <FileInput key={size} label={label} size={size} fullWidth />
      ))}
      <FileInput
        label="Custom placeholder"
        placeholder="Click to select your files"
        fullWidth
      />
    </Block>
  );
}
```

### Upload Progress

Upload files with `onUpload` and report each file's progress with its `onProgress` helper.

```tsx
import { Block, FileInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <FileInput
        label="Select files to upload"
        multiple
        fullWidth
        onUpload={async (files, { onProgress }) => {
          for (const file of files) {
            for (let progress = 0; progress <= 100; progress += 25) {
              onProgress(file.id, progress);
              await new Promise((resolve) => setTimeout(resolve, 300));
            }
          }
        }}
      />
    </Block>
  );
}
```

### Validation & States

File input with various validation rules and states.

```tsx
import { Block, FileInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <FileInput
        label="Upload small files"
        helperText="Files must be below 2MB"
        maxSize={2 * 1024 * 1024}
        multiple
        fullWidth
      />
      <FileInput
        label="Upload up to 3 files"
        maxFiles={3}
        multiple
        fullWidth
      />
      <FileInput
        label="Required upload"
        error="Please select at least one file"
        required
        fullWidth
      />
      <FileInput
        label="Disabled upload"
        helperText="The uploader is unavailable"
        disabled
        fullWidth
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Flex.md -->

# Flex

Flex provides a powerful and intuitive way to create flexible layouts using CSS Flexbox principles. It handles spacing, alignment, and direction with a clean API that works consistently across platforms.

## Metadata

- Import: `import { Flex } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Flex
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Flex

## Props

- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction. `row` already follows the layout direction (it runs right-to-left in RTL on both React Native and the web).
- `align`: 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline' — Align items on the cross axis
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content on the main axis
- `wrap`: 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: SizeValue — Gap between children (applies to both row and column gap)
- `rowGap`: SizeValue — Row gap between children
- `columnGap`: SizeValue — Column gap between children
- `grow`: number — Flex grow
- `shrink`: number — Flex shrink
- `basis`: DimensionValue — Flex basis
- `children`: React.ReactNode — Children elements
- `disableRTLMirroring`: boolean — Keep left-to-right order even in right-to-left layouts (e.g. media controls, number pads). Lays this container's subtree out LTR.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { Row, Column } from '@plocks/ui';`

### Row

- `direction`: 'row' | 'row-reverse' — Override direction - defaults to 'row' but can be changed to 'row-reverse'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Flex` props (`align` `justify` `wrap` `gap` `rowGap` `columnGap` `grow` `shrink` `basis` `children` `disableRTLMirroring`): https://plocks.dev/llms/components/Flex.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Column

- `direction`: 'column' | 'column-reverse' — Override direction - defaults to 'column' but can be changed to 'column-reverse'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Flex` props (`align` `justify` `wrap` `gap` `rowGap` `columnGap` `grow` `shrink` `basis` `children` `disableRTLMirroring`): https://plocks.dev/llms/components/Flex.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Align Items

Item alignment options along the cross axis (flex-start, center, stretch, etc.).

```tsx
import { Block, Card, Flex, Text, useTheme } from '@plocks/ui';

const ALIGNMENTS = ['flex-start', 'center', 'flex-end', 'stretch', 'baseline'] as const;

export function Demo() {
  const theme = useTheme();
  // Baseline is only legible if each Text has a visible box; pull the fill from
  // the theme so it reads in both light and dark.
  const chip = { backgroundColor: theme.backgrounds.elevated, paddingHorizontal: 8 };

  return (
    // wrap="wrap" — five fixed-width examples in a row would overflow on narrow
    // viewports, since flex children don't shrink by default here.
    <Flex wrap="wrap" align="flex-start" gap="lg" fullWidth>
      {ALIGNMENTS.map((value) => (
        <Block key={value} gap="xs">
          <Text variant="span" size="sm" c="muted">align=&quot;{value}&quot;</Text>
          <Card variant="subtle" p="sm">
            {value === 'baseline' ? (
              <Flex direction="row" align="baseline" gap="sm" h={80}>
                {/* Text of varying sizes — their baselines line up, not their boxes */}
                <Text variant="span" size={24} style={chip}>Aa</Text>
                <Text variant="span" size={16} style={chip}>Bb</Text>
                <Text variant="span" size={12} style={chip}>Cc</Text>
              </Flex>
            ) : value === 'stretch' ? (
              <Flex direction="row" align={value} gap="sm" h={80}>
                {/* No fixed heights so children stretch to the container's cross-size */}
                <Card p="xs" style={{ minWidth: 32 }}><Text variant="small">1</Text></Card>
                <Card p="xs" style={{ minWidth: 32 }}><Text variant="small">2</Text></Card>
                <Card p="xs" style={{ minWidth: 32 }}><Text variant="small">3</Text></Card>
              </Flex>
            ) : (
              <Flex direction="row" align={value} gap="sm" h={80}>
                {/* Different heights to showcase flex-start/center/flex-end */}
                <Card p="xs" h={40}><Text variant="small">A</Text></Card>
                <Card p="xs" h={60}><Text variant="small">B</Text></Card>
                <Card p="xs" h={30}><Text variant="small">C</Text></Card>
              </Flex>
            )}
          </Card>
        </Block>
      ))}
    </Flex>
  );
}
```

### Basics

Simple flex container with three items and gap spacing.

```tsx
import { Card, Flex, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Flex gap="md" fullWidth>
      <Card p="sm">
        <Text>Item 1</Text>
      </Card>
      <Card p="sm">
        <Text>Item 2</Text>
      </Card>
      <Card p="sm">
        <Text>Item 3</Text>
      </Card>
    </Flex>
  );
}
```

### Flex Direction

Row and column direction layouts for different item arrangements.

```tsx
import { Block, Card, Flex, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="span" size="sm" c="muted">direction="row"</Text>
        <Flex direction="row" gap="md">
          <Card p="sm"><Text>Item 1</Text></Card>
          <Card p="sm"><Text>Item 2</Text></Card>
          <Card p="sm"><Text>Item 3</Text></Card>
        </Flex>
      </Block>

      <Block>
        <Text variant="span" size="sm" c="muted">direction="column"</Text>
        <Flex direction="column" gap="md">
          <Card p="sm"><Text>Item 1</Text></Card>
          <Card p="sm"><Text>Item 2</Text></Card>
          <Card p="sm"><Text>Item 3</Text></Card>
        </Flex>
      </Block>
    </Block>
  );
}
```

### Justify Content

Content justification options along the main axis (flex-start, center, space-between, etc.).

```tsx
import { Block, Card, Flex, Text, useTheme, type FlexProps } from '@plocks/ui';

const JUSTIFY_OPTIONS: Array<{ label: string; value: NonNullable<FlexProps['justify']> }> = [
  { label: 'Start', value: 'flex-start' },
  { label: 'Center', value: 'center' },
  { label: 'End', value: 'flex-end' },
  { label: 'Between', value: 'space-between' },
  { label: 'Around', value: 'space-around' },
  { label: 'Evenly', value: 'space-evenly' },
];

export function Demo() {
  const theme = useTheme();

  return (
    <Block align="stretch">
      {JUSTIFY_OPTIONS.map(({ value }) => (
        <Block key={value} align="stretch">
          <Text variant="span" size="sm" c="muted">justify="{value}"</Text>
          <Flex
            direction="row"
            justify={value}
            mih={60}
            style={{
              // Give the row a large track to clearly expose free space
              width: 600,
              maxWidth: '100%',
              borderWidth: 1,
              borderStyle: 'dashed' as const,
              // Without an explicit color the dashed track falls back to black
              // in both themes.
              borderColor: theme.backgrounds.border,
              borderRadius: 4
            }}
          >
            {/* Small fixed squares with no shrink so free space is obvious */}
            <Card padding={0} style={{ width: 40, height: 40, flexShrink: 0, alignItems: 'center', justifyContent: 'center' }}>
              <Text variant="small">A</Text>
            </Card>
            <Card padding={0} style={{ width: 40, height: 40, flexShrink: 0, alignItems: 'center', justifyContent: 'center' }}>
              <Text variant="small">B</Text>
            </Card>
            <Card padding={0} style={{ width: 40, height: 40, flexShrink: 0, alignItems: 'center', justifyContent: 'center' }}>
              <Text variant="small">C</Text>
            </Card>
          </Flex>
        </Block>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/FloatingActions.md -->

# FloatingActions

FloatingActions places related commands above a trigger or fans them out in a flower layout. It opens on click or hover, supports controlled state, and uses theme-aware IconButtons for its trigger and actions. Labels can appear on hover and focus or stay visible.

## Metadata

- Import: `import { FloatingActions } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/FloatingActions
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/FloatingActions

## Props

- `actions`: FloatingActionItem[] — Custom actions. If not provided, defaults to a theme toggle, plus Spotlight and GitHub when `onOpenSpotlight` / `githubUrl` are set
- `onOpen`: () => void — Called when the speed dial opens
- `onClose`: () => void — Called when the speed dial closes
- `opened`: boolean — Controlled open state.
- `defaultOpened`: boolean = false — Initial open state when uncontrolled. @default false
- `onChange`: (opened: boolean) => void — Called when an interaction requests an open-state change.
- `trigger`: 'click' | 'hover' = 'click' — How the dial opens on web. Tap and keyboard activation work in either mode. @default 'click'
- `disableOutsideClose`: boolean = false — If true, clicking/tapping outside will not close the menu (web)
- `mode`: 'stack' | 'flower' = 'stack' — Action layout. @default 'stack'
- `labelMode`: 'tooltip' | 'persistent' | 'none' = 'tooltip' — How action labels appear. @default 'tooltip'
- `arcRadius`: number = 88 — Minimum radius (in px) of the flower layout. @default 88
- `color`: ColorProp = 'primary' — Button color: palette token, `'primary.6'` shade syntax, or CSS color. @default 'primary'
- `variant`: 'default' | 'filled' | 'secondary' | 'outline' | 'ghost' | 'gradient' | 'none' = 'filled' — Trigger and default action appearance. @default 'filled'
- `toggleIcon`: string = 'plus' — Trigger icon while closed. @default 'plus'
- `closeIcon`: string — Trigger icon while open. Defaults to a rotated plus when `toggleIcon` is `'plus'`, otherwise `'close'`.
- `onOpenSpotlight`: () => void — Opens Spotlight; the default Spotlight action is only shown when this is set
- `onToggleTheme`: () => void — Handler to toggle theme (if omitted, the Theme action still shows but will be a no-op)
- `githubUrl`: string — Repository URL for the default GitHub action; the action is only shown when this is set
- `toggleLabels`: { open: string; close: string } = { open: 'Open actions', close: 'Close actions' } — Accessible names of the main button. @default { open: 'Open actions', close: 'Close actions' }
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface FloatingActionItem {
  key: string;
  /** Icon registry name */
  icon?: string;
  /** Icon name computed at render time (e.g. reflecting the current theme mode) */
  getIcon?: () => string;
  onPress: () => void;
  /** Visible label; defaults to `accessibilityLabel`, then `key` */
  label?: string;
  /** Accessible name of the action (falls back to `key`, with a dev warning) */
  accessibilityLabel?: string;
  /** Extra description for screen readers (native) */
  accessibilityHint?: string;
  /** Use the Button theme roles for each action. @default 'filled' */
  variant?: IconButtonVariant;
  /** Override the dial's color for this action. */
  color?: ColorProp;
  /** Disabled actions remain visible but cannot be activated. */
  disabled?: boolean;
}
```

## Examples

### Basics

The default stack places actions above the main button. `trigger="click"` opens on press; `trigger="hover"` opens when a mouse enters the dial and closes shortly after it leaves. Tap and keyboard activation still work in hover mode. Use `labelMode="persistent"` to keep labels visible or `labelMode="tooltip"` to show them on hover and keyboard focus. `mode="flower"` fans actions up and toward the start side. The trigger and actions use `IconButton`, so their icon contrast, focus ring, pressed state, and theme colors follow the same rules as Button. Set `color` and `variant` on the dial, or override them on an individual action. Actions can also be `disabled`. Use `toggleIcon` and `closeIcon` to customize the trigger. For controlled use, pass `opened` and `onChange`. Keep the dial to a few related commands (roughly three to six). Persistent labels are easier to discover on touch screens, where hover tooltips are unavailable.

```tsx
import { useState } from 'react';
import { Block, Column, FloatingActions, Text } from '@plocks/ui';

export function Demo() {
  const [message, setMessage] = useState('Choose an action');
  const actions = [
    { key: 'create', icon: 'plus', accessibilityLabel: 'Create item', color: 'success' as const, onPress: () => setMessage('Created') },
    { key: 'search', icon: 'search', accessibilityLabel: 'Search items', onPress: () => setMessage('Search selected') },
    { key: 'info', icon: 'info', accessibilityLabel: 'Show details', onPress: () => setMessage('Details selected') },
  ];

  return (
    <Column gap="lg" fullWidth>
      <Block fullWidth h={280} position="relative" p="md">
        <Text fw="semibold">Click or tap · persistent labels</Text>
        <Text>{message}</Text>
        <FloatingActions trigger="click" mode="stack" labelMode="persistent" actions={actions} />
      </Block>
      <Block fullWidth h={220} position="relative" p="md">
        <Text fw="semibold">Hover · flower layout · focus for labels</Text>
        <FloatingActions trigger="hover" mode="flower" labelMode="tooltip" actions={actions} />
      </Block>
    </Column>
  );
}
```

### Variants

Compare the floating trigger appearance across four IconButton variants.

```tsx
import { Block, Column, FloatingActions, Text } from '@plocks/ui';

const actions = [{ key: 'add', icon: 'plus', label: 'Add item', onPress: () => {} }];
const variants = ['filled', 'default', 'outline', 'ghost'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <Block key={variant} position="relative" h={110} fullWidth p="sm">
          <Text fw="semibold">{variant}</Text>
          <FloatingActions variant={variant} actions={actions} />
        </Block>
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/FloatingIndicator.md -->

# FloatingIndicator

Give the parent `position: 'relative'`. On native, placement updates when the target or parent changes or the screen dimensions change.

## Metadata

- Import: `import { FloatingIndicator } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/FloatingIndicator
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/FloatingIndicator

## Props

- `target` (required): View | HTMLElement | null — Element to highlight; null hides the indicator.
- `parent` (required): View | HTMLElement | null — Positioned ancestor used for relative coordinates.
- `transitionDuration`: number = 150 — Animation time in ms. @default 150
- `onTransitionStart`: () => void — Called before animated movement.
- `onTransitionEnd`: () => void — Called when animated movement finishes.
- `displayAfterTransitionEnd`: boolean — Defer appearance until a parent CSS transition finishes on web.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

The indicator follows the selected target and remains behind the controls.

```tsx
import { useMemo, useState } from 'react';
import { Pressable, View } from 'react-native';
import { Block, FloatingIndicator, Text } from '@plocks/ui';

export function Demo() {
  const [parent, setParent] = useState<View | null>(null);
  const [targets, setTargets] = useState<(View | null)[]>([]);
  const [active, setActive] = useState(0);
  const refs = useMemo(
    () =>
      [0, 1, 2].map(
        (i) => (node: View | null) =>
          setTargets((current) =>
            current[i] === node ? current : Object.assign([...current], { [i]: node }),
          ),
      ),
    [],
  );
  return (
    <Block fullWidth>
      <View ref={setParent} style={{ position: 'relative', flexDirection: 'row', padding: 4 }}>
        <FloatingIndicator
          parent={parent}
          target={targets[active] ?? null}
          bg="primary.2"
          style={{ borderRadius: 8 }}
        />
        {['React', 'Vue', 'Svelte'].map((label, i) => (
          <Pressable key={label} ref={refs[i]} onPress={() => setActive(i)} style={{ padding: 12 }}>
            <Text>{label}</Text>
          </Pressable>
        ))}
      </View>
    </Block>
  );
}
```

### Multiple Rows

The indicator can move between targets in a grid.

```tsx
import { useMemo, useState } from 'react';
import { Pressable, View } from 'react-native';
import { Block, FloatingIndicator, Text } from '@plocks/ui';

export function Demo() {
  const [parent, setParent] = useState<View | null>(null);
  const [targets, setTargets] = useState<(View | null)[]>([]);
  const [active, setActive] = useState(4);
  const refs = useMemo(
    () =>
      Array.from(
        { length: 9 },
        (_, i) => (node: View | null) =>
          setTargets((current) =>
            current[i] === node ? current : Object.assign([...current], { [i]: node }),
          ),
      ),
    [],
  );
  return (
    <Block fullWidth>
      <View
        ref={setParent}
        style={{ position: 'relative', flexDirection: 'row', flexWrap: 'wrap', width: 180 }}
      >
        <FloatingIndicator
          parent={parent}
          target={targets[active] ?? null}
          bg="primary.2"
          style={{ borderRadius: 8 }}
        />
        {Array.from({ length: 9 }, (_, i) => (
          <Pressable
            key={i}
            ref={refs[i]}
            onPress={() => setActive(i)}
            style={{ width: 60, height: 50, alignItems: 'center', justifyContent: 'center' }}
          >
            <Text>{i + 1}</Text>
          </Pressable>
        ))}
      </View>
    </Block>
  );
}
```

### Tab Highlight

A decorative indicator can follow an accessible tab selection.

```tsx
import { useMemo, useState } from 'react';
import { Pressable, View } from 'react-native';
import { Block, FloatingIndicator, Text } from '@plocks/ui';

export function Demo() {
  const [parent, setParent] = useState<View | null>(null);
  const [targets, setTargets] = useState<(View | null)[]>([]);
  const [active, setActive] = useState(0);
  const refs = useMemo(
    () =>
      [0, 1, 2].map(
        (i) => (node: View | null) =>
          setTargets((current) =>
            current[i] === node ? current : Object.assign([...current], { [i]: node }),
          ),
      ),
    [],
  );
  return (
    <Block fullWidth>
      <View ref={setParent} role="tablist" style={{ position: 'relative', flexDirection: 'row' }}>
        <FloatingIndicator
          parent={parent}
          target={targets[active] ?? null}
          bg="primary.2"
          style={{ borderRadius: 8 }}
        />
        {['Overview', 'Details', 'Activity'].map((label, i) => (
          <Pressable
            key={label}
            ref={refs[i]}
            role="tab"
            aria-selected={active === i}
            onPress={() => setActive(i)}
            style={{ padding: 12 }}
          >
            <Text>{label}</Text>
          </Pressable>
        ))}
      </View>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/FloatingWindow.md -->

# FloatingWindow

Use DragHandle when controls inside the window need their own pointer interactions. Without it, the whole surface can be dragged.

## Metadata

- Import: `import { FloatingWindow } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/FloatingWindow
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/FloatingWindow

## Props

- `children`: React.ReactNode
- `dimensions`: FloatingWindowDimensions — Dimensions and resize limits.
- `onSizeChange`: (size: { width: number; height: number }) => void — Called when resized.
- `onResizeStart`: () => void
- `onResizeEnd`: () => void
- `withBorder`: boolean — Surface border.
- `radius`: RadiusValue — Surface radius.
- `shadow`: ShadowToken — Surface shadow.
- `zIndex`: number — Overlay stack order.
- `withinPortal`: boolean = true — Render at app root. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `initialPosition`: FloatingWindowInitialPosition
- `enabled`: boolean
- `constrainToViewport`: boolean
- `constrainOffset`: number
- `axis`: 'x' | 'y'
- `onPositionChange`: (position: FloatingWindowPosition) => void
- `onDragStart`: () => void
- `onDragEnd`: () => void
- `setPositionRef`: React.RefObject<FloatingWindowHandle | null>

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { FloatingWindowDragHandle, FloatingWindowResizeHandle } from '@plocks/ui';`

### FloatingWindowDragHandle

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### FloatingWindowResizeHandle

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### FloatingWindow.DragHandle

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### FloatingWindow.ResizeHandle

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useFloatingWindow({ initialPosition = { top: 20, left: 20 }, enabled = true, constrainToViewport = true, constrainOffset = 0, axis, onPositionChange, onDragStart, onDragEnd, setPositionRef }: UseFloatingWindowOptions = {}): UseFloatingWindowReturn`

## Types

```ts
export interface FloatingWindowDimensions { initialWidth?: number; initialHeight?: number; minWidth?: number; maxWidth?: number; minHeight?: number; maxHeight?: number }
```

## Examples

### Basics

Drag the header to move the window. The corner grip resizes it.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened((value) => !value)}>
        {opened ? 'Hide window' : 'Show window'}
      </Button>
      {opened && (
        <FloatingWindow
          dimensions={{ initialWidth: 260, initialHeight: 160 }}
          initialPosition={{ top: 90, left: 40 }}
          p="md"
        >
          <FloatingWindow.DragHandle>
            <Text fw="600">Drag this header</Text>
          </FloatingWindow.DragHandle>
          <Text>Move or resize this window.</Text>
          <FloatingWindow.ResizeHandle />
        </FloatingWindow>
      )}
    </>
  );
}
```

### Without Viewport Constraint

`constrainToViewport={false}` lets the window move beyond the viewport edge.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened(!opened)}>Toggle window</Button>
      {opened && (
        <FloatingWindow w={240} p="md" constrainToViewport={false}>
          <Text>Drag beyond the viewport.</Text>
        </FloatingWindow>
      )}
    </>
  );
}
```

### Drag Handle

The DragHandle confines movement to one region, leaving child buttons interactive.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened(true)}>Open window</Button>
      {opened && (
        <FloatingWindow w={260} p="md">
          <FloatingWindow.DragHandle>
            <Text fw="600">Drag here</Text>
          </FloatingWindow.DragHandle>
          <Button size="sm" onPress={() => setOpened(false)}>
            Close
          </Button>
        </FloatingWindow>
      )}
    </>
  );
}
```

### Disabled Dragging

`enabled={false}` keeps the window fixed in place.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened(!opened)}>Toggle static window</Button>
      {opened && (
        <FloatingWindow enabled={false} w={220} p="md">
          <Text>This window stays put.</Text>
        </FloatingWindow>
      )}
    </>
  );
}
```

### Constrain Offset

`constrainOffset` keeps space between the window and viewport edges.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened(!opened)}>Toggle inset window</Button>
      {opened && (
        <FloatingWindow constrainOffset={30} w={220} p="md">
          <Text>30 px from the edge.</Text>
        </FloatingWindow>
      )}
    </>
  );
}
```

### Lock Axis

`axis="x"` limits dragging to the horizontal axis.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened(!opened)}>Toggle horizontal window</Button>
      {opened && (
        <FloatingWindow axis="x" w={220} p="md">
          <Text>Drag horizontally.</Text>
        </FloatingWindow>
      )}
    </>
  );
}
```

### Set Position

`setPositionRef` can move the window to a new viewport inset.

```tsx
import { useRef, useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';
import type { FloatingWindowHandle } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  const windowRef = useRef<FloatingWindowHandle>(null);
  return (
    <>
      <Button onPress={() => setOpened(true)}>Open window</Button>
      {opened && (
        <FloatingWindow
          setPositionRef={windowRef}
          initialPosition={{ top: 100, left: 40 }}
          dimensions={{ initialWidth: 240, initialHeight: 140 }}
          p="md"
        >
          <FloatingWindow.DragHandle>
            <Text fw="600">Move me</Text>
          </FloatingWindow.DragHandle>
          <Button onPress={() => windowRef.current?.setPosition({ top: 60, right: 60 })}>
            Move to top right
          </Button>
        </FloatingWindow>
      )}
    </>
  );
}
```

### Resize Handle

`FloatingWindow.ResizeHandle` resizes within the limits in `dimensions`.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  return (
    <>
      <Button onPress={() => setOpened(true)}>Open resizable window</Button>
      {opened && (
        <FloatingWindow
          initialPosition={{ top: 110, left: 60 }}
          dimensions={{
            initialWidth: 230,
            initialHeight: 130,
            minWidth: 160,
            minHeight: 90,
            maxWidth: 360,
            maxHeight: 280,
          }}
          p="md"
        >
          <FloatingWindow.DragHandle>
            <Text fw="600">Resizable window</Text>
          </FloatingWindow.DragHandle>
          <FloatingWindow.ResizeHandle />
        </FloatingWindow>
      )}
    </>
  );
}
```

### Resize Callbacks

`onSizeChange` reports the final window dimensions after a resize.

```tsx
import { useState } from 'react';
import { Button, FloatingWindow, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  const [size, setSize] = useState({ width: 240, height: 140 });
  return (
    <>
      <Button onPress={() => setOpened(true)}>Open window</Button>
      {opened && (
        <FloatingWindow
          initialPosition={{ top: 110, left: 60 }}
          dimensions={{ initialWidth: 240, initialHeight: 140 }}
          onSizeChange={setSize}
          p="md"
        >
          <FloatingWindow.DragHandle>
            <Text fw="600">Resize me</Text>
          </FloatingWindow.DragHandle>
          <Text>
            {Math.round(size.width)} × {Math.round(size.height)}
          </Text>
          <FloatingWindow.ResizeHandle />
        </FloatingWindow>
      )}
    </>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Form.md -->

# Form

Form manages values, validation, and submission state for a group of inputs.

## Metadata

- Import: `import { Form } from '@plocks/ui';`
- Tags: form, fields, validation, submit
- Docs: https://plocks.dev/components/Form
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Form

## Props

- `initialValues`: FormValues — Initial form values
- `validationSchema`: ValidationSchema — Form validation schema
- `onSubmit`: (values: FormValues) => void | Promise<void> — Submit handler
- `validate`: (values: FormValues) => Record<string, string> | Promise<Record<string, string>> — Validation handler
- `disabled`: boolean — Whether form is disabled
- `validateOnChange`: boolean — Whether to validate on change
- `validateOnBlur`: boolean — Whether to validate on blur
- `children` (required): React.ReactNode — Children components
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### Form.Field

- `name`: string — Field name (binds the field to the enclosing `Form`).
- `dependsOn`: FormFieldDependency[] — Field dependencies for conditional logic
- `validateWhen`: { field: string; condition: (value: unknown, formValues: FormValues) => boolean; } — Only validate this field (its `validation` rules) while the condition holds.
- `validation`: ValidationRule[] — Validation rules for this field, added to the form's `validationSchema`.
- `label`: React.ReactNode — Label rendered above (or beside) the field.
- `description`: React.ReactNode — Description rendered under the label.
- `error`: React.ReactNode — Error message. Defaults to the form's error for `name` once touched (when a label is shown).
- `helperText`: React.ReactNode — Helper text under the field when there is no error.
- `required`: boolean — Marks the field required.
- `labelPosition`: 'top' | 'start' | 'end' — Where the label goes. `'start'` / `'end'` put it beside the field (logical: they follow the reading direction).
- `children` (required): React.ReactNode — Children components
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Form.Input

- `flex`: number — Flex factor for an input placed beside buttons or icons.
- `inputColor`: string — Color of the editable text.
- `inputFontSize`: number — Editable text size in pixels.
- `id`: string — Id of the TextInput (DOM `id` on web, `nativeID` on native); label/error ids derive from it. Generated when omitted.
- `focused`: boolean — Force the focused look regardless of real focus.
- `textInputProps`: ExtendedTextInputProps — Additional TextInput props.
- `inputRef`: React.Ref<TextInput> — Extra ref to the TextInput; merged with `ref`.
- `secureTextEntry`: boolean — Force secure entry regardless of type.
- `containerProps`: Omit<ViewProps, 'style' | 'testID' | 'children'> — Props for the root `View` (gesture handlers, onLayout, ...).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Input` props (`type` `validation` `autoComplete` `keyboardType` `multiline` `numberOfLines` `minLines` `maxLines` `maxLength` `autoCapitalize` `autoCorrect` `autoFocus` `returnKeyType` `blurOnSubmit` `selectTextOnFocus` `textContentType` `textAlign` `spellCheck` `inputMode` `enterKeyHint` `selectionColor` `showSoftInputOnFocus` `editable`): https://plocks.dev/llms/components/Input.md

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `debounceMs` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

### Form.Submit

- `children` (required): React.ReactNode — Submit button content
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Button` props (`onPressIn` `onPressOut` `onHoverIn` `onHoverOut` `onLongPress` `onLayout` `variant` `color` `size` `disabled` `loading` `loadingTitle` `fullWidth` `textColor` `icon` `startSection` `endSection` `tooltip` `transitionDuration` `accessibilityLabel` `accessibilityHint` `labelProps`): https://plocks.dev/llms/components/Button.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useFormContext(): FormContextValue` — Returns the enclosing `Form`'s state and actions (`values`, `errors`, `touched`, `isSubmitting`, `isValid`, `setFieldValue`, `getFieldProps`, `submitForm`, `resetForm`, …) for custom fields and buttons, and throws outside a `Form` — use `useOptionalFormContext()` for a non-throwing read.
- `useOptionalFormContext(): FormContextValue | null` — Returns the enclosing `Form`'s state and actions, or `null` outside one — the non-throwing variant of `useFormContext()`, for inputs that bind to a `Form` when there is one and work standalone otherwise.

## Types

```ts
export type FormValues = Record<string, any>;

export interface ValidationSchema {
  [fieldName: string]: ValidationRule[];
}

export interface FormFieldDependency {
  field: string;
  condition: (value: unknown, formValues: FormValues) => boolean;
  action: 'show' | 'hide' | 'enable' | 'disable' | 'require';
}
```

## Examples

### Basics

`Form` manages values, validation, and submission state. Give each `Form.Field` a `name` and put a `Form.Input` inside it (it binds to that field's value, change handler and error), then trigger submission with `Form.Submit`.

```tsx
import { Block, Form } from '@plocks/ui';

export function Demo() {
  return (
    <Form
      initialValues={{ name: '', email: '' }}
      onSubmit={(values) => console.log('submit', values)}
    >
      <Block style={{ width: '100%', maxWidth: 400 }}>
        <Form.Field name="name">
          <Form.Input label="Full name" placeholder="Ada Lovelace" />
        </Form.Field>
        <Form.Field name="email">
          <Form.Input label="Email" placeholder="ada@example.com" />
        </Form.Field>
        <Form.Submit>Create account</Form.Submit>
      </Block>
    </Form>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/FormLayout.md -->

# FormLayout

FormLayout arranges fields in spaced form sections.

## Metadata

- Import: `import { FormLayout } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/FormLayout
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/FormLayout

## Props

- `children` (required): ReactNode
- `spacing`: 'sm' | 'md' | 'lg' | 'xl'
- `variant`: 'default' | 'card' | 'modal' — `card`: subtle filled panel with a border. `modal`: raised surface with a shadow.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { FormSection, FormGroup } from '@plocks/ui';`

### FormSection

- `title`: ReactNode
- `description`: ReactNode
- `children` (required): ReactNode
- `spacing`: 'sm' | 'md' | 'lg'
- `collapsible`: boolean — Let the user collapse the section from its header.
- `expanded`: boolean — Controlled expanded state (with `collapsible`).
- `defaultExpanded`: boolean — Initial expanded state while uncontrolled. Default true.
- `onExpandedChange`: (expanded: boolean) => void — Called when the header toggles the section.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### FormGroup

- `children` (required): ReactNode
- `direction`: 'row' | 'column'
- `columns`: 2 | 3 | 4
- `spacing`: 'xs' | 'sm' | 'md' | 'lg'
- `align`: 'start' | 'center' | 'end' | 'stretch'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

FormLayout arranges fields in spaced form sections.

```tsx
import { FormLayout, FormSection, Input } from '@plocks/ui';

export function Demo() {
  return (
    <FormLayout variant="card">
      <FormSection title="Profile">
        <Input label="Name" placeholder="Your name" />
        <Input label="Email" placeholder="you@example.com" />
      </FormSection>
    </FormLayout>
  );
}
```

### Variants

Compare plain form spacing, the bordered card, and the raised modal surface.

```tsx
import { Column, FormLayout, FormSection, Input, Text } from '@plocks/ui';

const variants = ['default', 'card', 'modal'] as const;

export function Demo() {
  return (
    <Column gap="lg" fullWidth>
      {variants.map(variant => (
        <Column key={variant} gap="xs" fullWidth>
          <Text fw="semibold">{variant}</Text>
          <FormLayout variant={variant}>
            <FormSection title="Profile"><Input label="Name" placeholder="Your name" /></FormSection>
          </FormLayout>
        </Column>
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Gauge.md -->

# Gauge

Use Gauge for a value within a known range. Configure ranges, ticks, and labels or compose its parts directly.

## Metadata

- Import: `import { Gauge } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Gauge
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Gauge

## Props

- `value` (required): number — Current value
- `min`: number = 0 — Minimum value
- `max`: number = 100 — Maximum value
- `size`: number | string = DEFAULT_SIZE — Gauge size in px (non-numeric values fall back to 200).
- `thickness`: number = 8 — Track thickness
- `startAngle`: number = 135 — Start angle in degrees (0° = top)
- `endAngle`: number = 45 — End angle in degrees
- `rotationOffset`: number = 0 — Rotation offset in degrees (rotates entire gauge)
- `color`: ColorValue | string = 'primary' — Accent color of the needle and center dot: palette token, `'primary.6'`, or any CSS color.
- `trackColor`: string — Track color. Defaults to the theme's `backgrounds.borderStrong`.
- `ranges`: GaugeRange[] — Color ranges
- `ticks`: GaugeTicks — Tick configuration
- `labels`: GaugeLabels — Label configuration
- `needle`: GaugeNeedle — Needle configuration
- `animationDuration`: number = 500 — Needle animation duration in ms. `0` (and reduced motion) moves the needle instantly.
- `animationEasing`: GaugeEasing | (string & {}) = 'ease-out' — Needle animation easing.
- `disabled`: boolean = false — Dims the gauge.
- `aria-label`: string — Accessible name of the gauge.
- `children`: React.ReactNode — Children for compound component pattern
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### Gauge.Center

- `color`: string — Center dot color
- `size`: number — Center dot size
- `show`: boolean — Whether to show center
- `children`: React.ReactNode — Custom center content
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Gauge.Labels

- `config`: GaugeLabels — Labels configuration
- `positions`: number[] — Custom positions
- `formatter`: (value: number) => string — Label formatter
- `color`: string — Label color
- `fontSize`: number — Font size in px. Defaults to the theme's `sm` font size.
- `offset`: number — Offset from edge
- `labelStyle`: TextStyle — Style applied to every label text.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Gauge.Needle

- `value`: number — Needle value (angle will be calculated)
- `angle`: number — Direct angle override
- `config`: GaugeNeedle — Needle configuration
- `color`: string — Needle color
- `width`: number — Needle width
- `length`: number — Needle length
- `shape`: 'line' | 'arrow' | 'triangle' — Needle shape
- `animationDuration`: number — Animation duration
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Gauge.Range

- `from` (required): number — Range start value
- `to` (required): number — Range end value
- `color` (required): string — Range color
- `thickness`: number — Range thickness (inherits from parent if not specified)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Gauge.Ticks

- `config`: GaugeTicks — Tick configuration
- `major`: number — Major tick count
- `minor`: number — Minor tick count
- `positions`: number[] — Custom positions
- `length`: number — Tick length
- `color`: string — Tick color
- `width`: number — Tick width. Defaults to 2 for major ticks and 1 for minor ticks.
- `type`: 'major' | 'minor' — Tick type
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Gauge.Track

- `color`: string — Track color. Defaults to the gauge's `backgroundColor`, else `backgrounds.borderStrong`.
- `thickness`: number — Track thickness
- `opacity`: number — Track opacity
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface GaugeRange {
  /** Starting value for the range */
  from: number;
  /** Ending value for the range */
  to: number;
  /** Color for this range */
  color: string;
  /**
   * Name of the band (`'Normal'`, `'Danger'`). While the value falls inside the
   * band, the name is appended to the gauge's spoken value text.
   */
  label?: string;
}

export interface GaugeTicks {
  /** Number of major ticks */
  major?: number;
  /** Number of minor ticks */
  minor?: number;
  /** Custom major tick positions */
  majorPositions?: number[];
  /** Custom minor tick positions */
  minorPositions?: number[];
  /** Major tick length */
  majorLength?: number;
  /** Minor tick length */
  minorLength?: number;
  /** Tick color */
  color?: string;
  /** Tick width (stroke thickness). Defaults to 2 for major ticks and 1 for minor ticks. */
  width?: number;
}

export interface GaugeLabels {
  /** Whether to show labels */
  show?: boolean;
  /** Custom label positions */
  positions?: number[];
  /** Label formatter function. Also formats the gauge's spoken value. */
  formatter?: (value: number) => string;
  /** Label color */
  color?: string;
  /** Label font size */
  fontSize?: number;
  /** Label offset from gauge edge */
  offset?: number;
}

export interface GaugeNeedle {
  /** Needle color. Defaults to the gauge `color`. */
  color?: string;
  /** Needle width/thickness */
  width?: number;
  /** Needle length (0-1, percentage of radius) */
  length?: number;
  /** Needle shape */
  shape?: GaugeNeedleShape;
  /** Whether to show center dot */
  showCenter?: boolean;
  /** Center dot color */
  centerColor?: string;
  /** Center dot size */
  centerSize?: number;
}

export type GaugeEasing = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out';
```

## Examples

### Basics

Adjust a measured value and watch the needle move across the scale.

```tsx
import { useState } from 'react';
import { Block, Button, Gauge, Row } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(65);

  return (
    <Block align="center" gap="md">
      <Gauge
        value={value}
        size={220}
        aria-label="Completion"
        ticks={{ major: 5 }}
        labels={{ show: true, formatter: (current) => `${current}%` }}
      />
      <Row gap="sm">
        <Button variant="outline" onPress={() => setValue(Math.max(0, value - 10))}>
          -10%
        </Button>
        <Button onPress={() => setValue(Math.min(100, value + 10))}>+10%</Button>
      </Row>
    </Block>
  );
}
```

### Colored ranges

Color the scale by operating range and include the current band in the spoken value.

```tsx
import { Gauge } from '@plocks/ui';

const ranges = [
  { from: 0, to: 40, color: '#3b82f6', label: 'Low' },
  { from: 40, to: 75, color: '#f59e0b', label: 'Elevated' },
  { from: 75, to: 100, color: '#ef4444', label: 'High' },
];

export function Demo() {
  return (
    <Gauge
      value={68}
      size={220}
      aria-label="System load"
      ranges={ranges}
      ticks={{ major: 5, minor: 4 }}
      labels={{ show: true }}
    />
  );
}
```

### Compound parts

Compose the track, range, ticks, needle, and center to control each part directly.

```tsx
import { Gauge } from '@plocks/ui';

export function Demo() {
  return (
    <Gauge value={72} size={220} aria-label="Battery charge">
      <Gauge.Track />
      <Gauge.Range from={0} to={25} color="#ef4444" />
      <Gauge.Range from={25} to={100} color="#22c55e" />
      <Gauge.Ticks major={5} />
      <Gauge.Labels formatter={(value) => `${value}%`} />
      <Gauge.Needle config={{ shape: 'arrow' }} />
      <Gauge.Center />
    </Gauge>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Gradient.md -->

# Gradient

Gradient fills a layout container with a color transition.

## Metadata

- Import: `import { Gradient } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Gradient
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Gradient

## Props

- `colors` (required): readonly string[]
- `start`: { x: number; y: number }
- `end`: { x: number; y: number }
- `locations`: readonly number[]
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `translateY`: number — Small visual offset without affecting surrounding layout.
- `rotate`: string — Rotation around the block center, such as `"45deg"`.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Plus the `Block` props (`children` `className` `onPress` `onLongPress` `onPressIn` `onPressOut` `onMouseEnter` `onMouseLeave` `disabled`): https://plocks.dev/llms/components/Block.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Gradient fills a layout container with a color transition.

```tsx
import { Gradient, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Gradient colors={['#2563eb', '#7c3aed']} h={120} radius="lg" p="md" justify="center">
      <Text c="#ffffff" fw="bold">
        Gradient surface
      </Text>
    </Gradient>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/GradientText.md -->

# GradientText

A text component that displays text with gradient colors. Supports customizable gradients with multiple colors, different angles, and animated transitions (web only).

## Metadata

- Import: `import { GradientText } from '@plocks/ui';`
- Tags: text, gradient, animation, color
- Docs: https://plocks.dev/components/GradientText
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/GradientText

## Props

- `colors` (required): string[] — Array of colors for the gradient (at least 2 required)
- `locations`: number[] — Color stops (0-1) for each color. If not provided, colors are evenly distributed
- `angle`: number — Gradient direction angle in degrees (0 = left to right, 90 = top to bottom, etc.)
- `start`: [number, number] — Start point [x, y] (0-1). Overrides angle if provided
- `end`: [number, number] — End point [x, y] (0-1). Overrides angle if provided
- `position`: number — Gradient position offset (0-1). Moves the gradient along the line
- `animation`: GradientTextAnimation — Sweep the gradient position continuously (web only). Runs as a CSS animation, so no JavaScript executes per frame. Overrides `position` while it is running; on native — and under reduced motion — the gradient stays static.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Text` props (`children` `tx` `txParams` `variant` `textRole` `size` `fw` `ta` `lh` `lts` `tt` `fs` `td` `ff` `flex` `shrink` `top` `right` `bottom` `left` `as` `selectable` `onPress` `onLayout` `value` `numberOfLines` `ellipsizeMode` `id` `nativeID`): https://plocks.dev/llms/components/Text.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface GradientTextAnimation {
  /** Position offset the sweep starts from (same space as `position`) */
  from: number;
  /** Position offset the sweep ends at */
  to: number;
  /** Seconds for a single sweep */
  duration: number;
  /** Seconds to wait before the first sweep */
  delay?: number;
  /** Repeat forever instead of running once */
  repeat?: boolean;
  /** Seconds held at `to` between repeats */
  repeatDelay?: number;
}
```

## Examples

### Basics

Pass two or more `colors` to fill text with a gradient. All other `Text` props still apply.

```tsx
import { GradientText } from '@plocks/ui';

export function Demo() {
  return (
    <GradientText colors={['#FF0080', '#7928CA']}>
      Hello World
    </GradientText>
  );
}
```

### Angles

Different gradient directions using the `angle` prop.

```tsx
import { Block, GradientText } from '@plocks/ui';

const angles = [0, 45, 90, 135];

export function Demo() {
  return (
    <Block gap="md">
      {angles.map((angle) => (
        <GradientText key={angle} colors={['#FF0080', '#7928CA']} angle={angle} size="lg">
          {angle}° gradient
        </GradientText>
      ))}
    </Block>
  );
}
```

### Variants

The text variant changes the semantic element while keeping the gradient fill.

```tsx
import { Column, GradientText, Text } from '@plocks/ui';

const variants = ['h3', 'p', 'strong'] as const;

export function Demo() {
  return (
    <Column gap="md">
      {variants.map(variant => (
        <Column key={variant} gap="xs">
          <Text size="xs" c="secondary">{variant}</Text>
          <GradientText variant={variant} colors={['#FF0080', '#7928CA']}>
            Gradient text with semantic markup
          </GradientText>
        </Column>
      ))}
    </Column>
  );
}
```

### Controlled

Control the gradient position manually using the `position` prop (0.0 to 1.0).

```tsx
import { useState } from 'react';
import { Block, GradientText, Slider } from '@plocks/ui';

export function Demo() {
  const [position, setPosition] = useState(0);

  return (
    <Block>
      <GradientText
        value="Controlled Gradient"
        position={position}
        colors={['#ff76ba', '#FF0080', '#7928CA', '#4F46E5']}
        size="3xl"
      />
      <Slider
        value={position}
        onChange={setPosition}
        min={0}
        max={1}
        step={0.01}
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Grid.md -->

# Grid

Grid arranges items in responsive columns and spans.

## Metadata

- Import: `import { Grid } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Grid
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Grid

## Props

- `columns`: ResponsiveProp<number> — Number of columns (can be responsive)
- `gap`: SizeValue — Gap between items
- `rowGap`: SizeValue — Row gap between items
- `columnGap`: SizeValue — Column gap between items
- `fullWidth`: boolean — Make the grid take full width (100%)
- `children`: React.ReactNode — Children elements
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { GridItem } from '@plocks/ui';`

### GridItem

- `span`: ResponsiveProp<number> — Column span (how many columns this item should span) - can be responsive
- `children`: React.ReactNode — Children elements
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Basic 12-column grid with equal width items.

```tsx
import { Block, Card, Grid, GridItem, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Grid columns={12} gap="md">
        {Array.from({ length: 12 }).map((_, index) => (
          <GridItem key={index} span={1}>
            <Card variant="outline">
              <Text size="sm" ta="center">
                {index + 1}
              </Text>
            </Card>
          </GridItem>
        ))}
      </Grid>
    </Block>
  );
}
```

### Gaps

Row and column gutters come from the container: `gap` sets both, `rowGap` and `columnGap` override one each. Items never carry their own padding or margin.

```tsx
import { Block, Card, Grid, GridItem, Text } from '@plocks/ui';

const sections = [
  {
    label: 'Compact gap (xs)',
    props: { gap: 'xs' as const },
  },
  {
    label: 'Roomy gap (2xl)',
    props: { gap: '2xl' as const },
  },
  {
    label: 'Wide rows, tight columns',
    props: { rowGap: '2xl' as const, columnGap: 'xs' as const },
  },
];

export function Demo() {
  return (
    <Block fullWidth>
      {sections.map(({ label, props }) => (
        <Block key={label} fullWidth>
          <Text size="sm" fw="semibold">
            {label}
          </Text>
          <Grid columns={6} {...props}>
            {Array.from({ length: 12 }).map((_, index) => (
              <GridItem key={index} span={1}>
                <Card variant="outline">
                  <Text size="sm" ta="center">
                    Item {index + 1}
                  </Text>
                </Card>
              </GridItem>
            ))}
          </Grid>
        </Block>
      ))}
    </Block>
  );
}
```

### Nesting

Nested grids demonstrating composition inside a grid item.

```tsx
import { Block, Card, Grid, GridItem, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Grid columns={12} gap="md">
        <GridItem span={8}>
          <Card variant="outline">
            <Block>
              <Text size="sm" ta="center">
                Parent span=8
              </Text>
              <Grid columns={6} gap="sm">
                {Array.from({ length: 6 }).map((_, index) => (
                  <GridItem key={index} span={2}>
                    <Card variant="filled" p="xs">
                      <Text size="xs" ta="center">
                        Nested {index + 1}
                      </Text>
                    </Card>
                  </GridItem>
                ))}
              </Grid>
            </Block>
          </Card>
        </GridItem>
        <GridItem span={4}>
          <Card variant="outline">
            <Text size="sm" ta="center">
              Sidebar span=4
            </Text>
          </Card>
        </GridItem>
      </Grid>
    </Block>
  );
}
```

### Responsive

Pass breakpoint objects such as `{ base: 4, md: 8, lg: 12 }` to `columns` and `span` so the layout adapts at `base`, `md` and `lg`; each label lists its span at those three breakpoints.

```tsx
import { Block, Card, Grid, GridItem, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Grid columns={{ base: 4, md: 8, lg: 12 }} gap="md">
        <GridItem span={{ base: 4, md: 4, lg: 6 }}>
          <Card variant="outline">
            <Text size="sm" ta="center">Hero (4/4/6)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 4, md: 4, lg: 6 }}>
          <Card variant="outline">
            <Text size="sm" ta="center">Hero (4/4/6)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 2, md: 4, lg: 3 }}>
          <Card variant="outline">
            <Text size="sm" ta="center">Side (2/4/3)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 2, md: 4, lg: 3 }}>
          <Card variant="outline">
            <Text size="sm" ta="center">Side (2/4/3)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 4, md: 8, lg: 12 }}>
          <Card variant="outline">
            <Text size="sm" ta="center">Footer (4/8/12)</Text>
          </Card>
        </GridItem>
      </Grid>
    </Block>
  );
}
```

### Spans

Demonstrates varying column spans within a 12-column grid.

```tsx
import { Block, Card, Grid, GridItem, Text } from '@plocks/ui';

export function Demo() {
  const spans = [6, 6, 4, 4, 4, 3, 3, 3, 3];

  return (
    <Block fullWidth>
      <Grid columns={12} gap="md">
        {spans.map((span, index) => (
          <GridItem key={`${span}-${index}`} span={span}>
            <Card variant="outline">
              <Text size="sm" ta="center">{`span=${span}`}</Text>
            </Card>
          </GridItem>
        ))}
      </Grid>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Highlight.md -->

# Highlight

Highlight emphasizes matching fragments inside longer strings, reusing the Text component so typography settings stay consistent across platforms.

## Metadata

- Import: `import { Highlight } from '@plocks/ui';`
- Tags: text, emphasis, highlight, mark
- Docs: https://plocks.dev/components/Highlight
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Highlight

## Props

- `highlight`: HighlightValue | HighlightValue[] — Substring or substrings to emphasize within the provided children
- `highlightStyles`: HighlightStyles — Optional override for the highlighted segment styles. Accepts either a style object/array or a callback that receives the current theme and returns styles.
- `highlightColor`: string — Marker background. Defaults to the theme's `backgrounds.mark`. A theme palette name (`'teal'`, `'highlight'`) uses a soft shade of that palette; `'primary.2'` shade syntax, a background role (`'selected'`) or any CSS color is used as-is. The fragment's text color stays readable on it.
- `caseSensitive`: boolean = false — Toggle case-sensitive matching (defaults to case-insensitive).
- `trim`: boolean = true — Trim highlight values before matching to ignore accidental whitespace. Defaults to true.
- `highlightProps`: Partial<TextProps> — Additional props applied to the highlighted Text nodes.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Text` props (`children` `tx` `txParams` `variant` `textRole` `size` `c` `fw` `ta` `lh` `lts` `tt` `fs` `td` `ff` `flex` `shrink` `position` `top` `right` `bottom` `left` `as` `selectable` `onPress` `onLayout` `value` `numberOfLines` `ellipsizeMode` `id` `nativeID`): https://plocks.dev/llms/components/Text.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type HighlightValue = string | number;

export type HighlightStyles = StyleProp<TextStyle> | ((theme: PlocksTheme) => StyleProp<TextStyle>);
```

## Examples

### Basics

Default highlight behavior with a single search term. Matching fragments are wrapped with the theme-aware highlight styles.

```tsx
import { View } from 'react-native';
import { Highlight, Text } from '@plocks/ui';

const PARAGRAPH = 'Highlight This, definitely THIS and also this!';

export function Demo() {
  return (
    <View>
      <Text variant="h5">Case-insensitive match</Text>
      <Highlight highlight="this">{PARAGRAPH}</Highlight>
    </View>
  );
}
```

### Variants

Use semantic text variants without changing which phrase is highlighted.

```tsx
import { Column, Highlight, Text } from '@plocks/ui';

const variants = ['h4', 'p', 'small'] as const;

export function Demo() {
  return (
    <Column gap="md">
      {variants.map(variant => (
        <Column key={variant} gap="xs">
          <Text size="xs" c="secondary">{variant}</Text>
          <Highlight variant={variant} highlight="design">A design system for every screen.</Highlight>
        </Column>
      ))}
    </Column>
  );
}
```

### Multiple

Pass an array to highlight several distinct substrings. Every match shares the same styles by default.

```tsx
import { View } from 'react-native';
import { Highlight, Text } from '@plocks/ui';

const SENTENCE = 'plocks brings patterns, blocks, and building tools together.';

export function Demo() {
  return (
    <View>
      <Text variant="h5">Multiple values</Text>
      <Highlight highlight={['blocks', 'tools']}>{SENTENCE}</Highlight>
    </View>
  );
}
```

### Styles

Swap the marker color with the `highlightColor` prop, passing any theme palette name. The default marker style (yellow background, unchanged text) is preserved.

```tsx
import { Highlight, Text, Block } from '@plocks/ui';

const copy = 'You can switch the highlight color while keeping the default marker style.';

export function Demo() {
  return (
    <Block>
      <Text variant="h5">Highlight color</Text>
      <Highlight highlight="highlight" highlightColor="highlight">{copy}</Highlight>
      <Highlight highlight="color" highlightColor="teal">{copy}</Highlight>
      <Highlight highlight="marker" highlightColor="pink">{copy}</Highlight>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/HoverCard.md -->

# HoverCard

HoverCard shows supplementary content beside a target on hover or focus.

## Metadata

- Import: `import { HoverCard } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/HoverCard
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/HoverCard

## Props

- `children` (required): ReactNode — Floating content
- `target` (required): ReactElement — Element that shows the card. It receives the hover / focus / press handlers directly — no wrapper, so no extra tab stop.
- `position`: 'top' | 'bottom' | 'left' | 'right' | 'auto' = 'bottom' — Position relative to target (written for LTR; mirrored in RTL). @default 'bottom'
- `offset`: number = 8 — Offset gap between target and card
- `openDelay`: number = 100 — Delay before opening (ms). @default 100
- `closeDelay`: number = 150 — Delay before closing (ms). @default 150
- `opened`: boolean — Controlled opened state
- `defaultOpened`: boolean = false — Initial opened state when uncontrolled. @default false
- `shadow`: 'none' | 'sm' | 'md' | 'lg' = 'md' — Shadow size. @default 'md'
- `radius`: RadiusValue = 'md' — Corner radius. @default 'md'
- `w`: number = fits the content, between 160 and 320 — Card width. @default fits the content, between 160 and 320
- `withArrow`: boolean = false — Show directional arrow
- `closeOnEscape`: boolean = true — Close on Escape (web) and Android back. @default true
- `onOpen`: () => void — Called when opened
- `onClose`: () => void — Called when closed
- `disabled`: boolean = false — Disable interactions
- `zIndex`: number = the theme's `popover` layer — z-index override. @default the theme's `popover` layer
- `trigger`: 'hover' | 'click' = 'hover' — `hover` (default): pointer hover or keyboard focus shows it; a press toggles it where there is no hover (touch). `click`: a press toggles it and focus moves into the card.
- `strategy`: 'fixed' | 'portal' = 'fixed' on web, 'portal' (an RN Modal) on native — Positioning strategy. @default 'fixed' on web, 'portal' (an RN Modal) on native
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Pass the element that shows the card as `target` and the card content as children. The card opens when the pointer rests on the target or when the target receives keyboard focus, stays open while the pointer is on the card, and closes on Escape. On touch devices a tap toggles it.

```tsx
import { Avatar, Block, Button, HoverCard, Text } from '@plocks/ui';

export function Demo() {
  return (
    <HoverCard
      target={
        <Button variant="subtle" size="sm">
          @plocks
        </Button>
      }
    >
      <Block gap="xs" style={{ maxWidth: 240 }}>
        <Avatar
          fallback="PB"
          label="plocks"
          description="@plocks"
          accessibilityLabel="plocks"
        />
        <Text size="sm" c="secondary">
          Cross-platform UI components for React Native and the web.
        </Text>
      </Block>
    </HoverCard>
  );
}
```

### Click Trigger

Set `trigger="click"` for cards with interactive content: a press toggles the card, focus moves into it, and Escape or a press outside closes it and returns focus to the target.

```tsx
import { Block, Button, HoverCard, Text } from '@plocks/ui';

export function Demo() {
  return (
    <HoverCard
      trigger="click"
      w={260}
      target={
        <Button variant="outline" size="sm">
          Show details
        </Button>
      }
    >
      <Block gap="xs">
        <Text fw="semibold">Deployment #482</Text>
        <Text size="sm" c="secondary">Built from main 4 minutes ago.</Text>
        <Button size="xs" variant="subtle">
          View logs
        </Button>
      </Block>
    </HoverCard>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Icon.md -->

# Icon

The `Icon` component displays icons with optional captions and overlays, providing a flexible way to present visual content in your application.

## Metadata

- Import: `import { Icon } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Icon
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Icon

## Props

- `name`: string — Icon name from the registry
- `icon`: ExternalIconComponent | React.ReactElement — An external icon library component or element, rendered instead of `name`. Enables using any icon library (e.g. Tabler) without registry registration.
- `size`: IconSize = 'md' — Size token or px.
- `color`: ColorProp — Icon color: palette token (`'primary'`, `'error.6'`) or any CSS color. Defaults to `theme.text.primary`.
- `stroke`: number = 1.5 — Stroke thickness for outlined icons. Defaults to 1.5.
- `variant`: 'filled' | 'outlined' — Icon variant - overrides the default variant from icon definition
- `label`: string — Accessible name. An icon with a name is announced as an image; without one it is decorative (hidden from assistive technology).
- `accessibilityLabel`: string — Alias of `label`.
- `title`: string — Alias of `label` (the icon's title).
- `decorative`: boolean — Hide the icon from assistive technology. Defaults to `true` unless the icon has an accessible name (`label` / `accessibilityLabel` / `title`), so icons inside labelled controls never add noise to what a screen reader announces.
- `mirrorInRTL`: boolean — Whether to mirror this icon in RTL mode. If not specified, uses auto-detection based on icon name
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type ExternalIconComponent = React.ComponentType<ExternalIconProps>;

export type IconSize = SizeValue;

export interface ExternalIconProps {
  size?: number | string;
  color?: ColorValue;
  strokeWidth?: number | string;
  style?: StyleProp<ViewStyle>;
  /** Icon libraries take extra SVG props; they are passed through untouched. */
  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- must accept any icon library's props (Tabler, lucide, vector-icons…).
  [key: string]: any;
}
```

## Examples

### Basics

Render any icon from the built-in Tabler set by its registry `name`.

```tsx
import { Icon, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="lg" align="center" wrap="wrap">
      <Icon name="home" />
      <Icon name="search" />
      <Icon name="bell" />
      <Icon name="calendar" />
      <Icon name="heart" />
      <Icon name="star" />
      <Icon name="user" />
      <Icon name="settings" />
    </Row>
  );
}
```

### Stroke

Set `stroke` to change the line thickness of outlined icons. It defaults to `1.5`.

```tsx
import { Flex, Icon, Text } from '@plocks/ui';

const strokeVariants = [
  { label: 'Thin (0.75)', value: 0.75 },
  { label: 'Default (1.5)', value: 1.5 },
  { label: 'Bold (3)', value: 3 },
];

export function Demo() {
  return (
    <Flex direction="row" align="center" gap="lg" wrap="wrap">
      {strokeVariants.map(({ label, value }) => (
        <Flex key={label} direction="column" align="center" gap="sm">
          <Icon name="contrast" size="xl" stroke={value} />
          <Text variant="small" style={{ textAlign: 'center' }}>{label}</Text>
        </Flex>
      ))}
    </Flex>
  );
}
```

### Variants

Compare filled and outlined versions of the same icons.

```tsx
import { Column, Icon, Row, Text } from '@plocks/ui';

const variants = ['outlined', 'filled'] as const;

export function Demo() {
  return (
    <Column gap="md">
      {variants.map(variant => (
        <Row key={variant} gap="md" align="center">
          <Text>{variant}</Text>
          <Icon name="heart" variant={variant} size="xl" />
          <Icon name="star" variant={variant} size="xl" />
          <Icon name="bell" variant={variant} size="xl" />
        </Row>
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/IconButton.md -->

# IconButton

IconButton triggers an action with an icon instead of a text label.

## Metadata

- Import: `import { IconButton } from '@plocks/ui';`
- Tags: button, icon, clickable, action
- Docs: https://plocks.dev/components/IconButton
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/IconButton

## Props

- `icon` (required): string | ExternalIconComponent | React.ReactElement — Icon to render. Accepts a registry name, or an external icon library component/element (e.g. a Tabler icon) for use without registration.
- `variant`: 'default' | 'filled' | 'secondary' | 'outline' | 'ghost' | 'gradient' | 'none' = 'default' — Button visual variant. `default` is the neutral button, matching `Button`; a solid primary fill is opt-in via `filled`.
- `color`: ColorProp — Tint for the button: a palette token (`'primary'`), `'primary.6'` shade syntax, or any CSS color. `filled`, `secondary` and `outline` tint the container; `ghost` and the neutral `default`/`none` keep their chrome and tint only the icon.
- `iconColor`: ColorProp — Explicit icon color override (else derived automatically from variant & color)
- `iconVariant`: IconProps['variant'] — Icon variant override
- `iconSize`: IconProps['size'] — Icon size override (defaults to half the button height)
- `accessibilityLabel`: string — Accessible name. Icon-only buttons need one: pass this, or a `tooltip` (whose text is then used as the name). A dev warning fires when neither is set.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Button` props (`onPress` `onPressIn` `onPressOut` `onHoverIn` `onHoverOut` `onLongPress` `onLayout` `size` `disabled` `loading` `fullWidth` `tooltip` `transitionDuration` `accessibilityHint`): https://plocks.dev/llms/components/Button.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

IconButton triggers an action with an icon instead of a text label.

```tsx
import { IconButton, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" align="center" wrap="wrap">
      <IconButton icon="home" tooltip="Home" />
      <IconButton icon="bell" variant="filled" tooltip="Notifications" />
      <IconButton icon="heart" variant="secondary" tooltip="Favorite" />
      <IconButton icon="settings" variant="outline" tooltip="Settings" />
      <IconButton icon="search" variant="ghost" tooltip="Search" />
      <IconButton icon="star" variant="gradient" tooltip="Star" />
    </Row>
  );
}
```

### Variants

Compare every IconButton visual variant with the same icon and size.

```tsx
import { IconButton, Row } from '@plocks/ui';

const variants = ['default', 'filled', 'secondary', 'outline', 'ghost', 'gradient', 'none'] as const;

export function Demo() {
  return (
    <Row gap="sm" align="center" wrap="wrap">
      {variants.map(variant => (
        <IconButton key={variant} icon="heart" variant={variant} accessibilityLabel={`${variant} icon button`} tooltip={variant} />
      ))}
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Image.md -->

# Image

The `Image` component displays images with optional captions and overlays, providing a flexible way to present visual content in your application.

## Metadata

- Import: `import { Image } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Image
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Image

## Props

- `src`: string | ImageSourcePropType — Remote image URI, or a bundled asset from `require('./photo.png')`
- `source`: ImageSourcePropType — Image source object (alternative to src)
- `alt`: string — Text alternative, announced by screen readers (`aria-label` on web, `accessibilityLabel` on native). Pass `alt=""` for a purely decorative image: it is then hidden from assistive technology. An image with neither `alt` nor `accessibilityLabel` is treated as decorative too.
- `accessibilityLabel`: string — Accessible name; takes precedence over `alt`.
- `resizeMode`: 'cover' | 'contain' | 'stretch' | 'repeat' | 'center' = 'cover' — Image resize mode
- `size`: SizeValue — Size preset (`xs` 24 … `3xl` 96) or a square size in px. `w` / `h` win over it.
- `aspectRatio`: number — Aspect ratio
- `borderWidth`: number — Border width
- `borderColor`: ColorValue — Border color (defaults to the theme border color)
- `radius`: RadiusValue — Corner radius: size token, px number, `'none'` or `'full'`. Wins over `rounded`.
- `rounded`: boolean — Round the corners with the theme's `md` radius
- `circle`: boolean — Render as a circle (radius = half the width)
- `fallback`: React.ReactNode — Fallback element to show on error
- `loading`: React.ReactNode — Loading state element
- `onLoad`: () => void — Called when image loads successfully
- `onError`: (error: NativeSyntheticEvent<ImageErrorEventData>) => void — Called when image fails to load
- `onLoadStart`: () => void — Called when image starts loading
- `onLoadEnd`: () => void — Called when image finishes loading (success or error)
- `containerStyle`: StyleProp<ViewStyle> — Container style (applied before `style`)
- `imageStyle`: StyleProp<ImageStyle> — Image style overrides
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Pass a `src` and size the image with `w` and `h`; `alt` gives screen readers a text alternative.

```tsx
import { Image } from '@plocks/ui';

export function Demo() {
  return (
    <Image
      src={require('../../../../assets/images/scene-mountains.png')}
      alt="Mountain landscape"
      w={300}
      h={200}
    />
  );
}
```

### Sizes

Set the `size` prop to any token (`xs`–`3xl`) to scale the image box, or pass `w`/`h` when you need exact dimensions.

```tsx
import { Block, Image, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

/** Inline 8x8 PNG — keeps the demo offline and identical on web and native. */
const SAMPLE_SRC =
  'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAALklEQVR42mNITvsIR409P+CIAasokMuAVRQqgSkKksAqiiKB5goGrKJQCawuBgC2Wnfh+zNA9wAAAABJRU5ErkJggg==';

export function Demo() {
  return (
    <Row align="flex-end" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Image src={SAMPLE_SRC} size={size} radius="md" alt={`Sample image at ${size}`} />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Shapes

Add `rounded` for the theme's corner radius or `circle` to crop the image into a circle.

```tsx
import { Block, Image, Row, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Row align="flex-start" gap="lg" wrap="wrap">
      <Block align="center">
        <Image
          src={require('../../../../assets/images/scene-lake.png')}
          size={80}
          alt="Default"
        />
        <Text variant="small">Default</Text>
      </Block>

      <Block align="center">
        <Image
          src={require('../../../../assets/images/scene-lake.png')}
          size={80}
          rounded
          alt="Rounded"
        />
        <Text variant="small">Rounded</Text>
      </Block>

      <Block align="center">
        <Image
          src={require('../../../../assets/images/scene-lake.png')}
          size={80}
          circle
          alt="Circle"
        />
        <Text variant="small">Circle</Text>
      </Block>
    </Row>
  );
}
```

### Fallback

When the image fails to load, whatever you pass to `fallback` (an icon, text, any element) renders in its place.

```tsx
import { Block, Icon, Image, Row, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Row align="flex-start" gap="lg" wrap="wrap">
      <Block align="center">
        <Image
          src="https://invalid-url-that-will-fail.com/image.jpg"
          w={120}
          h={80}
          fallback={<Icon name="image-off" size={24} color="gray.5" />}
          alt="Failed to load"
        />
        <Text variant="small">Icon fallback</Text>
      </Block>

      <Block align="center">
        <Image
          src="https://another-invalid-url.com/image.jpg"
          w={120}
          h={80}
          fallback={
            <Text size="sm" c="gray.6" ta="center">
              Image not found
            </Text>
          }
          alt="Failed to load"
        />
        <Text variant="small">Text fallback</Text>
      </Block>
    </Row>
  );
}
```

### Spacing

Image accepts the universal margin props: theme tokens (`m="lg"`), pixel numbers (`m={20}`), axis shorthands (`mx`, `my`), and `auto` to center it.

```tsx
import { Block, Card, Image, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="small">m="auto"</Text>
        <Card variant="subtle" p={0}>
          <Image
            src={require('../../../../assets/images/scene-meadow.png')}
            alt="Centered image"
            w={100}
            h={100}
            m="auto"
          />
        </Card>
      </Block>

      <Block>
        <Text variant="small">m="lg"</Text>
        <Card variant="subtle" p={0}>
          <Image
            src={require('../../../../assets/images/scene-meadow.png')}
            alt="Image with theme spacing"
            w={80}
            h={80}
            m="lg"
          />
        </Card>
      </Block>

      <Block>
        <Text variant="small">m={'{20}'}</Text>
        <Card variant="subtle" p={0}>
          <Image
            src={require('../../../../assets/images/scene-meadow.png')}
            alt="Image with numeric spacing"
            w={60}
            h={60}
            m={20}
          />
        </Card>
      </Block>

      <Block>
        <Text variant="small">mx="auto" my="md"</Text>
        <Card variant="subtle" p={0}>
          <Image
            src={require('../../../../assets/images/scene-meadow.png')}
            alt="Image with axis spacing"
            w={80}
            h={80}
            mx="auto"
            my="md"
          />
        </Card>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Indicator.md -->

# Indicator

Indicator places a status dot or count on a parent element.

## Metadata

- Import: `import { Indicator } from '@plocks/ui';`
- Tags: indicator, badge, status, count, dot
- Docs: https://plocks.dev/components/Indicator
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Indicator

## Props

- `size`: SizeValue | number = 'sm' — Dot diameter: a size token (the font size of that token) or px. @default 'sm'
- `color`: ColorProp = 'success' — Fill: palette token, `'primary.6'` shade syntax, or CSS color. @default 'success'
- `borderColor`: ColorProp = theme.backgrounds.surface — Ring color separating the dot from what it sits on. @default theme.backgrounds.surface
- `borderWidth`: number = 1
- `placement`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' = 'bottom-right' — Corner of the parent. `left` / `right` follow the reading direction (they mirror under RTL).
- `offset`: number = 0
- `children`: React.ReactNode — Free-form content rendered inside the indicator dot. Useful when a custom icon is needed; for plain text counts prefer `label`, which auto-resizes the dot and applies a contrast-aware text color.
- `label`: React.ReactNode — Convenience text content (typically a count). When set, the dot expands to fit the label and the text uses a contrast-aware color.
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>` (style, fw, ff, size, c).
- `accessibilityLabel`: string — Accessible description of what the indicator means ("Online", "3 unread messages"). Without it a plain dot is decorative.
- `invisible`: boolean
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Place `Indicator` inside a relatively positioned container to pin a status dot to its corner.

```tsx
import { Avatar, Block, Indicator } from '@plocks/ui';

export function Demo() {
  return (
    <Block position="relative">
      <Avatar size="lg" fallback="JS" />
      <Indicator size="md" accessibilityLabel="Online" />
    </Block>
  );
}
```

### Placements

Set `placement` to pin the indicator to any corner of its container.

```tsx
import { Block, Indicator, Row, Text } from '@plocks/ui';

const PLACEMENTS = ['top-left', 'top-right', 'bottom-left', 'bottom-right'] as const;

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      {PLACEMENTS.map((placement) => (
        <Block
          key={placement}
          w={88}
          h={88}
          radius="lg"
          bg="subtle"
          position="relative"
          align="center"
          justify="center"
        >
          <Text size="xs" c="secondary">
            {placement}
          </Text>
          <Indicator placement={placement} />
        </Block>
      ))}
    </Row>
  );
}
```

### Sizes

Set the `size` prop to any token (`xs`–`3xl`) for theme-aligned dots, or provide a raw number when you need a bespoke diameter for your badge.

```tsx
import { Block, Card, Indicator, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', 24] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Card w={56} h={56} radius="lg">
            <Indicator placement="top-right" size={size} offset={4} />
          </Card>
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Statuses

Map presence states (online, idle, busy, offline) to palette colors with `color`, and give each dot an `accessibilityLabel` so the status is announced, not just shown.

```tsx
import { Avatar, Block, Indicator, Row, Text } from '@plocks/ui';

const presenceStatuses = [
  { label: 'Online', palette: 'success', avatar: require('../../../../assets/avatars/avatar-1.png') },
  { label: 'Idle', palette: 'warning', avatar: require('../../../../assets/avatars/avatar-2.png') },
  { label: 'Busy', palette: 'error', avatar: require('../../../../assets/avatars/avatar-3.png') },
  { label: 'Offline', palette: 'gray', avatar: require('../../../../assets/avatars/avatar-4.png') },
] as const;

export function Demo() {
  return (
    <Row gap="lg" wrap="wrap">
      {presenceStatuses.map((status) => (
        <Block key={status.label} align="center">
          <Block position="relative">
            <Avatar
              size={56}
              fallback={status.label.charAt(0)}
              src={status.avatar}
            />
            <Indicator size={14} color={status.palette} accessibilityLabel={status.label} />
          </Block>
          <Text size="xs" c="secondary">
            {status.label}
          </Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Labels & counts

Pass `label` to render a count or short text inside the indicator — the dot expands to a pill so multi-digit values fit. `labelProps` accepts any `<Text>` props for fonts, weights, etc. For arbitrary custom content (icons, status markers), use `children` instead.

```tsx
import { View } from 'react-native';
import { Block, Indicator, Row } from '@plocks/ui';

const Anchor = ({ children }: { children?: React.ReactNode }) => (
  <Block w={48} h={48} radius="full" bg="subtle" position="relative" align="center" justify="center">
    {children}
  </Block>
);

export function Demo() {
  return (
    <Row gap="lg" wrap="wrap">
      <Anchor>
        <Indicator size={20} color="#ef4444" label={3} />
      </Anchor>
      <Anchor>
        <Indicator size={20} color="#ef4444" label={12} />
      </Anchor>
      <Anchor>
        <Indicator size={20} color="#ef4444" label="99+" />
      </Anchor>
      <Anchor>
        <Indicator size={22} color="#0ea5e9" label="42" labelProps={{ ff: 'monospace' }} />
      </Anchor>
      <Anchor>
        <Indicator
          size={22}
          color="#10b981"
          label="NEW"
          labelProps={{ tt: 'uppercase', lts: 1, size: 9 }}
        />
      </Anchor>
      <Anchor>
        <Indicator size={16} color="#10b981">
          <View style={{ width: 6, height: 6, borderRadius: 3, backgroundColor: '#fff' }} />
        </Indicator>
      </Anchor>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Input.md -->

# Input

Input provides a styled text field with labels, validation states, and helper text.

## Metadata

- Import: `import { Input } from '@plocks/ui';`
- Tags: input, form, text, validation
- Docs: https://plocks.dev/components/Input
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Input

## Props

- `type`: 'text' | 'password' | 'email' | 'tel' | 'number' | 'search' = 'text' — Input type - determines styling and behavior
- `validation`: ValidationRule[] — Validation rules, checked after the field is first blurred and then on every change (debounced by `debounceMs`). The first failing rule's message is shown as the error while no `error` prop is given.
- `autoComplete`: 'off' | 'password' | 'email' | 'tel' | 'url' | 'name' | 'additional-name' | 'address-line1' | 'address-line2' | 'birthdate-day' | 'birthdate-full' | 'birthdate-month' | 'birthdate-year' | 'cc-csc' | 'cc-exp' | 'cc-exp-month' | 'cc-exp-year' | 'cc-number' | 'country' | 'current-password' | 'family-name' | 'given-name' | 'honorific-prefix' | 'honorific-suffix' | 'new-password' | 'one-time-code' | 'organization' | 'organization-title' | 'postal-code' | 'street-address' | 'username' — Auto-complete type
- `keyboardType`: KeyboardTypeOptions — Keyboard type for mobile
- `multiline`: boolean — Whether input is multiline
- `numberOfLines`: number — Number of lines for multiline input
- `minLines`: number = 1 — Minimum number of lines for multiline input (default: 1)
- `maxLines`: number — Maximum number of lines for multiline input
- `maxLength`: number — Maximum length
- `autoCapitalize`: RNTextInputProps['autoCapitalize'] — Text auto-capitalization behavior
- `autoCorrect`: boolean — Whether to enable auto-correct
- `autoFocus`: boolean — Whether to auto-focus on mount
- `returnKeyType`: RNTextInputProps['returnKeyType'] — Return key type for soft keyboard
- `blurOnSubmit`: boolean — Whether to blur on submit
- `selectTextOnFocus`: boolean — Select all text on focus
- `textContentType`: RNTextInputProps['textContentType'] — iOS text content type for autofill
- `textAlign`: RNTextInputProps['textAlign'] — Text alignment
- `spellCheck`: boolean — Whether spell check is enabled
- `inputMode`: RNTextInputProps['inputMode'] — Input mode (modern alternative to keyboardType)
- `enterKeyHint`: RNTextInputProps['enterKeyHint'] — Hint for the enter key
- `selectionColor`: string — Color of the text selection handles and highlight
- `showSoftInputOnFocus`: boolean — Whether to show the soft keyboard on focus
- `editable`: boolean — Passthrough to the TextInput. Prefer `readOnly`; `editable={false}` behaves the same.
- `flex`: number — Flex factor for an input placed beside buttons or icons.
- `inputColor`: string — Color of the editable text.
- `inputFontSize`: number — Editable text size in pixels.
- `id`: string — Id of the TextInput (DOM `id` on web, `nativeID` on native); label/error ids derive from it. Generated when omitted.
- `focused`: boolean — Force the focused look regardless of real focus.
- `textInputProps`: ExtendedTextInputProps — Additional TextInput props.
- `inputRef`: React.Ref<TextInput> — Extra ref to the TextInput; merged with `ref`.
- `secureTextEntry`: boolean — Force secure entry regardless of type.
- `containerProps`: Omit<ViewProps, 'style' | 'testID' | 'children'> — Props for the root `View` (gesture handlers, onLayout, ...).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `debounceMs` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { PasswordInput, TextInputBase } from '@plocks/ui';`

### PasswordInput

- `showStrengthIndicator`: boolean — Whether to show password strength indicator
- `showVisibilityToggle`: boolean — Whether to show toggle visibility button
- `strengthValidation`: PasswordStrengthRule[] — Password strength validation rules
- `flex`: number — Flex factor for an input placed beside buttons or icons.
- `inputColor`: string — Color of the editable text.
- `inputFontSize`: number — Editable text size in pixels.
- `id`: string — Id of the TextInput (DOM `id` on web, `nativeID` on native); label/error ids derive from it. Generated when omitted.
- `focused`: boolean — Force the focused look regardless of real focus.
- `textInputProps`: ExtendedTextInputProps — Additional TextInput props.
- `inputRef`: React.Ref<TextInput> — Extra ref to the TextInput; merged with `ref`.
- `containerProps`: Omit<ViewProps, 'style' | 'testID' | 'children'> — Props for the root `View` (gesture handlers, onLayout, ...).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Input` props (`validation` `autoComplete` `keyboardType` `multiline` `numberOfLines` `minLines` `maxLines` `maxLength` `autoCapitalize` `autoCorrect` `autoFocus` `returnKeyType` `blurOnSubmit` `selectTextOnFocus` `textContentType` `textAlign` `spellCheck` `inputMode` `enterKeyHint` `selectionColor` `showSoftInputOnFocus` `editable`): https://plocks.dev/llms/components/Input.md

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `debounceMs` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

### TextInputBase

- `flex`: number — Flex factor for an input placed beside buttons or icons.
- `inputColor`: string — Color of the editable text.
- `inputFontSize`: number — Editable text size in pixels.
- `id`: string — Id of the TextInput (DOM `id` on web, `nativeID` on native); label/error ids derive from it. Generated when omitted.
- `focused`: boolean — Force the focused look regardless of real focus.
- `textInputProps`: ExtendedTextInputProps — Additional TextInput props.
- `inputRef`: React.Ref<TextInput> — Extra ref to the TextInput; merged with `ref`.
- `secureTextEntry`: boolean — Force secure entry regardless of type.
- `containerProps`: Omit<ViewProps, 'style' | 'testID' | 'children'> — Props for the root `View` (gesture handlers, onLayout, ...).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `debounceMs` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface ValidationRule {
  type: 'required' | 'minLength' | 'maxLength' | 'pattern' | 'custom' | 'passwordStrength';
  value?: ValidationRuleValue;
  message: string;
  /** Custom check for `type: 'custom'`. */
  validator?: ValidatorFunction;
}

export interface PasswordStrengthRule extends Omit<ValidationRule, 'type'> {
  type: 'passwordStrength';
  requirements: {
    minLength?: number;
    requireUppercase?: boolean;
    requireLowercase?: boolean;
    requireNumbers?: boolean;
    requireSymbols?: boolean;
  };
}

export type ExtendedTextInputProps = Omit<RNTextInputProps, keyof TextFieldBaseProps> & {
  /** Style of the TextInput itself, merged after the field's text style. */
  style?: RNTextInputProps['style'];
  onKeyDown?: (event: WebKeyboardEvent) => void;
  onKeyUp?: (event: WebKeyboardEvent) => void;
};

export type ValidationRuleValue = number | string | RegExp;

export type ValidatorFunction = {
  bivarianceHack(value: unknown, formValues?: Record<string, unknown>): boolean | Promise<boolean>;
}['bivarianceHack'];
```

## Examples

### Basics

Basic text input with label, placeholder, and value handling.

```tsx
import { useState } from 'react';

import { Input } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState('');

  return (
    <Input
      label="Full name"
      placeholder="Enter your full name"
      value={value}
      onChangeText={setValue}
    />
  );
}
```

### Variants

Four visual variants for the input shell: `default`, `filled`, `outline`, and `unstyled`. The variant only changes the container fill and border — label, sections, and disclaimer stay consistent.

```tsx
import { Block, Input } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Input variant="default" label="Default" placeholder="user@example.com" />
      <Input variant="filled" label="Filled" placeholder="user@example.com" />
      <Input variant="outline" label="Outline" placeholder="user@example.com" />
      <Input variant="unstyled" placeholder="Unstyled — type to edit inline" />
    </Block>
  );
}
```

### Types

Set `type` to switch the keyboard and browser behaviour — email, password, number, and tel are all supported.

```tsx
import { Block, Input } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Input type="email" label="Email address" placeholder="user@example.com" />
      <Input type="password" label="Password" placeholder="Enter your password" />
      <Input type="number" label="Age" placeholder="Enter your age" />
      <Input type="tel" label="Phone number" placeholder="+1 (555) 123-4567" />
    </Block>
  );
}
```

### Validation

Pass `error` to show a validation message, `required` to mark the field, and `helperText` for guidance. `disabled` blocks editing.

```tsx
import { useState } from 'react';

import { Block, Input } from '@plocks/ui';

const isValidEmail = (email: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);

export function Demo() {
  const [email, setEmail] = useState('');

  return (
    <Block fullWidth>
      <Input
        type="email"
        label="Email address"
        placeholder="user@example.com"
        value={email}
        onChangeText={setEmail}
        required
        error={email.length > 0 && !isValidEmail(email) ? 'Please enter a valid email address' : undefined}
        helperText="We'll never share your email"
      />

      <Input label="Disabled" value="Cannot edit this value" disabled />
    </Block>
  );
}
```

### Multiline Modes

Pair `multiline` with `minLines`/`maxLines` to auto-expand, or with `numberOfLines` for a fixed height.

```tsx
import { useState } from 'react';

import { Block, Input } from '@plocks/ui';

export function Demo() {
  const [autoText, setAutoText] = useState('');
  const [fixedText, setFixedText] = useState('');

  return (
    <Block fullWidth>
      <Input
        label="Auto-expanding"
        placeholder="Start typing — press Enter to add lines"
        value={autoText}
        onChangeText={setAutoText}
        multiline
        minLines={1}
        maxLines={5}
        helperText="Grows from 1 to 5 lines, then scrolls"
      />

      <Input
        label="Fixed height"
        placeholder="Always 3 lines tall"
        value={fixedText}
        onChangeText={setFixedText}
        multiline
        numberOfLines={3}
      />
    </Block>
  );
}
```

### Sections and slot styling

Render content inside the field with `startSection` / `endSection`, and add `clearable` for a dismiss button. `startSectionProps` and `endSectionProps` accept any `<View>` props (including `style`) and apply them to the slot wrapper; `placeholderTextColor` overrides the muted default.

```tsx
import { useState } from 'react';

import { Block, Icon, Input, Text } from '@plocks/ui';

export function Demo() {
  const [workspace, setWorkspace] = useState('');
  const [search, setSearch] = useState('');

  return (
    <Block fullWidth>
      <Input
        label="URL"
        placeholder="my-workspace"
        value={workspace}
        onChangeText={setWorkspace}
        startSection={<Text ff="monospace" c="muted">https://</Text>}
        startSectionProps={{ style: { paddingRight: 8 } }}
      />

      <Input
        label="Search"
        placeholder="Find anything…"
        value={search}
        onChangeText={setSearch}
        clearable
        placeholderTextColor="#a855f7"
        startSection={<Icon name="search" size={16} />}
        startSectionProps={{ style: { paddingRight: 8 } }}
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Joystick.md -->

# Joystick

Joystick captures two-axis input as a spring-return stick or persistent XY pad.

## Metadata

- Import: `import { Joystick } from '@plocks/ui';`
- Tags: joystick, xy, pad, gesture, two-axis, input
- Docs: https://plocks.dev/components/Joystick
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Joystick

## Props

- `value`: JoystickValue — Controlled value. Both axes are normalized to −1…1.
- `defaultValue`: JoystickValue — Initial value while uncontrolled. Default `{ x: 0, y: 0 }`.
- `onChange`: (value: JoystickValue) => void — Fired for every position change, including each frame of a drag.
- `onChangeEnd`: (value: JoystickValue) => void — Fired once when the gesture ends, with the value it settled on.
- `onChangeStart`: (value: JoystickValue) => void — Fired when a drag or keyboard interaction begins.
- `shape`: 'circle' | 'square' = 'circle' — `circle` clamps the handle to a disc — a stick. `square` clamps each axis on its own so the corners are reachable — an XY pad. Default `circle`.
- `returnToCenter`: boolean — Spring the handle back to the centre when released, the way a physical stick does. Defaults to `true` for `circle` and `false` for `square`.
- `lockAxis`: 'x' | 'y' — Restrict travel to a single axis.
- `deadZone`: number = 0 — Report `0` until the handle travels this far from centre (0–1). Default `0`.
- `step`: number = 0 — Snap each axis to this increment. Default `0` (continuous).
- `keyboardStep`: number — Increment applied by a single arrow key press. Defaults to `step` or `0.1`.
- `invertY`: boolean = true — Report a positive `y` when the handle is pushed up. Default `true`.
- `size`: ComponentSizeValue = 'md' — Outer size in px, or a size token. Default `'md'`.
- `handleSize`: number — Handle diameter in px. Defaults to ~32% of `size`.
- `variant`: 'default' | 'filled' | 'outline' | 'minimal' | 'unstyled' = 'default' — Visual preset. Default `'default'`.
- `color`: string — Accent color: a palette token (`'primary'`), `'primary.6'` shade syntax, or any CSS color.
- `baseColor`: string — Base surface color override.
- `handleColor`: string — Handle color override.
- `showGuides`: boolean = true — Draw the static centre guides. Default `true`.
- `showCrosshair`: boolean = false — Draw accent rules that track the handle on each axis — the XY-pad readout. Default `false`.
- `valueLabel`: boolean | ((value: JoystickValue) => string) = false — Render the current value under the pad. Pass a function to format it.
- `label`: React.ReactNode — Field label rendered above the pad.
- `disabled`: boolean = false — Ignore all input and dim the control.
- `readOnly`: boolean = false — Ignore all input while keeping full contrast.
- `transitionDuration`: number — Spring-back / keyboard transition duration in ms. Default `220`.
- `baseStyle`: StyleProp<ViewStyle> — Style for the pad surface.
- `handleStyle`: StyleProp<ViewStyle> — Style for the handle.
- `valueLabelStyle`: StyleProp<TextStyle> — Style for the value label text.
- `accessibilityLabel`: string — Accessible name when there is no visible `label`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface JoystickValue {
  x: number;
  y: number;
}
```

## Examples

### Basics

A stick that springs back to centre on release. Drag anywhere on the pad — the gesture keeps tracking even when the finger leaves it.

```tsx
import { useState } from 'react';
import { Joystick } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState({ x: 0, y: 0 });

  return (
    <Joystick accessibilityLabel="Joystick"
      value={value}
      onChange={setValue}
      showCrosshair
      valueLabel
    />
  );
}
```

### Variants

Compare the joystick presets, including the unstyled base for custom skins.

```tsx
import { Column, Flex, Joystick, Text } from '@plocks/ui';

const variants = ['default', 'filled', 'outline', 'minimal', 'unstyled'] as const;

export function Demo() {
  return (
    <Flex direction="row" gap="lg" wrap="wrap">
      {variants.map(variant => (
        <Column key={variant} gap="xs" align="center">
          <Text size="sm">{variant}</Text>
          <Joystick variant={variant} accessibilityLabel={`${variant} joystick`} />
        </Column>
      ))}
    </Flex>
  );
}
```

### XY pad

`shape="square"` clamps each axis independently so the corners are reachable, and the handle holds its position on release — the shape a filter or effect pad wants.

```tsx
import { useState } from 'react';
import { Flex, Joystick, Text } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState({ x: -0.4, y: 0.6 });

  // Map the pad onto a pair of parameters the way an effect unit would.
  const cutoff = Math.round(((value.x + 1) / 2) * 18000 + 200);
  const resonance = ((value.y + 1) / 2).toFixed(2);

  return (
    <Flex direction="column" gap="md">
      <Joystick
        shape="square"
        size="lg"
        value={value}
        onChange={setValue}
        showCrosshair
        label="Filter"
      />
      <Text size="sm" c="muted">Cutoff {cutoff} Hz · Resonance {resonance}</Text>
    </Flex>
  );
}
```

### Dead zone and steps

`deadZone` ignores small deflections around centre and rescales the rest, so full travel still reports 1. `step` snaps each axis onto a grid.

```tsx
import { useState } from 'react';
import { Flex, Joystick } from '@plocks/ui';

export function Demo() {
  const [free, setFree] = useState({ x: 0, y: 0 });
  const [stepped, setStepped] = useState({ x: 0, y: 0 });

  return (
    <Flex gap="xl" wrap="wrap">
      <Joystick
        label="Dead zone 0.25"
        deadZone={0.25}
        value={free}
        onChange={setFree}
        valueLabel
      />
      <Joystick
        label="Step 0.25"
        shape="square"
        step={0.25}
        returnToCenter={false}
        value={stepped}
        onChange={setStepped}
        showCrosshair
        valueLabel
      />
    </Flex>
  );
}
```

### Axis lock

`lockAxis` restricts travel to one direction. A single-axis pad also leaves the perpendicular direction to the page, so vertical scrolling still works over a horizontal control.

```tsx
import { useState } from 'react';
import { Flex, Joystick, Text } from '@plocks/ui';

export function Demo() {
  const [pan, setPan] = useState({ x: 0, y: 0 });

  const position = pan.x === 0
    ? 'Center'
    : `${pan.x < 0 ? 'L' : 'R'} ${Math.round(Math.abs(pan.x) * 100)}`;

  return (
    <Flex direction="column" gap="md" align="flex-start">
      <Joystick
        label="Pan"
        lockAxis="x"
        size="sm"
        value={pan}
        onChange={setPan}
      />
      <Text size="sm" c="muted">{position}</Text>
    </Flex>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/KeyboardAvoidingArea.md -->

# KeyboardAvoidingArea

KeyboardAvoidingArea moves content clear of the mobile keyboard.

## Metadata

- Import: `import { KeyboardAvoidingArea } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/KeyboardAvoidingArea
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/KeyboardAvoidingArea

## Props

- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `translateY`: number — Small visual offset without affecting surrounding layout.
- `rotate`: string — Rotation around the block center, such as `"45deg"`.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `start`: number | string — Start inset (logical: left in LTR, right in RTL)
- `end`: number | string — End inset (logical: right in LTR, left in RTL)
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Plus the `Block` props (`children` `className` `onPress` `onLongPress` `onPressIn` `onPressOut` `onMouseEnter` `onMouseLeave` `disabled`): https://plocks.dev/llms/components/Block.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

KeyboardAvoidingArea moves content clear of the mobile keyboard.

```tsx
import { Block, Input, KeyboardAvoidingArea } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth h={220}>
      <KeyboardAvoidingArea flex={1} p="md">
        <Input label="Message" placeholder="Type a message" />
      </KeyboardAvoidingArea>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/KeyboardAwareLayout.md -->

# KeyboardAwareLayout

KeyboardAwareLayout adjusts screen content when the on-screen keyboard appears.

## Metadata

- Import: `import { KeyboardAwareLayout } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/KeyboardAwareLayout
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/KeyboardAwareLayout

## Props

- `children` (required): React.ReactNode
- `behavior`: KeyboardAvoidingViewProps['behavior'] — Optional behavior override for KeyboardAvoidingView
- `keyboardVerticalOffset`: number — Additional offset passed to KeyboardAvoidingView (defaults to 0)
- `enabled`: boolean — Enables or disables KeyboardAvoidingView adjustments
- `scrollable`: boolean — When true (default) content is wrapped in a ScrollView
- `extraScrollHeight`: number — Extra padding added in addition to keyboard height
- `contentContainerStyle`: StyleProp<ViewStyle> — Style applied to the ScrollView/inner content container
- `keyboardShouldPersistTaps`: 'always' | 'never' | 'handled' — Controls ScrollView keyboard tap handling
- `scrollRef`: React.Ref<ScrollView> — Forward ref to the internal ScrollView when scrollable is true
- `scrollViewProps`: ScrollViewProps — Additional props that will be spread onto the internal ScrollView
- `scrollEnabled`: boolean — Whether scrolling is enabled
- `bounces`: boolean — Whether the scroll view bounces past the edge of content (iOS)
- `onScroll`: ScrollViewProps['onScroll'] — Scroll event callback
- `scrollEventThrottle`: number — Throttle interval for scroll events in ms
- `onMomentumScrollBegin`: ScrollViewProps['onMomentumScrollBegin'] — Callback when momentum scroll begins
- `onMomentumScrollEnd`: ScrollViewProps['onMomentumScrollEnd'] — Callback when momentum scroll ends
- `showsVerticalScrollIndicator`: boolean — Whether to show the vertical scroll indicator
- `showsHorizontalScrollIndicator`: boolean — Whether to show the horizontal scroll indicator
- `decelerationRate`: ScrollViewProps['decelerationRate'] — Deceleration rate ('normal' | 'fast' | number)
- `overScrollMode`: ScrollViewProps['overScrollMode'] — Over-scroll mode for Android
- `refreshControl`: ScrollViewProps['refreshControl'] — Pull-to-refresh control
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Keep form fields scrollable when the on-screen keyboard opens.

```tsx
import { Block, Input, KeyboardAwareLayout } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth h={220}>
      <KeyboardAwareLayout>
        <Block p="md" gap="md">
          <Input label="Name" placeholder="Your name" />
          <Input label="Email" placeholder="you@example.com" />
        </Block>
      </KeyboardAwareLayout>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/KeyCap.md -->

# KeyCap

A visual component for displaying keyboard keys, shortcuts, and key combinations with proper styling.

## Metadata

- Import: `import { KeyCap } from '@plocks/ui';`
- Tags: keycap, keyboard, shortcut, key, hotkey
- Docs: https://plocks.dev/components/KeyCap
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/KeyCap

## Props

- `children` (required): ReactNode — The key or text to display
- `size`: ComponentSizeValue = 'md' — Size token (a key cap renders below a control of the same size), or the height in px
- `variant`: 'default' | 'minimal' | 'outline' | 'filled' = 'default' — Visual variant of the key cap
- `color`: ColorProp = 'gray' — Color for the `minimal`, `outline` and `filled` variants: a palette token, `'primary.6'` shade syntax, or any CSS color. `default` stays neutral.
- `animateOnPress`: boolean = true — Whether the key should animate when the actual key is pressed Only works on web platforms
- `transitionDuration`: number = 250 — Length of the press-down/up animation in ms; both legs scale against a 250ms baseline. `0` leaves the cap at rest. Always 0 under reduced motion.
- `keyCode`: string — The actual key code to listen for (e.g., 'Enter', 'Space', 'Escape') If provided, the component will animate when this key is pressed (web)
- `modifiers`: KeyCapModifier[] — Modifier keys that must be pressed along with the main key
- `pressed`: boolean = false — Whether the key cap should appear pressed
- `onKeyPress`: () => void — Callback when the key combination is pressed (web)
- `ff`: string — Custom font family (overrides the theme's monospace stack)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), `radius`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useKeyCapStyles(props: KeyCapStyleProps)` — Returns the `{ container, text }` styles of a key cap for the current theme, given its `metrics`, `variant`, `color` and `pressed` state — the hook form of `getKeyCapStyles`, for drawing a custom key that matches `KeyCap`.

## Types

```ts
export type KeyCapModifier = 'ctrl' | 'cmd' | 'alt' | 'shift' | 'meta';
```

## Examples

### Basics

Basic keyboard key display for showing shortcuts and key combinations.

```tsx
import { Block, KeyCap, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Block align="flex-start">
      <Row gap="sm" wrap="wrap">
        <KeyCap>A</KeyCap>
        <KeyCap>Enter</KeyCap>
        <KeyCap>Space</KeyCap>
        <KeyCap>⌘</KeyCap>
        <KeyCap>Ctrl</KeyCap>
        <KeyCap>⇧</KeyCap>
      </Row>
    </Block>
  );
}
```

### Sizes

Different sizes for KeyCap components from extra small to extra large.

```tsx
import { Block, KeyCap, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Block align="flex-start">
      <Row gap="sm" align="center" wrap="wrap">
        <KeyCap size="xs">XS</KeyCap>
        <KeyCap size="sm">SM</KeyCap>
        <KeyCap size="md">MD</KeyCap>
        <KeyCap size="lg">LG</KeyCap>
        <KeyCap size="xl">XL</KeyCap>
      </Row>
    </Block>
  );
}
```

### Variants

Different visual variants for KeyCap components including default, filled, minimal, and outline styles.

```tsx
import { Block, KeyCap, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Block align="flex-start">
      <Row gap="sm" wrap="wrap">
        <KeyCap variant="default">Default</KeyCap>
        <KeyCap variant="filled">Filled</KeyCap>
        <KeyCap variant="minimal">Minimal</KeyCap>
        <KeyCap variant="outline">Outline</KeyCap>
      </Row>
    </Block>
  );
}
```

### Modifiers

KeyCap components with modifier keys for displaying keyboard shortcuts and key combinations.

```tsx
import { Block, KeyCap, Row, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Row gap="xs" align="center">
        <Text>Copy</Text>
        <KeyCap keyCode="C" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <Text>+</Text>
        <KeyCap keyCode="C" modifiers={['cmd']} size="sm">C</KeyCap>
      </Row>
      <Row gap="xs" align="center">
        <Text>Save</Text>
        <KeyCap keyCode="S" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <Text>+</Text>
        <KeyCap keyCode="S" modifiers={['cmd']} size="sm">S</KeyCap>
      </Row>
      <Row gap="xs" align="center">
        <Text>Undo</Text>
        <KeyCap keyCode="Z" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <Text>+</Text>
        <KeyCap keyCode="Z" modifiers={['cmd']} size="sm">Z</KeyCap>
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Knob.md -->

# Knob

Knob provides a rotary control for selecting a value within a range.

## Metadata

- Import: `import { Knob } from '@plocks/ui';`
- Tags: knob, dial, rotary, gesture, input
- Docs: https://plocks.dev/components/Knob
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Knob

## Props

- `behavior`: 'level' | 'stepped' | 'endless' | 'dual' | 'status' = 'level' — What kind of control this is: how it behaves and what it reads out. @default 'level'
- `variant`: 'default' | 'minimal' | 'digital' | 'retro' | 'studio' = 'default' — Visual style preset. Merged under `appearance`, so single properties stay overridable.
- `mode`: 'bounded' | 'endless' — Interaction mode for bounded or endless rotary behavior
- `value`: number — Controlled value
- `defaultValue`: number — Uncontrolled initial value
- `min`: number — Minimum selectable value
- `max`: number — Maximum selectable value
- `step`: number — Step increment applied when interacting
- `onChange`: (value: number) => void — Called on every value change
- `onChangeEnd`: (value: number) => void — Called after interaction completes
- `onScrubStart`: () => void — Fired when the user begins dragging
- `onScrubEnd`: () => void — Fired when the user ends dragging
- `size`: ComponentSizeValue — Size token (`xs`–`3xl`) or an explicit diameter in pixels
- `thumbSize`: number — Diameter of the thumb indicator, in pixels. Defaults to a ratio of the resolved size.
- `disabled`: boolean — Disable all user interaction
- `readOnly`: boolean — Prevent interaction but keep visual state
- `formatLabel`: (value: number) => ReactNode — Custom formatter for the value label
- `withLabel`: boolean — Render the value label inside the knob
- `valueLabel`: KnobValueLabelConfig | false — Structured configuration for the value label block
- `marks`: KnobMark[] — Optional marks rendered around the control
- `restrictToMarks`: boolean — Restrict interaction to the supplied marks
- `label`: ReactNode — Optional visual label rendered outside the knob
- `description`: ReactNode — Optional helper text rendered with the label
- `labelPosition`: 'left' | 'right' | 'top' | 'bottom' — Placement for the external label
- `style`: StyleProp<ViewStyle> — Style overrides for the outer container
- `trackStyle`: StyleProp<ViewStyle> — Style overrides for the circular track
- `thumbStyle`: StyleProp<ViewStyle> — Style overrides for the thumb
- `markLabelStyle`: StyleProp<TextStyle> — Style overrides for mark labels
- `testID`: string — Accessibility identifier
- `accessibilityLabel`: string — Screen reader label
- `appearance`: KnobAppearance — Unified surface styling and interaction overrides
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### Knob.Progress

- `value` (required): number — Completion, 0–100 (clamped).
- `size`: SizeValue = 'md' — Bar thickness: a control-size token (`getControlSize(theme, size).height`) or pixels. @default 'md'
- `color`: ThemeColor = 'primary' — Fill color: palette token, `'primary.6'` shade syntax, or any CSS color. @default 'primary'
- `radius`: RadiusValue = 'md' — Corner radius: theme radius token, px, `'none'` or `'full'`. @default 'md'
- `striped`: boolean
- `animate`: boolean — Animates the stripes. Requires `striped`. Off while reduced motion is on.
- `transitionDuration`: number = 0 — Animate fill changes over this many ms. `0` (and reduced motion) jumps straight to the value. @default 0
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Axis the bar fills along. Vertical bars fill bottom-up. @default 'horizontal'
- `length`: number | `${number}%` — Length along the main axis. Vertical bars default to 160.
- `trackColor`: string — Track (unfilled) color. Defaults to the theme's `backgrounds.border`.
- `aria-label`: string — Accessible name. Defaults to the `label` (web: by reference).
- `aria-valuetext`: string — Spoken value text, e.g. `"3 of 8 files"`. Defaults to the percentage.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `label`: React.ReactNode — Label rendered outside the track. Strings are styled; nodes render as-is.
- `description`: React.ReactNode — Helper text ("sublabel") rendered directly beneath the label. Hidden while `error` is set.
- `error`: React.ReactNode — Error message rendered below the bar (announced politely). Replaces `description` when present.
- `required`: boolean = false — Marks the field as required, rendering an asterisk beside the label. @default false
- `withAsterisk`: boolean = true — Whether the required marker is drawn. @default true
- `labelPosition`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Placement of the label block relative to the bar. @default 'top'
- `labelGap`: SizeValue = 'xs' — Gap between the label block and the bar — a theme spacing token or pixel value. @default 'xs'
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>`
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the description `<Text>`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Knob.Ring

- `value` (required): number — Current value represented by the ring
- `min`: number — Lower bound for normalization. Defaults to 0.
- `max`: number — Upper bound for normalization. Defaults to 100.
- `size`: number — Diameter of the ring in pixels. Defaults to 100.
- `thickness`: number — Stroke thickness in pixels. Defaults to 12.
- `caption`: React.ReactNode — Optional caption rendered beneath the ring
- `label`: React.ReactNode — Main label rendered in the ring center
- `subLabel`: React.ReactNode — Secondary label rendered below the main label
- `showValue`: boolean — Displays the computed percentage when no label/subLabel is provided. Defaults to true.
- `valueFormatter`: (value: number, percent: number) => React.ReactNode — Formats the displayed value or percentage
- `trackColor`: string — Track color behind the progress stroke. Defaults to the theme's `backgrounds.border`.
- `progressColor`: string | ((value: number, percent: number) => string) — Progress stroke color or resolver
- `colorStops`: RingColorStop[] — Optional color stops evaluated against the computed percent
- `neutral`: boolean — Forces the ring into a neutral state, disabling the progress stroke
- `roundedCaps`: boolean — Controls whether the progress stroke has rounded caps. Defaults to true.
- `ringStyle`: StyleProp<ViewStyle> — Style applied to the ring wrapper
- `contentStyle`: StyleProp<ViewStyle> — Style applied to the center content container
- `labelStyle`: StyleProp<TextStyle> — Style overrides for the main label
- `subLabelStyle`: StyleProp<TextStyle> — Style overrides for the secondary label
- `captionStyle`: StyleProp<TextStyle> — Style overrides for the caption
- `labelColor`: string — Color override for the main label
- `subLabelColor`: string — Color override for the secondary label
- `captionColor`: string — Color override for the caption
- `children`: React.ReactNode | ((context: RingRenderContext) => React.ReactNode) — Custom center content. Receives value info when passed as a function
- `accessibilityLabel`: string — Accessible name of the ring (a `progressbar`). Defaults to the text of `caption`, else of `label`. The value is exposed as aria-value* on its own.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Knob.Root

- `children`: ReactNode — Modular children composed of Knob.* sub-components
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Knob` props (`behavior` `variant` `mode` `value` `defaultValue` `min` `max` `step` `onChange` `onChangeEnd` `onScrubStart` `onScrubEnd` `size` `thumbSize` `disabled` `readOnly` `formatLabel` `withLabel` `valueLabel` `marks` `restrictToMarks` `label` `description` `labelPosition` `style` `trackStyle` `thumbStyle` `markLabelStyle` `testID` `accessibilityLabel` `appearance`): https://plocks.dev/llms/components/Knob.md

Also accepts the shared props — spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

`Knob.Fill`, `Knob.Pointer`, `Knob.RingSegment`, `Knob.Thumb`, `Knob.TickLayer`, `Knob.ValueLabel` have no props interface of their own.

## Types

```ts
export interface KnobValueLabelConfig {
  /** Placement relative to the knob surface */
  position?: KnobValueLabelPosition;
  /** Primary formatter for the displayed value */
  formatter?: (value: number) => ReactNode;
  /** Optional prefix rendered before the value */
  prefix?: ReactNode;
  /** Optional suffix rendered after the value */
  suffix?: ReactNode;
  /** Style overrides for the wrapper */
  containerStyle?: StyleProp<ViewStyle>;
  /** Style overrides for the primary text */
  textStyle?: StyleProp<TextStyle>;
  /** Secondary readout rendered at an independent slot */
  secondary?: {
    formatter?: (value: number) => ReactNode;
    position?: KnobValueLabelPosition;
    prefix?: ReactNode;
    suffix?: ReactNode;
    containerStyle?: StyleProp<ViewStyle>;
    textStyle?: StyleProp<TextStyle>;
  };
}

export interface KnobMark {
  /** Absolute value within the knob range to display */
  value: number;
  /** Optional label rendered near the tick */
  label?: ReactNode;
  /** Optional accent color applied when the mark becomes active */
  accentColor?: string;
  /** Optional icon surfaced by status-oriented variants */
  icon?: ReactNode;
}

export interface KnobAppearance {
  /**
   * Take the knob's accent — thumb, arm, and progress arc — from the `accentColor` of the
   * mark nearest the current value, so the whole control matches the detent it is on.
   * `behavior="status"` already does this; this opts any other behavior in. Marks without
   * an `accentColor` leave the theme accent in place. @default false
   */
  accentFromMarks?: boolean;
  ring?: KnobRingStyle;
  fill?: KnobFillStyle;
  thumb?: KnobThumbStyle | false;
  ticks?: KnobTickLayer | KnobTickLayer[] | false;
  pointer?: KnobPointerStyle | false;
  arc?: KnobArcConfig;
  progress?: KnobProgressConfig | false;
  panning?: KnobPanningConfig;
  interaction?: KnobInteractionConfig;
}

export interface KnobRingStyle {
  thickness?: number;
  color?: string;
  trailColor?: string;
  backgroundColor?: string;
  cap?: 'butt' | 'round';
  radiusOffset?: number;
  shadow?: KnobRingShadow;
  /** Colored bands drawn over the ring, laid end to end from `min`. */
  segments?: KnobRingSegment[];
  /**
   * How `segments` relate to the current value.
   *
   * - `'track'` (default) paints every band across the whole ring as a static backdrop —
   *   zones you read the value against, with the progress arc drawn over the top.
   * - `'progress'` makes the bands the progress arc itself: they are clipped at the current
   *   value and nothing is drawn beyond it, so the dial fills through each color in turn.
   *   The plain progress stroke is suppressed, since the bands replace it.
   */
  segmentMode?: 'track' | 'progress';
}

export interface KnobFillStyle {
  color?: string;
  borderWidth?: number;
  borderColor?: string;
  radiusOffset?: number;
}

export interface KnobThumbStyle {
  size?: number;
  /**
   * Scale applied to the thumb while the knob is being scrubbed, as press feedback.
   * `1` disables it; values below 1 shrink instead. @default 1.25
   */
  activeScale?: number;
  shape?: KnobThumbShape;
  color?: string;
  strokeWidth?: number;
  strokeColor?: string;
  offset?: number;
  glow?: KnobThumbGlow;
  style?: StyleProp<ViewStyle>;
  renderThumb?: (context: KnobThumbRenderContext) => ReactNode;
}

export interface KnobTickLayer {
  source?: KnobTickSource;
  values?: number[];
  /**
   * With `source: 'count'`, how many evenly spaced ticks to lay around the arc — an LED
   * ring of a fixed resolution, independent of `step` and `marks`. Capped at 512.
   */
  count?: number;
  shape?: KnobTickShape;
  length?: number;
  width?: number;
  radiusOffset?: number;
  position?: 'inner' | 'center' | 'outer';
  /**
   * Color of an active tick. A resolver colors each tick individually; for
   * `source: 'marks'`, a mark's own `accentColor` is used ahead of a flat string, so
   * per-detent colors need no resolver at all.
   */
  color?: KnobTickColor;
  /** Color of a tick the layer's `activeMode` leaves unlit. Also accepts a resolver. */
  inactiveColor?: KnobTickColor;
  /**
   * What counts as an active tick in this layer.
   *
   * - `'fill'` (default) lights every tick from `min` up to the current value, the way a
   *   meter fills.
   * - `'nearest'` lights only the single tick the pointer is aimed at, the way a selector
   *   or detent indicator reads. Matched by angle, so it works on endless knobs too.
   */
  activeMode?: 'fill' | 'nearest';
  iconName?: string;
  label?: KnobTickLabelConfig;
  renderTick?: (context: {
    value: number;
    angle: number;
    index: number;
    isActive: boolean;
    center: { x: number; y: number };
    radius: number;
  }) => ReactNode;
}

export interface KnobPointerStyle {
  visible?: boolean;
  length?: number;
  width?: number;
  offset?: number;
  color?: string;
  cap?: 'round' | 'butt';
  counterweight?: { size?: number; color?: string };
}
```

## Examples

### Basics

Controlled knob with percentage formatting and a mirrored readout below the dial.

```tsx
import { useState } from 'react';
import { Knob } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(90);

  return (
    <Knob accessibilityLabel="Level"
      value={value}
      onChange={setValue}
      valueLabel={{
        formatter: (current) => Math.round(current),
        suffix: '°',
      }}
    />
  );
}
```

### Events

Demonstrates live value, committed value, and scrubbing lifecycle callbacks.

```tsx
import { useState } from 'react';
import { Block, DataList, Knob } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(32);
  const [isScrubbing, setIsScrubbing] = useState(false);
  const [committed, setCommitted] = useState(value);

  return (
    <Block direction="row" align="center" justify="space-evenly">
      <Knob accessibilityLabel="Value"
        value={value}
        onChange={setValue}
        onChangeEnd={setCommitted}
        onScrubStart={() => setIsScrubbing(true)}
        onScrubEnd={() => setIsScrubbing(false)}
      />
      <DataList
        data={[
          { label: 'Current', value: Math.round(value) },
          { label: 'Last commit', value: Math.round(committed) },
          { label: 'State', value: isScrubbing ? 'Scrubbing' : 'Idle' },
        ]}
      />
    </Block>
  );
}
```

### Visual Variants

`variant` picks the dial's look, independent of `behavior`. Each preset sets stroke weights, caps, body fill, and which indicator carries the value, taking its colors from the theme so the same knob reads correctly in light and dark. Presets are merged *under* `appearance`, so any single property stays overridable.

```tsx
import { useState } from 'react';

import { Block, Knob, Row, Text } from '@plocks/ui';
import type { KnobVariant } from '@plocks/ui';

const VARIANTS: { variant: KnobVariant; blurb: string }[] = [
  { variant: 'default', blurb: 'Stock dial' },
  { variant: 'minimal', blurb: 'Hairline, dense UIs' },
  { variant: 'digital', blurb: 'Hard edges, lit marker' },
  { variant: 'retro', blurb: 'Solid body, indicator arm' },
  { variant: 'studio', blurb: 'Plugin rack' },
];

export function Demo() {
  const [value, setValue] = useState(62);

  return (
    <Block fullWidth direction="row" justify="space-between">
        {VARIANTS.map(({ variant, blurb }) => (
          <Block key={variant} align="center" gap="xs">
            <Knob accessibilityLabel={`${variant} knob`}
              value={value}
              onChange={setValue}
              variant={variant}
            />
            <Text size="sm" fw="600">{variant}</Text>
          </Block>
        ))}
    </Block>
  );
}
```

### Endless

Endless mode resets the dial each turn while tracking the cumulative rotation value.

```tsx
import { useMemo, useState } from 'react';
import { Block, Knob } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(0);
  const normalizedAngle = useMemo(() => ((value % 360) + 360) % 360, [value]);
  const rotations = useMemo(() => value / 360, [value]);

  return (
    <Block fullWidth>
      <Knob accessibilityLabel="Jog wheel"
        value={value}
        onChange={setValue}
        behavior="endless"
        valueLabel={{
          formatter: () => `${Math.round(normalizedAngle)}°`,
          secondary: {
            formatter: () => `${rotations.toFixed(2)} turns`,
          },
        }}
      />
    </Block>
  );
}
```

### Dual Readout

Demonstrates the `dual` behavior with a center frequency label and a derived percentage below the knob.

```tsx
import { useMemo, useState } from 'react';

import { Block, Knob } from '@plocks/ui';

export function Demo() {
  const [cutoff, setCutoff] = useState(3200);
  const percent = useMemo(() => Math.round(((cutoff - 200) / (8000 - 200)) * 100), [cutoff]);

  return (
    <Block fullWidth>
      <Knob accessibilityLabel="Cutoff"
        value={cutoff}
        onChange={setCutoff}
        min={200}
        max={8000}
        step={50}
        behavior="dual"
        size={180}
        valueLabel={{
          position: 'center',
          formatter: (val) => `${Math.round(val)} Hz`,
          secondary: {
            position: 'bottom',
            formatter: () => `${percent}% span`,
          },
        }}
        marks={[
          { value: 400, label: 'Warm' },
          { value: 1200, label: 'Neutral' },
          { value: 6400, label: 'Bright' },
        ]}
      />
    </Block>
  );
}
```

### Status Selector

Highlights the `status` behavior with icon-enhanced marks, accent colors, and the active scene named directly beneath the icon in the center slot.

```tsx
import { useMemo, useState } from 'react';
import { Block, Icon, Knob } from '@plocks/ui';

import { STATUS_SCENES } from './data';

export function Demo() {
  const [value, setValue] = useState(0);

  const statusMarks = useMemo(
    () => STATUS_SCENES.map(scene => ({
      ...scene,
      icon: <Icon name={scene.iconName} size="3xl" color={scene.accentColor} />,
    })),
    []
  );

  const activeStatus = useMemo(
    () => statusMarks.reduce((closest, mark) => (
      Math.abs(mark.value - value) < Math.abs(closest.value - value) ? mark : closest
    ), statusMarks[0]),
    [statusMarks, value]
  );

  return (
    <Block>
      <Knob accessibilityLabel="Status"
        value={value}
        onChange={setValue}
        min={0}
        max={360}
        step={90}
        my="3xl"
        marks={statusMarks}
        restrictToMarks
        behavior="status"
        size={200}
        valueLabel={{
          position: 'center',
          formatter: () => activeStatus.label,
        }}
      />
    </Block>
  );
}
```

`data.ts`

```ts
/**
 * The scenes the knob selects between, one per detent around the dial. Icons are named
 * rather than built here so this stays plain data; the demo turns each name into an
 * `<Icon>` tinted with the same accent.
 */
export type StatusScene = {
  /** Position on the 0–360 dial. */
  value: number;
  label: string;
  accentColor: string;
  iconName: string;
};

export const STATUS_SCENES: StatusScene[] = [
  { value: 0, label: 'Sleep', accentColor: '#64748b', iconName: 'moon' },
  { value: 90, label: 'Focus', accentColor: '#0ea5e9', iconName: 'target' },
  { value: 180, label: 'Charge', accentColor: '#22c55e', iconName: 'bolt' },
  { value: 270, label: 'Party', accentColor: '#f97316', iconName: 'sparkles' },
];
```

### Segmented Progress

The same bands with `ring.segmentMode: 'progress'`, which makes them the progress arc itself: they stop at the current value and nothing is drawn beyond it, so the fill runs through each color in turn.

```tsx
import { useState } from 'react';
import { Block, Knob } from '@plocks/ui';

const ZONES = [
  { value: 60, color: '#22c55e' },
  { value: 25, color: '#f59e0b' },
  { value: 15, color: '#ef4444' },
];

export function Demo() {
  const [load, setLoad] = useState(72);

  return (
    <Block align="center">
      <Knob accessibilityLabel="Load"
        value={load}
        onChange={setLoad}
        variant="minimal"
        max={100}
        appearance={{
          arc: { startAngle: -135, sweepAngle: 270 },
          ring: {  segments: ZONES, segmentMode: 'progress' },
          fill: { radiusOffset: -20 },
        }}
        valueLabel={{ formatter: (val) => `${Math.round(val)}%` }}
      />
    </Block>
  );
}
```

### Tick Selector

A twelve-position rotary switch using `activeMode: 'nearest'`, which lights only the tick the pointer is aimed at. The default `'fill'` instead lights every tick up to the value, the way a meter fills.

```tsx
import { useState } from 'react';
import { Block, Knob } from '@plocks/ui';
import { POSITION_COLORS } from './data';

// Twelve detents on a full circle. `max` is 12 rather than 11 so position 11 sits one step
// short of the top instead of overlapping position 0. Each detent carries its own
const POSITIONS = POSITION_COLORS.map((accentColor, index) => ({ value: index, accentColor }));

export function Demo() {
  const [position, setPosition] = useState(3);

  return (
    <Block >
      <Knob accessibilityLabel="Position"
        value={position}
        onChange={setPosition}
        min={0}
        max={12}
        marks={POSITIONS}
        restrictToMarks
        appearance={{
          accentFromMarks: true,
          ticks: [
            {
              source: 'marks',
              shape: 'line',
              // Only the detent the arm is aimed at lights up. The default 'fill' would
              // instead light every tick from 0 up to the current position.
              activeMode: 'nearest',
              length: 14,
              width: 20,
              position: 'outer',
              inactiveColor: ({ mark }) => (mark?.accentColor ? `${mark.accentColor}44` : '#475569'),
            },
          ],
        }}
        valueLabel={{ formatter: (val) => `${Math.round(val) + 1}` }}
      />
    </Block>
  );
}
```

`data.ts`

```ts
/** One hue per detent, walking the spectrum so neighbouring positions stay tellable apart. */
export const POSITION_COLORS = [
  '#f87171',
  '#fb923c',
  '#fbbf24',
  '#facc15',
  '#a3e635',
  '#4ade80',
  '#34d399',
  '#22d3ee',
  '#38bdf8',
  '#818cf8',
  '#c084fc',
  '#f472b6',
];
```

### Compound Panning

Stereo-style panning knob composed with `Knob.Root`, split progress, and custom tick labels to highlight the compound sub-component API.

```tsx
import { useMemo, useState } from 'react';

import { Block, Knob, Text } from '@plocks/ui';

// The split arc reads the same on both sides of center: direction is carried by which way
// the arc grows and by the L/R label, not by a color change.
const PAN_COLOR = '#4ade80';

export function Demo() {
  const [pan, setPan] = useState(-18);

  const readout = useMemo(() => {
    if (pan === 0) return 'Center';
    return pan > 0 ? `Right ${Math.abs(pan)}` : `Left ${Math.abs(pan)}`;
  }, [pan]);

  return (
    <Block align="center">
      <Knob.Root accessibilityLabel="Pan"
        min={-100}
        max={100}
        value={pan}
        onChange={setPan}
        step={1}
        size={220}
        appearance={{
          arc: { startAngle: -135, sweepAngle: 270, clampInput: true },
          panning: {
            pivotValue: 0,
            positiveColor: PAN_COLOR,
            negativeColor: PAN_COLOR,
          },
        }}
      >
        <Knob.Fill
          radiusOffset={-28}
          color="#0f172a"
          borderWidth={2}
          borderColor="rgba(148, 163, 184, 0.4)"
        />
        <Knob.Ring color="#0f172a" trailColor="#1f2937" />
        <Knob.Progress mode="split" thickness={14} roundedCaps />
        <Knob.Thumb  color="#f8fafc" strokeWidth={3} strokeColor="#0f172a" />
        <Knob.ValueLabel
          position="center"
          formatter={(value) => `${value > 0 ? 'R' : value < 0 ? 'L' : ''}${Math.abs(Math.round(value))}`}
          textStyle={{ fontSize: 30, fontWeight: '700', color: '#f8fafc' }}
        />
      </Knob.Root>
      <Text size="sm" c="secondary">
        Stereo balance · {readout}
      </Text>
    </Block>
  );
}
```

### Pointer Clock

Read-only analog clock face built with the compound `Knob.Root` API: a bezel ring, 60 minute marks with bolder hour marks, hour numerals, and `Knob.Pointer` as the hour hand driven by the value (minutes past 12). The minute and second hands are plain rotated views composed over the same center, synced to the system clock each second.

```tsx
import { useEffect, useState } from 'react';
import { View } from 'react-native';

import { Block, Knob, Text, useTheme } from '@plocks/ui';

const SIZE = 240;
const CENTER = SIZE / 2;
const MINUTES_PER_TURN = 12 * 60;

const HOUR_VALUES = Array.from({ length: 12 }, (_, index) => index * 60);
const HOUR_LABELS = ['12', '1', '2', '3', '4', '5', '6', '7', '8', '9', '10', '11'];
// 60 minute marks around the dial; hour positions are drawn by the layer above.
const MINUTE_VALUES = Array.from({ length: 60 }, (_, index) => index * 12).filter(
  (value) => value % 60 !== 0
);

const formatTime = (minutes: number) => {
  const hour = Math.floor(minutes / 60);
  return `${hour === 0 ? 12 : hour}:${(minutes % 60).toString().padStart(2, '0')}`;
};

/** Hand pivoting on the dial center: the wrapper is twice the hand length, so it rotates around it. */
const Hand = ({
  angle,
  length,
  width,
  color,
  tail = 0,
}: {
  angle: number;
  length: number;
  width: number;
  color: string;
  tail?: number;
}) => (
  <View
    pointerEvents="none"
    style={{
      position: 'absolute',
      left: CENTER - width / 2,
      top: CENTER - length,
      width,
      height: length * 2,
      transform: [{ rotate: `${angle}deg` }],
    }}
  >
    <View
      style={{
        width,
        height: length + tail,
        borderRadius: width / 2,
        backgroundColor: color,
      }}
    />
  </View>
);

export function Demo() {
  const theme = useTheme();
  const face = theme.backgrounds.surface;
  const ink = theme.text.primary;
  const accent = theme.colors.primary[6];

  // Start on a fixed time so server-rendered and client markup match, then sync on mount.
  const [time, setTime] = useState({ minutes: 10 * 60 + 10, seconds: 0 });

  useEffect(() => {
    const tick = () => {
      const now = new Date();
      setTime({
        minutes: (now.getHours() % 12) * 60 + now.getMinutes(),
        seconds: now.getSeconds(),
      });
    };
    tick();
    const id = setInterval(tick, 1000);
    return () => clearInterval(id);
  }, []);

  return (
    <Block align="center" gap="sm">
      <View style={{ width: SIZE, height: SIZE }}>
        <Knob.Root
          min={0}
          max={MINUTES_PER_TURN}
          value={time.minutes}
          size={SIZE}
          readOnly
          withLabel={false}
          accessibilityLabel={`Clock showing ${formatTime(time.minutes)}`}
          appearance={{
            arc: { startAngle: 0, sweepAngle: 360, clampInput: true },
          }}
        >
          <Knob.Ring thickness={12} color={ink} trailColor={ink} backgroundColor={face} />
          {/* Chapter ring just inside the minute marks */}
          <Knob.Fill
            color={face}
            radiusOffset={-18}
            borderWidth={1}
            borderColor={theme.backgrounds.border}
          />
          <Knob.Progress visible={false} />
          <Knob.Thumb visible={false} />
          <Knob.TickLayer
            source="values"
            values={MINUTE_VALUES}
            shape="line"
            length={6}
            width={1.5}
            position="inner"
            color={theme.text.muted}
            inactiveColor={theme.text.muted}
          />
          <Knob.TickLayer
            source="values"
            values={HOUR_VALUES}
            shape="line"
            length={12}
            width={3}
            position="inner"
            color={ink}
            inactiveColor={ink}
            label={{
              show: true,
              formatter: (_, index) => HOUR_LABELS[index],
              position: 'inner',
              offset: -26,
              style: { color: ink, fontSize: 15, fontWeight: '600' },
            }}
          />
          {/* Hour hand — the knob value is minutes past 12, so it advances gradually. */}
          <Knob.Pointer visible length={58} width={6} color={ink} counterweight={{ size: 12, color: ink }} />
        </Knob.Root>

        <Hand angle={((time.minutes % 60) / 60) * 360} length={88} width={4} color={ink} />
        <Hand angle={(time.seconds / 60) * 360} length={94} width={1.5} color={accent} tail={18} />
        <View
          pointerEvents="none"
          style={{
            position: 'absolute',
            left: CENTER - 4,
            top: CENTER - 4,
            width: 8,
            height: 8,
            borderRadius: 4,
            backgroundColor: accent,
          }}
        />
      </View>

      <Text size="xl" fw="700">
        {formatTime(time.minutes)}
      </Text>
    </Block>
  );
}
```

### Semicircle Gauge

Semicircle gauge layout that uses `Knob.Root` with custom ring thickness, contiguous progress, and a pointer hand for instrumentation-style readouts.

```tsx
import { useMemo, useState } from 'react';

import { Block, Knob, Text } from '@plocks/ui';

const TEMPERATURE_STOPS = [0, 25, 50, 75, 100];

export function Demo() {
  const [level, setLevel] = useState(62);

  const status = useMemo(() => {
    if (level >= 85) return 'Critical';
    if (level >= 60) return 'Elevated';
    if (level >= 35) return 'Nominal';
    return 'Idle';
  }, [level]);

  return (
    <Block align="center">
      <Knob.Root accessibilityLabel="Level"
        min={0}
        max={100}
        value={level}
        onChange={setLevel}
        step={1}
        size={260}
        appearance={{
          arc: { startAngle: -120, sweepAngle: 240, clampInput: true },
          interaction: { spinStopAtLimits: true },
        }}
      >
        <Knob.Fill visible={false} />
        <Knob.Ring thickness={30} color="#0f172a" trailColor="#1f2937" radiusOffset={-4} />
        <Knob.RingSegment value={35} color="#1e3a8a" />
        <Knob.RingSegment value={25} color="#155e75" />
        <Knob.RingSegment value={25} color="#854d0e" />
        <Knob.RingSegment value={15} color="#7f1d1d" />
        <Knob.Progress
          mode="contiguous"
          thickness={14}
          color="#22d3ee"
          roundedCaps
        />
        <Knob.TickLayer
          source="values"
          values={TEMPERATURE_STOPS}
          shape="line"
          length={22}
          width={3}
          position="outer"
          radiusOffset={10}
          label={{
            show: true,
            formatter: (_, index) => `${TEMPERATURE_STOPS[index]}%`,
            offset: 24,
            style: { color: '#cbd5f5', fontSize: 12, fontWeight: '600' },
          }}
        />
        <Knob.Pointer length={90} width={4} color="#f8fafc" offset={-8} cap="round" />
        <Knob.Thumb visible={false} />
        <Knob.ValueLabel
          position="bottom"
          formatter={(value) => `${Math.round(value)}% capacity`}
          textStyle={{ fontSize: 18, fontWeight: '600', color: '#f8fafc' }}
          secondary={{
            formatter: () => status,
            position: 'bottom',
            textStyle: { fontSize: 14, color: '#94a3b8', marginTop: 4 },
          }}
        />
      </Knob.Root>
      <Text size="sm" c="secondary">
        Thermal headroom · {status}
      </Text>
    </Block>
  );
}
```

### Tick Layers

Stacks two tick layers on one dial: labelled lines driven by `marks`, over a finer dot scale from an explicit step list.

```tsx
import { useState } from 'react';

import { Block, Knob } from '@plocks/ui';

const LEVEL_MARKS = [
  { value: 0, label: 'Mute' },
  { value: 25, label: 'Low' },
  { value: 50, label: 'Mid' },
  { value: 75, label: 'High' },
  { value: 100, label: 'Max' },
];

export function Demo() {
  const [level, setLevel] = useState(48);

  return (
    <Block align="center">
      <Knob accessibilityLabel="Level"
        value={level}
        onChange={setLevel}
        min={0}
        max={100}
        step={1}
        marks={LEVEL_MARKS}
        size={180}
        appearance={{
          // A full circle would put the 0 and 100 marks on the same point, overprinting
          // their labels; the 270deg arc gives each end of the scale its own position.
          arc: { startAngle: -135, sweepAngle: 270 },
          ring: { thickness: 16 },
          fill: { radiusOffset: -24 },
          progress: { mode: 'contiguous', color: '#f97316' },
          ticks: [
            // Two layers over the same dial: labelled lines from `marks`, and a finer
            // dot scale from an explicit step list underneath them.
            {
              source: 'marks',
              shape: 'line',
              length: 16,
              width: 3,
              position: 'outer',
              label: { show: true, position: 'outer' },
            },
            {
              source: 'steps',
              values: [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100],
              shape: 'dot',
              radiusOffset: -6,
              color: '#475569',
              inactiveColor: 'rgba(71, 85, 105, 0.4)',
            },
          ],
        }}
        valueLabel={{ formatter: (val) => `${Math.round(val)}%` }}
      />
    </Block>
  );
}
```

### Interaction modes

Showcases spin, vertical-slide, horizontal-slide, and scroll gestures enabled through `appearance.interaction`, updating the label as each mode locks in.

```tsx
import { useState } from 'react';
import { Block, DataList, Knob, Row, Text, useTheme } from '@plocks/ui';

const MODES = [
  {
    key: 'spin',
    name: 'Spin',
    detail: 'Drag in a circular path. Move away from the thumb for finer adjustments.',
  },
  {
    key: 'vertical-slide',
    name: 'Vertical slide',
    detail: 'Grab either side of the knob and drag up or down for mixer-style throws.',
  },
  {
    key: 'horizontal-slide',
    name: 'Horizontal slide',
    detail: 'Start above or below the center, then drag left or right for sideways sweeps.',
  },
  {
    key: 'scroll',
    name: 'Scroll',
    detail: 'Hover with a mouse or trackpad and use the wheel/two-finger scroll.',
  },
] as const;

type ModeName = (typeof MODES)[number]['key'];

const MODE_LABELS: Record<ModeName, string> = MODES.reduce((acc, mode) => {
  acc[mode.key] = mode.name;
  return acc;
}, {} as Record<ModeName, string>);

export function Demo() {
  const theme = useTheme();
  const [value, setValue] = useState(12);
  const [activeMode, setActiveMode] = useState<ModeName | null>(null);

  return (
    <Block fullWidth>
      <Row gap="xl" align="center" wrap="wrap">
        <Block align="center">
          <Text size="sm" fw="500">
            Multimodal control
          </Text>
          <Knob accessibilityLabel="Pan"
            value={value}
            onChange={setValue}
            min={-100}
            max={100}
            step={1}
            size={180}
            behavior="endless"
            valueLabel={{
              position: 'center',
              formatter: (current) => `${current > 0 ? '+' : ''}${Math.round(current)}`,
              secondary: {
                position: 'bottom',
                formatter: () => (activeMode ? `${MODE_LABELS[activeMode]} mode` : 'Try a gesture'),
              },
            }}
            appearance={{
              arc: { startAngle: -135, sweepAngle: 270, clampInput: true },
              ring: { thickness: 16, color: '#0f172a', trailColor: '#1e293b' },
              fill: { color: '#020617', radiusOffset: -14 },
              progress: {
                mode: 'split',
                roundedCaps: true,
                thickness: 10,
                color: '#38bdf8',
                trailColor: '#475569',
              },
              interaction: {
                modes: MODES.map((mode) => mode.key),
                lockThresholdPx: 32,
                slideRatio: 1.5,
                variancePx: 6,
                spinPrecisionRadius: 80,
                respectStartSide: true,
                scroll: { enabled: true, ratio: 0.8, preventPageScroll: true },
                onModeChange: setActiveMode,
              },
            }}
          />
        </Block>
        <Block style={{ minWidth: 140, flex: 1 }}>
          <DataList spacing="2xl" labelWidth={140}>
            {MODES.map((mode) => (
              <DataList.Item key={mode.key}>
                {/* The mode currently driving the knob is pulled up to full-contrast text. */}
                <DataList.ItemLabel
                  c={activeMode === mode.key ? theme.text.primary : theme.text.muted}
                >
                  {mode.name}
                </DataList.ItemLabel>
                <DataList.ItemValue c={theme.text.secondary}>{mode.detail}</DataList.ItemValue>
              </DataList.Item>
            ))}
          </DataList>
        </Block>
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Layout.md -->

# Layout

Row and Column arrange content horizontally and vertically with Flex alignment, spacing, and sizing props. Row accepts `row` (the default) or `row-reverse` for `direction`; Column accepts `column` (the default) or `column-reverse`. Both default to `gap="sm"`, and Column defaults to `fullWidth={true}`.

## Metadata

- Import: `import { Row, Column } from '@plocks/ui';`
- Tags: layout, horizontal, vertical, row, column, flex, responsive, alignment
- Docs: https://plocks.dev/components/Layout
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Layout

## Props

- `direction`: 'row' | 'row-reverse' | 'column' | 'column-reverse' — Override direction - defaults to 'row' but can be changed to 'row-reverse' Override direction - defaults to 'column' but can be changed to 'column-reverse'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Flex` props (`align` `justify` `wrap` `gap` `rowGap` `columnGap` `grow` `shrink` `basis` `children` `disableRTLMirroring`): https://plocks.dev/llms/components/Flex.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Combine Row and Column to arrange content in horizontal and vertical groups.

```tsx
import { Block, Column, Row, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      <Row gap="sm">
        <Block bg="subtle" p="sm">
          <Text>First</Text>
        </Block>
        <Block bg="subtle" p="sm">
          <Text>Second</Text>
        </Block>
      </Row>
      <Text>Rows place items side by side; columns stack them.</Text>
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Lightbox.md -->

# Lightbox

Lightbox displays images in a full-screen viewer with navigation and optional metadata.

## Metadata

- Import: `import { Lightbox } from '@plocks/ui';`
- Status: experimental
- Tags: lightbox, gallery, images, thumbnails, media
- Docs: https://plocks.dev/components/Lightbox
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Lightbox

## Props

- `images` (required): LightboxItem[] — Array of images to display in the lightbox.
- `initialIndex`: number = 0 — Index of the image shown when the lightbox first opens.
- `onClose`: () => void — Called when the lightbox is closed.
- `onImageChange`: (index: number, image: LightboxItem) => void — Called when the active image changes, receiving the new index and image.
- `onDownload`: (image: LightboxItem) => void — Called when the download action is triggered for the current image.
- `showMetadata`: boolean = false — Whether to display the metadata panel for the current image.
- `showThumbnails`: boolean = true — Whether to display the thumbnail strip for navigating between images.
- `showDownloadButton`: boolean = true — Whether to display the download button in the lightbox controls.
- `allowKeyboardNavigation`: boolean = true — Whether the arrow keys move between images (web). Escape always closes the lightbox, and the thumbnail strip always supports arrow keys.
- `allowSwipeNavigation`: boolean = true — Whether swipe gestures can be used to move between images.
- `overlayOpacity`: number = 0.9 — Opacity of the backdrop behind the lightbox, from 0 to 1 — applied to the theme scrim's color (`theme.backgrounds.scrim`).
- `animationDuration`: number = 250 — `0` opens and closes the lightbox without animation; any other value uses the platform's modal fade. Reduced motion also turns the fade off.
- `accessibilityLabel`: string = 'Image gallery' — Accessible name of the lightbox dialog. @default 'Image gallery'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface LightboxItem {
  id: string;
  /** Remote image URI, or a bundled asset from `require('./photo.png')` */
  uri: string | ImageSourcePropType;
  title?: string;
  description?: string;
  metadata?: {
    size?: string;
    dimensions?: {
      width: number;
      height: number;
    };
    dateCreated?: string;
    camera?: string;
    location?: string;
    /** Extra fields are listed in the metadata panel as `Key: String(value)`. */
    [key: string]: unknown;
  };
}
```

## Examples

### Basics

Basic lightbox with navigation and metadata.

```tsx
import { useState } from 'react';
import { TouchableOpacity } from 'react-native';
import { Block, Lightbox, Image, Row } from '@plocks/ui';

import { SAMPLE_IMAGES } from './data';

export function Demo() {
  // `null` closes the lightbox; any index opens it on that image.
  const [openIndex, setOpenIndex] = useState<number | null>(null);

  return (
    <Block>
      <Row gap="sm" wrap="wrap">
        {SAMPLE_IMAGES.map((image, index) => (
          <TouchableOpacity key={image.id} onPress={() => setOpenIndex(index)}>
            <Image src={image.uri} w={120} h={90} rounded resizeMode="cover" />
          </TouchableOpacity>
        ))}
      </Row>

      <Lightbox
        opened={openIndex !== null}
        images={SAMPLE_IMAGES}
        initialIndex={openIndex ?? 0}
        onClose={() => setOpenIndex(null)}
        showMetadata
      />
    </Block>
  );
}
```

`data.ts`

```ts
import type { LightboxItem } from '@plocks/ui';

/**
 * Three bundled scenes with full metadata, so the viewer's info panel has something
 * to show for every slide.
 */
export const SAMPLE_IMAGES: LightboxItem[] = [
  {
    id: '1',
    uri: require('../../../../assets/images/scene-mountains.png'),
    title: 'Mountain Landscape',
    description: 'Beautiful mountain view with snow-capped peaks',
    metadata: {
      size: '2.4 MB',
      dimensions: { width: 1920, height: 1080 },
      dateCreated: 'March 15, 2024',
      camera: 'Canon EOS R5',
      location: 'Swiss Alps',
    },
  },
  {
    id: '2',
    uri: require('../../../../assets/images/scene-forest.png'),
    title: 'Forest Path',
    description: 'A serene path through the forest',
    metadata: {
      size: '1.8 MB',
      dimensions: { width: 1600, height: 1200 },
      dateCreated: 'April 2, 2024',
      camera: 'Sony A7 III',
      location: 'Pacific Northwest',
    },
  },
  {
    id: '3',
    uri: require('../../../../assets/images/scene-lake.png'),
    title: 'Alpine Lake',
    description: 'Still water beneath the ridgeline',
    metadata: {
      size: '3.1 MB',
      dimensions: { width: 2048, height: 1536 },
      dateCreated: 'May 18, 2024',
      camera: 'Nikon D850',
      location: 'Banff National Park',
    },
  },
];
```

### Advanced

Advanced lightbox configurations with custom handlers.

```tsx
import { useState } from 'react';
import { Block, Button, Lightbox, Row, Text } from '@plocks/ui';
import type { LightboxItem } from '@plocks/ui';

import { SAMPLE_IMAGES } from './data';

export function Demo() {
  const [active, setActive] = useState<'minimal' | 'custom' | null>(null);
  const [downloaded, setDownloaded] = useState<string | null>(null);

  return (
    <Block>
      <Row gap="sm" wrap="wrap">
        <Button variant="outline" onPress={() => setActive('minimal')}>
          Minimal
        </Button>
        <Button variant="outline" onPress={() => setActive('custom')}>
          Custom download
        </Button>
      </Row>

      {/* Chrome stripped back to the image itself — swipe and arrow keys still navigate. */}
      <Lightbox
        opened={active === 'minimal'}
        images={SAMPLE_IMAGES}
        onClose={() => setActive(null)}
        showThumbnails={false}
        showDownloadButton={false}
      />

      {/* `onDownload` replaces the built-in behaviour, so the host app decides what saving means. */}
      <Lightbox
        opened={active === 'custom'}
        images={SAMPLE_IMAGES}
        onClose={() => setActive(null)}
        onDownload={(image: LightboxItem) => setDownloaded(image.title ?? image.id)}
        showMetadata
      />

      {downloaded ? (
        <Text size="sm" c="secondary">
          Downloaded {downloaded}
        </Text>
      ) : null}
    </Block>
  );
}
```

`data.ts`

```ts
import type { LightboxItem } from '@plocks/ui';

/**
 * A short two-image set — enough to exercise navigation without burying the
 * feature each lightbox on this page is meant to demonstrate.
 */
export const SAMPLE_IMAGES: LightboxItem[] = [
  {
    id: 'scene1',
    uri: require('../../../../assets/images/scene-ocean.png'),
    title: 'Coastal Sunrise',
    description: 'First light over the breakwater',
    metadata: {
      size: '1.5 MB',
      dimensions: { width: 1600, height: 1200 },
      dateCreated: 'March 8, 2024',
      camera: 'Fujifilm X-T5',
      location: 'Half Moon Bay',
    },
  },
  {
    id: 'scene2',
    uri: require('../../../../assets/images/scene-city.png'),
    title: 'City at Dusk',
    description: 'Skyline windows lighting up one by one',
    metadata: {
      size: '1.8 MB',
      dimensions: { width: 1400, height: 1050 },
      dateCreated: 'March 12, 2024',
      camera: 'Leica Q3',
      location: 'Downtown rooftop',
    },
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Link.md -->

# Link

A versatile component for creating styled hyperlinks and navigation elements with hover states and accessibility features.

## Metadata

- Import: `import { Link } from '@plocks/ui';`
- Tags: link, anchor, navigation, url, href
- Docs: https://plocks.dev/components/Link
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Link

## Props

- `children` (required): React.ReactNode — Link text content
- `href`: string — Destination URL. On web the link is a real `<a href>` (middle-click, open in new tab, …).
- `onPress`: () => void — Custom press handler (overrides navigating to `href`)
- `onNavigate`: () => void — Client-side navigation on an ordinary click/press. Modified web clicks keep the native anchor behavior.
- `size`: SizeValue = 'lg' — Size of the link text (default: 'lg' = 16px to match the Text component)
- `c`: ColorProp | 'inherit' — Palette token, `'primary.6'` shade syntax, CSS color, or `'inherit'`
- `variant`: 'default' | 'subtle' | 'hover-underline' = 'default' — Link variant
- `disabled`: boolean = false — Whether the link is disabled
- `external`: boolean = false — An external link: opens in a new tab on web (`target="_blank"`, `rel="noopener noreferrer"`), shows a ↗ indicator, and is announced as opening in a new tab.
- `textStyle`: StyleProp<TextStyle> — Additional text style (merged after `style`)
- `accessibilityLabel`: string — Accessible name (defaults to the link text)
- `target`: '_blank' | '_self' = '_self' — Whether this link opens in a new tab/window (web only)
- `newTabLabel`: string = 'opens in a new tab' — Label appended to the accessible name of links that open in a new tab. @default 'opens in a new tab'
- `ff`: string — Custom font family (overrides theme font)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { LinkBox } from '@plocks/ui';`

### LinkBox

- `href` (required): string
- `children` (required): React.ReactNode
- `style`: StyleProp<ViewStyle>
- `accessibilityLabel`: string
- `onNavigate`: () => void — Handles ordinary navigation. Modified browser clicks retain their native behavior.
- `onHoverIn`: () => void
- `onHoverOut`: () => void

## Examples

### Basics

Embed links directly inside supporting copy to guide readers toward related resources.

```tsx
import { Link, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Text>
      Before publishing, review the <Link href="#brand">brand guidelines</Link>, consult our{' '}
      <Link href="#voice">voice and tone guide</Link>, and confirm each launch in the{' '}
      <Link href="#releases">release checklist</Link>.
    </Text>
  );
}
```

### External Destinations

Use the `external` prop when pointing to destinations outside the current shell.

```tsx
import { Link } from '@plocks/ui';

export function Demo() {
  return (
    <Link href="https://reactnative.dev" external>
      React Native documentation
    </Link>
  );
}
```

### Size Options

Demonstrate how the `size` token scales link typography and spacing.

```tsx
import { Block, Link, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Link size={size} href="#">Link</Link>
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Visual Variants

Compare persistent and hover-only underlines alongside subtle variants.

```tsx
import { Block, Link } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Link href="#">Default underline</Link>
      <Link href="#" variant="hover-underline">
        Hover underline
      </Link>
      <Link href="#" variant="subtle">
        Subtle primary
      </Link>
      <Link href="#" variant="subtle" c="gray">
        Subtle gray
      </Link>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ListGroup.md -->

# ListGroup

The ListGroup component provides an organized list structure with items, dividers, and sections for displaying grouped content.

## Metadata

- Import: `import { ListGroup } from '@plocks/ui';`
- Tags: list, group, items, divider, sections
- Docs: https://plocks.dev/components/ListGroup
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ListGroup

## Props

- `children` (required): React.ReactNode
- `variant`: 'default' | 'bordered' | 'flush' = 'default'
- `size`: ComponentSizeValue = 'md'
- `radius`: RadiusValue = 'md' — Corner radius: theme radius token, px, `'none'` or `'full'`.
- `dividers`: boolean = true
- `insetDividers`: boolean = false
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ListGroupItem, ListGroupDivider, ListGroupBody } from '@plocks/ui';`

### ListGroupItem

- `children`: React.ReactNode — Single-line row content. Rendered inside the item's own `<Text>`, so it takes strings and inline text — not a layout block. For a two-line row use `label` + `description` instead.
- `label`: React.ReactNode — Primary line of a two-line row. Takes precedence over `children`, which is ignored when this is set.
- `description`: React.ReactNode — Muted secondary line beneath `label`.
- `value`: React.ReactNode — Muted trailing text, rendered before `endSection`.
- `onPress`: () => void
- `disabled`: boolean
- `active`: boolean
- `danger`: boolean
- `startSection`: React.ReactNode
- `endSection`: React.ReactNode
- `textStyle`: StyleProp<TextStyle> — Applied to the single-line `children` text and to `label`.
- `descriptionStyle`: StyleProp<TextStyle> — Applied to the `description` text.
- `numberOfLines`: number — Truncate `label`/`description` to this many lines instead of wrapping.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ListGroupDivider

- `inset`: boolean — Indent the divider from the leading edge. Defaults to the group's `insetDividers`.
- `style`: StyleProp<ViewStyle>

`ListGroupBody` has no props interface of its own.

## Examples

### Basics

Compose a vertical list by nesting `ListGroupItem` elements inside a `ListGroup`. Use the `variant` prop to switch between `default`, `bordered`, and `flush` styles.

```tsx
import { ListGroup, ListGroupItem } from '@plocks/ui';

export function Demo() {
  return (
    <ListGroup variant="bordered" style={{ width: '100%', maxWidth: 360 }}>
      <ListGroupItem>Overview</ListGroupItem>
      <ListGroupItem>Analytics</ListGroupItem>
      <ListGroupItem>Reports</ListGroupItem>
      <ListGroupItem>Settings</ListGroupItem>
    </ListGroup>
  );
}
```

### Two-line rows

Pass `label` and `description` for a stacked row. These take precedence over `children`, which renders as a single line of text and so cannot hold a layout block. `description` is optional — a `label` on its own reads the same as `children`, and mixing both row shapes in one group stays aligned.

```tsx
import { ListGroup, ListGroupItem } from '@plocks/ui';

export function Demo() {
  return (
    <ListGroup variant="bordered" style={{ width: '100%', maxWidth: 360 }}>
      <ListGroupItem
        label="Download your data"
        description="A ZIP bundle of your profile, library, and history"
      />
      <ListGroupItem label="Privacy" description="Control who sees your activity" />
      <ListGroupItem label="About" />
    </ListGroup>
  );
}
```

### Variants

Compare the default, bordered, and flush group surfaces with identical rows.

```tsx
import { Column, ListGroup, ListGroupItem, Text } from '@plocks/ui';

const variants = ['default', 'bordered', 'flush'] as const;

export function Demo() {
  return (
    <Column gap="lg" fullWidth>
      {variants.map(variant => (
        <Column key={variant} gap="xs" fullWidth>
          <Text fw="semibold">{variant}</Text>
          <ListGroup variant={variant}>
            <ListGroupItem>Overview</ListGroupItem>
            <ListGroupItem>Settings</ListGroupItem>
          </ListGroup>
        </Column>
      ))}
    </Column>
  );
}
```

### Trailing value

`value` renders muted text at the end of the row, before `endSection`. A two-line row already claims the free space, so its value sits flush right on its own; a single-line row only takes its natural width, so the value is what gets pushed to the edge and `endSection` follows it.

```tsx
import { Badge, ListGroup, ListGroupItem } from '@plocks/ui';

export function Demo() {
  return (
    <ListGroup variant="bordered" style={{ width: '100%', maxWidth: 360 }}>
      <ListGroupItem label="Username" value="@ada" />
      <ListGroupItem label="Language" description="App language" value="English" />
      <ListGroupItem value="2 unread" endSection={<Badge>New</Badge>}>
        Inbox
      </ListGroupItem>
    </ListGroup>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Loader.md -->

# Loader

A animated loading component for indicating ongoing processes and loading states with various sizes and styles.

## Metadata

- Import: `import { Loader } from '@plocks/ui';`
- Tags: loader, loading, progress, indicator, animation
- Docs: https://plocks.dev/components/Loader
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Loader

## Props

- `size`: SizeValue = 'md' — Size of the loader - can be a size token (the icon scale) or number
- `color`: ThemeColor — Color of the loader: palette token, `'primary.6'` shade syntax, or any CSS color.
- `variant`: 'bars' | 'dots' | 'oval' = 'oval' — Variant of the loader
- `speed`: number = 1000 — Duration of one animation cycle in milliseconds
- `accessibilityLabel`: string = 'Loading' — Accessible name of the busy indicator (`role="progressbar"`, `aria-busy`).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Pick a loader `variant` to match the type of busy indicator you need for a loading state.

```tsx
import { Loader, Row } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="lg" align="center">
      <Loader variant="oval" />
      <Loader variant="bars" />
      <Loader variant="dots" />
    </Row>
  );
}
```

### Sizes

Set the `size` token to align loaders with other controls, from `xs` indicators up to `3xl` spinners.

```tsx
import { Block, Loader, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Loader size={size} />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Variants

Compare the oval, bars, and dots loading animations.

```tsx
import { Column, Loader, Row, Text } from '@plocks/ui';

const variants = ['oval', 'bars', 'dots'] as const;

export function Demo() {
  return (
    <Row gap="xl" align="center" wrap="wrap">
      {variants.map(variant => (
        <Column key={variant} gap="xs" align="center">
          <Loader variant={variant} />
          <Text size="sm">{variant}</Text>
        </Column>
      ))}
    </Row>
  );
}
```

### Colors

Pull palette values from `useTheme()` and pass them to the `color` prop to align loaders with your semantic colors.

```tsx
import { Block, Loader, Row, Text, useTheme } from '@plocks/ui';

interface LoaderSwatch {
  label: string;
  color: string;
}

export function Demo() {
  const theme = useTheme();

  const swatches: LoaderSwatch[] = [
    { label: 'Primary', color: theme.colors.primary[5] },
    { label: 'Success', color: theme.colors.success[5] },
    { label: 'Warning', color: theme.colors.warning[5] },
    { label: 'Error', color: theme.colors.error[5] }
  ];

  return (
    <Block>
      {swatches.map(({ label, color }) => (
        <Row key={label} gap="md" align="center">
          <Block miw={88}>
            <Text variant="small" c="muted">
              {label}
            </Text>
          </Block>
          <Loader variant="oval" color={color} />
          <Loader variant="bars" color={color} />
          <Loader variant="dots" color={color} />
        </Row>
      ))}
    </Block>
  );
}
```

### Speed

```tsx
import { Block, Loader, Row, Text } from '@plocks/ui';

// `speed` is the duration of one full animation cycle in milliseconds —
// lower is faster. Default is 1000ms.
const SPEEDS = [
  { label: 'Fast', value: 400 },
  { label: 'Default', value: 1000 },
  { label: 'Slow', value: 2000 },
];

export function Demo() {
  return (
    <Block>
      {SPEEDS.map(({ label, value }) => (
        <Row key={value} gap="lg" align="center">
          <Block miw={96}>
            <Text variant="small" fw="semibold">
              {label}
            </Text>
            <Text variant="small" c="muted">
              {value}ms
            </Text>
          </Block>
          <Loader variant="oval" size="lg" speed={value} />
          <Loader variant="bars" size="lg" speed={value} />
          <Loader variant="dots" size="lg" speed={value} />
        </Row>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/LoadingOverlay.md -->

# LoadingOverlay

LoadingOverlay covers content with a loading indicator while work is in progress.

## Metadata

- Import: `import { LoadingOverlay } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/LoadingOverlay
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/LoadingOverlay

## Props

- `visible`: boolean = false — Controls visibility of the loading overlay.
- `zIndex`: number — z-index applied to the overlay container; `overlayProps.zIndex` wins when both are set. Defaults to Overlay's, which lifts it above the content it covers.
- `overlayProps`: OverlayProps — Props forwarded to the underlying Overlay component.
- `loaderProps`: LoaderProps — Props forwarded to the Loader component.
- `loader`: ReactNode — Custom loader content. When provided, Loader component is not rendered.
- `loadingLabel`: string = 'Loading' — Accessible name of the busy indicator, and what is announced. @default 'Loading'
- `announceAfter`: number | false = 1000 — Announce `loadingLabel` to screen readers when loading lasts longer than this many ms (short waits stay silent). `false` never announces.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Locks a simple form while background work finishes and keeps the loader aligned with the card container.

```tsx
import { useState } from 'react';
import { Block, Card, Input, LoadingOverlay, Switch } from '@plocks/ui';

export function Demo() {
  const [visible, setVisible] = useState(true);

  return (
    <Block fullWidth maw={480}>
      <Card>
        <Block>
          <Input label="Name" placeholder="Jane Doe" disabled={visible} />
          <Input label="Email" placeholder="jane@example.com" disabled={visible} />
        </Block>
        <LoadingOverlay visible={visible} overlayProps={{ radius: 'md' }} />
      </Card>

      <Switch label="Loading" checked={visible} onChange={setVisible} />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Markdown.md -->

# Markdown

Markdown component provides a way to render Markdown content with custom styling and component mapping. It supports standard Markdown syntax including headers, lists, code blocks, and more.

## Metadata

- Import: `import { Markdown } from '@plocks/code';`
- Install: `npm install @plocks/code` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/Markdown
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/code/src/components/Markdown

## Props

- `children` (required): string — Markdown source.
- `defaultCodeLanguage`: string — Language for code fences that don't name one (default `tsx`).
- `maxHeadingLevel`: number — Deepest heading level rendered; deeper headings are clamped to it.
- `components`: Partial<MarkdownComponentMap> — Custom renderer overrides
- `onLinkPress`: (href: string) => void — Called when a markdown link is activated. Without it, links open with `Linking.openURL`. On web, modified clicks (new tab / window) are left to the browser.
- `ff`: string — Custom font family applied to all rendered prose (code keeps `theme.fontFamilyMono`)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface MarkdownComponentMap {
  heading: (props: { level: number; children: React.ReactNode }) => React.ReactNode;
  paragraph: (props: { children: React.ReactNode }) => React.ReactNode;
  strong: (props: { children: React.ReactNode }) => React.ReactNode;
  em: (props: { children: React.ReactNode }) => React.ReactNode;
  codeInline: (props: { children: string }) => React.ReactNode;
  codeBlock: (props: { code: string; language?: string }) => React.ReactNode;
  blockquote: (props: { children: React.ReactNode }) => React.ReactNode;
  list: (props: { ordered: boolean; items: React.ReactNode[] }) => React.ReactNode;
  listItem: (props: { children: React.ReactNode; index?: number; ordered?: boolean }) => React.ReactNode;
  link: (props: { href: string; children: React.ReactNode }) => React.ReactNode;
  image: (props: { src: string; alt?: string }) => React.ReactNode;
  thematicBreak: () => React.ReactNode;
  table: (props: {
    headers: React.ReactNode[];
    rows: React.ReactNode[][];
    alignments?: (TableAlignment | undefined)[];
  }) => React.ReactNode;
  tableCell: (props: {
    children: React.ReactNode;
    isHeader?: boolean;
    align?: TableAlignment;
  }) => React.ReactNode;
}
```

## Examples

### Basics

Simple markdown rendering with headers, lists, and text formatting.

```tsx
import { Block } from '@plocks/ui';
import { Markdown } from '@plocks/code';
import content from './content.md';

export function Demo() {
  return (
    <Block fullWidth>
      <Markdown>{content}</Markdown>
    </Block>
  );
}
```

`content.md`

```md
# Hello Markdown

This is a **bold** statement and this is _italic_.

- Item one
- Item two
- Item three

> Blockquote with *inline emphasis* and **strong** text.

Inline code: `const x = 42;`
```

### Code Blocks

Markdown rendering with syntax-highlighted code blocks.

```tsx
import { Block } from '@plocks/ui';
import { Markdown } from '@plocks/code';
import content from './content.md';

export function Demo() {
  return (
    <Block fullWidth>
      <Markdown>{content}</Markdown>
    </Block>
  );
}
```

`content.md`

```md
Here's some JavaScript:

```javascript
function fibonacci(n) {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}
```

And some TypeScript:

```typescript
interface User {
  id: number;
  name: string;
  email: string;
}

const user: User = {
  id: 1,
  name: "John Doe",
  email: "john@example.com"
};
```

Inline code: `const result = fibonacci(10);`
```

### Custom Components

Custom component mapping for markdown elements.

```tsx
import { Block, Card, Text } from '@plocks/ui';
import { Markdown, type MarkdownComponentMap } from '@plocks/code';
import content from './content.md';

// Keys match `MarkdownComponentMap`; anything not listed keeps the default renderer.
const CUSTOM_COMPONENTS: Partial<MarkdownComponentMap> = {
  heading: ({ level, children }) => (
    <Text
      variant={level === 1 ? 'h1' : 'h2'}
      size={level === 1 ? 'xl' : 'lg'}
      fw={level === 1 ? 'bold' : 'semibold'}
      c={level === 1 ? 'primary' : 'secondary'}
      mb={level === 1 ? 12 : 8}
    >
      {children}
    </Text>
  ),
  paragraph: ({ children }) => (
    <Text size="md" mb={8}>
      {children}
    </Text>
  ),
  blockquote: ({ children }) => (
    <Card p={12} variant="outline" bg="muted" mb={8}>
      <Text size="sm" style={{ fontStyle: 'italic' }}>
        {children}
      </Text>
    </Card>
  ),
};

export function Demo() {
  return (
    <Block fullWidth>
      <Markdown components={CUSTOM_COMPONENTS}>{content}</Markdown>
    </Block>
  );
}
```

`content.md`

```md
# Custom styled Markdown

## This is a subtitle

This paragraph uses custom styling and components.

> This blockquote is rendered with a custom Card component and muted background.

Regular paragraph text with default styling.
```

### Inline Usage

Using markdown inline within other text content.

```tsx
import { Block, Text } from '@plocks/ui';
import { Markdown } from '@plocks/code';
import content from './content.md';

export function Demo() {
  const [inlineContent, formatting, code] = content.trim().split(/\n\s*\n/);

  return (
    <Block fullWidth>
      <Text size="md" as="div">
        Inline markdown: <Markdown>{inlineContent}</Markdown>
      </Text>

      <Text size="md" as="div">
        Mix with regular text: Here's some regular text, then <Markdown>{formatting}</Markdown> and
        back to regular.
      </Text>

      <Text size="md" as="div">
        Code in context: Use <Markdown>{code}</Markdown> to declare a variable.
      </Text>
    </Block>
  );
}
```

`content.md`

```md
This is **bold text** and this is *italic text* with `inline code`.

**markdown formatting**

`const x = 42;`
```

### Media & Tables

Markdown with images, links, tables, and horizontal rules.

```tsx
import { Block } from '@plocks/ui';
import { Markdown } from '@plocks/code';
import content from './content.md';

export function Demo() {
  return (
    <Block fullWidth>
      <Markdown>{content}</Markdown>
    </Block>
  );
}
```

`content.md`

```md
# Images

![plocks logo](https://raw.githubusercontent.com/platform-blocks/plocks/main/brand/png/mark.png)

## Links

Visit [plocks.dev](https://plocks.dev) for more examples.

## Tables

| Feature | Status | Notes |
| --- | --- | --- |
| **Text Formatting** | ✅ | Bold, _italic_, `code` |
| Code Blocks | ✅ | Syntax highlighting |
| Tables | ✅ | Responsive layout |
| Images | ✅ | Auto-sizing |
| [Links](https://plocks.dev) | ✅ | External navigation |
```

### Table Support

Markdown tables with proper formatting and styling.

```tsx
import { Block } from '@plocks/ui';
import { Markdown } from '@plocks/code';
import content from './content.md';

export function Demo() {
  return (
    <Block fullWidth>
      <Markdown>{content}</Markdown>
    </Block>
  );
}
```

`content.md`

```md
| Feature | Status | **Priority** | Notes |
|---------|--------|-------------|--------|
| Authentication | ✅ | **High** | _Complete_ |
| User Management | 🔄 | **Medium** | In progress |
| Analytics | ❌ | **Low** | `Not started` |
| API Integration | ✅ | **High** | [Documentation](https://example.com) |
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Marquee.md -->

# Marquee

Use Marquee for decorative rows such as logos or short badges. It respects reduced motion settings.

## Metadata

- Import: `import { Marquee } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Marquee
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Marquee

## Props

- `children` (required): React.ReactNode
- `duration`: number = 20000 — Time for one copy to travel its length in ms. @default 20000
- `reverse`: boolean = false — Reverse travel direction. @default false
- `pauseOnHover`: boolean = false — Pause on web hover and native press. @default false
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Travel axis. @default 'horizontal'
- `repeat`: number = 4 — Number of copies. @default 4
- `gap`: SpacingValue = 'md' — Space between copies. @default 'md'
- `fadeEdges`: boolean = true — Mask the leading and trailing edges. @default true
- `fadeEdgeColor`: string — Color behind a fade edge.
- `fadeEdgeSize`: string = '5%' — Width of each edge fade. @default '5%'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

The children repeat seamlessly; `duration` controls one cycle.

```tsx
import { Badge, Block, Marquee } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Marquee>
        {['Design', 'Build', 'Ship', 'Learn'].map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
    </Block>
  );
}
```

### Vertical and Reverse

Set a fixed `h` for vertical scrolling and use `reverse` to change direction.

```tsx
import { Badge, Block, Marquee } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Marquee orientation="vertical" h={120} reverse>
        {['Alpha', 'Beta', 'Gamma'].map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
    </Block>
  );
}
```

### Pause on Hover

`pauseOnHover` pauses the row when a pointer rests on it.

```tsx
import { Badge, Block, Marquee } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Marquee pauseOnHover>
        {['Alpha', 'Beta', 'Gamma', 'Delta'].map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
    </Block>
  );
}
```

### Multiple Rows

Combine forward and reverse marquees for two rows.

```tsx
import { Badge, Block, Marquee } from '@plocks/ui';

const labels = ['Alpha', 'Beta', 'Gamma', 'Delta'];
export function Demo() {
  return (
    <Block fullWidth>
      <Marquee>
        {labels.map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
      <Marquee reverse mt="sm">
        {labels.map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
    </Block>
  );
}
```

### Fade Edges

`fadeEdgeSize` and `fadeEdges` control the edge treatment.

```tsx
import { Badge, Block, Marquee } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Marquee fadeEdgeSize="15%">
        {['Alpha', 'Beta', 'Gamma', 'Delta'].map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
    </Block>
  );
}
```

### Customization

`duration`, `gap`, and `repeat` tune movement and density.

```tsx
import { Badge, Block, Marquee } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Marquee duration={12000} gap="xl" repeat={5}>
        {['Alpha', 'Beta', 'Gamma', 'Delta'].map((item) => (
          <Badge key={item}>{item}</Badge>
        ))}
      </Marquee>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Masonry.md -->

# Masonry

Masonry arranges items of varying heights in responsive columns.

## Metadata

- Import: `import { Masonry } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Masonry
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Masonry

## Props

- `data` (required): MasonryItem[] = [] — Array of items to display in masonry layout
- `numColumns`: number = 2 — Number of columns (default: 2)
- `gap`: SizeValue = 'sm' — Spacing between items (spacing token or px) — applied by the default item renderer
- `optimizeItemArrangement`: boolean = true — Whether to optimize for staggered grid layout
- `renderItem`: (item: MasonryItem, index: number) => ReactNode — Custom item renderer - receives item and index
- `contentContainerStyle`: StyleProp<ViewStyle> — Content container style
- `contentProps`: StyleProps — Named spacing and sizing props for the scrollable content.
- `loading`: boolean = false — Loading state
- `emptyContent`: ReactNode — Empty state content
- `flashListProps`: MasonryFlashListProps — Flash list props to pass through
- `onEndReached`: ((info: { distanceFromEnd: number }) => void) | null — Callback when the end of the list is reached (for pagination / infinite scroll)
- `onEndReachedThreshold`: number — Distance from end (in pixels) to trigger onEndReached (default: FlashList default)
- `onViewableItemsChanged`: ((info: { viewableItems: MasonryViewToken<MasonryItem>[]; changed: MasonryViewToken<MasonryItem>[] }) => void) | null — Callback when viewable items change
- `scrollEnabled`: boolean — Whether scrolling is enabled
- `ListEmptyComponent`: React.ComponentType | React.ReactElement | null — Component rendered when the list is empty
- `ListFooterComponent`: React.ComponentType | React.ReactElement | null — Component rendered at the bottom of the list
- `ListHeaderComponent`: React.ComponentType | React.ReactElement | null — Component rendered at the top of the list
- `estimatedItemSize`: number — Estimated size of each item (performance hint)
- `refreshControl`: ScrollViewProps['refreshControl'] — Pull-to-refresh control
- `onScroll`: ScrollViewProps['onScroll'] — Scroll event callback
- `scrollEventThrottle`: number — Throttle interval for scroll events in ms
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface MasonryItem {
  /** Unique identifier for the item */
  id: string;
  /** Content to render inside the item */
  content: ReactNode;
  /** Optional custom height ratio (default: 1) */
  heightRatio?: number;
  /** Optional custom styling for the item */
  style?: StyleProp<ViewStyle>;
}

export type MasonryFlashListProps = Partial<ScrollViewProps> & Record<string, unknown>;

export interface MasonryViewToken<T = MasonryItem> {
  item: T;
  key: string;
  index: number | null;
  isViewable: boolean;
  timestamp?: number;
}
```

## Examples

### Basics

Simple masonry layout with uniform item heights arranged in a two-column grid.

```tsx
import { Card, Masonry, Text } from '@plocks/ui';
import type { MasonryItem } from '@plocks/ui';

export function Demo() {
  const masonryItems: MasonryItem[] = [
    {
      id: '1',
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Card 1</Text>
          <Text>This is a basic card item in the masonry layout.</Text>
        </Card>
      ),
    },
    {
      id: '2',
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Card 2</Text>
          <Text>Short content.</Text>
        </Card>
      ),
    },
    {
      id: '3',
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Card 3</Text>
          <Text>A third card showing how items are arranged in the masonry grid with longer content that will make this card taller than the others.</Text>
        </Card>
      ),
    },
    {
      id: '4',
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Card 4</Text>
          <Text>Medium length content here.</Text>
        </Card>
      ),
    },
    {
      id: '5',
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Card 5</Text>
          <Text>Fifth card in the masonry layout grid.</Text>
        </Card>
      ),
    },
    {
      id: '6',
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Card 6</Text>
          <Text>Sixth card showing the two-column arrangement.</Text>
        </Card>
      ),
    },
  ];

  return (
    <Masonry
      data={masonryItems}
      gap="md"
      style={{ height: 400 }}
    />
  );
}
```

### Custom Columns

Masonry layout with configurable number of columns demonstrating different grid arrangements.

```tsx
import { useState } from 'react';
import { Block, Button, Card, Masonry, Row, Text } from '@plocks/ui';
import type { MasonryItem } from '@plocks/ui';

const COLUMN_OPTIONS = [1, 2, 3, 4];

export function Demo() {
  const [numColumns, setNumColumns] = useState(3);

  const masonryItems: MasonryItem[] = [
    {
      id: '1',
      heightRatio: 1.1,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 1</Text>
          <Text>Content for first item with some extra text.</Text>
        </Card>
      ),
    },
    {
      id: '2',
      heightRatio: 0.8,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 2</Text>
          <Text>Short content.</Text>
        </Card>
      ),
    },
    {
      id: '3',
      heightRatio: 1.3,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 3</Text>
          <Text>Longer content to demonstrate height variation in different column layouts.</Text>
        </Card>
      ),
    },
    {
      id: '4',
      heightRatio: 0.9,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 4</Text>
          <Text>Medium length content.</Text>
        </Card>
      ),
    },
    {
      id: '5',
      heightRatio: 1.5,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 5</Text>
          <Text>Extended content that takes up more space to show how columns adapt.</Text>
        </Card>
      ),
    },
    {
      id: '6',
      heightRatio: 0.7,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 6</Text>
          <Text>Compact.</Text>
        </Card>
      ),
    },
    {
      id: '7',
      heightRatio: 1.2,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 7</Text>
          <Text>Another item with moderate content length for testing.</Text>
        </Card>
      ),
    },
    {
      id: '8',
      heightRatio: 0.9,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 8</Text>
          <Text>Standard content item.</Text>
        </Card>
      ),
    },
    {
      id: '9',
      heightRatio: 1.4,
      content: (
        <Card p={12}>
          <Text variant="strong" style={{ marginBottom: 6 }}>Item 9</Text>
          <Text>Taller content to fill out the grid and show column distribution effects.</Text>
        </Card>
      ),
    },
  ];

  return (
    <Block fullWidth>
      <Row gap="sm" wrap="wrap">
        {COLUMN_OPTIONS.map((count) => (
          <Button
            key={count}
            title={count === 1 ? '1 Column' : `${count} Columns`}
            size="sm"
            variant={numColumns === count ? 'filled' : 'outline'}
            onPress={() => setNumColumns(count)}
          />
        ))}
      </Row>

      <Masonry
        data={masonryItems}
        numColumns={numColumns}
        gap="md"
        style={{ height: 400 }}
      />
    </Block>
  );
}
```

### Variable Heights

Masonry layout with items of different heights creating an organic, Pinterest-style staggered appearance.

```tsx
import { Card, Masonry, Text } from '@plocks/ui';
import type { MasonryItem } from '@plocks/ui';

export function Demo() {
  const masonryItems: MasonryItem[] = [
    {
      id: '1',
      heightRatio: 1.2,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Tall Card</Text>
          <Text>
            This is a taller card with more content to demonstrate the variable height 
            functionality. It shows how items with different heights are arranged in 
            the masonry layout to create an organic, staggered appearance.
          </Text>
        </Card>
      ),
    },
    {
      id: '2',
      heightRatio: 0.7,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Short Card</Text>
          <Text>A shorter card with minimal content.</Text>
        </Card>
      ),
    },
    {
      id: '3',
      heightRatio: 1.8,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Very Tall Card</Text>
          <Text>
            This card is extra tall to showcase the masonry layout's ability to handle 
            significant height variations. Lorem ipsum dolor sit amet, consectetur 
            adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna 
            aliqua. Ut enim ad minim veniam, quis nostrud exercitation.
          </Text>
          <Text style={{ marginTop: 8 }}>
            Additional paragraph to make it even taller and show how the layout adapts 
            to content of different sizes naturally.
          </Text>
        </Card>
      ),
    },
    {
      id: '4',
      heightRatio: 1.0,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Regular Card</Text>
          <Text>A standard height card with regular content length.</Text>
        </Card>
      ),
    },
    {
      id: '5',
      heightRatio: 0.9,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Medium Card</Text>
          <Text>Medium height card with moderate content.</Text>
        </Card>
      ),
    },
    {
      id: '6',
      heightRatio: 1.5,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Extended Card</Text>
          <Text>
            An extended card that demonstrates how the masonry layout handles 
            items that are taller than average, creating natural flow patterns.
          </Text>
        </Card>
      ),
    },
    {
      id: '7',
      heightRatio: 0.6,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Compact</Text>
          <Text>Compact card.</Text>
        </Card>
      ),
    },
    {
      id: '8',
      heightRatio: 2.0,
      content: (
        <Card p={16}>
          <Text variant="strong" style={{ marginBottom: 8 }}>Extra Tall Card</Text>
          <Text>
            This is the tallest card in the set, demonstrating the maximum height 
            variation supported by the masonry layout. It shows how very tall items 
            are positioned while maintaining good visual balance.
          </Text>
          <Text style={{ marginTop: 8 }}>
            The masonry layout algorithm ensures that even with extreme height 
            differences, the overall composition remains visually pleasing and 
            well-balanced across columns.
          </Text>
          <Text style={{ marginTop: 8 }}>
            This extra content makes the card significantly taller than others to 
            really showcase the variable height capabilities.
          </Text>
        </Card>
      ),
    },
  ];

  return (
    <Masonry
      data={masonryItems}
      gap="lg"
      style={{ height: 600 }}
    />
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Menu.md -->

# Menu

The Menu component provides a dropdown interface for navigation links, actions, and contextual options.

## Metadata

- Import: `import { Menu } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Menu
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Menu

## Props

- `opened`: boolean — Controlled open state.
- `defaultOpened`: boolean = false — Initial open state when uncontrolled. @default false
- `onChange`: (opened: boolean) => void — Called with the requested open state (both modes).
- `trigger`: 'click' | 'hover' | 'contextmenu' = 'click' — What opens the menu: a press on the trigger (`click`), the pointer resting on it (`hover`, web), or a right-click / long-press (`contextmenu`) — the menu then opens at the pointer.
- `position`: MenuPosition = 'auto' on web, 'top' on native (flips below when needed) — Placement relative to the trigger, written for LTR (mirrored in RTL).
- `offset`: number = 4 — Gap between trigger and menu, px. @default 4
- `closeOnClickOutside`: boolean = true — Close when pressing outside the menu. @default true
- `closeOnEscape`: boolean = true — Close on Escape (web) / Android back. Only the topmost overlay closes. @default true
- `onOpen`: () => void — Called when the menu opens.
- `onClose`: () => void — Called when the menu closes.
- `w`: number | 'target' | 'auto' = 'auto' — Menu width: a number, `'target'` (the trigger's width) or `'auto'` (as wide as the longest item, never narrower than the trigger).
- `mah`: number = 300 — Maximum height before the items scroll. @default 300
- `shadow`: ShadowToken = 'md' — Menu shadow. @default 'md'
- `radius`: RadiusValue = 'md' — Menu corner radius. @default 'md'
- `children` (required): ReactNode — The trigger element followed by a `Menu.Dropdown`.
- `disabled`: boolean = false — Disable the trigger.
- `strategy`: 'absolute' | 'fixed' | 'portal' = isWeb ? 'fixed' : 'portal' — 'fixed' (web default): viewport-fixed; 'absolute'; 'portal' (native default): rendered in an RN Modal at the app root.
- `aria-label`: string — Accessible name of the menu. Defaults to the trigger labelling it (web).
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { MenuItem, MenuLabel, MenuDivider, MenuDropdown, MenuSub, MenuCheckboxItem, MenuRadioGroup, MenuRadioItem } from '@plocks/ui';`

### MenuItem

- `children` (required): ReactNode — Item content
- `onPress`: () => void — Press handler
- `disabled`: boolean — Whether the item is disabled (skipped by arrow keys, announced as disabled)
- `startSection`: ReactNode — Content before the label
- `endSection`: ReactNode — Content after the label (shortcut hint, badge)
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Item color.
- `closeMenuOnClick`: boolean = true — Close the menu when the item is pressed. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuLabel

- `children` (required): ReactNode — Label content
- `textProps`: Omit<TextProps, 'children'> — Override props for the label `<Text>`; the theme's `sectionLabel` text role by default.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuDivider

- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuDropdown

- `children` (required): ReactNode — Dropdown content: Menu.Item / Menu.Label / Menu.Divider / Menu.Sub
- `scrollable`: boolean = true — Wrap the items in a scroll container. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuSub

- `label` (required): ReactNode — Trigger label shown in the parent dropdown
- `children` (required): ReactNode — Submenu items (Menu.Item / Menu.Divider / nested Menu.Sub)
- `startSection`: ReactNode — Content before the trigger label
- `disabled`: boolean — Whether the submenu trigger is disabled
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Trigger color.
- `w`: number = 200 — Submenu width. @default 200
- `mah`: number = 300 — Maximum height before the submenu scrolls. @default 300
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuCheckboxItem

- `checked`: boolean — Controlled checked state.
- `defaultChecked`: boolean = false — Initial checked state. @default false
- `onChange`: (checked: boolean) => void — Called when toggled.
- `closeMenuOnClick`: boolean = false — Close the menu after toggling. @default false
- `children` (required): ReactNode — Item content
- `disabled`: boolean — Whether the item is disabled (skipped by arrow keys, announced as disabled)
- `startSection`: ReactNode — Content before the label
- `endSection`: ReactNode — Content after the label (shortcut hint, badge)
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Item color.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuRadioGroup

- `children` (required): ReactNode
- `value`: string
- `defaultValue`: string
- `onChange`: (value: string) => void
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenuRadioItem

- `value` (required): string
- `closeMenuOnClick`: boolean
- `children` (required): ReactNode — Item content
- `disabled`: boolean — Whether the item is disabled (skipped by arrow keys, announced as disabled)
- `startSection`: ReactNode — Content before the label
- `endSection`: ReactNode — Content after the label (shortcut hint, badge)
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Item color.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menu.CheckboxItem

- `checked`: boolean — Controlled checked state.
- `defaultChecked`: boolean = false — Initial checked state. @default false
- `onChange`: (checked: boolean) => void — Called when toggled.
- `closeMenuOnClick`: boolean = false — Close the menu after toggling. @default false
- `children` (required): ReactNode — Item content
- `disabled`: boolean — Whether the item is disabled (skipped by arrow keys, announced as disabled)
- `startSection`: ReactNode — Content before the label
- `endSection`: ReactNode — Content after the label (shortcut hint, badge)
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Item color.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menu.Dropdown

- `children` (required): ReactNode — Dropdown content: Menu.Item / Menu.Label / Menu.Divider / Menu.Sub
- `scrollable`: boolean = true — Wrap the items in a scroll container. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menu.RadioGroup

- `children` (required): ReactNode
- `value`: string
- `defaultValue`: string
- `onChange`: (value: string) => void
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menu.RadioItem

- `value` (required): string
- `closeMenuOnClick`: boolean
- `children` (required): ReactNode — Item content
- `disabled`: boolean — Whether the item is disabled (skipped by arrow keys, announced as disabled)
- `startSection`: ReactNode — Content before the label
- `endSection`: ReactNode — Content after the label (shortcut hint, badge)
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Item color.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useMenuContext(): MenuContextValue` — Returns the enclosing menu state for custom items.
- `useMenuStyles(options: MenuStyleOptions = {})` — Returns the current theme's menu surface styles (`dropdown`, `item`, `itemHovered`, `label`, `divider`, … plus the raw level-2 `surfaceToken`) — for a custom dropdown or list that should match `Menu`.

## Types

```ts
export type MenuPosition = PlacementType;
```

## Examples

### Basics

Pair a trigger with `MenuDropdown` to show primary actions and separators in a compact surface.

```tsx
import { Button, Icon, Menu, MenuDivider, MenuDropdown, MenuItem } from '@plocks/ui';

export function Demo() {
  return (
    <Menu>
      <Button size="sm" variant="outline">
        Open menu
      </Button>
      <MenuDropdown>
        <MenuItem startSection={<Icon name="user" size="sm" />}>
          Profile
        </MenuItem>
        <MenuItem startSection={<Icon name="settings" size="sm" />}>
          Settings
        </MenuItem>
        <MenuItem startSection={<Icon name="info" size="sm" />}>
          Help & Support
        </MenuItem>
        <MenuDivider />
        <MenuItem startSection={<Icon name="arrow-left" size="sm" />}>
          Logout
        </MenuItem>
      </MenuDropdown>
    </Menu>
  );
}
```

### Context Trigger

Enable `trigger="contextmenu"` to surface a menu when users right-click or long-press a target.

```tsx
import { Card, Icon, Menu, MenuDivider, MenuDropdown, MenuItem, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Menu trigger="contextmenu">
      <Card variant="outline" p="xl">
        <Text>Right-click or long-press here</Text>
      </Card>
      <MenuDropdown>
        <MenuItem startSection={<Icon name="copy" size="sm" />}>
          Copy link
        </MenuItem>
        <MenuItem startSection={<Icon name="edit" size="sm" />}>
          Rename
        </MenuItem>
        <MenuItem startSection={<Icon name="share" size="sm" />}>
          Share
        </MenuItem>
        <MenuDivider />
        <MenuItem startSection={<Icon name="trash" size="sm" />}>
          Delete
        </MenuItem>
      </MenuDropdown>
    </Menu>
  );
}
```

### Placement Presets

Adjust the `position` prop to pin dropdown content to any edge of the trigger.

```tsx
import { Button, Menu, MenuDropdown, MenuItem, Row } from '@plocks/ui';

const POSITIONS = [
  { label: 'Bottom start', position: 'bottom-start' },
  { label: 'Bottom', position: 'bottom' },
  { label: 'Bottom end', position: 'bottom-end' },
  { label: 'Top start', position: 'top-start' },
  { label: 'Top', position: 'top' },
  { label: 'Top end', position: 'top-end' },
] as const;

export function Demo() {
  return (
    <Row gap="md" justify="center" wrap="wrap">
      {POSITIONS.map(({ label, position }) => (
        <Menu key={position} position={position}>
          <Button size="sm" variant="outline">
            {label}
          </Button>
          <MenuDropdown>
            <MenuItem>Duplicate</MenuItem>
            <MenuItem>Archive</MenuItem>
          </MenuDropdown>
        </Menu>
      ))}
    </Row>
  );
}
```

### Checkbox and Radio Items

Choice items keep the menu open while their state changes.

```tsx
import { Button, Menu } from '@plocks/ui';

export function Demo() {
  return (
    <Menu>
      <Button>View options</Button>
      <Menu.Dropdown>
        <Menu.CheckboxItem defaultChecked>Show grid</Menu.CheckboxItem>
        <Menu.RadioGroup defaultValue="comfortable">
          <Menu.RadioItem value="comfortable">Comfortable</Menu.RadioItem>
          <Menu.RadioItem value="compact">Compact</Menu.RadioItem>
        </Menu.RadioGroup>
      </Menu.Dropdown>
    </Menu>
  );
}
```

### Submenu

```tsx
import { Button, Icon, Menu, MenuDropdown, MenuItem, MenuSub } from '@plocks/ui';

export function Demo() {
  return (
    <Menu w={220}>
      <Button size="sm" variant="outline">
        Actions
      </Button>
      <MenuDropdown>
        <MenuItem startSection={<Icon name="edit" size="sm" />}>Rename</MenuItem>
        <MenuSub label="Share" startSection={<Icon name="share" size="sm" />}>
          <MenuItem startSection={<Icon name="link" size="sm" />}>Copy link</MenuItem>
          <MenuItem startSection={<Icon name="mail" size="sm" />}>Email</MenuItem>
          <MenuSub label="Social">
            <MenuItem>Twitter / X</MenuItem>
            <MenuItem>LinkedIn</MenuItem>
            <MenuItem>Reddit</MenuItem>
          </MenuSub>
        </MenuSub>
        <MenuSub label="Move to" startSection={<Icon name="folder" size="sm" />}>
          <MenuItem>Projects</MenuItem>
          <MenuItem>Archive</MenuItem>
          <MenuItem>Trash</MenuItem>
        </MenuSub>
      </MenuDropdown>
    </Menu>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Menubar.md -->

# Menubar

Menubar wraps the existing Menu dropdowns and keeps only one menu open at a time.

## Metadata

- Import: `import { Menubar } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Menubar
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Menubar

## Props

- `children` (required): React.ReactNode
- `trigger`: 'click' | 'hover'
- `loop`: boolean
- `openIndex`: number | null
- `defaultOpenIndex`: number | null
- `onOpenChange`: (index: number | null) => void
- `position`: MenuProps['position']
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { MenubarMenu, MenubarTarget, MenubarDropdown } from '@plocks/ui';`

### MenubarMenu

- `children` (required): React.ReactNode
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Menu` props (`position` `offset` `closeOnClickOutside` `closeOnEscape` `onOpen` `onClose` `w` `mah` `shadow` `radius` `disabled` `strategy` `aria-label`): https://plocks.dev/llms/components/Menu.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenubarTarget

- `children` (required): React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Button` props (`onPress` `onPressIn` `onPressOut` `onHoverIn` `onHoverOut` `onLongPress` `onLayout` `variant` `color` `size` `disabled` `loading` `loadingTitle` `fullWidth` `textColor` `icon` `startSection` `endSection` `tooltip` `transitionDuration` `accessibilityLabel` `accessibilityHint` `labelProps`): https://plocks.dev/llms/components/Button.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### MenubarDropdown

- `children` (required): ReactNode — Dropdown content: Menu.Item / Menu.Label / Menu.Divider / Menu.Sub
- `scrollable`: boolean = true — Wrap the items in a scroll container. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menubar.Dropdown

- `children` (required): ReactNode — Dropdown content: Menu.Item / Menu.Label / Menu.Divider / Menu.Sub
- `scrollable`: boolean = true — Wrap the items in a scroll container. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menubar.Menu

- `children` (required): React.ReactNode
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Menu` props (`position` `offset` `closeOnClickOutside` `closeOnEscape` `onOpen` `onClose` `w` `mah` `shadow` `radius` `disabled` `strategy` `aria-label`): https://plocks.dev/llms/components/Menu.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Menubar.Target

- `children` (required): React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Button` props (`onPress` `onPressIn` `onPressOut` `onHoverIn` `onHoverOut` `onLongPress` `onLayout` `variant` `color` `size` `disabled` `loading` `loadingTitle` `fullWidth` `textColor` `icon` `startSection` `endSection` `tooltip` `transitionDuration` `accessibilityLabel` `accessibilityHint` `labelProps`): https://plocks.dev/llms/components/Button.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Open a menu by pressing its target, then hover or use arrow keys to switch menus.

```tsx
import { Block, Menu, Menubar } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Menubar>
        <Menubar.Menu>
          <Menubar.Target>File</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>New</Menu.Item>
            <Menu.Item>Open</Menu.Item>
            <Menu.Divider />
            <Menu.Item>Exit</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
        <Menubar.Menu>
          <Menubar.Target>Edit</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>Undo</Menu.Item>
            <Menu.Item>Redo</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
        <Menubar.Menu>
          <Menubar.Target>Help</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>Documentation</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
      </Menubar>
    </Block>
  );
}
```

### Hover Trigger

With `trigger="hover"`, moving across targets switches menus.

```tsx
import { Block, Menu, Menubar } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Menubar trigger="hover">
        <Menubar.Menu>
          <Menubar.Target>File</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>New</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
        <Menubar.Menu>
          <Menubar.Target>Edit</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>Undo</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
      </Menubar>
    </Block>
  );
}
```

### Checkbox and Radio Items

Top-level dropdowns can contain persistent menu choices.

```tsx
import { Block, Menu, Menubar } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Menubar>
        <Menubar.Menu>
          <Menubar.Target>View</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.CheckboxItem>Show grid</Menu.CheckboxItem>
            <Menu.RadioGroup defaultValue="list">
              <Menu.RadioItem value="list">List</Menu.RadioItem>
              <Menu.RadioItem value="grid">Grid</Menu.RadioItem>
            </Menu.RadioGroup>
          </Menubar.Dropdown>
        </Menubar.Menu>
      </Menubar>
    </Block>
  );
}
```

### Submenus

Menubar dropdowns reuse nested Menu.Sub groups.

```tsx
import { Block, Menu, Menubar } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Menubar>
        <Menubar.Menu>
          <Menubar.Target>File</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Sub label="Share">
              <Menu.Item>Email</Menu.Item>
              <Menu.Item>Copy link</Menu.Item>
            </Menu.Sub>
          </Menubar.Dropdown>
        </Menubar.Menu>
      </Menubar>
    </Block>
  );
}
```

### Dropdown Position

A menu can override the default bottom-start placement.

```tsx
import { Block, Menu, Menubar } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Menubar>
        <Menubar.Menu position="bottom-end">
          <Menubar.Target>Options</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>Settings</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
      </Menubar>
    </Block>
  );
}
```

### Controlled State

`openIndex` and `onOpenChange` let a parent own the open menu.

```tsx
import { useState } from 'react';
import { Block, Menu, Menubar } from '@plocks/ui';

export function Demo() {
  const [openIndex, setOpenIndex] = useState<number | null>(null);
  return (
    <Block fullWidth>
      <Menubar openIndex={openIndex} onOpenChange={setOpenIndex}>
        <Menubar.Menu>
          <Menubar.Target>File</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>New</Menu.Item>
            <Menu.Item>Open</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
        <Menubar.Menu>
          <Menubar.Target>Edit</Menubar.Target>
          <Menubar.Dropdown>
            <Menu.Item>Undo</Menu.Item>
            <Menu.Item>Redo</Menu.Item>
          </Menubar.Dropdown>
        </Menubar.Menu>
      </Menubar>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/MenuItemButton.md -->

# MenuItemButton

A row button used inside menus and command palettes. The inner label `<Text>` accepts the full Text-prop API via `labelProps` (`ff`, `fw`, `lts`, `tt`, `c`, `style`).

## Metadata

- Import: `import { MenuItemButton } from '@plocks/ui';`
- Tags: menu, dropdown, command, item, button
- Docs: https://plocks.dev/components/MenuItemButton
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/MenuItemButton

## Props

- `title`: string — Text label (alternative to children)
- `children`: React.ReactNode — Custom content
- `startSection`: React.ReactNode — Leading content (usually an icon)
- `endSection`: React.ReactNode — Trailing content (icon, shortcut hint)
- `onPress`: () => void — Click handler
- `disabled`: boolean — Whether the button is disabled
- `active`: boolean — Whether the button is active (highlighted / selected)
- `danger`: boolean — Whether the button has destructive styling
- `fullWidth`: boolean — Whether the button should take up full width
- `size`: ComponentSizeValue — Size of the button (token or height in px)
- `compact`: boolean — Whether to use compact styling
- `rounded`: boolean — Whether to use fully rounded corners
- `onMouseDown`: (event: WebMouseEvent) => void — Web-only mouse down handler (e.g. to keep focus in a text input)
- `color`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Semantic color for menu styling
- `hoverColor`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Color to apply when hovered
- `activeColor`: 'default' | 'primary' | 'error' | 'success' | 'warning' — Color to apply when active/pressed
- `textColor`: string — Override text color for base state
- `hoverTextColor`: string — Override text color when hovered
- `activeTextColor`: string — Override text color when active
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the inner label `<Text>` (style, fw, ff, size, c).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Simple dropdown menu with icons and dividers.

```tsx
import { Menu, MenuItem, MenuDivider, MenuDropdown, Button, Icon } from '@plocks/ui';

export function Demo() {
  return (
    <Menu>
      <Button variant="filled">Open Menu</Button>
      <MenuDropdown>
        <MenuItem startSection={<Icon name="user" />}>
          Profile
        </MenuItem>
        <MenuItem startSection={<Icon name="settings" />}>
          Settings
        </MenuItem>
        <MenuItem startSection={<Icon name="info" />}>
          Help & Support
        </MenuItem>
        <MenuItem startSection={<Icon name="arrow-left" />}>
          Logout
        </MenuItem>
      </MenuDropdown>
    </Menu>
  )
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/MiniCalendar.md -->

# MiniCalendar

A compact calendar component for displaying a month view with selectable dates.

## Metadata

- Import: `import { MiniCalendar } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/MiniCalendar
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/MiniCalendar

## Props

- `value`: Date | null — Value
- `onChange`: (date: Date | null) => void
- `defaultValue`: Date | null
- `numberOfDays`: number = 7 — Days shown in the strip. Default `7`.
- `defaultDate`: Date
- `minDate`: Date — Constraints
- `maxDate`: Date
- `nextControlProps`: MiniCalendarControlProps — Extra props for the "next days" control (label, testID, style, ...).
- `previousControlProps`: MiniCalendarControlProps — Extra props for the "previous days" control (label, testID, style, ...).
- `getDayProps`: (date: Date) => Partial<DayProps> — Customization
- `renderDay`: (date: Date) => React.ReactNode
- `locale`: string = 'en-US' — Localization
- `size`: SizeValue = 'md'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Compact calendar showing a week view with date selection.

```tsx
import { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { MiniCalendar } from '@plocks/dates';

export function Demo() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());

  return (
    <Block fullWidth>
      <MiniCalendar
        value={selectedDate}
        onChange={(date: Date | null) => setSelectedDate(date)}
        numberOfDays={7}
      />
      <Text size="sm" c="secondary">
        {selectedDate ? `Selected: ${selectedDate.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Custom Day Count

MiniCalendar with configurable number of days displayed.

```tsx
import React, { useState } from 'react';
import { Block, Button, Row, Text } from '@plocks/ui';
import { MiniCalendar } from '@plocks/dates';

const DAY_OPTIONS = [3, 5, 7];

export function Demo() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());
  const [numberOfDays, setNumberOfDays] = useState(5);

  return (
    <Block fullWidth>
      <Row gap="xs">
        {DAY_OPTIONS.map((days) => (
          <Button
            key={days}
            size="sm"
            variant={numberOfDays === days ? 'filled' : 'outline'}
            onPress={() => setNumberOfDays(days)}
          >
            {days} days
          </Button>
        ))}
      </Row>
      <MiniCalendar
        value={selectedDate}
        onChange={(date: Date | null) => setSelectedDate(date)}
        numberOfDays={numberOfDays}
      />
      <Text size="sm" c="secondary">
        {selectedDate ? `Selected: ${selectedDate.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Date Constraints

MiniCalendar with minimum and maximum date restrictions.

```tsx
import React, { useMemo, useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { MiniCalendar } from '@plocks/dates';

export function Demo() {
  const [selectedDate, setSelectedDate] = useState<Date | null>(new Date());

  const { minDate, maxDate } = useMemo(() => {
    const today = new Date();
    const nextWeek = new Date();
    nextWeek.setDate(today.getDate() + 7);
    return { minDate: today, maxDate: nextWeek };
  }, []);

  return (
    <Block fullWidth>
      <MiniCalendar
        value={selectedDate}
        onChange={(date: Date | null) => setSelectedDate(date)}
        numberOfDays={7}
        minDate={minDate}
        maxDate={maxDate}
      />
      <Text size="sm" c="secondary">
        {selectedDate ? `Selected: ${selectedDate.toLocaleDateString()}` : 'No date selected'}
      </Text>
      <Text size="xs" c="secondary">
        Only the next seven days are enabled
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/MonthPicker.md -->

# MonthPicker

Interactive grid for selecting a month within a given year. Renders a responsive layout that adapts to screen width and respects locale formatting as well as min/max date constraints.

## Metadata

- Import: `import { MonthPicker } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Tags: date, month, picker, calendar
- Docs: https://plocks.dev/components/MonthPicker
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/MonthPicker

## Props

- `value`: Date | null — Currently selected date (uses the first day of the month)
- `onChange`: (date: Date | null) => void — Called when user picks a new month
- `year`: number — Force a specific year to render
- `onYearChange`: (year: number) => void — Called when the visible year changes
- `minDate`: Date — Minimum selectable date (inclusive)
- `maxDate`: Date — Maximum selectable date (inclusive)
- `locale`: string = 'en-US' — Locale used for month labels
- `size`: ComponentSizeValue = 'md' — Size token that influences typography weight
- `monthLabelFormat`: 'short' | 'long' = 'long' — Format of month labels
- `hideHeader`: boolean = false — Hide navigation header (used when embedded in Calendar)
- `monthsPerRow`: ResponsiveProp<number> — Responsive override for the number of months rendered per row (breakpoints from `theme.breakpoints`).
- `fullWidth`: boolean = false — Stretch to fill the container instead of sizing to the natural grid width. Default `false`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Interactive grid for selecting a month within a given year. Renders a responsive layout that adapts to screen width and respects locale formatting as well as min/max date constraints.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { MonthPicker } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(new Date());

  return (
    <Block fullWidth>
      <MonthPicker value={value} onChange={setValue} monthLabelFormat="long" />
      <Text size="sm" c="secondary">
        {value
          ? value.toLocaleDateString(undefined, { month: 'long', year: 'numeric' })
          : 'No month selected'}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/MonthPickerInput.md -->

# MonthPickerInput

MonthPickerInput opens a month picker from a form field.

## Metadata

- Import: `import { MonthPickerInput } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/MonthPickerInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/MonthPickerInput

## Props

- `value`: Date | null — Controlled value for the selected month
- `defaultValue`: Date | null — Default month when uncontrolled
- `onChange`: (value: Date | null) => void — Called when the month selection changes
- `locale`: string = 'en-US' — Locale used for formatting the input value
- `formatOptions`: Intl.DateTimeFormatOptions — Intl format options for rendering the selected month
- `formatValue`: (value: Date) => string — Custom formatter for the input value; overrides locale/formatOptions
- `closeOnSelect`: boolean = true — Close the picker after selecting a month
- `monthPickerProps`: Partial<Omit<MonthPickerProps, 'value'>> — Additional props forwarded to MonthPicker (except value)
- `dropdownType`: 'modal' | 'popover' = 'modal' — `modal` (default): a centered sheet. `popover`: a dropdown anchored to the field on desktop web (the sheet on native and small screens).
- `modalTitle`: string = 'Select month' — Title of the picker sheet / name of the popover.
- `onOpen`: () => void — Called when the picker opens
- `onClose`: () => void — Called when the picker closes
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

MonthPickerInput opens a month picker from a form field.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { MonthPickerInput } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <Block fullWidth>
      <MonthPickerInput
        value={value}
        onChange={setValue}
        label="Billing cycle"
        placeholder="Select a month"
        clearable
        fullWidth
      />
      <Text size="sm" c="secondary">
        {value
          ? value.toLocaleDateString(undefined, { month: 'long', year: 'numeric' })
          : 'No month selected'}
      </Text>
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on MonthPickerInput.

```tsx
import { Column } from '@plocks/ui';
import { MonthPickerInput } from '@plocks/dates';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <MonthPickerInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Choose a month" />
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/MotionBlock.md -->

# MotionBlock

MotionBlock animates a layout container using React Native animated values.

## Metadata

- Import: `import { MotionBlock } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/MotionBlock
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/MotionBlock

## Props

- `scale`: AnimatedNumber
- `translateX`: AnimatedNumber
- `translateY`: AnimatedNumber
- `motionRotate`: AnimatedString
- `motionOpacity`: AnimatedNumber
- `motionWidth`: AnimatedString
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `start`: number | string — Start inset (logical: left in LTR, right in RTL)
- `end`: number | string — End inset (logical: right in LTR, left in RTL)
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Plus the `Block` props (`children` `className` `onPress` `onLongPress` `onPressIn` `onPressOut` `onMouseEnter` `onMouseLeave` `disabled`): https://plocks.dev/llms/components/Block.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
type AnimatedNumber = number | Animated.Value;

type AnimatedString = string | Animated.AnimatedInterpolation<string>;
```

## Examples

### Basics

MotionBlock animates a layout container using React Native animated values.

```tsx
import { useEffect, useRef } from 'react';
import { Animated } from 'react-native';
import { MotionBlock, Text } from '@plocks/ui';

export function Demo() {
  const offset = useRef(new Animated.Value(16)).current;

  useEffect(() => {
    Animated.timing(offset, { toValue: 0, duration: 500, useNativeDriver: true }).start();
  }, [offset]);

  return (
    <MotionBlock translateY={offset} bg="subtle" p="md" radius="md">
      <Text>Animated entrance</Text>
    </MotionBlock>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/NavTree.md -->

# NavTree

NavTree turns a flat route list into a collapsible sidebar navigation tree.

## Metadata

- Import: `import { NavTree } from '@plocks/ui';`
- Tags: navigation, sidebar, tree, menu, routes
- Docs: https://plocks.dev/components/NavTree
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/NavTree

## Props

- `items` (required): NavTreeItem<T>[] — The destinations, flat. Grouped and nested by `buildNavTree`.
- `activeHref`: string — Current route. Marks its row (`aria-current="page"` on web) and opens the groups above it.
- `onNavigate`: (item: NavTreeItem<T>, node: TreeNode<NavTreeItem<T>>) => void — Where a row press goes. Supply it to route client-side; without it the rows stay plain links and the browser navigates.
- `size`: ComponentSizeValue = 'sm' — Row density. @default 'sm'
- `collapsed`: boolean — Rail mode: only the top level renders, as icons. For a sidebar that collapses to a strip — the full tree is one hover away, and a column of every leaf's icon is not navigation, it is noise.
- `searchable`: boolean — Show a filter field above the tree, wired to `filterQuery`. Past a certain length no amount of nesting beats typing three letters, and every sidebar that needs one would otherwise wire the same input and the same state. Pass `filterQuery` as well to drive it from outside; on its own the field keeps its own query. Hidden in `collapsed` mode, where there is no room.
- `searchPlaceholder`: string = 'Filter…' — Placeholder for the filter field. @default 'Filter…'
- `highlightMatches`: boolean = true — Matched substrings are marked in the row labels. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `groupOrder`: string[] — Curated order for group labels, checked at every level. Groups not listed follow, alphabetically — so a partial order is enough, and a new group appears in a sensible place without touching this. Entries are bare labels (`'Input'`) or full paths (`'Hooks/Navigation'`). A path wins over a bare label, which is how the same name can rank differently in two branches.
- `groupIcons`: Record<string, React.ReactNode> — Leading icon per group label.
- `sortLeaves`: 'alpha' | 'none' = 'alpha' — How leaves inside a group are ordered. - `'alpha'` — by `order` then label. The default: a long list is easier to scan alphabetically than in whatever order the array happened to be in. - `'none'` — keep the order given.
- `openDepth`: number = 1 — Groups shallower than this start open. `1` opens the top level and leaves everything below it closed, which is the shape a docs sidebar wants: the sections are visible, the long category lists are not.
- `openGroups`: string[] — Group labels (or full `A/B` paths) to open regardless of `openDepth`.
- `getGroupNode`: (context: { label: string; path: string[]; depth: number; items: NavTreeItem<T>[]; }) => Partial<TreeNode<NavTreeItem<T>>> — Decorates each group row — a count, a badge, an icon. Receives the group's path from the root and the items beneath it, at every level.

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface NavTreeItem<T = unknown> {
  /** Row text. */
  label: string;
  /** Route this row points at. Doubles as the item's id unless `id` is given. */
  href: string;
  /**
   * Where the item sits, outermost group first. A string is a single level;
   * omit it for a top-level row. Empty strings are dropped, so an item whose
   * category is unset lands beside the groups rather than under a blank one.
   */
  group?: string | string[];
  /** Stable id. Defaults to `href`, which is already unique in a router. */
  id?: string;
  /** Leading icon for the row. */
  icon?: React.ReactNode;
  /** Sorts before `label` when leaves are ordered. Unset sorts last. */
  order?: number;
  disabled?: boolean;
  /** Anything the consumer wants back in `onNavigate`. */
  data?: T;
}
```

## Examples

### Basics

A flat list of routes becomes a nested sidebar. The group above the active route is already open, because `activeHref` opened it.

```tsx
import React, { useState } from 'react';
import { NavTree, type NavTreeItem } from '@plocks/ui';

// The whole input: a flat list, with a category on each row. Nothing here
// describes the tree — `NavTree` derives it.
const ROUTES: NavTreeItem[] = [
  { label: 'Getting Started', href: '/getting-started' },
  { label: 'Button', href: '/components/Button', group: ['Components', 'Input'] },
  { label: 'Select', href: '/components/Select', group: ['Components', 'Input'] },
  { label: 'Checkbox', href: '/components/Checkbox', group: ['Components', 'Input'] },
  { label: 'Card', href: '/components/Card', group: ['Components', 'Display'] },
  { label: 'Badge', href: '/components/Badge', group: ['Components', 'Display'] },
  { label: 'Tabs', href: '/components/Tabs', group: ['Components', 'Navigation'] },
];

export function Demo() {
  const [route, setRoute] = useState('/components/Select');

  return (
    <NavTree
      items={ROUTES}
      activeHref={route}
      onNavigate={item => setRoute(item.href)}
      showGuides
    />
  );
}
```

### Counts and order

`groupOrder` curates the sections that matter and leaves the rest alphabetical. `renderEndSection` hangs a count off each branch, and `openDepth={0}` starts everything closed.

```tsx
import React, { useState } from 'react';
import { Badge, NavTree, type NavTreeItem } from '@plocks/ui';

const ROUTES: NavTreeItem[] = [
  { label: 'Button', href: '/components/Button', group: 'Input' },
  { label: 'Select', href: '/components/Select', group: 'Input' },
  { label: 'Checkbox', href: '/components/Checkbox', group: 'Input' },
  { label: 'Card', href: '/components/Card', group: 'Display' },
  { label: 'Badge', href: '/components/Badge', group: 'Display' },
  { label: 'Tabs', href: '/components/Tabs', group: 'Navigation' },
];

export function Demo() {
  const [route, setRoute] = useState('/components/Card');

  return (
    <NavTree
      items={ROUTES}
      activeHref={route}
      onNavigate={item => setRoute(item.href)}
      // Curate the order that matters and let the rest sort themselves.
      groupOrder={['Input', 'Display']}
      openDepth={0}
      renderEndSection={node =>
        node.children ? <Badge size="xs" variant="light">{node.children.length}</Badge> : null
      }
    />
  );
}
```

### Filtering

`searchable` adds a filter field wired to the tree. Typing hides the rows that do not match, opens the branches above the ones that do, and marks the matched substring — past a certain length, three letters beat any amount of nesting.

```tsx
import React, { useState } from 'react';
import { NavTree, type NavTreeItem } from '@plocks/ui';

const ROUTES: NavTreeItem[] = [
  { label: 'Button', href: '/components/Button', group: 'Input' },
  { label: 'Checkbox', href: '/components/Checkbox', group: 'Input' },
  { label: 'Select', href: '/components/Select', group: 'Input' },
  { label: 'TextArea', href: '/components/TextArea', group: 'Input' },
  { label: 'Badge', href: '/components/Badge', group: 'Display' },
  { label: 'Card', href: '/components/Card', group: 'Display' },
  { label: 'Breadcrumbs', href: '/components/Breadcrumbs', group: 'Navigation' },
  { label: 'Tabs', href: '/components/Tabs', group: 'Navigation' },
];

export function Demo() {
  const [route, setRoute] = useState('/components/Card');

  return (
    <NavTree
      items={ROUTES}
      activeHref={route}
      onNavigate={item => setRoute(item.href)}
      searchable
      searchPlaceholder="Filter components…"
    />
  );
}
```

### Collapsed rail

`collapsed` drops the sidebar to a strip of top-level icons — the group holding the current route stays marked, and pressing one lands on the first page inside it. A sidebar with a hundred routes shows a handful of icons here, not a hundred.

```tsx
import React, { useState } from 'react';
import { Column, Icon, NavTree, Switch, type NavTreeItem } from '@plocks/ui';

const ROUTES: NavTreeItem[] = [
  { label: 'Button', href: '/components/Button', group: 'Components' },
  { label: 'Card', href: '/components/Card', group: 'Components' },
  { label: 'LineChart', href: '/components/LineChart', group: 'Charts' },
  { label: 'BarChart', href: '/components/BarChart', group: 'Charts' },
  { label: 'useHover', href: '/hooks/useHover', group: 'Hooks' },
];

const GROUP_ICONS = {
  Components: <Icon name="grid" size={18} />,
  Charts: <Icon name="chart-bar" size={18} />,
  Hooks: <Icon name="hook" size={18} />,
};

export function Demo() {
  const [collapsed, setCollapsed] = useState(true);
  const [route, setRoute] = useState('/components/Card');

  return (
    <Column gap="md">
      <Switch checked={collapsed} onChange={setCollapsed} label="Collapsed" />
      <NavTree
        items={ROUTES}
        activeHref={route}
        onNavigate={item => setRoute(item.href)}
        groupIcons={GROUP_ICONS}
        collapsed={collapsed}
      />
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/NumberInput.md -->

# NumberInput

NumberInput provides a numeric field with step controls and optional formatting.

## Metadata

- Import: `import { NumberInput } from '@plocks/ui';`
- Tags: input, numeric, stepper, formatter
- Docs: https://plocks.dev/components/NumberInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/NumberInput

## Props

- `id`: string — Id of the TextInput; label/error ids derive from it. Generated when omitted.
- `value`: number — Controlled value. Passing the prop at all (even `undefined`, meaning "empty") makes the field controlled; omit it and use `defaultValue` for an uncontrolled field.
- `defaultValue`: number — Initial value while uncontrolled.
- `onChange`: (value: number | undefined) => void — Called with the new number, or `undefined` when the field is cleared.
- `allowDecimal`: boolean — Allow decimal values
- `allowNegative`: boolean = true — Allow negative values
- `allowLeadingZeros`: boolean = true — Allow leading zeros while editing
- `allowedDecimalSeparators`: string[] — Additional characters that should be treated as decimal separators
- `decimalSeparator`: string = DEFAULT_DECIMAL_SEPARATOR — Decimal separator character
- `decimalScale`: number — Maximum number of digits after the decimal point
- `fixedDecimalScale`: boolean = false — When true, pads the decimal part with trailing zeros to match decimalScale
- `min`: number — Minimum value
- `max`: number — Maximum value
- `step`: number = 1 — Step increment
- `shiftMultiplier`: number = 10 — Multiplier applied to the step when using modifier keys
- `precision`: number — Number of decimal places
- `thousandSeparator`: string | boolean — Thousand separator character or boolean to enable default separator
- `thousandsGroupStyle`: 'none' | 'thousand' | 'lakh' | 'wan' = 'thousand' — Thousand grouping strategy
- `prefix`: string — Prefix string appended before the value when displayed
- `suffix`: string — Suffix string appended after the value when displayed
- `format`: 'integer' | 'decimal' | 'currency' | 'percentage' = 'decimal' — Number format
- `currency`: string = 'USD' — Currency code for currency format
- `isAllowed`: (values: { floatValue?: number; formattedValue: string; value: string }) => boolean — Optional guard executed before value is committed
- `startValue`: number = 0 — Value applied when stepping from an empty state
- `stepHoldDelay`: number = DEFAULT_STEP_DELAY — Delay before step-hold behaviour kicks in (ms)
- `stepHoldInterval`: number | ((stepCount: number) => number) = DEFAULT_STEP_INTERVAL — Interval or function controlling step-hold cadence
- `withKeyboardEvents`: boolean = true — ArrowUp / ArrowDown step the value (Shift multiplies by `shiftMultiplier`). Default true.
- `withControls`: boolean = false — Show increment/decrement buttons
- `withSideButtons`: boolean = false — Render horizontal decrement/increment buttons flanking the input
- `hideControlsOnMobile`: boolean = true — Whether to hide step controls on mobile
- `withDragGesture`: boolean = false — Enable press-drag gesture to adjust value
- `dragAxis`: 'horizontal' | 'vertical' = 'horizontal' — Axis that determines how drag gestures adjust the value
- `dragStepDistance`: number = DEFAULT_DRAG_STEP_DISTANCE — Pixel distance required to trigger a single step while dragging
- `dragStepMultiplier`: number = 1 — Multiplier applied to the configured step while dragging
- `onDragStateChange`: (isDragging: boolean) => void — Callback fired when the drag gesture activation state changes
- `formatter`: (value: number) => string — Custom formatter function
- `parser`: (value: string) => number — Custom parser function
- `clampBehavior`: 'strict' | 'blur' | 'none' = 'blur' — Clamp value to min/max bounds
- `allowEmpty`: boolean = true — Allow empty value
- `textInputProps`: ExtendedTextInputProps — Additional TextInput props
- `autoCapitalize`: RNTextInputProps['autoCapitalize'] — Text auto-capitalization behavior
- `autoCorrect`: boolean — Whether to enable auto-correct
- `autoFocus`: boolean — Whether to auto-focus on mount
- `returnKeyType`: RNTextInputProps['returnKeyType'] — Return key type for soft keyboard
- `blurOnSubmit`: boolean — Whether to blur on submit
- `selectTextOnFocus`: boolean — Select all text on focus
- `textContentType`: RNTextInputProps['textContentType'] — iOS text content type for autofill
- `textAlign`: RNTextInputProps['textAlign'] — Text alignment
- `spellCheck`: boolean — Whether spell check is enabled
- `inputMode`: RNTextInputProps['inputMode'] — Input mode (modern alternative to keyboardType)
- `enterKeyHint`: RNTextInputProps['enterKeyHint'] — Enter key hint
- `selectionColor`: string — Color of the text selection handles and highlight
- `showSoftInputOnFocus`: boolean — Whether to show the soft keyboard on focus
- `editable`: boolean — Passthrough to the TextInput. Prefer `readOnly`; `editable={false}` behaves the same.
- `incrementLabel`: string = 'Increase value' — Accessible names of the step buttons.
- `decrementLabel`: string = 'Decrease value'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `debounceMs` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Keep the number in state with `value` and `onChange`; `min` stops it from going below zero.

```tsx
import { useState } from 'react';
import { NumberInput } from '@plocks/ui';

export function Demo() {
  const [quantity, setQuantity] = useState<number | undefined>(2);

  return (
    <NumberInput
      label="Quantity"
      placeholder="Enter amount"
      value={quantity}
      onChange={setQuantity}
      min={0}
    />
  );
}
```

### Formats

Set `format` to `currency` or `percentage` to show the currency symbol or percent sign once the field loses focus; `decimalScale` with `fixedDecimalScale` pins the decimal places.

```tsx
import { Block, NumberInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <NumberInput
        label="List price"
        defaultValue={249.99}
        format="currency"
        decimalScale={2}
        fixedDecimalScale
      />
      <NumberInput
        label="Discount"
        defaultValue={10}
        format="percentage"
      />
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on NumberInput.

```tsx
import { Column, NumberInput } from '@plocks/ui';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <NumberInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Enter a quantity" />
      ))}
    </Column>
  );
}
```

### Side buttons

`withSideButtons` puts decrement and increment buttons on either side of the field. Hold Shift while pressing to step by `shiftMultiplier` (10 by default) for coarse adjustments.

```tsx
import { NumberInput } from '@plocks/ui';

export function Demo() {
  return (
    <NumberInput
      label="Playback speed"
      defaultValue={32}
      min={0}
      max={200}
      suffix="%"
      withSideButtons
    />
  );
}
```

### Drag gesture

Add `withDragGesture` to change the value by pressing and dragging across the field; `dragAxis` picks horizontal or vertical movement.

```tsx
import { Block, NumberInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <NumberInput
        label="Horizontal drag"
        defaultValue={32}
        withDragGesture
        dragAxis="horizontal"
      />
      <NumberInput
        label="Vertical drag"
        defaultValue={120}
        withDragGesture
        dragAxis="vertical"
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/OverflowList.md -->

# OverflowList

Items are measured offscreen before the list is shown. The overflow item receives the hidden entries.

## Metadata

- Import: `import { OverflowList } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/OverflowList
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/OverflowList

## Props

- `data` (required): readonly T[] — Items to fit.
- `renderItem` (required): (item: T, index: number) => React.ReactNode — Renders an item at its original index.
- `renderOverflow` (required): (hiddenItems: T[]) => React.ReactNode — Renders the item that replaces hidden entries.
- `gap`: SpacingValue = 'sm' — Space between items. @default 'sm'
- `maxRows`: number = 1 — Maximum lines before collapsing. @default 1
- `maxVisibleItems`: number — Hard cap on shown entries.
- `collapseFrom`: 'start' | 'end' = 'end' — Side from which entries disappear. @default 'end'
- `getItemKey`: (item: T, index: number) => React.Key — Stable key for each item.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Entries beyond the available width collapse into a single item.

```tsx
import { Badge, Block, OverflowList } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'];
export function Demo() {
  return (
    <Block fullWidth>
      <OverflowList
        maw={320}
        data={data}
        renderItem={(item) => <Badge>{item}</Badge>}
        renderOverflow={(hidden) => <Badge>+{hidden.length} more</Badge>}
      />
    </Block>
  );
}
```

### Multiple Rows

`maxRows` lets entries wrap before collapsing.

```tsx
import { Badge, Block, OverflowList } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry', 'Fig', 'Grape'];
export function Demo() {
  return (
    <Block fullWidth>
      <OverflowList
        maw={320}
        data={data}
        maxRows={2}
        renderItem={(item) => <Badge>{item}</Badge>}
        renderOverflow={(hidden) => <Badge>+{hidden.length} more</Badge>}
      />
    </Block>
  );
}
```

### Collapse From Start

`collapseFrom="start"` keeps the last entries visible, as in breadcrumbs.

```tsx
import { Badge, Block, OverflowList } from '@plocks/ui';

const data = ['Home', 'Library', 'Projects', 'Design', 'Components', 'Current'];
export function Demo() {
  return (
    <Block fullWidth>
      <OverflowList
        maw={320}
        data={data}
        collapseFrom="start"
        renderItem={(item) => <Badge>{item}</Badge>}
        renderOverflow={(hidden) => <Badge>+{hidden.length} more</Badge>}
      />
    </Block>
  );
}
```

### Max Visible Items

`maxVisibleItems` limits the count even when space remains.

```tsx
import { Badge, Block, OverflowList } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
export function Demo() {
  return (
    <Block fullWidth>
      <OverflowList
        data={data}
        maxVisibleItems={3}
        renderItem={(item) => <Badge>{item}</Badge>}
        renderOverflow={(hidden) => <Badge>+{hidden.length} more</Badge>}
      />
    </Block>
  );
}
```

### Overflow Details

The overflow item can reveal hidden entries in a HoverCard.

```tsx
import { Badge, Block, HoverCard, OverflowList, Text } from '@plocks/ui';

const data = ['Apple', 'Banana', 'Cherry', 'Date', 'Elderberry'];
export function Demo() {
  return (
    <Block fullWidth>
      <OverflowList
        maw={280}
        data={data}
        renderItem={(item) => <Badge>{item}</Badge>}
        renderOverflow={(hidden) => (
          <HoverCard target={<Badge>+{hidden.length} more</Badge>}>
            {hidden.map((item) => (
              <Text key={item}>{item}</Text>
            ))}
          </HoverCard>
        )}
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Overlay.md -->

# Overlay

Overlay dims or blurs content behind a foreground element.

## Metadata

- Import: `import { Overlay } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Overlay
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Overlay

## Props

- `color`: ThemeColor = theme.backgrounds.scrim — Background color for the overlay: a raw color, a palette token (`'primary'`, `'primary.6'`) or a `theme.backgrounds` / `theme.text` key.
- `opacity`: number — Opacity of the background color only — children stay opaque. Defaults to 0.6 with a `color`; without one, the theme scrim keeps its own alpha unless this is set.
- `backgroundOpacity`: number — Opacity applied to the background color; takes precedence over `opacity`.
- `gradient`: string — Web-only CSS gradient string. Falls back to `color` on native platforms.
- `blur`: number | string — Amount of backdrop blur (px number or CSS length). Web only.
- `radius`: RadiusValue — Corner radius for the overlay surface.
- `zIndex`: number — z-index applied to the overlay container. Defaults to 1 so the overlay covers its siblings wherever it is rendered, or the theme's `overlay` layer when `fixed`.
- `fixed`: boolean = false — Use viewport-fixed positioning instead of absolute positioning (web only).
- `center`: boolean = false — Center children horizontally and vertically.
- `style`: StyleProp<ViewStyle> — Optional style overrides applied after computed styles.
- `children`: ReactNode — Overlay content rendered on top of the dimmed background.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.

Also accepts the shared props — base (`testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Overlay fills its parent: dim it with `color` and `backgroundOpacity`, fade it with a CSS `gradient`, or frost it with `blur` (gradient and blur are web-only). Children render on top at full strength.

```tsx
import { ImageBackground, StyleSheet } from 'react-native';
import { Block, Overlay, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth maw={520}>
      <ImageBackground source={require('../../../../assets/images/scene-city.png')} style={styles.image} imageStyle={styles.backgroundImage}>
        <Overlay color="#000" backgroundOpacity={0.5} center>
          <Text fw="semibold" c="white">
            Dim
          </Text>
        </Overlay>
      </ImageBackground>

      <ImageBackground source={require('../../../../assets/images/scene-aurora.png')} style={styles.image} imageStyle={styles.backgroundImage}>
        <Overlay gradient="linear-gradient(145deg, rgba(0, 0, 0, 0.95) 0%, rgba(0, 0, 0, 0) 75%)" center>
          <Text fw="semibold" c="white">
            Gradient
          </Text>
        </Overlay>
      </ImageBackground>

      <ImageBackground source={require('../../../../assets/images/scene-desert.png')} style={styles.image} imageStyle={styles.backgroundImage}>
        <Overlay color="#000" backgroundOpacity={0.35} blur={18} center>
          <Text fw="semibold" c="white">
            Blur
          </Text>
        </Overlay>
      </ImageBackground>
    </Block>
  );
}

const styles = StyleSheet.create({
  image: {
    width: '100%',
    aspectRatio: 3 / 2,
    borderRadius: 24,
    overflow: 'hidden',
  },
  backgroundImage: {
    width: '100%',
    height: '100%',
  },
});
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Pagination.md -->

# Pagination

Pagination provides controls for moving through pages of content.

## Metadata

- Import: `import { Pagination } from '@plocks/ui';`
- Tags: pagination, navigation, pages, data
- Docs: https://plocks.dev/components/Pagination
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Pagination

## Props

- `value`: number — Current page number (1-indexed). Controlled.
- `defaultValue`: number = 1 — Initial page when uncontrolled. @default 1
- `total` (required): number — Total number of pages
- `siblings`: number = 1 — Number of page items to show on each side of current page
- `boundaries`: number = 1 — Number of page items to show at the boundaries
- `onChange`: (page: number) => void — Called with the new page number (1-indexed).
- `size`: SizeValue = 'md' — Size of the pagination controls. Page items are compact controls: they render one step below `size` on the shared control scale.
- `variant`: 'default' | 'outline' | 'subtle' = 'default' — Variant style
- `color`: ColorProp = 'primary' — Accent color of the current page: a palette name (`'primary'`), a shade (`'primary.6'`) or any CSS color.
- `showFirst`: boolean = true — Show first/last page buttons
- `showPrevNext`: boolean = true — Show previous/next buttons
- `labels`: { first?: ReactNode; previous?: ReactNode; next?: ReactNode; last?: ReactNode; } — Custom visible content for the navigation buttons (defaults to chevron icons).
- `accessibilityLabels`: PaginationAccessibilityLabels — Accessible names for the landmark and controls (for translation).
- `disabled`: boolean = false — Whether pagination is disabled
- `buttonStyle`: StyleProp<ViewStyle> — Custom button styles
- `activeButtonStyle`: StyleProp<ViewStyle> — Custom active button styles
- `textStyle`: StyleProp<TextStyle> — Custom text styles
- `activeTextStyle`: StyleProp<TextStyle> — Custom active text styles
- `hideOnSinglePage`: boolean = false — Hide pagination when there's only one page
- `showSizeChanger`: boolean = false — Show page size selector
- `pageSizeOptions`: number[] = [10, 20, 50, 100] — Available page sizes
- `pageSize`: number = 10 — Current page size
- `onPageSizeChange`: (size: number) => void — Page size change handler
- `showTotal`: boolean | ((total: number, range: [number, number]) => ReactNode) = false — Show total count
- `totalItems`: number — Total number of items
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to every page-button label `<Text>` (style, fw, ff, size, c).
- `activeLabelProps`: Omit<TextProps, 'children'> — Override props applied to the active page-button label `<Text>` (merged on top of `labelProps`).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface PaginationAccessibilityLabels {
  /** Label of the `navigation` landmark. @default 'Pagination' */
  root?: string;
  /** @default 'First page' */
  first?: string;
  /** @default 'Previous page' */
  previous?: string;
  /** @default 'Next page' */
  next?: string;
  /** @default 'Last page' */
  last?: string;
  /** Name of a page button. @default (page) => `Page ${page}` */
  page?: (page: number) => string;
}
```

## Examples

### Basics

Provide `value`, `total`, and an `onChange` handler to keep numbered pagination in sync with surrounding state.

```tsx
import { useState } from 'react';

import { Block, Pagination, Text } from '@plocks/ui';

export function Demo() {
  const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 10;

  return (
    <Block>
      <Pagination value={currentPage} total={totalPages} onChange={setCurrentPage} />
      <Text size="xs" c="secondary">
        Page {currentPage} of {totalPages}
      </Text>
    </Block>
  );
}
```

### Variants

Switch the `variant` prop between `default`, `outline`, and `subtle` to align pagination with the surrounding surface treatment.

```tsx
import { useState } from 'react';

import { Block, Pagination, Text } from '@plocks/ui';

export function Demo() {
  const [defaultPage, setDefaultPage] = useState(5);
  const [outlinePage, setOutlinePage] = useState(5);
  const [subtlePage, setSubtlePage] = useState(5);

  return (
    <Block>
      <Block>
        <Pagination value={defaultPage} total={15} onChange={setDefaultPage} variant="default" />
        <Text size="xs" c="secondary">
          Default variant keeps the control fully filled. Page {defaultPage} of 15.
        </Text>
      </Block>

      <Block>
        <Pagination value={outlinePage} total={15} onChange={setOutlinePage} variant="outline" />
        <Text size="xs" c="secondary">
          Outline keeps the surface quiet while the active page gets a stroke. Page {outlinePage} of 15.
        </Text>
      </Block>

      <Block>
        <Pagination value={subtlePage} total={15} onChange={setSubtlePage} variant="subtle" />
        <Text size="xs" c="secondary">
          Subtle removes backgrounds for tinted surfaces. Page {subtlePage} of 15.
        </Text>
      </Block>
    </Block>
  );
}
```

### Sizes

Use the `size` prop (`xs` through `3xl`) to match pagination density to its container without changing behavior.

```tsx
import { useState } from 'react';
import { Block, Pagination, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  const [page, setPage] = useState(3);

  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" c="secondary">{size}</Text>
          <Pagination value={page} total={8} onChange={setPage} size={size} />
        </Block>
      ))}
    </Block>
  );
}
```

### Advanced

Combine `showFirst`, `showPrevNext`, `siblings`, and `boundaries` to reveal the right amount of context for long result sets.

```tsx
import { useState } from 'react';

import { Block, Pagination, Text } from '@plocks/ui';

export function Demo() {
  const [page1, setPage1] = useState(10);
  const [page2, setPage2] = useState(15);
  const [page3, setPage3] = useState(25);

  return (
    <Block>
      <Block>
        <Pagination
          value={page1}
          total={30}
          onChange={setPage1}
          showFirst
          showPrevNext
          siblings={2}
          boundaries={2}
        />
        <Text size="xs" c="secondary">
          Includes first and last buttons. Page {page1} of 30.
        </Text>
      </Block>

      <Block>
        <Pagination
          value={page2}
          total={40}
          onChange={setPage2}
          showPrevNext
          siblings={1}
          boundaries={1}
        />
        <Text size="xs" c="secondary">
          Minimal navigation with prev/next only. Page {page2} of 40.
        </Text>
      </Block>

      <Block>
        <Pagination
          value={page3}
          total={50}
          onChange={setPage3}
          showPrevNext
          siblings={0}
          boundaries={1}
          size="sm"
        />
        <Text size="xs" c="secondary">
          Compact layout with tight siblings. Page {page3} of 50.
        </Text>
      </Block>
    </Block>
  );
}
```

### Total & size changer

Set `showTotal` with `totalItems` to render an "X-Y of N" summary, and `showSizeChanger` with `pageSizeOptions` / `onPageSizeChange` to let users change the rows-per-page. This is the same footer the `DataTable` renders internally.

```tsx
import { useState } from 'react';

import { Block, Pagination, Text } from '@plocks/ui';

export function Demo() {
  const totalItems = 248;
  const [pageSize, setPageSize] = useState(10);
  const [current, setCurrent] = useState(1);

  const total = Math.max(1, Math.ceil(totalItems / pageSize));

  return (
    <Block>
      <Pagination
        value={current}
        total={total}
        onChange={setCurrent}
        showTotal
        totalItems={totalItems}
        pageSize={pageSize}
        showSizeChanger
        pageSizeOptions={[10, 20, 50, 100]}
        onPageSizeChange={(size) => {
          setPageSize(size);
          setCurrent(1);
        }}
      />
      <Text size="xs" c="secondary">
        Page {current} of {total} · {pageSize} rows per page
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/PhoneInput.md -->

# PhoneInput

The `PhoneInput` component provides a flexible way to capture telephone numbers with built-in masking and formatting.

## Metadata

- Import: `import { PhoneInput } from '@plocks/ui';`
- Tags: phone, input, mask, formatting, international
- Docs: https://plocks.dev/components/PhoneInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/PhoneInput

## Props

- `id`: string — Id of the TextInput; label/error ids derive from it. Generated when omitted.
- `value`: string — Phone number value (digits only). Omit for an uncontrolled field.
- `defaultValue`: string — Initial value while uncontrolled.
- `onChange`: (raw: string, formatted: string, meta: PhoneChangeMeta) => void — Change handler receiving (nationalDigits, formattedDisplay, meta)
- `country`: PhoneCountryCode — Country preset to format against. Controlled when provided.
- `defaultCountry`: PhoneCountryCode = 'US' — Initial country while uncontrolled. Defaults to 'US'.
- `onCountryChange`: (country: PhoneCountryCode) => void — Called when the country changes (via the picker, or `autoDetect`).
- `selectableCountry`: boolean = false — Render the dial code as a dropdown so the user can change country.
- `autoDetect`: boolean = false — Switch country when the user types or pastes an explicit `+<dial code>` prefix. Off by default: it changes the mask out from under the caller's `country` prop. The active country's own dial code is stripped either way, so pasting a full local number never truncates it. A *foreign* dial code is only stripped when `autoDetect` lets us switch to that country — otherwise the digits would be re-filed under the active country, turning `+447911123456` into `+17911123456`.
- `showCountryCode`: boolean = true — Show the dial code prefix ahead of the field
- `mask`: string — Custom mask pattern (overrides the country mask). Use '0' for digits, any other character as a literal. Avoid literal digits — see `PhoneFormat.mask`.
- `textInputProps`: ExtendedTextInputProps — Additional props forwarded to the underlying TextInput.
- `countryPickerLabel`: (countryName: string) => string = defaultCountryPickerLabel — Accessible name of the country picker button (`selectableCountry`); receives the country name.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `debounceMs` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface PhoneChangeMeta {
  /** The resolved country the value is formatted for. */
  country: PhoneCountryCode;
  /** Dial code for that country (e.g. '+1'). Empty for the international format. */
  dialCode: string;
  /** Submittable E.164 value (e.g. '+15551234567'), or '' while empty. */
  e164: string;
  /** Whether every digit the mask expects has been entered. */
  isComplete: boolean;
}

export type PhoneCountryCode =
  | 'US'
  | 'CA'
  | 'GB'
  | 'FR'
  | 'DE'
  | 'AU'
  | 'BR'
  | 'IN'
  | 'JP'
  | 'INTL'
  | (string & {});
```

## Examples

### Basics

Controlled PhoneInput example that surfaces both raw digits and the formatted display.

```tsx
import { useState } from 'react';

import { Block, PhoneInput, Text } from '@plocks/ui';

export function Demo() {
  const [raw, setRaw] = useState('');
  const [formatted, setFormatted] = useState('');

  return (
    <Block fullWidth>
      <PhoneInput
        label="Phone number"
        value={raw}
        onChange={(rawDigits, formattedDisplay) => {
          setRaw(rawDigits);
          setFormatted(formattedDisplay);
        }}
      />
      <Text size="sm">
        Raw: {raw || '—'} · Formatted: {formatted || '—'}
      </Text>
    </Block>
  );
}
```

### International

With `autoDetect`, typing or pasting a `+` dial code switches the country and mask to match. The second field uses the catch-all `country="INTL"` format instead.

```tsx
import { Block, PhoneInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <PhoneInput
        label="Auto-detect from a + prefix"
        autoDetect
        placeholder="Try +447911123456 or +33123456789"
      />
      <PhoneInput
        label="Manual international"
        country="INTL"
        placeholder="Enter any international number"
      />
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on PhoneInput.

```tsx
import { Column, PhoneInput } from '@plocks/ui';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <PhoneInput key={variant} variant={variant} label={`${variant} variant`} placeholder="(555) 123-4567" />
      ))}
    </Column>
  );
}
```

### Country Picker

Set `selectableCountry` to turn the dial-code prefix into a country picker. Switching country remasks the digits already entered instead of clearing them.

```tsx
import { Block, PhoneInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <PhoneInput label="Phone number" selectableCountry defaultValue="5551234567" />
    </Block>
  );
}
```

### Country Formats

Pass `country` to format against a built-in preset, each with its own localized mask and dial code.

```tsx
import { Block, PhoneInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <PhoneInput label="United States" country="US" />
      <PhoneInput label="United Kingdom" country="GB" />
      <PhoneInput label="France" country="FR" />
      <PhoneInput label="Brazil" country="BR" />
    </Block>
  );
}
```

### Mask Visibility

Set `showCountryCode={false}` to hide the dial-code prefix; the raw digits reported by `onChange` stay the same.

```tsx
import { Block, PhoneInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <PhoneInput label="With country code" />
      <PhoneInput label="Without country code" showCountryCode={false} />
    </Block>
  );
}
```

### Validation

Length-based validation for US and international formats with inline messaging.

```tsx
import { useState } from 'react';

import { Block, PhoneInput } from '@plocks/ui';

export function Demo() {
  const [usRaw, setUsRaw] = useState('');
  const [internationalRaw, setInternationalRaw] = useState('');

  const isValidUs = usRaw.length === 10;
  const isValidInternational = internationalRaw.length >= 7 && internationalRaw.length <= 15;

  return (
    <Block fullWidth>
      <PhoneInput
        label="US phone (10 digits required)"
        value={usRaw}
        onChange={(raw) => setUsRaw(raw)}
        error={usRaw.length > 0 && !isValidUs ? 'Enter a 10-digit US phone number' : undefined}
      />
      <PhoneInput
        label="International phone (7-15 digits)"
        country="INTL"
        value={internationalRaw}
        onChange={(raw) => setInternationalRaw(raw)}
        error={
          internationalRaw.length > 0 && !isValidInternational
            ? 'International numbers should be 7-15 digits'
            : undefined
        }
      />
    </Block>
  );
}
```

### Advanced Masking

Custom mask patterns for international formats and extension fields.

```tsx
import { Block, PhoneInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <PhoneInput
        label="International format"
        mask="+00 (000) 000-0000"
        showCountryCode={false}
        placeholder="+44 (791) 112-3456"
      />
      <PhoneInput
        label="North America with extension"
        mask="000-000-0000 x0000"
        showCountryCode={false}
        placeholder="555-123-4567 x1234"
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/PinInput.md -->

# PinInput

PinInput provides a sequence of fields for entering a PIN or verification code.

## Metadata

- Import: `import { PinInput } from '@plocks/ui';`
- Tags: pin, otp, security, input, verification
- Docs: https://plocks.dev/components/PinInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/PinInput

## Props

- `length`: number = 4 — Number of cells. Default 4.
- `value`: string — PIN value (controlled).
- `defaultValue`: string = '' — Initial value (uncontrolled).
- `onChange`: (pin: string) => void — Called with the whole PIN on every change.
- `onComplete`: (pin: string) => void — Called once when the PIN becomes complete (all cells filled) — not again on re-renders; again only after it was incomplete in between or a digit changed.
- `mask`: boolean = false — Mask the characters.
- `maskChar`: string = '•' — Character shown for a masked cell. Default `'•'`.
- `manageFocus`: boolean = true — Move focus to the next cell as each character is typed. Default true.
- `enforceOrderInitialOnly`: boolean = false — Sequential entry (focusing a later cell jumps back to the first empty one) is always enforced by default. With `enforceOrderInitialOnly`, it only applies until the PIN has been complete once; after that any cell can be edited directly.
- `type`: 'alphanumeric' | 'numeric' = 'numeric' — Accepted characters. Default `'numeric'`.
- `placeholder`: string = '' — Placeholder shown in each empty cell.
- `allowPaste`: boolean = true — Allow pasting a whole code into a cell. Default true.
- `oneTimeCode`: boolean = false — Offer SMS one-time-code autofill.
- `spacing`: number = 8 — Gap between cells (px). Default 8.
- `textInputProps`: Omit< TextInputProps, 'value' | 'defaultValue' | 'onChangeText' | 'onFocus' | 'onBlur' | 'style' | 'testID' | 'placeholder' | 'editable' > — Extra TextInput props for every cell.
- `autoCapitalize`: TextInputProps['autoCapitalize'] — Text auto-capitalization behavior.
- `autoCorrect`: boolean — Whether to enable auto-correct.
- `autoFocus`: boolean — Focus the first cell on mount.
- `selectTextOnFocus`: boolean — Select a cell's text on focus. Default true.
- `textContentType`: TextInputProps['textContentType'] — iOS text content type for autofill.
- `textAlign`: TextInputProps['textAlign'] = 'center' — Text alignment inside each cell. Default centered.
- `spellCheck`: boolean — Whether spell check is enabled.
- `selectionColor`: string — Color of the selection handles and highlight.
- `showSoftInputOnFocus`: boolean — Show the soft keyboard on focus.
- `id`: string — Base id: the cell group gets it, the label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Controlled 4-digit PIN input with automatic focus handoff between cells.

```tsx
import { useState } from 'react';
import { PinInput } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState('');

  return <PinInput value={value} onChange={setValue} label="PIN code" />;
}
```

### Types

Contrast numeric-only PIN entry with an alphanumeric option for recovery codes.

```tsx
import { Block, PinInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <PinInput type="numeric" label="Numeric" />
      <PinInput type="alphanumeric" label="Alphanumeric" />
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on PinInput.

```tsx
import { Column, PinInput } from '@plocks/ui';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <PinInput key={variant} variant={variant} label={`${variant} variant`} />
      ))}
    </Column>
  );
}
```

### Sizes

Compare the `size` prop from `xs` through `lg`.

```tsx
import { Block, PinInput } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg'] as const;

export function Demo() {
  return (
    <Block>
      {SIZES.map((size) => (
        <PinInput key={size} size={size} label={size} />
      ))}
    </Block>
  );
}
```

### Lengths

Compare 4, 6, and 8-digit PIN inputs tailored for common authentication flows.

```tsx
import { Block, PinInput } from '@plocks/ui';

const LENGTHS = [4, 6, 8];

export function Demo() {
  return (
    <Block>
      {LENGTHS.map((length) => (
        <PinInput key={length} length={length} label={`${length} digits`} />
      ))}
    </Block>
  );
}
```

### Security

Conceal digits with `mask`, offer SMS code autofill with `oneTimeCode`, and show inline validation messages through `error`.

```tsx
import { Block, PinInput } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <PinInput mask defaultValue="1234" label="Masked" />
      <PinInput oneTimeCode length={6} label="One-time code" />
      <PinInput defaultValue="1289" error="Incorrect PIN. Try again." label="Validation" />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Popover.md -->

# Popover

Popover sits on the same overlay primitives as Menu and Tooltip, making it suitable for interactive content like forms, lists, and quick action menus while keeping focus management predictable.

## Metadata

- Import: `import { Popover } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Popover
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Popover

## Props

- `children` (required): ReactNode
- `opened`: boolean — Controlled open state
- `defaultOpened`: boolean = false — Initial open state in uncontrolled mode
- `onChange`: (opened: boolean) => void — Called when open state changes
- `onOpen`: () => void — Called when popover opens
- `onClose`: () => void — Called when popover closes
- `onDismiss`: () => void — Called when popover is dismissed via outside click or escape
- `trigger`: 'click' | 'hover' = 'click' — How the popover is triggered: 'click' (default) or 'hover' (mostly useful for devices with a mouse)
- `disabled`: boolean = false — Disable popover entirely
- `closeOnClickOutside`: boolean = true — Close when clicking outside
- `closeOnEscape`: boolean = true — Close when pressing Escape (web) or the Android back button. Only the topmost open overlay closes, so Escape in a nested popover closes just that one.
- `trapFocus`: boolean = false — Trap focus within the dropdown (web): focus moves to its first focusable element on open and Tab / Shift+Tab cycle inside it until it closes. Without it, a click-opened dropdown still receives focus (on the dropdown itself) so keyboard users can Tab into it.
- `keepMounted`: boolean = false — Keep dropdown mounted when hidden
- `returnFocus`: boolean = true — Return focus to the target after close (when focus was inside the dropdown — closing by clicking elsewhere never steals focus back).
- `w`: number | 'target' — Dropdown width, number or 'target' to match target width
- `maw`: number — Dropdown max-width
- `mah`: number — Dropdown max-height
- `miw`: number — Dropdown min-width
- `mih`: number — Dropdown min-height
- `radius`: RadiusValue | number — Border radius
- `shadow`: ShadowValue — Box shadow
- `zIndex`: number = the theme's `popover` layer (`getZIndex(theme, 'popover')`) — Dropdown z-index. @default the theme's `popover` layer (`getZIndex(theme, 'popover')`)
- `position`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom' — Popover position relative to target, written for left-to-right layouts: in RTL `left`/`right` and the `-start`/`-end` of `top`/`bottom` are mirrored.
- `offset`: number | { mainAxis?: number; crossAxis?: number } = 8 — Offset from target
- `floatingStrategy`: 'absolute' | 'fixed' = 'fixed' — Floating strategy for positioning
- `middlewares`: PopoverMiddlewares — Custom positioning options
- `preventPositionChangeWhenVisible`: boolean = false — Prevent flipping/shifting when visible
- `viewport`: PositioningOptions['viewport'] — Override viewport padding
- `keyboardAvoidance`: boolean = true — Whether positioning should avoid the on-screen keyboard
- `fallbackPlacements`: PlacementType[] — Override fallback placements
- `boundary`: number — Override boundary padding
- `withRoles`: boolean = true — Render ARIA roles
- `id`: string — Unique id base for accessibility
- `withArrow`: boolean = false — Render arrow
- `arrowSize`: number = DEFAULT_ARROW_SIZE — Arrow size
- `arrowRadius`: number = 0 — Arrow border radius
- `arrowOffset`: number = 5 — Arrow offset
- `arrowPosition`: 'center' | 'side' = 'center' — Arrow position for start/end placements
- `onPositionChange`: (placement: PlacementType) => void — Called when the dropdown's physical placement changes (after flipping / RTL mirroring)
- `h`: DimensionProp — Height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### Popover.Dropdown

- `children` (required): ReactNode
- `role`: ViewProps['role'] = 'dialog' — ARIA role of the dropdown; the target's `aria-controls` points at it. @default 'dialog'
- `trapFocus`: boolean — Whether dropdown content should trap focus (web only); same as Popover's `trapFocus`
- `keepMounted`: boolean — Keep dropdown mounted

### Popover.Target

- `children` (required): ReactElement
- `popupType`: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid'
- `refProp`: string
- `targetProps`: Record<string, unknown> — Additional props merged onto target

## Types

```ts
export interface PopoverMiddlewares {
  flip?: boolean | { padding?: number };
  shift?: boolean | { padding?: number };
  inline?: boolean;
}
```

## Examples

### Basics

Popover targets wrap an interactive element and render dropdown content within `Popover.Dropdown`.

```tsx
import { Block, Button, Popover, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Popover>
      <Popover.Target>
        <Button>
          Toggle popover
        </Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Block p="sm">
          <Text fw="semibold">Quick actions</Text>
          <Button size="xs" variant="ghost">
            Create new entry
          </Button>
          <Button size="xs" variant="ghost">
            View documentation
          </Button>
        </Block>
      </Popover.Dropdown>
    </Popover>
  );
}
```

### Hover Trigger

Set `trigger="hover"` to open the popover when the user hovers over the target element. This is useful for mouse users who want quick access to additional content without clicking.

```tsx
import { Block, Button, Popover, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Popover trigger="hover">
      <Popover.Target>
        <Button>
          Hover over me
        </Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Block p="sm">
          <Text fw="semibold">Hover popover</Text>
        </Block>
      </Popover.Dropdown>
    </Popover>
  );
}
```

### Controlled State

Control the `opened` prop and respond to `onChange` when the popover needs to sync with surrounding form state.

```tsx
import { useState } from 'react';
import { Block, Button, Checkbox, Input, Popover, Text } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);

  return (
    <Block>
      <Checkbox
        label="Show popover"
        checked={opened}
        onChange={setOpened}
      />
      <Popover opened={opened} onChange={setOpened}>
        <Popover.Target>
          <Button>
            Invite teammate
          </Button>
        </Popover.Target>
        <Popover.Dropdown>
          <Block p="sm">
            <Text fw="semibold">Invite team member</Text>
            <Input
              label="Email"
              placeholder="name@example.com"
              size="sm"
              fullWidth
            />
            <Button size="xs" onPress={() => setOpened(false)}>
              Send invite
            </Button>
          </Block>
        </Popover.Dropdown>
      </Popover>
    </Block>
  );
}
```

### Placement Options

Set the `position` prop to control where the dropdown renders relative to its trigger.

```tsx
import { Button, Block, Popover, Text } from '@plocks/ui';

const OPTIONS = [
  { label: 'Top', position: 'top' },
  { label: 'Right', position: 'right' },
  { label: 'Bottom', position: 'bottom' },
  { label: 'Left', position: 'left' },
] as const;

export function Demo() {
  return (
    <Block direction="row">
      {OPTIONS.map(({ label, position }) => (
        <Popover key={position} position={position} withArrow>
          <Popover.Target>
            <Button>
              {label}
            </Button>
          </Popover.Target>
          <Popover.Dropdown>
            <Block p="sm">
              <Text fw="semibold">{label} placement</Text>
            </Block>
          </Popover.Dropdown>
        </Popover>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Progress.md -->

# Progress

The Progress component displays the completion progress of a task or process. Supports different variants, colors, and animations.

## Metadata

- Import: `import { Progress } from '@plocks/ui';`
- Tags: progress, loading, status, indicator, completion, segments, vertical
- Docs: https://plocks.dev/components/Progress
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Progress

## Props

- `value` (required): number — Completion, 0–100 (clamped).
- `size`: SizeValue = 'md' — Bar thickness: a control-size token (`getControlSize(theme, size).height`) or pixels. @default 'md'
- `color`: ThemeColor = 'primary' — Fill color: palette token, `'primary.6'` shade syntax, or any CSS color. @default 'primary'
- `radius`: RadiusValue = 'md' — Corner radius: theme radius token, px, `'none'` or `'full'`. @default 'md'
- `striped`: boolean = false
- `animate`: boolean = false — Animates the stripes. Requires `striped`. Off while reduced motion is on.
- `transitionDuration`: number = 0 — Animate fill changes over this many ms. `0` (and reduced motion) jumps straight to the value. @default 0
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Axis the bar fills along. Vertical bars fill bottom-up. @default 'horizontal'
- `length`: number | `${number}%` — Length along the main axis. Vertical bars default to 160.
- `trackColor`: string — Track (unfilled) color. Defaults to the theme's `backgrounds.border`.
- `aria-label`: string — Accessible name. Defaults to the `label` (web: by reference).
- `aria-valuetext`: string — Spoken value text, e.g. `"3 of 8 files"`. Defaults to the percentage.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `label`: React.ReactNode — Label rendered outside the track. Strings are styled; nodes render as-is.
- `description`: React.ReactNode — Helper text ("sublabel") rendered directly beneath the label. Hidden while `error` is set.
- `error`: React.ReactNode — Error message rendered below the bar (announced politely). Replaces `description` when present.
- `required`: boolean = false — Marks the field as required, rendering an asterisk beside the label. @default false
- `withAsterisk`: boolean = true — Whether the required marker is drawn. @default true
- `labelPosition`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Placement of the label block relative to the bar. @default 'top'
- `labelGap`: SizeValue = 'xs' — Gap between the label block and the bar — a theme spacing token or pixel value. @default 'xs'
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>`
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the description `<Text>`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ProgressRoot, ProgressSection, ProgressLabel } from '@plocks/ui';`

### ProgressRoot

- `size`: SizeValue = 'md' — Bar thickness: a control-size token or pixels. @default 'md'
- `radius`: RadiusValue = 'md' — Corner radius of the track. @default 'md'
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Axis sections fill along. Vertical roots stack sections bottom-up. @default 'horizontal'
- `length`: number | `${number}%` — Length along the main axis. Vertical roots default to 160.
- `trackColor`: string — Track (unfilled) color. Defaults to the theme's `backgrounds.border`.
- `transitionDuration`: number — Default `transitionDuration` for child sections.
- `children` (required): React.ReactNode
- `aria-label`: string — Accessible name of the group of sections. Defaults to the `label`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `label`: React.ReactNode — Label rendered outside the track. Strings are styled; nodes render as-is.
- `description`: React.ReactNode — Helper text ("sublabel") rendered directly beneath the label. Hidden while `error` is set.
- `error`: React.ReactNode — Error message rendered below the bar (announced politely). Replaces `description` when present.
- `required`: boolean = false — Marks the field as required, rendering an asterisk beside the label. @default false
- `withAsterisk`: boolean = true — Whether the required marker is drawn. @default true
- `labelPosition`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Placement of the label block relative to the bar. @default 'top'
- `labelGap`: SizeValue = 'xs' — Gap between the label block and the bar — a theme spacing token or pixel value. @default 'xs'
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>`
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the description `<Text>`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ProgressSection

- `value` (required): number — This section's share of the track, 0–100 (clamped).
- `color`: ThemeColor
- `striped`: boolean — Diagonal stripe overlay, matching `Progress`'s `striped`.
- `animate`: boolean — Animates the stripes. Requires `striped`. Off while reduced motion is on.
- `transitionDuration`: number — Animate size changes over this many ms. Inherited from `Progress.Root`.
- `radius`: RadiusValue — Rounds this section's own corners. Sections are square by default.
- `tooltip`: TooltipPropValue — Tooltip shown on hover/focus/tap, rendered inside the section. Prefer this over wrapping the section in `Tooltip` yourself: the wrapper would become the flex item and collapse the section's percentage width. Pass a string for the common case, or a config object to tune the tooltip: `tooltip={{ label: 'Documents — 35%', position: 'bottom' }}`.
- `aria-label`: string — Accessible name. Defaults to the tooltip text.
- `aria-valuetext`: string — Spoken value text. Defaults to the percentage.
- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `onPress`: () => void
- `onHoverIn`: () => void
- `onHoverOut`: () => void
- `onMouseEnter`: (event: WebMouseEvent) => void — Web only. Forwarded for wrappers (e.g. `Tooltip`) that attach mouse handlers; prefer `onHoverIn`.
- `onMouseLeave`: (event: WebMouseEvent) => void — Web only. Forwarded for wrappers (e.g. `Tooltip`) that attach mouse handlers; prefer `onHoverOut`.
- `onFocus`: () => void
- `onBlur`: () => void

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ProgressLabel

- `children` (required): React.ReactNode
- `color`: string — Label color. Defaults to a color readable on the enclosing section's fill.
- `size`: SizeValue = 'sm' — Font size token or px. @default 'sm'
- `numberOfLines`: number
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Progress.Label

- `children` (required): React.ReactNode
- `color`: string — Label color. Defaults to a color readable on the enclosing section's fill.
- `size`: SizeValue = 'sm' — Font size token or px. @default 'sm'
- `numberOfLines`: number
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Progress.Root

- `size`: SizeValue = 'md' — Bar thickness: a control-size token or pixels. @default 'md'
- `radius`: RadiusValue = 'md' — Corner radius of the track. @default 'md'
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Axis sections fill along. Vertical roots stack sections bottom-up. @default 'horizontal'
- `length`: number | `${number}%` — Length along the main axis. Vertical roots default to 160.
- `trackColor`: string — Track (unfilled) color. Defaults to the theme's `backgrounds.border`.
- `transitionDuration`: number — Default `transitionDuration` for child sections.
- `children` (required): React.ReactNode
- `aria-label`: string — Accessible name of the group of sections. Defaults to the `label`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `label`: React.ReactNode — Label rendered outside the track. Strings are styled; nodes render as-is.
- `description`: React.ReactNode — Helper text ("sublabel") rendered directly beneath the label. Hidden while `error` is set.
- `error`: React.ReactNode — Error message rendered below the bar (announced politely). Replaces `description` when present.
- `required`: boolean = false — Marks the field as required, rendering an asterisk beside the label. @default false
- `withAsterisk`: boolean = true — Whether the required marker is drawn. @default true
- `labelPosition`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Placement of the label block relative to the bar. @default 'top'
- `labelGap`: SizeValue = 'xs' — Gap between the label block and the bar — a theme spacing token or pixel value. @default 'xs'
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>`
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the description `<Text>`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Progress.Section

- `value` (required): number — This section's share of the track, 0–100 (clamped).
- `color`: ThemeColor
- `striped`: boolean — Diagonal stripe overlay, matching `Progress`'s `striped`.
- `animate`: boolean — Animates the stripes. Requires `striped`. Off while reduced motion is on.
- `transitionDuration`: number — Animate size changes over this many ms. Inherited from `Progress.Root`.
- `radius`: RadiusValue — Rounds this section's own corners. Sections are square by default.
- `tooltip`: TooltipPropValue — Tooltip shown on hover/focus/tap, rendered inside the section. Prefer this over wrapping the section in `Tooltip` yourself: the wrapper would become the flex item and collapse the section's percentage width. Pass a string for the common case, or a config object to tune the tooltip: `tooltip={{ label: 'Documents — 35%', position: 'bottom' }}`.
- `aria-label`: string — Accessible name. Defaults to the tooltip text.
- `aria-valuetext`: string — Spoken value text. Defaults to the percentage.
- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `onPress`: () => void
- `onHoverIn`: () => void
- `onHoverOut`: () => void
- `onMouseEnter`: (event: WebMouseEvent) => void — Web only. Forwarded for wrappers (e.g. `Tooltip`) that attach mouse handlers; prefer `onHoverIn`.
- `onMouseLeave`: (event: WebMouseEvent) => void — Web only. Forwarded for wrappers (e.g. `Tooltip`) that attach mouse handlers; prefer `onHoverOut`.
- `onFocus`: () => void
- `onBlur`: () => void

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Track a single completion percentage. Set `transitionDuration` so the bar animates its width whenever `value` changes instead of snapping to it.

```tsx
import { useState } from 'react';
import { Block, Button, Progress } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(50);

  return (
    <Block fullWidth>
      <Progress value={value} transitionDuration={400} />
      <Button onPress={() => setValue(Math.round(Math.random() * 100))}>Randomize value</Button>
    </Block>
  );
}
```

### Label and description

Progress takes the same field props as the input components: `label`, `description` (the sublabel beneath it), `error`, `required`, and `labelPosition`. The block renders outside the track — use `Progress.Label` for text drawn *inside* a filled section.

```tsx
import { Block, Progress } from '@plocks/ui';

export function Demo() {
  return (
    <Block gap="lg" fullWidth>
      <Progress value={64} label="Uploading assets" description="12 of 18 files" />

      <Progress
        value={40}
        color="error"
        label="Sync"
        description="Retries every 30 seconds"
        error="Connection lost — retrying"
      />

      <Progress value={82} label="Storage" required labelPosition="left" color="success" />

      <Progress.Root label="Disk usage" description="Documents, photos, and system files">
        <Progress.Section value={35} color="primary" />
        <Progress.Section value={28} color="success" />
        <Progress.Section value={12} color="warning" />
      </Progress.Root>
    </Block>
  );
}
```

### Advanced

Combine `striped` and `animate` to represent indeterminate work.

```tsx
import { Block, Progress } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Progress value={100} striped animate />
    </Block>
  );
}
```

### Compound sections

Compose a multi-part bar from `Progress.Root`, `Progress.Section`, and `Progress.Label`. Each section is sized as a percentage of the track, so sections may sum to less than 100% and leave the remainder unfilled.

```tsx
import { Block, Progress } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Progress.Root>
        <Progress.Section value={35} color="primary">
          <Progress.Label>Docs</Progress.Label>
        </Progress.Section>
        <Progress.Section value={28} color="success">
          <Progress.Label>Media</Progress.Label>
        </Progress.Section>
        <Progress.Section value={15} color="warning">
          <Progress.Label>Other</Progress.Label>
        </Progress.Section>
      </Progress.Root>
    </Block>
  );
}
```

### With tooltips

```tsx
import { Block, Progress } from '@plocks/ui';

const SECTIONS = [
  { label: 'Documents', value: 34, color: 'primary' as const },
  { label: 'Photos', value: 26, color: 'success' as const },
  { label: 'Backups', value: 18, color: 'warning' as const }
];

export function Demo() {
  return (
    <Block fullWidth>
      <Progress.Root>
        {SECTIONS.map((section) => (
          <Progress.Section
            key={section.label}
            value={section.value}
            color={section.color}
            tooltip={`${section.label} — ${section.value}%`}
          />
        ))}
      </Progress.Root>
    </Block>
  );
}
```

### Example — segments with legend

Custom-colored segments with tooltips and legend.

```tsx
import { Block, ColorSwatch, Progress, Row, Text } from '@plocks/ui';

const USAGE = [
  { label: 'Documents', value: 32, color: '#4c6ef5' },
  { label: 'Music', value: 24, color: '#12b886' },
  { label: 'Code', value: 14, color: '#fab005' },
  { label: 'Video Games', value: 9, color: '#fa5252' }
];

const TOTAL_GB = 500;

const formatSize = (percent: number) => {
  const gb = (percent / 100) * TOTAL_GB;
  return gb < 1 ? `${Math.round(gb * 1024)} MB` : `${Math.round(gb)} GB`;
};

export function Demo() {
  return (
    <Block gap="md" fullWidth>
      <Progress.Root size="lg" radius="xl">
        {USAGE.map((segment) => (
          <Progress.Section
            key={segment.label}
            value={segment.value}
            color={segment.color}
            tooltip={{
              label: `${segment.label} — ${formatSize(segment.value)} (${segment.value}%)`,
              withArrow: true
            }}
          >
            <Progress.Label>{formatSize(segment.value)}</Progress.Label>
          </Progress.Section>
        ))}
      </Progress.Root>

      <Block gap="lg" direction="row" justify="center">
        {USAGE.map((segment) => (
          <Row key={segment.label} gap="xs" align="center">
            <ColorSwatch color={segment.color} size={12} />
            <Text variant="small">{segment.label}</Text>
            <Text variant="small" c="muted">
              {segment.value}%
            </Text>
          </Row>
        ))}
      </Block>
    </Block>
  );
}
```

### Vertical orientation

Set `orientation="vertical"` to fill from the bottom up. Vertical bars have no intrinsic length, so they default to 160 — use `length` (or `h`) to size them.

```tsx
import { Block, Progress, Row, Text } from '@plocks/ui';

const CHANNELS = [
  { label: 'Kick', value: 82 },
  { label: 'Snare', value: 64 },
  { label: 'Bass', value: 91 },
  { label: 'Vox', value: 47 }
];

export function Demo() {
  return (
    <Row gap="md">
      {CHANNELS.map((channel) => (
        <Block key={channel.label} gap="xs" align="center">
          <Progress value={channel.value} orientation="vertical" length={120} />
          <Text variant="small" c="muted">
            {channel.label}
          </Text>
        </Block>
      ))}
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/QRCode.md -->

# QRCode

The QRCode component generates QR codes for encoding text, URLs, or other data. Supports customization of size, colors, quiet zones, error correction, and various rendering options.

## Metadata

- Import: `import { QRCode } from '@plocks/qrcode';`
- Install: `npm install @plocks/qrcode` — a separate package from `@plocks/ui`
- Tags: qrcode, barcode, scan, data, encoding
- Docs: https://plocks.dev/components/QRCode
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/qrcode/src/components/QRCode

## Props

- `value` (required): string — The data/text to encode in the QR code
- `label`: React.ReactNode — Caption rendered with the code — what the user is being asked to scan. Also supplies the accessibility label when `accessibilityLabel` is unset.
- `description`: React.ReactNode — Secondary line rendered under the label, for the longer explanation.
- `labelPosition`: 'top' | 'bottom' = 'bottom' — Which side of the code the caption sits on. @default 'bottom'
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>`
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the description `<Text>`
- `size`: ComponentSizeValue = 400 — Size of the QR code (both width and height). Accepts a size token (`xs`–`3xl`) or an explicit pixel value.
- `bg`: string — Background of the code itself: a background token, palette color, or any CSS color.
- `color`: string — Foreground color (the QR code pattern color)
- `moduleShape`: 'square' | 'rounded' | 'diamond' — Module shape variant for data modules. Note: Finder patterns (corner anchors) always remain square for optimal scanner compatibility.
- `cornerRadius`: number — Rounded corner radius factor (0-1) applied when moduleShape='rounded'
- `gradient`: { type?: 'linear' | 'radial'; from: string; to: string; rotation?: number; } — Gradient fill (overrides color)
- `errorCorrectionLevel`: 'L' | 'M' | 'Q' | 'H' = 'M' — Error correction level
- `quietZone`: number = 4 — Quiet zone size (border modules around the QR code). Defaults to 4 for QR code standard compliance. Set to 0 to remove all padding around the code.
- `logo`: { uri: string | ImageSourcePropType; element?: React.ReactNode; size?: number; backgroundColor?: string; borderRadius?: number; } — Logo to display in the center of the QR code
- `accessibilityLabel`: string — Accessible name of the code (announced as an image). Defaults to a string `label`, else `"QR code: <value>"` (long values truncated).
- `onError`: (error: Error) => void — Callback when QR code generation fails
- `copyOnPress`: boolean | { value?: string } — If true (or object), tapping the QR copies the value (or provided value).
- `showCopyButton`: boolean — Show a floating copy button overlay
- `copyToastTitle`: string — Custom toast title when copied
- `copyToastMessage`: string — Custom toast message when copied
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { QRCodeSVG } from '@plocks/qrcode';`

### QRCodeSVG

- `size`: number
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `opacity`: number — Opacity, `0`–`1`

Plus the `QRCode` props (`value` `label` `description` `labelPosition` `labelProps` `descriptionProps` `bg` `color` `moduleShape` `cornerRadius` `gradient` `errorCorrectionLevel` `quietZone` `logo` `accessibilityLabel` `onError` `copyOnPress` `showCopyButton` `copyToastTitle` `copyToastMessage`): https://plocks.dev/llms/components/QRCode.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Render a single QR code for a link or payload and provide helper text for scanning context.

```tsx
import { QRCode } from '@plocks/qrcode';

export function Demo() {
  return (
    <QRCode
      value="https://plocks.dev"
      size={168}
      quietZone={2}
      label="Scan to open the plocks docs."
    />
  );
}
```

### Sizes

Size accepts a token (`xs`–`3xl`) or an explicit pixel value, so QR codes line up with the rest of the size system while still allowing a bespoke footprint.

```tsx
import { Block, Row } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block>
      <Row align="flex-end" gap="lg" wrap="wrap">
        {SIZES.map((size) => (
          <QRCode
            key={size}
            value="https://plocks.dev"
            size={size}
            quietZone={2}
            label={size}
          />
        ))}
      </Row>

      <QRCode
        value="https://plocks.dev"
        size={144}
        quietZone={2}
        label="144 (numeric)"
      />
    </Block>
  );
}
```

### Spacing

Compare quiet zone values and pair them with outer spacing props when embedding codes in dense layouts.

```tsx
import { Block } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

const QUIET_ZONES = [
  { label: 'Default quiet zone (4)', quietZone: undefined },
  { label: 'Minimal quiet zone (1)', quietZone: 1 },
  { label: 'No quiet zone (0)', quietZone: 0 }
] as const;

export function Demo() {
  return (
    <Block align="center">
      {QUIET_ZONES.map(({ label, quietZone }) => (
        <QRCode
          key={label}
          value="https://plocks.dev"
          size={150}
          quietZone={quietZone}
          label={label}
        />
      ))}
      <Block bg="subtle" radius="lg" p="sm">
        <QRCode
          value="https://plocks.dev"
          size={150}
          quietZone={0}
          m="xs"
        />
      </Block>
    </Block>
  );
}
```

### Colors

Derive QR foreground and background colors from theme palettes to keep scans on brand.

```tsx
import { Row, useTheme } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

const SCHEMES = ['primary', 'success', 'warning', 'error'] as const;

export function Demo() {
  const theme = useTheme();

  return (
    <Row gap="lg" wrap="wrap" justify="center">
      {SCHEMES.map((scheme) => (
        <QRCode
          key={scheme}
          value="https://plocks.dev"
          size={144}
          color={theme.colors[scheme][6]}
          bg={theme.colors[scheme][0]}
          quietZone={2}
          label={scheme}
        />
      ))}
    </Row>
  );
}
```

### Shapes

Switch between square, rounded, and diamond module shapes while keeping finder patterns scanner-safe.

```tsx
import { Row } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

const SHAPES = ['square', 'rounded', 'diamond'] as const;

export function Demo() {
  return (
    <Row gap="lg" wrap="wrap" justify="center">
      {SHAPES.map((shape) => (
        <QRCode
          key={shape}
          value="https://plocks.dev"
          size={150}
          moduleShape={shape}
          quietZone={1}
          label={shape}
        />
      ))}
    </Row>
  );
}
```

### Gradients

Blend theme colors with linear or radial gradients to add polish without hurting scan reliability.

```tsx
import { Row, useTheme } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

export function Demo() {
  const theme = useTheme();

  return (
    <Row gap="lg" wrap="wrap" justify="center">
      <QRCode
        value="https://plocks.dev"
        size={160}
        quietZone={2}
        gradient={{ type: 'linear', from: theme.colors.primary[6], to: theme.colors.highlight[5], rotation: 45 }}
        label="linear"
      />
      <QRCode
        value="https://plocks.dev"
        size={160}
        quietZone={2}
        gradient={{ type: 'radial', from: theme.colors.success[5], to: theme.colors.primary[4] }}
        label="radial"
      />
    </Row>
  );
}
```

### Interactive

Let editors tweak the payload, size, error correction, and module shape while previewing the QR code live.

```tsx
import { useState } from 'react';
import { Block, Button, Input, Row, Text } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

const SIZES = [144, 168, 192] as const;
const ERROR_LEVELS = ['L', 'M', 'Q', 'H'] as const;
const MODULE_SHAPES = ['square', 'rounded', 'diamond'] as const;

export function Demo() {
  const [value, setValue] = useState('https://plocks.dev');
  const [size, setSize] = useState<(typeof SIZES)[number]>(168);
  const [errorLevel, setErrorLevel] = useState<(typeof ERROR_LEVELS)[number]>('M');
  const [moduleShape, setModuleShape] = useState<(typeof MODULE_SHAPES)[number]>('square');

  return (
    <Block>
      <Input value={value} onChangeText={setValue} placeholder="Enter text, URL, or contact info" />
      <Row gap="lg" wrap="wrap" align="flex-start">
        <Block>
          <Block>
            <Text variant="small" c="muted">
              Size
            </Text>
            <Row gap="xs" wrap="wrap">
              {SIZES.map((option) => (
                <Button
                  key={option}
                  size="xs"
                  variant={size === option ? 'filled' : 'outline'}
                  onPress={() => setSize(option)}
                >
                  {option}px
                </Button>
              ))}
            </Row>
          </Block>
          <Block>
            <Text variant="small" c="muted">
              Error correction
            </Text>
            <Row gap="xs" wrap="wrap">
              {ERROR_LEVELS.map((level) => (
                <Button
                  key={level}
                  size="xs"
                  variant={errorLevel === level ? 'filled' : 'outline'}
                  onPress={() => setErrorLevel(level)}
                >
                  {level}
                </Button>
              ))}
            </Row>
          </Block>
          <Block>
            <Text variant="small" c="muted">
              Module shape
            </Text>
            <Row gap="xs" wrap="wrap">
              {MODULE_SHAPES.map((shape) => (
                <Button
                  key={shape}
                  size="xs"
                  variant={moduleShape === shape ? 'filled' : 'outline'}
                  onPress={() => setModuleShape(shape)}
                >
                  {shape}
                </Button>
              ))}
            </Row>
          </Block>
        </Block>
        <QRCode
          value={value || 'plocks'}
          size={size}
          quietZone={2}
          errorCorrectionLevel={errorLevel}
          moduleShape={moduleShape}
        />
      </Row>
    </Block>
  );
}
```

### Logos

Embed brand marks inside the QR code while preserving quiet zones and scanner-friendly contrast.

```tsx
import { QRCode } from '@plocks/qrcode';

export function Demo() {
  return (
    <QRCode
      value="https://plocks.dev"
      size={176}
      quietZone={2}
      logo={{
        uri: require('../../../../assets/logo-mark.png'),
        size: 48,
        borderRadius: 8
      }}
    />
  );
}
```

### QR Code Variants

Compare how error correction levels and quiet zone widths influence scannability.

```tsx
import { Block, Row } from '@plocks/ui';
import { QRCode } from '@plocks/qrcode';

const ERROR_LEVELS = [
  { label: 'Level L (~7%)', value: 'L' },
  { label: 'Level M (~15%)', value: 'M' },
  { label: 'Level Q (~25%)', value: 'Q' },
  { label: 'Level H (~30%)', value: 'H' }
] as const;

const QUIET_ZONES = [0, 2, 4, 8] as const;

export function Demo() {
  return (
    <Block>
      <Row gap="lg" wrap="wrap" justify="center">
        {ERROR_LEVELS.map(({ label, value }) => (
          <QRCode
            key={value}
            value={`https://plocks.dev/ecc/${value}`}
            errorCorrectionLevel={value}
            size={140}
            label={label}
          />
        ))}
      </Row>
      <Row gap="lg" wrap="wrap" justify="center">
        {QUIET_ZONES.map((quietZone) => (
          <QRCode
            key={quietZone}
            value={`https://plocks.dev/quiet-zone/${quietZone}`}
            quietZone={quietZone}
            size={140}
            label={`Quiet zone: ${quietZone}`}
          />
        ))}
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Radio.md -->

# Radio

Radio lets users select one option from a group of choices.

## Metadata

- Import: `import { Radio } from '@plocks/ui';`
- Tags: input, form, selection, choice
- Docs: https://plocks.dev/components/Radio
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Radio

## Props

- `value` (required): string — Value reported to `onChange` when this radio is picked.
- `checked`: boolean — Whether this radio is the selected one.
- `onChange`: (value: string) => void — Called with `value` when the radio is picked.
- `color`: ThemeColor — Radio color: a palette token, `'primary.6'` shade syntax, or any CSS color.
- `labelPosition`: 'left' | 'right' — Label side. Default `'right'`.
- `children`: React.ReactNode — Label content (alternative to `label`; wins when both are set).
- `icon`: React.ReactNode | string — Icon shown before the label: an icon registry name or any element.
- `onKeyDown`: (event: WebKeyboardEvent) => void — Web key handler on the radio (RadioGroup uses it for arrow-key navigation).
- `tabIndex`: 0 | -1 — Web tab order of the radio. Groups manage it (only the selected radio is a tab stop); a standalone radio is always a tab stop.
- `transitionDuration`: number = 160 — Length of the select/deselect animation in ms; the center dot grows in and shrinks out against it. `0` applies the state instantly. Always 0 under reduced motion.
- `id`: string — Base id: the control gets it, the label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { RadioGroup } from '@plocks/ui';`

### RadioGroup

- `options` (required): RadioGroupOption[] — Available options.
- `value`: string — Selected value (controlled).
- `defaultValue`: string — Initially selected value (uncontrolled).
- `onChange`: (value: string) => void — Called with the newly selected value.
- `orientation`: 'vertical' | 'horizontal' — Group orientation. Ignored by `segmented` (always horizontal) and `chip` (wraps).
- `variant`: 'default' | 'card' | 'segmented' | 'chip' — Visual variant of the group. Defaults to `'default'`.
- `color`: ThemeColor — Radio color: a palette token, `'primary.6'` shade syntax, or any CSS color.
- `gap`: SizeValue | number — Gap between options: a spacing token or px. Default 8.
- `labelPosition`: 'left' | 'right' — Label position relative to each radio (default variant).
- `transitionDuration`: number = 160 — Length of each radio's select/deselect animation in ms. `0` applies the state instantly. Always 0 under reduced motion.
- `id`: string — Base id for the group; option radios get `${id}-option-${index}`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface RadioGroupOption {
  label: React.ReactNode;
  value: string;
  disabled?: boolean;
  description?: React.ReactNode;
  icon?: React.ReactNode | string;
}
```

## Examples

### Basics

Use standalone `Radio` components for custom layouts or pass an `options` array to `RadioGroup` for quick single-selection forms.

```tsx
import { useState } from 'react';
import { Block, Radio, RadioGroup, Text } from '@plocks/ui';

const TEAMS = ['Falcons', 'Tigers', 'Sharks'] as const;

export function Demo() {
  const [favoriteTeam, setFavoriteTeam] = useState<string>('Tigers');
  const [ticketType, setTicketType] = useState<string>('reserved');

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">
          Standalone radios
        </Text>
        <Block>
          {TEAMS.map((team) => (
            <Radio
              key={team}
              value={team}
              checked={favoriteTeam === team}
              onChange={setFavoriteTeam}
              label={team}
            />
          ))}
        </Block>
      </Block>

      <Block>
        <Text variant="small" c="muted">
          Grouped selection
        </Text>
        <RadioGroup
          value={ticketType}
          onChange={setTicketType}
          options={[
            { label: 'General admission', value: 'general' },
            { label: 'Reserved seating', value: 'reserved' },
            { label: 'VIP hospitality', value: 'vip' }
          ]}
        />
      </Block>
    </Block>
  );
}
```

### Variants

The `variant` prop on `RadioGroup` selects how the group is laid out and how the selected option is communicated. `default` keeps the classic dot indicators; `card` renders each option as a bordered surface (useful when options have descriptions); `segmented` joins the options into a single iOS-style control; `chip` lays them out as wrap-friendly pills (good for filter UIs).

```tsx
import { useState } from 'react';
import { Block, RadioGroup, Text } from '@plocks/ui';

const PLAN_OPTIONS = [
  { label: 'Starter', value: 'starter', description: 'Up to 3 projects, community support' },
  { label: 'Growth', value: 'growth', description: 'Unlimited projects, priority email support' },
  { label: 'Scale', value: 'scale', description: 'Dedicated success manager + SSO' },
];

const FREQUENCY_OPTIONS = [
  { label: 'Daily', value: 'daily' },
  { label: 'Weekly', value: 'weekly' },
  { label: 'Monthly', value: 'monthly' },
];

const FILTER_OPTIONS = [
  { label: 'All', value: 'all' },
  { label: 'Active', value: 'active' },
  { label: 'Archived', value: 'archived' },
  { label: 'Trashed', value: 'trashed' },
];

export function Demo() {
  const [defaultValue, setDefaultValue] = useState('weekly');
  const [planValue, setPlanValue] = useState('growth');
  const [frequencyValue, setFrequencyValue] = useState('weekly');
  const [filterValue, setFilterValue] = useState('active');

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">default</Text>
        <RadioGroup
          variant="default"
          value={defaultValue}
          onChange={setDefaultValue}
          options={FREQUENCY_OPTIONS}
        />
      </Block>

      <Block>
        <Text variant="small" c="muted">card</Text>
        <RadioGroup
          variant="card"
          value={planValue}
          onChange={setPlanValue}
          options={PLAN_OPTIONS}
        />
      </Block>

      <Block>
        <Text variant="small" c="muted">segmented</Text>
        <RadioGroup
          variant="segmented"
          value={frequencyValue}
          onChange={setFrequencyValue}
          options={FREQUENCY_OPTIONS}
        />
      </Block>

      <Block>
        <Text variant="small" c="muted">chip</Text>
        <RadioGroup
          variant="chip"
          value={filterValue}
          onChange={setFilterValue}
          options={FILTER_OPTIONS}
        />
      </Block>
    </Block>
  );
}
```

### Theming

Combine the `size`, `color`, and validation props to align radios with your UI tokens and state requirements.

```tsx
import { useState } from 'react';
import { Block, Radio, RadioGroup, Text } from '@plocks/ui';

const COLOR_OPTIONS = ['primary', 'secondary', 'success', 'error'] as const;

export function Demo() {
  const [sizeValue, setSizeValue] = useState<string>('club');
  const [colorValue, setColorValue] = useState<typeof COLOR_OPTIONS[number]>('primary');

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">
          Size tokens
        </Text>
        <RadioGroup
          size="sm"
          value={sizeValue}
          onChange={setSizeValue}
          options={[
            { label: 'Club', value: 'club' },
            { label: 'Suite', value: 'suite' },
            { label: 'Field level', value: 'field' }
          ]}
        />
      </Block>

      <Block>
        <Text variant="small" c="muted">
          Semantic colors
        </Text>
        <Block>
          {COLOR_OPTIONS.map((tone) => (
            <Radio
              key={tone}
              value={tone}
              checked={colorValue === tone}
              onChange={(value) => setColorValue(value as typeof COLOR_OPTIONS[number])}
              label={`${tone.charAt(0).toUpperCase()}${tone.slice(1)} tickets`}
              color={tone}
            />
          ))}
        </Block>
      </Block>

      <Block>
        <Text variant="small" c="muted">
          Common states
        </Text>
        <Radio value="available" checked label="Available" />
        <Radio value="disabled" disabled label="Disabled" />
        <Radio value="error" error="Select a seat" label="Needs attention" />
      </Block>
    </Block>
  );
}
```

### Orientations

Toggle `orientation` between `horizontal` and `vertical` to adapt radio groups to the available space.

```tsx
import { useState } from 'react';
import { Block, RadioGroup, Text } from '@plocks/ui';

export function Demo() {
  const [favoriteSport, setFavoriteSport] = useState<string>('soccer');
  const [skillLevel, setSkillLevel] = useState<string>('intermediate');

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">
          Horizontal layout
        </Text>
        <RadioGroup
          orientation="horizontal"
          value={favoriteSport}
          onChange={setFavoriteSport}
          options={[
            { label: 'Soccer', value: 'soccer' },
            { label: 'Basketball', value: 'basketball' },
            { label: 'Tennis', value: 'tennis' },
            { label: 'Volleyball', value: 'volleyball' }
          ]}
        />
      </Block>

      <Block>
        <Text variant="small" c="muted">
          Vertical layout
        </Text>
        <RadioGroup
          orientation="vertical"
          value={skillLevel}
          onChange={setSkillLevel}
          options={[
            { label: 'Beginner', value: 'beginner' },
            { label: 'Intermediate', value: 'intermediate' },
            { label: 'Advanced', value: 'advanced' },
            { label: 'Expert', value: 'expert' }
          ]}
        />
      </Block>
    </Block>
  );
}
```

### Forms

Pair `RadioGroup` with `required` and `error` messaging to validate selections before submitting a form workflow.

```tsx
import { useState } from 'react';
import { Block, Button, RadioGroup, Text } from '@plocks/ui';

const PLANS = [
  {
    label: 'Starter — $9/mo',
    value: 'starter',
    description: 'Streamline a single project'
  },
  {
    label: 'Team — $19/mo',
    value: 'team',
    description: 'Collaborate with up to 10 teammates'
  },
  {
    label: 'Club — $39/mo',
    value: 'club',
    description: 'Unlock advanced analytics'
  }
];

const BILLING = [
  { label: 'Monthly', value: 'monthly' },
  { label: 'Annual (save 20%)', value: 'annual' }
];

export function Demo() {
  const [plan, setPlan] = useState<string>('');
  const [billingCycle, setBillingCycle] = useState<string>('monthly');
  const [planError, setPlanError] = useState<string | undefined>();
  const [confirmation, setConfirmation] = useState<string | null>(null);

  const handleSubmit = () => {
    if (!plan) {
      setPlanError('Select a plan to continue');
      setConfirmation(null);
      return;
    }

    setPlanError(undefined);
    setConfirmation(`Subscribed to the ${plan} plan with ${billingCycle} billing.`);
  };

  return (
    <Block>
      <RadioGroup
        label="Select a membership"
        options={PLANS}
        value={plan}
        onChange={(next) => {
          setPlan(next);
          setPlanError(undefined);
        }}
        error={planError}
        required
      />

      <RadioGroup
        label="Billing cadence"
        orientation="horizontal"
        options={BILLING}
        value={billingCycle}
        onChange={setBillingCycle}
      />

      <Button onPress={handleSubmit}>Confirm subscription</Button>

      {confirmation && (
        <Text variant="small" c="success">
          {confirmation}
        </Text>
      )}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Rating.md -->

# Rating

An interactive component for displaying star ratings and allowing users to provide ratings with customizable appearance.

## Metadata

- Import: `import { Rating } from '@plocks/ui';`
- Tags: rating, stars, review, score, feedback
- Docs: https://plocks.dev/components/Rating
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Rating

## Props

- `value`: number — Current rating value (controlled).
- `defaultValue`: number = 0 — Initial rating value for uncontrolled usage.
- `count`: number = 5 — Number of rating items (stars) to render.
- `readOnly`: boolean = false — Display only: the rating shows its value (as an image with a spoken "4 out of 5") and takes no input.
- `disabled`: boolean = false — Disables the rating: blocks input, dims the control and reports it disabled to assistive technology.
- `allowFraction`: boolean = false — Allows partial values so a star can be filled fractionally.
- `precision`: number = 0.1 when `allowFraction`, otherwise 1 — Smallest increment a value is rounded to when `allowFraction` is enabled. Clamped to the `0.01`–`1` range.
- `size`: SizeValue = 'md' — Size of each rating item — a theme size token or an explicit pixel size.
- `color`: string — Color of filled items. Defaults to the theme warning color.
- `emptyColor`: string — Color of empty items. Defaults to `theme.text.muted`.
- `hoverColor`: string — Color of items while hovering/dragging. Defaults to a deeper theme warning color.
- `onChange`: (value: number) => void — Called with the new value when the rating changes.
- `onHover`: (value: number) => void — Called with the previewed value while hovering (web only).
- `clearable`: boolean = false — Allows clearing the rating by selecting the value that is already set.
- `showTooltip`: boolean = false — Shows a tooltip with the current value out of `count` while hovering.
- `getTooltipLabel`: (value: number, count: number) => string — Formats the tooltip text. Receives the previewed value and `count`; defaults to `4.5 / 5`.
- `icon`: RatingIcon — Icon rendered for each item instead of the default star. Accepts an icon registry name (`'heart'`), an icon library component, or an element. Takes precedence over `character`.
- `emptyIcon`: RatingIcon — Icon rendered for empty items. Defaults to `icon`, so the same glyph is drawn in `emptyColor` unless a different empty icon is supplied.
- `character`: string | React.ReactNode = '★' — Character or node rendered for filled items. Custom strings render as text glyphs, a React element is cloned with `size` and `color`, and the default star character renders the built-in star icon. Ignored when `icon` is set.
- `emptyCharacter`: string | React.ReactNode = '☆' — Character or node rendered for empty items. Ignored when `icon` or `emptyIcon` is set.
- `gap`: SizeValue = 'xs' — Spacing between rating items — a theme size token or an explicit pixel value.
- `labelPosition`: 'left' | 'right' | 'above' | 'below' = 'above' — Placement of the label relative to the rating (`left` / `right` follow the reading direction).
- `labelGap`: SizeValue = 'xs' — Spacing between the label and the rating — a theme size token or pixel value.
- `id`: string — Base id: the control gets it, the label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type RatingIcon = string | ExternalIconComponent | React.ReactElement;
```

## Examples

### Basics

Capture a single rating value with an interactive control and mirror the current score in helper text.

```tsx
import { useState } from 'react';
import { Block, Rating, Text } from '@plocks/ui';

export function Demo() {
  const [score, setScore] = useState<number>(3);

  return (
    <Block>
      <Rating
        value={score}
        onChange={setScore}
        size="lg"
        label="Rate the broadcast quality"
      />
      <Text variant="small" c="muted">
        Current score: {score} out of 5.
      </Text>
    </Block>
  );
}
```

### Sizes

Compare the available `size` tokens side by side to pick the right scale for your scene.

```tsx
import { Block, Rating, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block fullWidth direction="row" align="center" justify="space-evenly">
      {SIZES.map((size) => (
        <Rating
          key={size}
          size={size}
          value={1}
          readOnly
          count={1}
          label={size}
          labelPosition="left"
        />
      ))}
    </Block>
  );
}
```

### Colors

Derive filled, hover, and empty colors from the theme palette to align ratings with product semantics.

```tsx
import { useState } from 'react';
import { Block, Rating, Text, useTheme } from '@plocks/ui';

const COLOR_CONFIG = [
  {
    key: 'primary',
    label: 'Primary accent',
    getColors: (palette: string[]) => ({
      color: palette[5],
      emptyColor: palette[1],
      hoverColor: palette[6]
    })
  },
  {
    key: 'success',
    label: 'Success feedback',
    getColors: (palette: string[]) => ({
      color: palette[5],
      emptyColor: palette[1],
      hoverColor: palette[6]
    })
  },
  {
    key: 'warning',
    label: 'Warning feedback',
    getColors: (palette: string[]) => ({
      color: palette[5],
      emptyColor: palette[1],
      hoverColor: palette[6]
    })
  }
] as const;

type PaletteKey = (typeof COLOR_CONFIG)[number]['key'];

export function Demo() {
  const theme = useTheme();
  const [values, setValues] = useState<Record<PaletteKey, number>>({
    primary: 4,
    success: 3.5,
    warning: 2.5
  });

  return (
    <Block>
      {COLOR_CONFIG.map(({ key, label, getColors }) => {
        const palette = theme.colors[key as keyof typeof theme.colors] ?? theme.colors.gray;
        const { color, emptyColor, hoverColor } = getColors(palette);

        return (
          <Block key={key}>
            <Rating
              value={values[key]}
              onChange={(next) =>
                setValues((prev) => ({ ...prev, [key]: next }))
              }
              color={color}
              emptyColor={emptyColor}
              hoverColor={hoverColor}
              size="lg"
              labelPosition="right"
              label={
            <Text variant="small" c="muted">
              {label}
            </Text>
            }
            />
          </Block>
        );
      })}
    </Block>
  );
}
```

### Fractions

Enable fractional ratings with configurable `precision` values to capture nuanced feedback.

```tsx
import { useState } from 'react';
import { Block, Rating, Text, useTheme } from '@plocks/ui';

const FRACTION_SETTINGS = [
  {
    key: 'match',
    label: 'Match excitement',
    precision: 0.1,
    helper: 'Set scores in 0.1 increments to capture precise fan sentiment.'
  },
  {
    key: 'broadcast',
    label: 'Broadcast quality',
    precision: 0.5,
    helper: 'Use half-star increments when quick feedback is enough.'
  }
] as const;

type FractionKey = (typeof FRACTION_SETTINGS)[number]['key'];

export function Demo() {
  const theme = useTheme();
  const [values, setValues] = useState<Record<FractionKey, number>>({
    match: 4.2,
    broadcast: 3.5
  });

  return (
    <Block>
      {FRACTION_SETTINGS.map(({ key, label, precision, helper }) => (
        <Block key={key}>
          <Text variant="small" c="muted">
            {label}
          </Text>
          <Rating accessibilityLabel="Rating"
            value={values[key]}
            onChange={(next) => setValues((prev) => ({ ...prev, [key]: next }))}
            allowFraction
            precision={precision}
            size="lg"
            color={theme.colors.highlight[5]}
            emptyColor={theme.colors.highlight[1]}
            hoverColor={theme.colors.highlight[6]}
            showTooltip
          />
          <Text variant="small" c="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Custom Icons

Swap the default star for any registry icon with `icon`, pair it with a different `emptyIcon` for the unfilled state, or fall back to plain text glyphs through `character` and `emptyCharacter`.

```tsx
import { useState } from 'react';
import { Block, Rating, Text, useTheme } from '@plocks/ui';

export function Demo() {
  const theme = useTheme();
  const [hearts, setHearts] = useState<number>(4);
  const [bolts, setBolts] = useState<number>(3);

  return (
    <Block>
      <Rating
        value={hearts}
        onChange={setHearts}
        icon="heart"
        size="lg"
        color={theme.colors.error[5]}
        emptyColor={theme.colors.error[2]}
        hoverColor={theme.colors.error[6]}
        label="Registry icon via `icon`"
      />
      <Rating
        value={bolts}
        onChange={setBolts}
        icon="bolt"
        emptyIcon="circle"
        size="lg"
        label="Different empty icon via `emptyIcon`"
      />
      <Rating
        value={3.5}
        readOnly
        allowFraction
        icon="moon"
        size="lg"
        label="Custom icons support fractions"
      />
      <Rating
        value={4}
        readOnly
        character="♥"
        emptyCharacter="♡"
        size="lg"
        label="Text glyphs via `character`"
      />
    </Block>
  );
}
```

### Variants

Contrast interactive, read-only, and tooltip-enabled ratings to decide which fits your feedback flow.

```tsx
import { useState } from 'react';
import { Block, Rating } from '@plocks/ui';

export function Demo() {
  const [interactiveValue, setInteractiveValue] = useState<number>(4);

  return (
    <Block>
      <Rating
        value={interactiveValue}
        onChange={setInteractiveValue}
        size="lg"
        label="Interactive rating"
      />
      <Rating
        value={4.5}
        readOnly
        size="lg"
        label="Read-only rating"
        disclaimer="Use `readOnly` to show aggregated scores."
      />
      <Rating
        defaultValue={3}
        showTooltip
        size="lg"
        label="Tooltip rating"
        disclaimer="Tooltips show numeric value on hover."
      />
      <Rating
        defaultValue={4}
        showTooltip
        getTooltipLabel={(value, count) => `${value} out of ${count} stars`}
        size="lg"
        label="Custom tooltip text"
        disclaimer="Pass `getTooltipLabel` to format the tooltip."
      />
      <Rating
        value={3}
        disabled
        size="lg"
        label="Disabled rating"
        disclaimer="`disabled` blocks input and dims the control."
      />
    </Block>
  );
}
```

### Form Field

Use `required`, `description`, and `error` to drop a rating into a form like any other field, and `clearable` to let people undo a score by selecting it again.

```tsx
import { useState } from 'react';
import { Block, Button, Rating, Text } from '@plocks/ui';

export function Demo() {
  const [score, setScore] = useState<number>(0);
  const [submitted, setSubmitted] = useState(false);

  const error = submitted && score === 0 ? 'Please choose a rating' : undefined;

  return (
    <Block>
      <Rating
        value={score}
        onChange={setScore}
        clearable
        required
        size="lg"
        label="Overall experience"
        description="Select a star again to clear your rating."
        error={error}
      />
      <Button onPress={() => setSubmitted(true)}>Submit</Button>
      <Text variant="small" c="muted">
        {score === 0 ? 'No rating selected.' : `You rated ${score} out of 5.`}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ReorderableList.md -->

# ReorderableList

ReorderableList accepts an ordered `data` array and calls `onReorder({ data, from, to })` after a move. Update your state with the returned array. On native, long press the handle to drag; on web, drag a row or focus its handle and press Up or Down. Native drag gestures need `GestureHandlerRootView` at the application root.

Use `scrollEnabled={false}` for short native lists embedded in a parent ScrollView. Set `w="100%"` when placing the list in a column that aligns children to the start.

## Metadata

- Import: `import { ReorderableList } from '@plocks/ui';`
- Status: beta
- Tags: list, reorder, drag, sort
- Docs: https://plocks.dev/components/ReorderableList
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ReorderableList

## Props

- `data` (required): T[] — Ordered items. Update this array in onReorder to commit a move.
- `keyExtractor` (required): (item: T, index: number) => string
- `renderItem` (required): (info: { item: T; index: number; isActive: boolean }) => React.ReactNode
- `getItemLabel`: (item: T, index: number) => string — Used in the drag handle's accessible name.
- `onReorder` (required): (result: ReorderResult<T>) => void
- `disabled`: boolean = false
- `scrollEnabled`: boolean = true — Enable the native list's own scrolling. Disable inside a parent ScrollView. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface ReorderResult<T> {
  data: T[];
  from: number;
  to: number;
}
```

## Examples

### Reorder tasks

Drag a row to change its position. On web, focus the reorder handle and use the Up and Down arrows; on native, long press the handle or use screen reader move actions. The list is controlled, so `onReorder` updates the items state.

```tsx
import { useState } from 'react';
import { Block, Column, ReorderableList, Text } from '@plocks/ui';

const initialTasks = [
  { id: 'plan', title: 'Plan the release' },
  { id: 'build', title: 'Build the package' },
  { id: 'share', title: 'Share with developers' },
];

export function Demo() {
  const [tasks, setTasks] = useState(initialTasks);
  return (
    <Column gap="sm" fullWidth>
      <ReorderableList
        w="100%"
        scrollEnabled={false}
        data={tasks}
        keyExtractor={(task) => task.id}
        getItemLabel={(task) => task.title}
        onReorder={({ data }) => setTasks(data)}
        renderItem={({ item }) => <Block p="sm" fullWidth><Text>{item.title}</Text></Block>}
      />
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Ring.md -->

# Ring

Ring displays progress or status in a circular indicator.

## Metadata

- Import: `import { Ring } from '@plocks/ui';`
- Tags: ring, progress, indicator, radial
- Docs: https://plocks.dev/components/Ring
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Ring

## Props

- `value` (required): number — Current value represented by the ring
- `min`: number = 0 — Lower bound for normalization. Defaults to 0.
- `max`: number = 100 — Upper bound for normalization. Defaults to 100.
- `size`: number = 100 — Diameter of the ring in pixels. Defaults to 100.
- `thickness`: number = 12 — Stroke thickness in pixels. Defaults to 12.
- `caption`: React.ReactNode — Optional caption rendered beneath the ring
- `label`: React.ReactNode — Main label rendered in the ring center
- `subLabel`: React.ReactNode — Secondary label rendered below the main label
- `showValue`: boolean = true — Displays the computed percentage when no label/subLabel is provided. Defaults to true.
- `valueFormatter`: (value: number, percent: number) => React.ReactNode — Formats the displayed value or percentage
- `trackColor`: string — Track color behind the progress stroke. Defaults to the theme's `backgrounds.border`.
- `progressColor`: string | ((value: number, percent: number) => string) — Progress stroke color or resolver
- `colorStops`: RingColorStop[] — Optional color stops evaluated against the computed percent
- `neutral`: boolean = false — Forces the ring into a neutral state, disabling the progress stroke
- `roundedCaps`: boolean = true — Controls whether the progress stroke has rounded caps. Defaults to true.
- `ringStyle`: StyleProp<ViewStyle> — Style applied to the ring wrapper
- `contentStyle`: StyleProp<ViewStyle> — Style applied to the center content container
- `labelStyle`: StyleProp<TextStyle> — Style overrides for the main label
- `subLabelStyle`: StyleProp<TextStyle> — Style overrides for the secondary label
- `captionStyle`: StyleProp<TextStyle> — Style overrides for the caption
- `labelColor`: string — Color override for the main label
- `subLabelColor`: string — Color override for the secondary label
- `captionColor`: string — Color override for the caption
- `children`: React.ReactNode | ((context: RingRenderContext) => React.ReactNode) — Custom center content. Receives value info when passed as a function
- `accessibilityLabel`: string — Accessible name of the ring (a `progressbar`). Defaults to the text of `caption`, else of `label`. The value is exposed as aria-value* on its own.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface RingColorStop {
  /** Threshold (0-100) that determines when the color becomes active */
  value: number;
  /** Stroke color applied once the threshold is reached */
  color: string;
}

export interface RingRenderContext {
  /** Clamped value within the provided min/max range */
  value: number;
  /** Normalized percentage (0-100) for the current value */
  percent: number;
  /** Minimum bound used for normalization */
  min: number;
  /** Maximum bound used for normalization */
  max: number;
}
```

## Examples

### Basics

Drive multiple ring presentations from a single stateful value and expose how sizing and labels adapt.

```tsx
import { useState } from 'react';
import { Block, Button, Ring, Row } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(72);

  return (
    <Block align="center" gap="md">
      <Row gap="lg" align="center">
        <Ring value={value} caption="Completion" />
        <Ring value={value} size={72} thickness={8} caption="Compact" />
      </Row>
      <Row gap="sm">
        <Button variant="outline" onPress={() => setValue(Math.max(0, value - 10))}>
          -10%
        </Button>
        <Button onPress={() => setValue(Math.min(100, value + 10))}>+10%</Button>
      </Row>
    </Block>
  );
}
```

### Dynamic Color Stops

Display how `colorStops` shift the progress color as values cross threshold ranges.

```tsx
import { Ring, Row } from '@plocks/ui';

const colorStops = [
  { value: 0, color: '#f87171' },
  { value: 60, color: '#f59e0b' },
  { value: 90, color: '#14b8a6' },
];

export function Demo() {
  return (
    <Row gap="lg" justify="center" wrap="wrap">
      {[48, 72, 97].map((value) => (
        <Ring key={value} value={value} colorStops={colorStops} caption={`${value}%`} />
      ))}
    </Row>
  );
}
```

### Custom Center Content

Showcase the render-prop API for injecting icons, text, or status badges inside the ring.

```tsx
import { Block, Icon, Ring, Row, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="lg" justify="center" wrap="wrap">
      <Ring value={86} caption="Pipeline">
        {({ percent }) => (
          <Block align="center">
            <Icon name="rocket" size="lg" color="primary" />
            <Text fw="700">{Math.round(percent)}%</Text>
          </Block>
        )}
      </Ring>

      <Ring value={0} neutral caption="Design system">
        <Block align="center">
          <Icon name="clock" size="lg" color="gray" />
          <Text size="xs" c="secondary">
            On hold
          </Text>
        </Block>
      </Ring>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/RollingNumber.md -->

# RollingNumber

RollingNumber animates changing digits in a numeric readout.

## Metadata

- Import: `import { RollingNumber } from '@plocks/ui';`
- Tags: number, counter, animation, odometer, metric
- Docs: https://plocks.dev/components/RollingNumber
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/RollingNumber

## Props

- `value` (required): number — Value to display. Each digit that changes rolls to its new position.
- `prefix`: string — Static text rendered before the number (e.g. `"$ "`).
- `suffix`: string — Static text rendered after the number (e.g. `" USD"`).
- `thousandSeparator`: boolean | string = false — `true` for `,`, or an explicit separator string.
- `decimalSeparator`: string = '.' — Character between the integer and decimal parts. Default `.`.
- `decimalScale`: number — Number of decimal places to render.
- `fixedDecimalScale`: boolean = false — Pad the decimal part with zeros up to `decimalScale`.
- `transitionDuration`: number — Roll duration in ms. Default `600`. `0` — and an active reduced-motion preference — snap straight to the new digits.
- `animationDuration`: number — alias for `transitionDuration`.
- `timingFunction`: 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' = 'ease' — Easing curve for the roll. Default `ease`.
- `stagger`: number = 0 — Per-column delay in ms, applied right-to-left so the least significant digit leads. Default `0` (all columns move together).
- `trend`: RollingNumberTrend — Which way the digits roll. By default they roll up when the number grows and down when it shrinks, so 19 → 20 carries the ones column forward 9 → 0 like an odometer. `1` or `-1` fix the direction, `0` moves each digit straight to its new value, and a function decides per change.
- `animateOnMount`: boolean = false — Animate from zero on first render instead of appearing settled. Default `false`.
- `size`: SizeValue = 'md' — Font size token or explicit number. Default `'md'`.
- `c`: string — Text color. Accepts a text role (`'muted'`), palette syntax (`'primary.6'`) or any CSS color.
- `fw`: TextStyle['fontWeight'] | 'normal' | 'medium' | 'semibold' | 'bold' — Font weight.
- `ff`: string — Custom font family.
- `tabularNums`: boolean = true — Use tabular (fixed-width) figures so columns do not shift width as digits change. Default `true`.
- `style`: StyleProp<ViewStyle> — Style for the row that wraps prefix, digits and suffix.
- `textStyle`: StyleProp<TextStyle> — Style applied to every glyph — digits, separators, prefix and suffix.
- `digitStyle`: StyleProp<TextStyle> — Style applied to digit glyphs only.
- `accessibilityLabel`: string — Screen-reader label. Defaults to the formatted value including prefix and suffix, so the rolling columns never have to be read digit by digit.
- `testID`: string

Also accepts the shared props — spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type RollingNumberTrend = -1 | 0 | 1 | ((previous: number, value: number) => number);
```

## Examples

### Basics

A counter whose digits roll to their new positions. Only the columns that changed move.

```tsx
import { useState } from 'react';
import { Button, Flex, RollingNumber } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(1234);

  return (
    <Flex direction="column" align="center" gap="md">
      <RollingNumber value={value} size={48} fw="bold" />
      <Button variant="outline" onPress={() => setValue((current) => current + 1)}>+1</Button>
    </Flex>
  );
}
```

### Currency

`prefix`, `suffix` and the decimal options cover currency formatting without an external formatter. Copying the value on web yields the formatted string, not the digit strips.

```tsx
import { useState } from 'react';
import { Button, Flex, RollingNumber } from '@plocks/ui';

export function Demo() {
  const [total, setTotal] = useState(1299.99);

  return (
    <Flex direction="column" align="center" gap="md">
      <RollingNumber
        value={total}
        prefix="$ "
        suffix=" USD"
        decimalScale={2}
        fixedDecimalScale
        thousandSeparator
        size={36}
        fw="semibold"
      />
      <Button variant="outline" onPress={() => setTotal((current) => current + 149.5)}>
        Add item
      </Button>
    </Flex>
  );
}
```

### Timing

`transitionDuration`, `timingFunction` and `stagger` shape the roll. Stagger delays each column right-to-left, so the carries trail the ones place the way an odometer does.

```tsx
import { useState } from 'react';
import { Button, Flex, RollingNumber, Text } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(407219);

  return (
    <Flex direction="column" gap="lg">
      <Flex direction="column" gap="xs">
        <Text size="xs" c="muted">Snappy — 200ms, no stagger</Text>
        <RollingNumber value={value} transitionDuration={200} size={32} thousandSeparator />
      </Flex>

      <Flex direction="column" gap="xs">
        <Text size="xs" c="muted">Odometer — 900ms, 60ms stagger</Text>
        <RollingNumber
          value={value}
          transitionDuration={900}
          timingFunction="ease-out"
          stagger={60}
          size={32}
          thousandSeparator
        />
      </Flex>

      <Button variant="outline" onPress={() => setValue(Math.floor(Math.random() * 999999))}>
        Shuffle
      </Button>
    </Flex>
  );
}
```

### Trend

By default the digits roll up when the number grows and down when it shrinks, so 19 → 20 carries the ones column forward like an odometer. `trend={1}` or `trend={-1}` fix the direction, `trend={0}` moves each digit straight to its new value, and a function `(previous, value) => number` decides per change.

```tsx
import { useState } from 'react';
import { Button, Flex, RollingNumber, Text } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(19);

  return (
    <Flex direction="column" gap="lg">
      <Flex gap="xl">
        <Flex direction="column" align="center" gap="xs">
          <Text size="xs" c="muted">Auto</Text>
          <RollingNumber value={value} size={32} />
        </Flex>
        <Flex direction="column" align="center" gap="xs">
          <Text size="xs" c="muted">Always up</Text>
          <RollingNumber value={value} trend={1} size={32} />
        </Flex>
        <Flex direction="column" align="center" gap="xs">
          <Text size="xs" c="muted">Per digit</Text>
          <RollingNumber value={value} trend={0} size={32} />
        </Flex>
      </Flex>

      <Flex gap="sm" justify="center">
        <Button variant="outline" onPress={() => setValue((current) => current - 1)}>−1</Button>
        <Button variant="outline" onPress={() => setValue((current) => current + 1)}>+1</Button>
      </Flex>
    </Flex>
  );
}
```

### Live metric

A ticking live metric. Values that change faster than the roll retarget mid-flight rather than snapping.

```tsx
import { useEffect, useState } from 'react';
import { Flex, RollingNumber, Text } from '@plocks/ui';

export function Demo() {
  const [requests, setRequests] = useState(84213);

  useEffect(() => {
    const timer = setInterval(() => {
      setRequests((current) => current + Math.floor(Math.random() * 40));
    }, 1200);
    return () => clearInterval(timer);
  }, []);

  return (
    <Flex direction="column" gap="xs">
      <Text size="xs" c="muted" tt="uppercase">Requests today</Text>
      <RollingNumber
        value={requests}
        thousandSeparator
        size={40}
        fw="bold"
        transitionDuration={500}
        stagger={40}
      />
    </Flex>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/SafeArea.md -->

# SafeArea

SafeArea extends a layout container through the device safe area.

## Metadata

- Import: `import { SafeArea } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/SafeArea
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/SafeArea

## Props

- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `translateY`: number — Small visual offset without affecting surrounding layout.
- `rotate`: string — Rotation around the block center, such as `"45deg"`.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `start`: number | string — Start inset (logical: left in LTR, right in RTL)
- `end`: number | string — End inset (logical: right in LTR, left in RTL)
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Plus the `Block` props (`children` `className` `onPress` `onLongPress` `onPressIn` `onPressOut` `onMouseEnter` `onMouseLeave` `disabled`): https://plocks.dev/llms/components/Block.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

SafeArea extends a layout container through the device safe area.

```tsx
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { SafeArea, Text } from '@plocks/ui';

export function Demo() {
  return (
    <SafeAreaProvider>
      <SafeArea bg="subtle" p="md">
        <Text>Content inside the safe area</Text>
      </SafeArea>
    </SafeAreaProvider>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ScrollArea.md -->

# ScrollArea

ScrollArea provides a scrollable container with named layout and spacing props.

## Metadata

- Import: `import { ScrollArea } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/ScrollArea
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ScrollArea

## Props

- `children`: React.ReactNode
- `contentProps`: ContentProps — Layout and spacing of the scrollable content.
- `contentContainerStyle`: ScrollViewProps['contentContainerStyle'] — Escape hatch for native ScrollView content behavior.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'` or `'full'`.
- `borderWidth`: number — Border width
- `borderColor`: string — Border color
- `borderTopWidth`: number
- `borderRightWidth`: number
- `borderBottomWidth`: number
- `borderLeftWidth`: number
- `borderTopColor`: string
- `borderRightColor`: string
- `borderBottomColor`: string
- `borderLeftColor`: string
- `borderTopLeftRadius`: number
- `borderTopRightRadius`: number
- `borderStyle`: ViewStyle['borderStyle']
- `overflow`: ViewStyle['overflow']
- `aspectRatio`: number
- `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces.
- `translateY`: number — Small visual offset without affecting surrounding layout.
- `rotate`: string — Rotation around the block center, such as `"45deg"`.
- `shadow`: ShadowToken — Shadow: a `theme.shadows` token.
- `fullWidth`: boolean — Whether to take full width (100%) - shorthand for w="full"; an explicit `w` wins
- `fluid`: boolean — Makes block take full available height (flex: 1) - useful for scrollable containers
- `grow`: boolean | number — Flex grow
- `shrink`: boolean | number — Flex shrink
- `basis`: number | string — Flex basis
- `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction
- `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items
- `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent.
- `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content
- `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap
- `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). Defaults to `'sm'`; pass `0` to remove it.
- `position`: 'relative' | 'absolute' — Position type
- `top`: number | string — Top position
- `right`: number | string — Right position (physical; use `end` to mirror in right-to-left layouts)
- `bottom`: number | string — Bottom position
- `left`: number | string — Left position (physical; use `start` to mirror in right-to-left layouts)
- `inset`: number | string — Shorthand for all four physical insets.
- `start`: number | string — Start inset (logical: left in LTR, right in RTL)
- `end`: number | string — End inset (logical: right in LTR, left in RTL)
- `zIndex`: number — Z-index
- `flex`: boolean | number — Whether to render as a flex container

Plus the `Block` props (`className` `onPress` `onLongPress` `onPressIn` `onPressOut` `onMouseEnter` `onMouseLeave` `disabled`): https://plocks.dev/llms/components/Block.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
type ContentProps = BlockStyleProps & StyleProps;
```

## Examples

### Basics

ScrollArea provides a scrollable container with named layout and spacing props.

```tsx
import { Block, ScrollArea, Text } from '@plocks/ui';

export function Demo() {
  return (
    <ScrollArea fullWidth h={180} contentProps={{ p: 'md', gap: 'sm' }}>
      {Array.from({ length: 8 }, (_, index) => (
        <Block key={index} bg="subtle" p="sm">
          <Text>Item {index + 1}</Text>
        </Block>
      ))}
    </ScrollArea>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Scroller.md -->

# Scroller

Use Scroller for horizontal content that should preserve native scrolling and expose visible navigation controls.

## Metadata

- Import: `import { Scroller } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Scroller
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Scroller

## Props

- `children` (required): React.ReactNode
- `controlSize`: SizeValue — Control button size.
- `startControlIcon`: React.ReactNode — Replaces the start chevron.
- `endControlIcon`: React.ReactNode — Replaces the end chevron.
- `startControlProps`: Partial<IconButtonProps> — Props forwarded to the start button.
- `endControlProps`: Partial<IconButtonProps> — Props forwarded to the end button.
- `showStartControl`: boolean — Always show the start button.
- `showEndControl`: boolean — Always show the end button.
- `edgeGradientColor`: string — Gradient end color.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `scrollAmount`: number
- `draggable`: boolean

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useScroller({ scrollAmount = 200, draggable = true }: UseScrollerOptions = {}): UseScrollerReturn`

## Examples

### Basics

Controls appear only when there is content to scroll in their direction.

```tsx
import { Badge, Block, Scroller } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Scroller>
        {Array.from({ length: 20 }, (_, i) => (
          <Badge key={i} m="xs">
            Badge {i + 1}
          </Badge>
        ))}
      </Scroller>
    </Block>
  );
}
```

### Controls and Scroll Amount

`controlSize` and `scrollAmount` tune the edge controls and their movement.

```tsx
import { Badge, Block, Scroller } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Scroller scrollAmount={300} controlSize="lg" showEndControl>
        {Array.from({ length: 20 }, (_, i) => (
          <Badge key={i} m="xs">
            Item {i + 1}
          </Badge>
        ))}
      </Scroller>
    </Block>
  );
}
```

### Mouse Drag Scrolling

Drag with a mouse on web; touch scrolling remains native.

```tsx
import { Badge, Block, Scroller } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Scroller draggable>
        {Array.from({ length: 20 }, (_, i) => (
          <Badge key={i} m="xs">
            Item {i + 1}
          </Badge>
        ))}
      </Scroller>
    </Block>
  );
}
```

### Custom Icons

`startControlIcon` and `endControlIcon` replace the chevrons.

```tsx
import { Badge, Block, Icon, Scroller } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Scroller
        startControlIcon={<Icon name="arrow-left" />}
        endControlIcon={<Icon name="arrow-right" />}
        showStartControl
        showEndControl
      >
        {Array.from({ length: 20 }, (_, i) => (
          <Badge key={i} m="xs">
            Item {i + 1}
          </Badge>
        ))}
      </Scroller>
    </Block>
  );
}
```

### Tab-like Chips

Scroller can hold a long horizontal row of navigation chips.

```tsx
import { Block, Chip, Scroller } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Scroller>
        {Array.from({ length: 16 }, (_, i) => (
          <Chip key={i} m="xs">
            Section {i + 1}
          </Chip>
        ))}
      </Scroller>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Search.md -->

# Search

Search provides a text field with debouncing, loading feedback, and a clear control.

## Metadata

- Import: `import { Search } from '@plocks/ui';`
- Tags: search, input, filter, debounce
- Docs: https://plocks.dev/components/Search
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Search

## Props

- `value`: string — Controlled query.
- `defaultValue`: string — Initial query while uncontrolled.
- `onChangeText`: (value: string) => void — Called with the query as the user types (after `debounce` ms when set).
- `onSubmit`: (value: string) => void — Called with the query on Enter, and with `''` when cleared.
- `placeholder`: string
- `size`: SizeValue
- `radius`: RadiusValue
- `autoFocus`: boolean
- `debounce`: number — Delay (ms) before `onChangeText` fires; typing still shows immediately.
- `clearButton`: boolean — Show a clear button while there is a query. Default true.
- `clearButtonLabel`: string — Accessible name of the clear button. Default `'Clear search'`.
- `loading`: boolean — Show a loading indicator in place of the clear button.
- `endSection`: React.ReactNode
- `accessibilityLabel`: string — Accessible name of the field (or the button in `buttonMode`). Default `'Search'`.
- `disabled`: boolean
- `buttonMode`: boolean — When true, renders as a button (e.g. a Spotlight launcher) instead of a typeable input
- `onPress`: () => void — Called when the button is pressed (buttonMode only)
- `rightComponent`: React.ReactNode — Component to render on the right side (useful for button mode to show shortcuts like CMD+K)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Control the `Search` value with local state so you can react to user input and mirror the query elsewhere in your UI.

```tsx
import { useState } from 'react';
import { Block, Search, Text } from '@plocks/ui';

export function Demo() {
  const [query, setQuery] = useState('');

  return (
    <Block maw={320} w="100%">
      <Search value={query} onChangeText={setQuery} placeholder="Search docs" />
      <Text size="xs" c="muted">
        Current query: {query || '—'}
      </Text>
    </Block>
  );
}
```

### Button mode

Set `buttonMode` to turn `Search` into a pressable launcher — for example `onPress={() => spotlight.open()}` with `@plocks/spotlight` — and pass a `rightComponent` with `KeyCap` shortcuts so users discover keyboard access.

```tsx
import { KeyCap, Row, Search, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  return (
    <Search
      buttonMode
      maw={420}
      placeholder="Search the workspace"
      onPress={() => toast.show({ message: 'Open your search here' })}
      rightComponent={(
        <Row gap="xs" align="center">
          <KeyCap size="xs">⌘</KeyCap>
          <KeyCap size="xs">K</KeyCap>
        </Row>
      )}
    />
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/SegmentedControl.md -->

# SegmentedControl

SegmentedControl lets users choose one option from a small set of segments.

## Metadata

- Import: `import { SegmentedControl } from '@plocks/ui';`
- Status: beta
- Tags: input, segmentation, toggle, selection
- Docs: https://plocks.dev/components/SegmentedControl
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/SegmentedControl

## Props

- `data` (required): SegmentedControlData[] — Data that defines the segments
- `value`: string — Controlled value
- `defaultValue`: string — Uncontrolled initial value
- `onChange`: (value: string) => void — Called when value changes
- `size`: SizeValue — Control size, maps to height and font size
- `color`: ColorProp — Indicator color: palette token, `'primary.6'` shade syntax, or CSS color
- `orientation`: 'horizontal' | 'vertical' — Layout orientation
- `fullWidth`: boolean — Stretch across available width
- `disabled`: boolean — Disable entire control
- `readOnly`: boolean — Prevent user interaction but keep visual state
- `autoContrast`: boolean — Adjust text color automatically for filled/outline variants
- `withItemsBorders`: boolean — Render dividers between items
- `transitionDuration`: number — Indicator transition duration (ms)
- `transitionTimingFunction`: string — Indicator transition easing
- `name`: string — Radio group name; also the group's accessible name when there is no label
- `variant`: 'default' | 'filled' | 'outline' | 'ghost' — Visual style variant
- `indicatorStyle`: StyleProp<ViewStyle> — Custom style for indicator
- `itemStyle`: StyleProp<ViewStyle> — Custom style applied to every item
- `accessibilityLabel`: string — Accessibility label for the entire control
- `label`: ReactNode — Optional label rendered alongside the control
- `description`: ReactNode — Supplementary description text rendered with the label
- `labelPosition`: 'left' | 'right' | 'top' | 'bottom' — Placement of the label relative to the control (`left` / `right` follow the reading direction)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type SegmentedControlData = string | SegmentedControlItem;

export interface SegmentedControlItem {
  /** Unique value returned in change events */
  value: string;
  /** Item label, string will be rendered with Text component */
  label: ReactNode;
  /** Disable this specific segment */
  disabled?: boolean;
  /** Screen reader label override (required when `label` isn't a string) */
  ariaLabel?: string;
  /** Optional test identifier for automation */
  testID?: string;
}
```

## Examples

### Basics

Set `defaultValue` to preselect a segment and let the control manage focus and selection state internally.

```tsx
import { SegmentedControl } from '@plocks/ui';

const frameworks = [
  { label: 'React', value: 'react' },
  { label: 'Angular', value: 'angular' },
  { label: 'Vue', value: 'vue' },
];

export function Demo() {
  return (
    <SegmentedControl defaultValue="react" data={frameworks} />
  );
}
```

### Controlled Value

Provide `value` and `onChange` to synchronize the selected segment with external state or companion controls.

```tsx
import { useState } from 'react';
import { Block, SegmentedControl, Text } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState('React');

  return (
    <Block>
      <SegmentedControl value={value} onChange={setValue} data={['React', 'Angular', 'Vue']} />
      <Text size="xs" c="secondary">
        Selected value: {value}
      </Text>
    </Block>
  );
}
```

### Sizes

Use the `size` prop to match dense toolbars or spacious layouts without changing the underlying data.

```tsx
import { Block, SegmentedControl, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" c="secondary">{size}</Text>
          <SegmentedControl size={size} data={['React', 'Angular', 'Vue']} defaultValue="React" />
        </Block>
      ))}
    </Block>
  );
}
```

### Full Width

Apply `fullWidth` to let segments expand and distribute evenly across the available horizontal space.

```tsx
import { SegmentedControl } from '@plocks/ui';

export function Demo() {
  return (
    <SegmentedControl fullWidth defaultValue="Preview" data={['Preview', 'Code', 'Export']} />
  );
}
```

### Orientation

Toggle the `orientation` prop to rotate the control vertically for sidebars or keep it horizontal for toolbars.

```tsx
import { Row, SegmentedControl } from '@plocks/ui';

const data = ['React', 'Angular', 'Vue'];

export function Demo() {
  return (
    <Row gap="lg" align="flex-start" wrap="wrap">
      <SegmentedControl
        label="Horizontal (default)"
        orientation="horizontal"
        defaultValue="React"
        data={data}
      />
      <SegmentedControl
        label="Vertical"
        orientation="vertical"
        defaultValue="React"
        data={data}
      />
    </Row>
  );
}
```

### Custom Colors

Set the `color` prop to pull semantic tokens or pass custom values, and enable `autoContrast` when you need readable labels on vivid fills.

```tsx
import { Block, SegmentedControl } from '@plocks/ui';

const data = ['React', 'Angular', 'Vue'];

export function Demo() {
  return (
    <Block>
      <SegmentedControl color="primary" defaultValue="React" data={data} />
      <SegmentedControl color="success" defaultValue="React" data={data} />
      <SegmentedControl color="purple" defaultValue="React" data={data} />
      <SegmentedControl color="#FF6B6B" autoContrast defaultValue="React" data={data} />
    </Block>
  );
}
```

### Interaction States

Combine `disabled`, `readOnly`, or per-item `disabled` flags to signal availability without changing layout or selection rules.

```tsx
import { Block, SegmentedControl } from '@plocks/ui';

const data = ['React', 'Angular', 'Vue'];

export function Demo() {
  return (
    <Block>
      <SegmentedControl label="Disabled" disabled defaultValue="React" data={data} />
      <SegmentedControl label="Read only" readOnly defaultValue="React" data={data} />
      <SegmentedControl
        label="Single option disabled"
        defaultValue="React"
        data={['React', 'Angular', { label: 'Vue', value: 'Vue', disabled: true }]}
      />
    </Block>
  );
}
```

### Visual Variants

Choose between `default`, `filled`, `outline`, or `ghost` variants and pair them with semantic `color` tokens to match the surrounding surface.

```tsx
import { Block, SegmentedControl } from '@plocks/ui';

const data = ['React', 'Angular', 'Vue'];

export function Demo() {
  return (
    <Block>
      <SegmentedControl label="Default" variant="default" defaultValue="React" data={data} />
      <SegmentedControl label="Filled" variant="filled" defaultValue="React" data={data} />
      <SegmentedControl label="Outline" variant="outline" color="secondary" defaultValue="React" data={data} />
      <SegmentedControl label="Ghost" variant="ghost" color="success" defaultValue="React" data={data} />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Select.md -->

# Select

Select provides a dropdown interface for choosing from predefined options. It supports single and multi-selection modes, disabled states, validation, and customizable styling.

## Metadata

- Import: `import { Select } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Select
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Select

## Props

- `value`: T | null — Current value when the component is controlled. `null` = nothing selected.
- `defaultValue`: T | null — Initial value when the component manages its own state.
- `onChange`: (value: T | null, option: SelectOption<T> | null) => void — Called with the new value and its option (`null, null` when cleared).
- `options` (required): SelectOption<T>[] — Collection of options available to choose from.
- `placeholder`: string = 'Select…' — Placeholder text shown when no value is selected.
- `searchable`: boolean = false — Adds a filter input at the top of the dropdown.
- `searchPlaceholder`: string = 'Search…' — Placeholder of the filter input. @default 'Search…'
- `nothingFoundMessage`: string = 'Nothing found' — Shown when the filter matches nothing. @default 'Nothing found'
- `renderOption`: (opt: SelectOption<T>, active: boolean, selected: boolean) => React.ReactNode — Custom renderer for an individual option row (the row stays an accessible option).
- `maxDropdownHeight`: number = 260 — Maximum height the dropdown may reach before it scrolls. @default 260
- `closeOnSelect`: boolean = true — Whether the dropdown closes after a selection. @default true
- `clearable`: boolean = false — Allows the user to clear the current selection.
- `refocusAfterSelect`: boolean = true — Whether the trigger keeps focus after a selection (web). `false` blurs it.
- `keyboardAvoidance`: boolean = true — Whether dropdown positioning should avoid the on-screen keyboard. @default true
- `onDropdownOpen`: () => void — Called when the dropdown opens.
- `onDropdownClose`: () => void — Called when the dropdown closes.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholderTextColor` `clearButtonLabel` `onClear` `startSection` `startSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { PickerTrigger } from '@plocks/ui';`

### PickerTrigger

- `triggerRef`: React.Ref<View> — Ref of the pressable trigger — the focus target and the floating anchor.
- `triggerProps`: PickerTriggerElementProps — Spread on the trigger (role, aria-*, id, onKeyDown, …).
- `onPress` (required): (event: GestureResponderEvent) => void
- `displayValue`: string — Text shown in the box. Empty / undefined shows the placeholder.
- `placeholder`: string
- `placeholderTextColor`: string
- `size`: SizeValue
- `radius`: RadiusValue
- `variant`: 'default' | 'filled' | 'outline' | 'unstyled'
- `opened`: boolean — Dropdown open: the frame border takes the accent color.
- `invalid`: boolean
- `disabled`: boolean
- `readOnly`: boolean
- `startSection`: React.ReactNode
- `endSection`: React.ReactNode — Trailing affordance (chevron / calendar). Decorative: hidden from assistive technology.
- `startSectionProps`: Omit<ViewProps, 'children'>
- `endSectionProps`: Omit<ViewProps, 'children'>
- `showClear`: boolean — Show the clear button (a sibling of the trigger, never nested in it).
- `onClear`: () => void
- `clearButtonLabel`: string
- `testID`: string
- `frameStyle`: StyleProp<ViewStyle> — Extra styles for the frame (merged last).

## Types

```ts
export interface SelectOption<T = any> {
  /** Human-readable text displayed for the option. */
  label: string;
  /** Value returned when the option is chosen. */
  value: T;
  /**
   * Secondary line rendered under the label inside the dropdown. The trigger
   * still shows the label alone, so this is for disambiguating options, not for
   * copy the user needs after choosing.
   */
  description?: string;
  /** When true, the option renders but cannot be selected. */
  disabled?: boolean;
}

export type PickerTriggerElementProps = Omit<PressableProps, 'style' | 'children' | 'onPress' | 'disabled'>;
```

## Examples

### Basics

Simple single-value select with helper copy and live selection feedback.

```tsx
import { Select } from '@plocks/ui'
import { sports } from '../data'

export function Demo() {
  return (
    <Select
      label="Favorite sport"
      description="Choose your favorite sport"
      placeholder="Choose a sport"
      options={sports}
    />
  )
}
```

`data.ts`

```ts
import type { SelectOption } from '@plocks/ui';

export const sports: SelectOption<string>[] = [
  { label: 'Soccer', value: 'soccer' },
  { label: 'Basketball', value: 'basketball' },
  { label: 'Tennis', value: 'tennis' },
  { label: 'Football', value: 'football' },
]

/** Emoji and blurb are only needed by the custom rendering demo. */
export const detailedSports = [
  { name: 'Soccer', emoji: '⚽', value: 'soccer', description: 'Continuous play across two 45-minute halves.' },
  { name: 'Basketball', emoji: '🏀', value: 'basketball', description: 'Fast breaks balanced with half-court sets.' },
  { name: 'Tennis', emoji: '🎾', value: 'tennis', description: 'Sets decided by holding and breaking serve.' },
  { name: 'Football', emoji: '🏈', value: 'football', description: 'Down-by-down strategy on a 100-yard field.' },
].map((sport) => ({ ...sport, label: `${sport.emoji} ${sport.name}` }))

export type DetailedSport = (typeof detailedSports)[number]
```

### Variants

`Select` accepts the same `variant` prop as `<Input>` — `default`, `filled`, `outline`, `unstyled` — and shares the underlying input styles, so the trigger reads consistently with text inputs in the same form.

```tsx
import { useState } from 'react'
import { Block, Select } from '@plocks/ui'
import { sports } from '../data'

const variants = [
  { variant: 'default', label: 'Default' },
  { variant: 'filled', label: 'Filled' },
  { variant: 'outline', label: 'Outline' },
  { variant: 'unstyled', label: 'Unstyled' },
] as const

export function Demo() {
  const [value, setValue] = useState<string | null>(null)

  return (
    <Block flex>
      {variants.map(({ variant, label }) => (
        <Select
          key={variant}
          variant={variant}
          label={label}
          placeholder="Pick one…"
          options={sports}
          value={value}
          onChange={(v) => setValue(v as string | null)}
        />
      ))}
    </Block>
  )
}
```

`data.ts` is the same file shown under “Basics” above.

### Custom rendering

Render each option with additional detail and selection styling using `renderOption`.

```tsx
import { useState } from 'react'
import { Block, Icon, Select, Text, useTheme } from '@plocks/ui'
import { detailedSports, type DetailedSport } from '../data'

export function Demo() {
  const theme = useTheme()
  const [value, setValue] = useState<string | null>(detailedSports[0].value)
  const accent = theme.colorScheme === 'dark' ? theme.colors.primary[5] : theme.colors.primary[6]

  return (
    <Block w={400}>
      <Select
        label="Choose a sport"
        placeholder="Pick a sport"
        options={detailedSports}
        value={value}
        onChange={(selected) => setValue(selected as string)}
        renderOption={(option, active, selected) => {
          const { emoji, name, description } = option as DetailedSport

          return (
            <Block
              direction="row"
              align="center"
              gap={12}
              style={{
                padding: 12,
                borderLeftWidth: 3,
                borderLeftColor: active || selected ? accent : 'transparent',
                backgroundColor: selected ? theme.colors.primary[0] : undefined,
              }}
            >
              <Text size="3xl">{emoji}</Text>
              <Block direction="column" style={{ flex: 1 }} gap={0}>
                <Text fw={selected ? '900' : '600'}>{name}</Text>
                <Text size="sm" c="secondary">
                  {description}
                </Text>
              </Block>
              {selected ? <Icon name="check" size={16} color={accent} /> : null}
            </Block>
          )
        }}
      />
    </Block>
  )
}
```

`data.ts` is the same file shown under “Basics” above.

### Disabled states

Disable individual options or the full control to reflect availability.

```tsx
import { useState } from 'react'
import { Block, Select } from '@plocks/ui'
import { sports } from '../data'

// One option is taken out of play to show the per-option disabled state next to
// the whole-field one.
const options = sports.map((option) =>
  option.value === 'basketball' ? { ...option, label: 'Basketball (disabled)', disabled: true } : option,
)

export function Demo() {
  const [value, setValue] = useState<string | null>(sports[0].value)

  return (
    <Block flex direction="row">
      <Select
        label="Disabled option example"
        options={options}
        value={value}
        onChange={(val) => setValue(val as string)}
      />
      <Select label="Entire select disabled" options={options} value={value} disabled />
    </Block>
  )
}
```

`data.ts` is the same file shown under “Basics” above.

### Persistent menu

Keep the dropdown open after each choice for quick comparisons.

```tsx
import { useState } from 'react'
import { Select } from '@plocks/ui'
import { sports } from '../data'

export function Demo() {
  const [value, setValue] = useState<string | null>(null)

  return (
    <Select
      label="Persistent menu"
      description="Menu doesn't close on option press"
      options={sports}
      value={value}
      onChange={(val) => setValue(val as string)}
      closeOnSelect={false}
    />
  )
}
```

`data.ts` is the same file shown under “Basics” above.

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ShimmerText.md -->

# ShimmerText

Animated text highlight that sweeps a configurable gradient across the content. Ideal for loading states, premium callouts, and attention-grabbing text accents.

## Metadata

- Import: `import { ShimmerText } from '@plocks/ui';`
- Tags: text, shimmer, animation, gradient
- Docs: https://plocks.dev/components/ShimmerText
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/ShimmerText

## Props

- `children`: ReactNode — Text node children. Overrides `text` when provided
- `text`: string — Text content to render when not using children
- `c`: string — Base text color rendered underneath the shimmer. Default: `theme.text.muted`.
- `colors`: string[] — Optional gradient stops override
- `shimmerColor`: string — Highlight color used for the shimmer pass. Default: `theme.text.primary`.
- `spread`: number — Width of the highlight band as a multiple of the text width (higher = wider highlight). The band always travels from fully clear of one edge to fully clear of the other, so this also sets how far it moves per cycle.
- `duration`: number — Duration of a single shimmer cycle in seconds
- `delay`: number — Delay before the shimmer starts (seconds)
- `repeatDelay`: number — Pause held at the end of each cycle, with the band off screen (seconds)
- `repeat`: boolean — Whether the shimmer should repeat indefinitely
- `once`: boolean — Animate only once after becoming visible
- `direction`: 'ltr' | 'rtl' — Direction of shimmer movement
- `debug`: boolean — Enable verbose logging for debugging
- `onLayout`: TextProps['onLayout'] — Called with the layout of the shimmer container
- `startOnView`: boolean — Start shimmering once the component enters the viewport (web only)
- `inViewMargin`: string — `rootMargin` for the `startOnView` IntersectionObserver (web only)
- `containerStyle`: StyleProp<ViewStyle> — Style for the wrapping container view (style props apply here too).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Text` props (`tx` `txParams` `variant` `textRole` `size` `fw` `ta` `lh` `lts` `tt` `fs` `td` `ff` `flex` `shrink` `position` `top` `right` `bottom` `left` `as` `selectable` `onPress` `numberOfLines` `ellipsizeMode` `id` `nativeID`): https://plocks.dev/llms/components/Text.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Wrap text in `ShimmerText` to add the default looping highlight with no additional configuration.

```tsx
import { Block, ShimmerText } from '@plocks/ui';

export function Demo() {
  return (
    <Block align="flex-start">
      <ShimmerText size="xl" fw="bold">
        Weekly highlights go live
      </ShimmerText>
      <ShimmerText>
        New arrivals shimmer into view every Friday at noon.
      </ShimmerText>
    </Block>
  );
}
```

### Interactive controls

Expose `spread`, `repeat`, and `once` controls to let readers tune the shimmer loop at runtime.

```tsx
import { useState } from 'react';
import { Block, Row, ShimmerText, Slider, Switch, Text } from '@plocks/ui';

const MIN_SPREAD = 1;
const MAX_SPREAD = 4;
const SPREAD_STEP = 0.1;

export function Demo() {
  const [spread, setSpread] = useState(2);
  const [repeat, setRepeat] = useState(true);
  const [once, setOnce] = useState(false);

  const handleRepeatChange = (value: boolean) => {
    setRepeat(value);
    if (value) {
      setOnce(false);
    }
  };

  const handleOnceChange = (value: boolean) => {
    setOnce(value);
    if (value) {
      setRepeat(false);
    }
  };

  return (
    <Block align="flex-start" fullWidth>
      <ShimmerText
        spread={spread}
        repeat={repeat}
        once={once}
        repeatDelay={0.6}
        duration={1.6}
        shimmerColor="#38bdf8"
        fw="bold"
        size="lg"
      >
        Interactive shimmer headline
      </ShimmerText>

      <Block w="100%">
        <Text variant="small" fw="medium">
          Spread: {spread.toFixed(1)}
        </Text>
        <Slider
          value={spread}
          onChange={setSpread}
          min={MIN_SPREAD}
          max={MAX_SPREAD}
          step={SPREAD_STEP}
        />
      </Block>

      <Block w="100%">
        <Row align="center" justify="space-between">
          <Text variant="small">Repeat animation</Text>
          <Switch checked={repeat} onChange={handleRepeatChange} />
        </Row>
        <Row align="center" justify="space-between">
          <Text variant="small">Run once</Text>
          <Switch checked={once} onChange={handleOnceChange} />
        </Row>
      </Block>
    </Block>
  );
}
```

### Variants

Compare semantic text variants while the shimmer animation stays the same.

```tsx
import { Column, ShimmerText, Text } from '@plocks/ui';

const variants = ['h3', 'p', 'small'] as const;

export function Demo() {
  return (
    <Column gap="md">
      {variants.map(variant => (
        <Column key={variant} gap="xs">
          <Text size="xs" c="secondary">{variant}</Text>
          <ShimmerText variant={variant}>New arrivals this week</ShimmerText>
        </Column>
      ))}
    </Column>
  );
}
```

### Customization options

Combine custom color stops, timing tweaks, and direction to align the shimmer with your brand voice.

```tsx
import { Block, ShimmerText } from '@plocks/ui';

export function Demo() {
  return (
    <Block align="flex-start">
      <ShimmerText shimmerColor="#facc15" spread={3} fw="bold" size="xl">
        Golden spotlight offer
      </ShimmerText>
      <ShimmerText
        c="#475569"
        shimmerColor="#38bdf8"
        spread={1.2}
        duration={1.2}
        repeatDelay={0.2}
      >
        Fast pulse notification
      </ShimmerText>
      <ShimmerText direction="rtl" repeatDelay={0.8}>
        Shimmer sweeps from right to left
      </ShimmerText>
      <ShimmerText once repeat={false} delay={0.5}>
        Single pass announcement
      </ShimmerText>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Skeleton.md -->

# Skeleton

Skeleton components provide visual placeholders for text, avatars, and blocks to reduce perceived loading time.

## Metadata

- Import: `import { Skeleton } from '@plocks/ui';`
- Tags: loading, placeholder, skeleton
- Docs: https://plocks.dev/components/Skeleton
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Skeleton

## Props

- `shape`: 'text' | 'chip' | 'avatar' | 'button' | 'card' | 'circle' | 'rectangle' | 'rounded' = 'rectangle' — Shape of the skeleton placeholder
- `size`: SizeValue = 'md' — Size of the skeleton component (a control-size token or px; `w`/`h` win)
- `radius`: RadiusValue — Corner radius: theme radius token, px, `'none'` or `'full'`. Defaults per shape.
- `animate`: boolean = true — Whether to show the loading (pulse) animation. Never runs while reduced motion is on.
- `animationDuration`: number = 1500 — Duration of the loading animation in milliseconds
- `colors`: [string, string] — Base and highlight colors of the pulse. Defaults to `backgrounds.border` / `backgrounds.borderStrong`.
- `accessibilityLabel`: string — Announce the placeholder as a loading status with this name (`role="status"`, `aria-busy`). Without it the skeleton is decorative and hidden from assistive technology — label the region that is loading instead.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Stack text, avatar, and block placeholders to preview the structure of incoming content while data loads.

```tsx
import { Block, Row, Skeleton } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Skeleton shape="text" w="60%" />
      <Skeleton shape="text" w="80%" />
      <Skeleton shape="text" w="40%" />
      <Row gap="md" align="center">
        <Skeleton shape="avatar" size="lg" />
        <Block grow={1}>
          <Skeleton shape="text" w="40%" />
          <Skeleton shape="text" w="60%" />
        </Block>
      </Row>
      <Skeleton shape="rectangle" h={120} />
      <Skeleton shape="button" w={120} />
    </Block>
  );
}
```

### Shapes

Preview the available skeleton shapes for avatars, typography lines, actions, and media blocks.

```tsx
import { Block, Row, Skeleton } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Row gap="lg" align="center" wrap="wrap">
        <Skeleton shape="avatar" size="sm" />
        <Skeleton shape="avatar" size="md" />
        <Skeleton shape="avatar" size="lg" />
        <Skeleton shape="avatar" size="xl" />
      </Row>
      <Block>
        <Skeleton shape="text" w="100%" />
        <Skeleton shape="text" w="90%" />
        <Skeleton shape="text" w="70%" />
      </Block>
      <Row gap="md" wrap="wrap">
        <Skeleton shape="button" w={80} />
        <Skeleton shape="button" w={100} />
        <Skeleton shape="button" w={120} />
      </Row>
      <Row gap="sm" wrap="wrap">
        <Skeleton shape="chip" />
        <Skeleton shape="chip" />
        <Skeleton shape="chip" />
      </Row>
      <Skeleton shape="rectangle" h={60} />
      <Skeleton shape="card" h={200} />
    </Block>
  );
}
```

### Card Layout

Combine avatar, text, and action placeholders to preview a rich card layout ahead of remote content.

```tsx
import { Block, Row, Skeleton, useTheme } from '@plocks/ui';

export function Demo() {
  const theme = useTheme();

  return (
    <Block
      p="lg"
      radius="lg"
      borderWidth={1}
      borderColor={theme.backgrounds.border}
      bg={theme.backgrounds.surface}
    >
      <Block>
        <Row gap="md" align="center">
          <Skeleton shape="avatar" size="lg" />
          <Block grow={1}>
            <Skeleton shape="text" w="32%" />
            <Skeleton shape="text" w="48%" />
          </Block>
        </Row>
        <Skeleton shape="rectangle" h={120} />
        <Block>
          <Skeleton shape="text" w="100%" />
          <Skeleton shape="text" w="78%" />
        </Block>
        <Row gap="sm" wrap="wrap">
          <Skeleton shape="chip" />
          <Skeleton shape="chip" />
          <Skeleton shape="chip" />
        </Row>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Slider.md -->

# Slider

Slider lets users select a value or range by moving handles along a track.

## Metadata

- Import: `import { Slider } from '@plocks/ui';`
- Tags: slider, range, input, numeric, control
- Docs: https://plocks.dev/components/Slider
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Slider

## Props

- `value`: number — Value (controlled).
- `defaultValue`: number — Initial value (uncontrolled).
- `onChange`: (value: number) => void — Called with every value change (each frame of a drag, each key press).
- `onChangeEnd`: (value: number) => void — Called once when an interaction settles: drag released, or after each key press.
- `valueLabel`: ((value: number) => string) | null — Value label formatter (also the spoken value text); `null` hides the label.
- `min`: number = 0 — Minimum value. Default 0.
- `max`: number = 100 — Maximum value. Default 100.
- `step`: number = 1 — Step increment (arrow keys, snapping). Default 1.
- `largeStep`: number — PageUp / PageDown distance. Default: a tenth of the range.
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Slider orientation. Default `'horizontal'`.
- `inverted`: boolean = false — Reverse the direction: the maximum sits at the start (left) of a horizontal slider, or at the bottom of a vertical one.
- `trackColor`: ThemeColor — Inactive track color.
- `activeTrackColor`: ThemeColor — Active track color.
- `thumbColor`: ThemeColor — Thumb color.
- `trackSize`: number — Track thickness (px).
- `thumbSize`: number — Thumb diameter (px).
- `color`: ThemeColor — Color driving the active track, thumb, and active ticks: a palette token, `'primary.6'` shade syntax, or any CSS color.
- `variant`: 'default' | 'filled' | 'outline' | 'minimal' | 'segmented' | 'unstyled' = 'default' — Visual variant of the slider track + thumb. Defaults to `'default'`.
- `trackStyle`: StyleProp<ViewStyle> — Additional styling for the inactive track.
- `activeTrackStyle`: StyleProp<ViewStyle> — Additional styling for the active track.
- `thumbStyle`: StyleProp<ViewStyle> — Additional styling for the thumb(s).
- `tickColor`: ThemeColor — Inactive tick color.
- `activeTickColor`: ThemeColor — Active tick color.
- `tickStyle`: StyleProp<ViewStyle> — Style applied to inactive tick marks (merged on top of color/size defaults).
- `activeTickStyle`: StyleProp<ViewStyle> — Style applied to active tick marks.
- `tickLabelProps`: Omit<TextProps, 'children'> — Props applied to the `<Text>` rendered for each tick label (style, ff, weight, size, color).
- `valueLabelAlwaysOn`: boolean = false — Keep the value label visible even when not interacting.
- `tooltip`: 'always' | 'hover' | 'never' = 'hover' — When the value label (the bubble over the thumb) shows: `hover` (default) while hovered, dragged or keyboard-focused; `always`; or `never`.
- `valueLabelPosition`: 'top' | 'bottom' | 'left' | 'right' — Where the value label sits relative to the thumb: 'top' / 'bottom' (horizontal), 'left' / 'right' (vertical).
- `valueLabelOffset`: number — Pixel gap between the thumb and the value label (default: 6 for top/bottom, 16 for left/right).
- `valueLabelStyle`: StyleProp<ViewStyle> — Style applied to the value label wrapper (Card/View).
- `valueLabelProps`: Omit<TextProps, 'children'> — Props applied to the value label `<Text>` (style, fw, ff, size, c).
- `valueLabelAsCard`: boolean = true — Wrap the value label in a `<Card>` (default true); false renders the bare `<Text>`.
- `showMarks`: boolean = false — Label the two ends of the track with the min / max values.
- `ticks`: SliderTick[] — Custom ticks/marks to display on the slider.
- `showTicks`: boolean = false — Show automatic tick marks at every `step`.
- `restrictToTicks`: boolean = false — Restrict value changes (pointer and keyboard) to tick positions.
- `containerSize`: number — Slider length when not `fullWidth` (width for horizontal, height for vertical).
- `precision`: number — Decimal places of the default value label. Default: inferred from `step`.
- `fullWidth`: boolean = true — Stretch to fill the parent width (height when vertical). Default true.
- `id`: string — Base id: the field's label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { RangeSlider } from '@plocks/ui';`

### RangeSlider

- `value`: [number, number] — Range value `[start, end]` (controlled).
- `defaultValue`: [number, number] — Initial range (uncontrolled). Default `[min, max]`.
- `onChange`: (value: [number, number]) => void — Called with every change.
- `onChangeEnd`: (value: [number, number]) => void — Called once when an interaction settles: drag released, or after each key press.
- `valueLabel`: ((value: number, index: number) => string) | null — Value label formatter for each thumb (also the spoken value text); `null` hides the labels.
- `minRange`: number — Minimum distance kept between the thumbs. Default 0.
- `allowCross`: boolean — Let a thumb be dragged past the other (it becomes the other end of the range). Default `!pushOnOverlap`.
- `pushOnOverlap`: boolean — Thumbs stop at each other instead of crossing (default true). `allowCross` wins when both are set.
- `rangeLabels`: [string, string] — Accessible names of the two thumbs. Default `['Minimum', 'Maximum']`.
- `min`: number — Minimum value. Default 0.
- `max`: number — Maximum value. Default 100.
- `step`: number — Step increment (arrow keys, snapping). Default 1.
- `largeStep`: number — PageUp / PageDown distance. Default: a tenth of the range.
- `orientation`: 'horizontal' | 'vertical' — Slider orientation. Default `'horizontal'`.
- `inverted`: boolean — Reverse the direction: the maximum sits at the start (left) of a horizontal slider, or at the bottom of a vertical one.
- `trackColor`: ThemeColor — Inactive track color.
- `activeTrackColor`: ThemeColor — Active track color.
- `thumbColor`: ThemeColor — Thumb color.
- `trackSize`: number — Track thickness (px).
- `thumbSize`: number — Thumb diameter (px).
- `color`: ThemeColor — Color driving the active track, thumb, and active ticks: a palette token, `'primary.6'` shade syntax, or any CSS color.
- `variant`: 'default' | 'filled' | 'outline' | 'minimal' | 'segmented' | 'unstyled' — Visual variant of the slider track + thumb. Defaults to `'default'`.
- `trackStyle`: StyleProp<ViewStyle> — Additional styling for the inactive track.
- `activeTrackStyle`: StyleProp<ViewStyle> — Additional styling for the active track.
- `thumbStyle`: StyleProp<ViewStyle> — Additional styling for the thumb(s).
- `tickColor`: ThemeColor — Inactive tick color.
- `activeTickColor`: ThemeColor — Active tick color.
- `tickStyle`: StyleProp<ViewStyle> — Style applied to inactive tick marks (merged on top of color/size defaults).
- `activeTickStyle`: StyleProp<ViewStyle> — Style applied to active tick marks.
- `tickLabelProps`: Omit<TextProps, 'children'> — Props applied to the `<Text>` rendered for each tick label (style, ff, weight, size, color).
- `valueLabelAlwaysOn`: boolean — Keep the value label visible even when not interacting.
- `tooltip`: 'always' | 'hover' | 'never' — When the value label (the bubble over the thumb) shows: `hover` (default) while hovered, dragged or keyboard-focused; `always`; or `never`.
- `valueLabelPosition`: 'top' | 'bottom' | 'left' | 'right' — Where the value label sits relative to the thumb: 'top' / 'bottom' (horizontal), 'left' / 'right' (vertical).
- `valueLabelOffset`: number — Pixel gap between the thumb and the value label (default: 6 for top/bottom, 16 for left/right).
- `valueLabelStyle`: StyleProp<ViewStyle> — Style applied to the value label wrapper (Card/View).
- `valueLabelProps`: Omit<TextProps, 'children'> — Props applied to the value label `<Text>` (style, fw, ff, size, c).
- `valueLabelAsCard`: boolean — Wrap the value label in a `<Card>` (default true); false renders the bare `<Text>`.
- `showMarks`: boolean — Label the two ends of the track with the min / max values.
- `ticks`: SliderTick[] — Custom ticks/marks to display on the slider.
- `showTicks`: boolean — Show automatic tick marks at every `step`.
- `restrictToTicks`: boolean — Restrict value changes (pointer and keyboard) to tick positions.
- `containerSize`: number — Slider length when not `fullWidth` (width for horizontal, height for vertical).
- `precision`: number — Decimal places of the default value label. Default: inferred from `step`.
- `fullWidth`: boolean — Stretch to fill the parent width (height when vertical). Default true.
- `id`: string — Base id: the field's label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Basic slider usage for selecting numeric values within a range.

```tsx
import { useState } from 'react';
import { Block, Slider } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState(25);

  return (
    <Block fullWidth>
      <Slider accessibilityLabel="Volume" value={value} onChange={setValue} />
    </Block>
  );
}
```

### Slider variants

```tsx
import { Block, Slider } from '@plocks/ui';

const VARIANTS = ['default', 'filled', 'outline', 'minimal', 'segmented', 'unstyled'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {VARIANTS.map((variant) => (
        <Slider
          key={variant}
          label={variant}
          variant={variant}
          defaultValue={40}
          step={5}
          showTicks={variant === 'segmented'}
          restrictToTicks={variant === 'segmented'}
        />
      ))}
    </Block>
  );
}
```

### Ticks and Marks

Slider with visible tick marks and labeled values for better precision.

```tsx
import { Block, Slider } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Slider
        accessibilityLabel="Milestone"
        defaultValue={50}
        restrictToTicks
        ticks={[
          { value: 0, label: 'Min' },
          { value: 25 },
          { value: 50, label: 'Mid' },
          { value: 75 },
          { value: 100, label: 'Max' },
        ]}
      />
    </Block>
  );
}
```

### Range Slider

`RangeSlider` puts two thumbs on one track and its `value` is a `[min, max]` tuple, for filters such as price ranges.

```tsx
import { useState } from 'react';
import { Block, RangeSlider } from '@plocks/ui';

export function Demo() {
  const [priceRange, setPriceRange] = useState<[number, number]>([25, 75]);

  return (
    <Block fullWidth>
      <RangeSlider label="Price range" value={priceRange} onChange={setPriceRange} />
    </Block>
  );
}
```

### Value label customization

`valueLabelPosition` chooses where the thumb tooltip sits (`top` / `bottom` for horizontal, `left` / `right` for vertical). `valueLabelOffset` tunes the gap from the thumb. `valueLabelProps` accepts any `<Text>` props — `ff`, `fw`, `size`, `c`, `style` — and `valueLabelStyle` overrides the wrapper Card's style. Set `valueLabelAsCard={false}` for a flat tooltip with no Card chrome. Both `<Slider>` and `<RangeSlider>` accept the same set of props.

```tsx
import { Block, Slider, RangeSlider, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="small" c="secondary">Bottom</Text>
        <Slider
          accessibilityLabel="Value label below"
          defaultValue={60}
          valueLabelAlwaysOn
          valueLabelPosition="bottom"
          valueLabelOffset={2}
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">Custom text</Text>
        <Slider
          accessibilityLabel="Custom label text"
          defaultValue={72}
          valueLabelAlwaysOn
          valueLabelProps={{
            ff: 'monospace',
            fw: '700',
            size: 'md',
            c: 'primary',
          }}
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">Flat</Text>
        <Slider
          accessibilityLabel="Flat value label"
          defaultValue={72}
          valueLabelAlwaysOn
          valueLabelAsCard={false}
          valueLabelStyle={{
            backgroundColor: 'rgba(15, 23, 42, 0.92)',
            paddingHorizontal: 8,
            paddingVertical: 4,
            borderRadius: 6,
          }}
          valueLabelProps={{ ff: 'monospace', fw: '600', c: '#fff' }}
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">RangeSlider</Text>
        <RangeSlider
          accessibilityLabel="Range with labels below"
          defaultValue={[20, 80]}
          valueLabelAlwaysOn
          valueLabelPosition="bottom"
          valueLabelProps={{ fw: '700', size: 'sm' }}
          valueLabel={(v, i) => (i === 0 ? `min ${Math.round(v)}` : `max ${Math.round(v)}`)}
        />
      </Block>

      <Block direction="row" justify="center" gap="xl">
        <Block align="center">
          <Text variant="small" c="secondary">Left</Text>
          <Block style={{ height: 200 }}>
            <Slider
              accessibilityLabel="Vertical, label left"
              defaultValue={40}
              orientation="vertical"
              valueLabelAlwaysOn
              valueLabelPosition="left"
              valueLabelProps={{ fw: '700' }}
            />
          </Block>
        </Block>
        <Block align="center">
          <Text variant="small" c="secondary">Right</Text>
          <Block style={{ height: 200 }}>
            <Slider
              accessibilityLabel="Vertical, label right"
              defaultValue={60}
              orientation="vertical"
              valueLabelAlwaysOn
              valueLabelPosition="right"
              valueLabelProps={{ fw: '700' }}
            />
          </Block>
        </Block>
      </Block>
    </Block>
  );
}
```

### Decimal steps & precision

The thumb tooltip formats its value from the `step`: a fractional step like `0.01` shows two decimals, while an integer step rounds to a whole number (trailing zeros are trimmed, so `0.10` reads as `0.1`). Pass `precision` to force a fixed number of decimals regardless of the step.

```tsx
import { Block, Slider, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="small" c="secondary">step 0.01</Text>
        <Slider
          accessibilityLabel="Position"
          defaultValue={0.25}
          max={1}
          step={0.01}
          valueLabelAlwaysOn
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">step 0.5</Text>
        <Slider
          accessibilityLabel="Temperature"
          defaultValue={21.5}
          min={16}
          max={30}
          step={0.5}
          valueLabelAlwaysOn
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">precision 2</Text>
        <Slider
          accessibilityLabel="Ratio"
          defaultValue={0.5}
          max={1}
          step={0.1}
          precision={2}
          valueLabelAlwaysOn
        />
      </Block>
    </Block>
  );
}
```

### Slot styling

Each visual layer of the slider is independently customizable: `trackStyle` and `activeTrackStyle` for the track halves, `thumbStyle` for the handle, `tickStyle` / `activeTickStyle` for tick marks, and `tickLabelProps` for tick labels. Per-tick `style` overrides on individual `ticks[i].style` win over the global tick styles. Combined with the value-label slot props (`valueLabelStyle`, `valueLabelProps`) you can fully reskin the slider without forking it.

```tsx
import { Block, Slider, RangeSlider, Text } from '@plocks/ui';

const milestoneTicks = [
  { value: 0, label: '0' },
  { value: 25, label: '25' },
  { value: 50, label: '50' },
  { value: 75, label: '75' },
  { value: 100, label: '100' },
];

const milestoneTicksWithHighlight = milestoneTicks.map((t) =>
  t.value === 50
    ? {
        ...t,
        style: {
          width: 4,
          height: 14,
          backgroundColor: '#facc15',
          borderRadius: 2,
          top: 11,
        },
      }
    : t,
);

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="small" c="secondary">Track and thumb</Text>
        <Slider
          accessibilityLabel="Track and thumb overrides"
          defaultValue={35}
          trackStyle={{ height: 10, borderRadius: 2 }}
          activeTrackStyle={{ height: 10, borderRadius: 2 }}
          thumbStyle={{ borderRadius: 4, borderWidth: 0 }}
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">Ticks and tick labels</Text>
        <Slider
          accessibilityLabel="Tick styling"
          defaultValue={50}
          ticks={milestoneTicks}
          tickStyle={{ width: 3, height: 10, borderRadius: 1.5, top: 13 }}
          activeTickStyle={{ width: 3, height: 12, borderRadius: 1.5, top: 12 }}
          tickLabelProps={{ ff: 'monospace', size: 'xs', fw: '700' }}
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">Per-tick style</Text>
        <Slider
          accessibilityLabel="Per-tick override"
          defaultValue={50}
          ticks={milestoneTicksWithHighlight}
          tickStyle={{ width: 3, height: 10, borderRadius: 1.5, top: 13 }}
          activeTickStyle={{ width: 3, height: 10, borderRadius: 1.5, top: 13 }}
          tickLabelProps={{ size: 'xs' }}
        />
      </Block>

      <Block>
        <Text variant="small" c="secondary">RangeSlider</Text>
        <RangeSlider
          accessibilityLabel="Range with slot styling"
          defaultValue={[20, 80]}
          ticks={milestoneTicks}
          activeTrackColor="#a855f7"
          trackStyle={{ height: 8, borderRadius: 4 }}
          activeTrackStyle={{ height: 8, borderRadius: 4 }}
          thumbStyle={{ backgroundColor: '#a855f7', borderColor: '#7e22ce', borderWidth: 2 }}
          tickStyle={{ width: 2, height: 8, top: 14 }}
          activeTickStyle={{ width: 2, height: 8, top: 14, backgroundColor: '#a855f7' }}
          tickLabelProps={{ size: 'xs', c: 'muted' }}
          valueLabelAlwaysOn
          valueLabelProps={{ fw: '700', size: 'sm' }}
        />
      </Block>
    </Block>
  );
}
```

### Vertical Orientation

Vertical slider orientation for space-efficient layouts and different use cases.

```tsx
import { Block, Slider } from '@plocks/ui';

export function Demo() {
  return (
    <Block style={{ height: 200 }}>
      <Slider accessibilityLabel="Level" defaultValue={60} orientation="vertical" />
    </Block>
  );
}
```

### CustomStyles

Restyle the slider with `color`, `trackSize` / `thumbSize`, and the `trackStyle`, `activeTrackStyle`, and `thumbStyle` overrides. `RangeSlider` accepts the same props.

```tsx
import { Block, RangeSlider, Slider } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Slider
        label="Success palette"
        defaultValue={65}
        color="success"
        trackSize={12}
        thumbSize={30}
        trackStyle={{ opacity: 0.25 }}
        activeTrackStyle={{
          shadowColor: '#34C759',
          shadowOpacity: 0.35,
          shadowRadius: 8,
          shadowOffset: { width: 0, height: 4 },
        }}
        thumbStyle={{ borderColor: '#1F5520', borderWidth: 3 }}
      />
      <RangeSlider
        label="Warning palette"
        defaultValue={[20, 80]}
        color="warning"
        trackSize={10}
        thumbSize={26}
        trackStyle={{ opacity: 0.2 }}
        activeTrackStyle={{ opacity: 0.55 }}
        thumbStyle={{ borderColor: '#B45309', borderWidth: 2 }}
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/SoundButton.md -->

# SoundButton

SoundButton adds sound and haptic feedback to a button.

## Metadata

- Import: `import { SoundButton } from '@plocks/media';`
- Install: `npm install @plocks/media` — a separate package from `@plocks/ui`
- Status: beta
- Docs: https://plocks.dev/components/SoundButton
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/media/src/components/SoundButton

## Props

- `enableSoundFeedback`: boolean — Whether to play sound feedback on press
- `enableHapticFeedback`: boolean — Whether to play haptic feedback on press
- `soundOptions`: SoundOptions — Custom sound options for button press
- `hapticOptions`: HapticFeedbackOptions — Custom haptic options for button press
- `enableHoverSound`: boolean — Whether to play hover sound (web only)
- `hoverSoundOptions`: SoundOptions — Custom sound options for hover
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Button` props (`title` `children` `onPress` `onPressIn` `onPressOut` `onHoverIn` `onHoverOut` `onLongPress` `onLayout` `variant` `color` `size` `disabled` `loading` `loadingTitle` `fullWidth` `textColor` `icon` `startSection` `endSection` `tooltip` `transitionDuration` `accessibilityLabel` `accessibilityHint` `labelProps`): https://plocks.dev/llms/components/Button.md

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

SoundButton adds sound and haptic feedback to a button.

```tsx
import { SoundButton, SoundProvider } from '@plocks/media';

export function Demo() {
  return (
    <SoundProvider enableAudioMode={false}>
      <SoundButton title="Tap for feedback" enableSoundFeedback={false} onPress={() => {}} />
    </SoundProvider>
  );
}
```

### Variants

Compare Button-style variants while audio feedback is disabled for the preview.

```tsx
import { Column } from '@plocks/ui';
import { SoundButton, SoundProvider } from '@plocks/media';

const variants = ['default', 'filled', 'light', 'outline', 'ghost'] as const;

export function Demo() {
  return (
    <SoundProvider enableAudioMode={false}>
      <Column gap="sm" align="flex-start">
        {variants.map(variant => (
          <SoundButton key={variant} variant={variant} title={`${variant} action`} enableSoundFeedback={false} onPress={() => {}} />
        ))}
      </Column>
    </SoundProvider>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Space.md -->

# Space

Use the Space component to insert fixed spacing between elements when margin props are not available or would make layouts harder to reason about.

## Metadata

- Import: `import { Space } from '@plocks/ui';`
- Tags: spacing, layout, utility
- Docs: https://plocks.dev/components/Space
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Space

## Props

- `h`: SizeValue | DimensionProp — Height of the spacer: a `theme.spacing` token, px, or any box dimension (`'full'`, `'50%'`).
- `w`: SizeValue | DimensionProp — Width of the spacer: a `theme.spacing` token, px, or any box dimension (`'full'`, `'50%'`).
- `size`: SizeValue — Fallback size when neither `h` nor `w` is provided. Defaults to `md` so the component always occupies some space.
- `children`: never — Space is presentational only, so children are not supported.
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Compare token-based and numeric vertical gaps between stacked content blocks.

```tsx
import { Block, Space, Text, useTheme } from '@plocks/ui';

const EXAMPLES = [
  {
    label: 'Token spacing (md)',
    gap: 'md' as const,
    helper: 'Use theme tokens for consistent rhythm between related content.'
  },
  {
    label: 'Token spacing (xl)',
    gap: 'xl' as const,
    helper: 'Larger tokens create breathing room for grouped sections.'
  },
  {
    label: 'Numeric spacing (24px)',
    gap: 24,
    helper: 'Fallback to numeric values when a token does not fit the layout.'
  }
] as const;

export function Demo() {
  const theme = useTheme();

  return (
    <Block>
      {EXAMPLES.map(({ label, gap, helper }) => (
        <Block key={label}>
          <Text fw="medium">{label}</Text>
          <Block bg={theme.backgrounds.subtle} radius="lg" p="md">
            <Block>
              <Text>First line</Text>
              <Space h={gap} />
              <Text>Second line</Text>
            </Block>
          </Block>
          <Text variant="small" c="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Horizontal spacing

Use `Space` to control gutters between inline buttons with tokens or fixed widths.

```tsx
import { Block, Button, Row, Space, Text, useTheme } from '@plocks/ui';

const GROUPS = [
  {
    label: 'Token spacing (lg)',
    gap: 'lg' as const,
    helper: 'Theme tokens keep button gutters aligned with the spacing scale.'
  },
  {
    label: 'Numeric spacing (18px)',
    gap: 18,
    helper: 'Use a numeric width when exact measurements are required.'
  }
] as const;

export function Demo() {
  const theme = useTheme();

  return (
    <Block>
      {GROUPS.map(({ label, gap, helper }) => (
        <Block key={label}>
          <Text fw="medium">{label}</Text>
          <Block bg={theme.backgrounds.surface} radius="lg" p="md">
            <Row align="center">
              <Button size="sm">Primary</Button>
              <Space w={gap} />
              <Button size="sm" variant="secondary">
                Secondary
              </Button>
              <Space w={gap} />
              <Button size="sm" variant="ghost">
                Ghost
              </Button>
            </Row>
          </Block>
          <Text variant="small" c="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Splitter.md -->

# Splitter

A number or percent size is flexible; a px or rem size stays fixed as the container changes.

## Metadata

- Import: `import { Splitter } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Splitter
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Splitter

## Props

- `children` (required): React.ReactNode
- `onResizeStart`: (index: number) => void
- `onResizeEnd`: (index: number) => void
- `step`: number
- `shiftStep`: number
- `lineSize`: number
- `handleColor`: string
- `withHandle`: boolean
- `handleIcon`: React.ReactNode
- `resetOnDoubleClick`: boolean
- `splitterRef`: React.RefObject<SplitterHandle | null>
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `orientation`: 'horizontal' | 'vertical'
- `sizes`: SplitterPaneSize[]
- `onSizeChange`: (sizes: SplitterPaneSize[]) => void
- `onCollapseChange`: (index: number, collapsed: boolean) => void
- `redistribute`: 'nearest' | 'equal' | ((sizes: SplitterPaneSize[], index: number, delta: number) => SplitterPaneSize[])

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { SplitterPane } from '@plocks/ui';`

### SplitterPane

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `defaultSize`: SplitterPaneSize
- `min`: SplitterPaneSize
- `max`: SplitterPaneSize
- `collapsible`: boolean
- `collapseThreshold`: SplitterPaneSize

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Splitter.Pane

- `children`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `defaultSize`: SplitterPaneSize
- `min`: SplitterPaneSize
- `max`: SplitterPaneSize
- `collapsible`: boolean
- `collapseThreshold`: SplitterPaneSize

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useSplitter({ panels, orientation = 'horizontal', sizes: controlled, onSizeChange, onCollapseChange, redistribute = 'nearest', }: UseSplitterOptions): UseSplitterReturn`

## Types

```ts
export interface SplitterHandle {
  sizes: SplitterPaneSize[];
  collapsed: boolean[];
  setSizes: (sizes: SplitterPaneSize[]) => void;
  collapse: (index: number) => void;
  expand: (index: number) => void;
  toggleCollapse: (index: number) => void;
}

export type SplitterPaneSize = number | `${number}%` | `${number}px` | `${number}rem`;
```

## Examples

### Basics

Drag or focus the separator to resize the panes.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter h={200}>
        <Splitter.Pane defaultSize={35} min={20} bg="surface" p="md">
          <Text>Sidebar</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={65} min={20} bg="subtle" p="md">
          <Text>Content</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Fixed and Flexible Sizes

A pixel-sized sidebar keeps its width as the container changes.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter h={160}>
        <Splitter.Pane defaultSize="180px" min="120px" bg="subtle" p="md">
          <Text>Fixed sidebar</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={100} bg="surface" p="md">
          <Text>Flexible content</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Vertical Orientation

Vertical panes resize from a horizontal separator.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter orientation="vertical" h={220}>
        <Splitter.Pane defaultSize={50} bg="surface" p="md">
          <Text>Top</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={50} bg="subtle" p="md">
          <Text>Bottom</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Collapsible Pane

A collapsible pane can be toggled through the imperative ref.

```tsx
import { useRef } from 'react';
import { Block, Button, Splitter, Text } from '@plocks/ui';
import type { SplitterHandle } from '@plocks/ui';

export function Demo() {
  const splitterRef = useRef<SplitterHandle>(null);
  return (
    <Block fullWidth>
      <Button size="sm" onPress={() => splitterRef.current?.toggleCollapse(0)}>
        Toggle sidebar
      </Button>
      <Splitter splitterRef={splitterRef} h={150} mt="sm">
        <Splitter.Pane defaultSize={30} collapsible bg="subtle" p="md">
          <Text>Sidebar</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={70} bg="surface" p="md">
          <Text>Content</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Multiple Panes

Handles appear between every adjacent pair.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter h={160}>
        <Splitter.Pane defaultSize={25} bg="subtle" p="md">
          <Text>One</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={50} bg="surface" p="md">
          <Text>Two</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={25} bg="subtle" p="md">
          <Text>Three</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Without Grip

`withHandle={false}` keeps the separator line without the visual grip.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter h={160} withHandle={false} lineSize={4}>
        <Splitter.Pane defaultSize={50} bg="surface" p="md">
          <Text>One</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={50} bg="subtle" p="md">
          <Text>Two</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Controlled Sizes

The parent owns the pane sizes through `sizes` and `onSizeChange`.

```tsx
import { useState } from 'react';
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  const [sizes, setSizes] = useState<[number, number]>([40, 60]);
  return (
    <Block fullWidth>
      <Splitter h={160} sizes={sizes} onSizeChange={(next) => setSizes(next as [number, number])}>
        <Splitter.Pane bg="subtle" p="md">
          <Text>First ({Math.round(sizes[0])}%)</Text>
        </Splitter.Pane>
        <Splitter.Pane bg="surface" p="md">
          <Text>Second</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Nested Splitters

A pane can contain another splitter with its own direction.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter h={220}>
        <Splitter.Pane defaultSize={40} bg="subtle" p="md">
          <Text>Left</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={60}>
          <Splitter orientation="vertical" h={220}>
            <Splitter.Pane defaultSize={50} bg="surface" p="md">
              <Text>Top</Text>
            </Splitter.Pane>
            <Splitter.Pane defaultSize={50} bg="subtle" p="md">
              <Text>Bottom</Text>
            </Splitter.Pane>
          </Splitter>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Redistribute Space

`redistribute="nearest"` borrows from farther panes when a neighbor reaches its minimum.

```tsx
import { Block, Splitter, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Splitter h={160} redistribute="nearest">
        {['A', 'B', 'C', 'D'].map((item) => (
          <Splitter.Pane
            key={item}
            defaultSize={25}
            min={item === 'B' ? 20 : 10}
            bg="subtle"
            p="sm"
          >
            <Text>{item}</Text>
          </Splitter.Pane>
        ))}
      </Splitter>
    </Block>
  );
}
```

### Line Size

`lineSize` and `handleColor` customize the visible separator.

```tsx
import { Block, Splitter, Text, useTheme } from '@plocks/ui';

export function Demo() {
  const theme = useTheme();
  return (
    <Block fullWidth>
      <Splitter h={160} lineSize={4} handleColor={theme.colors.primary[5]}>
        <Splitter.Pane defaultSize={40} bg="subtle" p="md">
          <Text>Navigation</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={60} bg="surface" p="md">
          <Text>Content</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

### Imperative API

`splitterRef` exposes collapse and expand controls for each pane.

```tsx
import { useRef } from 'react';
import { Block, Button, Flex, Splitter, Text } from '@plocks/ui';
import type { SplitterHandle } from '@plocks/ui';

export function Demo() {
  const splitterRef = useRef<SplitterHandle>(null);
  return (
    <Block fullWidth>
      <Flex gap="sm">
        <Button onPress={() => splitterRef.current?.collapse(0)}>Collapse</Button>
        <Button onPress={() => splitterRef.current?.expand(0)}>Expand</Button>
      </Flex>
      <Splitter h={160} splitterRef={splitterRef} mt="sm">
        <Splitter.Pane defaultSize={35} collapsible bg="subtle" p="md">
          <Text>Sidebar</Text>
        </Splitter.Pane>
        <Splitter.Pane defaultSize={65} bg="surface" p="md">
          <Text>Content</Text>
        </Splitter.Pane>
      </Splitter>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Spoiler.md -->

# Spoiler

Spoiler collapses long content behind a show or hide control.

## Metadata

- Import: `import { Spoiler } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Spoiler
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Spoiler

## Props

- `children` (required): React.ReactNode — Content to hide/show
- `mah`: number = 120 — Height in px the content collapses to — the content's, not the root's. @default 120
- `expanded`: boolean — Controlled expanded state. Pair with `onExpandedChange`.
- `defaultExpanded`: boolean = false — Initial expanded state when uncontrolled. @default false
- `onExpandedChange`: (expanded: boolean) => void — Called with the requested expanded state whenever the control is pressed.
- `showLabel`: string — Label for show more
- `hideLabel`: string — Label for hide
- `transitionDuration`: number = 180 — Transition duration ms (`0` — or reduced motion — disables the transition). @default 180
- `size`: SizeValue — Size token for the show/hide control font size
- `disabled`: boolean — Disable toggle
- `renderControl`: (args: SpoilerControlArgs) => React.ReactNode — Render custom control (it is wrapped in the toggle button, so render no pressable of your own)
- `transparentFade`: boolean — If true (default) fade bottom of clamped content to transparent using CSS mask on web
- `fadeColor`: string — Fallback overlay gradient end color (used only when transparentFade=false)
- `disableFadeAnimation`: boolean — Disable gradient fade animation (debug / perf). Default false (animation enabled).
- `controlProps`: Omit<TextProps, 'children'> — Override props applied to the show/hide control `<Text>` (style, weight, ff, size, color).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface SpoilerControlArgs {
  /** Whether the content is currently expanded. */
  expanded: boolean;
  toggle: () => void;
  showLabel: string;
  hideLabel: string;
}
```

## Examples

### Basics

Set `mah` to reveal a preview of long copy while the rest stays accessible behind the built-in toggle.

```tsx
import { Block, Spoiler, Text } from '@plocks/ui';

const paragraphs = [
  'Spoilers collapse long sections of copy while keeping the content accessible to screen readers and keyboard users.',
  'Use them for optional detail or secondary information that might distract from a primary task. They expand inline, so the surrounding layout stays stable.',
  'They suit release notes, FAQ answers, long product descriptions, and legal terms: copy that most readers skim past but that some readers need to see in full before they make a decision.',
];

export function Demo() {
  return (
    <Block fullWidth>
      <Spoiler mah={96}>
        <Block>
          {paragraphs.map((paragraph) => (
            <Text key={paragraph}>{paragraph}</Text>
          ))}
        </Block>
      </Spoiler>
    </Block>
  );
}
```

### Initial State

Flip the `defaultExpanded` prop to choose whether content renders expanded on mount or waits for user interaction.

```tsx
import { Block, Spoiler, Text } from '@plocks/ui';

const content =
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="small" c="secondary">Initially open</Text>
        <Spoiler mah={48} defaultExpanded>
          <Text>{content}</Text>
        </Spoiler>
      </Block>
      <Block>
        <Text variant="small" c="secondary">Initially closed</Text>
        <Spoiler mah={48}>
          <Text>{content}</Text>
        </Spoiler>
      </Block>
    </Block>
  );
}
```

### Max Heights

Dial the `mah` value up or down to control how much content stays visible before the toggle appears.

```tsx
import { Block, Spoiler, Text } from '@plocks/ui';

const paragraphs = [
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.',
  'Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt.',
];

const MAX_HEIGHTS = [60, 100, 150];

export function Demo() {
  return (
    <Block fullWidth>
      {MAX_HEIGHTS.map((maxHeight) => (
        <Block key={maxHeight}>
          <Text variant="small" c="secondary">{maxHeight}px</Text>
          <Spoiler mah={maxHeight}>
            <Block>
              {paragraphs.map((paragraph) => (
                <Text key={paragraph}>{paragraph}</Text>
              ))}
            </Block>
          </Spoiler>
        </Block>
      ))}
    </Block>
  );
}
```

### Custom Control

Use the `renderControl` callback alongside `expanded` and `onExpandedChange` to drive expansion with your own button or analytics hooks.

```tsx
import { useState } from 'react';

import { Block, Icon, Spoiler, Text } from '@plocks/ui';

export function Demo() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Block fullWidth>
      <Spoiler
        mah={40}
        expanded={isOpen}
        onExpandedChange={setIsOpen}
        // The control is already a button (with aria-expanded): render its
        // content only, not another pressable.
        renderControl={({ expanded }) => (
          <Block direction="row" align="center" gap="xs">
            <Icon name={expanded ? 'chevron-up' : 'chevron-down'} size={14} />
            <Text size="sm" fw="600" c="primary">
              {expanded ? 'Collapse content' : 'Expand content'}
            </Text>
          </Block>
        )}
      >
        <Block>
          <Text size="sm">Open state: {String(isOpen)}</Text>
          <Text size="sm">You can render any React node as the control.</Text>
          <Text size="sm">
            Because the component is controlled, you can track expansion analytics or sync other UI elements when content is revealed.
          </Text>
        </Block>
      </Spoiler>
    </Block>
  );
}
```

### Control customization

`controlProps` accepts any `<Text>` props (`ff`, `fw`, `lts`, `tt`, `size`, `c`) and applies them to the show/hide control text — useful when the rest of your design system uses a particular weight or tracking style.

```tsx
import { Block, Spoiler, Text } from '@plocks/ui';

const longText =
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text size="sm" c="muted">Default control</Text>
        <Spoiler mah={60}>
          <Text>{longText}</Text>
        </Spoiler>
      </Block>

      <Block>
        <Text size="sm" c="muted">
          Uppercase tracked control
        </Text>
        <Spoiler
          mah={60}
          controlProps={{ tt: 'uppercase', lts: 1.5, fw: '700', size: 'xs' }}
        >
          <Text>{longText}</Text>
        </Spoiler>
      </Block>

      <Block>
        <Text size="sm" c="muted">
          Monospace control
        </Text>
        <Spoiler mah={60} controlProps={{ ff: 'monospace', fw: '600' }}>
          <Text>{longText}</Text>
        </Spoiler>
      </Block>
    </Block>
  );
}
```

### Newspaper

Combine imagery with long-form copy to mimic a newspaper-style reveal where the reader can expand to see the full story.

```tsx
import { Block, Spoiler, Text } from '@plocks/ui';
import { Image, Platform, View } from 'react-native';

const paragraphs = [
  'The coastal morning edition arrived with stories about record tides and neighborhoods working together to reinforce their seawalls. Photographers captured gulls darting between the waves as volunteers stacked sandbags along the promenade.',
  'Hidden inside the fold was a feature about an amateur archivist who discovered a crate of glass negatives documenting life on the waterfront a century ago. Each plate is being digitized so classrooms can study the evolution of the shoreline.',
  'City gardeners are also experimenting with hardy dune grasses to keep wind-swept sand in place during the colder months. The pilot plots stretch for blocks and bring a warm beige tone to an otherwise grey season.',
];

export function Demo() {
  const isWeb = Platform.OS === 'web';

  return (
    <Block fullWidth>
      <Spoiler mah={isWeb ? 220 : 260}>
        <View style={{ flexDirection: isWeb ? 'row' : 'column' }}>
          <Image
            source={require('../../../../assets/images/scene-ocean.png')}
            style={{ width: 180, height: 180, borderRadius: 12, marginRight: isWeb ? 16 : 0, marginBottom: isWeb ? 0 : 12 }}
          />
          <View style={{ flex: 1, marginTop: isWeb ? 0 : 8 }}>
            {paragraphs.map((paragraph) => (
              <Text key={paragraph} size="lg" style={{ marginBottom: 12 }}>
                {paragraph}
              </Text>
            ))}
          </View>
        </View>
      </Spoiler>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Spotlight.md -->

# Spotlight

Spotlight provides a searchable command palette for actions, routes, and other items.

## Metadata

- Import: `import { Spotlight } from '@plocks/spotlight';`
- Install: `npm install @plocks/spotlight` — a separate package from `@plocks/ui`
- Status: experimental
- Tags: command-palette, search, quick actions
- Docs: https://plocks.dev/components/Spotlight
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/spotlight/src/components/Spotlight

## Props

- `actions` (required): SpotlightItem[]
- `nothingFound`: string
- `highlightQuery`: boolean | HighlightComponentProps['highlight']
- `limit`: number
- `scrollable`: boolean
- `maxHeight`: number = fills the panel — Max height of the results list — not the panel — before it scrolls. @default fills the panel
- `shortcut`: string | string[] | null
- `searchProps`: Partial<SpotlightSearchProps> — Props for the search field (placeholder, startSection, autoFocus, inputRef, TextInput props…).
- `groupLabelProps`: Omit<TextProps, 'children'> — Override props for each group label `<Text>` (style, weight, size, color, uppercase…). Labels use the theme's `sectionLabel` text role by default.
- `store`: SpotlightStore — A store from `createSpotlightStore` / `useSpotlightStoreInstance`; defaults to the provider's.
- `variant`: 'modal' | 'bottomsheet' | 'fullscreen'
- `accessibilityLabel`: string = 'Search' — Accessible name of the spotlight dialog. @default 'Search'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { SpotlightProvider } from '@plocks/spotlight';`

### SpotlightProvider

- `children` (required): ReactNode

## Related hooks

- `useSpotlightStore(): SpotlightStore`
- `useSpotlightStoreInstance(): [SpotlightStore, SpotlightStore]`
- `useDirectSpotlightState()`

## Types

```ts
export type SpotlightItem = SpotlightActionData | SpotlightActionGroupData;

export interface SpotlightSearchProps extends Omit<TextInputProps, 'value' | 'onChangeText' | 'placeholder' | 'autoFocus'> {
  value?: string;
  onChangeText?: (text: string) => void;
  placeholder?: string;
  startSection?: ReactNode;
  onNavigateUp?: () => void;
  onNavigateDown?: () => void;
  onSelectAction?: () => void;
  onClose?: () => void;
  autoFocus?: boolean;
  inputRef?: RefObject<TextInput | null>;
  /**
   * Show a close button in the search row. Defaults to true on the mobile
   * experience, where the fullscreen presentation offers no backdrop or
   * Escape key to dismiss with.
   */
  withCloseButton?: boolean;
}

export interface SpotlightStore {
  state: SpotlightState;
  open: () => void;
  close: () => void;
  toggle: () => void;
  setQuery: (query: string) => void;
  setSelectedIndex: (index: number) => void;
  navigateUp: () => void;
  navigateDown: () => void;
}

export interface SpotlightActionData {
  /** Unique action identifier */
  id: string;
  /** Action label */
  label: string;
  /** Action description */
  description?: string;
  /** Action keywords for better search matching */
  keywords?: string[];
  /** Icon to display */
  icon?: string | ReactNode;
  /** Action press handler */
  onPress?: () => void;
  /** Whether action is disabled */
  disabled?: boolean;
  /** Custom component to render instead of default action */
  component?: ReactNode;
}

export interface SpotlightActionGroupData {
  /** Group label */
  group: string;
  /** Actions in this group */
  actions: SpotlightActionData[];
}

export interface SpotlightState {
  opened: boolean;
  query: string;
  selectedIndex: number;
}
```

## Examples

### Basics

Open the Spotlight command palette with `⌘K` / `Ctrl+K`, or from a button through its store.

```tsx
import { Block, Button } from '@plocks/ui';
import { Spotlight, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions: SpotlightProps['actions'] = [
  {
    id: 'home',
    label: 'Go to home',
    description: 'Navigate to the home screen',
    icon: 'home',
    onPress: () => console.log('navigate: home'),
  },
  {
    id: 'profile',
    label: 'Open profile',
    description: 'View your account details',
    icon: 'user',
    onPress: () => console.log('navigate: profile'),
  },
  {
    id: 'settings',
    label: 'Adjust settings',
    description: 'Update application preferences',
    icon: 'settings',
    onPress: () => console.log('navigate: settings'),
  },
];

export function Demo() {
  const [store] = useSpotlightStoreInstance();

  return (
    <Block>
      <Button onPress={() => store.open()}>Open spotlight</Button>
      <Spotlight actions={actions} store={store} />
    </Block>
  );
}
```

### Custom Icons

Swap `icon` definitions with custom React nodes to render richer action affordances.

```tsx
import { Block, Button, Icon } from '@plocks/ui';
import { Spotlight, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions: SpotlightProps['actions'] = [
  {
    id: 'deploy',
    label: 'Deploy service',
    description: 'Trigger the CI/CD pipeline',
    icon: <Icon name="bolt" />,
    onPress: () => console.log('deploy service'),
  },
  {
    id: 'logs',
    label: 'Inspect logs',
    description: 'Open the latest runtime logs',
    icon: <Icon name="code" />,
    onPress: () => console.log('view logs'),
  },
  {
    id: 'alerts',
    label: 'Review alerts',
    description: 'Check active incidents',
    icon: <Icon name="bell" />,
    onPress: () => console.log('open alerts'),
  },
];

export function Demo() {
  const [store] = useSpotlightStoreInstance();

  return (
    <Block>
      <Button onPress={() => store.open()}>Open spotlight</Button>
      <Spotlight actions={actions} store={store} />
    </Block>
  );
}
```

### Variants

Open Spotlight as a modal, bottom sheet, or fullscreen search panel.

```tsx
import { Button, Column } from '@plocks/ui';
import { Spotlight, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions = [{ id: 'home', label: 'Go home', icon: 'home', onPress: () => {} }];
const variants = ['modal', 'bottomsheet', 'fullscreen'] as const;

function VariantPreview({ variant }: { variant: typeof variants[number] }) {
  const [store] = useSpotlightStoreInstance();
  return (
    <>
      <Button variant="light" onPress={() => store.open()}>Open {variant}</Button>
      <Spotlight variant={variant} actions={actions} store={store} />
    </>
  );
}

export function Demo() {
  return <Column gap="sm" align="flex-start">{variants.map(variant => <VariantPreview key={variant} variant={variant} />)}</Column>;
}
```

### Grouped Actions

Organize actions into named groups so related commands render under semantic headers.

```tsx
import { Block, Button } from '@plocks/ui';
import { Spotlight, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions: SpotlightProps['actions'] = [
  {
    group: 'Navigation',
    actions: [
      { id: 'home', label: 'Home', icon: 'home', onPress: () => console.log('navigate: home') },
      {
        id: 'dashboard',
        label: 'Dashboard',
        description: 'Jump to the analytics overview',
        icon: 'star',
        onPress: () => console.log('navigate: dashboard'),
      },
    ],
  },
  {
    group: 'Settings',
    actions: [
      { id: 'profile', label: 'Profile', icon: 'user', onPress: () => console.log('navigate: profile') },
      {
        id: 'billing',
        label: 'Billing settings',
        description: 'Manage payment methods',
        icon: 'settings',
        onPress: () => console.log('navigate: billing'),
      },
    ],
  },
];

export function Demo() {
  const [store] = useSpotlightStoreInstance();

  return (
    <Block>
      <Button onPress={() => store.open()}>Open spotlight</Button>
      <Spotlight actions={actions} store={store} />
    </Block>
  );
}
```

### Highlight Matches

Enable `highlightQuery` so matching substrings glow while you refine command searches.

```tsx
import { Block, Button } from '@plocks/ui';
import { Spotlight, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions: SpotlightProps['actions'] = [
  {
    id: 'create-project',
    label: 'Create project',
    description: 'Start a new project workspace',
    icon: 'plus',
    onPress: () => console.log('action: create project'),
  },
  {
    id: 'create-branch',
    label: 'Create branch',
    description: 'Open branch creation workflow',
    icon: 'code',
    onPress: () => console.log('action: create branch'),
  },
  {
    id: 'open-recent',
    label: 'Open recent project',
    description: 'Choose from recently opened projects',
    icon: 'folder',
    onPress: () => console.log('action: open recent'),
  },
  {
    id: 'project-settings',
    label: 'Project settings',
    description: 'Configure repository options',
    icon: 'settings',
    onPress: () => console.log('action: project settings'),
  },
];

export function Demo() {
  const [store] = useSpotlightStoreInstance();

  return (
    <Block>
      <Button onPress={() => store.open()}>Open spotlight</Button>
      <Spotlight actions={actions} highlightQuery store={store} />
    </Block>
  );
}
```

### Limit Results

Restrict how many matching actions render by applying the `limit` prop.

```tsx
import { Block, Button } from '@plocks/ui';
import { Spotlight, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions: SpotlightProps['actions'] = Array.from({ length: 25 }).map((_, index) => ({
  id: `command-${index}`,
  label: `Command ${index + 1}`,
  description: `Example action #${index + 1}`,
  icon: 'star',
  onPress: () => console.log('command', index + 1),
}));

export function Demo() {
  const [store] = useSpotlightStoreInstance();

  return (
    <Block>
      <Button onPress={() => store.open()}>Open spotlight</Button>
      <Spotlight actions={actions} limit={8} store={store} />
    </Block>
  );
}
```

### Fullscreen Mobile

Pin the `fullscreen` variant to mimic native command palettes on handheld devices.

```tsx
import { Block, Button } from '@plocks/ui';
import { Spotlight, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const actions: SpotlightProps['actions'] = Array.from({ length: 18 }).map((_, index) => ({
  id: `mobile-action-${index}`,
  label: `Mobile action ${index + 1}`,
  description: 'Available on every screen',
  icon: 'star',
  onPress: () => console.log('mobile action', index + 1),
}));

export function Demo() {
  const [store] = useSpotlightStoreInstance();

  return (
    <Block>
      <Button onPress={() => store.open()}>Open spotlight</Button>
      <Spotlight actions={actions} variant="fullscreen" store={store} />
    </Block>
  );
}
```

### Programmatic Stores

Showcase scoped Spotlight stores, dynamic actions, and the global `spotlight` helper working together.

```tsx
import { useMemo, useState } from 'react';
import { Block, Button, Row } from '@plocks/ui';
import { spotlight, Spotlight, SpotlightProvider, type SpotlightProps, useSpotlightStoreInstance } from '@plocks/spotlight';

const baseActions: SpotlightProps['actions'] = [
  {
    id: 'ping',
    label: 'Ping server',
    description: 'Send a ping to the backend',
    icon: 'bolt',
    onPress: () => console.log('ping'),
  },
  {
    id: 'refresh',
    label: 'Refresh data',
    description: 'Reload cached domain data',
    icon: 'refresh',
    onPress: () => console.log('refresh'),
  },
];

const globalActions: SpotlightProps['actions'] = [
  {
    id: 'global-home',
    label: 'Global home',
    description: 'Navigate home via the shared store',
    icon: 'home',
    onPress: () => console.log('global home'),
  },
  {
    id: 'global-settings',
    label: 'Global settings',
    description: 'Open the account-wide preferences',
    icon: 'settings',
    onPress: () => console.log('global settings'),
  },
];

export function Demo() {
  const [store] = useSpotlightStoreInstance();
  const [dynamicCount, setDynamicCount] = useState(0);

  const actions = useMemo<SpotlightProps['actions']>(
    () => [
      ...baseActions,
      {
        id: 'add-dynamic',
        label: 'Add dynamic action',
        icon: 'plus',
        onPress: () => setDynamicCount((count) => count + 1),
      },
      ...Array.from({ length: dynamicCount }).map((_, index) => ({
        id: `dynamic-${index}`,
        label: `Dynamic action ${index + 1}`,
        description: 'Added at runtime to the local store',
        icon: 'star',
        onPress: () => console.log('dynamic', index + 1),
      })),
    ],
    [dynamicCount]
  );

  return (
    <SpotlightProvider>
      <Block>
        <Row gap="sm" wrap="wrap">
          <Button onPress={() => store.open()}>Open scoped store</Button>
          <Button variant="outline" onPress={() => spotlight.toggle()}>
            Toggle global spotlight
          </Button>
        </Row>
        <Spotlight actions={actions} store={store} />
        <Spotlight actions={globalActions} />
      </Block>
    </SpotlightProvider>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Stepper.md -->

# Stepper

Step-by-step navigation interface, perfect for multi-step forms, wizards, and progress tracking.

## Metadata

- Import: `import { Stepper } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Stepper
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Stepper

## Props

- `active` (required): number — Active step index
- `onStepClick`: (stepIndex: number) => void — Called when step is clicked
- `orientation`: 'horizontal' | 'vertical' — Step orientation
- `iconPosition`: 'left' | 'right' — Icon position relative to step body
- `iconSize`: number — Icon size
- `size`: SizeValue = 'md' — Component size: a size token, or a numeric control height. @default 'md'
- `color`: ColorProp — Accent color: a palette name (`'primary'`), a shade (`'primary.6'`) or any CSS color.
- `completedIcon`: ReactNode — Icon to display when step is completed
- `allowNextStepsSelect`: boolean — Whether next steps (steps with higher index) can be selected
- `children` (required): ReactNode — Step content
- `aria-label`: string — Accessible name of the stepper (renders it as a labelled group).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### Stepper.Completed

- `children` (required): ReactNode — Content to display when all steps are completed

### Stepper.Step

- `children`: ReactNode — Step content
- `label`: string — Step label
- `description`: string — Step description
- `icon`: ReactNode — Custom icon to display instead of the step number
- `completedIcon`: ReactNode — Icon to display when step is completed (overrides global completedIcon)
- `allowStepSelect`: boolean — Whether this step can be selected by clicking
- `color`: ColorProp — Step accent color: a palette name (`'teal'`), a shade (`'teal.6'`) or any CSS color.
- `loading`: boolean — Whether the step is loading
- `aria-label`: string — Accessibility label for screen readers
- `title`: string — Title attribute for tooltips
- `stepIndex`: number — Internal step index (added automatically)
- `isFirst`: boolean — Internal: true for the first step in the stepper (added automatically)
- `isLast`: boolean — Internal: true for the last step in the stepper (added automatically)
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the step's label `<Text>` (style, fw, ff, size, c).
- `descriptionProps`: Omit<TextProps, 'children'> — Override props applied to the step's description `<Text>`.

Also accepts the shared props — base (`style` `testID`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Control the active step with local state and show completion messaging once the flow finishes.

```tsx
import { useState } from 'react';
import { Block, Button, Row, Stepper } from '@plocks/ui';

export function Demo() {
  const [active, setActive] = useState(1);

  return (
    <Block fullWidth>
      <Stepper active={active} onStepClick={setActive}>
        <Stepper.Step label="Account" description="Create your credentials">
          Set up your sign-in information.
        </Stepper.Step>
        <Stepper.Step label="Verification" description="Confirm your email">
          Check your inbox for a verification link.
        </Stepper.Step>
        <Stepper.Step label="Preferences" description="Adjust defaults">
          Choose your notification defaults.
        </Stepper.Step>
        <Stepper.Completed>All steps complete.</Stepper.Completed>
      </Stepper>
      <Row gap="sm" justify="space-between">
        <Button variant="outline" onPress={() => setActive(active - 1)} disabled={active === 0}>
          Back
        </Button>
        <Button onPress={() => setActive(active + 1)} disabled={active === 3}>
          Next
        </Button>
      </Row>
    </Block>
  );
}
```

### Disable Step Selection

Set `allowStepSelect={false}` to stop a step from being selected by click. Here, Preferences can't be clicked.

```tsx
import { useState } from 'react';
import { Block, Stepper } from '@plocks/ui';

export function Demo() {
  const [active, setActive] = useState(0);

  return (
    <Block fullWidth>
      <Stepper active={active} onStepClick={setActive}>
        <Stepper.Step label="Account" />
        <Stepper.Step label="Verification" />
        <Stepper.Step label="Preferences" allowStepSelect={false} />
      </Stepper>
    </Block>
  );
}
```

### Icon Overrides

Swap icons for both active steps and the completed state to reinforce the status of each milestone.

```tsx
import { Block, Icon, Stepper } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Stepper active={1} completedIcon={<Icon name="check" />}>
        <Stepper.Step label="Account" icon={<Icon name="user" />} />
        <Stepper.Step label="Verification" icon={<Icon name="mail" />} />
        <Stepper.Step label="Preferences" icon={<Icon name="settings" />} />
      </Stepper>
    </Block>
  );
}
```

### Step Colors

Give each step its own `color` to override the stepper's accent color.

```tsx
import { Block, Stepper } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Stepper active={3}>
        <Stepper.Step label="Plan" color="teal" />
        <Stepper.Step label="Design" color="cyan" />
        <Stepper.Step label="Build" color="violet" />
        <Stepper.Step label="Launch" color="pink" />
      </Stepper>
    </Block>
  );
}
```

### Vertical Orientation

Switch the orientation to vertical when you need more room for descriptive copy under each step.

```tsx
import { Block, Stepper } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Stepper active={1} orientation="vertical">
        <Stepper.Step label="Account" description="Create your credentials" />
        <Stepper.Step label="Verification" description="Confirm your email" />
        <Stepper.Step label="Preferences" description="Adjust defaults" />
      </Stepper>
    </Block>
  );
}
```

### Loading Indicator

Replace the step icon with a spinner during long-running work by toggling the `loading` prop.

```tsx
import { Block, Stepper } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Stepper active={1}>
        <Stepper.Step label="Details" />
        <Stepper.Step label="Processing" loading />
        <Stepper.Step label="Ready" />
      </Stepper>
    </Block>
  );
}
```

### Size Variants

Compare the `size` prop across the full `xs`–`3xl` scale while reusing the same steps.

```tsx
import { Block, Stepper, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {SIZES.map((size) => (
        <Block key={size} fullWidth>
          <Text variant="small" c="secondary">{size}</Text>
          <Stepper active={1} size={size}>
            <Stepper.Step label="Plan" />
            <Stepper.Step label="Build" />
            <Stepper.Step label="Launch" />
          </Stepper>
        </Block>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/StickyNote.md -->

# Sticky Note

StickyNote displays reminders and annotations on a colorful paper-like surface.

## Metadata

- Import: `import { StickyNote } from '@plocks/ui';`
- Tags: note, reminder, paper, pinboard
- Docs: https://plocks.dev/components/StickyNote
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/StickyNote

## Props

- `children`: React.ReactNode — Note body. Plain text receives the note's readable text color automatically.
- `title`: string — Optional heading above the body.
- `footer`: React.ReactNode — Optional content anchored below the body, such as a date or author.
- `color`: StickyNoteColor = 'yellow' — Paper color preset, theme palette token, or CSS color. @default 'yellow'
- `size`: number = 220 — Width and minimum height in pixels. @default 220
- `rotation`: number = 0 — Rotation in degrees for a casual pinboard layout. @default 0
- `onPress`: () => void — Makes the note an accessible button.
- `disabled`: boolean — Disables an interactive note.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type StickyNoteColor = 'yellow' | 'pink' | 'blue' | 'green' | 'purple' | ColorProp;
```

## Examples

### Basics

Use preset colors for a small collection of reminders. Each note can also carry a title and footer.

```tsx
import { Block, StickyNote } from '@plocks/ui';

export function Demo() {
  return (
    <Block direction="row" wrap="wrap" gap={24} p="lg">
      <StickyNote title="Today" footer="Tuesday · 9:30 AM" color="yellow" rotation={-2}>
        Review the sketches and share feedback with the team.
      </StickyNote>
      <StickyNote title="Idea" color="blue" rotation={2}>
        Keep the interface simple enough to understand at a glance.
      </StickyNote>
      <StickyNote title="Remember" color="pink" rotation={-1}>
        Bring the latest prototype to the design review.
      </StickyNote>
    </Block>
  );
}
```

### Interactive note

Add `onPress` to use a note as a button. The component supplies button semantics and a pressed state.

```tsx
import React, { useState } from 'react';
import { StickyNote } from '@plocks/ui';

export function Demo() {
  const [done, setDone] = useState(false);

  return (
    <StickyNote
      title={done ? 'Done!' : 'To do'}
      color={done ? 'green' : 'purple'}
      accessibilityLabel={done ? 'Mark note as to do' : 'Mark note as done'}
      onPress={() => setDone(value => !value)}
    >
      {done ? 'Tap to reopen this task.' : 'Tap this note when the task is complete.'}
    </StickyNote>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Surface.md -->

# Surface

Surface provides the base container for the library's elevated components.

## Metadata

- Import: `import { Surface } from '@plocks/ui';`
- Tags: surface, paper, elevation, container, layout
- Docs: https://plocks.dev/components/Surface
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Surface

## Props

- `children`: React.ReactNode
- `level`: 0 | 1 | 2 | 3 — Elevation step (`0`–`3`). Drives background, border color and the default shadow together, so a surface can't end up with a level-3 shadow over a level-0 fill. Omit it to derive the level from the enclosing Surface — see `raised`.
- `raised`: boolean — Take the enclosing Surface's level and add one (clamped at 3). This is what makes nesting work: a popover inside a card lands a step above the card without either one hard-coding a number.
- `withBorder`: boolean | 'auto' — Show the level's hairline border. Defaults to `'auto'`, which draws it only in dark mode — light mode conveys elevation with shadow, dark mode can't.
- `borderColor`: string — Border color override. Implies a border.
- `borderWidth`: number — Border width override in px. Implies a border.
- `padding`: SizeValue — Internal padding — size token or px. Surfaces have none by default.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), `radius`, `shadow`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useSurfaceLevel(): SurfaceLevel` — Returns the elevation level (`0`–`3`) of the nearest enclosing `Surface`, or `0` (the page) when there is none — never throws.

## Examples

### Basics

Use a Surface to give content a theme-aware background and elevation.

```tsx
import { Block, Surface, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Surface level={1} padding="md" radius="lg" fullWidth>
        <Text>Resting surface</Text>
      </Surface>
    </Block>
  );
}
```

### Elevation levels

Level 0 is the page, 1 is resting content, 2 floats over content and 3 takes over the screen. Each resolves its own background, border and shadow from `theme.surfaces`; toggle the color scheme to see the ladder switch from shadow-led to fill-led.

```tsx
import { Block, Surface, Text } from '@plocks/ui';

const LEVELS = [0, 1, 2, 3] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {LEVELS.map((level) => (
        <Surface key={level} level={level} padding="md" radius="lg" fullWidth>
          <Text size="sm">Level {level}</Text>
        </Surface>
      ))}
    </Block>
  );
}
```

### Nesting with raised

`raised` takes the enclosing Surface's level and adds one, so nested containers stack correctly without any of them hard-coding a number. Move the outer Surface to a different level and everything inside follows.

```tsx
import { Block, Surface, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Surface level={0} padding="md" radius="lg" fullWidth>
      <Block>
        <Text size="sm">Level 0</Text>
        <Surface raised padding="md" radius="lg" fullWidth>
          <Block>
            <Text size="sm">Level 1</Text>
            <Surface raised padding="md" fullWidth>
              <Text size="sm">Level 2</Text>
            </Surface>
          </Block>
        </Surface>
      </Block>
    </Surface>
  );
}
```

### Surface vs Card

Card is a Surface with padding and section semantics on top. Reach for Surface directly when you want the elevation without Card's structure — a toolbar, a sheet, a custom panel.

```tsx
import { Block, Card, Row, Surface, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Surface padding="md" radius="lg" fullWidth>
        <Row align="center" justify="space-between">
          <Text size="sm">Surface</Text>
          <Text size="sm" c="muted">
            level 1
          </Text>
        </Row>
      </Surface>

      <Card variant="elevated" radius="lg" fullWidth>
        <Row align="center" justify="space-between">
          <Text size="sm">Card</Text>
          <Text size="sm" c="muted">
            level 2
          </Text>
        </Row>
      </Card>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/SwipeableRow.md -->

# SwipeableRow

SwipeableRow reveals actions when swiped and provides an action button for keyboard and touch discovery. Actions use the theme-aware Button primitive. Put the row inside a `GestureHandlerRootView` to enable swipe gestures; the action button remains available without Gesture Handler.

## Metadata

- Import: `import { SwipeableRow } from '@plocks/ui';`
- Status: beta
- Tags: swipe, row, actions, list
- Docs: https://plocks.dev/components/SwipeableRow
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/SwipeableRow

## Props

- `children` (required): React.ReactNode
- `startActions`: SwipeableRowAction[] = [] — Actions revealed from the logical start edge.
- `endActions`: SwipeableRowAction[] = [] — Actions revealed from the logical end edge.
- `accessibilityLabel`: string — Accessible name for this row's action group.
- `actionWidth`: number = 104 — Width of each revealed action. @default 104
- `disabled`: boolean = false — Disable swipe and action activation.
- `showActionButton`: boolean = true — Show an action-menu button for keyboard and touch discovery. @default true
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface SwipeableRowAction {
  key: string;
  label: string;
  icon?: string;
  onPress: () => void;
  color?: ColorProp;
  variant?: ButtonVariant;
  disabled?: boolean;
}
```

## Examples

### Swipe actions

Swipe the message toward either side to reveal actions. The action button also shows all actions, including for keyboard users. `startActions` and `endActions` follow the current text direction. Use `color` and `variant` on each action to communicate its purpose.

```tsx
import { useState } from 'react';
import { Block, Column, SwipeableRow, Text } from '@plocks/ui';

export function Demo() {
  const [status, setStatus] = useState('Choose an action');
  return (
    <Column gap="sm" fullWidth>
      <Text c="secondary">Swipe the row, or open its action button.</Text>
      <SwipeableRow
        w="100%"
        accessibilityLabel="Message from Ada"
        startActions={[{ key: 'archive', label: 'Archive', icon: 'folder', color: 'primary', onPress: () => setStatus('Archived') }]}
        endActions={[{ key: 'delete', label: 'Delete', icon: 'trash', color: 'error', onPress: () => setStatus('Deleted') }]}
      >
        <Block p="md" fullWidth>
          <Text fw="semibold">Ada Lovelace</Text>
          <Text c="secondary">New design notes are ready to review.</Text>
        </Block>
      </SwipeableRow>
      <Text>{status}</Text>
    </Column>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Switch.md -->

# Switch

Switch components provide a way to toggle between two states, typically representing on/off or enabled/disabled states.

## Metadata

- Import: `import { Switch } from '@plocks/ui';`
- Tags: input, form, toggle, switch, boolean
- Docs: https://plocks.dev/components/Switch
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Switch

## Props

- `checked`: boolean — Controlled on state.
- `defaultChecked`: boolean = false — Initial on state for uncontrolled usage.
- `onChange`: (checked: boolean) => void — Called with the next on state.
- `variant`: 'filled' | 'outline' | 'ios' | 'android' = 'filled' — Visual style. Default `'filled'`.
- `color`: ThemeColor = 'primary' — Track color when on: a palette token, `'primary.6'` shade syntax, or any CSS color.
- `transitionDuration`: number — Length of the on/off transition in ms. `0` moves the thumb instantly. When omitted the switch keeps its spring animation; any explicit value (including 0) swaps it for a timing curve. Always 0 under reduced motion.
- `labelPosition`: SwitchLabelPosition = 'right' — Label position relative to the switch. `left` / `right` follow the reading direction (`right` = after the switch). Default `'right'`.
- `children`: React.ReactNode — Label content (alternative to `label`; wins when both are set).
- `onIcon`: React.ReactNode — Icon inside the thumb while on.
- `offIcon`: React.ReactNode — Icon inside the thumb while off.
- `onLabel`: string = 'On' — Spoken state while on (native). Default `'On'`.
- `offLabel`: string = 'Off' — Spoken state while off (native). Default `'Off'`.
- `controls`: string — Id of the element the switch shows/hides (web `aria-controls`).
- `id`: string — Base id: the control gets it, the label/description/error get `${id}-label` etc.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `name` `accessibilityLabel` `accessibilityHint` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type SwitchLabelPosition = ChoiceLabelPosition;
```

## Examples

### Basics

Control a `Switch` with local state and surface its status with supporting text and the `description` prop.

```tsx
import { useState } from 'react';
import { Block, Switch, Text } from '@plocks/ui';

export function Demo() {
  const [enabled, setEnabled] = useState<boolean>(true);

  return (
    <Block>
      <Switch
        checked={enabled}
        onChange={setEnabled}
        label="Enable live score alerts"
        description="Send push notifications when the match score changes."
      />
      <Text variant="small" c="muted">
        Notices are {enabled ? 'enabled' : 'disabled'}.
      </Text>
    </Block>
  );
}
```

### Sizes

Choose a `size` token to scale the switch track and thumb; `defaultChecked` seeds uncontrolled switches.

```tsx
import { Block, Row, Switch, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Switch accessibilityLabel={`Switch ${size}`} size={size} defaultChecked />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Variants

Choose between a solid `filled` track (default) and an `outline` track whose border and thumb take on the active color.

```tsx
import { useState } from 'react';
import { Block, Row, Switch, Text } from '@plocks/ui';

const VARIANTS = [
  { variant: 'filled', hint: 'filled (default) — solid track fills with the active color' },
  { variant: 'outline', hint: 'outline — bordered track with a colored thumb' },
  { variant: 'ios', hint: 'ios — large white thumb in a rounded pill track' },
  { variant: 'android', hint: 'android — Material dot thumb that grows and whitens when on' },
] as const;

export function Demo() {
  const [on, setOn] = useState<Record<string, boolean>>({
    filled: true,
    outline: true,
    ios: true,
    android: true,
  });

  return (
    <Block>
      {VARIANTS.map(({ variant, hint }) => (
        <Block key={variant}>
          <Text variant="small" c="muted">
            {hint}
          </Text>
          <Row gap="lg" wrap="wrap" align="center">
            <Switch
              variant={variant}
              checked={on[variant]}
              onChange={(v) => setOn((prev) => ({ ...prev, [variant]: v }))}
              label="On"
            />
            <Switch variant={variant} checked={false} label="Off" />
            <Switch variant={variant} checked color="success" label="Success" />
          </Row>
        </Block>
      ))}
    </Block>
  );
}
```

### Label on the thumb

Render content inside the moving thumb with the `onIcon` / `offIcon` props — an icon or a short text label that swaps with the on/off state.

```tsx
import { useState } from 'react';
import { Block, Icon, Switch, Text, useTheme } from '@plocks/ui';

export function Demo() {
  const theme = useTheme();
  const [wifi, setWifi] = useState<boolean>(true);
  const [available, setAvailable] = useState<boolean>(true);

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">
          Icon on the thumb — swaps with the on/off state
        </Text>
        <Switch
          checked={wifi}
          onChange={setWifi}
          size="xl"
          label="Wi-Fi"
          onIcon={<Icon name="check" size={18} color={theme.colors.primary[3]} stroke={3} />}
          offIcon={<Icon name="close" size={18} color={theme.text.muted} stroke={3} />}
        />
      </Block>

      <Block>
        <Text variant="small" c="muted">
          Text label on the thumb
        </Text>
        <Switch
          checked={available}
          onChange={setAvailable}
          size="3xl"
          color="success"
          label="Availability"
          onIcon={
            <Text style={{ fontSize: 12, lineHeight: 11, fontWeight: '700', color: theme.colors.success[5] }}>
              ON
            </Text>
          }
          offIcon={
            <Text style={{ fontSize: 12, lineHeight: 11, fontWeight: '700', color: theme.text.muted }}>
              OFF
            </Text>
          }
        />
      </Block>
    </Block>
  );
}
```

### Colors

Provide a `color` token to align switches with semantic palettes such as `primary`, `success`, or `error` states.

```tsx
import { Block, Row, Switch, Text } from '@plocks/ui';

const COLOR_VARIANTS = [
  { label: 'Primary', color: 'primary' },
  { label: 'Secondary', color: 'secondary' },
  { label: 'Success', color: 'success' },
  { label: 'Warning', color: 'warning' },
  { label: 'Error', color: 'error' }
] as const;

export function Demo() {
  return (
    <Block>
      <Text variant="small" c="muted">
        Semantic color variants
      </Text>
      <Row gap="md" wrap="wrap">
        {COLOR_VARIANTS.map(({ label, color }) => (
          <Switch key={color} defaultChecked label={label} labelPosition="right" color={color} />
        ))}
      </Row>
    </Block>
  );
}
```

### States

Present interactive, disabled, and validation states by combining `checked`, `disabled`, `required`, and `error` props.

```tsx
import { useState } from 'react';
import { Block, Switch, Text } from '@plocks/ui';

export function Demo() {
  const [homeAlerts, setHomeAlerts] = useState(true);
  const [awayAlerts, setAwayAlerts] = useState(false);

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">
          Interactive states
        </Text>
        <Switch
          checked={homeAlerts}
          onChange={setHomeAlerts}
          label="Home team alerts"
        />
        <Switch
          checked={awayAlerts}
          onChange={setAwayAlerts}
          label="Away team alerts"
        />
      </Block>
      <Block>
        <Text variant="small" c="muted">
          Disabled states
        </Text>
        <Switch defaultChecked label="Lineup lock" disabled />
        <Switch label="Sound effects" disabled />
      </Block>
      <Block>
        <Text variant="small" c="muted">
          Validation helpers
        </Text>
        <Switch
          label="Require broadcast approval"
          required
          error="Approval is needed before publishing."
        />
        <Switch
          defaultChecked
          label="Send pre-game summary"
          description="Dispatch an email recap to coaches and analysts."
        />
      </Block>
    </Block>
  );
}
```

### Shared State

Coordinate multiple switches with a shared state object and reflect the current selections in supporting copy.

```tsx
import { useState } from 'react';
import { Block, Switch, Text } from '@plocks/ui';

const PREFERENCE_CONTROLS = [
  {
    key: 'scoreAlerts',
    label: 'Live score alerts',
    description: 'Push notifications for scoring plays.'
  },
  {
    key: 'newsEmails',
    label: 'Breaking news emails',
    description: 'Send a morning recap with roster updates.'
  },
  {
    key: 'audioHighlights',
    label: 'Audio highlights',
    description: 'Play broadcast clips after each match.'
  }
] as const;

type PreferenceKey = (typeof PREFERENCE_CONTROLS)[number]['key'];

const INITIAL_SETTINGS: Record<PreferenceKey, boolean> = {
  scoreAlerts: true,
  newsEmails: false,
  audioHighlights: false
};

export function Demo() {
  const [settings, setSettings] = useState<Record<PreferenceKey, boolean>>(
    () => ({ ...INITIAL_SETTINGS })
  );

  return (
    <Block>
      <Block>
        <Text variant="small" c="muted">
          Shared state
        </Text>
        {PREFERENCE_CONTROLS.map(({ key, label, description }) => (
          <Switch
            key={key}
            checked={settings[key]}
            onChange={(checked) =>
              setSettings((prev) => ({ ...prev, [key]: checked }))
            }
            label={label}
            description={description}
          />
        ))}
      </Block>
  <Block>
        <Text variant="small" c="muted">
          Summary
        </Text>
        <Text variant="p">
          Score alerts are {settings.scoreAlerts ? 'on' : 'off'}.
        </Text>
        <Text variant="p">
          Breaking news emails are {settings.newsEmails ? 'on' : 'off'}.
        </Text>
        <Text variant="p">
          Audio highlights are {settings.audioHighlights ? 'on' : 'off'}.
        </Text>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Table.md -->

# Table

Table provides semantic rows, columns, and cells for simple tabular content.

## Metadata

- Import: `import { Table } from '@plocks/ui';`
- Status: experimental
- Tags: table, layout, semantic
- Docs: https://plocks.dev/components/Table
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Table

## Props

- `children`: React.ReactNode
- `data`: TableData — Table data for automatic generation of rows
- `horizontalSpacing`: TableSpacing — Horizontal spacing between cells (`data` mode) — a theme spacing token or px
- `verticalSpacing`: TableSpacing — Vertical spacing between cells (`data` mode) — a theme spacing token or px
- `striped`: boolean — Add striped styling to rows (`data` mode)
- `highlightOnHover`: boolean — Highlight rows on hover (web / pointer devices) — applies to every `Table.Tr` inside the table
- `withTableBorder`: boolean — Add borders around table
- `withColumnBorders`: boolean — Add borders between columns (`data` mode)
- `withRowBorders`: boolean — Add borders between rows (`data` mode)
- `captionSide`: 'top' | 'bottom' — Caption position
- `layout`: 'auto' | 'fixed' — Table layout mode
- `variant`: 'default' | 'vertical' — `vertical` places data headers down the first column (`data` mode).
- `tabularNums`: boolean — Enable tabular numbers for better number alignment
- `fullWidth`: boolean — Make table take full width of container
- `columns`: TableColumnConfig[] — Column width configuration for auto-sizing (`data` mode)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `aria-rowindex`: number
- `aria-colindex`: number
- `aria-rowcount`: number
- `aria-colcount`: number
- `aria-colspan`: number
- `aria-sort`: 'ascending' | 'descending' | 'none' | 'other'

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { TableTh, TableTd, TableTr, TableThead, TableTbody, TableTfoot, TableCaption, TableScrollContainer } from '@plocks/ui';`

### TableScrollContainer

- `children`: React.ReactNode
- `miw`: number — Minimum width of the scrolled content — narrower viewports scroll horizontally. Defaults to `500`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `aria-rowindex`: number
- `aria-colindex`: number
- `aria-rowcount`: number
- `aria-colcount`: number
- `aria-colspan`: number
- `aria-sort`: 'ascending' | 'descending' | 'none' | 'other'

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### Table.ScrollContainer

- `children`: React.ReactNode
- `miw`: number — Minimum width of the scrolled content — narrower viewports scroll horizontally. Defaults to `500`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`
- `aria-rowindex`: number
- `aria-colindex`: number
- `aria-rowcount`: number
- `aria-colcount`: number
- `aria-colspan`: number
- `aria-sort`: 'ascending' | 'descending' | 'none' | 'other'

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

`TableTh`, `TableTd`, `TableTr`, `TableThead`, `TableTbody`, `TableTfoot`, `TableCaption`, `Table.Caption`, `Table.Tbody`, `Table.Td`, `Table.Th`, `Table.Thead`, `Table.Tr` have no props interface of their own.

## Types

```ts
type TableSpacing = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;

export interface TableColumnConfig {
  /** Column key for identification */
  key?: string;
  /** Column width strategy */
  width?: number | string | 'auto' | 'min-content' | 'max-content';
  /** Minimum column width */
  minWidth?: number;
  /** Maximum column width */
  maxWidth?: number;
  /** Flex grow factor */
  flex?: number;
}
```

## Examples

### Basics

Pass a dataset to the `data` prop to render the caption, header, and body without composing subcomponents.

```tsx
import { Block, Table } from '@plocks/ui';

const data = {
  caption: 'User accounts overview',
  head: ['Name', 'Role', 'Status', 'Posts'],
  body: [
    ['Alice', 'Admin', 'Active', 128],
    ['Bob', 'Editor', 'Invited', 42],
    ['Carol', 'Viewer', 'Active', 5],
    ['Dave', 'Editor', 'Suspended', 16],
  ],
};

export function Demo() {
  return (
    <Block fullWidth>
      <Table data={data} withTableBorder />
    </Block>
  );
}
```

### Variants

Compare the default and vertical table layout modes with the same data.

```tsx
import { Column, Table, Text } from '@plocks/ui';

const data = { head: ['Name', 'Status'], body: [['Avery', 'Active'], ['Jordan', 'Pending']] };
const variants = ['default', 'vertical'] as const;

export function Demo() {
  return (
    <Column gap="lg" fullWidth>
      {variants.map(variant => (
        <Column key={variant} gap="xs" fullWidth>
          <Text fw="semibold">{variant}</Text>
          <Table variant={variant} data={data} withTableBorder fullWidth />
        </Column>
      ))}
    </Column>
  );
}
```

### Border Options

Enable `withTableBorder`, `withColumnBorders`, and `withRowBorders` to emphasize cell boundaries.

```tsx
import { Block, Table } from '@plocks/ui';

const data = {
  head: ['ID', 'Region', 'Sales', 'Growth %'],
  body: [
    ['#1001', 'NA', '$120,340', '+12.4%'],
    ['#1002', 'EU', '$98,210', '+4.1%'],
    ['#1003', 'APAC', '$76,003', '+8.9%'],
    ['#1004', 'LATAM', '$23,554', '+15.2%'],
  ],
  caption: 'Quarterly regional performance',
};

export function Demo() {
  return (
    <Block fullWidth>
      <Table data={data} withTableBorder withColumnBorders withRowBorders />
    </Block>
  );
}
```

### Manual Composition

Use the table subcomponents when you need custom cells, alignments, or dynamic rows beyond the `data` helper.

```tsx
import { Block, Chip, Table } from '@plocks/ui';

const rows = [
  { name: 'plocks', stack: 'RN / Expo', status: 'stable', stars: 4210 },
  { name: 'ignite', stack: 'RN', status: 'active', stars: 9230 },
  { name: 'tamagui', stack: 'RN / Web', status: 'active', stars: 16000 },
  { name: 'nativewind', stack: 'RN', status: 'active', stars: 7600 },
];

export function Demo() {
  return (
    <Block fullWidth>
      <Table withTableBorder>
        <Table.Caption>React Native UI libraries</Table.Caption>
        <Table.Thead>
          <Table.Tr>
            <Table.Th>Name</Table.Th>
            <Table.Th>Stack</Table.Th>
            <Table.Th align="center">Status</Table.Th>
            <Table.Th align="right">Stars</Table.Th>
          </Table.Tr>
        </Table.Thead>
        <Table.Tbody>
          {rows.map((row) => (
            <Table.Tr key={row.name}>
              <Table.Td>{row.name}</Table.Td>
              <Table.Td>{row.stack}</Table.Td>
              <Table.Td align="center">
                <Chip size="xs" color={row.status === 'stable' ? 'success' : 'primary'} variant="light">
                  {row.status}
                </Chip>
              </Table.Td>
              <Table.Td align="right" widthStrategy="min-content">
                {row.stars.toLocaleString()}
              </Table.Td>
            </Table.Tr>
          ))}
        </Table.Tbody>
      </Table>
    </Block>
  );
}
```

### Horizontal Scroll

Use `Table.ScrollContainer` to clamp table width and let users horizontally scroll large matrices.

```tsx
import { Block, Table } from '@plocks/ui';

const columns = Array.from({ length: 12 }, (_, index) => `Col ${index + 1}`);

const body = Array.from({ length: 8 }, (_, rowIndex) =>
  columns.map((_, columnIndex) => `R${rowIndex + 1}C${columnIndex + 1}`)
);

export function Demo() {
  return (
    <Block fullWidth>
      <Table.ScrollContainer miw={900}>
        <Table
          data={{ head: columns, body, caption: 'Wide matrix sample' }}
          withTableBorder
          striped
        />
      </Table.ScrollContainer>
    </Block>
  );
}
```

### Column Sizing

Define the `columns` array to set fixed widths, min widths, or flex growth for responsive tables.

```tsx
import { Block, Table } from '@plocks/ui';

const columns = [
  { key: 'name', minWidth: 140 },
  { key: 'email', flex: 2, minWidth: 200 },
  { key: 'plan', width: 90 },
  { key: 'usage', flex: 1, minWidth: 120 },
];

const data = {
  head: ['Name', 'Email', 'Plan', 'Usage'],
  body: [
    ['Alice Carter', 'alice@example.com', 'Pro', '13.4 GB'],
    ['Brandon Lee', 'brandon@example.com', 'Free', '1.1 GB'],
    ['Chloe Mills', 'chloe@example.com', 'Business', '54.2 GB'],
    ['Daniel Stone', 'daniel@example.com', 'Pro', '8.7 GB'],
  ],
};

export function Demo() {
  return (
    <Block fullWidth>
      <Table data={data} columns={columns} withTableBorder />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/TableOfContents.md -->

# TableOfContents

TableOfContents builds a navigable outline from page headings.

## Metadata

- Import: `import { TableOfContents } from '@plocks/ui';`
- Docs: https://plocks.dev/components/TableOfContents
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/TableOfContents

## Props

- `variant`: 'filled' | 'outline' | 'ghost' | 'none' = 'none' — Visual style variant for the table of contents
- `color`: ColorProp — Background color for the filled variant (and the active-item marker): a palette name, a shade (`'primary.6'`) or any CSS color. Falls back to the theme primary color.
- `size`: SizeValue = 'sm' — Text size for table of contents items
- `radius`: RadiusValue = 'md' — Border radius of the container: a radius token, px number, `'none'` or `'full'`.
- `scrollSpyOptions`: ScrollSpyOptions — Configuration options for scroll spy behavior
- `getControlProps`: (payload: { data: TocItem; active: boolean; index: number }) => TableOfContentsControlProps — Function to customize props for each table of contents item control
- `initialData`: TocItem[] — Initial data for table of contents items (useful for SSR or pre-rendering)
- `minDepthToOffset`: number = 1 — Depth from which items are indented: an item is offset by `(depth - minDepthToOffset) × depthOffset` px (never negative).
- `depthOffset`: number = 20 — Pixel offset to apply for each depth level (indentation amount)
- `reinitializeRef`: React.RefObject<(() => void) | null> — Ref to expose the reinitialize function for manually triggering TOC refresh
- `autoContrast`: boolean = false — Automatically adjust text color for contrast when using filled variant
- `onActiveChange`: (id: string | null, item?: TocItem) => void — Callback fired when the active item changes
- `container`: string | HTMLElement = 'main, [role="main"], .main-content, #main-content, article, .content, #content' — CSS selector string or HTMLElement to use as the scroll container
- `accessibilityLabel`: string = 'Table of contents' — Accessible name of the navigation landmark.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type TableOfContentsControlProps = Partial<Omit<PressableProps, 'children'>> & {
  /** Replaces the default label. */
  children?: React.ReactNode;
};
```

## Examples

### Basics

Drop a table of contents beside your main article and it will register headings automatically through the shared title registry.

```tsx
import { Block, Row, TableOfContents, Text, Title, TitleRegistryProvider } from '@plocks/ui';

const SECTIONS = [
  { id: 'intro', title: 'Introduction', summary: 'Set the stage for the walkthrough.' },
  { id: 'setup', title: 'Setup', summary: 'Install dependencies and initialize the provider.' },
  { id: 'usage', title: 'Usage', summary: 'Render headings inside your content area to register them.' },
  { id: 'faq', title: 'FAQ', summary: 'Answer the questions you expect most often.' },
];

export function Demo() {

  return (
    <TitleRegistryProvider>
      <Row gap="xl" align="flex-start">
        <TableOfContents
          container="#toc-basic-content"
          variant="outline"
          size="sm"
          p="sm"
          style={{ width: 240 }}
        />
        <Block id="toc-basic-content" grow={1} style={{ maxWidth: 560 }}>
          {SECTIONS.map((section, index) => (
            <Block key={section.id}>
              <Title order={index === 0 ? 1 : 2}>{section.title}</Title>
              <Text c="secondary">{section.summary}</Text>
            </Block>
          ))}
        </Block>
      </Row>
    </TitleRegistryProvider>
  );
}
```

### Variants

Choose between the `outline`, `ghost`, `filled`, and `none` variants. Pair `filled` with `autoContrast` to keep labels legible against a brand color.

```tsx
import { Row, TableOfContents } from '@plocks/ui';

const ITEMS = [
  { id: 'overview', value: 'Overview', depth: 1 },
  { id: 'tokens', value: 'Color tokens', depth: 2 },
  { id: 'accessibility', value: 'Accessibility', depth: 1 },
];

export function Demo() {
  return (
    <Row gap="md" align="flex-start" wrap="wrap">
      <TableOfContents initialData={ITEMS} variant="outline" size="xs" style={{ width: 200 }} />
      <TableOfContents initialData={ITEMS} variant="ghost" size="xs" style={{ width: 200 }} />
      <TableOfContents
        initialData={ITEMS}
        variant="filled"
        color="primary.6"
        autoContrast
        size="xs"
        style={{ width: 200 }}
      />
    </Row>
  );
}
```

### Preloaded data

Seed the table of contents with `initialData` so servers and prerender jobs can render the navigation before headings mount.

```tsx
import { Block, TableOfContents } from '@plocks/ui';

const INITIAL_ITEMS = [
  { id: 'overview', value: 'Overview', depth: 1 },
  { id: 'setup', value: 'Setup', depth: 2 },
  { id: 'usage', value: 'Usage', depth: 2 },
  { id: 'advanced', value: 'Advanced', depth: 1 },
  { id: 'faq', value: 'FAQ', depth: 1 },
];

export function Demo() {
  return (
    <Block align="flex-start">
      <TableOfContents
        initialData={INITIAL_ITEMS}
        variant="outline"
        depthOffset={16}
        radius="sm"
        size="sm"
        p="sm"
        style={{ width: 240 }}
      />
    </Block>
  );
}
```

### Depth offset

Use `minDepthToOffset` and `depthOffset` to indent nested headings so deep sections are easy to scan.

```tsx
import { Block, TableOfContents } from '@plocks/ui';

const INITIAL_ITEMS = [
  { id: 'intro', value: 'Introduction', depth: 1 },
  { id: 'schedule', value: 'Release schedule', depth: 2 },
  { id: 'api', value: 'API reference', depth: 2 },
  { id: 'hooks', value: 'Hooks', depth: 3 },
  { id: 'migration', value: 'Migration', depth: 1 },
];

export function Demo() {
  return (
    <Block align="flex-start">
      <TableOfContents
        initialData={INITIAL_ITEMS}
        variant="outline"
        minDepthToOffset={2}
        depthOffset={28}
        size="xs"
        p="sm"
        style={{ width: 240 }}
      />
    </Block>
  );
}
```

### Active callbacks

Subscribe to `onActiveChange` to surface the currently highlighted section, perfect for syncing status chips or analytics.

```tsx
import { useState } from 'react';
import { Block, Chip, Row, TableOfContents, Text, Title, TitleRegistryProvider } from '@plocks/ui';

const SECTIONS = [
  { id: 'overview', title: 'Overview', summary: 'Explain when the progress indicator should appear.' },
  { id: 'loading', title: 'Loading States', summary: 'Describe feedback while content is fetching.' },
  { id: 'error', title: 'Error Recovery', summary: 'Clarify what happens if the data fails to load.' },
];

export function Demo() {
  const [activeId, setActiveId] = useState<string | null>(null);

  return (
    <TitleRegistryProvider>
      <Block>
        <Chip variant="light" color={activeId ? 'primary' : 'gray'} size="sm">
          Active section: {activeId ?? 'None'}
        </Chip>

        <Row gap="xl" align="flex-start">
          <TableOfContents
            container="#toc-active-callback-content"
            variant="outline"
            size="xs"
            p="sm"
            style={{ width: 240 }}
            onActiveChange={setActiveId}
          />
          <Block id="toc-active-callback-content" grow={1} style={{ maxWidth: 560 }}>
            {SECTIONS.map((section, index) => (
              <Block key={section.id}>
                <Title order={index === 0 ? 1 : 2}>{section.title}</Title>
                <Text c="secondary">{section.summary}</Text>
              </Block>
            ))}
          </Block>
        </Row>
      </Block>
    </TitleRegistryProvider>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Tabs.md -->

# Tabs

Tabs organize content into multiple sections that users can navigate between. The component supports various visual styles, orientations, and interactive behaviors while maintaining accessibility standards.

## Metadata

- Import: `import { Tabs } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Tabs
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Tabs

## Props

- `items` (required): TabItem[] — Array of tab definitions to render. The first item becomes active by default when uncontrolled.
- `value`: string — Controlled active tab key. When omitted the component manages internal state.
- `defaultValue`: string — Initially active tab key when uncontrolled (a persisted selection wins). Defaults to the first item.
- `onChange`: (tabKey: string) => void — Called with the tab key whenever the active tab changes. Fires for both controlled and uncontrolled usage.
- `activationMode`: 'automatic' | 'manual' = 'automatic' — Keyboard activation. `'automatic'` selects a tab as soon as arrow keys move focus to it; `'manual'` only moves focus, and Enter/Space selects.
- `onDisabledTabPress`: (tabKey: string, item: TabItem) => void — Invoked when a disabled tab is pressed, allowing custom messaging or recovery flows.
- `variant`: 'line' | 'chip' | 'card' | 'folder' = 'line' — Visual style of the tabs.
- `size`: SizeValue = 'sm' — Size token controlling text and padding.
- `color`: ColorProp = 'primary' — Theme color token or custom color used for indicators and active states.
- `orientation`: 'horizontal' | 'vertical' = 'horizontal' — Orientation of the tab list.
- `location`: 'start' | 'end' = 'start' — Placement of the tabs relative to their content. Influences indicator positioning.
- `scrollable`: boolean = false — Enables scrolling when tabs overflow the available axis.
- `animated`: boolean = true — Enables animated indicator transitions between tabs.
- `animationDuration`: number = 250 — Duration (ms) for indicator animations when `animated` is true.
- `transitionDuration`: number = 250 — Duration (ms) of the indicator transition. Cross-component spelling that takes precedence over `animationDuration`; `0` moves the indicator instantly. Always 0 under reduced motion.
- `tabStyle`: StyleProp<ViewStyle> — Style overrides applied to each tab pressable.
- `contentStyle`: StyleProp<ViewStyle> — Style for the active tab content wrapper.
- `textStyle`: StyleProp<TextStyle> — Additional text style applied to tab labels.
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to each tab's label `<Text>` (style, fw, ff, size, c). Applies to all tabs in the strip; per-tab styling can still be done via `TabItem.label` (custom node).
- `disabledKeys`: string[] — Array of tab keys that should be rendered disabled.
- `radius`: RadiusValue — Corner radius of every tab (chip, card and folder variants): a radius token, px number, `'none'` or `'full'`.
- `tabCornerRadius`: number — Corner radius applied to the tab elements (variant dependent).
- `contentCornerRadius`: number — Corner radius applied to the content panel. Falls back to theme defaults when omitted.
- `indicatorThickness`: number — Thickness (px) of the line indicator. Applies to `line` variant primarily.
- `tabGap`: number — Gap (px) inserted between tabs.
- `activeTabBackgroundColor`: string — Override background color for the active tab. Accepts theme tokens.
- `inactiveTabBackgroundColor`: string — Override background color for inactive tabs.
- `activeTabTextColor`: string — Explicit text color for the active tab label.
- `persistKey`: string — Key used to persist the active tab selection across sessions.
- `autoPersist`: boolean = true — Determines whether internal persistence should be enabled when `persistKey` is provided.
- `navigationOnly`: boolean = false — When true, the component only renders the tab list and forwards children for custom content.
- `children`: ReactNode — Optional custom content rendered below the tab list when `navigationOnly` is enabled.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface TabItem {
  /**
   * Unique identifier for the tab. This is also the value returned in callbacks and
   * persisted when `persistKey` / `autoPersist` are used.
   */
  key: string;
  /**
   * Main tab label. Accepts a string or custom React node for iconographic or styled content.
   */
  label: string | ReactNode;
  /**
   * Optional secondary content beside the label. A string renders as a
   * superscript; a node (e.g. a count `Badge`) renders as given.
   */
  subLabel?: string | ReactNode;
  /**
   * Content rendered when the tab becomes active. Ignored when `navigationOnly` is true.
   */
  content: ReactNode;
  /**
   * When true the tab is visually disabled and interaction is delegated to `onDisabledTabPress`.
   */
  disabled?: boolean;
  /**
   * Optional icon rendered alongside the label (decorative: hidden from
   * assistive technology).
   */
  icon?: ReactNode;
  /**
   * Accessible name for the tab. Required when `label` has no text (an
   * icon-only tab); otherwise the name comes from the label.
   */
  accessibilityLabel?: string;
}
```

## Examples

### Basics

Pass `items` with a `key`, `label`, and `content` for each tab; the active tab's content renders below the tab list.

```tsx
import { Block, Tabs, Text } from '@plocks/ui';

const ITEMS = [
  {
    key: 'overview',
    label: 'Overview',
    content: <Text>High-level summary and entry point.</Text>
  },
  {
    key: 'details',
    label: 'Details',
    content: <Text>Deeper dive into metrics and configuration.</Text>
  },
  {
    key: 'activity',
    label: 'Activity',
    content: <Text>Recent events, tasks, and notifications.</Text>
  }
];

export function Demo() {
  return (
    <Block fullWidth>
      <Tabs items={ITEMS} />
    </Block>
  );
}
```

### Animated transitions

Enable `animated` and set `animationDuration` (in ms) to control how quickly the indicator slides between tabs.

```tsx
import { Block, Tabs, Text } from '@plocks/ui';

const ITEMS = [
  {
    key: 'overview',
    label: 'Overview',
    content: <Text>High-level summary and entry point.</Text>
  },
  {
    key: 'details',
    label: 'Details',
    content: <Text>Deeper dive into metrics and configuration.</Text>
  },
  {
    key: 'settings',
    label: 'Settings',
    content: <Text>Manage workspace preferences.</Text>
  }
];

export function Demo() {
  return (
    <Block fullWidth>
      <Tabs animated animationDuration={500} items={ITEMS} />
    </Block>
  );
}
```

### Disabled tabs

Show how to disable a tab while capturing interaction attempts through `onDisabledTabPress` for auditing or messaging.

```tsx
import { useState } from 'react';
import { Block, Tabs, Text } from '@plocks/ui';

const ITEMS = [
  {
    key: 'overview',
    label: 'Overview',
    content: <Text>High-level snapshot of product activity and health.</Text>
  },
  {
    key: 'analytics',
    label: 'Analytics',
    content: <Text>Dive into usage metrics, adoption trends, and retention.</Text>
  },
  {
    key: 'billing',
    label: 'Billing',
    content: <Text>Billing is temporarily disabled while invoices reconcile.</Text>,
    disabled: true
  },
  {
    key: 'settings',
    label: 'Settings',
    content: <Text>Manage workspace preferences and security controls.</Text>
  }
];

export function Demo() {
  const [lastAttempt, setLastAttempt] = useState<string | null>(null);

  return (
    <Block fullWidth>
      <Tabs items={ITEMS} onDisabledTabPress={setLastAttempt} />
      {lastAttempt && (
        <Text variant="small" c="muted">
          Pressed disabled tab: {lastAttempt}
        </Text>
      )}
    </Block>
  );
}
```

### Controlled state

Demonstrates controlled tabs that surface the active label and rely on external state updates via `onChange`.

```tsx
import { useState } from 'react';
import { Block, Tabs, Text } from '@plocks/ui';

const ITEMS = [
  {
    key: 'dashboard',
    label: '🏠 Dashboard',
    content: <Text>Monitor analytics across teams and products.</Text>
  },
  {
    key: 'settings',
    label: '⚙️ Settings',
    content: <Text>Configure notifications, permissions, and integrations.</Text>
  },
  {
    key: 'profile',
    label: '👤 Profile',
    content: <Text>Review contact details, roles, and security options.</Text>
  }
];

export function Demo() {
  const [activeTab, setActiveTab] = useState('dashboard');
  const activeLabel = ITEMS.find((item) => item.key === activeTab)?.label ?? activeTab;

  return (
    <Block fullWidth>
      <Tabs value={activeTab} onChange={setActiveTab} items={ITEMS} />
      <Text variant="small" c="muted">
        Active tab: {activeLabel}
      </Text>
    </Block>
  );
}
```

### Location

Switch tab placement between `start` and `end` to position triggers above or below the associated content.

```tsx
import { Block, Tabs, Text } from '@plocks/ui';

const LOCATIONS = ['start', 'end'] as const;

const ITEMS = [
  {
    key: 'home',
    label: 'Home',
    content: <Text>Home content.</Text>
  },
  {
    key: 'settings',
    label: 'Settings',
    content: <Text>Update your configuration.</Text>
  },
  {
    key: 'profile',
    label: 'Profile',
    content: <Text>Profile information.</Text>
  }
];

export function Demo() {
  return (
    <Block fullWidth>
      {LOCATIONS.map((location) => (
        <Block key={location} fullWidth>
          <Text variant="small" c="secondary">{location}</Text>
          <Tabs location={location} items={ITEMS} />
        </Block>
      ))}
    </Block>
  );
}
```

### Navigation only

Demonstrates `navigationOnly` tabs that render the triggers separately while a custom container handles the content region.

```tsx
import { useMemo, useState } from 'react';
import { Block, Tabs, Text, useTheme } from '@plocks/ui';

const NAV_ITEMS = [
  { key: 'home', label: 'Home' },
  { key: 'products', label: 'Products' },
  { key: 'about', label: 'About' },
  { key: 'contact', label: 'Contact' }
] as const;

const CONTENT_COPY: Record<typeof NAV_ITEMS[number]['key'], string> = {
  home: 'Welcome back! Navigation only mode keeps the tab strip separated from the view.',
  products: 'Highlight product cards, filters, or category grids below the navigation.',
  about: 'Share the company story, values, and milestones alongside persistent tabs.',
  contact: 'Surface support channels and locations while the navigation stays fixed.'
};

export function Demo() {
  const theme = useTheme();
  const [activeTab, setActiveTab] = useState<typeof NAV_ITEMS[number]['key']>('home');

  const items = useMemo(
    () => NAV_ITEMS.map(({ key, label }) => ({ key, label, content: null })),
    []
  );

  return (
    <Block fullWidth>
      <Tabs
        items={items}
        value={activeTab}
        onChange={(tabKey) => setActiveTab(tabKey as typeof NAV_ITEMS[number]['key'])}
        variant="chip"
        navigationOnly
      />
      <Block bg={theme.backgrounds.surface} borderColor={theme.backgrounds.border} radius="lg" p="lg">
        <Text>{CONTENT_COPY[activeTab]}</Text>
      </Block>
    </Block>
  );
}
```

### Orientation

Compare horizontal and vertical tab lists to understand how orientation influences page layout.

```tsx
import { Block, Tabs, Text } from '@plocks/ui';

const ORIENTATIONS = ['horizontal', 'vertical'] as const;

const ITEMS = [
  {
    key: 'general',
    label: 'General',
    content: <Text>Broad overview content.</Text>
  },
  {
    key: 'security',
    label: 'Security',
    content: <Text>Security controls and permissions.</Text>
  },
  {
    key: 'notifications',
    label: 'Notifications',
    content: <Text>Configure alerts and digests.</Text>
  }
];

export function Demo() {
  return (
    <Block fullWidth>
      {ORIENTATIONS.map((orientation) => (
        <Block key={orientation} fullWidth>
          <Text variant="small" c="secondary">{orientation}</Text>
          <Tabs orientation={orientation} items={ITEMS} />
        </Block>
      ))}
    </Block>
  );
}
```

### Variants

Compare the `line`, `chip`, and `folder` visual variants to match tabs with different design aesthetics.

```tsx
import { Block, Tabs, Text } from '@plocks/ui';

const VARIANTS = ['line', 'chip', 'folder'] as const;

const ITEMS = [
  {
    key: 'overview',
    label: 'Overview',
    content: <Text>High-level summary and entry point.</Text>
  },
  {
    key: 'details',
    label: 'Details',
    content: <Text>Deeper dive into metrics and configuration.</Text>
  },
  {
    key: 'settings',
    label: 'Settings',
    content: <Text>Manage workspace preferences.</Text>
  }
];

export function Demo() {
  return (
    <Block fullWidth>
      {VARIANTS.map((variant) => (
        <Block key={variant} fullWidth>
          <Text variant="small" c="secondary">{variant}</Text>
          <Tabs variant={variant} items={ITEMS} />
        </Block>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Text.md -->

# Text

Render typography with various variants, colors, and styling options for displaying content.

## Metadata

- Import: `import { Text } from '@plocks/ui';`
- Tags: text, typography, content, display
- Docs: https://plocks.dev/components/Text
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Text

## Props

- `children`: React.ReactNode — Text node children. Optional if using translation via `tx`.
- `tx`: string — Translation key (if provided, overrides children when found)
- `txParams`: Record<string, unknown> — Params for translation interpolation
- `variant`: HTMLTextVariant — Text variant (mirrors semantic HTML tags). `h1`–`h6` are exposed to assistive technology as headings (web: the `<h1>`–`<h6>` element; native: `role="heading"`).
- `textRole`: TextRoleName | (string & {}) — A theme text role (`theme.textRoles`) — `'panelTitle'` for the title of a panel that holds a list, `'sectionLabel'` for a group header inside one, or a role your theme adds. Supplies color, size, weight, tracking and case; `c`, `size`, `fw`, `lts` and `tt` still win over it. Typography only: pair it with `role="heading"` etc. where that applies.
- `size`: SizeValue — Size can be a size token or number (overrides variant fontSize)
- `c`: string — Text color. Accepts a `theme.text` role (`'primary'`, `'secondary'`, `'muted'`, `'disabled'`, `'link'`), a palette name (`'success'` → its readable shade), `'primary.6'` shade syntax, or any CSS color string.
- `fw`: TextWeight — Font weight (supports all CSS font-weight values)
- `ta`: 'left' | 'center' | 'right' | 'justify' — Text alignment. `left` / `right` follow React Native semantics and mirror in right-to-left layouts (web: `start` / `end`).
- `lh`: number — Line height as a multiplier (e.g., 1.5) or absolute value (> 3)
- `lts`: number — Letter spacing (tracking) in pixels
- `tt`: TextStyle['textTransform'] — Text transform: `'uppercase'`, `'lowercase'`, `'capitalize'`, or `'none'` (which also undoes a text role's case).
- `fs`: TextStyle['fontStyle'] — Font style: `'italic'` or `'normal'` (which also undoes the italic of `i` / `em` / `cite`).
- `td`: TextStyle['textDecorationLine'] — Text decoration: `'underline'`, `'line-through'`, `'underline line-through'`, or `'none'`.
- `ff`: string — Custom font family (overrides theme font)
- `flex`: number — Flex factor when text shares a row with controls.
- `shrink`: number
- `position`: 'relative' | 'absolute'
- `top`: TextStyle['top']
- `right`: TextStyle['right']
- `bottom`: TextStyle['bottom']
- `left`: TextStyle['left']
- `as`: HTMLTextVariant — Element to render on web (defaults to `variant`); also decides heading semantics.
- `selectable`: boolean — Whether text is selectable (default: true)
- `onPress`: () => void — Called when text is pressed. Pressable text is exposed as a button (pass `role="link"` for navigation) and, on web, is focusable and activates with Enter (and Space for buttons).
- `onLayout`: (event: LayoutChangeEvent) => void — Called when the text layout is calculated
- `value`: string | number — Value to display (overrides children, useful for numbers)
- `numberOfLines`: RNTextProps['numberOfLines'] — Maximum number of lines to display (native + web)
- `ellipsizeMode`: RNTextProps['ellipsizeMode'] — Ellipsis strategy when text exceeds available space
- `id`: string — Element id. On web this is the DOM `id` — headings need one to be a link target.
- `nativeID`: string — React Native alias for `id`; used when the two platforms need different values.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { H1, H2, H3, H4, H5, H6, P, Small, Strong, Bold, Italic, Emphasis, Underline, Code, Kbd, Mark, Cite, Sub, Sup } from '@plocks/ui';`

`H1`, `H2`, `H3`, `H4`, `H5`, `H6`, `P`, `Small`, `Strong`, `Bold`, `Italic`, `Emphasis`, `Underline`, `Code`, `Kbd`, `Mark`, `Cite`, `Sub`, `Sup` have no props interface of their own.

## Types

```ts
export type HTMLTextVariant =
  | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
  | 'p' | 'span' | 'div'
  | 'small' | 'caption' | 'strong' | 'b' | 'i' | 'em' | 'u'
  | 'sub' | 'sup' | 'mark' | 'code' | 'kbd'
  | 'blockquote' | 'cite';

export type TextWeight =
  | 'normal' | 'medium' | 'semibold' | 'bold' | 'light' | 'black'
  | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'
  | number;
```

## Examples

### Basics

Various different variants and semantic elements.

```tsx
import { Block, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Text variant="h1">Heading 1</Text>
      <Text variant="h2">Heading 2</Text>
      <Text variant="h3">Heading 3</Text>
      <Text variant="h4">Heading 4</Text>
      <Text variant="h5">Heading 5</Text>
      <Text variant="h6">Heading 6</Text>
      <Text>The quick brown fox jumps over the lazy dog.</Text>
      <Text variant="small">The quick brown fox jumps over the lazy dog.</Text>
    </Block>
  );
}
```

### Colors

Set `c` to a theme text role (`primary`, `secondary`, `muted`, `disabled`, `link`), a palette color or shade (`success`, `error.7`), or any CSS color.

```tsx
import { Block, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block gap="lg">
      <Block>
        <Text c="primary">primary</Text>
        <Text c="secondary">secondary</Text>
        <Text c="muted">muted</Text>
        <Text c="disabled">disabled</Text>
        <Text c="link">link</Text>
      </Block>
      <Block>
        <Text c="success">success</Text>
        <Text c="error">error</Text>
        <Text c="primary.5">primary.5</Text>
        <Text c="error.7">error.7</Text>
      </Block>
      <Block>
        <Text c="#ff6b6b">#ff6b6b</Text>
        <Text c="#4ecdc4">#4ecdc4</Text>
        <Text c="#45b7d1">#45b7d1</Text>
        <Text c="#96ceb4">#96ceb4</Text>
        <Text c="#feca57">#feca57</Text>
      </Block>
    </Block>
  );
}
```

### Variants

Compare heading, paragraph, quotation, code, and small text variants.

```tsx
import { Column, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Column gap="md">
      <Text variant="h2">Section heading</Text>
      <Text variant="p">A paragraph uses the body text role.</Text>
      <Text variant="blockquote">A quotation gets its own semantic element.</Text>
      <Text variant="code">const label = 'inline code';</Text>
      <Text variant="small">Supporting text uses the small role.</Text>
    </Column>
  );
}
```

### Weights

Set the font weight with `fw`: a named weight (`light` → `black`) or a numeric one (`100` → `900`).

```tsx
import { Block, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block gap="lg">
      <Block>
        <Text fw="light">light</Text>
        <Text fw="normal">normal</Text>
        <Text fw="medium">medium</Text>
        <Text fw="semibold">semibold</Text>
        <Text fw="bold">bold</Text>
        <Text fw="black">black</Text>
      </Block>
      <Block>
        <Text fw="100">100</Text>
        <Text fw="300">300</Text>
        <Text fw="400">400</Text>
        <Text fw="600">600</Text>
        <Text fw="700">700</Text>
        <Text fw="900">900</Text>
      </Block>
    </Block>
  );
}
```

### Font family

`ff` sets the font family. Title, Highlight, the H1–H6 / Code / Kbd / Bold / Italic aliases, GradientText, ShimmerText, and every `<Text>` slot prop (`labelProps`, `descriptionProps`, …) take it too.

```tsx
import { Block, H3, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Text ff="monospace">monospace</Text>
      <Text ff="Courier New">Courier New</Text>
      <H3 ff="Georgia, serif">Heading in Georgia</H3>
    </Block>
  );
}
```

### Sizes

Different text sizes from small to large.

```tsx
import { Block, Row, Text } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Text size={size}>Aa</Text>
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Heights

Set line height with `lh`. ## Usage `lh` accepts: - **Multipliers** (e.g., `1.5`) - multiplied by the font size - **Absolute values** (e.g., `24`) - treated as pixel values when > 3 ```tsx <Text lh={1.2}>Tight line height</Text> <Text lh={1.5}>Normal line height</Text> <Text lh={24}>Absolute line height (24px)</Text> ``` This provides precise control over text spacing and readability.

```tsx
import { Block, Text } from '@plocks/ui';

const LINE_HEIGHTS = [1.2, 1.5, 1.8, 2, 24];

const SAMPLE_TEXT =
  'The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs. Sphinx of black quartz, judge my vow. How vexingly quick daft zebras jump.';

export function Demo() {
  return (
    <Block fullWidth gap="lg">
      {LINE_HEIGHTS.map((lineHeight) => (
        <Block key={lineHeight}>
          <Text variant="small" c="secondary">{lineHeight}</Text>
          <Text lh={lineHeight}>{SAMPLE_TEXT}</Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Tracking

Set letter spacing in pixels with `lts`. Negative values tighten spacing and positive values loosen it.

```tsx
import { Block, Text } from '@plocks/ui';

const TRACKING = [-1, -0.5, 0, 0.5, 1, 2, 4];

export function Demo() {
  return (
    <Block>
      {TRACKING.map((tracking) => (
        <Text key={tracking} lts={tracking}>
          Tracking {tracking}
        </Text>
      ))}
    </Block>
  );
}
```

### Text transform

Set `tt` to `uppercase`, `lowercase`, or `capitalize` to change the case of text without changing the string. `none` turns off the case a text role applies.

```tsx
import { Block, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Text tt="uppercase">uppercase</Text>
      <Text tt="lowercase">LOWERCASE</Text>
      <Text tt="capitalize">capitalize each word</Text>
    </Block>
  );
}
```

### Style and decoration

`fs` sets the font style (`italic`, `normal`) and `td` the decoration (`underline`, `line-through`, `none`). Both override the aliases that set them, so `<Italic fs="normal">` renders upright.

```tsx
import { Block, Italic, Text } from '@plocks/ui';

export function Demo() {
  return (
    <Block>
      <Text fs="italic">italic</Text>
      <Text td="underline">underline</Text>
      <Text td="line-through">line-through</Text>
      <Italic fs="normal">Italic, set upright</Italic>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/TextArea.md -->

# TextArea

The TextArea component provides a multi-line text input with support for auto-resizing, character counting, validation states, and flexible sizing options.

## Metadata

- Import: `import { TextArea } from '@plocks/ui';`
- Tags: input, textarea, multiline, text, form, validation
- Docs: https://plocks.dev/components/TextArea
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/TextArea

## Props

- `id`: string — Id of the TextInput; label/error ids derive from it. Generated when omitted.
- `rows`: number — Number of visible text rows (default 3).
- `minRows`: number — Minimum number of rows while `autoResize` is on.
- `maxRows`: number — Maximum number of rows while `autoResize` is on (then it scrolls).
- `autoResize`: boolean — Grow and shrink with the content, between `minRows` and `maxRows`.
- `maxLength`: number — Character limit
- `showCharCounter`: boolean — Show a `count/maxLength` counter under the field (needs `maxLength`).
- `h`: number — Fixed height of the text box in px (overrides `rows`). Sizes the box, not the root.
- `resize`: 'none' | 'vertical' | 'horizontal' | 'both' — Whether the user may resize the field (web only; CSS `resize`). Default `'none'`.
- `textInputProps`: ExtendedTextInputProps — Additional TextInput props
- `autoCapitalize`: RNTextInputProps['autoCapitalize'] — Text auto-capitalization behavior
- `autoCorrect`: boolean — Whether to enable auto-correct
- `autoFocus`: boolean — Whether to auto-focus on mount
- `returnKeyType`: RNTextInputProps['returnKeyType'] — Return key type for soft keyboard
- `blurOnSubmit`: boolean — Whether to blur on submit
- `selectTextOnFocus`: boolean — Select all text on focus
- `textContentType`: RNTextInputProps['textContentType'] — iOS text content type for autofill
- `textAlign`: RNTextInputProps['textAlign'] — Text alignment
- `spellCheck`: boolean — Whether spell check is enabled
- `inputMode`: RNTextInputProps['inputMode'] — Input mode (modern alternative to keyboardType)
- `enterKeyHint`: RNTextInputProps['enterKeyHint'] — Enter key hint
- `selectionColor`: string — Color of the text selection handles and highlight
- `showSoftInputOnFocus`: boolean — Whether to show the soft keyboard on focus
- `editable`: boolean — Passthrough to the TextInput. Prefer `readOnly`; `editable={false}` behaves the same.
- `scrollEnabled`: boolean — Whether the text scrolls inside the field (defaults to `!autoResize`).
- `w`: DimensionProp — Width
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

A controlled `TextArea` with a `label` and `description`; `rows` sets how many lines it shows before scrolling.

```tsx
import { useState } from 'react';

import { Block, TextArea } from '@plocks/ui';

export function Demo() {
  const [value, setValue] = useState('');

  return (
    <Block fullWidth>
      <TextArea
        label="Message"
        placeholder="Enter your message"
        value={value}
        onChangeText={setValue}
        description="Provide helpful context for your request."
        rows={4}
        fullWidth
      />
    </Block>
  );
}
```

### Features

Showcases auto-resize, character counting, validation, disabled, and required helper scenarios.

```tsx
import { useState } from 'react';

import { Block, TextArea } from '@plocks/ui';

export function Demo() {
  const [autoResizeValue, setAutoResizeValue] = useState(
    'Type more text to see auto-resize in action...\n\nAdd multiple lines to watch the text area grow and shrink with content.'
  );
  const [counterValue, setCounterValue] = useState('');
  const [errorValue, setErrorValue] = useState('');

  return (
    <Block fullWidth>
      <TextArea
        label="Auto-resize message"
        placeholder="Adjusts height between two and six rows based on content."
        value={autoResizeValue}
        onChangeText={setAutoResizeValue}
        autoResize
        minRows={2}
        maxRows={6}
        fullWidth
      />

      <TextArea
        label="Support message"
        placeholder="Type to see the counter (max 100 characters)"
        value={counterValue}
        onChangeText={setCounterValue}
        maxLength={100}
        showCharCounter
        rows={3}
        fullWidth
      />

      <TextArea
        label="Required response"
        placeholder="This field cannot be empty"
        value={errorValue}
        onChangeText={setErrorValue}
        error={errorValue.length > 0 ? undefined : 'A response is required before submission.'}
        required
        rows={3}
        fullWidth
      />

      <TextArea
        label="Disabled text area"
        placeholder="Disabled state"
        value="This text area is disabled and cannot be edited."
        disabled
        rows={2}
        fullWidth
      />

      <TextArea
        label="Required with helper"
        placeholder="Add details"
        required
        rows={2}
        helperText="Required fields display an asterisk and supporting guidance."
        fullWidth
      />
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on TextArea.

```tsx
import { Column, TextArea } from '@plocks/ui';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <TextArea key={variant} variant={variant} label={`${variant} variant`} placeholder="Write a note" rows={2} />
      ))}
    </Column>
  );
}
```

### Sizes

Walks the full `size` scale, `xs` through `3xl`, so the field matches the surrounding form density.

```tsx
import { Block, Text, TextArea } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block fullWidth>
      {SIZES.map((size) => (
        <Block key={size} fullWidth>
          <Text variant="small" c="secondary">{size}</Text>
          <TextArea size={size} rows={3} placeholder="Write a message" fullWidth />
        </Block>
      ))}
    </Block>
  );
}
```

### Validation

Validate on submit and pass the message to `error`: it replaces the `helperText` and marks the field invalid until the user edits it again.

```tsx
import { useState } from 'react';

import { Block, Button, TextArea } from '@plocks/ui';

export function Demo() {
  const [feedback, setFeedback] = useState('');
  const [error, setError] = useState<string>();

  const handleSubmit = () => {
    if (!feedback.trim()) {
      setError('Feedback is required.');
    } else if (feedback.trim().length < 10) {
      setError('Feedback must be at least 10 characters.');
    }
  };

  return (
    <Block fullWidth>
      <TextArea
        label="Feedback"
        placeholder="Share your thoughts (minimum 10 characters)"
        value={feedback}
        onChangeText={(value) => {
          setFeedback(value);
          setError(undefined);
        }}
        error={error}
        required
        rows={4}
        helperText="Tell us what went well and what could improve."
        fullWidth
      />
      <Button variant="filled" onPress={handleSubmit}>
        Submit feedback
      </Button>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Timeline.md -->

# Timeline

Timeline component displays a sequence of events or steps in chronological order with customizable styling and layout options.

## Metadata

- Import: `import { Timeline } from '@plocks/ui';`
- Tags: timeline, chronological, events, history, steps
- Docs: https://plocks.dev/components/Timeline
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Timeline

## Props

- `children` (required): ReactNode — Timeline items
- `active`: number — Active item index - items before this will be highlighted
- `color`: ColorProp — Timeline color. Palette token, `'primary.5'` shade syntax, or any CSS color.
- `titleColor`: string — Default title color for all items
- `descriptionColor`: string — Default description color for all items
- `timestampColor`: string — Default timestamp color for all items
- `lineWidth`: number — Line width
- `bulletSize`: number — Bullet size
- `align`: 'left' | 'right' — Side of the spine the content sits on (`left` = start side, `right` = end side; they flip under RTL)
- `reverseActive`: boolean — Reverse active highlighting
- `size`: SizeValue — Component size: a size token, or the title font size in px
- `centerMode`: boolean — Center mode renders a single central spine allowing items on both sides via itemAlign prop
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

### Timeline.Item

- `children`: ReactNode — Item content
- `title`: string — Item title
- `timestamp`: ReactNode — Optional timestamp text or node
- `bullet`: ReactNode — Custom bullet content (icon, avatar, etc.)
- `lineVariant`: 'solid' | 'dashed' | 'dotted' — Line variant for this item
- `color`: ColorProp — Item color (overrides timeline color). Palette token, `'primary.5'` shade syntax, or any CSS color.
- `titleColor`: string — Override title text color for this item
- `descriptionColor`: string — Override description text color for this item
- `timestampColor`: string — Override timestamp text color for this item
- `active`: boolean — Whether this item is active
- `itemAlign`: 'left' | 'right' — Override timeline alignment for this specific item (`left` = start side, `right` = end side; they flip under RTL)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Use `Timeline.Item` components to communicate major project milestones alongside short descriptions.

```tsx
import { Text, Timeline } from '@plocks/ui';

const events = [
  {
    title: 'Discovery',
    description: 'Ran stakeholder interviews and confirmed the project scope.',
    timestamp: '3 weeks ago',
  },
  {
    title: 'Design',
    description: 'Delivered the initial design system and screen mocks.',
    timestamp: '2 weeks ago',
  },
  {
    title: 'Development',
    description: 'Implementing core flows while gathering early feedback.',
    timestamp: 'Last week',
  },
  {
    title: 'Validation',
    description: 'QA pass is underway with regression tracking in place.',
    timestamp: 'In progress',
  },
];

export function Demo() {
  return (
    <Timeline active={2}>
      {events.map((event) => (
        <Timeline.Item key={event.title} title={event.title}>
          <Text c="secondary" size="xs">
            {event.timestamp}
          </Text>
          <Text size="sm">{event.description}</Text>
        </Timeline.Item>
      ))}
    </Timeline>
  );
}
```

### Alignment Options

Showcase left, right, and centered layouts by toggling `align` or `centerMode` on the timeline.

```tsx
import { Block, Text, Timeline } from '@plocks/ui';

const phases = [
  { title: 'Kickoff', description: 'Establish scope, goals, and responsible stakeholders.' },
  { title: 'Execution', description: 'Track feature work and unblock contributors.' },
  { title: 'Review', description: 'Collect feedback and iterate on the release candidate.' },
];

export function Demo() {
  return (
    <Block fullWidth gap="lg">
      <Block>
        <Text fw="semibold">Left</Text>
        <Timeline>
          {phases.map((phase) => (
            <Timeline.Item key={phase.title} title={phase.title}>
              <Text size="sm">{phase.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>

      <Block>
        <Text fw="semibold">Right</Text>
        <Timeline align="right">
          {phases.map((phase) => (
            <Timeline.Item key={phase.title} title={phase.title}>
              <Text size="sm">{phase.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>

      <Block>
        <Text fw="semibold">Center</Text>
        <Timeline centerMode>
          {phases.map((phase) => (
            <Timeline.Item key={phase.title} title={phase.title}>
              <Text size="sm">{phase.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
    </Block>
  );
}
```

### Bullet Customization

Swap bullet content or adjust bullet sizing using the `bullet` and `bulletSize` props.

```tsx
import { Block, Icon, Text, Timeline } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Timeline bulletSize={28}>
        <Timeline.Item title="Default" />
        <Timeline.Item title="Numbered" bullet={<Text size="xs" fw="semibold">1</Text>} />
        <Timeline.Item title="Completed" bullet={<Icon name="check" size={12} color="#0E8A16" />} />
        <Timeline.Item title="Pending" bullet={<Icon name="clock" size={12} color="#F59E0B" />} />
      </Timeline>
    </Block>
  );
}
```

### Line Styling

Demonstrate how `color` and `lineWidth` affect the connector line.

```tsx
import { Block, Text, Timeline } from '@plocks/ui';

const launches = [
  { title: 'Announcement', description: 'Introduced the roadmap to stakeholders.' },
  { title: 'Preview', description: 'Shared early access resources with champions.' },
  { title: 'Release', description: 'Rolled the feature out to everyone.' },
];

export function Demo() {
  return (
    <Block fullWidth gap="lg">
      <Block>
        <Text fw="semibold">Theme color</Text>
        <Timeline color="primary.6">
          {launches.map((milestone) => (
            <Timeline.Item key={milestone.title} title={milestone.title}>
              <Text size="sm">{milestone.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>

      <Block>
        <Text fw="semibold">Thicker connector</Text>
        <Timeline lineWidth={4}>
          {launches.map((milestone) => (
            <Timeline.Item key={milestone.title} title={milestone.title}>
              <Text size="sm">{milestone.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>

      <Block>
        <Text fw="semibold">Combined styling</Text>
        <Timeline color="success.6" lineWidth={3}>
          {launches.map((milestone) => (
            <Timeline.Item key={milestone.title} title={milestone.title}>
              <Text size="sm">{milestone.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
    </Block>
  );
}
```

### Line Variants

Compare solid, dashed, and dotted connectors, including mixed variants within a single flow.

```tsx
import { Block, Text, Timeline } from '@plocks/ui';

const phases = ['Start', 'Plan', 'Build'];

const variantExamples = [
  { label: 'Solid (default)', variant: undefined },
  { label: 'Dashed', variant: 'dashed' as const },
  { label: 'Dotted', variant: 'dotted' as const },
];

const releaseFlow = [
  { title: 'Planning', variant: 'solid' as const },
  { title: 'Design', variant: 'dashed' as const },
  { title: 'Development', variant: 'dotted' as const },
  { title: 'QA', variant: 'dashed' as const },
  { title: 'Launch', variant: 'solid' as const },
];

export function Demo() {
  return (
    <Block direction="row" justify="space-between" fullWidth>
      {variantExamples.map((example) => (
        <Block key={example.label}>
          <Text fw="semibold">{example.label}</Text>
          <Timeline>
            {phases.map((title) => (
              <Timeline.Item key={`${example.label}-${title}`} title={title} lineVariant={example.variant} />
            ))}
          </Timeline>
        </Block>
      ))}
      <Block>
        <Text fw="semibold">Mix line variants</Text>
        <Timeline>
          {releaseFlow.map((step) => (
            <Timeline.Item key={step.title} title={step.title} lineVariant={step.variant} />
          ))}
        </Timeline>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/TimePicker.md -->

# TimePicker

TimePicker provides an inline panel for choosing hours, minutes, and optional seconds.

## Metadata

- Import: `import { TimePicker } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Status: beta
- Docs: https://plocks.dev/components/TimePicker
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/TimePicker

## Props

- `value`: TimePickerValue | null — Controlled value. `null` shows the default time (00:00, or 12:00 AM).
- `defaultValue`: TimePickerValue | null
- `onChange`: (next: TimePickerValue) => void — Fired on every column selection.
- `onChangeComplete`: (next: TimePickerValue) => void — Fired when the user picks from the last meaningful column — minutes, or seconds when `withSeconds` is set. `TimePickerInput` uses this to drive `autoClose`.
- `format`: 12 | 24 = 24
- `withSeconds`: boolean = false
- `minuteStep`: number = 5
- `secondStep`: number = 5
- `columnWidth`: number = 88 — Width of each scroll column (hours/minutes/seconds).
- `columnHeight`: number = 200 — Max height of each scroll column.
- `disabled`: boolean = false
- `accessibilityLabel`: string = 'Time' — Accessible name of the column group. @default 'Time'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface TimePickerValue {
  hours: number; // 0-23 internal
  minutes: number; // 0-59
  seconds?: number; // 0-59
}
```

## Examples

### Basics

Basic controlled usage of the inline TimePicker panel with 24-hour format.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { TimePicker } from '@plocks/dates';
import type { TimePickerValue } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<TimePickerValue>({ hours: 13, minutes: 30 });

  const formatted = `${String(value.hours).padStart(2, '0')}:${String(value.minutes).padStart(2, '0')}`;

  return (
    <Block fullWidth>
      <TimePicker value={value} onChange={setValue} />
      <Text size="sm" c="secondary">{`Selected: ${formatted}`}</Text>
    </Block>
  );
}
```

### Format 12h

Using 12-hour clock format with AM/PM toggle.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { TimePicker } from '@plocks/dates';
import type { TimePickerValue } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<TimePickerValue>({ hours: 0, minutes: 15 });

  const formatted = `${String(value.hours).padStart(2, '0')}:${String(value.minutes).padStart(2, '0')}`;

  return (
    <Block fullWidth>
      <TimePicker value={value} onChange={setValue} format={12} />
      <Text size="sm" c="secondary">
        {`Internal (24h): ${formatted}`}
      </Text>
    </Block>
  );
}
```

### With Seconds

Including seconds selection in the TimePicker panel.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { TimePicker } from '@plocks/dates';
import type { TimePickerValue } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<TimePickerValue>({ hours: 9, minutes: 5, seconds: 30 });

  const formatted = `${String(value.hours).padStart(2, '0')}:${String(value.minutes).padStart(2, '0')}:${String(value.seconds || 0).padStart(2, '0')}`;

  return (
    <Block fullWidth>
      <TimePicker value={value} onChange={setValue} withSeconds />
      <Text size="sm" c="secondary">{`Selected: ${formatted}`}</Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/TimePickerInput.md -->

# TimePickerInput

TimePickerInput opens a time picker from a form field and displays the selected time.

## Metadata

- Import: `import { TimePickerInput } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Status: beta
- Docs: https://plocks.dev/components/TimePickerInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/TimePickerInput

## Props

- `value`: TimePickerValue | null
- `defaultValue`: TimePickerValue | null
- `onChange`: (next: TimePickerValue | null) => void — Emits `null` when the field is cleared, which the inline panel never does.
- `allowInput`: boolean = true — Allow typing a time directly into the field (`hh:mm`, `hh:mm:ss`, optional AM/PM). @default true
- `panelWidth`: number — Width of the sheet holding the panel.
- `onOpen`: () => void — Called when the panel opens.
- `onClose`: () => void — Called when the panel closes.
- `title`: string = 'Select time' — Title of the panel sheet. @default 'Select time'
- `autoClose`: boolean = false — Close the panel as soon as the last column is picked, hiding the Done button.
- `pickerButtonLabel`: string = 'Choose time' — Accessible label of the button that opens the panel. @default 'Choose time'
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `TimePicker` props (`format` `withSeconds` `minuteStep` `secondStep` `columnWidth`): https://plocks.dev/llms/components/TimePicker.md

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

TimePickerInput opens a time picker from a form field and displays the selected time.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { TimePickerInput } from '@plocks/dates';
import type { TimePickerValue } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<TimePickerValue | null>({ hours: 9, minutes: 30 });

  const formatted = value
    ? `${((value.hours + 11) % 12) + 1}:${String(value.minutes).padStart(2, '0')} ${value.hours >= 12 ? 'PM' : 'AM'}`
    : null;

  return (
    <Block fullWidth>
      <TimePickerInput
        value={value}
        onChange={setValue}
        label="Meeting time"
        format={12}
        fullWidth
      />
      <Text size="sm" c="secondary">
        {formatted ? `Selected: ${formatted}` : 'No time selected'}
      </Text>
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on TimePickerInput.

```tsx
import { Column } from '@plocks/ui';
import { TimePickerInput } from '@plocks/dates';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <TimePickerInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Choose a time" />
      ))}
    </Column>
  );
}
```

### Validation

Validation example showing custom error when outside allowed business hours (09:00-17:00).

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { TimePickerInput } from '@plocks/dates';
import type { TimePickerValue } from '@plocks/dates';

const withinBusiness = (v: TimePickerValue) => {
  const totalMinutes = v.hours * 60 + v.minutes;
  return totalMinutes >= 9 * 60 && totalMinutes <= 17 * 60; // 09:00 - 17:00 inclusive
};

export function Demo() {
  const [value, setValue] = useState<TimePickerValue | null>({ hours: 8, minutes: 45 });
  const [error, setError] = useState<string | undefined>(undefined);

  const handleChange = (next: TimePickerValue | null) => {
    setValue(next);
    if (!next) {
      setError(undefined);
      return;
    }

    if (!withinBusiness(next)) {
      setError('Select a time between 09:00 and 17:00');
    } else {
      setError(undefined);
    }
  };

  return (
    <Block fullWidth>
      <TimePickerInput
        value={value}
        onChange={handleChange}
        label="Meeting time"
        error={error}
        helperText="Business hours only"
        clearable
        fullWidth
      />
      {value && (
        <Text size="sm" c="secondary">
          Selected: {value.hours.toString().padStart(2, '0')}:{value.minutes.toString().padStart(2, '0')}
        </Text>
      )}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Title.md -->

# Title

Semantic heading component mapping `order={1..6}` to typography variants `h1..h6` while offering decorative enhancements like underline, afterline, and prefix adornments.

## Metadata

- Import: `import { Title } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Title
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Title

## Props

- `text`: string — The text content to display in the title
- `order`: 1 | 2 | 3 | 4 | 5 | 6 — The heading level (1-6): the level exposed to assistive technology (web `<hN>`, native `role="heading"`) and the default typography.
- `underline`: boolean — Whether to show an underline decoration below the title
- `afterline`: boolean — Whether to show a line after the title text
- `underlineColor`: string — Color of the underline decoration
- `underlineStroke`: number — Thickness/stroke width of the underline in pixels
- `afterlineGap`: number — Gap between the title text and afterline in pixels
- `underlineOffset`: number — Vertical offset of the underline from the text baseline in pixels
- `prefix`: boolean | React.ReactNode — Prefix decoration - can be a boolean to show default prefix or a custom React element
- `prefixVariant`: 'bar' | 'dot' — Style variant for the default prefix decoration
- `prefixColor`: string — Color of the prefix decoration
- `prefixSize`: number — Size of the prefix decoration in pixels
- `prefixLength`: number — Length of the prefix decoration (for bar variant) in pixels
- `prefixGap`: number — Gap between the prefix and title text in pixels
- `prefixRadius`: number — Border radius of the prefix decoration in pixels
- `style`: StyleProp<TextStyle> — Additional styles to apply to the title text element
- `variant`: TextProps['variant'] — Typography variant for the text. Defaults to the `h<order>` variant; only changes the look — the heading level still follows `order`.
- `containerStyle`: StyleProp<ViewStyle> — Additional styles to apply to the container wrapping the entire title
- `startIcon`: React.ReactNode — Icon element to display on the left side of the title
- `endIcon`: React.ReactNode — Icon element to display on the right side of the title
- `action`: React.ReactNode — Action button or element positioned at the far right of the title
- `subtitle`: React.ReactNode — Optional subtitle displayed below the title
- `subtitleProps`: Partial<TextProps> — Additional Text props applied to the subtitle when rendered as Text
- `subtitleSpacing`: number — Spacing between the title and subtitle in pixels (default: 8)
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Plus the `Text` props (`children` `tx` `txParams` `textRole` `size` `c` `fw` `ta` `lh` `lts` `tt` `fs` `td` `ff` `flex` `shrink` `position` `top` `right` `bottom` `left` `as` `selectable` `onPress` `onLayout` `value` `numberOfLines` `ellipsizeMode` `id` `nativeID`): https://plocks.dev/llms/components/Text.md

Also accepts the shared props — base (`testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { Heading1, Heading2, Heading3, Heading4, Heading5, Heading6 } from '@plocks/ui';`

`Heading1`, `Heading2`, `Heading3`, `Heading4`, `Heading5`, `Heading6` have no props interface of their own.

## Examples

### Basics

Default Title usage shows the h2-style heading produced by the component without additional props.

```tsx
import { Block, Title } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Title>Default section heading</Title>
    </Block>
  );
}
```

### Heading Levels

Set the `order` prop to align Title with semantic heading levels from h1 through h6.

```tsx
import { Block, Title } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Title order={1}>Page heading (order=1)</Title>
      <Title order={2}>Section heading (order=2)</Title>
      <Title order={3}>Subsection heading (order=3)</Title>
      <Title order={4}>Fourth-level heading (order=4)</Title>
      <Title order={5}>Fifth-level heading (order=5)</Title>
      <Title order={6}>Sixth-level heading (order=6)</Title>
    </Block>
  );
}
```

### Variants

Keep heading level three while changing its typography with the variant prop.

```tsx
import { Column, Text, Title } from '@plocks/ui';

const variants = ['h2', 'h3', 'h4'] as const;

export function Demo() {
  return (
    <Column gap="md">
      {variants.map(variant => (
        <Column key={variant} gap="xs">
          <Text size="xs" c="secondary">order=3 · variant={variant}</Text>
          <Title order={3} variant={variant}>Section title</Title>
        </Column>
      ))}
    </Column>
  );
}
```

### Prefix Styles

Enable the `prefix` prop to add visual markers, switching variants or supplying a custom icon for emphasis.

```tsx
import { Block, Icon, Title } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Title prefix>Default bar prefix</Title>
      <Title prefix prefixVariant="dot">Dot prefix</Title>
      <Title prefix prefixSize={6} prefixLength={40} prefixColor="#6366f1">
        Custom bar size and color
      </Title>
      <Title prefix={<Icon name="star" />} prefixGap={8} prefixColor="#f59e0b">
        Icon prefix with custom color
      </Title>
    </Block>
  );
}
```

### Underlines

Toggle `underline` and `afterline` to add emphasis and separation, including custom color and stroke weights.

```tsx
import { Block, Title } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Title underline>Underline only</Title>
      <Title afterline>Afterline only</Title>
      <Title underline afterline>Underline with afterline</Title>
      <Title underline underlineColor="#ff4d4f" underlineStroke={4}>
        Custom underline color and stroke
      </Title>
    </Block>
  );
}
```

### Actions

Pass an `action` element to align buttons or toggles alongside the heading.

```tsx
import { Block, Button, Title } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Title action={<Button title="Edit" size="sm" variant="outline" />}>Profile</Title>
    </Block>
  );
}
```

### Combined Accents

Mix prefix, underline, and afterline props to create a primary heading and aligned subsection titles with consistent accents.

```tsx
import { Block, Title } from '@plocks/ui';

export function Demo() {
  return (
    <Block fullWidth>
      <Title
        prefix
        underline
        afterline
        prefixSize={6}
        prefixLength={48}
        prefixColor="#10b981"
        underlineStroke={3}
      >
        Analytics overview
      </Title>
      <Title
        order={3}
        prefix
        prefixVariant="dot"
        prefixColor="#ef4444"
        underline
        underlineColor="#ef4444"
      >
        Active users
      </Title>
      <Title
        order={3}
        prefix
        prefixVariant="dot"
        prefixColor="#6366f1"
        underline
        underlineColor="#6366f1"
      >
        Conversion rate
      </Title>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Toast.md -->

# Toast

Toast displays a temporary notification about an action or event.

## Metadata

- Import: `import { Toast } from '@plocks/ui';`
- Tags: toast, notification, alert, message, feedback
- Docs: https://plocks.dev/components/Toast
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Toast

## Props

- `variant`: 'light' | 'filled' | 'outline' = 'light' — Toast variant
- `size`: ComponentSizeValue = 'md' — Size token controlling padding, typography, icon, and close-button scale. Accepts any of the seven component tokens (`xs`–`3xl`) or a number, which is read as the title font size and scales the rest proportionally.
- `color`: ThemeColor = 'gray' — Toast color - can be theme color or custom color string
- `severity`: 'info' | 'success' | 'warning' | 'error' — Severity level — sets the color, the default icon, and the haptic played on appear. More than a color: prefer it over `color` for status toasts.
- `title`: string — Toast title
- `children`: React.ReactNode — Toast content
- `icon`: React.ReactNode — Icon to display
- `withCloseButton`: boolean = true — Whether to show close button
- `loading`: boolean = false — Whether to show loading indicator
- `closeButtonLabel`: string = 'Close notification' — Close button accessibility label
- `onClose`: () => void — Callback when close button is pressed
- `onExited`: () => void — Fired once the hide transition has finished playing. `ToastProvider` uses this to unmount a toast exactly when it finishes leaving instead of on a fixed timer, so a custom `transitionDuration` never gets cut short.
- `visible`: boolean = false — Whether the toast is visible
- `animationDuration`: number = 300 — Animation duration in ms
- `transitionDuration`: number = 300 — Show/hide transition length in ms. Cross-component spelling that takes precedence over `animationDuration`; `0` shows and hides with no animation.
- `autoHide`: number = 4000 — Auto hide duration in ms (0 to disable)
- `paused`: boolean = false — Suspends the auto-hide countdown without resetting it; clearing it resumes with the time that was left. `ToastProvider` sets this for every toast in a stack while the pointer or keyboard focus is inside that stack.
- `position`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Edge the toast enters from (animation direction)
- `style`: StyleProp<ViewStyle> — Container style
- `testID`: string — Test ID for testing
- `actions`: ToastAction[] — Action buttons
- `dismissOnTap`: boolean = false — Whether toast can be dismissed by tapping
- `persistent`: boolean = false — Persist toast until manually dismissed
- `keepMounted`: boolean = true — Keep toast mounted in the tree when hidden
- `animationConfig`: ToastAnimationConfig — Animation configuration
- `swipeConfig`: ToastSwipeConfig — Swipe to dismiss configuration
- `onSwipeDismiss`: () => void — Callback when toast is dismissed via swipe
- `selectable`: boolean = false — Whether the toast text can be selected. Toasts are transient chrome that is usually swiped or tapped, so a press-and-hold that starts a selection reads as a glitch rather than an affordance.
- `titleProps`: Omit<TextProps, 'children'> — Override props applied to the title `<Text>` (style, fw, ff, size, c).
- `bodyProps`: Omit<TextProps, 'children'> — Override props applied to the body `<Text>` (the `children` content).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), `radius`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ToastProvider } from '@plocks/ui';`

### ToastProvider

- `children` (required): React.ReactNode
- `defaultPosition`: 'top-left' | 'top-right' | 'top-center' | 'bottom-left' | 'bottom-right' | 'bottom-center' — Default position for toasts
- `limit`: number — Maximum number of toasts per position
- `autoHide`: number — Default auto hide duration
- `defaultVariant`: 'light' | 'filled' | 'outline' — Default visual variant applied to toasts that don't specify their own
- `defaultSize`: ComponentSizeValue — Default size token applied to toasts that don't specify their own
- `offset`: ToastViewportOffset — Static viewport offset (px) reserved for app chrome. A dynamic offset published via `useToastViewportOffset` / `setToastViewportOffset` takes precedence per-axis when set.
- `queueOptions`: Partial<ToastQueueOptions> — Queue management options

## Related hooks

- `useToast()` — Returns the toast API (`show`, `update`, `hide`, `hideAll`, `promise`, `success` / `error` / `info` / `warning`, …) of the nearest `ToastProvider`; it never throws — outside a provider it returns the global `toasts` object, which queues calls until one mounts (use `useOptionalToast()` to get `null` instead).
- `useToastApi()` — Returns the same toast API as `useToast()` (an alias): the nearest `ToastProvider`'s `show` / `update` / `hide` / … methods, or the global `toasts` queue outside one — never throws.
- `useToastViewportOffset(offset: ToastViewportOffset)` — Publishes a viewport offset (`top` / `bottom` / `left` / `right`, in px) for every toast stack while the calling component is mounted — it works anywhere in the tree, no provider needed — and clears it on unmount, when the `ToastProvider`'s static `offset` applies again.
- `useOptionalToast(): ToastContextValue | null` — Returns the nearest `ToastProvider`'s toast API, or `null` when none is mounted — for components that show a toast only if the app has somewhere to render it (`useToast()` falls back to the global `toasts` queue instead).
- `useActiveToasts()` — Returns the toasts the nearest `ToastProvider` currently holds (as `ToastItem`s, including ones mid-exit with `visible: false`) and re-renders when that list changes — for counters, badges or a custom toast list; outside a provider it returns a non-reactive snapshot (empty when no provider is mounted) instead of throwing.

## Types

```ts
export interface ToastAction {
  label: string;
  onPress: () => void;
  color?: string;
}

export interface ToastAnimationConfig {
  type?: ToastAnimationType;
  duration?: number;
  springConfig?: {
    damping?: number;
    stiffness?: number;
    mass?: number;
  };
  /** Easing function (a reanimated `Easing`). */
  easing?: (value: number) => number;
}

export interface ToastSwipeConfig {
  enabled?: boolean;
  threshold?: number; // Distance to trigger dismiss
  direction?: 'horizontal' | 'vertical' | 'both';
  velocityThreshold?: number;
}

export interface ToastViewportOffset {
  top?: number;
  bottom?: number;
  left?: number;
  right?: number;
}

export interface ToastQueueOptions {
  /** Maximum number of visible toasts per position */
  maxVisible: number;
  /** How toasts stack when multiple are shown */
  stackDirection: ToastStackDirection;
  /** Space between stacked toasts */
  spacing: number;
  /** Queue processing priority */
  priority: ToastQueuePriority;
  /** Whether to allow duplicate toasts */
  allowDuplicates: boolean;
}
```

## Examples

### Basics

Call `toast.success` with a `title` and `message` to show a standard confirmation toast.

```tsx
import { Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  return (
    <Button
      onPress={() =>
        toast.success({
          title: 'Success!',
          message: 'The operation finished without issues.',
        })
      }
    >
      Show success toast
    </Button>
  );
}
```

### Positions

Set the `position` option to anchor the toast stack to any corner or edge of the viewport.

```tsx
import { Button, Row, useToast } from '@plocks/ui';

const toastPositions = [
  'top-left',
  'top-center',
  'top-right',
  'bottom-left',
  'bottom-center',
  'bottom-right',
] as const;

export function Demo() {
  const toast = useToast();

  const showToastAtPosition = (position: typeof toastPositions[number]) => {
    toast.show({
      title: `Toast at ${position}`,
      message: `This toast appears at ${position} position.`,
      position,
    });
  };

  return (
    <Row gap="xs" wrap="wrap">
      {toastPositions.map((position) => (
        <Button key={position} size="sm" onPress={() => showToastAtPosition(position)}>
          {position}
        </Button>
      ))}
    </Row>
  );
}
```

### Visual Variants

Use the `variant` prop to control the toast surface: `filled` (solid color with auto-contrast text), `outline` (surface with a full colored border), or `light` (subtle surface with a colored left accent). Combine it with any `color` or severity helper.

```tsx
import { Block, Icon, Text, Toast } from '@plocks/ui';

const VARIANTS = ['light', 'filled', 'outline'] as const;

export function Demo() {
  return (
    <Block gap="md">
      {VARIANTS.map((variant) => (
        <Block key={variant} gap="xs">
          <Text variant="small" c="secondary">
            {variant}
          </Text>
          <Toast
            visible
            variant={variant}
            severity="success"
            title="Changes saved"
            icon={<Icon name="success" variant="filled" />}
            withCloseButton={false}
          >
            Your profile has been updated.
          </Toast>
        </Block>
      ))}
    </Block>
  );
}
```

### Size Tokens

The `size` prop supports the full seven-token scale (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`) and scales padding, title and body typography, the leading icon, action buttons, and the close button together. A number is read as the title font size and scales the rest proportionally. Set `defaultSize` on `ToastProvider` to change the default for every toast.

```tsx
import { Block, Icon, Text, Toast } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block gap="md">
      {SIZES.map((size) => (
        <Block key={size} gap="xs">
          <Text variant="small" c="secondary">
            {size}
          </Text>
          <Toast
            visible
            size={size}
            severity="info"
            title="Sync complete"
            icon={<Icon name="info" variant="filled" />}
            withCloseButton={false}
          >
            Everything is up to date.
          </Toast>
        </Block>
      ))}
    </Block>
  );
}
```

### Severity Helpers

Use `toast.success`, `toast.warning`, `toast.error`, and `toast.info` to render consistent styling and icons for each severity.

```tsx
import { Button, Row, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  const showSuccessToast = () => {
    toast.success({
      title: 'Success',
      message: 'The request completed correctly.',
    });
  };

  const showWarningToast = () => {
    toast.warning({
      title: 'Warning',
      message: 'Double-check the highlighted fields.',
    });
  };

  const showErrorToast = () => {
    toast.error({
      title: 'Error',
      message: 'Something went wrong.',
    });
  };

  const showInfoToast = () => {
    toast.info({
      title: 'Info',
      message: 'Here is some additional context.',
    });
  };

  return (
    <Row gap="xs" wrap="wrap">
      <Button onPress={showSuccessToast} variant="filled" color="success">
        Success
      </Button>
      <Button onPress={showWarningToast} variant="filled" color="warning">
        Warning
      </Button>
      <Button onPress={showErrorToast} variant="filled" color="error">
        Error
      </Button>
      <Button onPress={showInfoToast} variant="outline">
        Info
      </Button>
    </Row>
  );
}
```

### Interactive Features

Add `actions`, toggle `persistent`, or shorten `autoHide` to tailor toast interactions for acknowledgements, warnings, and ephemeral notices.

```tsx
import { Block, Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  const showActionToast = () => {
    toast.show({
      title: 'File uploaded',
      message: 'Your file has been uploaded successfully.',
      actions: [
        {
          label: 'Undo',
          onPress: () => toast.info('Upload reverted'),
        },
      ],
    });
  };

  const showPersistentToast = () => {
    toast.show({
      title: 'Important notice',
      message: 'This toast stays visible until dismissed.',
      persistent: true,
    });
  };

  const showTimedToast = () => {
    toast.show({
      title: 'Quick message',
      message: 'This one hides after two seconds.',
      autoHide: 2000,
    });
  };

  return (
    <Block>
      <Button onPress={showActionToast}>Toast with action</Button>
      <Button variant="outline" onPress={showPersistentToast}>
        Persistent toast
      </Button>
      <Button variant="outline" onPress={showTimedToast}>
        Quick toast (2s)
      </Button>
    </Block>
  );
}
```

### Stacking

Toasts at the same position form a stack. The newest one always takes the slot against the anchored edge and the rest move out of its way; when one is dismissed, the toasts behind it slide into the gap while it fades. Hovering — or tabbing into — any toast pauses the countdown on the whole stack, and resumes it with the time that was left. `limit` caps how many are on screen at once, retiring the oldest with its normal exit rather than deleting it.

```tsx
import { useRef } from 'react';

import { Block, Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();
  const counter = useRef(0);

  const push = () => {
    counter.current += 1;
    const n = counter.current;
    toast.show({
      title: `Message ${n}`,
      message: 'Dismiss one from the middle to watch the stack close the gap.',
      severity: (['info', 'success', 'warning', 'error'] as const)[n % 4],
      autoHide: 6000,
    });
  };

  const pushBurst = () => {
    toast.batch(
      Array.from({ length: 5 }, (_, index) => ({
        title: `Burst ${index + 1}`,
        message: 'Five at once — the limit retires the oldest.',
        severity: 'info' as const,
      }))
    );
  };

  return (
    <Block>
      <Button onPress={push}>Add a toast</Button>
      <Button variant="outline" onPress={pushBurst}>
        Add five at once
      </Button>
    </Block>
  );
}
```

### Enhanced Features

Combine swipe gestures, custom `animationConfig`, batch helpers, and `toast.promise` to coordinate rich toast experiences.

```tsx
import { Block, Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  const showSwipeableToast = () => {
    toast.info({
      title: 'Swipe me!',
      message: 'Drag in any direction to dismiss this toast.',
      swipeConfig: { direction: 'both', threshold: 150 },
    });
  };

  const showAnimatedToast = () => {
    toast.success({
      title: 'Spring motion',
      message: 'Bounce animation with custom spring physics.',
      animationConfig: {
        type: 'bounce',
        springConfig: { damping: 10, stiffness: 100 },
      },
    });
  };

  const showBatchToasts = () => {
    toast.batch([
      { title: 'Batch 1', message: 'First toast in batch', severity: 'info' },
      { title: 'Batch 2', message: 'Second toast in batch', severity: 'success' },
      { title: 'Batch 3', message: 'Third toast in batch', severity: 'warning' },
    ]);
  };

  const showPromiseToast = () => {
    toast.promise(new Promise((resolve) => setTimeout(resolve, 2000)), {
      pending: 'Loading data…',
      success: 'Data loaded',
      error: 'Could not load data',
    });
  };

  return (
    <Block>
      <Button onPress={showSwipeableToast}>Swipe to dismiss</Button>
      <Button variant="outline" onPress={showAnimatedToast}>
        Bounce animation
      </Button>
      <Button variant="outline" onPress={showBatchToasts}>
        Show batch toasts
      </Button>
      <Button variant="outline" onPress={showPromiseToast}>
        Promise integration
      </Button>
    </Block>
  );
}
```

### Text customization

`titleProps` and `bodyProps` accept any `<Text>` props (`ff`, `fw`, `size`, `c`, `style`…) and apply them to the toast title and body slots. Useful for matching toast typography to your brand.

```tsx
import { Button, useToast } from '@plocks/ui';

export function Demo() {
  const toast = useToast();

  return (
    <Button
      onPress={() =>
        toast.show({
          title: 'Bold uppercase title',
          message: 'Title rendered with monospace + tracking.',
          severity: 'success',
          titleProps: {
            ff: 'monospace',
            fw: '700',
            tt: 'uppercase',
            lts: 1,
            size: 'sm',
          },
          bodyProps: { size: 'sm' },
        })
      }
    >
      Show custom toast
    </Button>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Toggle.md -->

# Toggle

Toggle provides an intuitive way to select between multiple options. It supports both single and multi-selection modes with various visual styles and orientations for different use cases.

## Metadata

- Import: `import { Toggle } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Toggle
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Toggle

## Props

- `value` (required): ToggleValue — Value for this toggle button
- `selected`: boolean — Whether this button is selected (pressed). Standalone buttons are controlled by it; inside a ToggleGroup the group's value decides.
- `onPress`: (value: ToggleValue) => void — Callback when button is pressed (standalone buttons)
- `disabled`: boolean — Whether the button is disabled
- `children` (required): React.ReactNode — Button content
- `size`: SizeValue — Size of the toggle button
- `color`: ColorProp — Button color. A palette token, `'primary.6'` shade syntax, or any CSS color.
- `variant`: 'solid' | 'ghost' — Visual style variant
- `accessibilityLabel`: string — Accessible name; required when the content isn't text (an icon-only toggle).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), `radius`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { ToggleButton, ToggleGroup, ToggleBar } from '@plocks/ui';`

### ToggleButton

- `value` (required): ToggleValue — Value for this toggle button
- `selected`: boolean — Whether this button is selected (pressed). Standalone buttons are controlled by it; inside a ToggleGroup the group's value decides.
- `onPress`: (value: ToggleValue) => void — Callback when button is pressed (standalone buttons)
- `disabled`: boolean — Whether the button is disabled
- `children` (required): React.ReactNode — Button content
- `size`: SizeValue — Size of the toggle button
- `color`: ColorProp — Button color. A palette token, `'primary.6'` shade syntax, or any CSS color.
- `variant`: 'solid' | 'ghost' — Visual style variant
- `accessibilityLabel`: string — Accessible name; required when the content isn't text (an icon-only toggle).
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), `radius`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

### ToggleGroup

- `value`: ToggleGroupValue — Current selected value(s) (controlled)
- `defaultValue`: ToggleGroupValue — Initial value(s) for uncontrolled usage
- `onChange`: (value: ToggleGroupValue) => void — Called when selection changes: the pressed value (or `[]` when it was deselected) in exclusive mode, the array of selected values otherwise.
- `exclusive`: boolean — Whether only one option can be selected at a time (a radio group)
- `disabled`: boolean — Whether the group is disabled
- `size`: SizeValue — Size of all toggle buttons
- `color`: ColorProp — Color for all buttons. A palette token, `'primary.6'` shade syntax, or any CSS color.
- `variant`: 'solid' | 'ghost' — Visual style variant for all buttons
- `orientation`: 'horizontal' | 'vertical' — Orientation of the toggle group (also the arrow keys that move focus)
- `required`: boolean — Whether selection is required (at least one must be selected)
- `accessibilityLabel`: string — Accessible name of the group
- `children` (required): React.ReactNode — Toggle buttons
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), `radius`, visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

### ToggleBar

- `value`: (string | number)[] — Selected values (controlled)
- `defaultValue`: (string | number)[] — Initial selected values (uncontrolled)
- `onChange`: (vals: (string | number)[]) => void — Called with updated values
- `options` (required): ToggleBarOption[] — Options to render
- `multiple`: boolean — Allow multiple selection (checkboxes). If false acts like a radio group.
- `required`: boolean — Require at least one selection
- `size`: SizeValue — Overall size passed to chips
- `chipVariant`: 'filled' | 'outline' | 'light' — Default chip variant when not selected
- `selectedVariant`: 'filled' | 'outline' | 'light' — Variant to use when selected (defaults to 'filled')
- `gap`: number — Gap between chips (px)
- `accessibilityLabel`: string — Accessible name of the group
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type ToggleValue = string | number;

export type ToggleGroupValue = ToggleValue | ToggleValue[];

export interface ToggleBarOption {
  /** Display label for the option */
  label: string;
  /** Value for the option */
  value: string | number;
  /** Optional leading content */
  startSection?: React.ReactNode;
  /** Optional trailing content */
  endSection?: React.ReactNode;
  /** Color for the chip when selected */
  color?: ColorProp;
  /** Override the unselected chip variant */
  chipVariant?: 'filled' | 'outline' | 'light';
  /** Disable this option */
  disabled?: boolean;
}
```

## Examples

### Basics

Render a simple `ToggleGroup` and listen for `onChange` to track the active value.

```tsx
import { useState } from 'react';

import { Block, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  const [alignment, setAlignment] = useState('center');

  const handleChange = (nextValue: string | number | (string | number)[]) => {
    if (typeof nextValue === 'string' || typeof nextValue === 'number') {
      setAlignment(String(nextValue));
    }
  };

  return (
    <Block>
      <ToggleGroup value={alignment} exclusive onChange={handleChange}>
        <ToggleButton value="left">Left</ToggleButton>
        <ToggleButton value="center">Center</ToggleButton>
        <ToggleButton value="right">Right</ToggleButton>
      </ToggleGroup>
      <Text size="xs" c="secondary">
        Selected alignment: {alignment}
      </Text>
    </Block>
  );
}
```

### Exclusive Mode

Enable the `exclusive` prop so the group behaves like radio buttons with a single active value.

```tsx
import { ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  return (
    <ToggleGroup defaultValue="center" exclusive>
      <ToggleButton value="left">Left</ToggleButton>
      <ToggleButton value="center">Center</ToggleButton>
      <ToggleButton value="right">Right</ToggleButton>
      <ToggleButton value="justify">Justify</ToggleButton>
    </ToggleGroup>
  );
}
```

### Variants

Compare solid and ghost toggle groups with the same selected value.

```tsx
import { Column, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

const variants = ['solid', 'ghost'] as const;

export function Demo() {
  return (
    <Column gap="lg">
      {variants.map(variant => (
        <Column key={variant} gap="xs">
          <Text fw="semibold">{variant}</Text>
          <ToggleGroup variant={variant} defaultValue="center" exclusive accessibilityLabel={`${variant} alignment`}>
            <ToggleButton value="left">Left</ToggleButton>
            <ToggleButton value="center">Center</ToggleButton>
            <ToggleButton value="right">Right</ToggleButton>
          </ToggleGroup>
        </Column>
      ))}
    </Column>
  );
}
```

### Multiple Values

Read the array returned by `onChange` to keep several toggles activated together.

```tsx
import { useState } from 'react';

import { Block, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  const [formats, setFormats] = useState(['bold']);

  const handleChange = (value: string | number | (string | number)[]) => {
    if (Array.isArray(value)) {
      setFormats(value.map(String));
    }
  };

  return (
    <Block>
      <ToggleGroup value={formats} onChange={handleChange}>
        <ToggleButton value="bold">Bold</ToggleButton>
        <ToggleButton value="italic">Italic</ToggleButton>
        <ToggleButton value="underline">Underline</ToggleButton>
        <ToggleButton value="color">Color</ToggleButton>
      </ToggleGroup>

      <Text size="xs" c="secondary">
        Active formatting: {formats.length > 0 ? formats.join(', ') : 'none'}
      </Text>
    </Block>
  );
}
```

### Orientation

Use the `orientation` prop to switch between horizontal rows (the default) and vertical stacks of toggle buttons.

```tsx
import { Block, Row, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="lg" align="flex-start" wrap="wrap">
      <Block>
        <Text variant="small" c="secondary">Horizontal</Text>
        <ToggleGroup defaultValue="list" exclusive orientation="horizontal">
          <ToggleButton value="list">List</ToggleButton>
          <ToggleButton value="grid">Grid</ToggleButton>
          <ToggleButton value="card">Card</ToggleButton>
        </ToggleGroup>
      </Block>

      <Block>
        <Text variant="small" c="secondary">Vertical</Text>
        <ToggleGroup defaultValue="list" exclusive orientation="vertical">
          <ToggleButton value="list">List</ToggleButton>
          <ToggleButton value="grid">Grid</ToggleButton>
          <ToggleButton value="card">Card</ToggleButton>
        </ToggleGroup>
      </Block>
    </Row>
  );
}
```

### Size Variants

Set the `size` prop (`xs` through `3xl`) to match the footprint of surrounding controls.

```tsx
import { Block, Text, ToggleButton, ToggleGroup } from '@plocks/ui';

const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;

export function Demo() {
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" c="secondary">{size}</Text>
          <ToggleGroup size={size}>
            <ToggleButton value="left">Left</ToggleButton>
            <ToggleButton value="center">Center</ToggleButton>
            <ToggleButton value="right">Right</ToggleButton>
          </ToggleGroup>
        </Block>
      ))}
    </Block>
  );
}
```

### Standalone Toggle

Drive a single toggle without a surrounding group by pairing its `selected` state with `onPress`.

```tsx
import { useState } from 'react';

import { ToggleButton } from '@plocks/ui';

export function Demo() {
  const [selected, setSelected] = useState(false);

  return (
    <ToggleButton
      value="favorite"
      selected={selected}
      onPress={() => setSelected((current) => !current)}
    >
      Mark favorite
    </ToggleButton>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Tooltip.md -->

# Tooltip

Tooltip provides contextual information without disrupting the user's workflow. It supports multiple trigger events, smart positioning, and accessibility features for an inclusive experience.

## Metadata

- Import: `import { Tooltip } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Tooltip
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Tooltip

## Props

- `label` (required): ReactNode — Tooltip label. Also becomes the trigger's accessible description.
- `position`: 'top' | 'bottom' | 'left' | 'right' = 'top' — Position of the tooltip (written for LTR; mirrored in RTL). @default 'top'
- `withArrow`: boolean = false — Whether to show an arrow
- `color`: ThemeColor = an inverted surface — Bubble color: a palette token (`'primary'`, `'red.6'`) or any CSS color. The label color is picked for contrast. @default an inverted surface
- `radius`: RadiusValue = 'md' — Border radius. @default 'md'
- `offset`: number = 8 — Offset from target
- `w`: number — Fixed bubble width in px (not the root's). Omit to size to content, capped by `maw`.
- `maw`: number = 280 — Largest width the bubble may grow to before the label wraps. Also clamped by the available viewport space.
- `lineClamp`: number — Clamp the label to N lines with an ellipsis. Unset = wrap freely.
- `opened`: boolean — Controlled open state.
- `defaultOpened`: boolean = false — Initial open state when uncontrolled. @default false
- `onOpen`: () => void — Called when the tooltip opens (uncontrolled or requested).
- `onClose`: () => void — Called when the tooltip closes or asks to close (Escape, pointer / focus leaving).
- `openDelay`: number = 0 — Open delay in ms
- `closeDelay`: number = 0 — Close delay in ms
- `events`: TooltipEvents — Events that show the tooltip. Focus is on by default so keyboard users see it.
- `disabled`: boolean = false — Never show the tooltip.
- `children` (required): ReactElement — Children element to attach tooltip to
- `labelProps`: Omit<TextProps, 'children'> — Override props applied to the label `<Text>` (style, weight, ff, size, color).
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface TooltipEvents {
  /** Show while the pointer rests on the trigger (web). @default true */
  hover?: boolean;
  /** Show while the trigger has keyboard focus. @default true */
  focus?: boolean;
  /** Toggle on press (touch); on web a press shows it. @default true */
  touch?: boolean;
}
```

## Examples

### Basics

Wrap a control in `Tooltip` to display concise helper text on hover, focus, or touch.

```tsx
import { Button, Tooltip } from '@plocks/ui';

export function Demo() {
  return (
    <Tooltip label="Invite teammates" withArrow>
      <Button size="sm" variant="outline">
        Invite teammates
      </Button>
    </Tooltip>
  );
}
```

### Trigger Modes

Configure the `events` prop to decide whether tooltips appear on hover, focus, or touch interactions.

```tsx
import { Button, Row, Tooltip } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Tooltip label="Default hover and focus behavior">
        <Button size="sm">Hover or focus</Button>
      </Tooltip>
      <Tooltip
        label="Only appears when the button receives focus"
        events={{ hover: false, focus: true, touch: false }}
      >
        <Button size="sm" variant="outline">
          Focus only
        </Button>
      </Tooltip>
      <Tooltip
        label="Shows on touch interactions"
        events={{ hover: false, focus: false, touch: true }}
      >
        <Button size="sm" variant="ghost">
          Touch only
        </Button>
      </Tooltip>
    </Row>
  );
}
```

### Positions

Set `position` to top, bottom, left, or right to anchor the tooltip relative to its trigger.

```tsx
import { Button, Row, Tooltip } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" justify="center" wrap="wrap">
      <Tooltip label="Appears above the target" position="top" withArrow>
        <Button size="sm" variant="outline">
          Top
        </Button>
      </Tooltip>
      <Tooltip label="Appears below the target" position="bottom" withArrow>
        <Button size="sm" variant="outline">
          Bottom
        </Button>
      </Tooltip>
      <Tooltip label="Anchors to the left" position="left" withArrow>
        <Button size="sm" variant="outline">
          Left
        </Button>
      </Tooltip>
      <Tooltip label="Anchors to the right" position="right" withArrow>
        <Button size="sm" variant="outline">
          Right
        </Button>
      </Tooltip>
    </Row>
  );
}
```

### Delays and Content

Tune `openDelay`/`closeDelay` to reduce flicker. Long labels wrap on their own — use `maw` to move the wrap point, `w` for a fixed bubble, or `lineClamp` to truncate on purpose.

```tsx
import { Button, Row, Tooltip } from '@plocks/ui';

export function Demo() {
  return (
    <Row gap="md" wrap="wrap">
      <Tooltip label="Opens after 400ms" openDelay={400} closeDelay={200}>
        <Button size="sm" variant="outline">
          Delayed tooltip
        </Button>
      </Tooltip>
      <Tooltip
        label="This tooltip wraps across multiple lines so you can surface longer instructions without truncation."
        maw={220}
        withArrow
      >
        <Button size="sm">
          Wrapped tooltip
        </Button>
      </Tooltip>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Tree.md -->

# Tree

Tree displays hierarchical data with expandable branches.

## Metadata

- Import: `import { Tree } from '@plocks/ui';`
- Docs: https://plocks.dev/components/Tree
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Tree

## Props

- `data` (required): TreeNode<T>[]
- `onNavigate`: (node: TreeNode<T>) => void — Called when a leaf is activated, or when any node carrying `href` is pressed
- `onNodePress`: ( node: TreeNode<T>, context: { isBranch: boolean; event?: TreePressEvent } ) => boolean | void — Called when a node row is pressed. Return false to prevent default handling (selection, expand).
- `collapsible`: boolean — Allow collapsing/expanding
- `disclosure`: 'always' | 'nested' | 'none' = 'always' — Where the expand/collapse caret is drawn, and whether every row reserves its column. - `'always'` — a caret on each branch, and the column held open on rows without one so labels line up whatever the row is. - `'nested'` — top-level branches go bare and no row reserves the column, so the outermost rows read as headings (the theme's `sectionLabel` text role) and the whole tree sits flush against its edge. Branches still open when the row itself is pressed. - `'none'` — no caret at any depth, and no column.
- `size`: ComponentSizeValue — Row density. Drives height, padding, indent and icon size (resolved from the theme's control sizes, one step down — rows are compact controls). A number is read as the label font size and the rest of the row scales with it.
- `indent`: number — Indent size in px for each depth level. Defaults to the `size` scale.
- `showGuides`: boolean — Draw vertical guide lines connecting a branch to its descendants
- `accordion`: boolean — Keep only one branch open per parent level
- `expandAll`: boolean — Expand every branch. Reactive: flipping it back restores the initial expansion.
- `renderLabel`: ( node: TreeNode<T>, depth: number, isOpen: boolean, state: TreeNodeState ) => React.ReactNode — Custom render for label
- `renderEndSection`: (node: TreeNode<T>, state: TreeNodeState) => React.ReactNode — Trailing slot rendered at the end of a row (actions, counts, badges)
- `rowStyle`: StyleProp<ViewStyle> — Style applied to every row container
- `selectionMode`: 'none' | 'single' | 'multiple' — Selection mode
- `selectedIds`: string[] — Controlled selected ids
- `defaultSelectedIds`: string[] — Uncontrolled default selected ids
- `onSelectionChange`: (ids: string[], node: TreeNode<T>) => void — Selection change callback
- `onActiveNodeChange`: (node: TreeNode<T> | null, ids: string[]) => void — Fired after selection changes with the node considered primary (first in selection)
- `checkboxes`: boolean — Enable checkboxes
- `checkedIds`: string[] — Controlled checked ids
- `defaultCheckedIds`: string[] — Uncontrolled default checked ids
- `onCheckedChange`: (ids: string[], node: TreeNode<T>) => void — Checked change callback
- `cascadeCheck`: boolean — Cascade checking to descendants
- `expandOnClick`: boolean — Expand branches also when pressing label area (not just chevron)
- `expandedIds`: string[] — Controlled external expansion state
- `defaultExpandedIds`: string[] — Uncontrolled initial expansion, overriding each node's `startOpen`
- `onExpandedIdsChange`: (ids: string[]) => void — Fired with the full expanded set whenever expansion changes
- `onToggle`: (node: TreeNode<T>, expanded: boolean) => void — Expansion change callback for a single node
- `loadChildren`: (node: TreeNode<T>) => Promise<TreeNode<T>[]> — Fetch a branch's children on first expand. Node needs `hasChildren` to show a caret.
- `filterQuery`: string — Filter query to highlight / hide unmatched nodes
- `hideFiltered`: boolean — If true, nodes that don't match filter are hidden; otherwise all shown with highlight
- `autoExpandOnFilter`: boolean — Open the branches leading to filter matches while a query is active
- `noResultsFallback`: React.ReactNode — Content when no results after filtering
- `highlight`: (label: string, query: string) => React.ReactNode — Custom highlight function for labels (return ReactNode)
- `striped`: boolean — Apply alternating background stripes to rows
- `useAnimations`: boolean — Animate branch expansion/collapse using the Collapse component (instant under reduced motion)
- `virtualized`: boolean — Render rows through a virtualized list, which fills the tree's height (`h`, 320 by default). Disables expand/collapse animation.
- `keyboardNavigation`: boolean — Arrow-key navigation, type-ahead and roving focus (web). Defaults to on. The tree is then a single tab stop that tracks the focused row with `aria-activedescendant`, per the WAI-ARIA tree pattern.
- `activeId`: string — Id of the node representing the current location — the navigation counterpart to selection. It paints the row as active, opens the branches above it, and scrolls it into view, without consuming `selectedIds`. On web the row gets `aria-current="page"`.
- `activeHref`: string — `activeId`, resolved by matching a node's `href` instead. Hand it a pathname and the tree finds the row. Ignored when `activeId` is set.
- `expandToActive`: boolean = true — Open the branches leading to the active node whenever it changes. Re-opening is keyed on the ancestor set, so a branch the reader collapsed stays collapsed while they move between its children.
- `scrollActiveIntoView`: boolean = true — Scroll the active row into view once it becomes visible (web only).
- `persistKey`: string — Remember which branches are open across reloads, under this key (`localStorage`, web only). Ignored while expansion is controlled through `expandedIds` — the parent owns the state in that mode.
- `selectionColor`: string — Base color for selection / focus affordances. Defaults to the primary palette.
- `accessibilityLabel`: string — Accessible name for the tree container
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Related hooks

- `useTreeState(options: UseTreeStateOptions): TreeStateResult` — Returns the headless state behind `Tree` — expansion (controlled or not), lazy-loaded children, filter matches and the flattened visible `rows` — for building a custom tree or outline view over the same `TreeNode` data.

## Types

```ts
export interface TreeNode<T = unknown> {
  id: string;
  label: string;
  children?: TreeNode<T>[];
  /**
   * Marks a node as a branch before its children exist — the disclosure control
   * renders, and pressing it calls `loadChildren`. Ignored once `children` is set.
   */
  hasChildren?: boolean;
  /**
   * Navigation target. On web the row renders as a real `<a href>`, so
   * cmd/middle-click, "copy link address" and crawlers all work; plain clicks
   * still go through `onNavigate`. Native has no anchor and falls back to a
   * pressable with the `link` role.
   */
  href?: string;
  startOpen?: boolean;
  icon?: React.ReactNode; // optional leading icon, branches included
  disabled?: boolean;
  selectable?: boolean; // override global selection mode
  data?: T; // arbitrary extra data
}

export type TreePressEvent = GestureResponderEvent | WebKeyboardEvent;

export interface TreeNodeState {
  selected: boolean;
  /** Row is the tree's `activeId` / `activeHref` target — "you are here". */
  active: boolean;
  checked: boolean;
  indeterminate: boolean;
  expanded: boolean;
  disabled: boolean;
  /** Row holds the keyboard focus ring. */
  focused: boolean;
  /** `loadChildren` is in flight for this node. */
  loading: boolean;
  /** Node's own label matched the active `filterQuery`. */
  matched: boolean;
  depth: number;
}
```

## Examples

### Basics

Render a hierarchical dataset with collapsing branches. Use `indent` to control how far each level is inset.

```tsx
import { Tree } from '@plocks/ui';

import { TREE_DATA } from './data';

export function Demo() {
  return <Tree data={TREE_DATA} collapsible indent={20} />;
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

/** A small file-manager hierarchy: folders deep enough to show nested expansion. */
export const TREE_DATA: TreeNode[] = [
  {
    id: 'documents',
    label: 'Documents',
    children: [
      {
        id: 'work',
        label: 'Work',
        children: [
          { id: 'presentation.pptx', label: 'Presentation.pptx' },
          { id: 'budget.xlsx', label: 'Budget.xlsx' },
          { id: 'report.docx', label: 'Report.docx' },
        ],
      },
      {
        id: 'personal',
        label: 'Personal',
        children: [
          { id: 'vacation-photos', label: 'Vacation Photos' },
          { id: 'recipes.txt', label: 'Recipes.txt' },
        ],
      },
    ],
  },
  {
    id: 'downloads',
    label: 'Downloads',
    children: [
      { id: 'installer.dmg', label: 'Installer.dmg' },
      { id: 'archive.zip', label: 'Archive.zip' },
    ],
  },
  {
    id: 'desktop',
    label: 'Desktop',
    children: [
      { id: 'screenshot.png', label: 'Screenshot.png' },
      { id: 'notes.txt', label: 'Notes.txt' },
    ],
  },
];
```

### Tree with Checkboxes

Enable `checkboxes` with `cascadeCheck` to keep parent and child nodes synchronized while tracking checked ids.

```tsx
import { useState } from 'react';

import { Tree } from '@plocks/ui';

import { TREE_DATA } from './data';

export function Demo() {
  const [checkedIds, setCheckedIds] = useState<string[]>(['react', 'css']);

  return (
    <Tree
      data={TREE_DATA}
      checkboxes
      cascadeCheck
      checkedIds={checkedIds}
      onCheckedChange={setCheckedIds}
      expandAll
    />
  );
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

/** Two-level technology groups, so cascading checks have parents to roll up into. */
export const TREE_DATA: TreeNode[] = [
  {
    id: 'frontend',
    label: 'Frontend Technologies',
    children: [
      {
        id: 'frameworks',
        label: 'Frameworks',
        children: [
          { id: 'react', label: 'React' },
          { id: 'vue', label: 'Vue.js' },
          { id: 'angular', label: 'Angular' },
        ],
      },
      {
        id: 'styling',
        label: 'Styling',
        children: [
          { id: 'css', label: 'CSS' },
          { id: 'sass', label: 'Sass' },
          { id: 'tailwind', label: 'Tailwind CSS' },
        ],
      },
    ],
  },
  {
    id: 'backend',
    label: 'Backend Technologies',
    children: [
      {
        id: 'languages',
        label: 'Languages',
        children: [
          { id: 'nodejs', label: 'Node.js' },
          { id: 'python', label: 'Python' },
          { id: 'go', label: 'Go' },
        ],
      },
      {
        id: 'databases',
        label: 'Databases',
        children: [
          { id: 'postgresql', label: 'PostgreSQL' },
          { id: 'mongodb', label: 'MongoDB' },
          { id: 'redis', label: 'Redis' },
        ],
      },
    ],
  },
];
```

### Tree Selection

Set `selectionMode` to `single` or `multiple` and drive `selectedIds` from state. In `multiple` mode, shift-click captures a range and Cmd/Ctrl-click toggles one row.

```tsx
import { useState } from 'react';

import { Block, Text, Tree } from '@plocks/ui';

import { TREE_DATA } from './data';

export function Demo() {
  const [selectedIds, setSelectedIds] = useState<string[]>([]);

  return (
    <Block fullWidth>
      <Tree
        data={TREE_DATA}
        selectionMode="multiple"
        selectedIds={selectedIds}
        onSelectionChange={setSelectedIds}
        expandAll
      />

      <Text size="xs" c="secondary">
        {selectedIds.length === 0
          ? 'Click a row, shift-click for a range, or Cmd/Ctrl-click to toggle.'
          : `${selectedIds.length} selected`}
      </Text>
    </Block>
  );
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

/** A catalogue tree with both nested and flat branches to select across. */
export const TREE_DATA: TreeNode[] = [
  {
    id: 'products',
    label: 'Products',
    children: [
      {
        id: 'electronics',
        label: 'Electronics',
        children: [
          { id: 'laptop', label: 'Laptops' },
          { id: 'phone', label: 'Smartphones' },
          { id: 'tablet', label: 'Tablets' },
        ],
      },
      {
        id: 'clothing',
        label: 'Clothing',
        children: [
          { id: 'shirts', label: 'Shirts' },
          { id: 'pants', label: 'Pants' },
          { id: 'shoes', label: 'Shoes' },
        ],
      },
    ],
  },
  {
    id: 'services',
    label: 'Services',
    children: [
      { id: 'support', label: 'Customer Support' },
      { id: 'consulting', label: 'Consulting' },
      { id: 'training', label: 'Training' },
    ],
  },
];
```

### Tree Filtering

Provide `filterQuery` with `hideFiltered` to search the tree. A `highlight` renderer and `noResultsFallback` are also available for custom match styling and empty states.

```tsx
import { useState } from 'react';

import { Block, Input, Tree } from '@plocks/ui';

import { TREE_DATA } from './data';

export function Demo() {
  const [filterQuery, setFilterQuery] = useState('');

  return (
    <Block fullWidth>
      <Input
        label="Search technologies"
        value={filterQuery}
        onChangeText={setFilterQuery}
        placeholder="Type to filter the tree"
      />

      <Tree
        data={TREE_DATA}
        filterQuery={filterQuery}
        hideFiltered
        expandAll={!!filterQuery}
      />
    </Block>
  );
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

/** Enough labels sharing substrings ("Java"/"JavaScript") to make filtering visible. */
export const TREE_DATA: TreeNode[] = [
  {
    id: 'programming',
    label: 'Programming Languages',
    children: [
      {
        id: 'frontend',
        label: 'Frontend',
        children: [
          { id: 'javascript', label: 'JavaScript' },
          { id: 'typescript', label: 'TypeScript' },
          { id: 'html', label: 'HTML' },
          { id: 'css', label: 'CSS' },
        ],
      },
      {
        id: 'backend',
        label: 'Backend',
        children: [
          { id: 'python', label: 'Python' },
          { id: 'java', label: 'Java' },
          { id: 'csharp', label: 'C#' },
          { id: 'go', label: 'Go' },
        ],
      },
      {
        id: 'mobile',
        label: 'Mobile',
        children: [
          { id: 'swift', label: 'Swift' },
          { id: 'kotlin', label: 'Kotlin' },
          { id: 'dart', label: 'Dart' },
        ],
      },
    ],
  },
  {
    id: 'databases',
    label: 'Databases',
    children: [
      { id: 'mysql', label: 'MySQL' },
      { id: 'postgresql', label: 'PostgreSQL' },
      { id: 'mongodb', label: 'MongoDB' },
      { id: 'redis', label: 'Redis' },
    ],
  },
];
```

### Lazy Loading

Mark a node with `hasChildren` and supply `loadChildren` to fetch a branch the first time it opens. The disclosure control shows a loader while the promise is in flight.

```tsx
import { Tree, type TreeNode } from '@plocks/ui';

import { TREE_DATA, fetchInstances, fetchVolumes } from './data';

export function Demo() {
  const loadChildren = (node: TreeNode) =>
    node.id.includes('-web') ? fetchVolumes(node.id) : fetchInstances(node.id);

  return <Tree data={TREE_DATA} loadChildren={loadChildren} selectionMode="single" showGuides />;
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

/** Roots that advertise children with `hasChildren` but ship none — `loadChildren` fills them in. */
export const TREE_DATA: TreeNode[] = [
  { id: 'us-east-1', label: 'us-east-1', hasChildren: true },
  { id: 'eu-west-1', label: 'eu-west-1', hasChildren: true },
  { id: 'ap-south-1', label: 'ap-south-1', hasChildren: true },
];

/** Stands in for the API call a real app would make. */
export const fetchInstances = (regionId: string): Promise<TreeNode[]> =>
  new Promise((resolve) => {
    setTimeout(() => {
      resolve([
        { id: `${regionId}-web`, label: 'web-server', hasChildren: true },
        { id: `${regionId}-db`, label: 'database' },
        { id: `${regionId}-cache`, label: 'cache' },
      ]);
    }, 700);
  });

export const fetchVolumes = (instanceId: string): Promise<TreeNode[]> =>
  new Promise((resolve) => {
    setTimeout(() => {
      resolve([
        { id: `${instanceId}-vol-1`, label: 'volume-1 (100 GiB)' },
        { id: `${instanceId}-vol-2`, label: 'volume-2 (500 GiB)' },
      ]);
    }, 700);
  });
```

### Custom Tree Rendering

Pass `renderLabel` to build custom rows with icons and badges while keeping the tree interactions intact.

```tsx
import { Badge, Icon, Row, Text, Tree, type TreeNode } from '@plocks/ui';

import { STATUS_BADGES, TREE_DATA, TYPE_ICONS, type CustomNodeData } from './data';

export function Demo() {
  const renderCustomLabel = (node: TreeNode) => {
    const data = node.data as CustomNodeData;
    const status = STATUS_BADGES[data.status];

    return (
      <Row gap="sm" align="center" style={{ flex: 1 }}>
        <Icon name={TYPE_ICONS[data.type]} size="sm" />
        <Text size="sm" style={{ flex: 1 }}>
          {node.label}
        </Text>
        <Badge variant="outline" c={status.color}>
          {status.label}
        </Badge>
      </Row>
    );
  };

  return <Tree data={TREE_DATA} renderLabel={renderCustomLabel} selectionMode="single" expandAll />;
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

/** Payload each node carries on `node.data` for the custom label renderer. */
export interface CustomNodeData {
  status: 'active' | 'inactive' | 'pending';
  count?: number;
  type: 'folder' | 'file' | 'project';
}

/** A workspace whose nodes cover every status and an empty branch. */
export const TREE_DATA: TreeNode[] = [
  {
    id: 'workspace',
    label: 'Workspace',
    data: { status: 'active', type: 'folder', count: 3 },
    children: [
      {
        id: 'project-a',
        label: 'Project Alpha',
        data: { status: 'active', type: 'project', count: 12 },
        children: [
          {
            id: 'file-1',
            label: 'main.ts',
            data: { status: 'active', type: 'file' }
          },
          {
            id: 'file-2',
            label: 'config.json',
            data: { status: 'pending', type: 'file' }
          },
          {
            id: 'file-3',
            label: 'README.md',
            data: { status: 'active', type: 'file' }
          },
        ],
      },
      {
        id: 'project-b',
        label: 'Project Beta',
        data: { status: 'pending', type: 'project', count: 5 },
        children: [
          {
            id: 'file-4',
            label: 'app.tsx',
            data: { status: 'inactive', type: 'file' }
          },
          {
            id: 'file-5',
            label: 'styles.css',
            data: { status: 'active', type: 'file' }
          },
        ],
      },
      {
        id: 'project-c',
        label: 'Project Gamma',
        data: { status: 'inactive', type: 'project', count: 0 },
        children: [],
      },
    ],
  },
];

/** Icon shown ahead of a node's label, keyed by node type. */
export const TYPE_ICONS: Record<CustomNodeData['type'], string> = {
  folder: 'folder',
  project: 'sheild',
  file: 'file',
};

/** Badge copy and colour for each status, also driving the legend above the tree. */
export const STATUS_BADGES: Record<CustomNodeData['status'], { label: string; color: string }> = {
  active: { label: 'Active', color: 'success' },
  pending: { label: 'Pending', color: 'warning' },
  inactive: { label: 'Inactive', color: 'gray' },
};
```

### Virtualized Tree

Pass `virtualized` with an `h` to render only the rows in view. Expansion animation is skipped in this mode; filtering, selection and keyboard navigation all still operate on the full row list.

```tsx
import { Tree } from '@plocks/ui';

import { TREE_DATA } from './data';

export function Demo() {
  return <Tree data={TREE_DATA} virtualized h={320} size="sm" striped showGuides />;
}
```

`data.ts`

```ts
import type { TreeNode } from '@plocks/ui';

const DEPARTMENTS = ['Engineering', 'Design', 'Sales', 'Support', 'Finance', 'Legal'];

/** ~1,500 rows: large enough that rendering every one of them would be felt. */
export const TREE_DATA: TreeNode[] = DEPARTMENTS.map((department, d) => ({
  id: `dept-${d}`,
  label: department,
  startOpen: d === 0,
  children: Array.from({ length: 15 }, (_, t) => ({
    id: `dept-${d}-team-${t}`,
    label: `${department} team ${t + 1}`,
    children: Array.from({ length: 16 }, (_, m) => ({
      id: `dept-${d}-team-${t}-member-${m}`,
      label: `Member ${t + 1}.${m + 1}`,
    })),
  })),
}));
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/TreeSelect.md -->

# TreeSelect

Branches open within the dropdown; in single and multiple mode, leaves are selectable.

## Metadata

- Import: `import { TreeSelect } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/TreeSelect
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/TreeSelect

## Props

- `mode`: 'single' | 'multiple' | 'checkbox' = 'single'
- `value`: string | null | string[]
- `defaultValue`: string | null | string[]
- `onChange`: ((value: string | null) => void) | ((value: string[]) => void)
- `data` (required): TreeNode[]
- `placeholder`: string = 'Select…'
- `expandOnClick`: boolean = true
- `checkStrictly`: boolean = false
- `checkedStrategy`: 'child' | 'all' | 'parent' = 'child'
- `onRemove`: (value: string) => void
- `maxDisplayedValues`: number = Infinity
- `maxDisplayedValuesContent`: React.ReactNode
- `maxValues`: number
- `searchable`: boolean = false
- `searchValue`: string
- `defaultSearchValue`: string
- `onSearchChange`: (query: string) => void
- `filter`: (node: TreeNode, query: string) => boolean
- `clearSearchOnChange`: boolean = true
- `nothingFoundMessage`: React.ReactNode = 'Nothing found'
- `clearable`: boolean = false
- `allowDeselect`: boolean = true
- `withLines`: boolean = true
- `renderNode`: (node: TreeNode, state: TreeNodeState) => React.ReactNode
- `maxDropdownHeight`: number = 260
- `expandedValues`: string[]
- `defaultExpandedValues`: string[]
- `defaultExpandAll`: boolean
- `onExpandedChange`: (ids: string[]) => void
- `dropdownOpened`: boolean
- `defaultDropdownOpened`: boolean
- `onDropdownOpen`: () => void
- `onDropdownClose`: () => void
- `position`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom-start'
- `dropdownWidth`: number | 'target' = 'target'
- `offset`: number
- `startSection`: React.ReactNode
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Search and choose a leaf from a nested tree.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} searchable />
    </Block>
  );
}
```

### Multiple Selection

Choose several leaves from the same tree.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} mode="multiple" defaultValue={['apple']} />
    </Block>
  );
}
```

### Checkbox Selection

Checkbox mode can check several leaves.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} mode="checkbox" />
    </Block>
  );
}
```

### Clearable

`clearable` adds a button to clear a selected value.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} defaultValue="apple" clearable />
    </Block>
  );
}
```

### Expanded Branches

`defaultExpandAll` opens all branches initially.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} defaultExpandAll />
    </Block>
  );
}
```

### Connecting Lines

`withLines` draws branch guides in the tree.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} withLines />
    </Block>
  );
}
```

### Strict Checking

`checkStrictly` stops cascading checkbox changes.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} mode="checkbox" checkStrictly />
    </Block>
  );
}
```

### Maximum Values

`maxValues` caps a multiple selection.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} mode="multiple" maxValues={2} />
    </Block>
  );
}
```

### Custom Node

`renderNode` changes the content of each tree row.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} renderNode={(node) => `${node.label} •`} />
    </Block>
  );
}
```

### Nothing Found

A fallback message appears when search has no matching nodes.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} searchable nothingFoundMessage="No matching food" />
    </Block>
  );
}
```

### Dropdown Position

`position` changes where the tree opens.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  { id: 'vegetable', label: 'Vegetable', children: [{ id: 'carrot', label: 'Carrot' }] },
];
export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} position="top-start" dropdownWidth={320} />
    </Block>
  );
}
```

### Searchable

`searchable` filters nested nodes by their labels.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
  {
    id: 'vegetable',
    label: 'Vegetable',
    children: [
      { id: 'carrot', label: 'Carrot' },
      { id: 'lettuce', label: 'Lettuce' },
    ],
  },
];

export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} searchable />
    </Block>
  );
}
```

### Controlled Value

`value` and `onChange` keep selection in parent state.

```tsx
import { useState } from 'react';
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
];

export function Demo() {
  const [value, setValue] = useState<string | null>('apple');
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} value={value} onChange={setValue} clearable />
    </Block>
  );
}
```

### Dropdown Offset

`offset` sets the gap between the field and its dropdown.

```tsx
import { Block, TreeSelect } from '@plocks/ui';

const data = [
  {
    id: 'fruit',
    label: 'Fruit',
    children: [
      { id: 'apple', label: 'Apple' },
      { id: 'banana', label: 'Banana' },
    ],
  },
];

export function Demo() {
  return (
    <Block fullWidth>
      <TreeSelect label="Food" data={data} offset={16} />
    </Block>
  );
}
```

### Field States

`readOnly`, `disabled`, and `error` use the shared field behavior.

```tsx
import { Block, Flex, TreeSelect } from '@plocks/ui';

const data = [{ id: 'fruit', label: 'Fruit', children: [{ id: 'apple', label: 'Apple' }] }];

export function Demo() {
  return (
    <Block fullWidth>
      <Flex direction="column" gap="md">
        <TreeSelect label="Read only" data={data} defaultValue="apple" readOnly />
        <TreeSelect label="Disabled" data={data} disabled />
        <TreeSelect label="Required" data={data} required error="Choose an item" />
      </Flex>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Video.md -->

# Video

Video plays video sources with playback controls and a seekable timeline.

## Metadata

- Import: `import { Video } from '@plocks/media';`
- Install: `npm install @plocks/media` — a separate package from `@plocks/ui`
- Docs: https://plocks.dev/components/Video
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/media/src/components/Video

## Props

- `source` (required): VideoSource — Video source configuration
- `aspectRatio`: number = 16 / 9 — Width / height ratio used when `w` or `h` is missing: with only one of them the other follows this ratio; with neither the player fills the width. @default 16 / 9
- `poster`: string
- `autoPlay`: boolean = false — Playback configuration
- `loop`: boolean = false
- `muted`: boolean = false
- `volume`: number = 1
- `playbackRate`: 0.25 | 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2 = 1
- `quality`: 'auto' | 'small' | 'medium' | 'large' | 'hd720' | 'hd1080' | 'highres' = 'auto'
- `controls`: boolean | VideoControls = true — Controls configuration
- `timeline`: VideoTimelineEvent[] = EMPTY_TIMELINE — Timeline events for synchronization
- `youtubeOptions`: { start?: number; end?: number; modestbranding?: boolean; rel?: boolean; iv_load_policy?: number; } — YouTube specific options
- `onPlay`: (state: VideoState) => void — Event handlers
- `onPause`: (state: VideoState) => void
- `onSeek`: (time: number, state: VideoState) => void
- `onTimeUpdate`: (state: VideoState) => void
- `onDurationChange`: (duration: number) => void
- `onVolumeChange`: (volume: number) => void
- `onPlaybackRateChange`: (rate: VideoPlaybackRate) => void
- `onQualityChange`: (quality: VideoQuality) => void — YouTube reported a quality change.
- `onFullscreenChange`: (fullscreen: boolean) => void — Entered / left fullscreen (web).
- `onError`: (error: string) => void
- `onLoad`: (state: VideoState) => void
- `onLoadStart`: () => void
- `onBuffer`: (buffering: boolean) => void
- `onTimelineEvent`: (event: VideoTimelineEvent, state: VideoState) => void
- `videoStyle`: StyleProp<ImageStyle> — Styling
- `controlsStyle`: StyleProp<ViewStyle>
- `accessibilityLabel`: string — Accessible name of the video (default "Video player")
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type VideoSource = {
  /** Video URL (mp4, webm, etc.) */
  url?: string;
  /** YouTube video ID or URL */
  youtube?: string;
  /** File buffer (for React Native) */
  buffer?: ArrayBuffer | string;
  /** MIME type for buffer */
  type?: string;
};

export interface VideoControls {
  /** Show/hide play button */
  play?: boolean;
  /** Show/hide pause button */
  pause?: boolean;
  /** Show/hide progress bar */
  progress?: boolean;
  /** Show/hide time display */
  time?: boolean;
  /** Show/hide volume control */
  volume?: boolean;
  /** Show/hide fullscreen toggle */
  fullscreen?: boolean;
  /** Show/hide playback speed control */
  playbackRate?: boolean;
  /** Auto-hide controls after inactivity */
  autoHide?: boolean;
  /** Auto-hide timeout in milliseconds */
  autoHideTimeout?: number;
}

export interface VideoTimelineEvent {
  /** Event ID */
  id: string;
  /** Time in seconds when event should trigger */
  time: number;
  /** Event type */
  type: 'marker' | 'chapter' | 'annotation' | 'cue' | 'custom';
  /** Event data */
  data?: VideoTimelineEventData;
  /** Callback function */
  callback?: (event: VideoTimelineEvent, state: VideoState) => void;
}

export interface VideoState {
  /** Current playback time in seconds */
  currentTime: number;
  /** Total duration in seconds */
  duration: number;
  /** Is video playing */
  playing: boolean;
  /** Is video loading */
  loading: boolean;
  /** Is video muted */
  muted: boolean;
  /** Volume level (0-1) */
  volume: number;
  /** Current playback rate */
  playbackRate: VideoPlaybackRate;
  /** Is video in fullscreen */
  fullscreen: boolean;
  /** Video quality (YouTube) */
  quality: VideoQuality;
  /** Error state */
  error: string | null;
  /** Is video buffering */
  buffering: boolean;
}

export type VideoPlaybackRate = 0.25 | 0.5 | 0.75 | 1 | 1.25 | 1.5 | 1.75 | 2;

export type VideoQuality = 'auto' | 'small' | 'medium' | 'large' | 'hd720' | 'hd1080' | 'highres';

export interface VideoTimelineEventData {
  title?: string;
  label?: string;
  [key: string]: unknown;
}
```

## Examples

### Basics

Render `Video` with a local source, default transport controls, and custom buttons wired to the imperative ref for play, pause, and seeking.

```tsx
import { useRef } from 'react';
import { Asset } from 'expo-asset';
import { Block, Button, Row } from '@plocks/ui';
import { Video } from '@plocks/media';
import type { VideoRef } from '@plocks/media';

// `source.url` takes a URL, so resolve the bundled clip to one. `Image.resolveAssetSource`
// is native-only, whereas expo-asset works on web too.
const SOURCE = {
  url: Asset.fromModule(require('../../../../assets/video/demo-clip.mp4')).uri,
} as const;

export function Demo() {
  const videoRef = useRef<VideoRef>(null);

  return (
    <Block fullWidth>
      <Video ref={videoRef} source={SOURCE} />
      <Row gap="sm">
        <Button size="xs" variant="outline" onPress={() => videoRef.current?.play()}>
          Play
        </Button>
        <Button size="xs" variant="outline" onPress={() => videoRef.current?.pause()}>
          Pause
        </Button>
        <Button size="xs" variant="outline" onPress={() => videoRef.current?.seek(4)}>
          Skip to 4s
        </Button>
      </Row>
    </Block>
  );
}
```

### Timeline Events

Pass `timeline` markers to fire callbacks at specific timestamps and keep a log of playback milestones without polling the player.

```tsx
import { useState } from 'react';
import { Asset } from 'expo-asset';
import { Block, Text } from '@plocks/ui';
import { Video } from '@plocks/media';
import type { VideoTimelineEvent } from '@plocks/media';

// `source.url` takes a URL, so resolve the bundled clip to one. `Image.resolveAssetSource`
// is native-only, whereas expo-asset works on web too.
const SOURCE = {
  url: Asset.fromModule(require('../../../../assets/video/demo-clip.mp4')).uri,
} as const;

export function Demo() {
  const [log, setLog] = useState<string[]>([]);

  const timeline: VideoTimelineEvent[] = [
    {
      id: 'intro',
      time: 2,
      type: 'chapter',
      data: { title: 'Introduction' },
      callback: () => setLog((entries) => [...entries, 'Reached introduction at 2s']),
    },
    {
      id: 'main-content',
      time: 5,
      type: 'chapter',
      data: { title: 'Main content' },
      callback: () => setLog((entries) => [...entries, 'Reached main content at 5s']),
    },
  ];

  return (
    <Block fullWidth>
      <Video source={SOURCE} timeline={timeline} />
      {log.map((entry, index) => (
        <Text key={`${entry}-${index}`} size="xs">
          {entry}
        </Text>
      ))}
    </Block>
  );
}
```

### YouTube Source

Set `source.youtube` to a YouTube video ID or URL to stream hosted media with the same controls as native sources.

```tsx
import { Block } from '@plocks/ui';
import { Video } from '@plocks/media';

export function Demo() {
  return (
    <Block fullWidth>
      <Video source={{ youtube: 'dQw4w9WgXcQ' }} />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Waveform.md -->

# Waveform

Waveform visualizes audio data and can provide a seek control.

## Metadata

- Import: `import { Waveform } from '@plocks/ui';`
- Tags: audio, waveform, visualization, media, interactive
- Docs: https://plocks.dev/components/Waveform
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Waveform

## Props

- `peaks` (required): number[] — Array of peak values (normalized between -1 and 1)
- `w`: number = 300 — Width in px; it sets the drawing's geometry. Use `fullWidth` to fill the parent. @default 300
- `h`: number — Height in px (the drawing's geometry). Defaults to the `size` token's height.
- `color`: string — Color of the waveform
- `variant`: 'bars' | 'line' | 'rounded' | 'gradient' — Visual variant of the waveform
- `size`: ComponentSizeValue = 'md' — Size token controlling height, bar width/gap, stroke width, and label type. Accepts any of the seven component tokens (`xs`–`3xl`) or a number, which is read as the waveform height and scales the bar metrics proportionally. Individual props (`h`, `barWidth`, `barGap`, `strokeWidth`, `minBarHeight`) override the token they derive from.
- `barWidth`: number — Width of individual bars (for bar variants)
- `barGap`: number — Gap between bars (for bar variants)
- `strokeWidth`: number — Stroke width for line variant
- `gradientColors`: string[] — Colors for gradient variant
- `progress`: number — Progress value (0-1) to show playback position
- `progressColor`: string — Color for the progress indicator
- `interactive`: boolean — Whether the waveform is interactive. With `onSeek` it becomes a seek slider: pointer press/drag, arrow keys (5 s steps when `duration` is set, else 1%), PageUp/PageDown, Home/End, and screen-reader adjust actions.
- `onSeek`: (position: number) => void — Callback fired when user clicks/seeks to a position (0-1)
- `onDragStart`: (position: number) => void — Callback fired when user starts dragging
- `onDrag`: (position: number) => void — Callback fired when user is dragging
- `onDragEnd`: (position: number) => void — Callback fired when user ends dragging
- `accessibilityLabel`: string — Accessible name. Interactive waveforms are announced as a slider (default name "Audio waveform"), others as an image ("Audio waveform visualization").
- `accessibilityHint`: string — Accessibility hint for interactive waveforms (native)
- `minBarHeight`: number — Minimum height for bars (prevents invisible bars)
- `normalize`: boolean — Whether to normalize waveform heights so the tallest bar uses full height
- `fullWidth`: boolean — Whether the waveform should take the full width of its container
- `maxVisibleBars`: number — Maximum number of bars to render (for performance with large datasets)
- `showProgressLine`: boolean — Whether to show a vertical progress line indicator
- `progressLineStyle`: { color?: string; width?: number; opacity?: number; } — Style configuration for the progress line
- `showTimeStamps`: boolean — Whether to show time stamps along the waveform
- `duration`: number — Duration in seconds, for time stamps and for the seek slider's spoken value ("1:05 of 3:20") and keyboard step.
- `timeStampInterval`: number — Time stamp interval in seconds
- `loading`: boolean — Whether the waveform is in a loading state
- `error`: string — Error message to display
- `loadingProgress`: number — Loading progress (0-1): fills that share of the loading skeleton's bars
- `selection`: [number, number] — Selected time range [start, end] in normalized coordinates (0-1)
- `onSelectionChange`: (selection: [number, number]) => void — Callback when selection changes. When set, Shift+press-and-drag (web) selects a range instead of seeking.
- `showRMS`: boolean — Whether to show RMS (average) levels alongside peaks
- `rmsData`: number[] — RMS data array (should match peaks length)
- `markers`: WaveformMarker[] — Custom markers to display on the waveform
- `enablePerformanceMonitoring`: boolean — Enable performance monitoring
- `onPerformanceMetrics`: (metrics: PerformanceMetrics) => void — Callback for performance metrics
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Sub-components

`import { WaveformSkeleton } from '@plocks/ui';`

### WaveformSkeleton

- `w`: number = 300 — Width in px; the bars are laid out from it. @default 300
- `h`: number = 60 — Height in px; the bars are sized from it. @default 60
- `fullWidth`: boolean
- `barsCount`: number
- `progress`: number — Loading progress (0-1): that share of the bars is drawn filled.
- `accessibilityLabel`: string = 'Loading waveform' — Accessible name of the loading placeholder. @default 'Loading waveform'
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface WaveformMarker {
  /** Position on waveform (0-1) */
  position: number;
  /** Marker label */
  label?: string;
  /** Marker color */
  color?: string;
  /** Marker type */
  type?: 'line' | 'flag' | 'dot';
  /** Click handler */
  onPress?: () => void;
}

export interface PerformanceMetrics {
  /** Render time in milliseconds */
  renderTime: number;
  /** Number of elements rendered */
  elementsRendered: number;
  /** Memory usage estimate */
  memoryUsage: number;
  /** FPS during interactions */
  averageFPS: number;
}
```

## Examples

### Basics

Render a static waveform by passing the `peaks` array and update playback UI by adjusting the `progress` prop. Here a `Slider` drives that value directly — both use `fullWidth` so they share the container's width.

```tsx
import { useState } from 'react';
import { Block, Slider, Waveform } from '@plocks/ui';

import { WAVEFORM_DEMO_PEAKS } from '../data';

export function Demo() {
  const [progress, setProgress] = useState<number>(0.3);

  return (
    <Block fullWidth>
      <Waveform peaks={WAVEFORM_DEMO_PEAKS} progress={progress} h={64} fullWidth />
      <Slider
        value={Math.round(progress * 100)}
        onChange={(percent) => setProgress(percent / 100)}
        min={0}
        max={100}
        step={1}
        valueLabel={(percent) => `${percent}%`}
      />
    </Block>
  );
}
```

`data.ts`

```ts
export const WAVEFORM_DEMO_PEAKS: number[] = [
  0, 0.002, 0.012, 0.006, -0.313, 0.151, 0.247, 0.114, -0.036, -0.097, -0.03,
  0.107, 0.24, 0.013, -0.124, 0.046, -0.016, 0.109, 0.067, 0.094, -0.171,
  -0.023, -0.104, 0.003, 0.081, 0.026, 0.187, 0.02, -0.15, 0.057, -0.001,
  0.275, 0.257, 0.076, 0.108, -0.066, 0.153, 0.071, 0.033, -0.09, 0.018,
  -0.049, -0.048, -0.007, 0.045, -0.024, -0.067, 0.123, -0.109, 0.038, -0.02,
  -0.031, 0.043, -0.092, 0.083, -0.004, 0.043, 0.076, -0.053, 0.035, -0.049,
  0.023, 0.008, 0.015, 0.008, 0.008
];

export const QUIET_WAVEFORM_PEAKS: number[] = [
  0, 0.05, 0.08, 0.03, -0.09, 0.04, 0.07, 0.02, -0.01, -0.03, -0.01, 0.04, 0.06,
  0.01, -0.04, 0.02, -0.01, 0.03, 0.02, 0.03, -0.05, -0.01, -0.03, 0.001, 0.02,
  0.01, 0.05, 0.01, -0.04, 0.02, 0, 0.07, 0.06, 0.02, 0.03, -0.02, 0.04, 0.02,
  0.01, -0.02, 0.01, -0.01, -0.01, -0.002, 0.01, -0.01
];

export const TRACK_TWO_PEAKS: number[] = [
  0.1, -0.25, 0.4, -0.15, 0.2, -0.35, 0.3, -0.1, 0.05, -0.2, 0.15, -0.3, 0.25,
  -0.05, 0.1, -0.15, 0.2, -0.25, 0.35, -0.1, 0.05, -0.2, 0.15, -0.3, 0.25,
  -0.05, 0.1, -0.15, 0.2, -0.25, 0.1
];

/** Peaks measured from assets/sounds/melody.mp3 (3.86s), 96 buckets. */
export const MELODY_PEAKS: number[] = [
  0.765, 0.683, 0.598, 0.528, 0.464, 0.407, 0.36, 0.316, 0.277, 0.243, 0.949, 0.876,
  0.776, 0.698, 0.592, 0.533, 0.477, 0.407, 0.365, 0.323, 0.528, 0.922, 0.851, 0.738,
  0.643, 0.569, 0.489, 0.438, 0.383, 0.34, 0.297, 0.954, 0.885, 0.798, 0.693, 0.606,
  0.525, 0.468, 0.41, 0.354, 0.308, 0.925, 0.919, 0.828, 0.727, 0.64, 0.557, 0.474,
  0.415, 0.376, 0.338, 0.297, 0.997, 0.869, 0.775, 0.667, 0.595, 0.51, 0.444, 0.408,
  0.356, 0.316, 1, 0.872, 0.786, 0.691, 0.619, 0.555, 0.483, 0.4, 0.359, 0.322,
  0.288, 0.941, 0.835, 0.748, 0.661, 0.588, 0.506, 0.439, 0.39, 0.342, 0.306, 0.272,
  0.238, 0.203, 0.148, 0.13, 0.114, 0.101, 0.088, 0.078, 0.068, 0.06, 0.053, 0.047,
];

/** Peaks measured from the audio track of assets/video/demo-clip.mp4 (7.86s), 96 buckets. */
export const CLIP_PEAKS: number[] = [
  0.77, 0.591, 0.457, 0.354, 0.268, 0.94, 0.741, 0.58, 0.448, 0.342, 0.921, 0.806,
  0.616, 0.469, 0.356, 0.978, 0.803, 0.619, 0.489, 0.366, 0.934, 0.851, 0.647, 0.484,
  0.37, 0.992, 0.859, 0.663, 0.502, 0.393, 0.993, 0.861, 0.691, 0.488, 0.396, 0.923,
  0.932, 0.696, 0.543, 0.41, 0.317, 0.239, 0.153, 0.119, 0.091, 0.071, 0.054, 0.081,
  0.209, 0.379, 0.524, 0.814, 0.61, 0.69, 0.658, 0.619, 0.763, 0.645, 0.576, 0.575,
  0.646, 0.67, 0.795, 0.688, 0.611, 0.65, 0.785, 0.552, 0.612, 0.699, 0.749, 0.72,
  0.731, 0.633, 0.584, 0.748, 0.511, 0.692, 0.698, 0.546, 0.541, 1, 0.466, 0.571,
  0.653, 0.494, 0.526, 0.413, 0.613, 0.41, 0.392, 0.442, 0.499, 0.647, 0.581, 0.319,
];
```

### Full Width

A waveform is a fixed `w` wide (300 by default); enable the `fullWidth` prop to let it stretch to its container instead.

```tsx
import { Block, Text, Waveform } from '@plocks/ui';

import { WAVEFORM_DEMO_PEAKS } from '../data';

export function Demo() {
  return (
    <Block fullWidth>
      <Block>
        <Text variant="small">Default</Text>
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} progress={0.35} h={56} />
      </Block>

      <Block>
        <Text variant="small">fullWidth</Text>
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} progress={0.6} h={56} fullWidth />
      </Block>
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Variants

`variant` picks the render style — `bars` (the default), `rounded`, `line`, or `gradient`, whose ramp derives from `color` unless you pass `gradientColors`. `color` and `normalize` restyle the result without changing the peak data.

```tsx
import { Block, Text, Waveform } from '@plocks/ui';

import { QUIET_WAVEFORM_PEAKS, WAVEFORM_DEMO_PEAKS } from '../data';

const VARIANTS = ['bars', 'rounded', 'line', 'gradient'] as const;

export function Demo() {
  return (
    <Block fullWidth gap="lg">
      <Block>
        {VARIANTS.map((variant) => (
          <Block key={variant} gap="xs">
            <Text variant="small">{variant}</Text>
            <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={64} progress={0.4} variant={variant} fullWidth />
          </Block>
        ))}
      </Block>

      <Block>
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={56} progress={0.25} color="primary" fullWidth />
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={56} progress={0.5} color="success" fullWidth />
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={56} progress={0.75} color="warning" fullWidth />
      </Block>

      <Block>
        <Block gap="xs">
          <Text variant="small">Default</Text>
          <Waveform peaks={QUIET_WAVEFORM_PEAKS} h={56} progress={0.45} color="surface" fullWidth />
        </Block>
        <Block gap="xs">
          <Text variant="small">normalize</Text>
          <Waveform peaks={QUIET_WAVEFORM_PEAKS} h={56} progress={0.45} normalize color="surface" fullWidth />
        </Block>
      </Block>
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Synchronized

Drive multiple waveforms from the same `progress` state so scrubbing either track keeps every timeline aligned.

```tsx
import { useState } from 'react';
import { Block, Text, Waveform } from '@plocks/ui';

import { TRACK_TWO_PEAKS, WAVEFORM_DEMO_PEAKS } from '../data';

export function Demo() {
  const [progress, setProgress] = useState<number>(0.35);

  return (
    <Block fullWidth>
      <Block>
        <Text variant="small">Narration track</Text>
        <Waveform
          peaks={WAVEFORM_DEMO_PEAKS}
          progress={progress}
          h={80}
          fullWidth
          interactive
          onSeek={setProgress}
        />
      </Block>

      <Block>
        <Text variant="small">Background score</Text>
        <Waveform
          peaks={TRACK_TWO_PEAKS}
          progress={progress}
          h={80}
          fullWidth
          color="secondary"
          interactive
          onSeek={setProgress}
        />
      </Block>
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Audio playback

Drive the waveform from real playback: `expo-audio` reports the position of a bundled clip, `progress` follows it, and `onSeek` scrubs by calling `seekTo`. The `peaks` array was measured from the same file, so the bars match what you hear.

```tsx
import { useAudioPlayer, useAudioPlayerStatus } from 'expo-audio';
import { Block, Button, Waveform } from '@plocks/ui';

import { MELODY_PEAKS } from '../data';

const MELODY_SOURCE = require('../../../../assets/sounds/melody.mp3');

export function Demo() {
  const player = useAudioPlayer(MELODY_SOURCE);
  const status = useAudioPlayerStatus(player);

  const duration = status.duration || 0;
  const progress = duration > 0 ? Math.min(1, status.currentTime / duration) : 0;

  const togglePlayback = () => {
    if (status.playing) {
      player.pause();
      return;
    }
    // Replay from the top instead of sitting at the end of a finished clip.
    if (status.didJustFinish || (duration > 0 && status.currentTime >= duration - 0.05)) {
      player.seekTo(0);
    }
    player.play();
  };

  const handleSeek = (position: number) => {
    if (duration > 0) {
      player.seekTo(position * duration);
    }
  };

  return (
    <Block fullWidth>
      <Waveform
        peaks={MELODY_PEAKS}
        progress={progress}
        h={96}
        fullWidth
        interactive
        onSeek={handleSeek}
        showProgressLine
        showTimeStamps
        duration={duration}
        accessibilityLabel="Arpeggio waveform"
        accessibilityHint="Tap or drag to seek within the clip"
      />

      <Button size="sm" onPress={togglePlayback}>
        {status.playing ? 'Pause' : 'Play'}
      </Button>
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Synced to video

Use the waveform as a scrub bar for a `Video`: `onTimeUpdate` feeds `progress`, and seeking on the waveform calls `seek()` on the video ref, so the two stay aligned in both directions.

```tsx
import { useRef, useState } from 'react';
import { Asset } from 'expo-asset';
import { Block, Waveform } from '@plocks/ui';
import { Video } from '@plocks/media';
import type { VideoRef, VideoState } from '@plocks/media';

import { CLIP_PEAKS } from '../data';

// `Video` takes a URL, so resolve the bundled clip to one. `Image.resolveAssetSource`
// is native-only, whereas expo-asset works on web too.
const CLIP_URL = Asset.fromModule(require('../../../../assets/video/demo-clip.mp4')).uri;

export function Demo() {
  const videoRef = useRef<VideoRef>(null);
  const [playback, setPlayback] = useState({ currentTime: 0, duration: 0 });

  const progress = playback.duration > 0 ? Math.min(1, playback.currentTime / playback.duration) : 0;

  // `duration` is 0 until metadata loads, so keep the last known value.
  const track = (state: VideoState) =>
    setPlayback((prev) => ({
      currentTime: state.currentTime,
      duration: state.duration || prev.duration,
    }));

  return (
    <Block w="100%" maw={640}>
      <Video
        ref={videoRef}
        source={{ url: CLIP_URL }}
        w="100%"
        aspectRatio={640 / 426}
        controls
        onLoad={track}
        onTimeUpdate={track}
        onDurationChange={(duration) => setPlayback((prev) => ({ ...prev, duration }))}
      />

      <Waveform
        peaks={CLIP_PEAKS}
        progress={progress}
        h={72}
        fullWidth
        interactive
        onSeek={(position) => videoRef.current?.seek(position * playback.duration)}
        showProgressLine
        showTimeStamps
        duration={playback.duration}
        accessibilityLabel="Waveform of the clip audio"
        accessibilityHint="Tap or drag to seek the video"
      />
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

### Interactive

Turn on the `interactive` prop and handle `onSeek`/drag callbacks to update shared playback progress as the user scrubs the waveform.

```tsx
import { useState } from 'react';
import { Block, Text, Waveform } from '@plocks/ui';

import { WAVEFORM_DEMO_PEAKS } from '../data';

export function Demo() {
  const [progress, setProgress] = useState<number>(0.2);

  return (
    <Block fullWidth>
      <Waveform
        peaks={WAVEFORM_DEMO_PEAKS}
        progress={progress}
        fullWidth
        h={72}
        interactive
        showProgressLine
        onSeek={setProgress}
        onDrag={setProgress}
        accessibilityLabel="Audio timeline"
        accessibilityHint="Drag or tap to seek"
      />

      <Text variant="small">Progress: {Math.round(progress * 100)}%</Text>
    </Block>
  );
}
```

`data.ts` is the same file shown under “Basics” above.

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/Wheel.md -->

# Wheel

Use one Wheel for a single choice or place columns together for related values.

## Metadata

- Import: `import { Wheel } from '@plocks/ui';`
- Status: beta
- Docs: https://plocks.dev/components/Wheel
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/Wheel

## Props

- `items` (required): readonly WheelItem<T>[]
- `value`: T — Selected value (controlled).
- `defaultValue`: T — Initially selected value (uncontrolled). Default: the first item.
- `onChange`: (value: T) => void — Called with each value that crosses the center (during a spin, a tap, or a key press).
- `onChangeComplete`: (value: T) => void — Called once the wheel settles on a value.
- `label` (required): string — Accessible name for the wheel, such as "Hour".
- `h`: number = 200 — Column height in px; the selected item sits in its middle. @default 200
- `itemHeight`: number = 40
- `disabled`: boolean = false
- `haptics`: boolean = true — Play a selection detent as each value crosses the center.
- `w`: DimensionProp — Width
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface WheelItem<T extends WheelValue = WheelValue> {
  value: T;
  label?: ReactNode;
}

export type WheelValue = string | number;
```

## Examples

### Basics

Spin or tap the wheel to choose a season. The selected value updates as the wheel moves.

```tsx
import { useState } from 'react';
import { Block, Text, Wheel } from '@plocks/ui';

const seasons = [
  { value: 'Spring', label: 'Spring' },
  { value: 'Summer', label: 'Summer' },
  { value: 'Autumn', label: 'Autumn' },
  { value: 'Winter', label: 'Winter' },
];

export function Demo() {
  const [season, setSeason] = useState('Summer');

  return (
    <Block align="center" gap="sm">
      <Wheel items={seasons} value={season} onChange={setSeason} label="Season" h={180} />
      <Text>Selected: {season}</Text>
    </Block>
  );
}
```

### Time columns

Pair two independently controlled wheels to select an hour and minute.

```tsx
import { useState } from 'react';
import { Block, Row, Text, Wheel } from '@plocks/ui';

const hours = Array.from({ length: 12 }, (_, index) => ({
  value: index + 1,
  label: String(index + 1).padStart(2, '0'),
}));

const minutes = [0, 15, 30, 45].map((value) => ({
  value,
  label: String(value).padStart(2, '0'),
}));

export function Demo() {
  const [hour, setHour] = useState(9);
  const [minute, setMinute] = useState(30);

  return (
    <Block align="center" gap="sm">
      <Row gap="sm">
        <Wheel items={hours} value={hour} onChange={setHour} label="Hour" h={180} itemHeight={36} />
        <Wheel
          items={minutes}
          value={minute}
          onChange={setMinute}
          label="Minute"
          h={180}
          itemHeight={36}
        />
      </Row>
      <Text>
        Time: {hour}:{String(minute).padStart(2, '0')}
      </Text>
    </Block>
  );
}
```

### Disabled wheel

Disable a wheel when its value should remain visible but cannot be changed.

```tsx
import { Wheel } from '@plocks/ui';

const options = [
  { value: 'Small', label: 'Small' },
  { value: 'Medium', label: 'Medium' },
  { value: 'Large', label: 'Large' },
];

export function Demo() {
  return <Wheel items={options} value="Medium" label="Size" disabled />;
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/YearPicker.md -->

# YearPicker

Grid-based selector for choosing a year within a configurable range. Supports responsive layouts, decade navigation, and min/max constraints for simplified year selection flows.

## Metadata

- Import: `import { YearPicker } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Status: beta
- Docs: https://plocks.dev/components/YearPicker
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/YearPicker

## Props

- `value`: Date | null — Currently selected date
- `onChange`: (date: Date | null) => void — Called when a year is selected
- `decade`: number — Decade anchor that should be displayed
- `onDecadeChange`: (decade: number) => void — Called when the visible decade changes
- `minDate`: Date — Minimum selectable date (inclusive)
- `maxDate`: Date — Maximum selectable date (inclusive)
- `size`: SizeValue = 'md' — Typography size token
- `yearsPerRow`: ResponsiveProp<number> — Responsive override for number of years per row (breakpoints from `theme.breakpoints`).
- `hideHeader`: boolean = false — Hide navigation header when embedding the picker
- `totalYears`: number = 20 — Total number of years to render (defaults to 20)
- `fullWidth`: boolean = false — Stretch to fill the container instead of sizing to the natural grid width. Default `false`.
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Grid-based selector for choosing a year within a configurable range. Supports responsive layouts, decade navigation, and min/max constraints for simplified year selection flows.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { YearPicker } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(new Date());

  return (
    <Block fullWidth>
      <YearPicker value={value} onChange={setValue} totalYears={20} />
      <Text size="sm" c="secondary">
        {value ? `Selected: ${value.getFullYear()}` : 'No year selected'}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/YearPickerInput.md -->

# YearPickerInput

YearPickerInput opens a year picker from a form field.

## Metadata

- Import: `import { YearPickerInput } from '@plocks/dates';`
- Install: `npm install @plocks/dates` — a separate package from `@plocks/ui`
- Status: beta
- Docs: https://plocks.dev/components/YearPickerInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/dates/src/components/YearPickerInput

## Props

- `value`: Date | null — Controlled value for the selected year
- `defaultValue`: Date | null — Default year when uncontrolled
- `onChange`: (value: Date | null) => void — Called when the year selection changes
- `formatValue`: (value: Date) => string = defaultFormat — Custom formatter for the input value
- `closeOnSelect`: boolean = true — Close the picker after selecting a year
- `yearPickerProps`: Partial<Omit<YearPickerProps, 'value'>> — Additional props forwarded to YearPicker (except value)
- `dropdownType`: 'modal' | 'popover' = 'modal' — `modal` (default): a centered sheet. `popover`: a dropdown anchored to the field on desktop web (the sheet on native and small screens).
- `modalTitle`: string = 'Select year' — Title of the picker sheet / name of the popover.
- `onOpen`: () => void — Called when the picker opens
- `onClose`: () => void — Called when the picker closes
- `w`: DimensionProp — Width
- `h`: DimensionProp — Height
- `miw`: DimensionProp — Minimum width
- `maw`: DimensionProp — Maximum width
- `mih`: DimensionProp — Minimum height
- `mah`: DimensionProp — Maximum height
- `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade syntax, or any CSS color.
- `opacity`: number — Opacity, `0`–`1`

Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `startSection` `endSection` `startSectionProps` `endSectionProps`), base (`style` `testID`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`), sizing (`fullWidth`), visibility (`lightHidden` `darkHidden` `hiddenFrom` `visibleFrom`), disclaimer (`disclaimer` `disclaimerProps`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

YearPickerInput opens a year picker from a form field.

```tsx
import React, { useState } from 'react';
import { Block, Text } from '@plocks/ui';
import { YearPickerInput } from '@plocks/dates';

export function Demo() {
  const [value, setValue] = useState<Date | null>(null);

  return (
    <Block fullWidth>
      <YearPickerInput
        value={value}
        onChange={setValue}
        label="Fiscal year"
        placeholder="Select a year"
        clearable
        fullWidth
      />
      <Text size="sm" c="secondary">
        {value ? `Selected: ${value.getFullYear()}` : 'No year selected'}
      </Text>
    </Block>
  );
}
```

### Variants

Compare the default, filled, outline, and unstyled field shells on YearPickerInput.

```tsx
import { Column } from '@plocks/ui';
import { YearPickerInput } from '@plocks/dates';

const variants = ['default', 'filled', 'outline', 'unstyled'] as const;

export function Demo() {
  return (
    <Column gap="md" fullWidth>
      {variants.map(variant => (
        <YearPickerInput key={variant} variant={variant} label={`${variant} variant`} placeholder="Choose a year" />
      ))}
    </Column>
  );
}
```

--------------------------------------------------------------------------------

# CHARTS (@plocks/charts)

<!-- source: https://plocks.dev/llms/components/AreaChart.md -->

# Area Chart

Area (filled) chart for visualizing cumulative or stacked trends.

## Metadata

- Import: `import { AreaChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, area, timeseries
- Docs: https://plocks.dev/charts/AreaChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/AreaChart

## Props

- `layout`: 'overlap' | 'stacked' | 'stackedPercentage' = 'overlap' — Controls how multiple series are rendered. - `overlap` leaves each area independent (default). - `stacked` cumulatively stacks values and renders using stacked layers.
- `areaOpacity`: number — Opacity used when rendering stacked layers (if not provided defaults to fillOpacity).
- `stackOrder`: 'normal' | 'reverse' — Adjust the stacking order when using stacked layouts.

Plus the `LineChart` props (`data` `series` `lineColor` `lineThickness` `lineStyle` `showPoints` `pointSize` `pointColor` `smooth` `fill` `fillColor` `fillOpacity` `areaFillMode` `xAxis` `yAxis` `grid` `legend` `tooltip` `animation` `enableCrosshair` `enableSeriesToggle` `liveTooltip` `multiTooltip` `enablePanZoom` `zoomMode` `minZoom` `onDomainChange` `enableWheelZoom` `wheelZoomStep` `invertWheelZoom` `resetOnDoubleTap` `clampToInitialDomain` `invertPinchZoom` `disableAnimations` `decimationThreshold` `xScaleType` `yScaleType` `enableBrushZoom` `annotations`): https://plocks.dev/llms/components/LineChart.md

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Simple random data area chart with title.

```tsx
import { AreaChart } from '@plocks/charts';

import { WEEKLY_SIGNUPS } from './data';

export function Demo() {
  return (
    <AreaChart
      title="Weekly signups"
      subtitle="Organic vs virality"
      h={240}
      data={WEEKLY_SIGNUPS}
      xAxis={{
        show: true,
        labelFormatter: (value: number) => `Week ${value + 1}`,
      }}
      yAxis={{
        show: true,
        labelFormatter: (value: number) => `${value} users`,
      }}
      grid={{ show: true, style: 'dashed' }}
      tooltip={{ show: true }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const WEEKLY_SIGNUPS = [
  { x: 0, y: 42 },
  { x: 1, y: 68 },
  { x: 2, y: 83 },
  { x: 3, y: 97 },
  { x: 4, y: 124 },
  { x: 5, y: 138 },
  { x: 6, y: 152 },
  { x: 7, y: 167 },
];
```

### Inventory Levels Warehouses

```tsx
import { AreaChart } from '@plocks/charts';

import { INVENTORY_SERIES, formatMonth } from './data';

export function Demo() {
  return (
    <AreaChart
      title="Inventory Levels by Warehouse"
      subtitle="Safety stock adjustments across the first half"
      h={420}
      series={INVENTORY_SERIES}
      smooth={false}
      grid={{ show: true, style: 'solid' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const label = formatMonth(Math.round(point.x));
          return `${label} • ${point.data?.warehouse ?? 'Warehouse'}: ${Math.round(point.y)}k units`;
        },
      }}
      xAxis={{
        show: true,
        title: '2025 timeline',
        labelFormatter: (value: number) => formatMonth(Math.round(value)),
      }}
      yAxis={{
        show: true,
        title: 'Inventory on hand (thousands)',
        labelFormatter: (value: number) => `${Math.round(value)}k`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'];

export const INVENTORY_SEGMENTS = [
  {
    id: 'north',
    name: 'North DC',
    values: [420, 432, 446, 438, 412, 398],
    smooth: true,
  },
  {
    id: 'central',
    name: 'Central Hub',
    values: [506, 498, 473, 452, 438, 421],
    smooth: false,
  },
  {
    id: 'south',
    name: 'South Cross-dock',
    values: [318, 332, 347, 352, 366, 371],
    smooth: true,
  },
];

export const formatMonth = (index: number) => MONTHS[index] ?? `M${index + 1}`;

export const INVENTORY_SERIES = INVENTORY_SEGMENTS.map(({ id, name, values, smooth }) => ({
  id,
  name,
  smooth,
  data: values.map((units, index) => ({
    x: index,
    y: units,
    data: { warehouse: name, month: formatMonth(index), units },
  })),
}));
```

### Mobile Device Sessions

```tsx
import { AreaChart } from '@plocks/charts';

import { PHASE_LABELS, SESSION_SERIES } from './data';

const formatPhase = (index: number) => PHASE_LABELS[index] ?? `Week ${index + 1}`;

export function Demo() {
  return (
    <AreaChart
      title="Active Sessions During Launch"
      subtitle="Layered by device platform"
      h={420}
      series={SESSION_SERIES}
      smooth
      grid={{ show: true, style: 'solid' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      enableSeriesToggle
      tooltip={{
        show: true,
        formatter: (point) => {
          const label = formatPhase(Math.round(point.x));
          const channel = point.data?.label ?? 'Sessions';
          return `${label} • ${channel}: ${Math.round(point.y)}k`;
        },
      }}
      xAxis={{
        show: true,
        title: 'Launch timeline',
        labelFormatter: (value: number) => formatPhase(Math.round(value)),
      }}
      yAxis={{
        show: true,
        title: 'Daily sessions (thousands)',
        labelFormatter: (value: number) => `${Math.round(value)}k`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const PHASE_LABELS = ['Pre-Launch', 'Launch Week', 'Week 2', 'Week 3', 'Week 4', 'Week 5'];

export const SESSION_SERIES = [
  {
    id: 'ios',
    name: 'iOS',
    data: [42, 78, 92, 88, 96, 101].map((value, index) => ({ x: index, y: value, data: { label: 'iOS' } })),
  },
  {
    id: 'android',
    name: 'Android',
    data: [58, 94, 103, 108, 112, 118].map((value, index) => ({ x: index, y: value, data: { label: 'Android' } })),
  },
  {
    id: 'web',
    name: 'Web',
    data: [64, 71, 69, 75, 82, 87].map((value, index) => ({ x: index, y: value, data: { label: 'Web' } })),
  },
];
```

### Renewable Energy Mix

Stacks monthly solar, wind, and hydro production to highlight how policy shifts increase clean generation share over the first half of 2025.

```tsx
import { AreaChart } from '@plocks/charts';

import { MONTH_LABELS, RENEWABLE_SERIES } from './data';

const formatMonth = (index: number) => MONTH_LABELS[index] ?? `M${index + 1}`;

export function Demo() {
  return (
    <AreaChart
      layout="stacked"
      title="Renewable Energy Generation"
      subtitle="Utility-scale output by source"
      h={420}
      series={RENEWABLE_SERIES}
      smooth
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      xAxis={{
        show: true,
        title: 'Month of 2025',
        labelFormatter: (value: number) => formatMonth(Math.round(value)),
      }}
      yAxis={{
        show: true,
        title: 'Generation (GWh)',
        labelFormatter: (value: number) => `${Math.round(value)} GWh`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const MONTH_LABELS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'];

export const RENEWABLE_SERIES = [
  {
    id: 'solar',
    name: 'Solar',
    data: [32, 38, 44, 52, 57, 61].map((value, index) => ({ x: index, y: value })),
  },
  {
    id: 'wind',
    name: 'Wind',
    data: [48, 42, 50, 47, 53, 58].map((value, index) => ({ x: index, y: value })),
  },
  {
    id: 'hydro',
    name: 'Hydro',
    data: [36, 34, 31, 28, 30, 33].map((value, index) => ({ x: index, y: value })),
  },
];
```

### Streaming Minutes Campaign

**Story focus** - Tracks how a marketing push shifts audience attention across Originals, TV, film, and live sports week-by-week. - Highlights the share-based stack so teams can see when new content overtakes legacy catalog minutes. - Surfaces total minute contribution per category inside the tooltip for quick campaign readouts. **Key settings** - Uses `layout="stackedPercentage"` to normalize each week to 100% share. - Keeps dashed gridlines and a centered legend for comparative scanning. - Custom tooltip blends absolute minutes with share-of-week for richer context.

```tsx
import { AreaChart } from '@plocks/charts';

import { STREAMING_SERIES, WEEK_TOTALS, formatWeek } from './data';

export function Demo() {
  return (
    <AreaChart
      title="Streaming Minutes During Campaign"
      subtitle="Share of viewing time by content category"
      h={420}
      series={STREAMING_SERIES}
      layout="stackedPercentage"
      stackOrder="normal"
      areaOpacity={0.6}
      smooth
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const index = Math.round(point.x);
          const label = formatWeek(index);
          const minutes = point.data?.minutes ?? 0;
          const total = WEEK_TOTALS[index] ?? 0;
          const share = total > 0 ? (minutes / total) * 100 : 0;
          return `${label} • ${point.data?.category ?? 'Content'}: ${minutes}M min (${share.toFixed(1)}%)`;
        },
      }}
      xAxis={{
        show: true,
        title: 'Campaign cadence',
        labelFormatter: (value: number) => formatWeek(Math.round(value)),
      }}
      yAxis={{
        show: true,
        title: 'Share of weekly minutes',
        labelFormatter: (value: number) => `${Math.round(value * 100)}%`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const CAMPAIGN_WEEKS = ['Teaser Week', 'Launch Week', 'Week 2', 'Week 3', 'Week 4', 'Week 5'];

export const CONTENT_SEGMENTS = [
  {
    id: 'originals',
    name: 'Original Series',
    values: [62, 88, 112, 131, 126, 118],
  },
  {
    id: 'licensed',
    name: 'Licensed TV',
    values: [78, 96, 108, 114, 109, 104],
  },
  {
    id: 'films',
    name: 'Films',
    values: [54, 63, 82, 91, 87, 84],
  },
  {
    id: 'sports',
    name: 'Live Sports',
    values: [18, 22, 34, 47, 52, 48],
  },
];

export const formatWeek = (index: number) => CAMPAIGN_WEEKS[index] ?? `Week ${index + 1}`;

export const STREAMING_SERIES = CONTENT_SEGMENTS.map(({ id, name, values }) => ({
  id,
  name,
  data: values.map((minutes, index) => ({
    x: index,
    y: minutes,
    data: { category: name, week: formatWeek(index), minutes },
  })),
}));

export const WEEK_TOTALS = CAMPAIGN_WEEKS.map((_, index) =>
  STREAMING_SERIES.reduce((sum, series) => sum + (series.data[index]?.y ?? 0), 0)
);
```

### Support Severity Over Time

**Story focus** - Demonstrates how stacked areas surface the composition of weekly ticket inflow by severity level. - Highlights declining critical volume while medium issues remain the majority of support demand. - Emphasizes stability gains after mid-quarter improvements. **Key settings** - Uses the AreaChart `layout="stacked"` mode to visually sum severities per week. - Enables dashed grid lines and a bottom legend for quick reference. - Applies a week-aware `xAxis.labelFormatter` that translates series indices into friendly timeline labels.

```tsx
import { AreaChart } from '@plocks/charts';

import { SEVERITY_SERIES, WEEKS } from './data';

const formatWeek = (index: number) => WEEKS[index] ?? `Week ${index + 1}`;

export function Demo() {
  return (
    <AreaChart
      title="Quarterly Support Ticket Mix"
      subtitle="Stacked by severity level"
      h={420}
      series={SEVERITY_SERIES}
      layout="stacked"
      smooth
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      xAxis={{
        show: true,
        title: 'Quarter timeline',
        labelFormatter: (value: number) => formatWeek(Math.round(value)),
      }}
      yAxis={{
        show: true,
        title: 'Tickets created',
        labelFormatter: (value: number) => `${Math.round(value)}`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const WEEKS = Array.from({ length: 12 }, (_, index) => `Week ${index + 1}`);

export const SEVERITY_SERIES = [
  {
    id: 'sev1',
    name: 'Critical',
    data: [12, 10, 9, 8, 7, 9, 8, 7, 6, 6, 5, 5].map((value, index) => ({ x: index, y: value })),
  },
  {
    id: 'sev2',
    name: 'High',
    data: [28, 32, 34, 29, 26, 24, 22, 23, 21, 19, 18, 17].map((value, index) => ({ x: index, y: value })),
  },
  {
    id: 'sev3',
    name: 'Medium',
    data: [46, 48, 51, 49, 45, 43, 41, 39, 36, 34, 33, 32].map((value, index) => ({ x: index, y: value })),
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/BarChart.md -->

# Bar Chart

Discrete / categorical bar chart visualization component.

## Metadata

- Import: `import { BarChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, bar, categorical
- Docs: https://plocks.dev/charts/BarChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/BarChart

## Props

- `data` (required): BarChartDataPoint[] — Data points
- `series`: BarChartSeries[] — Optional multi-series data
- `barColor`: ChartFill — Bar fill for a single-series chart — a color or a gradient
- `barSpacing`: number = 0.2 — Bar spacing (0-1)
- `barBorderRadius`: number = 4 — Bar border radius
- `orientation`: 'vertical' | 'horizontal' = 'vertical' — Orientation
- `layout`: 'single' | 'grouped' | 'stacked' — Layout strategy for multi-series data
- `stackMode`: 'normal' | '100%' = 'normal' — Stacked layout mode
- `valueFormatter`: (value: number, datum: BarChartDataPoint, index: number) => string — Optional value formatter for tooltip display
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid configuration
- `legend`: ChartLegend = { show: true, position: 'bottom', align: 'center' } — Legend configuration
- `legendToggleEnabled`: boolean — Allow toggling series visibility from the legend
- `thresholds`: BarChartThreshold[] — Reference lines overlaid on the chart
- `valueLabel`: BarChartValueLabelConfig — Value label configuration
- `colorScale`: BarColorScale — Color bars by value (shared scale config) or with a function. Outranks `barColor`.
- `tooltip`: ChartTooltip<BarChartDataPoint> — Tooltip configuration
- `animation`: ChartAnimation — Animation configuration
- `multiTooltip`: boolean — Shared multi-series tooltip
- `enableCrosshair`: boolean — Crosshair enable
- `liveTooltip`: boolean — Live pointer-follow tooltip

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface BarChartDataPoint {
  /** Unique identifier */
  id?: string | number;
  /** Category/label */
  category: string;
  /** Value */
  value: number;
  /** Color override */
  color?: string;
  /** Custom data for interactions */
  data?: any;
}

export interface BarChartSeries {
  /** Unique identifier for the series */
  id: string;
  /** Display name for the legend */
  name?: string;
  /** Optional base color for all data points in the series */
  color?: string;
  /** Data points belonging to this series */
  data: BarChartDataPoint[];
}

export interface BarChartThreshold {
  /** Threshold value rendered as a reference line */
  value: number;
  /** Optional label displayed alongside the line */
  label?: string;
  /** Line color */
  color?: string;
  /** Line thickness */
  width?: number;
  /** Dash pattern */
  style?: 'solid' | 'dashed';
  /** Offset the label from the line (px) */
  labelOffset?: number;
  /** Render the line above or below bars */
  position?: 'front' | 'back';
}

export interface BarChartValueLabelConfig {
  /** Show value labels above or inside bars */
  show?: boolean;
  /** Custom formatter for the value label */
  formatter?: (value: number, datum: BarChartDataPoint, index: number) => string;
  /** Text color */
  color?: string;
  /** Font size */
  fontSize?: number;
  /** Font weight */
  fontWeight?: string | number;
  /** Offset in pixels from the anchor position */
  offset?: number;
  /** Label position relative to the bar */
  position?: 'inside' | 'outside';
}

export type BarColorScale = ColorScaleConfig | ((context: BarColorScaleContext) => string | undefined);

export interface BarColorScaleContext {
  datum: BarChartDataPoint;
  series: BarChartSeries;
  seriesIndex: number;
  categoryIndex: number;
}
```

## Examples

### Basics

Basic BarChart usage with a title.

```tsx
import { BarChart } from '@plocks/charts';

import { QUARTERLY_REVENUE } from './data';

export function Demo() {
  return (
    <BarChart
      title="Quarterly revenue"
      subtitle="North America"
      h={260}
      data={QUARTERLY_REVENUE}
      barSpacing={0.25}
      barBorderRadius={6}
      valueFormatter={(value) => `$${(value / 1000).toFixed(0)}k`}
      xAxis={{ show: true }}
      yAxis={{
        show: true,
        labelFormatter: (value) => `$${(value / 1000).toFixed(0)}k`,
      }}
      grid={{ show: true, style: 'dotted' }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.category}: $${point.value.toLocaleString()}`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const QUARTERLY_REVENUE = [
  { id: 'q1', category: 'Q1', value: 420_000 },
  { id: 'q2', category: 'Q2', value: 515_000 },
  { id: 'q3', category: 'Q3', value: 468_500 },
  { id: 'q4', category: 'Q4', value: 590_200 },
];
```

### Diverging from zero

**Key settings** - `colorScale={{ type: 'diverging', midpoint: 0, colors: [low, high] }}` colors each bar by its value. The scale's domain always includes zero, where bars start. - Both arms are symmetric around the midpoint, so a $40k loss and a $40k gain carry the same intensity.

```tsx
import { BarChart } from '@plocks/charts';

import { NET_CASH_FLOW } from './data';

export function Demo() {
  return (
    <BarChart
      title="Monthly net cash flow"
      subtitle="Diverging from zero: red months lost money, blue months made it"
      h={340}
      data={NET_CASH_FLOW}
      barSpacing={0.24}
      legend={{ show: false }}
      colorScale={{ type: 'diverging', midpoint: 0, colors: ['#e34948', '#2a78d6'] }}
      yAxis={{
        show: true,
        title: 'Net cash flow (USD thousands)',
        labelFormatter: (value) => `$${value}k`,
      }}
      xAxis={{ show: true }}
      grid={{ show: true }}
      valueFormatter={(value) => `${value < 0 ? '-' : '+'}$${Math.abs(value)}k`}
    />
  );
}
```

`data.ts`

```ts
export const NET_CASH_FLOW = [
  { category: 'Jan', value: -42 },
  { category: 'Feb', value: -18 },
  { category: 'Mar', value: 12 },
  { category: 'Apr', value: 35 },
  { category: 'May', value: 28 },
  { category: 'Jun', value: -6 },
  { category: 'Jul', value: 44 },
  { category: 'Aug', value: 61 },
  { category: 'Sep', value: 38 },
  { category: 'Oct', value: 15 },
  { category: 'Nov', value: -24 },
  { category: 'Dec', value: 52 },
];
```

### Gradient bars

**Key settings** - `barColor` takes a gradient as well as a color: `{ angle, stops, extent }`. - `extent: 'plot'` lays one gradient across the whole plot, so each bar shows the slice behind it. The default, `extent: 'mark'`, gives every bar the full gradient.

```tsx
import { BarChart } from '@plocks/charts';

import { HOURLY_REQUESTS } from './data';

export function Demo() {
  return (
    <BarChart
      title="API requests by hour"
      subtitle="One gradient spans the plot, so busier hours reach the deeper end"
      h={320}
      data={HOURLY_REQUESTS}
      barSpacing={0.28}
      legend={{ show: false }}
      barBorderRadius={6}
      barColor={{
        angle: 90,
        extent: 'plot',
        stops: [
          { offset: 0, color: '#12805a' },
          { offset: 1, color: '#8fdcbf' },
        ],
      }}
      yAxis={{
        show: true,
        title: 'Requests (millions)',
        labelFormatter: (value) => `${value}M`,
      }}
      xAxis={{ show: true }}
      grid={{ show: true }}
      valueFormatter={(value) => `${value}M requests`}
    />
  );
}
```

`data.ts`

```ts
export const HOURLY_REQUESTS = [
  { category: '00h', value: 1.2 },
  { category: '03h', value: 0.7 },
  { category: '06h', value: 2.4 },
  { category: '09h', value: 6.8 },
  { category: '12h', value: 8.1 },
  { category: '15h', value: 7.4 },
  { category: '18h', value: 5.2 },
  { category: '21h', value: 3.1 },
];
```

### Coloring with a function

**Key settings** - `colorScale` also accepts a function, `({ datum, series, seriesIndex, categoryIndex }) => color`. Here each region is green when it beat its goal and red when it missed. Return `undefined` to fall back to `barColor`. - Green and red are status colors, so the value labels state every variance: color is never the only cue.

```tsx
import { BarChart } from '@plocks/charts';

import { REGIONAL_REVENUE } from './data';

// Status colors: the value labels spell out each variance, so color is never the only cue.
const BEAT_PLAN = '#0ca30c';
const MISSED_PLAN = '#d03b3b';

const formatMillions = (value: number) => `$${value.toFixed(2)}M`;

const formatVariance = (value: number, datum: (typeof REGIONAL_REVENUE)[number]) => {
  const goal = datum.data?.goal ?? 0;
  const diff = value - goal;
  const direction = diff >= 0 ? '+' : '-';
  return `${direction}$${Math.abs(diff).toFixed(2)}M vs goal`;
};

export function Demo() {
  return (
    <BarChart
      title="Quarterly Revenue by Region"
      subtitle="Q3 actuals with variance to plan"
      h={420}
      data={REGIONAL_REVENUE}
      barSpacing={0.32}
      colorScale={({ datum }) => (datum.value >= (datum.data?.goal ?? 0) ? BEAT_PLAN : MISSED_PLAN)}
      legend={{ show: false }}
      valueFormatter={(value, datum) => {
        const goal = datum.data?.goal;
        return goal != null
          ? `${formatMillions(value)} actual (goal ${formatMillions(goal)})`
          : formatMillions(value);
      }}
      valueLabel={{
        formatter: (value, datum) => formatVariance(value, datum as (typeof REGIONAL_REVENUE)[number]),
        color: '#1f2937',
        fontSize: 12,
        fontWeight: '600',
        offset: 12,
      }}
      yAxis={{
        show: true,
        title: 'Revenue (USD millions)',
        titleFontSize: 12,
        labelFormatter: (value) => `$${value.toFixed(1)}M`,
      }}
      xAxis={{ show: true }}
      grid={{ show: true }}
      tooltip={{
        formatter: (datum) => {
          const goal = datum.data?.goal ?? 0;
          const diff = datum.value - goal;
          const pct = goal ? (diff / goal) * 100 : 0;
          const direction = diff >= 0 ? '+' : '-';
          const varianceValue = `${direction}${formatMillions(Math.abs(diff))}`;
          const variancePct = `${direction}${Math.abs(pct).toFixed(1)}%`;
          return [
            `${datum.category}`,
            `Actual: ${formatMillions(datum.value)}`,
            `Goal: ${formatMillions(goal)}`,
            `Variance: ${varianceValue} (${variancePct})`,
            datum.data?.focus ? `Focus: ${datum.data.focus}` : undefined,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const REGIONAL_REVENUE = [
  {
    id: 'na',
    category: 'North America',
    value: 5.84,
    data: { goal: 5.6, focus: 'Enterprise upsell momentum' },
  },
  {
    id: 'emea',
    category: 'EMEA',
    value: 4.35,
    data: { goal: 4.1, focus: 'Channel partner acceleration' },
  },
  {
    id: 'apac',
    category: 'APAC',
    value: 3.92,
    data: { goal: 4.0, focus: 'Pipeline impacted by onboarding capacity' },
  },
  {
    id: 'latam',
    category: 'LATAM',
    value: 2.48,
    data: { goal: 2.2, focus: 'New reseller footprint' },
  },
];
```

### Feature Adoption By Tier

```tsx
import { BarChart } from '@plocks/charts';

import { FEATURE_ADOPTION } from './data';

const formatAccounts = (value: number) => `${value.toLocaleString()} accounts`;

export function Demo() {
  return (
    <BarChart
      title="Feature adoption by customer tier"
      subtitle="Accounts live on the experimentation canvas within 45 days"
      h={400}
      data={FEATURE_ADOPTION}
      barSpacing={0.26}
      barBorderRadius={12}
      legend={{ show: false }}
      valueFormatter={(value, datum) => {
        const segmentTotal = datum.data?.accounts ?? value;
        const rate = datum.data?.adoptionRate ?? value / segmentTotal;
        const percentage = `${Math.round((rate ?? 0) * 100)}% adoption`;
        return `${formatAccounts(value)} (${percentage})`;
      }}
      valueLabel={{
        position: 'inside',
        color: '#ffffff',
        fontSize: 13,
        fontWeight: '600',
        formatter: (value) => value.toLocaleString(),
      }}
      yAxis={{
        show: true,
        title: 'Activated accounts',
        titleFontSize: 12,
        labelFormatter: (value) => value.toLocaleString(),
      }}
      xAxis={{ show: true }}
      grid={{ show: true }}
      tooltip={{
        formatter: (datum) => {
          const accounts = datum.data?.accounts ?? datum.value;
          const adoptionRate = datum.data?.adoptionRate ?? datum.value / accounts;
          return [
            datum.category,
            `Activated: ${formatAccounts(datum.value)}`,
            `Account base: ${accounts.toLocaleString()}`,
            `Adoption rate: ${(adoptionRate * 100).toFixed(1)}%`,
          ].join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const FEATURE_ADOPTION = [
  {
    id: 'enterprise',
    category: 'Enterprise',
    value: 1280,
    data: { accounts: 1640, adoptionRate: 0.78 },
  },
  {
    id: 'midmarket',
    category: 'Mid-market',
    value: 930,
    data: { accounts: 1310, adoptionRate: 0.71 },
  },
  {
    id: 'growth',
    category: 'Growth',
    value: 610,
    data: { accounts: 980, adoptionRate: 0.62 },
  },
  {
    id: 'starter',
    category: 'Starter',
    value: 340,
    data: { accounts: 720, adoptionRate: 0.47 },
  },
];
```

### Marketing Spend Multi Touch

```tsx
import { BarChart } from '@plocks/charts';

import { CAMPAIGN_SPEND, TOTAL_SPEND } from './data';

const formatSpend = (value: number) => `$${value.toLocaleString()}k`;

export function Demo() {
  return (
    <BarChart
      title="Marketing spend by channel"
      subtitle="Multi-touch journey campaign mix"
      h={420}
      data={CAMPAIGN_SPEND}
      barSpacing={0.28}
      legend={{ show: false }}
      valueFormatter={(value) => `${formatSpend(value)} invested`}
      valueLabel={{
        color: '#1f2937',
        fontSize: 12,
        offset: 12,
        formatter: (value) => {
          const share = TOTAL_SPEND ? (value / TOTAL_SPEND) * 100 : 0;
          return `${share.toFixed(1)}% of spend`;
        },
      }}
      yAxis={{
        show: true,
        title: 'Investment (USD thousands)',
        titleFontSize: 12,
        labelFormatter: (value) => `$${value.toFixed(0)}k`,
      }}
      xAxis={{ show: true }}
      grid={{ show: true }}
      tooltip={{
        formatter: (datum) => {
          const share = TOTAL_SPEND ? (datum.value / TOTAL_SPEND) * 100 : 0;
          return [
            datum.category,
            `Spend: ${formatSpend(datum.value)}`,
            `Share: ${share.toFixed(1)}% of program`,
            datum.data?.objective ? `Objective: ${datum.data.objective}` : undefined,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const CAMPAIGN_SPEND = [
  {
    id: 'paid-search',
    category: 'Paid search',
    value: 820,
    data: { objective: 'Capture late-stage demand' },
  },
  {
    id: 'paid-social',
    category: 'Paid social',
    value: 540,
    data: { objective: 'Net new persona awareness' },
  },
  {
    id: 'field-events',
    category: 'Field events',
    value: 460,
    data: { objective: 'Pipeline acceleration' },
  },
  {
    id: 'webinars',
    category: 'Webinars & workshops',
    value: 380,
    data: { objective: 'Activation & nurture' },
  },
  {
    id: 'content',
    category: 'Content syndication',
    value: 295,
    data: { objective: 'Top-of-funnel scale' },
  },
  {
    id: 'partners',
    category: 'Partner marketing',
    value: 260,
    data: { objective: 'Co-sell influence' },
  },
];

export const TOTAL_SPEND = CAMPAIGN_SPEND.reduce((sum, item) => sum + item.value, 0);
```

### New Hire Recruiting Cycles

```tsx
import { BarChart } from '@plocks/charts';

import { RECRUITING_PROGRESS } from './data';

const formatDelta = (value: number, datum: (typeof RECRUITING_PROGRESS)[number]) => {
  const previous = datum.data?.previous ?? 0;
  const delta = value - previous;
  if (delta === 0) return 'No change vs last cycle';
  const sign = delta > 0 ? '+' : '-';
  return `${sign}${Math.abs(delta)} vs last cycle`;
};

export function Demo() {
  return (
    <BarChart
      title="New hires secured this recruiting cycle"
      subtitle="Compared with winter intake"
      h={440}
      orientation="horizontal"
      data={RECRUITING_PROGRESS}
      barSpacing={0.25}
      legend={{ show: false }}
      valueFormatter={(value) => `${value} hires`}
      valueLabel={{
        formatter: (value, datum) => formatDelta(value, datum as (typeof RECRUITING_PROGRESS)[number]),
        color: '#1f2937',
        fontSize: 12,
        offset: 10,
      }}
      xAxis={{
        title: 'Hires confirmed',
        labelFormatter: (value) => `${Math.round(value)}`,
      }}
      yAxis={{ show: true }}
      grid={{ show: true }}
      tooltip={{
        formatter: (datum) => {
          const previous = datum.data?.previous ?? 0;
          const delta = datum.value - previous;
          const direction = delta >= 0 ? '+' : '-';
          return [
            `${datum.category}`,
            `This cycle: ${datum.value} hires`,
            `Last cycle: ${previous} hires`,
            `Delta: ${direction}${Math.abs(delta)}`,
            datum.data?.priority ? `Focus: ${datum.data.priority}` : undefined,
            datum.data?.openRoles != null ? `Open roles: ${datum.data.openRoles}` : undefined,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const RECRUITING_PROGRESS = [
  {
    id: 'engineering',
    category: 'Engineering',
    value: 48,
    data: { previous: 42, openRoles: 6, priority: 'Backend & AI platform' },
  },
  {
    id: 'product',
    category: 'Product',
    value: 21,
    data: { previous: 18, openRoles: 3, priority: 'Activation journeys' },
  },
  {
    id: 'sales',
    category: 'Revenue',
    value: 27,
    data: { previous: 24, openRoles: 4, priority: 'Enterprise AEs' },
  },
  {
    id: 'success',
    category: 'Customer Success',
    value: 19,
    data: { previous: 16, openRoles: 2, priority: 'Strategic segments' },
  },
  {
    id: 'support',
    category: 'Support',
    value: 15,
    data: { previous: 14, openRoles: 2, priority: 'Follow-the-sun coverage' },
  },
];
```

### Sla Compliance By Team

```tsx
import { BarChart } from '@plocks/charts';

import { SLA_COMPLIANCE } from './data';

const formatPercent = (value: number) => `${value.toFixed(1)}%`;

export function Demo() {
  return (
    <BarChart
      title="SLA compliance by response team"
      subtitle="Rolling 12-month attainment"
      h={420}
      orientation="horizontal"
      data={SLA_COMPLIANCE}
      barSpacing={0.3}
      legend={{ show: false }}
      valueFormatter={(value) => `${formatPercent(value)} SLA met`}
      valueLabel={{
        color: '#111827',
        fontSize: 12,
        offset: 12,
        formatter: (value) => formatPercent(value),
      }}
      xAxis={{
        title: 'Tickets meeting SLA target',
        labelFormatter: (value) => `${Math.round(value)}%`,
      }}
      yAxis={{ show: true }}
      grid={{ show: true }}
      tooltip={{
        formatter: (datum) => {
          const last = datum.data?.lastQuarter ?? datum.value;
          const delta = datum.value - last;
          const direction = delta >= 0 ? '+' : '-';
          return [
            datum.category,
            `Current: ${formatPercent(datum.value)}`,
            `Last quarter: ${formatPercent(last)}`,
            `Change: ${direction}${Math.abs(delta).toFixed(1)} pts`,
          ].join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const SLA_COMPLIANCE = [
  {
    id: 'enterprise',
    category: 'Enterprise support',
    value: 97.6,
    color: '#16a34a',
    data: { lastQuarter: 96.8 },
  },
  {
    id: 'commercial',
    category: 'Commercial support',
    value: 94.8,
    color: '#f59e0b',
    data: { lastQuarter: 92.4 },
  },
  {
    id: 'success',
    category: 'Customer success',
    value: 96.2,
    color: '#22c55e',
    data: { lastQuarter: 95.1 },
  },
  {
    id: 'platform',
    category: 'Platform incidents',
    value: 91.5,
    color: '#ef4444',
    data: { lastQuarter: 89.7 },
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/BubbleChart.md -->

# Bubble Chart

Scatter-style plot where point radius encodes a third quantitative dimension.

## Metadata

- Import: `import { BubbleChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, bubble, scatter
- Docs: https://plocks.dev/charts/BubbleChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/BubbleChart

## Props

- `data` (required): T[] = [] — Dataset to render
- `dataKey` (required): BubbleChartDataKey<T> — Mapping between dataset keys and chart dimensions
- `range`: [number, number] = [36, 576] — Bubble area range (min/max) used to derive radius. Defaults to [36, 576].
- `minBubbleSize`: number — Optional minimum bubble radius override (px).
- `maxBubbleSize`: number — Optional maximum bubble radius override (px).
- `color`: string — Base fill color when data does not provide one.
- `colorScale`: BubbleColorScale<T> — Color bubbles by a field — a function, or a shared scale config over a numeric field.
- `bubbleOpacity`: number — Bubble fill opacity. Defaults to 0.85.
- `bubbleStrokeColor`: string = 'rgba(0,0,0,0.12)' — Bubble outline color.
- `bubbleStrokeWidth`: number = 1 — Bubble outline width. Defaults to 1.
- `textColor`: string — Axis/grid text color override.
- `gridColor`: string — Grid line color override.
- `label`: string — Optional label shown inside the plot area.
- `valueFormatter`: (value: number, record: T, index: number) => string — Custom formatter for bubble size values (tooltip + legend).
- `withTooltip`: boolean = true — Disable tooltip interactions. Defaults to true (tooltip enabled).
- `tooltip`: ChartTooltip<{ record: T; value: number; label: string; rawX: any; rawY: any; index: number; color: string; }> — Advanced tooltip configuration
- `grid`: ChartGrid | boolean = true — Supply custom grid configuration or disable grid entirely.
- `legend`: ChartLegend — Legend configuration.
- `xAxis`: ChartAxis = {} — X axis configuration (ticks, formatting, labels).
- `yAxis`: ChartAxis = {} — Y axis configuration (ticks, formatting, labels).

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface BubbleChartDataKey<T extends Record<string, any> = Record<string, any>> {
  /** Field name for x axis values */
  x: keyof T;
  /** Field name for y axis values */
  y: keyof T;
  /** Optional field name for bubble size values */
  z?: keyof T;
  /** Optional field giving label for this node */
  label?: keyof T;
  /** Optional field with color override per bubble */
  color?: keyof T;
  /** Optional field supplying stable id */
  id?: keyof T;
}

export type BubbleColorScale<T extends Record<string, any> = Record<string, any>> =
  | (ColorScaleConfig & { by?: 'color' | 'x' | 'y' | 'z' })
  | ((value: any, record: T, index: number) => string | undefined);
```

## Examples

### Basics

Scatter-style plot where point radius encodes a third quantitative dimension.

```tsx
import { BubbleChart } from '@plocks/charts';

import { companies } from './data';

export function Demo() {
  return (
    <BubbleChart
      title="Revenue vs Growth"
      subtitle="Bubble size shows valuation (in millions)"
      h={360}
      data={companies}
      dataKey={{
        x: 'revenue',
        y: 'growth',
        z: 'valuation',
        label: 'company',
        id: 'company',
      }}
      xAxis={{
        title: 'Annual revenue (USD millions)',
        labelFormatter: (value) => `${Math.round(value)}m`,
      }}
      yAxis={{
        title: 'YoY growth %',
        labelFormatter: (value) => `${Math.round(value)}%`,
      }}
      valueFormatter={(value) => `$${Math.round(value)}m`}
      grid={{ show: true }}
      withTooltip
      range={[64, 1152]}
    />
  );
}
```

`data.ts`

```ts
export const companies = [
  { company: 'Aster Labs', revenue: 320, growth: 28, valuation: 920 },
  { company: 'Blue Harbor', revenue: 180, growth: 35, valuation: 620 },
  { company: 'Canopy', revenue: 250, growth: 22, valuation: 710 },
  { company: 'Delta Systems', revenue: 140, growth: 44, valuation: 540 },
  { company: 'Elevate', revenue: 460, growth: 18, valuation: 1080 },
  { company: 'Fieldstone', revenue: 210, growth: 31, valuation: 680 },
  { company: 'Glowforge', revenue: 120, growth: 52, valuation: 480 },
  { company: 'Horizon', revenue: 390, growth: 24, valuation: 960 },
];
```

### Cities Talent Footprint

```tsx
import { BubbleChart } from '@plocks/charts';

import { Region, cities, regionPalette } from './data';

const formatFootprint = (value: number) => `${value.toFixed(0)}k sq ft`;

export function Demo() {
  return (
    <BubbleChart
      title="Global Talent Hubs"
      subtitle="Talent depth vs cost of living — bubble size represents active office footprint"
      h={440}
      data={cities}
      dataKey={{
        x: 'costOfLivingIndex',
        y: 'talentDepth',
        z: 'officeFootprintKsqft',
        label: 'city',
        color: 'region',
        id: 'city',
      }}
      colorScale={(value) => (value && regionPalette[value as Region]) || regionPalette.Americas}
      grid={{ show: true }}
      xAxis={{
        title: 'Cost of living index (base 100 = SF)',
        labelFormatter: (value) => value.toFixed(0),
      }}
      yAxis={{
        title: 'Tech talent depth (0–100 readiness)',
        labelFormatter: (value) => value.toFixed(0),
      }}
      valueFormatter={(value) => formatFootprint(value)}
      tooltip={{
        formatter: ({ record, value }) => [
          `Office footprint: ${formatFootprint(value)}`,
          `Remote ready: ${record.remoteReady}% • Avg tenure: ${record.averageTenure.toFixed(1)} yrs`,
          `Anchor university: ${record.anchorUniversity}`,
        ].join('\n'),
      }}
      range={[81, 1764]}
      legend={{ show: true, position: 'right', align: 'start' }}
    />
  );
}
```

`data.ts`

```ts
export type Region = 'Americas' | 'EMEA' | 'APAC';

export type CityProfile = {
  city: string;
  talentDepth: number;
  costOfLivingIndex: number;
  officeFootprintKsqft: number;
  remoteReady: number;
  averageTenure: number;
  region: Region;
  anchorUniversity: string;
};

export // Validated categorical palette slots (see charts colors.ts paletteDefaultLight).
const regionPalette: Record<Region, string> = {
  Americas: '#2a78d6',
  EMEA: '#eb6834',
  APAC: '#1baf7a',
};

export const cities: CityProfile[] = [
  { city: 'Austin', talentDepth: 78, costOfLivingIndex: 96, officeFootprintKsqft: 185, remoteReady: 68, averageTenure: 3.4, region: 'Americas', anchorUniversity: 'UT Austin' },
  { city: 'Toronto', talentDepth: 82, costOfLivingIndex: 104, officeFootprintKsqft: 150, remoteReady: 72, averageTenure: 3.1, region: 'Americas', anchorUniversity: 'University of Toronto' },
  { city: 'Berlin', talentDepth: 74, costOfLivingIndex: 88, officeFootprintKsqft: 120, remoteReady: 65, averageTenure: 2.9, region: 'EMEA', anchorUniversity: 'TU Berlin' },
  { city: 'Amsterdam', talentDepth: 76, costOfLivingIndex: 110, officeFootprintKsqft: 135, remoteReady: 70, averageTenure: 3.2, region: 'EMEA', anchorUniversity: 'University of Amsterdam' },
  { city: 'Singapore', talentDepth: 90, costOfLivingIndex: 134, officeFootprintKsqft: 210, remoteReady: 61, averageTenure: 3.8, region: 'APAC', anchorUniversity: 'NUS' },
  { city: 'Sydney', talentDepth: 69, costOfLivingIndex: 118, officeFootprintKsqft: 142, remoteReady: 64, averageTenure: 3.0, region: 'APAC', anchorUniversity: 'UNSW' },
  { city: 'Mexico City', talentDepth: 71, costOfLivingIndex: 74, officeFootprintKsqft: 95, remoteReady: 58, averageTenure: 2.6, region: 'Americas', anchorUniversity: 'UNAM' },
  { city: 'Warsaw', talentDepth: 67, costOfLivingIndex: 72, officeFootprintKsqft: 108, remoteReady: 60, averageTenure: 2.7, region: 'EMEA', anchorUniversity: 'Warsaw University of Technology' },
];
```

### Customer Account Health

```tsx
import { BubbleChart } from '@plocks/charts';

import { accounts } from './data';

const formatArr = (value: number) => `$${value.toFixed(2)}M ARR`;

export function Demo() {
  return (
    <BubbleChart
      title="Customer Account Health vs Expansion"
      subtitle="Bubble size reflects current ARR; use upper-right quadrant to spot ready-to-expand logos"
      h={440}
      data={accounts}
      dataKey={{
        x: 'healthScore',
        y: 'expansionPotential',
        z: 'arr',
        label: 'account',
        id: 'account',
      }}
      xAxis={{
        title: 'Account health score',
        labelFormatter: (value) => `${Math.round(value)}`,
      }}
      yAxis={{
        title: 'Expansion potential score',
        labelFormatter: (value) => `${Math.round(value)}`,
      }}
      grid={{ show: true }}
      valueFormatter={(value) => formatArr(value)}
      tooltip={{
        formatter: ({ record, value }) => [
          formatArr(value),
          `Segment: ${record.segment} • CSM: ${record.csOwner}`,
          `Last touch: ${record.lastTouch}`,
        ].join('\n'),
      }}
      range={[96, 1728]}
    />
  );
}
```

`data.ts`

```ts
export type Account = {
  account: string;
  healthScore: number;
  expansionPotential: number;
  arr: number;
  segment: 'Enterprise' | 'Mid-market' | 'Growth';
  csOwner: string;
  lastTouch: string;
};

export const accounts: Account[] = [
  { account: 'Acme Robotics', healthScore: 86, expansionPotential: 78, arr: 1.82, segment: 'Enterprise', csOwner: 'L. Howard', lastTouch: '4 days' },
  { account: 'Bluefin Media', healthScore: 63, expansionPotential: 72, arr: 0.96, segment: 'Mid-market', csOwner: 'A. Patel', lastTouch: '1 day' },
  { account: 'Cloudburst Analytics', healthScore: 92, expansionPotential: 88, arr: 2.35, segment: 'Enterprise', csOwner: 'C. Roman', lastTouch: '2 days' },
  { account: 'Driftwell', healthScore: 57, expansionPotential: 41, arr: 0.54, segment: 'Growth', csOwner: 'B. Ortiz', lastTouch: '6 days' },
  { account: 'Element Labs', healthScore: 74, expansionPotential: 67, arr: 1.22, segment: 'Mid-market', csOwner: 'T. Nguyen', lastTouch: 'Today' },
  { account: 'Fleetbase', healthScore: 48, expansionPotential: 83, arr: 0.81, segment: 'Growth', csOwner: 'D. Blake', lastTouch: '8 days' },
  { account: 'Horizon Capital', healthScore: 88, expansionPotential: 53, arr: 1.58, segment: 'Enterprise', csOwner: 'R. Chen', lastTouch: '3 days' },
  { account: 'Northwind Freight', healthScore: 69, expansionPotential: 91, arr: 1.44, segment: 'Mid-market', csOwner: 'S. Kim', lastTouch: '5 days' },
];
```

### Engineering Epic Risk

```tsx
import { BubbleChart } from '@plocks/charts';

import { Squad, epics, squadPalette } from './data';

const formatMultiplier = (value: number) => `${value.toFixed(1)}× risk`;

export function Demo() {
  return (
    <BubbleChart
      title="Epic Risk Landscape"
      subtitle="Story points vs defect density — bubble area communicates composite risk multiplier"
      h={420}
      data={epics}
      dataKey={{
        x: 'storyPoints',
        y: 'defectDensity',
        z: 'riskMultiplier',
        label: 'epic',
        color: 'squad',
        id: 'epic',
      }}
      colorScale={(value) => (value ? squadPalette[value as Squad] : squadPalette['Platform Reliability'])}
      grid={{ show: true }}
      xAxis={{
        title: 'Estimated effort (story points)',
        labelFormatter: (value) => `${Math.round(value)}`,
      }}
      yAxis={{
        title: 'Defect density (per 1000 lines)',
        labelFormatter: (value) => value.toFixed(1),
      }}
      valueFormatter={(value) => formatMultiplier(value)}
      tooltip={{
        formatter: ({ record, value }) => [
          formatMultiplier(value),
          `Critical paths: ${record.criticalPaths}`,
          `Squad: ${record.squad} • Phase: ${record.phase}`,
        ].join('\n'),
      }}
      range={[64, 1296]}
      legend={{ show: true, position: 'right', align: 'start' }}
    />
  );
}
```

`data.ts`

```ts
export type Squad =
  | 'Platform Reliability'
  | 'Automation'
  | 'Security'
  | 'Mobile'
  | 'Monetization'
  | 'Enablement'
  | 'Observability'
  | 'FinOps';

export type Epic = {
  epic: string;
  storyPoints: number;
  defectDensity: number;
  riskMultiplier: number;
  criticalPaths: number;
  squad: Squad;
  phase: 'Design' | 'Build' | 'Stabilize';
};

export // Validated categorical palette slots (see charts colors.ts paletteDefaultLight).
const squadPalette: Record<Squad, string> = {
  'Platform Reliability': '#2a78d6',
  Automation: '#eb6834',
  Security: '#1baf7a',
  Mobile: '#eda100',
  Monetization: '#e87ba4',
  Enablement: '#008300',
  Observability: '#4a3aa7',
  FinOps: '#e34948',
};

export const epics: Epic[] = [
  { epic: 'Observability Agent v2', storyPoints: 210, defectDensity: 0.7, riskMultiplier: 3.1, criticalPaths: 4, squad: 'Platform Reliability', phase: 'Build' },
  { epic: 'Workflow Automation', storyPoints: 160, defectDensity: 0.5, riskMultiplier: 2.4, criticalPaths: 2, squad: 'Automation', phase: 'Design' },
  { epic: 'Data Residency Controls', storyPoints: 180, defectDensity: 0.9, riskMultiplier: 3.6, criticalPaths: 5, squad: 'Security', phase: 'Build' },
  { epic: 'Mobile Offline Sync', storyPoints: 120, defectDensity: 0.4, riskMultiplier: 2.1, criticalPaths: 1, squad: 'Mobile', phase: 'Build' },
  { epic: 'Billing Pipeline Rewrite', storyPoints: 240, defectDensity: 1.2, riskMultiplier: 4.4, criticalPaths: 6, squad: 'Monetization', phase: 'Stabilize' },
  { epic: 'Feature Flag Governance', storyPoints: 95, defectDensity: 0.3, riskMultiplier: 1.7, criticalPaths: 1, squad: 'Enablement', phase: 'Design' },
  { epic: 'Real-time Alerts', storyPoints: 140, defectDensity: 0.6, riskMultiplier: 2.5, criticalPaths: 3, squad: 'Observability', phase: 'Build' },
  { epic: 'Infra Cost Guardrails', storyPoints: 185, defectDensity: 0.8, riskMultiplier: 3.2, criticalPaths: 2, squad: 'FinOps', phase: 'Stabilize' },
];
```

### Product Strategy Portfolio

```tsx
import { BubbleChart } from '@plocks/charts';

import { initiatives } from './data';

const formatMillions = (value: number) => `$${value.toFixed(1)}M`;

export function Demo() {
  return (
    <BubbleChart
      title="Product Initiative Portfolio"
      subtitle="Strategic value vs execution effort — bubble scales with projected revenue"
      h={440}
      data={initiatives}
      dataKey={{
        x: 'executionEffort',
        y: 'strategicValue',
        z: 'projectedRevenue',
        label: 'initiative',
        id: 'initiative',
      }}
      grid={{ show: true }}
      xAxis={{
        title: 'Execution effort (1=low, 10=high)',
        labelFormatter: (value) => value.toFixed(1),
      }}
      yAxis={{
        title: 'Strategic value (1=low, 10=high)',
        labelFormatter: (value) => value.toFixed(1),
      }}
      valueFormatter={(value) => formatMillions(value)}
      tooltip={{
        formatter: ({ record, value }) => [
          `Projected revenue: ${formatMillions(value)}`,
          `Confidence: ${record.confidence}%`,
          `Owner: ${record.owner} • Horizon: ${record.horizon}`,
        ].join('\n'),
      }}
      range={[72, 1440]}
    />
  );
}
```

`data.ts`

```ts
export type Initiative = {
  initiative: string;
  strategicValue: number;
  executionEffort: number;
  projectedRevenue: number;
  confidence: number;
  horizon: 'Now' | 'Next' | 'Later';
  owner: string;
};

export const initiatives: Initiative[] = [
  { initiative: 'Unified onboarding flow', strategicValue: 9.4, executionEffort: 3.2, projectedRevenue: 8.8, confidence: 76, horizon: 'Now', owner: 'Growth' },
  { initiative: 'Usage-based pricing', strategicValue: 8.6, executionEffort: 5.1, projectedRevenue: 9.7, confidence: 68, horizon: 'Next', owner: 'Monetization' },
  { initiative: 'AI-driven support', strategicValue: 7.9, executionEffort: 6.3, projectedRevenue: 6.9, confidence: 64, horizon: 'Next', owner: 'Support Ops' },
  { initiative: 'Insights dashboard revamp', strategicValue: 7.1, executionEffort: 4.5, projectedRevenue: 5.6, confidence: 72, horizon: 'Now', owner: 'Product Intelligence' },
  { initiative: 'Partner ecosystem API', strategicValue: 6.4, executionEffort: 7.8, projectedRevenue: 7.5, confidence: 54, horizon: 'Later', owner: 'Platform' },
  { initiative: 'In-app experimentation', strategicValue: 8.1, executionEffort: 3.9, projectedRevenue: 6.1, confidence: 82, horizon: 'Now', owner: 'Growth' },
  { initiative: 'Self-healing infrastructure', strategicValue: 9.1, executionEffort: 7.2, projectedRevenue: 5.4, confidence: 58, horizon: 'Later', owner: 'Core Engineering' },
  { initiative: 'Community templates marketplace', strategicValue: 6.8, executionEffort: 4.4, projectedRevenue: 4.9, confidence: 71, horizon: 'Next', owner: 'Ecosystem' },
];
```

### Vendor Contracts Scoring

```tsx
import { BubbleChart } from '@plocks/charts';

import { Category, categoryPalette, contracts } from './data';

const formatSpend = (value: number) => `$${value.toFixed(1)}M`;

export function Demo() {
  return (
    <BubbleChart
      title="Vendor Contract Health"
      subtitle="Compliance vs renewal probability — bubble area encodes annual spend"
      h={420}
      data={contracts}
      dataKey={{
        x: 'complianceScore',
        y: 'renewalProbability',
        z: 'annualSpendMillions',
        label: 'vendor',
        color: 'category',
        id: 'vendor',
      }}
      colorScale={(value) => (value && categoryPalette[value as Category]) || categoryPalette.Cloud}
      grid={{ show: true }}
      xAxis={{
        title: 'Compliance readiness score',
        labelFormatter: (value) => `${Math.round(value)}`,
      }}
      yAxis={{
        title: 'Renewal probability %',
        labelFormatter: (value) => `${Math.round(value)}%`,
      }}
      valueFormatter={(value) => formatSpend(value)}
      tooltip={{
        formatter: ({ record, value }) => [
          `Annual spend: ${formatSpend(value)}`,
          `Owner: ${record.owner} • Term ends: ${record.termEnds}`,
          `Risk: ${record.riskLevel}`,
        ].join('\n'),
      }}
      range={[72, 1620]}
      legend={{ show: true, position: 'right', align: 'start' }}
    />
  );
}
```

`data.ts`

```ts
export type Category = 'Cloud' | 'Security' | 'Data' | 'Productivity';

export type VendorContract = {
  vendor: string;
  complianceScore: number;
  renewalProbability: number;
  annualSpendMillions: number;
  category: Category;
  owner: string;
  termEnds: string;
  riskLevel: 'Low' | 'Medium' | 'High';
};

export // Validated categorical palette slots (see charts colors.ts paletteDefaultLight).
const categoryPalette: Record<Category, string> = {
  Cloud: '#2a78d6',
  Security: '#eb6834',
  Data: '#1baf7a',
  Productivity: '#eda100',
};

export const contracts: VendorContract[] = [
  { vendor: 'Atlas Cloud', complianceScore: 94, renewalProbability: 88, annualSpendMillions: 4.8, category: 'Cloud', owner: 'Infra Ops', termEnds: 'FY26 Q2', riskLevel: 'Low' },
  { vendor: 'ShieldGuard', complianceScore: 82, renewalProbability: 64, annualSpendMillions: 3.1, category: 'Security', owner: 'Security', termEnds: 'FY25 Q4', riskLevel: 'Medium' },
  { vendor: 'InsightLake', complianceScore: 90, renewalProbability: 79, annualSpendMillions: 2.6, category: 'Data', owner: 'Analytics', termEnds: 'FY25 Q3', riskLevel: 'Low' },
  { vendor: 'FlowSuite', complianceScore: 76, renewalProbability: 72, annualSpendMillions: 1.9, category: 'Productivity', owner: 'Workplace', termEnds: 'FY25 Q1', riskLevel: 'Medium' },
  { vendor: 'SentinelOne', complianceScore: 88, renewalProbability: 54, annualSpendMillions: 3.8, category: 'Security', owner: 'Security', termEnds: 'FY26 Q1', riskLevel: 'High' },
  { vendor: 'Nimbus Edge', complianceScore: 70, renewalProbability: 48, annualSpendMillions: 2.4, category: 'Cloud', owner: 'Infra Ops', termEnds: 'FY24 Q4', riskLevel: 'High' },
  { vendor: 'DataForge', complianceScore: 86, renewalProbability: 83, annualSpendMillions: 2.9, category: 'Data', owner: 'Analytics', termEnds: 'FY26 Q4', riskLevel: 'Low' },
  { vendor: 'CollabSphere', complianceScore: 92, renewalProbability: 91, annualSpendMillions: 3.5, category: 'Productivity', owner: 'Workplace', termEnds: 'FY27 Q1', riskLevel: 'Low' },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/CandlestickChart.md -->

# Candlestick Chart

Visualizes financial OHLC price movements over time.

## Metadata

- Import: `import { CandlestickChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, financial, ohlc
- Docs: https://plocks.dev/charts/CandlestickChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/CandlestickChart

## Props

- `series` (required): CandlestickSeries[] — One or more candlestick series to render
- `movingAveragePeriods`: number[] = [] — Periods for moving average overlay lines (e.g. [20,50])
- `movingAverageColors`: string[] = [] — Colors for moving average overlays (falls back to series palette)
- `showMovingAverages`: boolean = true — Show moving average overlays (defaults true if periods provided)
- `showVolume`: boolean = false — Show volume bars underneath (reserved)
- `volumeHeightRatio`: number = 0.22 — Relative height ratio for volume sub-chart (0-0.5)
- `xAxis`: ChartAxis — Configuration for the horizontal axis
- `yAxis`: ChartAxis — Configuration for the vertical axis
- `grid`: ChartGrid — Background grid configuration
- `legend`: ChartLegend — Legend display options
- `tooltip`: ChartTooltip<CandlestickDataPoint> — Tooltip configuration
- `animation`: ChartAnimation — Animation configuration
- `enableCrosshair`: boolean — Enable crosshair indicator
- `multiTooltip`: boolean — Enable shared tooltip for multiple series
- `liveTooltip`: boolean — Follow pointer live with tooltip
- `enablePanZoom`: boolean — Allow interactive pan and zoom
- `zoomMode`: 'x' | 'y' | 'both' — Which axes support zooming
- `minZoom`: number — Minimum zoom factor relative to original domain
- `enableWheelZoom`: boolean — Enable wheel-based zooming (web only)
- `wheelZoomStep`: number — Step factor applied to wheel zoom operations
- `invertWheelZoom`: boolean — Invert wheel zoom direction
- `resetOnDoubleTap`: boolean — Reset zoom on double-tap or double-click
- `clampToInitialDomain`: boolean — Clamp panning to the initial data domain
- `invertPinchZoom`: boolean — Invert pinch zoom direction
- `xScaleType`: 'linear' | 'log' | 'time' = 'time' — Scale type used for the x axis
- `yScaleType`: 'linear' | 'log' | 'time' = 'linear' — Scale type used for the y axis
- `annotations`: ChartAnnotation[] — Additional annotations to render on the chart

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface CandlestickSeries {
  /** Unique identifier for the series */
  id?: string | number;
  /** Display name for the series */
  name?: string;
  /** Candlestick data points to plot */
  data: CandlestickDataPoint[];
  /** Fill/stroke color used for bullish candles */
  colorBull?: string;
  /** Fill/stroke color used for bearish candles */
  colorBear?: string;
  /** Wick color applied to the candle */
  wickColor?: string;
  /** Whether the series is visible */
  visible?: boolean;
}

export interface CandlestickDataPoint {
  /** Unique identifier for the data point */
  id?: string | number;
  /** X coordinate for the candle (typically time) */
  x: number | Date;
  /** Opening price for the period */
  open: number;
  /** Highest price reached within the period */
  high: number;
  /** Lowest price reached within the period */
  low: number;
  /** Closing price for the period */
  close: number;
  /** Optional traded volume for the period */
  volume?: number;
  /** Arbitrary metadata associated with the data point */
  data?: any;
}
```

## Examples

### Basics

Visualizes financial OHLC price movements over time.

```tsx
import { CandlestickChart } from '@plocks/charts';

import { PRICE_SERIES } from './data';

export function Demo() {
  return (
    <CandlestickChart
      title="AAPL daily candles"
      subtitle="Includes 3 & 5-day moving averages"
      h={360}
      series={[
        {
          id: 'apple',
          name: 'Apple Inc.',
          data: PRICE_SERIES,
          colorBull: '#34C38F',
          colorBear: '#F56565',
          wickColor: '#6B7280',
        },
      ]}
      movingAveragePeriods={[3, 5]}
      xAxis={{
        show: true,
        labelFormatter: (value) => new Date(value).toLocaleDateString('en-US', {
          month: 'short',
          day: 'numeric',
        }),
        title: 'Trading day',
      }}
      yAxis={{
        show: true,
        title: 'Price (USD)',
        labelFormatter: (value) => `$${value.toFixed(0)}`,
      }}
      grid={{ show: true, color: '#E5EAF7' }}
      legend={{ show: true }}
      tooltip={{
        show: true,
        formatter: (candle) =>
          `O: $${candle.open.toFixed(2)} • H: $${candle.high.toFixed(2)} • L: $${candle.low.toFixed(2)} • C: $${candle.close.toFixed(2)}`,
      }}
      enableCrosshair
      liveTooltip
      animation={{ duration: 400 }}
      enablePanZoom
      zoomMode="both"
      minZoom={0.2}
      resetOnDoubleTap
      clampToInitialDomain
      xScaleType="time"
    />
  );
}
```

`data.ts`

```ts
export const PRICE_SERIES = [
  { x: new Date('2023-10-02'), open: 154, high: 158, low: 153, close: 157 },
  { x: new Date('2023-10-03'), open: 157, high: 161, low: 156, close: 160 },
  { x: new Date('2023-10-04'), open: 160, high: 164, low: 159, close: 162 },
  { x: new Date('2023-10-05'), open: 162, high: 166, low: 161, close: 165 },
  { x: new Date('2023-10-06'), open: 165, high: 168, low: 163, close: 164 },
  { x: new Date('2023-10-09'), open: 164, high: 167, low: 162, close: 166 },
  { x: new Date('2023-10-10'), open: 166, high: 170, low: 165, close: 169 },
  { x: new Date('2023-10-11'), open: 169, high: 172, low: 167, close: 168 },
];
```

### Battery Material Pricing

```tsx
import { CandlestickChart } from '@plocks/charts';

import { LITHIUM_SERIES, NICKEL_SERIES, negotiationMarkers } from './data';

const formatWeek = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  day: 'numeric',
});

export function Demo() {
  return (
    <CandlestickChart
      title="Battery Material Pricing"
      subtitle="Negotiation window tracked across lithium and nickel contracts"
      h={420}
      series={[
        {
          id: 'lithium',
          name: 'Lithium carbonate (USD/ton)',
          data: LITHIUM_SERIES,
          colorBull: '#0ea5e9',
          colorBear: '#bfdbfe',
          wickColor: '#1d4ed8',
        },
        {
          id: 'nickel',
          name: 'Nickel sulfate (USD/ton)',
          data: NICKEL_SERIES,
          colorBull: '#facc15',
          colorBear: '#fef08a',
          wickColor: '#ca8a04',
        },
      ]}
      movingAveragePeriods={[3]}
      movingAverageColors={['#6366f1']}
      annotations={negotiationMarkers}
      grid={{ show: true, color: '#E3E8F4' }}
      legend={{ show: true }}
      tooltip={{
        show: true,
        formatter: (candle) => `Open $${candle.open.toLocaleString('en-US')} • Close $${candle.close.toLocaleString('en-US')} \nRange $${candle.low.toLocaleString('en-US')} – $${candle.high.toLocaleString('en-US')}`,
      }}
      xAxis={{
        show: true,
        title: 'Week of shipment',
        labelFormatter: formatWeek,
      }}
      yAxis={{
        show: true,
        title: 'Spot price (USD per metric ton)',
        labelFormatter: (value) => `$${value.toLocaleString('en-US')}`,
      }}
      enableCrosshair
      liveTooltip
      multiTooltip
      xScaleType="time"
    />
  );
}
```

`data.ts`

```ts
export const LITHIUM_SERIES = [
  { x: new Date('2024-09-02'), open: 36200, high: 37180, low: 35420, close: 36840 },
  { x: new Date('2024-09-09'), open: 36840, high: 37510, low: 36080, close: 37200 },
  { x: new Date('2024-09-16'), open: 37200, high: 37840, low: 36520, close: 36610 },
  { x: new Date('2024-09-23'), open: 36610, high: 36950, low: 35840, close: 36020 },
  { x: new Date('2024-09-30'), open: 36020, high: 36480, low: 35260, close: 35510 },
  { x: new Date('2024-10-07'), open: 35510, high: 36040, low: 34800, close: 35160 },
  { x: new Date('2024-10-14'), open: 35160, high: 35590, low: 34420, close: 34780 },
  { x: new Date('2024-10-21'), open: 34780, high: 35200, low: 34060, close: 34920 },
];

export const NICKEL_SERIES = [
  { x: new Date('2024-09-02'), open: 18940, high: 19480, low: 18620, close: 19260 },
  { x: new Date('2024-09-09'), open: 19260, high: 19850, low: 19010, close: 19530 },
  { x: new Date('2024-09-16'), open: 19530, high: 20040, low: 19300, close: 19780 },
  { x: new Date('2024-09-23'), open: 19780, high: 20360, low: 19420, close: 19890 },
  { x: new Date('2024-09-30'), open: 19890, high: 20540, low: 19610, close: 20330 },
  { x: new Date('2024-10-07'), open: 20330, high: 20810, low: 20060, close: 20210 },
  { x: new Date('2024-10-14'), open: 20210, high: 20640, low: 19880, close: 20140 },
  { x: new Date('2024-10-21'), open: 20140, high: 20520, low: 19710, close: 19940 },
];

export const negotiationMarkers = [
  {
    id: 'kickoff',
    shape: 'vertical-line' as const,
    x: new Date('2024-09-16').getTime(),
    color: '#f97316',
    opacity: 0.55,
  },
  {
    id: 'conclusion',
    shape: 'vertical-line' as const,
    x: new Date('2024-10-14').getTime(),
    color: '#0ea5e9',
    opacity: 0.55,
  },
];
```

### Cloud Infra Cost Swings

```tsx
import { CandlestickChart } from '@plocks/charts';

import { COST_SERIES, CloudCandle, annotations } from './data';

export function Demo() {
  return (
    <CandlestickChart
      title="Cloud Spend Volatility"
      subtitle="Optimization window captured a 4.7% cost reduction"
      h={420}
      series={[
        {
          id: 'cloud-costs',
          name: 'Daily infrastructure cost',
          data: COST_SERIES,
          colorBull: '#10b981',
          colorBear: '#ef4444',
          wickColor: '#475569',
        },
      ]}
      movingAveragePeriods={[3, 5, 8]}
      movingAverageColors={['#38bdf8', '#6366f1', '#f97316']}
      showMovingAverages
      showVolume
      volumeHeightRatio={0.24}
      annotations={annotations}
      grid={{ show: true, color: '#E3E8F4' }}
      legend={{ show: true }}
      tooltip={{
        show: true,
        formatter: (candle) => {
          const delta = candle.close - candle.open;
          const deltaLabel = `${delta >= 0 ? '+' : ''}$${delta.toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
          const note = (candle as CloudCandle).note ? `\n• ${ (candle as CloudCandle).note }` : '';
          return [
            `Start: $${candle.open.toLocaleString('en-US', { maximumFractionDigits: 0 })}`,
            `End: $${candle.close.toLocaleString('en-US', { maximumFractionDigits: 0 })} (${deltaLabel})`,
            `Compute hours: ${(candle.volume ?? 0).toLocaleString('en-US')}`,
          ].join(' • ') + note;
        },
      }}
      xAxis={{
        show: true,
        title: 'Billing day',
        labelFormatter: (value) => new Date(value).toLocaleDateString('en-US', {
          month: 'short',
          day: 'numeric',
        }),
      }}
      yAxis={{
        show: true,
        title: 'Daily cloud cost (USD)',
        labelFormatter: (value) => `$${value.toLocaleString('en-US', { maximumFractionDigits: 0 })}`,
      }}
      enableCrosshair
      liveTooltip
      xScaleType="time"
    />
  );
}
```

`data.ts`

```ts
export type CloudCandle = {
  x: Date;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
  note?: string;
};

export const COST_SERIES: CloudCandle[] = [
  { x: new Date('2025-03-03'), open: 54250, high: 55840, low: 53620, close: 55180, volume: 1180 },
  { x: new Date('2025-03-04'), open: 55180, high: 56210, low: 54240, close: 54560, volume: 1340, note: 'CPU credits burst during load test' },
  { x: new Date('2025-03-05'), open: 54560, high: 54980, low: 53880, close: 54120, volume: 1225 },
  { x: new Date('2025-03-06'), open: 54120, high: 54820, low: 52940, close: 53280, volume: 1560, note: 'Rightsizing experiment kicked off' },
  { x: new Date('2025-03-07'), open: 53280, high: 53840, low: 52460, close: 52810, volume: 1490 },
  { x: new Date('2025-03-10'), open: 52810, high: 53350, low: 51980, close: 52140, volume: 1415 },
  { x: new Date('2025-03-11'), open: 52140, high: 53400, low: 51860, close: 53020, volume: 1305 },
  { x: new Date('2025-03-12'), open: 53020, high: 54680, low: 52510, close: 54440, volume: 1380, note: 'Idle clusters paused overnight' },
  { x: new Date('2025-03-13'), open: 54440, high: 55280, low: 53860, close: 54990, volume: 1255 },
  { x: new Date('2025-03-14'), open: 54990, high: 55710, low: 54480, close: 54620, volume: 1190 },
];

export const annotations = [
  {
    id: 'budget-cap',
    shape: 'horizontal-line' as const,
    y: 56000,
    color: '#f97316',
    opacity: 0.55,
  },
  {
    id: 'rightsizing-window',
    shape: 'box' as const,
    x1: new Date('2025-03-05').getTime(),
    x2: new Date('2025-03-11').getTime(),
    y1: 55200,
    y2: 52000,
    color: '#0ea5e9',
    backgroundColor: 'rgba(14,165,233,0.12)',
  },
];
```

### Crypto Treasury Balances

```tsx
import { CandlestickChart } from '@plocks/charts';

import { TREASURY_SERIES, TreasuryCandle, annotations } from './data';

const formatWeek = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  day: 'numeric',
});

export function Demo() {
  return (
    <CandlestickChart
      title="Crypto Treasury Balances"
      subtitle="Weekly BTC position changes with treasury policy markers"
      h={420}
      series={[
        {
          id: 'btc',
          name: 'BTC holdings (USD equivalent)',
          data: TREASURY_SERIES,
          colorBull: '#0ea5e9',
          colorBear: '#f97316',
          wickColor: '#1f2937',
        },
      ]}
      movingAveragePeriods={[2, 4, 6]}
      movingAverageColors={['#38bdf8', '#6366f1', '#facc15']}
      showMovingAverages
      showVolume
      volumeHeightRatio={0.2}
      annotations={annotations}
      grid={{ show: true, color: '#E3E8F4' }}
      legend={{ show: true }}
      tooltip={{
        show: true,
        formatter: (candle) => {
          const delta = candle.close - candle.open;
          const deltaLabel = `${delta >= 0 ? '+' : '-'}$${Math.abs(delta).toLocaleString('en-US', { maximumFractionDigits: 0 })}`;
          const note = (candle as TreasuryCandle).note ? `\n• ${(candle as TreasuryCandle).note}` : '';
          return [
            `Open $${candle.open.toLocaleString('en-US', { maximumFractionDigits: 0 })}`,
            `Close $${candle.close.toLocaleString('en-US', { maximumFractionDigits: 0 })} (${deltaLabel})`,
            `Flow: ${(candle.volume ?? 0).toLocaleString('en-US')} BTC`,
          ].join(' • ') + note;
        },
      }}
      xAxis={{
        show: true,
        title: 'Week of',
        labelFormatter: formatWeek,
      }}
      yAxis={{
        show: true,
        title: 'USD value (thousands)',
        labelFormatter: (value) => `$${value.toLocaleString('en-US')}`,
      }}
      enableCrosshair
      liveTooltip
      multiTooltip
      xScaleType="time"
    />
  );
}
```

`data.ts`

```ts
export type TreasuryCandle = {
  x: Date;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
  note?: string;
};

export const TREASURY_SERIES: TreasuryCandle[] = [
  { x: new Date('2024-05-06'), open: 42800, high: 44150, low: 42340, close: 43820, volume: 145 },
  { x: new Date('2024-05-13'), open: 43820, high: 44760, low: 43080, close: 43310, volume: 162, note: 'Sold 12 BTC to fund R&D' },
  { x: new Date('2024-05-20'), open: 43310, high: 44480, low: 42840, close: 44160, volume: 138 },
  { x: new Date('2024-05-27'), open: 44160, high: 45400, low: 43620, close: 45030, volume: 174 },
  { x: new Date('2024-06-03'), open: 45030, high: 46240, low: 44720, close: 45890, volume: 181 },
  { x: new Date('2024-06-10'), open: 45890, high: 47120, low: 45560, close: 46640, volume: 205, note: 'Derisked 8% into stablecoins' },
  { x: new Date('2024-06-17'), open: 46640, high: 47980, low: 46200, close: 47670, volume: 216 },
  { x: new Date('2024-06-24'), open: 47670, high: 48840, low: 46880, close: 47210, volume: 188 },
  { x: new Date('2024-07-01'), open: 47210, high: 48580, low: 46940, close: 48330, volume: 199 },
  { x: new Date('2024-07-08'), open: 48330, high: 49720, low: 47810, close: 49580, volume: 231 },
  { x: new Date('2024-07-15'), open: 49580, high: 50960, low: 48740, close: 49220, volume: 214 },
  { x: new Date('2024-07-22'), open: 49220, high: 50110, low: 48230, close: 48970, volume: 176, note: 'Compliance sign-off to rebalance' },
];

export const annotations = [
  {
    id: 'policy-shift',
    shape: 'vertical-line' as const,
    x: new Date('2024-06-10').getTime(),
    color: '#38bdf8',
    opacity: 0.65,
  },
  {
    id: 'risk-band',
    shape: 'horizontal-line' as const,
    y: 50000,
    color: '#f97316',
    opacity: 0.5,
  },
];
```

### Saas Usage Peaks

```tsx
import { CandlestickChart } from '@plocks/charts';

import { USAGE_SERIES, UsageCandle, annotations } from './data';

const formatDay = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  day: 'numeric',
});

export function Demo() {
  return (
    <CandlestickChart
      title="SaaS Usage Peaks"
      subtitle="Daily active sessions during phased launch with capacity guardrails"
      h={420}
      series={[
        {
          id: 'active-sessions',
          name: 'Concurrent sessions',
          data: USAGE_SERIES,
          colorBull: '#22c55e',
          colorBear: '#ef4444',
          wickColor: '#0f172a',
        },
      ]}
      movingAveragePeriods={[3, 5]}
      movingAverageColors={['#0ea5e9', '#f97316']}
      showMovingAverages
      showVolume
      volumeHeightRatio={0.24}
      annotations={annotations}
      grid={{ show: true, color: '#E3E8F4' }}
      legend={{ show: true }}
      tooltip={{
        show: true,
        formatter: (candle) => {
          const delta = candle.close - candle.open;
          const deltaLabel = `${delta >= 0 ? '+' : ''}${delta.toLocaleString('en-US')}`;
          const note = (candle as UsageCandle).note ? `\n• ${(candle as UsageCandle).note}` : '';
          return [
            `Start ${candle.open.toLocaleString('en-US')} sessions`,
            `End ${candle.close.toLocaleString('en-US')} (${deltaLabel})`,
            `Peak ${candle.high.toLocaleString('en-US')} • Floor ${candle.low.toLocaleString('en-US')}`,
            `Requests ${(candle.volume ?? 0).toLocaleString('en-US')}`,
          ].join(' • ') + note;
        },
      }}
      xAxis={{
        show: true,
        title: 'Day',
        labelFormatter: formatDay,
      }}
      yAxis={{
        show: true,
        title: 'Concurrent sessions',
        labelFormatter: (value) => value.toLocaleString('en-US'),
      }}
      enableCrosshair
      liveTooltip
      multiTooltip
      xScaleType="time"
    />
  );
}
```

`data.ts`

```ts
export type UsageCandle = {
  x: Date;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
  note?: string;
};

export const USAGE_SERIES: UsageCandle[] = [
  { x: new Date('2024-10-14'), open: 1240, high: 1380, low: 1210, close: 1345, volume: 24200 },
  { x: new Date('2024-10-15'), open: 1345, high: 1480, low: 1320, close: 1452, volume: 26840 },
  { x: new Date('2024-10-16'), open: 1452, high: 1610, low: 1405, close: 1576, volume: 30230, note: 'Feature flags enabled for 35% cohort' },
  { x: new Date('2024-10-17'), open: 1576, high: 1730, low: 1530, close: 1694, volume: 32560 },
  { x: new Date('2024-10-18'), open: 1694, high: 1820, low: 1645, close: 1762, volume: 31890 },
  { x: new Date('2024-10-21'), open: 1762, high: 1885, low: 1710, close: 1856, volume: 34120 },
  { x: new Date('2024-10-22'), open: 1856, high: 1980, low: 1795, close: 1924, volume: 35680, note: 'Marketing launch day' },
  { x: new Date('2024-10-23'), open: 1924, high: 2035, low: 1860, close: 1898, volume: 33140 },
  { x: new Date('2024-10-24'), open: 1898, high: 1975, low: 1805, close: 1832, volume: 28760 },
  { x: new Date('2024-10-25'), open: 1832, high: 1910, low: 1760, close: 1876, volume: 27410 },
];

export const annotations = [
  {
    id: 'launch',
    shape: 'vertical-line' as const,
    x: new Date('2024-10-22').getTime(),
    color: '#6366f1',
    opacity: 0.65,
  },
  {
    id: 'capacity-band',
    shape: 'horizontal-line' as const,
    y: 2000,
    color: '#f97316',
    opacity: 0.55,
  },
];
```

### Subscription Mrr Dynamics

```tsx
import { CandlestickChart } from '@plocks/charts';

import { MRR_SERIES, MrrCandle, annotations } from './data';

const formatMonth = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  year: 'numeric',
});

export function Demo() {
  return (
    <CandlestickChart
      title="Subscription MRR Momentum"
      subtitle="Expansion revenue outpaced churn across a pricing refresh"
      h={420}
      series={[
        {
          id: 'mrr',
          name: 'Monthly recurring revenue',
          data: MRR_SERIES,
          colorBull: '#22c55e',
          colorBear: '#ef4444',
          wickColor: '#0f172a',
        },
      ]}
      movingAveragePeriods={[2, 3]}
      movingAverageColors={['#14b8a6', '#6366f1']}
      showMovingAverages
      showVolume
      volumeHeightRatio={0.22}
      annotations={annotations}
      grid={{ show: true, color: '#E3E8F4' }}
      legend={{ show: true }}
      tooltip={{
        show: true,
        formatter: (candle) => {
          const net = candle.close - candle.open;
          const netLabel = `${net >= 0 ? '+' : '-'}$${Math.abs(net).toLocaleString('en-US')}`;
          const note = (candle as MrrCandle).note ? `\n• ${(candle as MrrCandle).note}` : '';
          return [
            `Open $${candle.open.toLocaleString('en-US')}`,
            `Close $${candle.close.toLocaleString('en-US')} (${netLabel})`,
            `Net expansions: ${(candle.volume ?? 0).toLocaleString('en-US')} accounts`,
          ].join(' • ') + note;
        },
      }}
      xAxis={{
        show: true,
        title: 'Month',
        labelFormatter: formatMonth,
      }}
      yAxis={{
        show: true,
        title: 'MRR (USD)',
        labelFormatter: (value) => `$${value.toLocaleString('en-US')}`,
      }}
      enableCrosshair
      liveTooltip
      multiTooltip
      xScaleType="time"
    />
  );
}
```

`data.ts`

```ts
export type MrrCandle = {
  x: Date;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
  note?: string;
};

export const MRR_SERIES: MrrCandle[] = [
  { x: new Date('2024-02-01'), open: 182000, high: 185400, low: 180600, close: 184900, volume: 58 },
  { x: new Date('2024-03-01'), open: 184900, high: 188200, low: 183300, close: 186700, volume: 62 },
  { x: new Date('2024-04-01'), open: 186700, high: 192500, low: 184200, close: 191400, volume: 96, note: 'Expansion push launched' },
  { x: new Date('2024-05-01'), open: 191400, high: 196300, low: 188100, close: 193800, volume: 104 },
  { x: new Date('2024-06-01'), open: 193800, high: 197600, low: 192200, close: 194100, volume: 71 },
  { x: new Date('2024-07-01'), open: 194100, high: 199900, low: 191500, close: 198600, volume: 109 },
  { x: new Date('2024-08-01'), open: 198600, high: 203200, low: 196700, close: 202800, volume: 122, note: 'New usage-based plan introduced' },
  { x: new Date('2024-09-01'), open: 202800, high: 208400, low: 200200, close: 206100, volume: 118 },
  { x: new Date('2024-10-01'), open: 206100, high: 209900, low: 201800, close: 203300, volume: 84, note: 'Churn spike from legacy tiers' },
  { x: new Date('2024-11-01'), open: 203300, high: 210800, low: 202100, close: 209200, volume: 131 },
  { x: new Date('2024-12-01'), open: 209200, high: 216500, low: 207600, close: 214800, volume: 144 },
  { x: new Date('2025-01-01'), open: 214800, high: 221400, low: 213100, close: 219500, volume: 152 },
];

export const annotations = [
  {
    id: 'pricing-refresh',
    shape: 'vertical-line' as const,
    x: new Date('2024-08-01').getTime(),
    color: '#22c55e',
    opacity: 0.65,
  },
  {
    id: 'churn-band',
    shape: 'box' as const,
    x1: new Date('2024-09-01').getTime(),
    x2: new Date('2024-10-15').getTime(),
    y1: 208000,
    y2: 198000,
    color: '#f97316',
    backgroundColor: 'rgba(249,115,22,0.12)',
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ComboChart.md -->

# Combo Chart

Combines multiple chart types (e.g., bars and line) for richer comparison.

## Metadata

- Import: `import { ComboChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, combo, mixed
- Docs: https://plocks.dev/charts/ComboChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/ComboChart

## Props

- `layers` (required): ComboChartLayer[] — Ordered set of layers to render in the combo chart
- `enableCrosshair`: boolean = true — Enable crosshair indicator across layers
- `multiTooltip`: boolean = true — Enable multi-series tooltip aggregation
- `liveTooltip`: boolean = true — Follow pointer live with tooltip
- `xDomain`: [number, number] — Explicit override for the shared x-domain
- `yDomain`: [number, number] — Explicit override for the primary y-domain
- `yDomainRight`: [number, number] — Explicit override for the secondary y-domain
- `xAxis`: ChartAxis — Axis configuration for the shared x-axis
- `yAxis`: ChartAxis — Axis configuration for the primary y-axis
- `yAxisRight`: ChartAxis — Axis configuration for the secondary y-axis
- `grid`: ChartGrid — Grid line configuration
- `legend`: ChartLegend — Legend display options

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Combines multiple chart types (e.g., bars and line) for richer comparison.

```tsx
import { ComboChart } from '@plocks/charts';

import { LAYERS } from './data';

export function Demo() {
	return (
		<ComboChart
			title="Revenue vs. active users"
			subtitle="First half of FY25"
			h={340}
			layers={LAYERS}
			enableCrosshair
			multiTooltip
			liveTooltip
			xAxis={{
				show: true,
				title: 'Month',
				labelFormatter: (value) => `M${value}`,
			}}
			yAxis={{
				show: true,
				title: 'Revenue (USD thousands)',
				labelFormatter: (value) => `$${value}`,
			}}
			yAxisRight={{
				show: true,
				title: 'Active users (thousands)',
				labelFormatter: (value) => `${value}k`,
			}}
			yDomain={[0, 650]}
			yDomainRight={[80, 200]}
			grid={{ show: true, style: 'dashed' }}
			legend={{ show: true, position: 'bottom' }}
		/>
	);
}
```

`data.ts`

```ts
export const LAYERS = [
	{
		type: 'bar' as const,
		id: 'revenue',
		name: 'Monthly revenue',
		data: [
			{ x: 1, y: 420 },
			{ x: 2, y: 455 },
			{ x: 3, y: 508 },
			{ x: 4, y: 480 },
			{ x: 5, y: 532 },
			{ x: 6, y: 575 },
		],
		opacity: 0.85,
	},
	{
		type: 'line' as const,
		id: 'active-users',
		name: 'Active users',
		targetAxis: 'right' as const,
		data: [
			{ x: 1, y: 110 },
			{ x: 2, y: 134 },
			{ x: 3, y: 149 },
			{ x: 4, y: 158 },
			{ x: 5, y: 166 },
			{ x: 6, y: 172 },
		],
		thickness: 3,
		showPoints: true,
		pointSize: 6,
	},
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/DonutChart.md -->

# Donut Chart

Circular proportional chart with a hollow center (variant of pie chart).

## Metadata

- Import: `import { DonutChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, donut, circular
- Docs: https://plocks.dev/charts/DonutChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/DonutChart

## Props

- `data`: DonutChartDataPoint[] — Data points rendered in the donut
- `rings`: DonutChartRing[] — Optional multi-ring configuration. When provided, the top-level data acts as a fallback
- `size`: number = 280 — Convenience size that sets both width and height when explicit values are omitted
- `innerRadiusRatio`: number = 0.55 — Ratio (0-1) of the inner radius relative to the outer radius when thickness is not provided
- `thickness`: number — Explicit ring thickness override (outerRadius - innerRadius)
- `ringGap`: number — Gap in chart units between concentric rings (defaults to 8 for multi-ring charts)
- `padAngle`: number = 1.5 — Padding between slices in degrees
- `startAngle`: number = -90 — Starting angle for the first slice (degrees)
- `endAngle`: number = 270 — Ending angle for the last slice (degrees)
- `primaryRingIndex`: number = 0 — Index of the ring used for center totals and value formatting (defaults to 0)
- `legendRingIndex`: number — Index of the ring whose slices feed the legend (defaults to primaryRingIndex)
- `inheritColorByLabel`: boolean = true — When true, slices across rings reuse colors based on their label/id
- `legend`: ChartLegend — Legend configuration
- `tooltip`: ChartTooltip<DonutChartDataPoint> — Tooltip configuration
- `animation`: ChartAnimation — Animation configuration
- `centerLabel`: string | DonutCenterLabelFormatter — Primary label rendered in the center (string or formatter)
- `centerSubLabel`: string | DonutCenterLabelFormatter — Secondary label rendered beneath the primary center label
- `centerValueFormatter`: DonutCenterValueFormatter — Formatter for the numerical value shown in the center
- `renderCenterContent`: DonutChartCenterRenderer — Custom renderer for the center content. When provided, overrides default labels
- `emptyLabel`: string = 'No data' — Label displayed when no data is provided
- `padding`: { top: number; right: number; bottom: number; left: number } — Optional padding override for the chart container
- `isolateOnClick`: boolean = false — When true, clicking a slice isolates it (toggles other slices off) and another click restores
- `labels`: DonutChartLabelsConfig — Global label rendering configuration

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface DonutChartDataPoint {
  /** Unique identifier for the slice */
  id?: string | number;
  /** Display label */
  label: string;
  /** Numerical value */
  value: number;
  /** Optional color override */
  color?: string;
  /** Custom metadata forwarded through interactions */
  data?: any;
}

export interface DonutChartRing {
  /** Unique identifier for the ring */
  id?: string | number;
  /** Human readable label for tooltips or analytics */
  label?: string;
  /** Data rendered in this ring */
  data: DonutChartDataPoint[];
  /** Padding between slices specific to this ring (degrees) */
  padAngle?: number;
  /** Starting angle override (degrees) */
  startAngle?: number;
  /** Ending angle override (degrees) */
  endAngle?: number;
  /** Explicit thickness for the ring */
  thickness?: number;
  /** Thickness ratio (0-1) relative to chart radius when explicit thickness is not provided */
  thicknessRatio?: number;
  /** Explicit inner radius ratio (0-1) relative to chart radius */
  innerRadiusRatio?: number;
  /** Optional palette to cycle through when slice colors are not provided */
  colorPalette?: string[];
  /** Determines whether slices from this ring appear in the legend (default true for primary ring) */
  showInLegend?: boolean;
}

export type DonutCenterLabelFormatter = (
  total: number,
  data: DonutChartDataPoint[],
  focused?: DonutChartDataPoint | null
) => string;

export type DonutCenterValueFormatter = (
  value: number,
  total: number,
  dataPoint?: DonutChartDataPoint | null
) => string;

export type DonutChartCenterRenderer = (context: DonutChartCenterRenderContext) => ReactNode;

export interface DonutChartLabelsConfig {
  /** Enable or disable label rendering */
  show?: boolean;
  /** Target rings by numeric index or id */
  rings?: Array<number | string>;
  /** Place labels inside the ring or outside with leader lines */
  position?: 'inside' | 'outside';
  /** Custom formatter for label lines */
  formatter?: (context: DonutChartLabelFormatterContext) => string | string[] | null | undefined;
  /** Whether to append a formatted value line */
  showValue?: boolean;
  /** Whether to append a percentage line */
  showPercentage?: boolean;
  /** Formatter for the numeric value when showValue is true */
  valueFormatter?: (context: DonutChartLabelFormatterContext) => string;
  /** Minimum slice sweep (degrees) required before labeling */
  minAngle?: number;
  /** Override label font size */
  fontSize?: number;
  /** Override label color */
  textColor?: string;
  /** Override line height for multi-line labels */
  lineHeight?: number;
  /** Offset distance applied beyond the ring edge (for outside labels) */
  offset?: number;
  /** Configuration for leader lines */
  leaderLine?: {
    show?: boolean;
    color?: string;
    width?: number;
    length?: number;
  };
}

export interface DonutChartCenterRenderContext {
  total: number;
  primaryRing?: DonutChartRingDetails;
  rings: DonutChartRingDetails[];
  focusedSlice: DonutChartSliceDetails | null;
}

export interface DonutChartLabelFormatterContext {
  slice: DonutChartSliceDetails;
  ring: DonutChartRingDetails;
  value: number;
  percentage: number;
}
```

## Examples

### Basics

Circular proportional chart with a hollow center (variant of pie chart).

```tsx
import { DonutChart } from '@plocks/charts';

import { SEGMENTS } from './data';

export function Demo() {
	return (
		<DonutChart
			title="Team allocation"
			size={260}
			data={SEGMENTS}
		/>
	);
}
```

`data.ts`

```ts
export const SEGMENTS = [
	{ label: 'Design', value: 28 },
	{ label: 'Engineering', value: 42 },
	{ label: 'Marketing', value: 18 },
	{ label: 'Support', value: 12 },
];
```

### Annual Expense Allocation

```tsx
import { DonutChart } from '@plocks/charts';

import { DEPARTMENT_ALLOCATIONS } from './data';

const formatBudget = (value: number) => `$${Intl.NumberFormat('en-US', { maximumFractionDigits: 0 }).format(value)}M`;

export function Demo() {
  return (
    <DonutChart
      title="Annual Expense Allocation"
      subtitle="FY26 operating plan"
      size={300}
      data={DEPARTMENT_ALLOCATIONS}
      padAngle={1.8}
      legend={{ position: 'bottom' }}
      centerLabel={() => 'Budget'}
      centerSubLabel={() => 'Allocation by function'}
      centerValueFormatter={(value) => formatBudget(value)}
    />
  );
}
```

`data.ts`

```ts
import type { DonutChartDataPoint } from '@plocks/charts';

export const DEPARTMENT_ALLOCATIONS: DonutChartDataPoint[] = [
  { label: 'Product & Engineering', value: 42 },
  { label: 'Go-to-Market', value: 24 },
  { label: 'Customer Success', value: 14 },
  { label: 'G&A', value: 9 },
  { label: 'R&D Partnerships', value: 7 },
  { label: 'Workplace & Ops', value: 4 },
];
```

### Customer Segment Growth

```tsx
import { DonutChart } from '@plocks/charts';
import type { DonutChartDataPoint } from '@plocks/charts';

import { ARR_SEGMENTS, GROWTH_CONTRIBUTION } from './data';

const formatMillions = (value: number) => `${Intl.NumberFormat('en-US', { maximumFractionDigits: 0 }).format(value)}M`;

const getRingId = (slice?: DonutChartDataPoint | null) => (slice as any)?.ringId as string | undefined;

export function Demo() {
  return (
    <DonutChart
      title="ARR Mix by Segment"
      subtitle="FY26 to date"
      size={320}
      ringGap={16}
      rings={[
        {
          id: 'arr',
          label: 'Annual Recurring Revenue',
          data: ARR_SEGMENTS,
          padAngle: 1.8,
          showInLegend: true,
        },
        {
          id: 'growth',
          label: 'YoY Growth Contribution',
          data: GROWTH_CONTRIBUTION,
          thicknessRatio: 0.16,
          padAngle: 1.2,
          showInLegend: false,
        },
      ]}
      primaryRingIndex={0}
      legendRingIndex={0}
      centerLabel={(total, _data, focused) => {
        if (focused) {
          return focused.label;
        }
        return 'Total ARR';
      }}
      centerSubLabel={(total, _data, focused) => {
        if (!focused) return 'YoY growth vs. FY25';
        return getRingId(focused) === 'growth' ? 'Growth contribution' : 'Segment share';
      }}
      centerValueFormatter={(value, _total, focused) => {
        if (focused && getRingId(focused) === 'growth') {
          return `${value.toFixed(0)}%`;
        }
        return `$${formatMillions(value)}`;
      }}
      legend={{ position: 'bottom' }}
    />
  );
}
```

`data.ts`

```ts
import type { DonutChartDataPoint } from '@plocks/charts';

export const ARR_SEGMENTS: DonutChartDataPoint[] = [
  { id: 'enterprise', label: 'Enterprise', value: 82, data: { metric: 'arr' } },
  { id: 'mid-market', label: 'Mid-Market', value: 54, data: { metric: 'arr' } },
  { id: 'smb', label: 'SMB', value: 36, data: { metric: 'arr' } },
  { id: 'self-serve', label: 'Self-Serve', value: 22, data: { metric: 'arr' } },
];

export const GROWTH_CONTRIBUTION: DonutChartDataPoint[] = [
  { id: 'enterprise', label: 'Enterprise', value: 34, data: { metric: 'growth' } },
  { id: 'mid-market', label: 'Mid-Market', value: 28, data: { metric: 'growth' } },
  { id: 'smb', label: 'SMB', value: 22, data: { metric: 'growth' } },
  { id: 'self-serve', label: 'Self-Serve', value: 16, data: { metric: 'growth' } },
];
```

### Data Center Power

```tsx
import { DonutChart } from '@plocks/charts';

import { POWER_BY_SUBSYSTEM } from './data';

const formatMegawatts = (value: number) => `${value.toFixed(1)} MW`;

export function Demo() {
  return (
    <DonutChart
      title="Data Center Power Draw"
      subtitle="May 2025 peak load"
      size={320}
      data={POWER_BY_SUBSYSTEM}
      padAngle={2}
      legend={{ position: 'right', align: 'start' }}
      padding={{ top: 140, right: 168, bottom: 72, left: 72 }}
      centerLabel={() => 'Power load'}
      centerSubLabel={() => 'Across campus subsystems'}
      centerValueFormatter={(value) => formatMegawatts(value)}
      labels={{
        show: true,
        position: 'outside',
        showPercentage: true,
        showValue: true,
        valueFormatter: ({ value }) => formatMegawatts(value),
        leaderLine: { width: 1.5 },
      }}
    />
  );
}
```

`data.ts`

```ts
import type { DonutChartDataPoint } from '@plocks/charts';

export const POWER_BY_SUBSYSTEM: DonutChartDataPoint[] = [
  { label: 'Compute clusters', value: 37 },
  { label: 'Storage arrays', value: 21 },
  { label: 'Networking fabric', value: 14 },
  { label: 'Cooling systems', value: 18 },
  { label: 'Ancillary load', value: 10 },
];
```

### Employee Geography Workstyle

```tsx
import { View, Text } from 'react-native';
import { DonutChart } from '@plocks/charts';

import { REGION_HEADCOUNT, WORK_STYLE, remoteRatio } from './data';

const formatHeadcount = (value: number) => Intl.NumberFormat('en-US', { maximumFractionDigits: 0 }).format(value);

export function Demo() {
  return (
    <DonutChart
      title="Employee Distribution"
      subtitle="Geography and work style"
      size={320}
      ringGap={18}
      rings={[
        {
          id: 'region',
          label: 'Regional distribution',
          data: REGION_HEADCOUNT,
          padAngle: 2.2,
          thicknessRatio: 0.3,
          showInLegend: false,
        },
        {
          id: 'work-style',
          label: 'Work style mix',
          data: WORK_STYLE,
          thicknessRatio: 0.18,
          padAngle: 1.5,
          showInLegend: true,
        },
      ]}
      primaryRingIndex={0}
      legendRingIndex={1}
      renderCenterContent={({ focusedSlice, primaryRing, total }) => {
        const isWorkStyle = focusedSlice?.ringId === 'work-style';
        const headline = focusedSlice ? focusedSlice.label : 'Headcount';
        const valueText = focusedSlice
          ? isWorkStyle
            ? `${Math.round((focusedSlice.percentage || 0) * 100)}%`
            : formatHeadcount(focusedSlice.value)
          : formatHeadcount(primaryRing?.total ?? total);
        const helperText = focusedSlice
          ? isWorkStyle
            ? 'of workforce'
            : 'global headcount'
          : `Remote ${Math.round(remoteRatio * 100)}%`;

        return (
          <View style={{ alignItems: 'center', justifyContent: 'center' }}>
            <Text
              style={{
                fontSize: 12,
                fontWeight: '600',
                textTransform: 'uppercase',
                color: '#868E96',
                marginBottom: 2,
              }}
            >
              {headline}
            </Text>
            <Text
              style={{
                fontSize: 26,
                fontWeight: '700',
                color: '#212529',
              }}
            >
              {valueText}
            </Text>
            <Text
              style={{
                fontSize: 12,
                color: '#495057',
                marginTop: 4,
              }}
            >
              {helperText}
            </Text>
          </View>
        );
      }}
      labels={{
        show: true,
        rings: ['work-style'],
        position: 'outside',
        showPercentage: true,
        leaderLine: { width: 1.4 },
      }}
      legend={{ position: 'bottom' }}
    />
  );
}
```

`data.ts`

```ts
import type { DonutChartDataPoint } from '@plocks/charts';

export const REGION_HEADCOUNT: DonutChartDataPoint[] = [
  { id: 'na', label: 'North America', value: 1820 },
  { id: 'emea', label: 'EMEA', value: 1240 },
  { id: 'apac', label: 'APAC', value: 860 },
  { id: 'latam', label: 'LATAM', value: 480 },
];

export const WORK_STYLE: DonutChartDataPoint[] = [
  { id: 'remote', label: 'Remote', value: 2760, data: { kind: 'work-style' } },
  { id: 'onsite', label: 'Onsite', value: 1640, data: { kind: 'work-style' } },
];

export const remoteRatio = WORK_STYLE[0].value / (WORK_STYLE[0].value + WORK_STYLE[1].value);
```

### Marketplace Fulfillment Mix

```tsx
import { DonutChart } from '@plocks/charts';

import { FULFILLMENT_PARTNERS } from './data';

const formatOrders = (value: number) => `${value.toFixed(2)}M`;

export function Demo() {
  return (
    <DonutChart
      title="Marketplace Fulfillment Mix"
      subtitle="Orders fulfilled in Q3"
      size={300}
      data={FULFILLMENT_PARTNERS}
      padAngle={1.6}
      isolateOnClick
      legend={{ position: 'bottom' }}
      centerLabel={() => 'Orders'}
      centerSubLabel={() => 'Fulfilled volume by partner'}
      centerValueFormatter={(value) => `${formatOrders(value)} total`}
    />
  );
}
```

`data.ts`

```ts
import type { DonutChartDataPoint } from '@plocks/charts';

export const FULFILLMENT_PARTNERS: DonutChartDataPoint[] = [
  { label: 'Direct warehouses', value: 1.35 },
  { label: '3PL network', value: 1.08 },
  { label: 'Regional partners', value: 0.82 },
  { label: 'Drop-ship vendors', value: 0.54 },
  { label: 'Micro-fulfillment hubs', value: 0.31 },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/FunnelChart.md -->

# Funnel Chart

Shows progressive reduction of data through stages (conversion pipeline).

## Metadata

- Import: `import { FunnelChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, funnel, conversion
- Docs: https://plocks.dev/charts/FunnelChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/FunnelChart

## Props

- `series` (required): FunnelChartSeries | FunnelChartSeries[] — Funnel data series to render
- `layout`: FunnelLayoutConfig — Layout customization options
- `valueFormatter`: FunnelValueFormatter — Formatter for step values
- `tooltip`: ChartTooltip<FunnelStep> — Tooltip configuration
- `legend`: ChartLegend — Legend configuration
- `enableCrosshair`: boolean = true — Enable crosshair indicator
- `multiTooltip`: boolean = true — Enable aggregated tooltip for multiple series
- `liveTooltip`: boolean = false — Keep tooltip following the pointer
- `accessibilityTable`: FunnelAccessibilityTableOptions — Render hidden accessibility table
- `onDataTable`: (payloads: FunnelDataTablePayload[]) => void — Callback invoked with data table payload

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface FunnelChartSeries {
  /** Unique identifier for the series */
  id?: string | number;
  /** Display name for the series */
  name?: string;
  /** Ordered steps within the funnel */
  steps: FunnelStep[];
  /** Base color applied to the steps */
  color?: string;
  /** Whether the series is visible */
  visible?: boolean;
}

export interface FunnelLayoutConfig {
  /** Shape style used to render steps */
  shape?: 'trapezoid' | 'bar';
  /** Gap between consecutive steps */
  gap?: number;
  /** Minimum pixel height for each segment */
  minSegmentHeight?: number;
  /** Horizontal alignment of the funnel */
  align?: 'center' | 'left' | 'right';
  /** Show conversion percentage between steps */
  showConversion?: boolean;
  /** How to render multiple series */
  seriesMode?: 'single' | 'grouped' | 'stacked';
  /** Pixel breakpoint used to switch to left-aligned layout */
  responsiveBreakpoint?: number;
  /** Extra spacing between grouped segments */
  groupGap?: number;
  /** Optional maximum label width before truncation */
  labelMaxWidth?: number;
  /** Connector configuration */
  connectors?: FunnelConnectorConfig;
}

export type FunnelValueFormatter = (
  value: number,
  index: number,
  context?: FunnelValueFormatterContext
) => string | string[];

export interface FunnelStep {
  /** Step label displayed in the funnel */
  label: string;
  /** Absolute value for the step */
  value: number;
  /** Override color used for the step */
  color?: string;
  /** Additional metadata associated with the step */
  meta?: any;
  /** Optional override for where the label should render */
  labelPosition?: 'inside' | 'outside-left' | 'outside-right';
  /** Human readable label for the trend delta */
  trendLabel?: string;
  /** Numeric delta used to drive up/down styling */
  trendDelta?: number;
}

export interface FunnelAccessibilityTableOptions {
  /** Display the hidden accessible table representation */
  show?: boolean;
  /** Optional aria-label or summary text */
  summary?: string;
  /** Custom id for the hidden table element */
  id?: string;
}

export interface FunnelDataTablePayload {
  /** Series identifier (for grouped funnels) */
  seriesId: string | number | undefined;
  /** Series display name */
  seriesName?: string;
  /** Flattened rows for consumers */
  rows: FunnelDataTableRow[];
}

export interface FunnelConnectorConfig {
  /** Render connectors between stages */
  show?: boolean;
  /** Stroke color for the connecting lines */
  stroke?: string;
  /** Stroke width for connector lines */
  strokeWidth?: number;
  /** Optional radius for rounded connector corners */
  radius?: number;
  /** Format the label displayed around the connector */
  labelFormatter?: FunnelConversionLabelFormatter;
  /** Offset applied to the connector label */
  labelOffset?: number;
}

export interface FunnelValueFormatterContext {
  /** Step index */
  index: number;
  /** Step currently being rendered */
  step: FunnelStep;
  /** All steps in the funnel */
  steps: FunnelStep[];
  /** Previous step value if available */
  previousValue?: number;
  /** First step value for retention calculations */
  firstValue: number;
  /** Share of the first step still present (0-1) */
  conversion: number;
  /** Share lost vs. the previous step (0-1) */
  dropRate: number;
  /** Absolute drop amount vs. the previous step */
  dropValue: number;
}
```

## Examples

### Basics

Shows progressive reduction of data through stages (conversion pipeline).

```tsx
import { FunnelChart, formatCompactNumber } from '@plocks/charts';

import { SALES_FUNNEL } from './data';

export function Demo() {
	return (
		<FunnelChart
			title="Product acquisition funnel"
			maw={420}
			h={420}
			series={SALES_FUNNEL}
			layout={{
				shape: 'trapezoid',
				gap: 8,
				showConversion: false,
				align: 'center',
				connectors: { show: false },
			}}
			valueFormatter={(value) => formatCompactNumber(value)}
			legend={{ show: false }}
			tooltip={{
				show: true,
				formatter: (step) => `${step.label}: ${step.value.toLocaleString()}`,
			}}
		/>
	);
}
```

`data.ts`

```ts
export const SALES_FUNNEL = {
	id: 'pipeline',
	name: 'Q2 pipeline',
	steps: [
		{ label: 'Website visits', value: 32_500 },
		{ label: 'Sign-ups', value: 9_600 },
		{ label: 'Qualified leads', value: 4_350 },
		{ label: 'Trials started', value: 2_150 },
		{ label: 'Customers', value: 1_120 },
	],
};
```

### Data Pipeline Quality

```tsx
import { FunnelChart, formatCompactNumber } from '@plocks/charts';

import { PIPELINE_QUALITY, PipelineMeta } from './data';

export function Demo() {
  return (
    <FunnelChart
      title="Data pipeline quality checks"
      subtitle="From ingestion to certified datasets"
      maw={520}
      h={440}
      series={PIPELINE_QUALITY}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => formatCompactNumber(value)}
      legend={{ show: false }}
      tooltip={{
        show: true,
        formatter: (step) => {
          const idx = PIPELINE_QUALITY.steps.findIndex((candidate) => candidate.label === step.label);
          const previous = idx > 0 ? PIPELINE_QUALITY.steps[idx - 1] : undefined;
          const dropValue = previous ? previous.value - step.value : 0;
          const dropRate = previous && previous.value > 0 ? (dropValue / previous.value) * 100 : 0;
          const meta = step.meta as PipelineMeta | undefined;
          return [
            step.label,
            `${step.value.toLocaleString()} rows`,
            previous ? `Filtered: ${dropValue.toLocaleString()} (${dropRate.toFixed(1)}%)` : 'Ingestion baseline',
            meta?.note,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export type PipelineMeta = {
  note?: string;
};

export const PIPELINE_QUALITY = {
  id: 'data-quality-pipeline',
  name: 'Data quality checkpoints',
  steps: [
    { label: 'Ingested', value: 12_400_000 },
    { label: 'Validated', value: 11_760_000, meta: { note: 'Dropped malformed partner feeds and null timestamps' } as PipelineMeta },
    { label: 'Deduplicated', value: 11_180_000, meta: { note: 'UserId + sessionId key resolves campaign duplicates' } as PipelineMeta },
    { label: 'QA passed', value: 10_260_000, meta: { note: 'Primary blockers: stale reference data & threshold breaches' } as PipelineMeta },
    { label: 'Certified', value: 9_940_000, meta: { note: 'Ready for downstream activation' } as PipelineMeta },
  ],
};
```

### Ecommerce Checkout Payments

```tsx
import { FunnelChart, formatCompactNumber } from '@plocks/charts';

import { CHECKOUT_FUNNEL, CheckoutMeta } from './data';

const formatPaymentSplit = (split: CheckoutMeta['paymentSplit']) => {
  if (!split) return undefined;
  return `Payment mix: ${Math.round(split.stripe * 100)}% Stripe • ${Math.round(split.paypal * 100)}% PayPal • ${Math.round(split.bnpl * 100)}% BNPL`;
};

export function Demo() {
  return (
    <FunnelChart
      title="Ecommerce checkout conversion"
      subtitle="Drop-off by stage"
      maw={520}
      h={440}
      series={CHECKOUT_FUNNEL}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => formatCompactNumber(value)}
      legend={{ show: false }}
      tooltip={{
        show: true,
        formatter: (step) => {
          const idx = CHECKOUT_FUNNEL.steps.findIndex((candidate) => candidate.label === step.label);
          const previous = idx > 0 ? CHECKOUT_FUNNEL.steps[idx - 1] : undefined;
          const dropValue = previous ? previous.value - step.value : 0;
          const dropRate = previous && previous.value > 0 ? (dropValue / previous.value) * 100 : 0;
          const meta = step.meta as CheckoutMeta | undefined;
          const paymentSplit = formatPaymentSplit(meta?.paymentSplit);
          return [
            step.label,
            `${step.value.toLocaleString()} sessions`,
            previous ? `Drop: ${dropValue.toLocaleString()} (${dropRate.toFixed(1)}%)` : 'Entry point',
            meta?.insight,
            paymentSplit,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export type CheckoutMeta = {
  insight?: string;
  paymentSplit?: {
    stripe: number;
    paypal: number;
    bnpl: number;
  };
};

export const CHECKOUT_FUNNEL = {
  id: 'checkout-flow',
  name: 'Checkout completion',
  steps: [
    { label: 'Product views', value: 158_000 },
    { label: 'Carts', value: 89_400, meta: { insight: 'Shipping cost surprises prompt abandon' } as CheckoutMeta },
    { label: 'Shipping', value: 74_200, meta: { insight: 'Address autocomplete boosted completion +12%' } as CheckoutMeta },
    { label: 'Payment', value: 51_200, meta: { insight: 'Card validations reject 28% due to CVV retries' } as CheckoutMeta },
    { label: 'Orders', value: 38_600, meta: { paymentSplit: { stripe: 0.52, paypal: 0.31, bnpl: 0.17 } } as CheckoutMeta },
  ],
};
```

### Hiring Funnel Role Family

```tsx
import { FunnelChart, formatCompactNumber } from '@plocks/charts';

import { HIRING_SERIES, HiringMeta, STEP_LOOKUP } from './data';

const findSeriesContext = (step: unknown) => STEP_LOOKUP.get(step as any) ?? null;

export function Demo() {
  return (
    <FunnelChart
      title="Hiring funnel — Staff engineer"
      subtitle="External candidates vs. internal transfers"
      maw={620}
      h={480}
      series={HIRING_SERIES}
      layout={{
        shape: 'bar',
        gap: 10,
        align: 'center',
        showConversion: false,
        seriesMode: 'grouped',
        connectors: { show: false },
      }}
      valueFormatter={(value) => formatCompactNumber(value)}
      tooltip={{
        show: true,
        formatter: (step) => {
          const lookup = findSeriesContext(step as any) ?? undefined;
          if (!lookup) {
            return `${step.label}: ${step.value.toLocaleString()} candidates`;
          }
          const series = lookup.series;
          const stepIndex = lookup.stepIndex;
          const previous = stepIndex > 0 ? series.steps[stepIndex - 1] : undefined;
          const dropValue = previous ? previous.value - step.value : 0;
          const dropRate = previous && previous.value > 0 ? (dropValue / previous.value) * 100 : 0;
          const meta = step.meta as HiringMeta | undefined;
          return [
            `${step.label} • ${series.name}`,
            `${step.value.toLocaleString()} candidates`,
            previous ? `Drop: ${dropValue.toLocaleString()} (${dropRate.toFixed(1)}%)` : 'Pipeline intake',
            meta?.medianDays != null ? `Median time in stage: ${meta.medianDays} days` : undefined,
            meta?.topDeclineReason ? `Top decline reason: ${meta.topDeclineReason}` : undefined,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export type HiringMeta = {
  medianDays?: number;
  topDeclineReason?: string;
};

export const EXTERNAL_CANDIDATES = [
  { label: 'Applied', value: 780, meta: { medianDays: 0 } as HiringMeta },
  { label: 'Screen', value: 420, meta: { medianDays: 3, topDeclineReason: 'Insufficient architecture depth' } as HiringMeta },
  { label: 'HM interview', value: 210, meta: { medianDays: 6, topDeclineReason: 'Product strategy alignment' } as HiringMeta },
  { label: 'Panel', value: 120, meta: { medianDays: 12, topDeclineReason: 'Leadership signal gaps' } as HiringMeta },
  { label: 'Offered', value: 48, meta: { medianDays: 18, topDeclineReason: 'Compensation delta' } as HiringMeta },
  { label: 'Accepted', value: 22, meta: { medianDays: 24 } as HiringMeta },
];

export const INTERNAL_TRANSFERS = [
  { label: 'Applied', value: 220, meta: { medianDays: 0 } as HiringMeta },
  { label: 'Screen', value: 188, meta: { medianDays: 2, topDeclineReason: 'Role scope mismatch' } as HiringMeta },
  { label: 'HM interview', value: 150, meta: { medianDays: 5, topDeclineReason: 'Org fit feedback' } as HiringMeta },
  { label: 'Panel', value: 110, meta: { medianDays: 9, topDeclineReason: 'Leadership depth' } as HiringMeta },
  { label: 'Offered', value: 72, meta: { medianDays: 14, topDeclineReason: 'Comp band negotiations' } as HiringMeta },
  { label: 'Accepted', value: 44, meta: { medianDays: 18 } as HiringMeta },
];

export const HIRING_SERIES = [
  {
    id: 'external-candidates',
    name: 'External candidates',
    steps: EXTERNAL_CANDIDATES,
  },
  {
    id: 'internal-transfers',
    name: 'Internal transfers',
    steps: INTERNAL_TRANSFERS,
  },
];

export const STEP_LOOKUP = new Map<any, { series: (typeof HIRING_SERIES)[number]; seriesIndex: number; stepIndex: number }>();
```

### Incident Response Workflow

```tsx
import { FunnelChart, formatCompactNumber } from '@plocks/charts';

import { INCIDENT_RESPONSE, IncidentMeta } from './data';

export function Demo() {
  return (
    <FunnelChart
      title="Incident response workflow"
      subtitle="Volume flowing through each stage"
      maw={520}
      h={460}
      series={INCIDENT_RESPONSE}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => formatCompactNumber(value)}
      legend={{ show: false }}
      tooltip={{
        show: true,
        formatter: (step) => {
          const idx = INCIDENT_RESPONSE.steps.findIndex((candidate) => candidate.label === step.label);
          const previous = idx > 0 ? INCIDENT_RESPONSE.steps[idx - 1] : undefined;
          const dropValue = previous ? previous.value - step.value : 0;
          const dropRate = previous && previous.value > 0 ? (dropValue / previous.value) * 100 : 0;
          const meta = step.meta as IncidentMeta | undefined;
          return [
            `${step.label}`,
            `${step.value.toLocaleString()} incidents`,
            meta?.medianDuration,
            previous ? `Drop since prior: ${dropValue.toLocaleString()} (${dropRate.toFixed(1)}%)` : 'Start of workflow',
            meta?.automationWin ? `Automation impact: ${meta.automationWin}` : undefined,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export type IncidentMeta = {
  medianDuration?: string;
  automationWin?: string;
};

export const INCIDENT_RESPONSE = {
  id: 'incident-response',
  name: 'Incident response workflow',
  steps: [
    { label: 'Detection', value: 264, meta: { medianDuration: '4 min to detect' } as IncidentMeta },
    { label: 'Triage', value: 228, meta: { medianDuration: '16 min to triage', automationWin: 'Pager triage rules auto-close 32 low-signal alerts' } as IncidentMeta },
    { label: 'Containment', value: 182, meta: { medianDuration: '38 min to contain', automationWin: 'Runbooks auto-isolate hosts for 41% of cases' } as IncidentMeta },
    { label: 'Eradication', value: 164, meta: { medianDuration: '1.4 hr to resolve root cause' } as IncidentMeta },
    { label: 'Recovery', value: 158, meta: { medianDuration: '2.3 hr to restore services' } as IncidentMeta },
    { label: 'Review', value: 151, meta: { medianDuration: 'Completed within 48 hr SLA' } as IncidentMeta },
  ],
};
```

### Saas Trial Conversion

```tsx
import { FunnelChart, formatCompactNumber } from '@plocks/charts';

import { TRIAL_CONVERSION, TrialMeta } from './data';

export function Demo() {
  return (
    <FunnelChart
      title="SaaS trial-to-paid conversion"
      subtitle="Retention from sign-up to paid"
      maw={520}
      h={440}
      series={TRIAL_CONVERSION}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => formatCompactNumber(value)}
      legend={{ show: false }}
      tooltip={{
        show: true,
        formatter: (step) => {
          const index = TRIAL_CONVERSION.steps.findIndex((candidate) => candidate.label === step.label);
          const previous = index > 0 ? TRIAL_CONVERSION.steps[index - 1] : undefined;
          const dropValue = previous ? previous.value - step.value : 0;
          const dropRate = previous && previous.value > 0 ? (dropValue / previous.value) * 100 : 0;
          const reason = (step.meta as TrialMeta | undefined)?.dropReason;
          return [
            `${step.label}`,
            `${step.value.toLocaleString()} accounts`,
            previous ? `Drop: ${dropValue.toLocaleString()} (${dropRate.toFixed(1)}%)` : 'Starting cohort',
            reason ? `Top reason: ${reason}` : undefined,
          ]
            .filter(Boolean)
            .join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export type TrialMeta = {
  dropReason?: string;
};

export const TRIAL_CONVERSION = {
  id: 'trial-to-paid',
  name: 'Trial to paid conversion',
  steps: [
    { label: 'Sign-ups', value: 12800 },
    { label: 'Onboarded', value: 9100, meta: { dropReason: 'Setup friction and confusing success criteria' } as TrialMeta },
    { label: 'Week-1 active', value: 6200, meta: { dropReason: 'No team invites or connected data sources' } as TrialMeta },
    { label: 'Contracts', value: 2900, meta: { dropReason: 'Security review backlog and pricing clarity' } as TrialMeta },
    { label: 'Paid', value: 1850, meta: { dropReason: 'Budget timing & procurement approvals' } as TrialMeta },
  ],
};
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/GroupedBarChart.md -->

# Grouped Bar Chart

Bar chart grouping multiple series side-by-side for comparison.

## Metadata

- Import: `import { GroupedBarChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, bar, grouped
- Docs: https://plocks.dev/charts/GroupedBarChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/GroupedBarChart

## Props

- `series` (required): StackedBarSeries[] — Grouped series data to render
- `barSpacing`: number = 0.2 — Gap between grouped categories
- `innerBarSpacing`: number = 0.1 — Gap between bars inside a group
- `legend`: ChartLegend = { show: true, position: 'bottom', align: 'center' } — Legend configuration
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid line configuration
- `animation`: ChartAnimation — Animation configuration
- `colorOptions`: GroupedBarColorOptions — Palette and hashing options for bar colors
- `valueLabels`: GroupedBarValueLabelConfig — Optional bar value label configuration
- `multiTooltip`: boolean — Enable multi-series aggregated tooltip content
- `liveTooltip`: boolean — Keep tooltip visible while pointer moves within chart
- `enableCrosshair`: boolean — Toggle crosshair overlay and events (defaults to enabled)

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface GroupedBarColorOptions {
  /** Palette name or array used for automatic colors */
  palette?: string | any;
  /** Enable color hashing based on category labels */
  hash?: boolean;
}

export interface GroupedBarValueLabelConfig {
  /** Display numeric labels for each bar */
  show?: boolean;
  /** Position strategy for labels */
  position?: 'inside' | 'outside' | 'auto';
  /** Custom formatter for label text */
  formatter?: (params: GroupedBarValueLabelFormatterParams) => string | number;
  /** Text color */
  color?: string;
  /** Font size */
  fontSize?: number;
  /** Font weight */
  fontWeight?: string | number;
  /** Font family override */
  fontFamily?: string;
  /** Pixel offset applied to label placement */
  offset?: number;
  /** Minimum bar height (px) required to keep labels inside */
  minBarHeightForInside?: number;
}

export interface GroupedBarValueLabelFormatterParams {
  /** Raw numeric value for the bar */
  value: number;
  /** Category the bar belongs to */
  category: string;
  /** Zero-based index of the category */
  categoryIndex: number;
  /** Identifier for the series */
  seriesId: string;
  /** Optional human readable series name */
  seriesName?: string;
  /** Zero-based index of the series */
  seriesIndex: number;
  /** Original datum backing the bar */
  datum: BarChartDataPoint;
}
```

## Examples

### Basics

Bar chart grouping multiple series side-by-side for comparison.

```tsx
import { GroupedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
	return (
		<GroupedBarChart
			title="Product revenue by segment"
			subtitle="Comparison vs targets"
			h={320}
			series={SERIES}
			barSpacing={0.15}
			innerBarSpacing={0.2}
			xAxis={{ show: true, title: 'Segment' }}
			yAxis={{
				show: true,
				title: 'Revenue (USD thousands)',
				labelFormatter: (value) => `$${value}`,
			}}
			grid={{ show: true }}
			legend={{ show: true, position: 'bottom' }}
			animation={{ duration: 450 }}
			colorOptions={{ hash: false }}
		/>
	);
}
```

`data.ts`

```ts
export const SERIES = [
	{
		id: '2024',
		name: '2024',
		data: [
			{ id: 'analytics-24', category: 'Analytics', value: 420 },
			{ id: 'automation-24', category: 'Automation', value: 365 },
			{ id: 'integrations-24', category: 'Integrations', value: 298 },
		],
	},
	{
		id: '2025',
		name: '2025',
		data: [
			{ id: 'analytics-25', category: 'Analytics', value: 512 },
			{ id: 'automation-25', category: 'Automation', value: 418 },
			{ id: 'integrations-25', category: 'Integrations', value: 342 },
		],
	},
	{
		id: 'target',
		name: 'Target',
		color: '#FF922B',
		data: [
			{ id: 'analytics-target', category: 'Analytics', value: 540 },
			{ id: 'automation-target', category: 'Automation', value: 440 },
			{ id: 'integrations-target', category: 'Integrations', value: 360 },
		],
	},
];
```

### Experiment Variant By Geo

```tsx
import { GroupedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <GroupedBarChart
      title="Experiment conversion uplift by region"
      subtitle="Completed purchases per 100 sessions"
      h={340}
      series={SERIES}
      barSpacing={0.22}
      innerBarSpacing={0.18}
      xAxis={{
        show: true,
        title: 'Region',
      }}
      yAxis={{
        show: true,
        title: 'Conversion rate (%)',
        labelFormatter: (value) => `${value.toFixed(1)}%`,
        ticks: [3, 4, 5, 6],
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      multiTooltip
      liveTooltip
      valueLabels={{
        show: true,
        position: 'outside',
        formatter: ({ value }) => `${value.toFixed(1)}%`,
        color: '#1F1F24',
        fontWeight: '600',
        offset: 8,
      }}
      animation={{ duration: 420 }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'control',
    name: 'Control',
    data: [
      { id: 'na-control', category: 'North America', value: 4.8 },
      { id: 'emea-control', category: 'EMEA', value: 4.2 },
      { id: 'apac-control', category: 'APAC', value: 3.9 },
      { id: 'latam-control', category: 'LATAM', value: 3.6 },
    ],
  },
  {
    id: 'variant-a',
    name: 'Variant A',
    data: [
      { id: 'na-var-a', category: 'North America', value: 5.6 },
      { id: 'emea-var-a', category: 'EMEA', value: 4.9 },
      { id: 'apac-var-a', category: 'APAC', value: 4.4 },
      { id: 'latam-var-a', category: 'LATAM', value: 4.1 },
    ],
  },
  {
    id: 'variant-b',
    name: 'Variant B',
    data: [
      { id: 'na-var-b', category: 'North America', value: 6.1 },
      { id: 'emea-var-b', category: 'EMEA', value: 5.3 },
      { id: 'apac-var-b', category: 'APAC', value: 4.8 },
      { id: 'latam-var-b', category: 'LATAM', value: 4.5 },
    ],
  },
];
```

### Feature Usage By Platform

```tsx
import { GroupedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <GroupedBarChart
      title="Feature usage by platform"
      subtitle="Weekly active users per capability (in thousands)"
      h={360}
      series={SERIES}
      barSpacing={0.18}
      innerBarSpacing={0.16}
      xAxis={{
        show: true,
        title: 'Product capability',
      }}
      yAxis={{
        show: true,
        title: 'Weekly active users (thousands)',
        labelFormatter: (value) => `${value}k`,
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      valueLabels={{
        show: true,
        position: 'inside',
        formatter: ({ value }) => `${value}k`,
        color: 'rgba(255,255,255,0.96)',
        fontWeight: '600',
        minBarHeightForInside: 24,
      }}
      animation={{ duration: 420 }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'web',
    name: 'Web',
    data: [
      { id: 'dashboard-web', category: 'Dashboard', value: 82 },
      { id: 'automation-web', category: 'Workflow automation', value: 68 },
      { id: 'notifications-web', category: 'Notifications', value: 74 },
      { id: 'reporting-web', category: 'Reporting', value: 59 },
      { id: 'integrations-web', category: 'Integrations', value: 65 },
    ],
  },
  {
    id: 'ios',
    name: 'iOS',
    data: [
      { id: 'dashboard-ios', category: 'Dashboard', value: 61 },
      { id: 'automation-ios', category: 'Workflow automation', value: 52 },
      { id: 'notifications-ios', category: 'Notifications', value: 78 },
      { id: 'reporting-ios', category: 'Reporting', value: 46 },
      { id: 'integrations-ios', category: 'Integrations', value: 54 },
    ],
  },
  {
    id: 'android',
    name: 'Android',
    data: [
      { id: 'dashboard-android', category: 'Dashboard', value: 57 },
      { id: 'automation-android', category: 'Workflow automation', value: 63 },
      { id: 'notifications-android', category: 'Notifications', value: 85 },
      { id: 'reporting-android', category: 'Reporting', value: 51 },
      { id: 'integrations-android', category: 'Integrations', value: 49 },
    ],
  },
];
```

### Sales Pipeline By Industry

```tsx
import { GroupedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <GroupedBarChart
      title="Sales pipeline by industry"
      subtitle="Qualified pipeline this quarter (USD millions)"
      h={360}
      series={SERIES}
      barSpacing={0.2}
      innerBarSpacing={0.22}
      xAxis={{
        show: true,
        title: 'Industry vertical',
      }}
      yAxis={{
        show: true,
        title: 'Pipeline value (USD millions)',
        labelFormatter: (value) => `$${value.toFixed(1)}M`,
        ticks: [0, 2, 4, 6],
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      valueLabels={{
        show: true,
        position: 'outside',
        formatter: ({ value }) => `$${value.toFixed(1)}M`,
        color: '#2F2F35',
        fontWeight: '600',
        offset: 10,
      }}
      animation={{ duration: 440 }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'new-business',
    name: 'New business',
    data: [
      { id: 'tech-new', category: 'Technology', value: 5.8 },
      { id: 'health-new', category: 'Healthcare', value: 4.1 },
      { id: 'finance-new', category: 'Financial services', value: 4.7 },
      { id: 'retail-new', category: 'Retail', value: 3.9 },
      { id: 'manufacturing-new', category: 'Manufacturing', value: 3.1 },
    ],
  },
  {
    id: 'expansion',
    name: 'Upsell / expansion',
    data: [
      { id: 'tech-expansion', category: 'Technology', value: 4.6 },
      { id: 'health-expansion', category: 'Healthcare', value: 3.4 },
      { id: 'finance-expansion', category: 'Financial services', value: 5.2 },
      { id: 'retail-expansion', category: 'Retail', value: 2.7 },
      { id: 'manufacturing-expansion', category: 'Manufacturing', value: 2.2 },
    ],
  },
];
```

### Student Assessment By Grade

```tsx
import { GroupedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <GroupedBarChart
      title="Assessment results by grade level"
      subtitle="Spring benchmark proficiency rates"
      h={360}
      series={SERIES}
      barSpacing={0.18}
      innerBarSpacing={0.18}
      xAxis={{
        show: true,
        title: 'Subject area',
      }}
      yAxis={{
        show: true,
        title: 'Students meeting or exceeding standard (%)',
        labelFormatter: (value) => `${value}%`,
        ticks: [60, 70, 80, 90, 100],
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      valueLabels={{
        show: true,
        position: 'inside',
        formatter: ({ value }) => `${Math.round(value)}%`,
        color: 'rgba(255,255,255,0.94)',
        fontWeight: '600',
        minBarHeightForInside: 20,
      }}
      animation={{ duration: 430 }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'grade-3',
    name: 'Grade 3',
    data: [
      { id: 'g3-math', category: 'Mathematics', value: 78 },
      { id: 'g3-science', category: 'Science', value: 81 },
      { id: 'g3-language', category: 'Language arts', value: 74 },
      { id: 'g3-social', category: 'Social studies', value: 69 },
      { id: 'g3-stem', category: 'STEM lab', value: 76 },
    ],
  },
  {
    id: 'grade-4',
    name: 'Grade 4',
    data: [
      { id: 'g4-math', category: 'Mathematics', value: 84 },
      { id: 'g4-science', category: 'Science', value: 86 },
      { id: 'g4-language', category: 'Language arts', value: 81 },
      { id: 'g4-social', category: 'Social studies', value: 77 },
      { id: 'g4-stem', category: 'STEM lab', value: 83 },
    ],
  },
  {
    id: 'grade-5',
    name: 'Grade 5',
    data: [
      { id: 'g5-math', category: 'Mathematics', value: 89 },
      { id: 'g5-science', category: 'Science', value: 91 },
      { id: 'g5-language', category: 'Language arts', value: 86 },
      { id: 'g5-social', category: 'Social studies', value: 83 },
      { id: 'g5-stem', category: 'STEM lab', value: 88 },
    ],
  },
];
```

### Supplier On Time By Partner

```tsx
import { GroupedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <GroupedBarChart
      title="On-time delivery by logistics partner"
      subtitle="Share of shipments delivered within committed window"
      h={360}
      series={SERIES}
      barSpacing={0.18}
      innerBarSpacing={0.16}
      xAxis={{
        show: true,
        title: 'Logistics partner',
      }}
      yAxis={{
        show: true,
        title: 'On-time shipments (%)',
        labelFormatter: (value) => `${value}%`,
        ticks: [80, 85, 90, 95, 100],
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      valueLabels={{
        show: true,
        position: 'inside',
        formatter: ({ value }) => `${Math.round(value)}%`,
        color: 'rgba(255,255,255,0.95)',
        fontWeight: '600',
        minBarHeightForInside: 22,
      }}
      animation={{ duration: 440 }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'tier-1',
    name: 'Tier 1 suppliers',
    data: [
      { id: 'tier1-apex', category: 'Apex Logistics', value: 97 },
      { id: 'tier1-northstar', category: 'NorthStar Freight', value: 95 },
      { id: 'tier1-coastal', category: 'Coastal Courier', value: 93 },
      { id: 'tier1-summit', category: 'Summit Express', value: 96 },
    ],
  },
  {
    id: 'tier-2',
    name: 'Tier 2 suppliers',
    data: [
      { id: 'tier2-apex', category: 'Apex Logistics', value: 93 },
      { id: 'tier2-northstar', category: 'NorthStar Freight', value: 90 },
      { id: 'tier2-coastal', category: 'Coastal Courier', value: 88 },
      { id: 'tier2-summit', category: 'Summit Express', value: 91 },
    ],
  },
  {
    id: 'new-suppliers',
    name: 'New suppliers',
    data: [
      { id: 'new-apex', category: 'Apex Logistics', value: 88 },
      { id: 'new-northstar', category: 'NorthStar Freight', value: 85 },
      { id: 'new-coastal', category: 'Coastal Courier', value: 82 },
      { id: 'new-summit', category: 'Summit Express', value: 86 },
    ],
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/HeatmapChart.md -->

# Heatmap Chart

HeatmapChart shows values in a color-coded grid to reveal patterns across two dimensions.

## Metadata

- Import: `import { HeatmapChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, heatmap, matrix
- Docs: https://plocks.dev/charts/HeatmapChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/HeatmapChart

## Props

- `data` (required): HeatmapCell[] | HeatmapMatrixInput — Heatmap data points or matrix-style input
- `colorScale`: HeatmapColorScaleConfig — Shared color scale. Defaults to a single-hue sequential ramp from the theme.
- `cellSize`: HeatmapCellSize — Explicit cell size overrides
- `gap`: number = 2 — Gap between cells in pixels
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid line configuration
- `legend`: ChartLegend — Legend configuration (often used for color scales)
- `tooltip`: ChartTooltip<HeatmapCell> | HeatmapTooltipOptions — Tooltip configuration or simplified toggle
- `enableCrosshair`: boolean = true — Highlight row/column under the cursor
- `multiTooltip`: boolean = true — Enable aggregated tooltip for multiple cells
- `liveTooltip`: boolean = false — Keep tooltip following the pointer
- `annotations`: any[] — Additional annotations to display
- `maxAnimatedCells`: number = 400 — Maximum number of cells to animate before switching to fast static rendering
- `disableAnimation`: boolean = false — When true, force fast static rendering (no per-cell animation)
- `showCellLabels`: boolean | HeatmapCellVisibilityPredicate | HeatmapLabelDisplayRule — Control whether cell labels render
- `valueFormatter`: HeatmapValueFormatter | HeatmapValueFormatPreset | { preset: HeatmapValueFormatPreset; decimals?: number; suffix?: string } — Custom formatter for cell labels and tooltip values
- `cellCornerRadius`: number = 2 — Corner radius applied to heatmap cells
- `hoverHighlight`: HeatmapHoverHighlightConfig — Customize hover highlight overlays
- `gradientLegend`: HeatmapGradientLegendConfig — Enable and customize gradient legend display
- `accessibilityTable`: HeatmapAccessibilityTableOptions — Render hidden accessible table representation
- `onDataTable`: (payload: HeatmapDataTablePayload) => void — Callback invoked with flattened data table payload

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface HeatmapCell {
  /** Column index or x-axis value for the cell */
  x: number;
  /** Row index or y-axis value for the cell */
  y: number;
  /** Numeric value represented by the cell */
  value: number;
  /** Optional label displayed for the cell */
  label?: string;
  /** Override color used for the cell */
  color?: string;
  /** Arbitrary metadata associated with the cell */
  data?: any;
  /** Pre-formatted value for display */
  formattedValue?: string;
}

export interface HeatmapMatrixInput {
  /** Row labels for the matrix input */
  rows: (string | number)[];
  /** Column labels for the matrix input */
  cols: (string | number)[];
  /** Matrix of values aligned with rows and columns */
  values: (number | null | undefined)[][];
}

export type HeatmapColorScaleConfig = ColorScaleConfig & {
  /** Color applied when the cell value is null */
  nullColor?: string;
};

export interface HeatmapCellSize {
  /** Width of each heatmap cell in pixels */
  width?: number;
  /** Height of each heatmap cell in pixels */
  height?: number;
}

export interface HeatmapTooltipOptions {
  /** Whether the tooltip should be displayed */
  show?: boolean;
  /** Whether to aggregate values when hovering multiple cells */
  aggregate?: boolean;
}

export type HeatmapCellVisibilityPredicate = (input: {
  /** Cell source metadata */
  cell: HeatmapCell;
  /** Rendered cell width */
  width: number;
  /** Rendered cell height */
  height: number;
  /** Share of row contributed by the cell (0-1) */
  rowPercent: number;
  /** Share of column contributed by the cell (0-1) */
  columnPercent: number;
}) => boolean;

export interface HeatmapLabelDisplayRule {
  /** Minimum absolute value required to show the label */
  minValue?: number;
  /** Minimum share of the row required to show the label (0-1) */
  minRowPercent?: number;
  /** Minimum share of the column required to show the label (0-1) */
  minColumnPercent?: number;
  /** Minimum share of the overall total required to show the label (0-1) */
  minOverallPercent?: number;
}

export type HeatmapValueFormatter = (input: {
  /** Raw numeric value */
  value: number;
  /** Cell source metadata */
  cell: HeatmapCell;
  /** Minimum value observed in dataset */
  min: number;
  /** Maximum value observed in dataset */
  max: number;
  /** Sum of all values in the same row */
  rowSum: number;
  /** Sum of all values in the same column */
  columnSum: number;
  /** Sum of all values across the dataset */
  totalSum: number;
  /** Share of row contributed by the cell (0-1) */
  rowPercent: number;
  /** Share of column contributed by the cell (0-1) */
  columnPercent: number;
  /** Share of entire dataset contributed by the cell (0-1) */
  overallPercent: number;
}) => string;
```

## Examples

### Basics

```tsx
import { HeatmapChart } from '@plocks/charts';

import { DAYS, SESSIONS, UTILIZATION } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="Support ticket load"
      subtitle="Average tickets per hour"
      h={320}
      data={{ rows: SESSIONS, cols: DAYS, values: UTILIZATION }}
      cellSize={{ width: 48, height: 44 }}
      gap={4}
      colorScale={{
        domain: [0, 30],
        colors: ['#EBF4FF', '#60A5FA', '#1D4ED8'],
      }}
      xAxis={{
        show: true,
        title: 'Weekday',
      }}
      yAxis={{
        show: true,
        title: 'Shift',
      }}
      grid={{ show: false }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Low', color: '#EBF4FF' },
          { label: 'High', color: '#1D4ED8' },
        ],
      }}
      tooltip={{ show: true }}
    />
  );
}
```

`data.ts`

```ts
export const DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'];

export const SESSIONS = ['Morning', 'Afternoon', 'Evening'];

export const UTILIZATION = [
  [12, 18, 25, 22, 28],
  [8, 14, 19, 24, 20],
  [6, 9, 12, 15, 11],
];
```

### GitHub Contributions

GitHub-style contribution calendar generated with a 7x53 grid (weeks x weekdays) and a 5-step color scale.

```tsx
import { HeatmapChart } from '@plocks/charts';

import { COLUMNS, CONTRIBUTION_MATRIX, PALETTE, WEEKDAY_LABELS } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="Weekly contributions"
      subtitle="GitHub-style activity calendar"
      h={280}
      data={{ rows: WEEKDAY_LABELS, cols: COLUMNS, values: CONTRIBUTION_MATRIX }}
      cellSize={{ width: 12, height: 12 }}
      gap={2}
      colorScale={{ domain: [0, 4], colors: PALETTE }}
      xAxis={{ show: false }}
      yAxis={{
        show: true,
        labelFormatter: (value) => WEEKDAY_LABELS[value] ?? '',
      }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Less', color: PALETTE[0] },
          { label: 'More', color: PALETTE[PALETTE.length - 1] },
        ],
      }}
      tooltip={{ show: true }}
    />
  );
}
```

`data.ts`

```ts
export const WEEKS = 52;

export const WEEKDAY_LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];

export const PALETTE = ['#EBEDF0', '#C6E48B', '#7BC96F', '#239A3B', '#196127'];

export const COLUMNS = Array.from({ length: WEEKS }, (_, index) => `W${index + 1}`);

/** Activity levels (0-4) per weekday/week — deterministic so the demo never shifts. */
export const CONTRIBUTION_MATRIX: number[][] = WEEKDAY_LABELS.map((_, row) =>
  Array.from({ length: WEEKS }, (_, col) => {
    const wave = Math.sin(col / 4) + Math.cos((row + col) / 3);
    const seasonal = Math.cos(col / 12) + row * 0.2;
    const score = wave + seasonal + 2;
    return Math.max(0, Math.min(4, Math.round(score)));
  })
);
```

### Employee Engagement Scores

Visualizes employee engagement survey scores per team across key dimensions to spotlight strengths and low-score focus areas.

```tsx
import { HeatmapChart } from '@plocks/charts';

import { DIMENSIONS, SCORES, TEAMS } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="Employee engagement survey"
      subtitle="Dimension scores (1-5) by team"
      h={360}
      data={{ rows: TEAMS, cols: DIMENSIONS, values: SCORES }}
      cellSize={{ width: 96, height: 48 }}
      gap={4}
      colorScale={{
        domain: [1, 5],
        stops: [
          { value: 2.5, color: '#F97316' },
          { value: 3.5, color: '#FACC15' },
          { value: 4.5, color: '#22C55E' },
        ],
      }}
      valueFormatter={({ value }) => `${value.toFixed(1)} score`}
      showCellLabels
      xAxis={{ show: true, title: 'Engagement dimension' }}
      yAxis={{ show: true, title: 'Team' }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Needs focus (< 3.0)', color: '#F97316' },
          { label: 'Steady (3-4)', color: '#FACC15' },
          { label: 'High confidence (> 4)', color: '#22C55E' },
        ],
      }}
      cellCornerRadius={4}
      hoverHighlight={{ rowOpacity: 0.12, columnOpacity: 0.12 }}
      tooltip={{ show: true, aggregate: false }}
    />
  );
}
```

`data.ts`

```ts
export const TEAMS = ['Product', 'Engineering', 'Sales', 'Customer Success', 'Operations'];

export const DIMENSIONS = ['Leadership', 'Growth', 'Recognition', 'Workload', 'Inclusion', 'Purpose'];

export const SCORES = [
  [4.2, 4.4, 3.9, 3.2, 4.5, 4.1],
  [4.6, 4.1, 3.8, 3.4, 4.3, 3.9],
  [3.8, 3.6, 4.2, 3.1, 3.7, 3.5],
  [4.5, 4.2, 4.0, 3.6, 4.4, 4.1],
  [4.1, 3.9, 3.7, 3.3, 4.0, 3.8],
];
```

### Infrastructure Cpu Utilization

Heatmap of average CPU utilization across infrastructure clusters and daily time blocks, highlighting hotspots that approach saturation bands.

```tsx
import { HeatmapChart } from '@plocks/charts';

import { CLUSTERS, CPU_UTILIZATION, TIME_BLOCKS } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="Infrastructure CPU utilization"
      subtitle="Average utilization (%) across compute clusters"
      h={360}
      data={{ rows: CLUSTERS, cols: TIME_BLOCKS, values: CPU_UTILIZATION }}
      cellSize={{ width: 90, height: 44 }}
      gap={6}
      colorScale={{
        domain: [0, 100],
        stops: [
          { value: 35, color: '#0EA5E9' },
          { value: 60, color: '#FACC15' },
          { value: 80, color: '#F97316' },
          { value: 95, color: '#DC2626' },
        ],
      }}
      valueFormatter={({ value }) => `${Math.round(value)}% utilized`}
      showCellLabels={({ width, height }) => width >= 70 && height >= 38}
      xAxis={{ show: true, title: 'Time block' }}
      yAxis={{ show: true, title: 'Cluster' }}
    grid={{ show: true, style: 'dashed' }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Healthy (< 60%)', color: '#0EA5E9' },
          { label: 'Watch (60-80%)', color: '#FACC15' },
          { label: 'Hotspot (> 80%)', color: '#F97316' },
        ],
      }}
      cellCornerRadius={6}
      hoverHighlight={{ rowOpacity: 0.16, columnOpacity: 0.12 }}
      tooltip={{ show: true, aggregate: false }}
    />
  );
}
```

`data.ts`

```ts
export const CLUSTERS = ['Edge - West', 'Edge - East', 'Core - EU', 'Core - US', 'Core - APAC'];

export const TIME_BLOCKS = ['00:00', '04:00', '08:00', '12:00', '16:00', '20:00'];

export const CPU_UTILIZATION = [
  [28, 44, 57, 65, 61, 43],
  [52, 66, 81, 88, 74, 62],
  [47, 58, 70, 83, 79, 60],
  [35, 49, 63, 72, 68, 55],
  [39, 55, 69, 76, 71, 58],
];
```

### Marketing Email Performance

Tracks marketing email click-through rates by segment and day of week to quickly surface best-performing send windows.

```tsx
import { HeatmapChart } from '@plocks/charts';

import { CLICK_RATES, DAYS, SEGMENTS } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="Email click-through performance"
      subtitle="Daily CTR (%) across audience segments"
      h={320}
      data={{ rows: SEGMENTS, cols: DAYS, values: CLICK_RATES }}
      cellSize={{ width: 80, height: 44 }}
      gap={4}
      colorScale={{
        domain: [10, 45],
        colors: ['#F5F3FF', '#C4B5FD', '#7C3AED'],
      }}
      valueFormatter={({ value }) => `${Math.round(value)}% CTR`}
      showCellLabels={({ cell }) => cell.value >= 32}
      xAxis={{ show: true, title: 'Day of week' }}
      yAxis={{ show: true, title: 'Segment' }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Baseline', color: '#F5F3FF' },
          { label: 'Above average', color: '#C4B5FD' },
          { label: 'Top performing', color: '#7C3AED' },
        ],
      }}
      cellCornerRadius={6}
      hoverHighlight={{ rowOpacity: 0.12, columnOpacity: 0.1 }}
      tooltip={{ show: true, aggregate: false }}
    />
  );
}
```

`data.ts`

```ts
export const SEGMENTS = ['New leads', 'Free trials', 'Customers', 'Churn risk'];

export const DAYS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];

export const CLICK_RATES = [
  [18, 22, 35, 31, 29, 26, 20],
  [24, 28, 38, 36, 33, 30, 27],
  [14, 18, 22, 20, 19, 17, 16],
  [30, 34, 42, 39, 36, 32, 28],
];
```

### Quality Assurance Pass Rates

Shows quality assurance pass rates for each regression suite across release candidates, emphasizing areas that fall below the team’s quality threshold.

```tsx
import { HeatmapChart } from '@plocks/charts';

import { PASS_RATES, RELEASES, SUITES } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="QA pass rates by release"
      subtitle="Regression suites vs. release candidates"
      h={340}
      data={{ rows: SUITES, cols: RELEASES, values: PASS_RATES }}
      cellSize={{ width: 110, height: 48 }}
      gap={4}
      colorScale={{
        domain: [80, 100],
        stops: [
          { value: 85, color: '#F87171' },
          { value: 92, color: '#FBBF24' },
          { value: 98, color: '#34D399' },
        ],
      }}
      valueFormatter={({ value }) => `${Math.round(value)}% pass`}
      showCellLabels
      xAxis={{ show: true, title: 'Release candidate' }}
      yAxis={{ show: true, title: 'Test suite' }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Below target (< 92%)', color: '#F87171' },
          { label: 'At risk (92-97%)', color: '#FBBF24' },
          { label: 'Meets target (> 97%)', color: '#34D399' },
        ],
      }}
      cellCornerRadius={5}
      hoverHighlight={{ rowOpacity: 0.14, columnOpacity: 0.12 }}
      tooltip={{ show: true, aggregate: false }}
    />
  );
}
```

`data.ts`

```ts
export const SUITES = ['Authentication', 'Checkout', 'APIs', 'Mobile app', 'Reporting'];

export const RELEASES = ['RC1', 'RC2', 'RC3', 'RC4'];

export const PASS_RATES = [
  [92, 95, 97, 96],
  [88, 91, 93, 94],
  [94, 96, 98, 99],
  [85, 89, 92, 93],
  [90, 92, 95, 96],
];
```

### Support Backlog Priority

Maps support ticket backlog volume across product modules and priority levels to expose severity hot spots.

```tsx
import { HeatmapChart } from '@plocks/charts';

import { BACKLOG, MODULES, PRIORITIES } from './data';

export function Demo() {
  return (
    <HeatmapChart
      title="Support backlog by module"
      subtitle="Open tickets by severity priority"
      h={360}
      data={{ rows: MODULES, cols: PRIORITIES, values: BACKLOG }}
      cellSize={{ width: 108, height: 48 }}
      gap={6}
      colorScale={{
        type: 'sequential',
        interpolation: 'log',
        domain: [1, 32],
        colors: ['#EFF6FF', '#60A5FA', '#1D4ED8'],
      }}
      valueFormatter={({ value }) => `${value} ${value === 1 ? 'ticket' : 'tickets'}`}
      showCellLabels={({ cell }) => cell.value >= 8}
      xAxis={{ show: true, title: 'Priority' }}
      yAxis={{ show: true, title: 'Product module' }}
      legend={{
        show: true,
        position: 'bottom',
        items: [
          { label: 'Low volume', color: '#EFF6FF' },
          { label: 'Rising load', color: '#60A5FA' },
          { label: 'Critical backlog', color: '#1D4ED8' },
        ],
      }}
      cellCornerRadius={4}
      hoverHighlight={{ rowOpacity: 0.14, columnOpacity: 0.12 }}
      tooltip={{ show: true, aggregate: true }}
    />
  );
}
```

`data.ts`

```ts
export const MODULES = ['Authentication', 'Billing', 'Analytics', 'Messaging', 'Integrations', 'Admin'];

export const PRIORITIES = ['P0', 'P1', 'P2', 'P3'];

export const BACKLOG = [
  [6, 14, 21, 9],
  [2, 11, 18, 13],
  [5, 13, 25, 19],
  [3, 9, 17, 12],
  [1, 7, 15, 10],
  [0, 6, 12, 9],
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/HistogramChart.md -->

# Histogram Chart

HistogramChart groups continuous values into bins to show their distribution.

## Metadata

- Import: `import { HistogramChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, histogram, distribution
- Docs: https://plocks.dev/charts/HistogramChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/HistogramChart

## Props

- `data` (required): number[] — Raw values used to build the histogram
- `bins`: number — Explicit number of bins (overrides method)
- `binMethod`: 'sturges' | 'sqrt' | 'fd' = 'sturges' — Bin selection heuristic
- `showDensity`: boolean = true — Show density (KDE) overlay line
- `bandwidth`: number — Gaussian kernel bandwidth (auto if not provided)
- `density`: boolean = true — Normalize histogram to probability density (area=1)
- `barColor`: ChartFill — Bar fill — a color or a gradient. Defaults to the theme's first palette slot.
- `colorScale`: HistogramColorScale — Color each bin by its position or count. Takes precedence over `barColor`.
- `barOpacity`: number = 0.8 — Opacity for bars (0-1)
- `barStroke`: string — Bar outline color
- `barStrokeWidth`: number — Bar outline width in px (defaults to 1 when `barStroke` is set)
- `densityColor`: string — Density line color. Defaults to the theme's second palette slot.
- `densityThickness`: number = 2 — Density line thickness
- `barRadius`: number = 2 — Rounded bar corners
- `barGap`: number = 0.08 — Gap ratio between bars (0-1)
- `multiTooltip`: boolean = true — Enable multi-series tooltip aggregation
- `liveTooltip`: boolean = true — Keep tooltip following the pointer
- `enableCrosshair`: boolean = true — Enable crosshair indicator
- `tooltip`: ChartTooltip<HistogramBin> — Tooltip configuration
- `valueFormatter`: (count: number, bin: HistogramBin) => string — Custom value formatter for tooltips
- `xAxis`: ChartAxis — Customise X axis presentation
- `yAxis`: ChartAxis — Customise Y axis presentation
- `grid`: ChartGrid — Grid line configuration
- `legend`: ChartLegend — Legend configuration
- `annotations`: ChartAnnotation[] — Render annotation markers (thresholds, targets)
- `rangeHighlights`: Array<{ id: string | number; start: number; end: number; color?: string; opacity?: number; }> — Highlight value ranges with background fills
- `onBinFocus`: (bin: HistogramBinSummary) => void — Called whenever the active bin under the pointer changes
- `onBinBlur`: (bin: HistogramBinSummary | null) => void — Called when focus leaves the current bin

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export type HistogramColorScale =
  | (ColorScaleConfig & {
      /**
       * What the scale reads from each bin:
       * - `'x'` (default): the bin's midpoint on the x axis — color by *where* values fall.
       * - `'count'`: the bin's sample count — color by *how many*.
       */
      by?: 'x' | 'count';
    })
  | ((bin: HistogramBinSummary) => string | undefined);

export interface HistogramBin {
  /** Inclusive lower bound of the bin */
  start: number;
  /** Exclusive upper bound of the bin */
  end: number;
  /** Number of samples that fell into the bin */
  count: number;
  /** Probability density represented by the bin */
  density: number;
}

export interface HistogramBinSummary extends HistogramBin {
  /** Zero-based index for the bin */
  index: number;
  /** Arithmetic midpoint between start and end */
  midpoint: number;
  /** Width of the bin interval */
  width: number;
  /** Running total count including this bin */
  cumulativeCount: number;
  /** Running density integral including this bin */
  cumulativeDensity: number;
  /** Cumulative density normalized to 0-1 */
  cumulativeDensityRatio: number;
  /** Percentile rank represented by the cumulative count */
  percentile: number;
}
```

## Examples

### Basics

Bins session durations with a density curve. The bars take their color implicitly from the theme's first palette slot; no color props are set.

```tsx
import { HistogramChart } from '@plocks/charts';

import { SESSION_DURATIONS } from './data';

export function Demo() {
	return (
		<HistogramChart
			title="Session duration distribution"
			subtitle="Product analytics cohort"
			h={280}
			data={SESSION_DURATIONS}
			bins={10}
			showDensity
			densityThickness={3}
			densityColor="#12B886"
			barGap={0.15}
			tooltip={{
				show: true,
				formatter: (bin) => `${bin.count} sessions between ${bin.start}-${bin.end} min`,
			}}
			valueFormatter={(count, bin) => `${count} • ${bin.density.toFixed(2)} pdf`}
			enableCrosshair
			liveTooltip
		/>
	);
}
```

`data.ts`

```ts
export const SESSION_DURATIONS = [
	4, 6, 7, 8, 9, 9, 10, 11, 11, 12, 12, 12, 13, 13, 14, 14, 14, 15, 16, 16,
	16, 17, 18, 18, 18, 19, 20, 20, 22, 24, 25,
];
```

### Threshold coloring

**Key settings** - `colorScale={{ type: 'threshold', thresholds: [2.5, 3.2] }}` splits bins into three bands by where they sit on the x axis. A bin whose midpoint lands on a breakpoint takes the band above it. - Band colors are status colors (good, warning, critical), and `labels` gives each band a legend entry, so a band's meaning never rides on color alone.

```tsx
import { useState } from 'react';
import { View, Text } from 'react-native';
import { HistogramChart, HistogramBinSummary } from '@plocks/charts';

import { BREACH_LIMIT, LOAD_TIMES, SLO_TARGET } from './data';

export function Demo() {
  const [focusedBin, setFocusedBin] = useState<HistogramBinSummary | null>(null);

  return (
  <View style={{ width: '100%', maxWidth: '100%' }}>
      <HistogramChart
        title="Page load time distribution"
        subtitle="Bins colored by SLO status"
        h={340}
        data={LOAD_TIMES}
        bins={14}
        density={false}
        showDensity={false}
        barOpacity={0.9}
        colorScale={{
          type: 'threshold',
          by: 'x',
          thresholds: [SLO_TARGET, BREACH_LIMIT],
          colors: ['#0ca30c', '#fab219', '#d03b3b'],
          labels: ['Within SLO', 'At risk', 'Breaching'],
        }}
        legend={{ show: true }}
        annotations={[
          {
            id: 'slo-target',
            shape: 'vertical-line',
            x: SLO_TARGET,
            color: '#71717A',
            label: 'SLO 2.5s',
          },
        ]}
        xAxis={{
          title: 'Page load time (seconds)',
          labelFormatter: (value) => `${value.toFixed(1)}s`,
        }}
        yAxis={{
          title: 'Page views',
        }}
        grid={{ show: true }}
        tooltip={{
          show: true,
          formatter: (bin) => `${bin.count} page views between ${bin.start.toFixed(1)}–${bin.end.toFixed(1)}s`,
        }}
        valueFormatter={(count) => `${count} views`}
        onBinFocus={(summary) => setFocusedBin(summary)}
        onBinBlur={() => setFocusedBin(null)}
      />
  <View style={{ paddingHorizontal: 4, marginTop: 12 }}>
        {focusedBin ? (
          <Text style={{ fontSize: 13, color: '#3F3F46' }}>
            {`${focusedBin.count} loads between ${focusedBin.start.toFixed(2)}–${focusedBin.end.toFixed(2)}s · percentile ${(focusedBin.percentile * 100).toFixed(1)}% · cumulative ${(focusedBin.cumulativeDensityRatio * 100).toFixed(1)}% density`}
          </Text>
        ) : (
          <Text style={{ fontSize: 13, color: '#52525B' }}>
            Hover a bar to highlight its percentile and cumulative share of traffic.
          </Text>
        )}
      </View>
    </View>
  );
}
```

`data.ts`

```ts
export const LOAD_TIMES = [
  1.2, 1.3, 1.4, 1.5, 1.5, 1.6, 1.6, 1.7, 1.7, 1.8, 1.8, 1.9,
  1.9, 2.0, 2.0, 2.1, 2.1, 2.2, 2.2, 2.3, 2.3, 2.4, 2.4, 2.5,
  2.5, 2.6, 2.6, 2.7, 2.7, 2.8, 2.8, 2.9, 2.9, 3.0, 3.1, 3.1,
  3.2, 3.3, 3.3, 3.4, 3.4, 3.5, 3.6, 3.7, 3.8, 3.9, 4.0, 2.2,
  1.8, 1.9, 2.0, 2.1, 2.3, 2.4, 2.5, 2.7, 2.8, 2.9,
];

export const SLO_TARGET = 2.5;

// Loads past this are breaching, not just at risk.
export const BREACH_LIMIT = 3.2;
```

### Diverging from a target

**Key settings** - `colorScale={{ type: 'diverging', midpoint: 3.9, colors: [low, high] }}` colors bins by which side of the target they fall on. A neutral gray middle is added automatically. - The arms are symmetric: bins the same distance from the midpoint get the same intensity, even though the data reaches further below the target than above it.

```tsx
import { HistogramChart } from '@plocks/charts';

import { BATTERY_VOLTAGES, REPLACEMENT_THRESHOLD, TARGET_VOLTAGE } from './data';

export function Demo() {
  return (
    <HistogramChart
      title="Sensor battery voltage after firmware upgrade"
      subtitle="Diverging from the 3.9V target: red runs low, blue runs high"
      h={320}
      data={BATTERY_VOLTAGES}
      bins={12}
      binMethod="sturges"
      density={false}
      showDensity={false}
      barOpacity={0.9}
      colorScale={{
        type: 'diverging',
        midpoint: TARGET_VOLTAGE,
        colors: ['#e34948', '#2a78d6'],
      }}
      annotations={[
        {
          id: 'replacement-line',
          shape: 'vertical-line',
          x: REPLACEMENT_THRESHOLD,
          color: '#e34948',
          label: 'Replace below 3.5V',
        },
        {
          id: 'target-line',
          shape: 'vertical-line',
          x: TARGET_VOLTAGE,
          color: '#71717A',
          label: 'Target 3.9V',
        },
      ]}
      xAxis={{
        title: 'Voltage (V)',
        labelFormatter: (value) => `${value.toFixed(2)}V`,
      }}
      yAxis={{
        title: 'Sensors',
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} sensors between ${bin.start.toFixed(2)}–${bin.end.toFixed(2)}V`,
      }}
      valueFormatter={(count) => `${count} sensors`}
    />
  );
}
```

`data.ts`

```ts
export const BATTERY_VOLTAGES = [
  3.42, 3.44, 3.45, 3.46, 3.48, 3.49, 3.51, 3.53, 3.54, 3.55,
  3.57, 3.58, 3.59, 3.60, 3.61, 3.62, 3.63, 3.64, 3.65, 3.66,
  3.68, 3.70, 3.71, 3.72, 3.73, 3.74, 3.76, 3.78, 3.79, 3.80,
  3.82, 3.83, 3.84, 3.85, 3.86, 3.88, 3.89, 3.90, 3.92, 3.94,
  3.96, 3.98, 4.00, 4.02, 4.04, 4.06, 4.08, 4.10, 4.12, 4.15,
];

export const REPLACEMENT_THRESHOLD = 3.5;

export const TARGET_VOLTAGE = 3.9;
```

### Sequential shading by count

**Key settings** - `colorScale={{ type: 'sequential', by: 'count' }}` shades each bin by how many people it holds instead of by where it sits (`by: 'x'`, the default). - With no `colors`, the ramp is built from the bar color itself: a tint that recedes toward the chart surface at the low end, a deeper shade at the high end. On a dark theme the same rule flips the anchor automatically.

```tsx
import { HistogramChart } from '@plocks/charts';

import { TENURE_YEARS, medianTenure } from './data';

export function Demo() {
  return (
    <HistogramChart
      title="Employee tenure distribution"
      subtitle="Shaded by headcount: bolder bins hold more people"
      h={320}
      data={TENURE_YEARS}
      bins={12}
      binMethod="sqrt"
      showDensity
      densityThickness={2.5}
      barOpacity={0.9}
      colorScale={{ type: 'sequential', by: 'count' }}
      annotations={[
        {
          id: 'median-tenure',
          shape: 'vertical-line',
          x: Number(medianTenure.toFixed(2)),
          color: '#71717A',
          label: `Median ${medianTenure.toFixed(1)} yrs`,
        },
      ]}
      xAxis={{
        title: 'Tenure (years)',
        labelFormatter: (value) => `${value.toFixed(1)} yrs`,
      }}
      yAxis={{
        title: 'Probability density',
        labelFormatter: (value) => value.toFixed(2),
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} teammates between ${bin.start.toFixed(1)}–${bin.end.toFixed(1)} years`,
      }}
      valueFormatter={(count, bin) => `${count} people · pdf ${bin.density.toFixed(3)}`}
    />
  );
}
```

`data.ts`

```ts
export const TENURE_YEARS = [
  0.3, 0.5, 0.7, 0.8, 1.1, 1.3, 1.5, 1.8, 2.1, 2.3,
  2.8, 3.0, 3.2, 3.5, 3.8, 4.1, 4.4, 4.7, 5.0, 5.3,
  5.7, 6.0, 6.3, 6.8, 7.1, 7.4, 7.8, 8.2, 8.6, 9.0,
  9.5, 10.0, 10.5, 11.0, 11.6, 12.2, 12.8, 13.4, 14.0, 14.7,
];

export const medianTenure = (() => {
  const sorted = [...TENURE_YEARS].sort((a, b) => a - b);
  const mid = Math.floor(sorted.length / 2);
  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
})();
```

### Gradient fill

**Key settings** - `barColor` accepts a gradient as well as a color: `{ angle, stops, extent }`. `angle` is in degrees; 90 runs top to bottom. - `extent: 'plot'` lays one gradient across the whole plot, so each bar shows the slice behind it and taller bins reach the deeper end. The default, `extent: 'mark'`, gives every bar the full gradient.

```tsx
import { HistogramChart } from '@plocks/charts';

import { DELIVERY_MINUTES } from './data';

export function Demo() {
  return (
    <HistogramChart
      title="Delivery time distribution"
      subtitle="One gradient spans the plot, so taller bins reach the deeper end"
      h={320}
      data={DELIVERY_MINUTES}
      bins={14}
      density={false}
      showDensity={false}
      barOpacity={1}
      barRadius={4}
      barColor={{
        angle: 90,
        extent: 'plot',
        stops: [
          { offset: 0, color: '#1c5cab' },
          { offset: 1, color: '#86b6ef' },
        ],
      }}
      xAxis={{
        title: 'Minutes from order to door',
        labelFormatter: (value) => `${value.toFixed(0)}m`,
      }}
      yAxis={{
        title: 'Orders',
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} orders in ${bin.start.toFixed(0)}–${bin.end.toFixed(0)} min`,
      }}
      valueFormatter={(count) => `${count} orders`}
    />
  );
}
```

`data.ts`

```ts
export const DELIVERY_MINUTES = [
  18, 21, 22, 24, 25, 26, 26, 27, 28, 28,
  29, 29, 30, 30, 30, 31, 31, 32, 32, 32,
  33, 33, 33, 34, 34, 34, 35, 35, 35, 35,
  36, 36, 36, 37, 37, 38, 38, 39, 39, 40,
  41, 41, 42, 43, 44, 45, 46, 48, 50, 52,
  55, 58, 62, 67, 74,
];
```

### Outlined bars

**Key settings** - A single explicit `barColor` at `barOpacity={0.18}`, outlined with `barStroke` and `barStrokeWidth`. - The density line uses the same accent, so the chart reads as one series.

```tsx
import { HistogramChart } from '@plocks/charts';

import { RESPONSE_HOURS } from './data';

const ACCENT = '#199e70';

export function Demo() {
  return (
    <HistogramChart
      title="Support first-response time"
      subtitle="Outlined bars: a faint fill under a solid stroke"
      h={320}
      data={RESPONSE_HOURS}
      bins={12}
      barColor={ACCENT}
      barOpacity={0.18}
      barStroke={ACCENT}
      barStrokeWidth={1.5}
      barRadius={6}
      barGap={0.16}
      showDensity
      densityColor={ACCENT}
      densityThickness={2}
      xAxis={{
        title: 'Hours to first response',
        labelFormatter: (value) => `${value.toFixed(0)}h`,
      }}
      yAxis={{
        title: 'Probability density',
        labelFormatter: (value) => value.toFixed(2),
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} tickets answered in ${bin.start.toFixed(1)}–${bin.end.toFixed(1)}h`,
      }}
      valueFormatter={(count) => `${count} tickets`}
    />
  );
}
```

`data.ts`

```ts
export const RESPONSE_HOURS = [
  0.4, 0.6, 0.8, 0.9, 1.1, 1.2, 1.3, 1.5, 1.6, 1.8,
  1.9, 2.0, 2.1, 2.2, 2.4, 2.5, 2.6, 2.8, 3.0, 3.1,
  3.3, 3.5, 3.6, 3.8, 4.0, 4.3, 4.5, 4.8, 5.1, 5.4,
  5.8, 6.2, 6.7, 7.3, 8.0, 8.8, 9.7, 10.9, 12.4,
];
```

### Themed with a brand palette

**Key settings** - The chart sets no color props. Bars take palette slot 1 and the density line takes slot 2 from the nearest `ChartThemeProvider`. - A nested provider re-themes only its own subtree: it inherits text, grid and surface colors from the app's theme and overrides just `accentPalette`.

```tsx
import { ChartThemeProvider, HistogramChart } from '@plocks/charts';

import { BASKET_TOTALS, BRAND_PALETTE } from './data';

export function Demo() {
  // No color props on the chart: bars take palette slot 1 and the density line
  // slot 2 from the nearest ChartThemeProvider. A nested provider re-themes just
  // its own subtree and inherits everything else from the app's theme.
  return (
    <ChartThemeProvider value={{ colors: { accentPalette: BRAND_PALETTE } }}>
      <HistogramChart
        title="Checkout basket size"
        subtitle="Colored entirely by the surrounding theme's palette"
        h={320}
        data={BASKET_TOTALS}
        bins={12}
        showDensity
        legend={{ show: true }}
        xAxis={{
          title: 'Basket total (USD)',
          labelFormatter: (value) => `$${value.toFixed(0)}`,
        }}
        yAxis={{
          title: 'Probability density',
          labelFormatter: (value) => value.toFixed(3),
        }}
        grid={{ show: true }}
        tooltip={{
          show: true,
          formatter: (bin) => `${bin.count} baskets between $${bin.start.toFixed(0)}–$${bin.end.toFixed(0)}`,
        }}
        valueFormatter={(count) => `${count} baskets`}
      />
    </ChartThemeProvider>
  );
}
```

`data.ts`

```ts
export const BASKET_TOTALS = [
  12, 18, 22, 25, 27, 29, 31, 33, 34, 36,
  37, 38, 40, 41, 42, 43, 44, 45, 46, 47,
  48, 49, 50, 51, 52, 54, 55, 57, 58, 60,
  62, 64, 66, 69, 72, 76, 80, 85, 91, 98,
  106, 115, 128,
];

// Two slots, validated for 3:1 contrast and CVD separation on light and dark surfaces.
export const BRAND_PALETTE = ['#7c5cdb', '#d9731a'];
```

### Contract Length Retention

```tsx
import { HistogramChart } from '@plocks/charts';

import { CONTRACT_LENGTHS, median } from './data';

export function Demo() {
  return (
    <HistogramChart
      title="Customer contract length distribution"
      subtitle="Used to calibrate retention and renewal strategy"
      h={320}
      data={CONTRACT_LENGTHS}
      bins={12}
      binMethod="sturges"
      density={false}
      showDensity={false}
      barOpacity={0.82}
      rangeHighlights={[{ id: 'core-subscription', start: 12, end: 24, color: '#22C55E', opacity: 0.14 }]}
      annotations={[
        {
          id: 'one-year',
          shape: 'vertical-line',
          x: 12,
          color: '#22C55E',
          label: '1 year',
        },
        {
          id: 'two-year',
          shape: 'vertical-line',
          x: 24,
          color: '#15803D',
          label: '2 years',
        },
        {
          id: 'median',
          shape: 'vertical-line',
          x: median,
          color: '#F97316',
          label: `Median ${median} mo`,
        },
      ]}
      xAxis={{
        title: 'Contract length (months)',
      }}
      yAxis={{
        title: 'Customer accounts',
        labelFormatter: (value) => `${value.toFixed(0)}`,
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} accounts between ${bin.start.toFixed(0)}–${bin.end.toFixed(0)} months`,
      }}
      valueFormatter={(count) => `${count} customers`}
    />
  );
}
```

`data.ts`

```ts
export const CONTRACT_LENGTHS = [
  6, 6, 6, 7, 8, 9, 9, 10, 10, 11,
  12, 12, 12, 12, 13, 14, 14, 15, 15, 16,
  17, 18, 18, 18, 18, 19, 20, 20, 21, 21,
  22, 24, 24, 24, 24, 25, 26, 26, 27, 28,
  30, 30, 30, 32, 32, 33, 34, 36, 36, 36,
  38, 40, 42, 45, 48,
];

export const sortedLengths = [...CONTRACT_LENGTHS].sort((a, b) => a - b);

export const median = sortedLengths[Math.floor(sortedLengths.length / 2)];
```

### Transaction Amount Fraud

```tsx
import { HistogramChart } from '@plocks/charts';

import { REVIEW_THRESHOLD, TRANSACTION_AMOUNTS } from './data';

export function Demo() {
  return (
    <HistogramChart
      title="Transaction amount distribution"
      subtitle="Identifying anomalous high-value purchases"
      h={320}
      data={TRANSACTION_AMOUNTS}
      bins={16}
      binMethod="fd"
      showDensity
      barOpacity={0.76}
      densityColor="#0EA5E9"
      rangeHighlights={[
        { id: 'high-risk-window', start: 900, end: 1400, color: '#EF4444', opacity: 0.12 },
      ]}
      annotations={[
        {
          id: 'manual-review',
          shape: 'vertical-line',
          x: REVIEW_THRESHOLD,
          color: '#DC2626',
          label: 'Manual review starts',
        },
      ]}
      xAxis={{
        title: 'Transaction amount (USD)',
        labelFormatter: (value) => `$${value.toFixed(0)}`,
      }}
      yAxis={{
        title: 'Probability density',
        labelFormatter: (value) => value.toFixed(3),
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} orders between $${bin.start.toFixed(0)}–$${bin.end.toFixed(0)}`,
      }}
      valueFormatter={(count, bin) => `${count} orders · pdf ${bin.density.toFixed(3)}`}
    />
  );
}
```

`data.ts`

```ts
export const TRANSACTION_AMOUNTS = [
  120, 135, 142, 150, 155, 160, 162, 168, 170, 174,
  180, 184, 188, 192, 198, 205, 210, 218, 225, 230,
  240, 245, 250, 260, 270, 280, 295, 310, 330, 340,
  360, 380, 395, 410, 430, 455, 480, 500, 520, 540,
  560, 580, 600, 620, 640, 660, 690, 720, 750, 780,
  820, 860, 890, 930, 970, 1020, 1080, 1150, 1220, 1310,
];

export const REVIEW_THRESHOLD = 750;
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/LineChart.md -->

# Line Chart

Basic line chart visualization component.

## Metadata

- Import: `import { LineChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, line, timeseries
- Docs: https://plocks.dev/charts/LineChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/LineChart

## Props

- `data`: ChartDataPoint[] — Data points (single series) or array of series (multiseries)
- `series`: LineChartSeries[] — Multiple data series
- `lineColor`: string — Line color (for single series)
- `lineThickness`: number = 2 — Line thickness (for single series)
- `lineStyle`: 'solid' | 'dashed' | 'dotted' = 'solid' — Line style (for single series)
- `showPoints`: boolean = true — Show data points (for single series)
- `pointSize`: number = 4 — Point size (for single series)
- `pointColor`: string — Point color (for single series)
- `smooth`: boolean = false — Smooth curve
- `fill`: boolean = false — Fill area under line
- `fillColor`: ChartFill — Area fill. A color fades from `fillOpacity` at the line to transparent at the baseline; a gradient is used exactly as given.
- `fillOpacity`: number = 0.3 — Fill opacity
- `areaFillMode`: 'single' | 'series' = 'single' — How to distribute fill across series when multiple are present
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid configuration
- `legend`: ChartLegend — Legend configuration
- `tooltip`: ChartTooltip<ChartDataPoint> — Tooltip configuration
- `animation`: ChartAnimation — Animation configuration
- `enableCrosshair`: boolean — Show a vertical crosshair that follows the nearest point
- `enableSeriesToggle`: boolean — Enable toggling series visibility from legend
- `liveTooltip`: boolean — Update tooltip continuously while moving (not just on press)
- `multiTooltip`: boolean — Show multi-series aggregated tooltip aligned to crosshair
- `enablePanZoom`: boolean — Enable pan and pinch zoom interactions
- `zoomMode`: 'x' | 'y' | 'both' — Which axes can zoom
- `minZoom`: number — Minimum zoom factor relative to original domain (e.g. 0.1 = 10%)
- `onDomainChange`: (xDomain: [number, number], yDomain: [number, number]) => void — Callback when visible data domain changes
- `enableWheelZoom`: boolean — Enable wheel zoom on web
- `wheelZoomStep`: number — Wheel zoom step factor (default 0.1)
- `invertWheelZoom`: boolean — Invert wheel zoom direction
- `resetOnDoubleTap`: boolean — Double-tap (or double-click on web) resets zoom
- `clampToInitialDomain`: boolean — Clamp pan/zoom so domains never exceed original data bounds
- `invertPinchZoom`: boolean — Invert pinch gesture direction (scale grows when fingers move closer)
- `disableAnimations`: boolean — Disable all Reanimated-driven animations (debug / perf fallback)
- `decimationThreshold`: number — Apply LTOB data decimation above this point count
- `xScaleType`: 'linear' | 'log' | 'time' — X axis scale type
- `yScaleType`: 'linear' | 'log' | 'time' — Y axis scale type
- `enableBrushZoom`: boolean — Enable shift+drag brush to zoom (web)
- `annotations`: ChartAnnotation[] — Optional chart annotations/markers

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface LineChartSeries {
  /** Unique identifier for the series */
  id?: string | number;
  /** Series name */
  name?: string;
  /** Data points for this series */
  data: ChartDataPoint[];
  /** Line color for this series */
  color?: string;
  /** Line thickness for this series */
  thickness?: number;
  /** Optional alias for line thickness */
  lineThickness?: number;
  /** Line style for this series */
  style?: 'solid' | 'dashed' | 'dotted';
  /** Optional alias for line style */
  lineStyle?: 'solid' | 'dashed' | 'dotted';
  /** Show points for this series */
  showPoints?: boolean;
  /** Point size for this series */
  pointSize?: number;
  /** Point color for this series */
  pointColor?: string;
  /** Whether this series is visible */
  visible?: boolean;
  /** Custom metadata for interactions */
  metadata?: any;
  /** Override fill visibility for area charts */
  areaFill?: boolean;
  /**
   * Area fill for this series. A color fades from `fillOpacity` at the line to
   * transparent at the baseline; a gradient is used exactly as given.
   */
  fillColor?: ChartFill;
  /** Optional fill opacity for the series area */
  fillOpacity?: number;
  /** Override smooth setting per series */
  smooth?: boolean;
}
```

## Examples

### Basics

Simple random data line chart with title.

```tsx
import { LineChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <LineChart
      // title="Monthly active customers"
      // subtitle="FY25"
      h={320}
      series={SERIES}
      xAxis={{
        show: true,
        title: 'Month',
        labelFormatter: (value) => `M${value}`,
      }}
      yAxis={{
        show: true,
        title: 'Customers (thousands)',
        labelFormatter: (value) => `${value}`,
      }}
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom' }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.y}k customers in month ${point.x}`,
      }}
      enableCrosshair
      multiTooltip
      liveTooltip
      enablePanZoom
      zoomMode="x"
      minZoom={0.3}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'north-america',
    name: 'North America',
    data: [
      { x: 1, y: 120 },
      { x: 2, y: 138 },
      { x: 3, y: 152 },
      { x: 4, y: 167 },
      { x: 5, y: 176 },
      { x: 6, y: 189 },
      { x: 7, y: 205 },
      { x: 8, y: 220 },
      { x: 9, y: 232 },
      { x: 10, y: 246 },
      { x: 11, y: 260 },
      { x: 12, y: 278 },
    ],
  },
  {
    id: 'emea',
    name: 'EMEA',
    data: [
      { x: 1, y: 96 },
      { x: 2, y: 108 },
      { x: 3, y: 117 },
      { x: 4, y: 126 },
      { x: 5, y: 134 },
      { x: 6, y: 142 },
      { x: 7, y: 150 },
      { x: 8, y: 158 },
      { x: 9, y: 168 },
      { x: 10, y: 175 },
      { x: 11, y: 182 },
      { x: 12, y: 191 },
    ],
  },
];
```

### Smooth Area

Smoothed dual-series line chart with gradient fill and custom legend.

```tsx
import { LineChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <LineChart
      title="Revenue trajectory"
      subtitle="Smoothed forecast vs. actuals"
      h={320}
      series={SERIES}
      smooth
      fill
      showPoints={false}
      lineThickness={3}
      fillOpacity={0.28}
      enableCrosshair
      multiTooltip
      liveTooltip
      enablePanZoom
      zoomMode="x"
      minZoom={0.35}
      legend={{ show: true, position: 'top', align: 'center' }}
      grid={{ show: true, style: 'dashed' }}
      xAxis={{
        show: true,
        title: 'Month',
        labelFormatter: (value) => `M${value}`,
      }}
      yAxis={{
        show: true,
        title: 'Revenue (USD thousands)',
        labelFormatter: (value) => `$${Math.round(value)}`,
      }}
      tooltip={{
        show: true,
        formatter: (point) => `$${point.y.toLocaleString()}k in month ${point.x}`,
      }}
      annotations={[
        {
          id: 'midyear-target',
          shape: 'vertical-line',
          x: 6,
          label: 'Mid-year target',
          color: '#6366F1',
          dashArray: [6, 6],
        },
      ]}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'projected-revenue',
    name: 'Projected revenue',
    data: [
      { x: 1, y: 940 },
      { x: 2, y: 980 },
      { x: 3, y: 1020 },
      { x: 4, y: 1090 },
      { x: 5, y: 1175 },
      { x: 6, y: 1260 },
      { x: 7, y: 1340 },
      { x: 8, y: 1415 },
      { x: 9, y: 1490 },
      { x: 10, y: 1575 },
      { x: 11, y: 1660 },
      { x: 12, y: 1740 },
    ],
  },
  {
    id: 'actual-revenue',
    name: 'Actual revenue',
    data: [
      { x: 1, y: 910 },
      { x: 2, y: 960 },
      { x: 3, y: 1005 },
      { x: 4, y: 1088 },
      { x: 5, y: 1150 },
      { x: 6, y: 1225 },
      { x: 7, y: 1312 },
      { x: 8, y: 1384 },
      { x: 9, y: 1478 },
      { x: 10, y: 1532 },
      { x: 11, y: 1610 },
      { x: 12, y: 1705 },
    ],
  },
];
```

### Time Series

Time-series interaction example with brush zoom and custom tooltip formatting.

```tsx
import { LineChart } from '@plocks/charts';

import { SERIES, formatter } from './data';

export function Demo() {
  return (
    <LineChart
      title="Web analytics"
      subtitle="Sessions and goals over time"
      h={360}
      series={SERIES}
      xScaleType="time"
      enableCrosshair
      multiTooltip
      liveTooltip
      enablePanZoom
      enableBrushZoom
      zoomMode="x"
      minZoom={0.25}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      grid={{ show: true, style: 'dotted' }}
      xAxis={{
        show: true,
        title: 'Month',
        labelFormatter: (value) => formatter.format(new Date(value)),
      }}
      yAxis={{
        show: true,
        title: 'Count',
        labelFormatter: (value) => value.toLocaleString(),
      }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const label = formatter.format(new Date(point.x));
          return `${label}: ${point.y.toLocaleString()} ${point.id === 'goal-completions' ? 'goals' : 'sessions'}`;
        },
      }}
      annotations={[
        {
          id: 'holiday-campaign',
          shape: 'range',
          x1: Date.UTC(2024, 10, 1),
          x2: Date.UTC(2024, 11, 31),
          label: 'Holiday campaign',
          color: '#0EA5E9',
          backgroundColor: 'rgba(14,165,233,0.12)',
        },
      ]}
    />
  );
}
```

`data.ts`

```ts
export const date = (month: number, value: number) => ({ x: Date.UTC(2024, month, 1), y: value });

export const SERIES = [
  {
    id: 'sessions',
    name: 'Sessions',
    data: [
      date(0, 4200),
      date(1, 4680),
      date(2, 5120),
      date(3, 5560),
      date(4, 6025),
      date(5, 6480),
      date(6, 7020),
      date(7, 7385),
      date(8, 7810),
      date(9, 8050),
      date(10, 8320),
      date(11, 8585),
    ],
  },
  {
    id: 'goal-completions',
    name: 'Goal completions',
    data: [
      date(0, 520),
      date(1, 560),
      date(2, 595),
      date(3, 640),
      date(4, 705),
      date(5, 760),
      date(6, 812),
      date(7, 860),
      date(8, 905),
      date(9, 948),
      date(10, 980),
      date(11, 1015),
    ],
  },
];

export const formatter = new Intl.DateTimeFormat('en-US', { month: 'short', year: '2-digit' });
```

### Gradient area fill

**Key settings** - `fillColor` accepts a gradient as well as a color. A plain color fades from `fillOpacity` at the line to transparent at the baseline; a gradient is used exactly as given. - `extent: 'plot'` spans one gradient across the whole plot, so peaks reach the deep end while quiet hours stay pale. Set `fillColor` on an individual series to give each area its own gradient.

```tsx
import { LineChart } from '@plocks/charts';

import { CONCURRENT_VIEWERS } from './data';

export function Demo() {
  return (
    <LineChart
      title="Concurrent viewers"
      subtitle="One gradient spans the plot: the evening peak reaches the deepest blue"
      h={320}
      data={CONCURRENT_VIEWERS}
      smooth
      fill
      showPoints={false}
      lineThickness={2.5}
      fillColor={{
        angle: 90,
        extent: 'plot',
        stops: [
          { offset: 0, color: '#1c5cab', opacity: 0.9 },
          { offset: 1, color: '#86b6ef', opacity: 0.12 },
        ],
      }}
      grid={{ show: true }}
      xAxis={{
        show: true,
        title: 'Hour',
        labelFormatter: (value) => `${String(Math.round(value)).padStart(2, '0')}:00`,
      }}
      yAxis={{
        show: true,
        title: 'Viewers (thousands)',
        labelFormatter: (value) => `${Math.round(value)}k`,
      }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.y}k viewers at ${String(point.x).padStart(2, '0')}:00`,
      }}
    />
  );
}
```

`data.ts`

```ts
// Concurrent viewers (thousands) across a 24-hour broadcast day.
export const CONCURRENT_VIEWERS = [
  { x: 0, y: 18 }, { x: 1, y: 14 }, { x: 2, y: 11 }, { x: 3, y: 9 },
  { x: 4, y: 8 }, { x: 5, y: 10 }, { x: 6, y: 16 }, { x: 7, y: 24 },
  { x: 8, y: 31 }, { x: 9, y: 28 }, { x: 10, y: 26 }, { x: 11, y: 29 },
  { x: 12, y: 38 }, { x: 13, y: 35 }, { x: 14, y: 30 }, { x: 15, y: 32 },
  { x: 16, y: 37 }, { x: 17, y: 45 }, { x: 18, y: 58 }, { x: 19, y: 72 },
  { x: 20, y: 81 }, { x: 21, y: 76 }, { x: 22, y: 54 }, { x: 23, y: 33 },
];
```

### Zoom & pan

Interactive zoom and pan on desktop web. **Scroll** the wheel over the plot to zoom, **drag** to pan, hold **Shift and drag** a box to zoom into a region, and **double-click** to reset. Note that wheel zoom requires both `enableWheelZoom` **and** `enablePanZoom` — the wheel handler is a no-op when panning is disabled. `zoomMode="x"` constrains zooming to the time axis.

```tsx
import { LineChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <LineChart
      title="Product engagement"
      subtitle="Scroll to zoom · drag to pan · Shift-drag to box-zoom · double-click to reset"
      h={340}
      series={SERIES}
      xAxis={{ show: true, title: 'Week', labelFormatter: (value) => `W${value}` }}
      yAxis={{ show: true, title: 'Count' }}
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom' }}
      tooltip={{ show: true }}
      enableCrosshair
      multiTooltip
      liveTooltip
      // Zoom & pan gestures (desktop web):
      enablePanZoom          // drag to pan (and gates wheel zoom)
      enableWheelZoom        // scroll wheel to zoom
      enableBrushZoom        // Shift + drag a box to zoom into it
      resetOnDoubleTap       // double-click to reset the view
      zoomMode="x"           // zoom the x-axis (time) only
      minZoom={0.15}
    />
  );
}
```

`data.ts`

```ts
export // A denser series so zooming reveals detail. Two years of weekly-ish points.
const makeSeries = (id: string, name: string, color: string, base: number, amp: number, phase: number) => ({
  id,
  name,
  color,
  data: Array.from({ length: 104 }, (_, i) => ({
    x: i,
    y: Math.round(
      base +
        amp * Math.sin(i / 6 + phase) +
        (i / 104) * amp * 1.5 +
        Math.sin(i / 2.3) * amp * 0.25
    ),
  })),
});

export const SERIES = [
  makeSeries('sessions', 'Sessions', '#4C6EF5', 420, 90, 0),
  makeSeries('signups', 'Signups', '#20C997', 180, 55, 1.2),
];
```

### Arr Progress Forecast

**Story focus** - Compares current ARR performance for each GTM region against the latest forecast trajectory. - Highlights the forward-looking window so teams can inspect upside or downside risk. - Uses matching dashed overlays to keep forecast lines aligned with their actual counterparts. **Key settings** - Provides paired solid and dashed series per region, sharing colors for quick comparison. - Applies a range annotation to tint the forecast horizon on the right side of the chart. - Enables multi-series tooltip formatting with ARR values expressed in millions.

```tsx
import { LineChart } from '@plocks/charts';

import { FORECAST_END, FORECAST_START, MONTH_LABELS, SERIES } from './data';

export function Demo() {
  return (
    <LineChart
      title="ARR Progression vs. Forecast"
      subtitle="GTM regions actualized ARR with forward-looking plans"
      h={440}
      series={SERIES}
      smooth
      showPoints
      pointSize={5}
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const month = MONTH_LABELS[Math.round(point.x)];
          const region = point.data?.region?.toUpperCase?.() ?? 'Region';
          const label = point.data?.type === 'forecast' ? 'Forecast' : 'Actual';
          return `${month} • ${region} ${label}: $${point.y.toFixed(0)}M ARR`;
        },
      }}
      annotations={[
        {
          id: 'forecast-window',
          shape: 'range',
          x1: FORECAST_START,
          x2: FORECAST_END,
          label: 'Forecast window',
          backgroundColor: '#2563eb1a',
          textColor: '#1f2937',
        },
      ]}
      xAxis={{
        show: true,
        title: 'Timeline',
        labelFormatter: (value: number) => MONTH_LABELS[Math.round(value)] ?? `M${Math.round(value) + 1}`,
      }}
      yAxis={{
        show: true,
        title: 'ARR ($M)',
        labelFormatter: (value: number) => `$${Math.round(value)}M`,
      }}
      enableCrosshair
      multiTooltip
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export type RegionKey = 'americas' | 'emea' | 'apac';

export const MONTH_LABELS = [
  'Jan 2024',
  'Feb 2024',
  'Mar 2024',
  'Apr 2024',
  'May 2024',
  'Jun 2024',
  'Jul 2024',
  'Aug 2024',
  'Sep 2024',
  'Oct 2024',
  'Nov 2024',
  'Dec 2024',
  'Jan 2025',
  'Feb 2025',
  'Mar 2025',
  'Apr 2025',
];

export const REGION_COLORS: Record<RegionKey, string> = {
  americas: '#2563EB',
  emea: '#22C55E',
  apac: '#F59E0B',
};

export const ACTUAL_VALUES: Record<RegionKey, number[]> = {
  americas: [118, 124, 131, 139, 147, 156, 166, 177, 189, 202, 214, 228],
  emea: [86, 91, 96, 102, 107, 113, 119, 125, 131, 138, 144, 151],
  apac: [62, 66, 70, 74, 79, 84, 90, 96, 103, 110, 118, 125],
};

export const FORECAST_DELTA: Record<RegionKey, number[]> = {
  americas: [240, 255, 271, 288],
  emea: [159, 168, 177, 187],
  apac: [133, 142, 152, 163],
};

export const buildActualSeries = (region: RegionKey) => ({
  id: `${region}-actual`,
  name: `${region.toUpperCase()} Actual`,
  color: REGION_COLORS[region],
  data: ACTUAL_VALUES[region].map((value, index) => ({
    x: index,
    y: value,
    data: { label: MONTH_LABELS[index], region },
  })),
});

export const buildForecastSeries = (region: RegionKey) => {
  const actual = ACTUAL_VALUES[region];
  const forecast = FORECAST_DELTA[region];
  const baselineIndex = actual.length - 1;
  const baselineValue = actual[baselineIndex];
  return {
    id: `${region}-forecast`,
    name: `${region.toUpperCase()} Forecast`,
    color: REGION_COLORS[region],
    lineStyle: 'dashed' as const,
    showPoints: false,
    data: [
      { x: baselineIndex, y: baselineValue, data: { label: MONTH_LABELS[baselineIndex], region, type: 'baseline' } },
      ...forecast.map((value, offset) => {
        const index = baselineIndex + 1 + offset;
        return {
          x: index,
          y: value,
          data: { label: MONTH_LABELS[index], region, type: 'forecast' },
        };
      }),
    ],
  };
};

export const SERIES = [
  buildActualSeries('americas'),
  buildActualSeries('emea'),
  buildActualSeries('apac'),
  buildForecastSeries('americas'),
  buildForecastSeries('emea'),
  buildForecastSeries('apac'),
];

export const FORECAST_START = ACTUAL_VALUES.americas.length - 0.5;

export const FORECAST_END = MONTH_LABELS.length - 1 + 0.25;
```

### Cohort Retention Curves

**Story focus** - Visualizes how recent signup cohorts retain through the first 120 days of product usage. - Calls out steady improvement quarter-over-quarter with the newest cohort holding above 50%. - Reinforces the retention target so growth teams can spot which cohorts beat the goal. **Key settings** - Keeps straight segments (`smooth={false}`) to preserve milestone-to-milestone retention steps. - Adds a horizontal annotation line at the 45% goal for quick benchmarking. - Expands tooltips to include cohort and milestone context in the retention readout.

```tsx
import { LineChart } from '@plocks/charts';

import { MILESTONES, SERIES, TARGET_RETENTION } from './data';

export function Demo() {
  return (
    <LineChart
      title="Cohort Retention Across Milestones"
      subtitle="Weekly retention milestones by signup quarter"
      h={440}
      series={SERIES}
      smooth={false}
      showPoints
      grid={{ show: true, style: 'dotted' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const milestone = point.data?.milestone ?? `Milestone ${point.x + 1}`;
          const cohort = point.data?.cohort ?? 'Cohort';
          return `${cohort} • ${milestone}: ${point.y.toFixed(0)}% retained`;
        },
      }}
      annotations={[
        {
          id: 'target-retention',
          shape: 'horizontal-line',
          y: TARGET_RETENTION,
          label: 'Target 45% Retention',
          color: '#0EA5E9',
          textColor: '#0F172A',
        },
      ]}
      xAxis={{
        show: true,
        title: 'Customer milestone',
        labelFormatter: (value: number) => MILESTONES[Math.round(value)] ?? `Step ${Math.round(value) + 1}`,
      }}
      yAxis={{
        show: true,
        title: 'Percent of original cohort',
        labelFormatter: (value: number) => `${Math.round(value)}%`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const MILESTONES = ['Signup', 'Day 7', 'Day 30', 'Day 60', 'Day 90', 'Day 120'];

export const COHORT_VALUES = {
  '2024 Q1 Cohort': [100, 64, 51, 44, 39, 36],
  '2024 Q2 Cohort': [100, 68, 55, 48, 43, 40],
  '2024 Q3 Cohort': [100, 72, 59, 52, 47, 44],
  '2024 Q4 Cohort': [100, 75, 63, 57, 54, 50],
} as const;

export const SERIES = Object.entries(COHORT_VALUES).map(([name, values]) => ({
  id: name,
  name,
  data: values.map((value, index) => ({
    x: index,
    y: value,
    data: { milestone: MILESTONES[index], cohort: name },
  })),
  pointSize: 5,
}));

export const TARGET_RETENTION = 45;
```

### Energy Consumption Portfolio

**Story focus** - Benchmarks energy usage across three global offices as efficiency projects roll out. - Highlights the hot-weather season where cooling demand spikes so facilities can react. - Tracks progress against the 360 MWh portfolio target while flagging retrofit milestones. **Key settings** - Demonstrates per-series smoothing choices (`smooth` on each series) while the chart default remains unsmoothed. - Utilizes range, vertical, and horizontal annotations to spotlight seasonal context and program milestones. - Formats tooltip readouts with building names and month labels for facilities reporting.

```tsx
import { LineChart } from '@plocks/charts';

import { COOLING_SEASON, MONTHS, PORTFOLIO_TARGET, SERIES } from './data';

export function Demo() {
  return (
    <LineChart
      title="Energy Consumption Across Office Portfolio"
      subtitle="Monthly MWh usage benchmarking against 360 MWh target"
      h={440}
      series={SERIES}
      smooth={false}
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const month = point.data?.month ?? `Month ${point.x + 1}`;
          const building = point.data?.building ?? 'Site';
          return `${building} • ${month}: ${point.y.toFixed(0)} MWh`;
        },
      }}
      annotations={[
        {
          id: 'cooling-season',
          shape: 'range',
          x1: COOLING_SEASON.start,
          x2: COOLING_SEASON.end,
          label: 'Cooling season monitoring',
          backgroundColor: '#0ea5e91a',
          textColor: '#0C4A6E',
        },
        {
          id: 'target-line',
          shape: 'horizontal-line',
          y: PORTFOLIO_TARGET,
          label: 'Target 360 MWh',
          color: '#16A34A',
          textColor: '#14532D',
        },
        {
          id: 'retrofit-complete',
          shape: 'vertical-line',
          x: 3,
          label: 'LED retrofit complete',
          color: '#10B981',
          textColor: '#064E3B',
        },
      ]}
      xAxis={{
        show: true,
        title: '2024 calendar',
        labelFormatter: (value: number) => MONTHS[Math.round(value)] ?? `M${Math.round(value) + 1}`,
      }}
      yAxis={{
        show: true,
        title: 'Energy consumed (MWh)',
        labelFormatter: (value: number) => `${Math.round(value)} MWh`,
      }}
      enableCrosshair
      multiTooltip
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];

export const BUILDINGS = {
  'New York HQ': {
    smooth: true,
    values: [412, 405, 398, 384, 372, 367, 362, 358, 361, 369, 378, 389],
  },
  'Amsterdam Campus': {
    smooth: true,
    values: [308, 302, 296, 288, 281, 277, 274, 272, 275, 279, 284, 290],
  },
  'Singapore Hub': {
    smooth: false,
    values: [352, 348, 345, 341, 338, 336, 334, 331, 333, 336, 340, 343],
  },
} as const;

export const SERIES = Object.entries(BUILDINGS).map(([name, meta]) => ({
  id: name,
  name,
  smooth: meta.smooth,
  lineThickness: meta.smooth ? 3 : 2,
  data: meta.values.map((value, index) => ({
    x: index,
    y: value,
    data: { building: name, month: MONTHS[index], value },
  })),
}));

export const COOLING_SEASON = { start: 5.5, end: 8.5 };

export const PORTFOLIO_TARGET = 360;
```

### Incident Volume Moving Average

**Story focus** - Shows how daily incident intake surged around a major outage and eventually normalized. - Overlays 7-day and 14-day moving averages so reliability leads can compare short- vs. medium-term trendlines. - Highlights a stabilization period driven by the SRE playbook after the spike. **Key settings** - Draws dashed and dotted overlay series using the new per-series `lineStyle` support. - Adds vertical and range annotations to call out root cause analysis and remediation windows. - Turns on multi-series tooltips so moving averages and raw volume can be read together.

```tsx
import { LineChart } from '@plocks/charts';

import { DAYS, MAJOR_OUTAGE_DAY, SERIES, STABILIZATION_END, STABILIZATION_START } from './data';

export function Demo() {
  return (
    <LineChart
      title="Incident Volume with Moving Averages"
      subtitle="SRE daily incident intake and trailing trends"
      h={440}
      series={SERIES}
      smooth
      grid={{ show: true, style: 'solid' }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const label = point.data?.window
            ? `${point.data.window}-day avg`
            : 'Incidents';
          const day = DAYS[Math.round(point.x)];
          return `${day} • ${label}: ${point.y.toFixed(1)} incidents`;
        },
      }}
      annotations={[
        {
          id: 'major-outage',
          shape: 'vertical-line',
          x: MAJOR_OUTAGE_DAY - 1,
          label: 'Major outage root cause',
          color: '#DC2626',
          textColor: '#0F172A',
        },
        {
          id: 'stabilization-window',
          shape: 'range',
          x1: STABILIZATION_START,
          x2: STABILIZATION_END,
          label: 'Stabilization playbook',
          backgroundColor: '#22c55e22',
          textColor: '#14532d',
        },
      ]}
      xAxis={{
        show: true,
        title: 'Rolling 30-day window',
        labelFormatter: (value: number) => DAYS[Math.round(value)] ?? `Day ${Math.round(value) + 1}`,
      }}
      yAxis={{
        show: true,
        title: 'Incident count',
        labelFormatter: (value: number) => `${Math.round(value)}`,
      }}
      enableCrosshair
      multiTooltip
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const DAYS = Array.from({ length: 30 }, (_, index) => `Day ${index + 1}`);

export const INCIDENT_COUNT = [
  28, 26, 32, 34, 30, 28, 25, 33, 38, 44,
  41, 36, 34, 39, 42, 48, 62, 71, 56, 44,
  38, 34, 31, 28, 32, 36, 40, 37, 33, 30,
];

export const mapSeries = (values: number[]) =>
  values.map((value, index) => ({
    x: index,
    y: value,
    data: { dayLabel: DAYS[index], value },
  }));

export const computeMovingAverage = (values: number[], window: number) => {
  const points: { x: number; y: number }[] = [];
  let rollingTotal = 0;
  for (let index = 0; index < values.length; index += 1) {
    rollingTotal += values[index];
    if (index >= window) {
      rollingTotal -= values[index - window];
    }
    if (index >= window - 1) {
      points.push({ x: index, y: +(rollingTotal / window).toFixed(2) });
    }
  }
  return points.map((point) => ({
    ...point,
    data: { dayLabel: DAYS[point.x], window },
  }));
};

export const SERIES = [
  {
    id: 'incidents',
    name: 'Daily Incidents',
    data: mapSeries(INCIDENT_COUNT),
    pointSize: 4,
  },
  {
    id: 'ma-7',
    name: '7-day Moving Average',
    lineStyle: 'dashed' as const,
    showPoints: false,
    data: computeMovingAverage(INCIDENT_COUNT, 7),
  },
  {
    id: 'ma-14',
    name: '14-day Moving Average',
    lineStyle: 'dotted' as const,
    showPoints: false,
    data: computeMovingAverage(INCIDENT_COUNT, 14),
  },
];

export const MAJOR_OUTAGE_DAY = 17;

export const STABILIZATION_START = 20.5;

export const STABILIZATION_END = 26.5;
```

### Nps Trend Release Markers

**Story focus** - Tracks the steady climb in NPS as successive product experiences ship throughout the year. - Annotates each launch so teams can correlate release timing with sentiment jumps. - Keeps a green performance line so customer orgs know when the brand clears the NPS target. **Key settings** - Enables area fill to spotlight the magnitude of the NPS climb across months. - Uses vertical annotations with labels to mark major releases on the timeline. - Adds a horizontal annotation at the 55-point goal for immediate benchmarking.

```tsx
import { LineChart } from '@plocks/charts';

import { MONTHS, RELEASE_MARKERS, SERIES } from './data';

export function Demo() {
  return (
    <LineChart
      title="NPS Trend with Product Releases"
      subtitle="Quarterly sentiment lift alongside major launches"
      h={420}
      series={SERIES}
      smooth
      fill
      grid={{ show: true, style: 'dashed' }}
      legend={{ show: false }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const month = point.data?.month ?? `Month ${point.x + 1}`;
          return `${month} NPS: ${point.y.toFixed(0)}`;
        },
      }}
      annotations={[
        ...RELEASE_MARKERS.map((marker) => ({
          id: marker.id,
          shape: 'vertical-line' as const,
          x: marker.x,
          label: marker.label,
          color: '#6366F1',
          textColor: '#312E81',
          backgroundColor: '#E0E7FF',
        })),
        {
          id: 'nps-target',
          shape: 'horizontal-line',
          y: 55,
          label: 'Target 55 NPS',
          color: '#16A34A',
          textColor: '#0F172A',
        },
      ]}
      xAxis={{
        show: true,
        title: '2024 timeline',
        labelFormatter: (value: number) => MONTHS[Math.round(value)] ?? `M${Math.round(value) + 1}`,
      }}
      yAxis={{
        show: true,
        title: 'Net Promoter Score',
        labelFormatter: (value: number) => `${Math.round(value)}`,
      }}
      enableCrosshair
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug'];

export const NPS_VALUES = [43, 45, 47, 52, 54, 58, 61, 64];

export const SERIES = [
  {
    id: 'nps-score',
    name: 'NPS',
    areaFill: true,
    fillOpacity: 0.25,
    data: NPS_VALUES.map((value, index) => ({
      x: index,
      y: value,
      data: { month: MONTHS[index], value },
    })),
  },
];

export const RELEASE_MARKERS = [
  { id: 'apr-release', x: 3, label: 'Onboarding revamp' },
  { id: 'jun-release', x: 5, label: 'Mobile UI refresh' },
  { id: 'jul-release', x: 6.5, label: 'Insights launch' },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/MarimekkoChart.md -->

# Marimekko Chart

Visualize categorical mix alongside overall weight with a mosaic-style variable-width column chart.

## Metadata

- Import: `import { MarimekkoChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, marimekko, mosaic
- Docs: https://plocks.dev/charts/MarimekkoChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/MarimekkoChart

## Props

- `data` (required): MarimekkoCategory[] — Categories rendered as variable-width columns.
- `legend`: ChartLegend — Optional legend configuration.
- `xAxis`: ChartAxis — Optional x-axis configuration.
- `yAxis`: ChartAxis — Optional y-axis configuration (defaults to percentage scale).
- `grid`: ChartGrid — Grid configuration applied to the background.
- `columnGap`: number = 12 — Gap (in pixels) inserted between columns.
- `segmentBorderRadius`: number = 2 — Corner radius applied to each segment rectangle.
- `padding`: { top: number; right: number; bottom: number; left: number } — Override padding around the chart plot area.
- `categoryLabelFormatter`: (category: MarimekkoCategory, index: number) => string — Formatter applied to categorical labels along the x-axis.

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface MarimekkoCategory {
  /** Pre-formatted helpers for tooltip rendering. */
  /** Unique identifier (falls back to the label). */
  id?: string | number;
  /** Display label for the category column. */
  label: string;
  /** Optional base color applied to segments that do not override their own color. */
  color?: string;
  /** Segments stacked within this category column. */
  segments: MarimekkoSegment[];
  /** Whether this category column is visible. */
  visible?: boolean;
  /** Arbitrary user data passed through interaction callbacks. */
  data?: any;
}

export interface MarimekkoSegment {
  /** Unique identifier within the category (falls back to the label). */
  id?: string | number;
  /** Display label for the segment. */
  label: string;
  /** Absolute measure represented by the segment. */
  value: number;
  /** Optional color override applied to this segment instance. */
  color?: string;
  /** Whether the segment is visible. */
  visible?: boolean;
  /** Arbitrary user data carried through interaction callbacks. */
  data?: any;
  /** Total for the category after applying legend visibility (injected by the chart). */
  visibleCategoryTotal?: number;
  /** Share of the visible dataset contributed by the category (injected by the chart). */
  visibleCategoryShare?: number;
}
```

## Examples

### Basics

Variable-width columns reveal how each pipeline channel and region contributes to total qualified pipeline.

```tsx
import { MarimekkoChart } from '@plocks/charts';

import { PIPELINE_COMPOSITION } from './data';

export function Demo() {
  return (
    <MarimekkoChart
      title="Pipeline contribution by segment"
      subtitle="Quarter to date"
      h={440}
      data={PIPELINE_COMPOSITION}
      columnGap={16}
      legend={{ show: true, position: 'bottom' }}
      yAxis={{ title: 'Segment share (%)' }}
      grid={{ show: true, style: 'dotted' }}
      categoryLabelFormatter={(category) => category.label}
    />
  );
}
```

`data.ts`

```ts
export const PIPELINE_COMPOSITION = [
  {
    label: 'Inbound',
    segments: [
      { label: 'North America', value: 52 },
      { label: 'EMEA', value: 34 },
      { label: 'APAC', value: 24 },
    ],
  },
  {
    label: 'Outbound',
    segments: [
      { label: 'North America', value: 44 },
      { label: 'EMEA', value: 28 },
      { label: 'APAC', value: 18 },
    ],
  },
  {
    label: 'Partnerships',
    segments: [
      { label: 'North America', value: 29 },
      { label: 'EMEA', value: 22 },
      { label: 'APAC', value: 15 },
    ],
  },
  {
    label: 'Expansion',
    segments: [
      { label: 'North America', value: 37 },
      { label: 'EMEA', value: 18 },
      { label: 'APAC', value: 12 },
    ],
  },
];
```

### Budget Allocation

Lay out the company plan to see both department budgets and how each team invests within their allocation.

```tsx
import { MarimekkoChart } from '@plocks/charts';

import { BUDGET_PLAN } from './data';

export function Demo() {
  return (
    <MarimekkoChart
      title="FY26 budget allocation"
      subtitle="Percentage of total discretionary spend"
      h={420}
      data={BUDGET_PLAN}
      segmentBorderRadius={3}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      yAxis={{ title: 'Share of category (%)' }}
      categoryLabelFormatter={(category) => `${category.label} (${category.segments.reduce((sum, seg) => sum + seg.value, 0)}%)`}
    />
  );
}
```

`data.ts`

```ts
export const BUDGET_PLAN = [
  {
    label: 'Growth',
    segments: [
      { label: 'Paid media', value: 28 },
      { label: 'Field marketing', value: 24 },
      { label: 'Events', value: 18 },
      { label: 'Advocacy', value: 12 },
    ],
  },
  {
    label: 'Product',
    segments: [
      { label: 'Roadmap', value: 26 },
      { label: 'Design', value: 14 },
      { label: 'Research', value: 10 },
      { label: 'Maintenance', value: 22 },
    ],
  },
  {
    label: 'Customer',
    segments: [
      { label: 'Success', value: 18 },
      { label: 'Support', value: 21 },
      { label: 'Education', value: 9 },
      { label: 'Community', value: 7 },
    ],
  },
  {
    label: 'Operations',
    segments: [
      { label: 'Security', value: 15 },
      { label: 'IT', value: 11 },
      { label: 'Finance', value: 14 },
      { label: 'People', value: 13 },
    ],
  },
];
```

### Product Portfolio

Compare how revenue mixes across product tiers and sales motions within a single view.

```tsx
import { MarimekkoChart } from '@plocks/charts';

import { PRODUCT_MIX } from './data';

export function Demo() {
  return (
    <MarimekkoChart
      title="ARR by product tier and motion"
      subtitle="Current quarter"
      h={460}
      data={PRODUCT_MIX}
      segmentBorderRadius={4}
      legend={{ show: true, position: 'right' }}
      yAxis={{ title: 'Revenue share (%)' }}
      categoryLabelFormatter={(category) => `${category.label}\n(${category.data?.region ?? 'Global'})`}
    />
  );
}
```

`data.ts`

```ts
export const PRODUCT_MIX = [
  {
    label: 'Starter',
    segments: [
      { label: 'Self-serve', value: 240 },
      { label: 'Sales assisted', value: 60 },
      { label: 'Channel', value: 45 },
    ],
  },
  {
    label: 'Growth',
    segments: [
      { label: 'Self-serve', value: 180 },
      { label: 'Sales assisted', value: 110 },
      { label: 'Channel', value: 95 },
    ],
  },
  {
    label: 'Scale',
    segments: [
      { label: 'Self-serve', value: 72 },
      { label: 'Sales assisted', value: 148 },
      { label: 'Channel', value: 126 },
    ],
  },
  {
    label: 'Enterprise',
    segments: [
      { label: 'Self-serve', value: 18 },
      { label: 'Sales assisted', value: 205 },
      { label: 'Channel', value: 164 },
    ],
  },
];
```

### Regional Mix

Explore regional totals and the mix of revenue streams side by side.

```tsx
import { MarimekkoChart } from '@plocks/charts';

import { REGIONAL_REVENUE } from './data';

export function Demo() {
  return (
    <MarimekkoChart
      title="Revenue mix by region"
      subtitle="Trailing twelve months"
      h={440}
      data={REGIONAL_REVENUE}
      columnGap={20}
      legend={{ show: true, position: 'bottom', align: 'start' }}
      grid={{ show: true, style: 'dotted' }}
      yAxis={{ title: 'Share within region (%)' }}
    />
  );
}
```

`data.ts`

```ts
export const REGIONAL_REVENUE = [
  {
    label: 'North America',
    segments: [
      { label: 'New business', value: 186 },
      { label: 'Expansion', value: 142 },
      { label: 'Renewal', value: 128 },
      { label: 'Services', value: 94 },
    ],
  },
  {
    label: 'EMEA',
    segments: [
      { label: 'New business', value: 132 },
      { label: 'Expansion', value: 98 },
      { label: 'Renewal', value: 87 },
      { label: 'Services', value: 76 },
    ],
  },
  {
    label: 'APAC',
    segments: [
      { label: 'New business', value: 94 },
      { label: 'Expansion', value: 72 },
      { label: 'Renewal', value: 65 },
      { label: 'Services', value: 48 },
    ],
  },
  {
    label: 'LATAM',
    segments: [
      { label: 'New business', value: 46 },
      { label: 'Expansion', value: 34 },
      { label: 'Renewal', value: 28 },
      { label: 'Services', value: 22 },
    ],
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/NetworkChart.md -->

# Network Chart

NetworkChart visualizes relationships among nodes and links.

## Metadata

- Import: `import { NetworkChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, network, graph
- Docs: https://plocks.dev/charts/NetworkChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/NetworkChart

## Props

- `nodes` (required): NetworkNode[] — Nodes to render in the network
- `links` (required): NetworkLink[] — Links connecting the nodes
- `layout`: 'force' | 'coordinate' | 'circular' | 'radial' = 'force' — Layout engine mode
- `grid`: ChartGrid | boolean — Optional grid configuration for coordinate layouts
- `xAxis`: ChartAxis — X axis configuration when using coordinate layouts
- `yAxis`: ChartAxis — Y axis configuration when using coordinate layouts
- `padding`: Partial<{ top: number; right: number; bottom: number; left: number }> — Optional padding overrides
- `coordinateAccessor`: { x?: (node: NetworkNode, index: number) => number; y?: (node: NetworkNode, index: number) => number; } — Accessor overrides for coordinate layouts
- `showLabels`: boolean = true — Show node labels
- `nodeRadius`: number = 12 — Radius override for nodes
- `nodeRadiusRange`: [number, number] — Optional range that scales node radius by node value
- `nodeValueAccessor`: (node: NetworkNode, index: number) => number — Optional accessor to extract numeric value for node sizing
- `linkWidthRange`: [number, number] — Optional range that maps link weights to stroke width
- `linkColorAccessor`: (link: NetworkLink, index: number) => string | undefined — Accessor for custom link colors
- `linkOpacityAccessor`: (link: NetworkLink, index: number) => number | undefined — Accessor for custom link opacity
- `linkShape`: 'straight' | 'curved' — Link rendering shape
- `linkCurveStrength`: number — Curvature strength multiplier when using curved links
- `linkPalette`: string[] — Palette used when a link does not provide an explicit color
- `onNodeFocus`: (event: NetworkNodeInteractionEvent) => void — Node focus callback for hover/focus interactions
- `onNodeBlur`: (event: NetworkNodeInteractionEvent) => void — Node blur callback
- `onNodePress`: (event: NetworkNodeInteractionEvent) => void — Node press callback
- `onLinkFocus`: (event: NetworkLinkInteractionEvent) => void — Link focus callback for hover/focus interactions
- `onLinkBlur`: (event: NetworkLinkInteractionEvent) => void — Link blur callback
- `onLinkPress`: (event: NetworkLinkInteractionEvent) => void — Link press callback

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface NetworkNode {
  /** Unique identifier for the node */
  id: string;
  /** Display name for the node */
  name?: string;
  /** Optional grouping key used for styling */
  group?: string | number;
  /** Numeric value associated with the node */
  value?: number;
  /** Explicit color override for the node */
  color?: string;
  /** Additional metadata associated with the node */
  meta?: any;
  /** Optional X coordinate for coordinate layouts */
  x?: number;
  /** Optional Y coordinate for coordinate layouts */
  y?: number;
}

export interface NetworkLink {
  /** ID of the source node */
  source: string;
  /** ID of the target node */
  target: string;
  /** Strength or weight of the connection */
  weight?: number;
  /** Additional metadata associated with the link */
  meta?: any;
  /** Optional color override for the link */
  color?: string;
  /** Optional opacity override for the link */
  opacity?: number;
  /** Explicit stroke width override for the link */
  width?: number;
}

export interface NetworkNodeInteractionEvent {
  node: NetworkNode;
  index: number;
  position: { x: number; y: number };
}

export interface NetworkLinkInteractionEvent {
  link: NetworkLink;
  index: number;
  source: { node?: NetworkNode; position: { x: number; y: number } };
  target: { node?: NetworkNode; position: { x: number; y: number } };
  weight: number;
}
```

## Examples

### Basics

NetworkChart visualizes relationships among nodes and links.

```tsx
import { NetworkChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
	return (
		<NetworkChart
			title="Cross-team collaboration"
			h={460}
			layout="circular"
			nodes={NODES}
			links={LINKS}
		/>
	);
}
```

`data.ts`

```ts
export const NODES = [
	{ id: 'product', name: 'Product', group: 'teams', value: 12 },
	{ id: 'design', name: 'Design', group: 'teams', value: 8 },
	{ id: 'engineering', name: 'Engineering', group: 'teams', value: 18 },
	{ id: 'marketing', name: 'Marketing', group: 'teams', value: 10 },
	{ id: 'sales', name: 'Sales', group: 'teams', value: 9 },
	{ id: 'support', name: 'Support', group: 'teams', value: 7 },
	{ id: 'platform', name: 'Platform', group: 'initiatives', value: 15 },
	{ id: 'ai', name: 'AI', group: 'initiatives', value: 11 },
];

export const LINKS = [
	{ source: 'platform', target: 'engineering', value: 6 },
	{ source: 'platform', target: 'product', value: 5 },
	{ source: 'platform', target: 'support', value: 2 },
	{ source: 'ai', target: 'product', value: 4 },
	{ source: 'ai', target: 'marketing', value: 3 },
	{ source: 'ai', target: 'sales', value: 2 },
	{ source: 'product', target: 'design', value: 7 },
	{ source: 'product', target: 'engineering', value: 8 },
	{ source: 'marketing', target: 'sales', value: 5 },
	{ source: 'support', target: 'sales', value: 4 },
];
```

### Customer Referral Network

```tsx
import { NetworkChart } from '@plocks/charts';

import { COHORTS, REFERRALS } from './data';

const waveToColor = (wave?: number) => {
  if (wave === 1) return '#34C759';
  if (wave === 2) return '#4DABF7';
  if (wave === 3) return '#FF922B';
  return '#ADB5BD';
};

const waveToOpacity = (wave?: number) => {
  if (wave === 1) return 0.7;
  if (wave === 2) return 0.6;
  if (wave === 3) return 0.55;
  return 0.45;
};

export function Demo() {
  return (
    <NetworkChart
      title="Customer referral influence network"
      subtitle="Referral pathways by activation wave"
      h={430}
      nodes={COHORTS}
      links={REFERRALS}
      showLabels
      nodeRadius={13}
      nodeRadiusRange={[11, 25]}
      linkWidthRange={[1, 3.6]}
      linkColorAccessor={(link) => waveToColor(typeof link.meta?.wave === 'number' ? link.meta.wave : Number(link.meta?.wave))}
      linkOpacityAccessor={(link) => waveToOpacity(typeof link.meta?.wave === 'number' ? link.meta.wave : Number(link.meta?.wave))}
    />
  );
}
```

`data.ts`

```ts
import type { NetworkLink, NetworkNode } from '@plocks/charts';

export const COHORTS: NetworkNode[] = [
  { id: 'seed-advocates', name: 'Seed Advocates', group: 'seed', value: 38 },
  { id: 'growth-us', name: 'Growth - US', group: 'growth', value: 44 },
  { id: 'growth-eu', name: 'Growth - EU', group: 'growth', value: 36 },
  { id: 'enterprise-wave', name: 'Enterprise Wave', group: 'enterprise', value: 29 },
  { id: 'partner-ecosystem', name: 'Partner Ecosystem', group: 'partners', value: 24 },
  { id: 'freemium-community', name: 'Freemium Community', group: 'seed', value: 50 },
  { id: 'latam-expansion', name: 'LATAM Expansion', group: 'growth', value: 31 },
];

export const REFERRALS: NetworkLink[] = [
  { source: 'seed-advocates', target: 'freemium-community', weight: 6.4, meta: { wave: 1 } },
  { source: 'seed-advocates', target: 'growth-us', weight: 4.7, meta: { wave: 1 } },
  { source: 'freemium-community', target: 'growth-eu', weight: 3.8, meta: { wave: 2 } },
  { source: 'growth-us', target: 'enterprise-wave', weight: 3.3, meta: { wave: 2 } },
  { source: 'growth-eu', target: 'enterprise-wave', weight: 2.6, meta: { wave: 3 } },
  { source: 'partner-ecosystem', target: 'enterprise-wave', weight: 3.9, meta: { wave: 1 } },
  { source: 'partner-ecosystem', target: 'growth-us', weight: 2.4, meta: { wave: 2 } },
  { source: 'latam-expansion', target: 'growth-eu', weight: 3.2, meta: { wave: 2 } },
  { source: 'latam-expansion', target: 'freemium-community', weight: 2.7, meta: { wave: 3 } },
];
```

### Knowledge Sharing Connections

```tsx
import { useState, useMemo } from 'react';
import { Text } from 'react-native';
import { NetworkChart } from '@plocks/charts';

import { MENTORSHIPS, TEAMS } from './data';

const linkColorByType = (type: string | undefined) => {
  switch (type) {
    case 'cross-team':
      return '#5F3DC4';
    case 'program':
      return '#1971C2';
    case 'rotation':
      return '#FFA94D';
    case 'pairing':
      return '#15AABF';
    default:
      return '#ADB5BD';
  }
};

const linkOpacityByType = (type: string | undefined) => {
  switch (type) {
    case 'cross-team':
      return 0.72;
    case 'program':
      return 0.6;
    case 'rotation':
      return 0.55;
    case 'pairing':
      return 0.5;
    default:
      return 0.45;
  }
};

export function Demo() {
  const [focusDetail, setFocusDetail] = useState<string | null>(null);

  const highlightText = useMemo(() => focusDetail, [focusDetail]);

  return (
    <>
      <NetworkChart
        title="Knowledge sharing mentorship graph"
        subtitle="Monthly mentorship hours across guild programs"
        h={440}
        layout="radial"
        nodes={TEAMS}
        links={MENTORSHIPS}
        showLabels
        nodeRadius={14}
        nodeRadiusRange={[12, 26]}
        linkWidthRange={[1.1, 3.8]}
        linkShape="curved"
        linkCurveStrength={0.38}
        linkPalette={['#7048E8', '#4263EB', '#0CA678', '#F08C00']}
        linkColorAccessor={(link) => linkColorByType(link.meta?.type)}
        linkOpacityAccessor={(link) => linkOpacityByType(link.meta?.type)}
        onNodeFocus={(event) =>
          setFocusDetail(
            `${event.node.name ?? event.node.id} • ${Math.round(event.node.value ?? 0)} active mentorship hours`
          )
        }
        onNodeBlur={() => setFocusDetail(null)}
        onLinkFocus={(event) => {
          const sourceName = event.source.node?.name ?? event.link.source;
          const targetName = event.target.node?.name ?? event.link.target;
          setFocusDetail(`${sourceName} mentoring ${targetName}`);
        }}
        onLinkBlur={() => setFocusDetail(null)}
      />
      {highlightText && (
        <Text style={{ marginTop: 12, fontSize: 12, color: '#495057' }}>{highlightText}</Text>
      )}
    </>
  );
}
```

`data.ts`

```ts
import type { NetworkLink, NetworkNode } from '@plocks/charts';

export const TEAMS: NetworkNode[] = [
  { id: 'design-guild', name: 'Design Guild', group: 'product', value: 36 },
  { id: 'frontend', name: 'Frontend', group: 'engineering', value: 52 },
  { id: 'backend', name: 'Platform API', group: 'engineering', value: 58 },
  { id: 'data-science', name: 'Data Science', group: 'analytics', value: 41 },
  { id: 'product-management', name: 'Product Management', group: 'product', value: 47 },
  { id: 'customer-success', name: 'Customer Success', group: 'go-to-market', value: 33 },
  { id: 'devrel', name: 'DevRel', group: 'growth', value: 26 },
];

export const MENTORSHIPS: NetworkLink[] = [
  { source: 'frontend', target: 'design-guild', weight: 6.5, meta: { type: 'cross-team' } },
  { source: 'backend', target: 'frontend', weight: 7.2, meta: { type: 'pairing' } },
  { source: 'backend', target: 'data-science', weight: 4.1, meta: { type: 'cross-team' } },
  { source: 'product-management', target: 'design-guild', weight: 5.4, meta: { type: 'program' } },
  { source: 'product-management', target: 'customer-success', weight: 3.7, meta: { type: 'rotation' } },
  { source: 'devrel', target: 'frontend', weight: 2.9, meta: { type: 'cross-team' } },
  { source: 'devrel', target: 'customer-success', weight: 3.4, meta: { type: 'program' } },
  { source: 'data-science', target: 'product-management', weight: 4.6, meta: { type: 'pairing' } },
  { source: 'customer-success', target: 'design-guild', weight: 2.7, meta: { type: 'rotation' } },
];
```

### Microservice Latency

```tsx
import { NetworkChart } from '@plocks/charts';

import { DEPENDENCIES, SERVICES } from './data';

const latencyToColor = (latency: number) => {
  if (latency <= 150) return '#12B886';
  if (latency <= 220) return '#FAB005';
  return '#FA5252';
};

const latencyToOpacity = (latency: number) => {
  if (latency >= 250) return 0.9;
  if (latency >= 200) return 0.7;
  return 0.5;
};

export function Demo() {
  return (
    <NetworkChart
      title="Microservice latency map"
      subtitle="Edge-to-core call graph with weighted latency"
      h={460}
      nodes={SERVICES}
      links={DEPENDENCIES}
      showLabels
      nodeRadius={12}
      nodeRadiusRange={[10, 28]}
      linkWidthRange={[1.2, 4.6]}
  linkColorAccessor={(link) => latencyToColor(Number(link.meta?.latency ?? 0))}
  linkOpacityAccessor={(link) => latencyToOpacity(Number(link.meta?.latency ?? 0))}
    />
  );
}
```

`data.ts`

```ts
import type { NetworkLink, NetworkNode } from '@plocks/charts';

export const SERVICES: NetworkNode[] = [
  { id: 'api-gateway', name: 'API Gateway', group: 'edge', value: 420 },
  { id: 'auth-service', name: 'Auth', group: 'core', value: 260 },
  { id: 'catalog-service', name: 'Catalog', group: 'core', value: 310 },
  { id: 'payment-service', name: 'Payments', group: 'revenue', value: 280 },
  { id: 'notification-service', name: 'Notifications', group: 'engagement', value: 190 },
  { id: 'search-service', name: 'Search', group: 'experience', value: 240 },
  { id: 'analytics-service', name: 'Analytics', group: 'insights', value: 210 },
  { id: 'inventory-service', name: 'Inventory', group: 'ops', value: 330 },
];

export const DEPENDENCIES: NetworkLink[] = [
  { source: 'api-gateway', target: 'auth-service', weight: 9.5, meta: { latency: 95 } },
  { source: 'api-gateway', target: 'catalog-service', weight: 8.2, meta: { latency: 132 } },
  { source: 'api-gateway', target: 'payment-service', weight: 7.1, meta: { latency: 214 } },
  { source: 'catalog-service', target: 'inventory-service', weight: 6.4, meta: { latency: 186 } },
  { source: 'catalog-service', target: 'search-service', weight: 5.5, meta: { latency: 158 } },
  { source: 'payment-service', target: 'auth-service', weight: 4.2, meta: { latency: 248 } },
  { source: 'payment-service', target: 'analytics-service', weight: 3.6, meta: { latency: 276 } },
  { source: 'notification-service', target: 'api-gateway', weight: 4.4, meta: { latency: 146 } },
  { source: 'analytics-service', target: 'notification-service', weight: 3.2, meta: { latency: 182 } },
  { source: 'analytics-service', target: 'catalog-service', weight: 2.8, meta: { latency: 224 } },
];
```

### Risk Propagation

```tsx
import { NetworkChart } from '@plocks/charts';

import { PROPAGATION, SYSTEMS } from './data';

const severityToColor = (severity?: string) => {
  switch (severity) {
    case 'critical':
      return '#FA5252';
    case 'major':
      return '#FD7E14';
    case 'minor':
      return '#FAB005';
    default:
      return '#ADB5BD';
  }
};

const severityToOpacity = (severity?: string) => {
  switch (severity) {
    case 'critical':
      return 0.88;
    case 'major':
      return 0.68;
    case 'minor':
      return 0.55;
    default:
      return 0.45;
  }
};

export function Demo() {
  return (
    <NetworkChart
      title="Risk propagation path"
      subtitle="Simulated attack progression across services"
      h={420}
      nodes={SYSTEMS}
      links={PROPAGATION}
      showLabels
      nodeRadius={12}
      nodeRadiusRange={[10, 26]}
      linkWidthRange={[1.1, 3.9]}
      linkColorAccessor={(link) => severityToColor(link.meta?.severity)}
      linkOpacityAccessor={(link) => severityToOpacity(link.meta?.severity)}
    />
  );
}
```

`data.ts`

```ts
import type { NetworkLink, NetworkNode } from '@plocks/charts';

export const SYSTEMS: NetworkNode[] = [
  { id: 'edge-firewall', name: 'Edge Firewall', group: 'perimeter', value: 34 },
  { id: 'api-gateway', name: 'API Gateway', group: 'perimeter', value: 48 },
  { id: 'auth-service', name: 'Auth Service', group: 'identity', value: 62 },
  { id: 'service-mesh', name: 'Service Mesh', group: 'platform', value: 55 },
  { id: 'data-lake', name: 'Data Lake', group: 'data', value: 74 },
  { id: 'billing-system', name: 'Billing', group: 'finance', value: 80 },
  { id: 'support-portal', name: 'Support Portal', group: 'customer', value: 46 },
];

export const PROPAGATION: NetworkLink[] = [
  { source: 'edge-firewall', target: 'api-gateway', weight: 5.6, meta: { severity: 'major' } },
  { source: 'api-gateway', target: 'auth-service', weight: 4.2, meta: { severity: 'critical' } },
  { source: 'auth-service', target: 'service-mesh', weight: 3.5, meta: { severity: 'major' } },
  { source: 'service-mesh', target: 'data-lake', weight: 3.1, meta: { severity: 'critical' } },
  { source: 'data-lake', target: 'billing-system', weight: 2.8, meta: { severity: 'critical' } },
  { source: 'billing-system', target: 'support-portal', weight: 2.4, meta: { severity: 'major' } },
  { source: 'edge-firewall', target: 'support-portal', weight: 2.9, meta: { severity: 'minor' } },
  { source: 'service-mesh', target: 'support-portal', weight: 2.2, meta: { severity: 'minor' } },
];
```

### Supply Chain Relationships

```tsx
import { NetworkChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

const riskToColor = (risk?: string) => {
  switch (risk) {
    case 'high':
      return '#FA5252';
    case 'medium':
      return '#FCC419';
    case 'low':
      return '#51CF66';
    default:
      return '#ADB5BD';
  }
};

const riskToOpacity = (risk?: string) => {
  switch (risk) {
    case 'high':
      return 0.85;
    case 'medium':
      return 0.65;
    case 'low':
      return 0.55;
    default:
      return 0.45;
  }
};

export function Demo() {
  return (
    <NetworkChart
      title="Supply chain relationship map"
      subtitle="Tiered flow from suppliers to regional distribution"
      h={440}
      layout="coordinate"
      nodes={NODES}
      links={LINKS}
      showLabels
      nodeRadius={12}
      nodeRadiusRange={[10, 24]}
      linkWidthRange={[1.2, 4.2]}
      linkColorAccessor={(link) => riskToColor(link.meta?.risk)}
      linkOpacityAccessor={(link) => riskToOpacity(link.meta?.risk)}
      grid={false}
      xAxis={{ show: false }}
      yAxis={{ show: false }}
    />
  );
}
```

`data.ts`

```ts
import type { NetworkLink, NetworkNode } from '@plocks/charts';

export const suppliers = (
  [
    { id: 'supplier-a', name: 'Supplier A', value: 68 },
    { id: 'supplier-b', name: 'Supplier B', value: 54 },
    { id: 'supplier-c', name: 'Supplier C', value: 46 },
  ] satisfies Array<Omit<NetworkNode, 'group'>>
).map((node, index) => ({
  ...node,
  group: 'supplier',
  x: 0,
  y: index * 80,
}));

export const manufacturers = (
  [
    { id: 'plant-north', name: 'Plant - North', value: 82 },
    { id: 'plant-central', name: 'Plant - Central', value: 76 },
    { id: 'plant-south', name: 'Plant - South', value: 64 },
  ] satisfies Array<Omit<NetworkNode, 'group'>>
).map((node, index) => ({
  ...node,
  group: 'manufacturer',
  x: 1,
  y: index * 80 + 30,
}));

export const distribution = (
  [
    { id: 'dc-west', name: 'DC West', value: 58 },
    { id: 'dc-east', name: 'DC East', value: 72 },
    { id: 'dc-emea', name: 'DC EMEA', value: 49 },
  ] satisfies Array<Omit<NetworkNode, 'group'>>
).map((node, index) => ({
  ...node,
  group: 'distribution',
  x: 2,
  y: index * 80 + 10,
}));

export const NODES: NetworkNode[] = [...suppliers, ...manufacturers, ...distribution];

export const LINKS: NetworkLink[] = [
  { source: 'supplier-a', target: 'plant-north', weight: 6.4, meta: { risk: 'low' } },
  { source: 'supplier-a', target: 'plant-central', weight: 4.8, meta: { risk: 'medium' } },
  { source: 'supplier-b', target: 'plant-central', weight: 5.6, meta: { risk: 'medium' } },
  { source: 'supplier-b', target: 'plant-south', weight: 4.1, meta: { risk: 'high' } },
  { source: 'supplier-c', target: 'plant-north', weight: 3.9, meta: { risk: 'low' } },
  { source: 'supplier-c', target: 'plant-south', weight: 3.3, meta: { risk: 'medium' } },
  { source: 'plant-north', target: 'dc-west', weight: 5.2, meta: { risk: 'low' } },
  { source: 'plant-north', target: 'dc-emea', weight: 3.5, meta: { risk: 'medium' } },
  { source: 'plant-central', target: 'dc-west', weight: 4.4, meta: { risk: 'medium' } },
  { source: 'plant-central', target: 'dc-east', weight: 5.9, meta: { risk: 'low' } },
  { source: 'plant-south', target: 'dc-east', weight: 4.7, meta: { risk: 'medium' } },
  { source: 'plant-south', target: 'dc-emea', weight: 3.8, meta: { risk: 'high' } },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ParetoChart.md -->

# Pareto Chart

Highlight the small number of categories that drive the majority of impact with a bar plus cumulative line visualization.

## Metadata

- Import: `import { ParetoChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, pareto, quality
- Docs: https://plocks.dev/charts/ParetoChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/ParetoChart

## Props

- `data` (required): ParetoChartDatum[] — Raw categories to render inside the Pareto analysis.
- `sortDirection`: 'desc' | 'asc' | 'none' = 'desc' — Sorting direction applied before calculating cumulative percentages.
- `valueSeriesLabel`: string = 'Frequency' — Display label for the bar series.
- `cumulativeSeriesLabel`: string = 'Cumulative %' — Display label for the cumulative line series.
- `barColor`: string — Base color used for the bar series when data points do not provide one.
- `lineColor`: string — Base color used for the cumulative line series.
- `categoryLabelFormatter`: (category: string, index: number) => string — Optional formatter applied to the categorical axis labels.

Plus the `ComboChart` props (`enableCrosshair` `multiTooltip` `liveTooltip` `xDomain` `yDomain` `yDomainRight` `xAxis` `yAxis` `yAxisRight` `grid` `legend`): https://plocks.dev/llms/components/ComboChart.md

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface ParetoChartDatum {
  /** Category or defect name represented by the bar. */
  label: string;
  /** Absolute contribution for the category. */
  value: number;
  /** Optional color override applied to the bar for this category. */
  color?: string;
}
```

## Examples

### Basics

Simple Pareto chart showing how cumulative contribution highlights the dominant defect categories.

```tsx
import { ParetoChart } from '@plocks/charts';

import { DEFECT_BREAKDOWN } from './data';

export function Demo() {
  return (
    <ParetoChart
      title="Monthly defect analysis"
      subtitle="Product QA triage"
      h={420}
      data={DEFECT_BREAKDOWN}
      valueSeriesLabel="Defects"
      cumulativeSeriesLabel="Cumulative impact"
      grid={{ show: true, style: 'dotted' }}
      legend={{ show: true, position: 'bottom' }}
      yAxis={{ title: 'Defects reported' }}
      yAxisRight={{ title: 'Cumulative share' }}
    />
  );
}
```

`data.ts`

```ts
export const DEFECT_BREAKDOWN = [
  { label: 'Authentication', value: 118 },
  { label: 'Checkout', value: 96 },
  { label: 'Notifications', value: 64 },
  { label: 'Analytics', value: 42 },
  { label: 'Billing', value: 31 },
  { label: 'Integrations', value: 27 },
  { label: 'Mobile', value: 19 },
  { label: 'Reporting', value: 17 },
];
```

### Customer Support Hotspots

Highlight how a handful of ticket categories drive the majority of support backlog volume.

```tsx
import { ParetoChart } from '@plocks/charts';

import { SUPPORT_CASES } from './data';

export function Demo() {
  return (
    <ParetoChart
      title="Support backlog concentration"
      subtitle="Top ten case drivers this quarter"
      h={440}
      data={SUPPORT_CASES}
      valueSeriesLabel="Cases"
      cumulativeSeriesLabel="Cumulative ticket share"
      yAxis={{ title: 'Case volume' }}
      yAxisRight={{ title: 'Cumulative share' }}
    />
  );
}
```

`data.ts`

```ts
export const SUPPORT_CASES = [
  { label: 'Login reset', value: 420 },
  { label: 'Billing error', value: 318 },
  { label: 'Delayed shipment', value: 247 },
  { label: 'Missing items', value: 186 },
  { label: 'Promo code', value: 132 },
  { label: 'Damaged product', value: 108 },
  { label: 'Account locked', value: 96 },
  { label: 'Wrong item', value: 74 },
  { label: 'Return label', value: 65 },
  { label: 'Subscription cancel', value: 52 },
];
```

### Incident Root Causes

Root-cause analysis illustrating which failure modes dominate incident volume.

```tsx
import { ParetoChart } from '@plocks/charts';

import { POSTMORTEM_CAUSES } from './data';

export function Demo() {
  return (
    <ParetoChart
      title="Incident root causes"
      subtitle="Rolling twelve months"
      h={420}
      data={POSTMORTEM_CAUSES}
      valueSeriesLabel="Incidents"
      cumulativeSeriesLabel="Cumulative impact"
      sortDirection="none"
      categoryLabelFormatter={(label) => label.replace(' ', '\n')}
      legend={{ show: true, position: 'right' }}
    />
  );
}
```

`data.ts`

```ts
export const POSTMORTEM_CAUSES = [
  { label: 'Configuration drift', value: 38 },
  { label: 'Dependency outage', value: 27 },
  { label: 'Release regression', value: 21 },
  { label: 'Capacity shortfall', value: 17 },
  { label: 'Access change', value: 13 },
  { label: 'Hardware failure', value: 11 },
  { label: 'DDoS attack', value: 9 },
  { label: 'Schema migration', value: 8 },
  { label: 'Data corruption', value: 7 },
  { label: 'Network partition', value: 6 },
  { label: 'Feature flag', value: 5 },
  { label: 'Manual error', value: 4 },
];
```

### Revenue Concentration

Examine how a few strategic accounts make up the bulk of recurring revenue.

```tsx
import { ParetoChart } from '@plocks/charts';

import { ACCOUNT_REVENUE } from './data';

export function Demo() {
  return (
    <ParetoChart
      title="Annual revenue concentration"
      subtitle="Top enterprise accounts"
      h={460}
      data={ACCOUNT_REVENUE}
      valueSeriesLabel="ARR"
      cumulativeSeriesLabel="Cumulative revenue"
      lineColor="#F97316"
      yAxis={{
        title: 'Recurring revenue',
        labelFormatter: (value) => `$${(value / 1_000_000).toFixed(1)}M`,
      }}
      yAxisRight={{
        title: 'Revenue share',
      }}
    />
  );
}
```

`data.ts`

```ts
export const ACCOUNT_REVENUE = [
  { label: 'Acme Corp', value: 2_480_000 },
  { label: 'Brightside', value: 1_940_000 },
  { label: 'Northwind', value: 1_275_000 },
  { label: 'Globex', value: 968_000 },
  { label: 'Initech', value: 744_000 },
  { label: 'Soylent', value: 612_000 },
  { label: 'Umbra', value: 481_000 },
  { label: 'LumenPay', value: 378_000 },
  { label: 'Veridian', value: 326_000 },
  { label: 'Terranova', value: 294_000 },
  { label: 'Zephyr', value: 242_000 },
  { label: 'BlueSky', value: 205_000 },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/PieChart.md -->

# Pie Chart

Proportional slice chart for categorical part-to-whole representation.

## Metadata

- Import: `import { PieChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, pie, categorical
- Docs: https://plocks.dev/charts/PieChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/PieChart

## Props

- `data` (required): PieChartDataPoint[] — Data points
- `innerRadius`: number — Inner radius (for donut chart)
- `outerRadius`: number — Outer radius
- `startAngle`: number — Start angle in degrees
- `endAngle`: number — End angle in degrees
- `padAngle`: number — Padding between slices
- `showLabels`: boolean — Show labels
- `showLabelsOnNarrow`: boolean — Keep outside labels visible below 400 px instead of showing details on selection.
- `labelPosition`: 'inside' | 'outside' | 'center' — Label position
- `labelStrategy`: 'auto' | 'inside' | 'outside' | 'center' — Automatically choose label placement
- `labelAutoSwitchAngle`: number — Minimum slice angle (deg) to keep label inside when strategy is auto
- `wrapLabels`: boolean — Automatically wrap labels that exceed width
- `labelMaxCharsPerLine`: number — Maximum characters per label line when wrapping
- `labelMaxLines`: number — Maximum number of lines when wrapping
- `showLeaderLines`: boolean — Render leader lines for outside labels
- `leaderLineColor`: string — Leader line stroke color
- `leaderLineWidth`: number — Leader line stroke width
- `labelTextStyle`: PieChartLabelTextStyle — Style overrides applied to rendered labels
- `labelFormatter`: (dataPoint: PieChartDataPoint) => string — Label formatter
- `showValues`: boolean — Show values
- `valueFormatter`: (value: number, total: number) => string — Value formatter
- `legend`: ChartLegend — Legend configuration
- `tooltip`: ChartTooltip<PieChartDataPoint> — Tooltip configuration
- `animation`: ChartAnimation — Animation configuration
- `highlightOnHover`: boolean — Enable hover highlighting
- `onSliceHover`: (slice: PieChartDataPoint | null) => void — Callback when hover target changes
- `defaultSliceStyle`: PieChartSliceStyle — Default style applied to slices
- `layers`: PieChartLayer[] — Additional rings rendered around the base series
- `legendToggleEnabled`: boolean — Allow toggling slice visibility from the legend
- `keyboardNavigation`: boolean — Enable keyboard navigation between slices
- `ariaLabelFormatter`: (slice: PieChartDataPoint, percentage: number) => string — Accessible label formatter

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface PieChartDataPoint {
  /** Unique identifier */
  id?: string | number;
  /** Value of the slice */
  value: number;
  /** Label for the slice */
  label: string;
  /** Color of the slice */
  color?: string;
  /** Custom data for interactions */
  data?: any;
  /** Style overrides for the slice */
  style?: PieChartSliceStyle;
}

export interface PieChartLabelTextStyle {
  /** Label text color */
  color?: string;
  /** Label font size */
  fontSize?: number;
  /** Label font weight */
  fontWeight?: string;
  /** Label font family */
  fontFamily?: string;
  /** Line height applied between wrapped lines */
  lineHeight?: number;
}

export interface PieChartSliceStyle {
  /** Stroke color override */
  strokeColor?: string;
  /** Stroke width override */
  strokeWidth?: number;
  /** Stroke opacity */
  strokeOpacity?: number;
  /** Fill opacity */
  fillOpacity?: number;
  /** Rounded corner radius in pixels (best with non-zero innerRadius) */
  cornerRadius?: number;
  /** Gradient fill configuration */
  gradient?: PieChartSliceGradient;
  /** Drop shadow configuration */
  shadow?: PieChartSliceShadow;
}

export interface PieChartLayer {
  /** Optional identifier for the layer */
  id?: string;
  /** Data points rendered in this ring */
  data: PieChartDataPoint[];
  /** Inner radius for the layer */
  innerRadius: number;
  /** Outer radius for the layer */
  outerRadius: number;
  /** Optional start angle override */
  startAngle?: number;
  /** Optional end angle override */
  endAngle?: number;
  /** Optional pad angle override */
  padAngle?: number;
}

export type PieChartSliceGradient = Omit<ChartGradient, 'extent'>;

export interface PieChartSliceShadow {
  /** Shadow color */
  color?: string;
  /** Horizontal offset */
  dx?: number;
  /** Vertical offset */
  dy?: number;
  /** Blur radius */
  blur?: number;
  /** Shadow opacity */
  opacity?: number;
}
```

## Examples

### Basics

Proportional slice chart for categorical part-to-whole representation.

```tsx
import { PieChart } from '@plocks/charts';

import { TRAFFIC_SOURCES } from './data';

export function Demo() {
  return (
    <PieChart
      title="Traffic sources"
      maw={560}
      h={360}
      data={TRAFFIC_SOURCES}
      innerRadius={70}
      outerRadius={150}
      showLabels={true}
      labelPosition="outside"
      showValues={true}
      valueFormatter={(value) => `${value}%`}
      legend={{ show: true, position: 'right' }}
      tooltip={{
        show: true,
        formatter: (segment) => `${segment.label}: ${segment.value}%`,
      }}
      startAngle={-90}
      endAngle={270}
    />
  );
}
```

`data.ts`

```ts
export const TRAFFIC_SOURCES = [
  { id: 'direct', label: 'Direct', value: 55 },
  { id: 'organic', label: 'Organic', value: 25 },
  { id: 'referral', label: 'Referral', value: 15 },
  { id: 'social', label: 'Social', value: 5 },
];
```

### Browser Usage Share

```tsx
import { PieChart, type PieChartDataPoint } from '@plocks/charts';

import { BROWSER_USAGE } from './data';

const formatLabel = (slice: PieChartDataPoint) => `${slice.label} ${slice.value}%`;

const formatTooltip = (slice: PieChartDataPoint) => `${slice.label}: ${slice.value}% of sessions`;

export function Demo() {
  return (
    <PieChart
      title="Browser usage share"
      subtitle="Active sessions"
      maw={520}
      h={420}
      data={BROWSER_USAGE}
      outerRadius={150}
      showLabels
      labelPosition="outside"
      padAngle={1.5}
      labelFormatter={formatLabel}
      legend={{ show: true, position: 'bottom' }}
      tooltip={{ show: true, formatter: formatTooltip }}
      animation={{ type: 'spiral', duration: 900 }}
      startAngle={-90}
      endAngle={270}
    />
  );
}
```

`data.ts`

```ts
export const BROWSER_USAGE = [
  { id: 'chrome', label: 'Chrome', value: 52 },
  { id: 'safari', label: 'Safari', value: 28 },
  { id: 'edge', label: 'Edge', value: 11 },
  { id: 'firefox', label: 'Firefox', value: 6 },
  { id: 'other', label: 'Other', value: 3 },
];
```

### Bug Type Distribution

```tsx
import { PieChart, type PieChartDataPoint } from '@plocks/charts';

import { BUG_TYPES } from './data';

const formatLabel = (slice: PieChartDataPoint) => `${slice.label} ${slice.value}%`;

const formatTooltip = (slice: PieChartDataPoint) => `${slice.label}: ${slice.value}% of release defects`;

export function Demo() {
  return (
    <PieChart
      title="Bug type distribution"
      subtitle="Latest release cycle"
      maw={560}
      h={380}
      data={BUG_TYPES}
      innerRadius={70}
      outerRadius={150}
      showLabels
      labelPosition="center"
      labelFormatter={formatLabel}
      padAngle={1}
      legend={{ show: true, position: 'right' }}
      tooltip={{ show: true, formatter: formatTooltip }}
      animation={{ type: 'bounce', duration: 800, stagger: 80 }}
      startAngle={-90}
      endAngle={270}
    />
  );
}
```

`data.ts`

```ts
export const BUG_TYPES = [
  { id: 'ui', label: 'UI', value: 38 },
  { id: 'api', label: 'API', value: 24 },
  { id: 'performance', label: 'Performance', value: 18 },
  { id: 'data', label: 'Data Quality', value: 12 },
  { id: 'security', label: 'Security', value: 5 },
  { id: 'infrastructure', label: 'Infrastructure', value: 3 },
];
```

### Operating Expense Composition

```tsx
import { PieChart, type PieChartDataPoint } from '@plocks/charts';

import { OPERATING_EXPENSES, TOTAL_EXPENSE } from './data';

const formatTooltip = (slice: PieChartDataPoint) => {
  const share = Math.round((slice.value / TOTAL_EXPENSE) * 100);
  return `${slice.label}: $${slice.value}M (${share}%)`;
};

export function Demo() {
  return (
    <PieChart
      title="Operating expense mix"
      subtitle="FY25 year-to-date"
      maw={520}
      h={440}
      data={OPERATING_EXPENSES}
      innerRadius={90}
      outerRadius={160}
      showLabels
      labelPosition="outside"
      padAngle={1.5}
      labelFormatter={(slice) => `${slice.label} · $${slice.value}M`}
      legend={{ show: true, position: 'bottom' }}
      tooltip={{ show: true, formatter: formatTooltip }}
      startAngle={-90}
      endAngle={270}
    />
  );
}
```

`data.ts`

```ts
export const OPERATING_EXPENSES = [
  { id: 'rnd', label: 'R&D', value: 42 },
  { id: 'marketing', label: 'Sales & Marketing', value: 34 },
  { id: 'operations', label: 'Operations', value: 28 },
  { id: 'ga', label: 'General & Admin', value: 18 },
  { id: 'it', label: 'IT & Security', value: 14 },
  { id: 'facilities', label: 'Facilities', value: 11 },
];

export const TOTAL_EXPENSE = OPERATING_EXPENSES.reduce((sum, slice) => sum + slice.value, 0);
```

### Support Channel Share

```tsx
import { PieChart, type PieChartDataPoint } from '@plocks/charts';

import { SUPPORT_CHANNELS, TOTAL_INTERACTIONS } from './data';

const toShare = (value: number) => Math.round((value / TOTAL_INTERACTIONS) * 100);

const formatLabel = (slice: PieChartDataPoint) => `${slice.label} ${toShare(slice.value)}%`;

const formatTooltip = (slice: PieChartDataPoint) => {
  const share = toShare(slice.value);
  return `${slice.label}: ${slice.value.toLocaleString()} interactions (${share}%)`;
};

export function Demo() {
  return (
    <PieChart
      title="Support contact mix"
      subtitle="Last 30 days"
      maw={580}
      h={380}
      data={SUPPORT_CHANNELS}
      innerRadius={80}
      outerRadius={150}
      showLabels
      labelPosition="outside"
      padAngle={1}
      labelFormatter={formatLabel}
      legend={{ show: true, position: 'right' }}
      tooltip={{ show: true, formatter: formatTooltip }}
      startAngle={-70}
      endAngle={290}
    />
  );
}
```

`data.ts`

```ts
export const SUPPORT_CHANNELS = [
  { id: 'chat', label: 'Live chat', value: 460 },
  { id: 'email', label: 'Email', value: 380 },
  { id: 'phone', label: 'Phone', value: 240 },
  { id: 'self-service', label: 'Self-service', value: 310 },
  { id: 'social', label: 'Social', value: 90 },
];

export const TOTAL_INTERACTIONS = SUPPORT_CHANNELS.reduce((sum, slice) => sum + slice.value, 0);
```

### Training Completion Share

```tsx
import { PieChart, type PieChartDataPoint } from '@plocks/charts';

import { TOTAL_COMPLETIONS, TRAINING_COMPLETIONS } from './data';

const toPercent = (value: number) => Math.round((value / TOTAL_COMPLETIONS) * 100);

const formatLabel = (slice: PieChartDataPoint) => `${slice.label} ${toPercent(slice.value)}%`;

const formatTooltip = (slice: PieChartDataPoint) => {
  const share = toPercent(slice.value);
  return `${slice.label}: ${slice.value.toLocaleString()} completions (${share}%)`;
};

export function Demo() {
  return (
    <PieChart
      title="Training completion share"
      subtitle="Annual compliance program"
      maw={520}
      h={440}
      data={TRAINING_COMPLETIONS}
      innerRadius={100}
      outerRadius={160}
      showLabels
      labelPosition="outside"
      padAngle={1.2}
      labelFormatter={formatLabel}
      legend={{ show: true, position: 'bottom' }}
      tooltip={{ show: true, formatter: formatTooltip }}
      animation={{ type: 'wave', duration: 900, stagger: 70 }}
      startAngle={-100}
      endAngle={260}
    />
  );
}
```

`data.ts`

```ts
export const TRAINING_COMPLETIONS = [
  { id: 'engineering', label: 'Engineering', value: 320 },
  { id: 'product', label: 'Product', value: 180 },
  { id: 'success', label: 'Customer Success', value: 150 },
  { id: 'sales', label: 'Sales', value: 210 },
  { id: 'operations', label: 'Operations', value: 140 },
  { id: 'people', label: 'People', value: 90 },
];

export const TOTAL_COMPLETIONS = TRAINING_COMPLETIONS.reduce((sum, slice) => sum + slice.value, 0);
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/RadarChart.md -->

# Radar Chart

Displays multivariate data across axes starting from the same origin.

## Metadata

- Import: `import { RadarChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, radar, polar
- Docs: https://plocks.dev/charts/RadarChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/RadarChart

## Props

- `series` (required): RadarChartSeries[] — Radar series to display
- `maxValue`: number — Maximum value displayed across axes
- `radialGrid`: RadarGridConfig — Grid styling configuration
- `smooth`: boolean | number — Smooth the polygon edges; pass a number between 0 and 1 to control tension
- `fill`: boolean = true — Fill the radar area
- `enableCrosshair`: boolean — Enable radial crosshair highlights
- `multiTooltip`: boolean — Enable multi-series tooltip aggregation
- `liveTooltip`: boolean — Follow pointer with tooltip
- `legend`: ChartLegend — Legend configuration
- `tooltip`: ChartTooltip<RadarAxisPoint> — Tooltip configuration

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface RadarChartSeries {
  /** Unique identifier for the series */
  id?: string | number;
  /** Display name for the series */
  name?: string;
  /** Data points included in the series */
  data: RadarAxisPoint[];
  /** Base color applied to the series */
  color?: string;
  /** Whether the series is visible */
  visible?: boolean;
  /** Opacity applied to the filled area */
  opacity?: number;
  /** Show point markers at each axis */
  showPoints?: boolean;
  /** Size of the point markers */
  pointSize?: number;
  /** Additional metadata associated with the series */
  metadata?: any;
}

export interface RadarGridConfig {
  /** Number of concentric rings rendered */
  rings?: number;
  /** Shape used for the grid (circle or polygon) */
  shape?: 'circle' | 'polygon';
  /** Whether to render axis spokes */
  showAxes?: boolean;
  /** Placement of axis labels */
  axisLabelPlacement?: 'inside' | 'edge' | 'outside';
  /** Offset in pixels applied to axis labels */
  axisLabelOffset?: number;
  /** Keep full spoke labels on narrow charts even when they would shrink the plot. */
  showFullLabelsOnNarrow?: boolean;
  /** Custom formatter for axis labels */
  axisLabelFormatter?: (
    axis: string | number,
    context: { index: number; total: number; label?: string }
  ) => string;
  /** Optional labels for each ring */
  ringLabels?:
    | string[]
    | ((context: { index: number; ringCount: number; value: number; maxValue: number }) => string);
  /** Where to position ring labels relative to the ring */
  ringLabelPosition?: 'inside' | 'outside';
  /** Offset in pixels applied to ring labels */
  ringLabelOffset?: number;
}

export interface RadarAxisPoint {
  /** Axis key associated with the point */
  axis: string | number;
  /** Value plotted on the axis */
  value: number;
  /** Optional label displayed for the point */
  label?: string;
  /** Color override for the point */
  color?: string;
  /** Optional value override used for tooltip output */
  formattedValue?: string | number;
  /** Custom tooltip content for the point */
  tooltip?: ReactNode | ((point: RadarAxisPoint, context: { axisIndex: number; seriesIndex: number; series: RadarChartSeries }) => ReactNode);
  /** Additional metadata associated with the point */
  meta?: any;
}
```

## Examples

### Skill Comparison

Comparison of three engineering guilds with polygon grid, crosshair, and aggregated tooltip.

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Engineering guild comparison"
      subtitle="Quarterly capability radar"
      maw={700}
      h={440}
      series={SERIES}
      maxValue={100}
      radialGrid={{ rings: 5, shape: 'polygon', showAxes: true }}
      enableCrosshair
      multiTooltip
      liveTooltip
      legend={{ show: true, position: 'right', align: 'start' }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.axis}: ${Math.round(point.value)}%`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = [
  'Code quality',
  'Delivery speed',
  'Testing coverage',
  'Observability',
  'Collaboration',
  'Innovation',
];

export const buildSeriesData = (values: number[]) =>
  AXES.map((axis, index) => ({ axis, value: values[index] }));

export const SERIES = [
  {
    id: 'frontend-guild',
    name: 'Frontend guild',
    showPoints: true,
    pointSize: 4,
    data: buildSeriesData([92, 84, 78, 86, 90, 74]),
  },
  {
    id: 'platform-guild',
    name: 'Platform guild',
    showPoints: true,
    pointSize: 4,
    data: buildSeriesData([88, 79, 91, 93, 82, 70]),
  },
  {
    id: 'qa-guild',
    name: 'QA guild',
    showPoints: true,
    pointSize: 4,
    data: buildSeriesData([80, 72, 95, 88, 76, 68]),
  },
];
```

### Product Health

Product health snapshot with circular grid, point markers, and custom tooltip messaging.

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Product health radar"
      subtitle="Operational score vs. strategic goal"
      maw={580}
      h={440}
      series={SERIES}
      maxValue={10}
      radialGrid={{ rings: 4, shape: 'circle', showAxes: false }}
      enableCrosshair
      legend={{ show: true, position: 'bottom', align: 'center' }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.axis}: ${point.value.toFixed(1)} / 10`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = [
  'Availability',
  'Latency',
  'NPS',
  'Feature velocity',
  'Security posture',
  'Cost efficiency',
];

export const makeSeriesData = (values: number[]) =>
  AXES.map((axis, index) => ({ axis, value: values[index] }));

export const SERIES = [
  {
    id: 'current-health',
    name: 'Current health',
    showPoints: true,
    pointSize: 3,
    data: makeSeriesData([8.4, 7.2, 6.8, 7.5, 8.8, 6.2]),
  },
  {
    id: 'target-health',
    name: 'Target health',
    showPoints: true,
    pointSize: 3,
    data: makeSeriesData([9.2, 8.6, 8.1, 8.5, 9.0, 7.5]),
  },
];
```

### Basics

Displays multivariate data across axes starting from the same origin.

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Team capability radar"
      maw={560}
      h={380}
      series={SERIES}
      maxValue={60}
      radialGrid={{ rings: 5, shape: 'polygon', showAxes: true }}
      smooth
      fill
      enableCrosshair
      multiTooltip
      liveTooltip
      legend={{ show: true, position: 'bottom' }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.axis}: ${point.value}`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'current',
    name: 'Current quarter',
    data: [
      { axis: 'Sales', value: 42 },
      { axis: 'Marketing', value: 30 },
      { axis: 'R&D', value: 50 },
      { axis: 'Support', value: 35 },
      { axis: 'Operations', value: 24 },
      { axis: 'Finance', value: 18 },
    ],
  },
  {
    id: 'target',
    name: 'Target',
    data: [
      { axis: 'Sales', value: 48 },
      { axis: 'Marketing', value: 36 },
      { axis: 'R&D', value: 44 },
      { axis: 'Support', value: 40 },
      { axis: 'Operations', value: 28 },
      { axis: 'Finance', value: 22 },
    ],
  },
];
```

### Data Platform Maturity

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Data platform maturity"
      subtitle="Governance and enablement dimensions"
      maw={620}
      h={480}
      series={SERIES}
      maxValue={5}
      fill
      enableCrosshair
      multiTooltip
      legend={{ show: true, position: 'bottom', align: 'center' }}
      radialGrid={{
        rings: 5,
        shape: 'polygon',
        axisLabelPlacement: 'outside',
        axisLabelOffset: 24,
        ringLabels: [
          'Ad hoc',
          'Emerging',
          'Defined',
          'Managed',
          'Optimized',
        ],
        ringLabelPosition: 'outside',
        ringLabelOffset: 16,
      }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.label ?? point.axis}: ${point.value.toFixed(1)} / 5`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = [
  { axis: 'governance', label: 'Data\nGovernance' },
  { axis: 'quality', label: 'Data\nQuality' },
  { axis: 'lineage', label: 'Lineage &\nCataloguing' },
  { axis: 'selfServe', label: 'Self-service\nEnablement' },
  { axis: 'automation', label: 'Automation &\nObservability' },
  { axis: 'culture', label: 'Culture &\nLiteracy' },
];

export const maturityLabel = (value: number) => {
  if (value >= 4.5) return 'Optimized';
  if (value >= 3.5) return 'Managed';
  if (value >= 2.5) return 'Defined';
  if (value >= 1.5) return 'Emerging';
  return 'Ad hoc';
};

export const assembleSeries = (values: number[]) =>
  AXES.map(({ axis, label }, index) => {
    const value = values[index];
    return {
      axis,
      value,
      label,
      formattedValue: `${value.toFixed(1)} / 5`,
      tooltip: `${value.toFixed(1)} / 5 • ${maturityLabel(value)}`,
    };
  });

export const SERIES = [
  {
    id: 'current',
    name: 'Current state',
    showPoints: true,
    pointSize: 4,
    data: assembleSeries([2.3, 2.8, 2.2, 1.9, 2.5, 2.1]),
  },
  {
    id: 'target',
    name: 'Target FY24',
    showPoints: true,
    pointSize: 4,
    data: assembleSeries([3.6, 3.8, 3.4, 3.2, 3.5, 3.3]),
  },
  {
    id: 'leader',
    name: 'Industry leader benchmark',
    showPoints: true,
    pointSize: 4,
    data: assembleSeries([4.5, 4.6, 4.4, 4.2, 4.5, 4.3]),
  },
];
```

### Engineering Readiness

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Engineering readiness radar"
      subtitle="Security, reliability, scalability, performance, maintainability"
      maw={600}
      h={440}
      series={SERIES}
      maxValue={5}
      fill
      enableCrosshair
      legend={{ show: true, position: 'bottom' }}
      radialGrid={{
        rings: 5,
        shape: 'circle',
        showAxes: true,
        axisLabelPlacement: 'outside',
        ringLabels: [
          'Reactive',
          'Developing',
          'Consistent',
          'Resilient',
          'Elite',
        ],
        ringLabelPosition: 'inside',
        ringLabelOffset: 18,
      }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.axis}: ${point.value.toFixed(1)} readiness`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = ['Security', 'Reliability', 'Scalability', 'Performance', 'Maintainability'];

export const createSeries = (values: number[]) =>
  AXES.map((axis, index) => {
    const value = values[index];
    return {
      axis,
      value,
      formattedValue: `${value.toFixed(1)} / 5`,
    };
  });

export const SERIES = [
  {
    id: 'current',
    name: 'Current posture',
    showPoints: true,
    pointSize: 4,
    data: createSeries([2.6, 3.1, 2.8, 3.4, 2.9]),
  },
  {
    id: 'target',
    name: 'Target readiness',
    showPoints: true,
    pointSize: 4,
    data: createSeries([4.2, 4.4, 4.1, 4.3, 4.0]),
  },
];
```

### Market Perception Interviews

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Market perception signal"
      subtitle="Customer interview scorecard"
      maw={700}
      h={460}
      series={SERIES}
      maxValue={5}
      fill
      enableCrosshair
      multiTooltip
      legend={{ show: true, position: 'right', align: 'center' }}
      radialGrid={{
        rings: 5,
        shape: 'polygon',
        axisLabelPlacement: 'outside',
        axisLabelOffset: 18,
        ringLabels: ({ index }) => ['Poor', 'Fair', 'Good', 'Great', 'Exceptional'][index],
      }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.label ?? point.axis}: ${point.value.toFixed(1)} / 5`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = [
  { axis: 'ease', label: 'Ease of\nUse' },
  { axis: 'feature', label: 'Feature\nDepth' },
  { axis: 'innovation', label: 'Innovation\nStory' },
  { axis: 'trust', label: 'Trust &\nCredibility' },
  { axis: 'support', label: 'Support\nExperience' },
  { axis: 'value', label: 'Value for\nMoney' },
];

export const buildSeries = (values: number[]) =>
  AXES.map(({ axis, label }, index) => {
    const value = values[index];
    return {
      axis,
      value,
      label,
      formattedValue: `${value.toFixed(1)} / 5`,
    };
  });

export const SERIES = [
  {
    id: 'customers',
    name: 'Existing customers',
    showPoints: true,
    pointSize: 4,
    data: buildSeries([4.6, 4.1, 4.3, 4.4, 4.7, 4.2]),
  },
  {
    id: 'prospects',
    name: 'Active prospects',
    showPoints: true,
    pointSize: 4,
    data: buildSeries([4.2, 3.8, 4.0, 4.1, 3.9, 4.0]),
  },
  {
    id: 'analysts',
    name: 'Industry analysts',
    showPoints: true,
    pointSize: 4,
    data: buildSeries([4.4, 4.3, 4.5, 4.2, 4.0, 4.1]),
  },
];
```

### Product Capability Benchmark

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Product capability vs. competition"
      subtitle="Benchmarking core differentiators"
      maw={620}
      h={460}
      series={SERIES}
      maxValue={10}
      fill
      enableCrosshair
      legend={{ show: true, position: 'bottom', align: 'center' }}
      radialGrid={{
        rings: 5,
        shape: 'polygon',
        showAxes: true,
        axisLabelPlacement: 'outside',
        axisLabelOffset: 20,
        ringLabels: [
          'Baseline',
          'Market ready',
          'Parity',
          'Differentiated',
          'Category leader',
        ],
      }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.label ?? point.axis}: ${point.value.toFixed(1)} / 10`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = [
  { axis: 'ai', label: 'AI Assist' },
  { axis: 'integrations', label: 'Integration\nEcosystem' },
  { axis: 'analytics', label: 'Analytics\nDepth' },
  { axis: 'scale', label: 'Enterprise\nScalability' },
  { axis: 'security', label: 'Security\n& Compliance' },
  { axis: 'ux', label: 'User\nExperience' },
];

export const buildSeries = (values: number[]) =>
  AXES.map(({ axis, label }, index) => {
    const value = values[index];
    return {
      axis,
      value,
      label,
      formattedValue: `${value.toFixed(1)} / 10`,
    };
  });

export const SERIES = [
  {
    id: 'ours',
    name: 'Our platform',
    showPoints: true,
    pointSize: 4,
    data: buildSeries([8.4, 7.8, 8.9, 8.7, 9.4, 8.6]),
  },
  {
    id: 'competitor-a',
    name: 'Competitor Alpha',
    showPoints: true,
    pointSize: 4,
    data: buildSeries([7.6, 8.4, 8.1, 8.2, 8.9, 7.5]),
  },
  {
    id: 'competitor-b',
    name: 'Competitor Beta',
    showPoints: true,
    pointSize: 4,
    data: buildSeries([6.8, 7.4, 7.5, 7.9, 8.1, 6.9]),
  },
];
```

### Skills Gap Role Family

```tsx
import { RadarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RadarChart
      title="Role family skills gap analysis"
      subtitle="Percent attainment against competency targets"
      maw={720}
      h={480}
      series={SERIES}
      maxValue={100}
      fill
      enableCrosshair
      multiTooltip
      legend={{ show: true, position: 'right', align: 'start' }}
      radialGrid={{
        rings: 4,
        shape: 'polygon',
        axisLabelPlacement: 'outside',
        axisLabelOffset: 24,
        ringLabels: ({ value }) => `${Math.round(value)} pts`,
      }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.label ?? point.axis}: ${Math.round(point.value)} / 100`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const AXES = [
  { axis: 'strategy', label: 'Product\nStrategy' },
  { axis: 'delivery', label: 'Delivery\nExecution' },
  { axis: 'customer', label: 'Customer\nInsight' },
  { axis: 'collaboration', label: 'Cross-team\nCollaboration' },
  { axis: 'quality', label: 'Quality &\nReliability' },
];

export const makeSeries = (values: number[]) =>
  AXES.map(({ axis, label }, index) => {
    const value = values[index];
    return {
      axis,
      value,
      label,
      formattedValue: `${value} pts`,
    };
  });

export const SERIES = [
  {
    id: 'target',
    name: 'Target capability',
    showPoints: true,
    pointSize: 4,
    data: makeSeries([92, 90, 95, 94, 93]),
  },
  {
    id: 'engineering',
    name: 'Engineering org',
    showPoints: true,
    pointSize: 4,
    data: makeSeries([88, 82, 76, 84, 80]),
  },
  {
    id: 'product',
    name: 'Product org',
    showPoints: true,
    pointSize: 4,
    data: makeSeries([86, 78, 90, 88, 82]),
  },
  {
    id: 'design',
    name: 'Design org',
    showPoints: true,
    pointSize: 4,
    data: makeSeries([80, 70, 88, 90, 76]),
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/RadialBarChart.md -->

# Radial Bar Chart

Circular bar segments representing values radially.

## Metadata

- Import: `import { RadialBarChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, radial, bar
- Docs: https://plocks.dev/charts/RadialBarChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/RadialBarChart

## Props

- `data` (required): RadialBarDatum[] — Radial bar data to render
- `radius`: number — Radius of outer ring (auto if not provided)
- `barThickness`: number = 14 — Thickness of each arc
- `gap`: number = 8 — Gap (px) between concentric bars
- `startAngle`: number = -90 — Start angle in degrees (default -90 = top)
- `endAngle`: number = 270 — End angle in degrees (default 270 for full circle)
- `showValueLabels`: boolean = true — Show value labels at the tip of each arc
- `showValueLabelsOnNarrow`: boolean = false — Keep tip labels visible below 400 px even when they crowd the center readout.
- `valueFormatter`: (value: number, datum: RadialBarDatum, index: number) => string — Format value for label
- `centerLabel`: string — Primary text rendered in the empty center (e.g. an aggregate value)
- `centerSubLabel`: string — Secondary text rendered beneath the center label
- `multiTooltip`: boolean = true — Enable aggregated tooltip across arcs
- `liveTooltip`: boolean = true — Keep tooltip following the pointer
- `enableCrosshair`: boolean = false — Highlight the hovered ring (dim the others) on pointer interaction. Default false.
- `legend`: ChartLegend — Legend configuration
- `tooltip`: ChartTooltip<RadialBarDatum> — Tooltip configuration

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface RadialBarDatum {
  /** Unique identifier for the datum */
  id?: string | number;
  /** Numeric value represented by the arc */
  value: number;
  /** Optional per-datum maximum value */
  max?: number;
  /** Label displayed near the arc */
  label?: string;
  /** Color applied to the arc */
  color?: string;
  /** Track color rendered beneath the arc */
  trackColor?: string;
  /** Additional metadata associated with the datum */
  data?: any;
}
```

## Examples

### Basics

Concentric rings compare progress across several metrics, with tip labels and a center average.

```tsx
import { RadialBarChart } from '@plocks/charts';

import { AVG, METRICS } from './data';

export function Demo() {
	return (
		<RadialBarChart
			title="Quarterly KPIs"
			subtitle="Progress toward goals"
			maw={400}
			h={400}
			data={METRICS}
			barThickness={18}
			gap={12}
			showValueLabels
			valueFormatter={(value) => `${value}%`}
			centerLabel={`${AVG}%`}
			centerSubLabel="Avg score"
			multiTooltip
			liveTooltip
			legend={{ show: true, position: 'bottom' }}
		/>
	);
}
```

`data.ts`

```ts
export const METRICS = [
	{ id: 'uptime', label: 'Uptime', value: 99, max: 100, color: '#4C6EF5', trackColor: '#E3E9FF' },
	{ id: 'nps', label: 'NPS', value: 72, max: 100, color: '#20C997', trackColor: '#DEF7EE' },
	{ id: 'retention', label: 'Retention', value: 86, max: 100, color: '#FF922B', trackColor: '#FFE8D7' },
	{ id: 'sla', label: 'SLA', value: 94, max: 100, color: '#845EF7', trackColor: '#EFE6FF' },
];

export const AVG = Math.round(METRICS.reduce((sum, m) => sum + m.value, 0) / METRICS.length);
```

### Goal Progress Ring

A single thick ring with a center readout — ideal for one headline metric.

```tsx
import { RadialBarChart } from '@plocks/charts';

import { GOAL } from './data';

export function Demo() {
	return (
		<RadialBarChart
			title="Fundraising Goal"
			subtitle="$74k raised of $100k"
			maw={300}
			h={300}
			data={GOAL}
			barThickness={24}
			showValueLabels={false}
			centerLabel="74%"
			centerSubLabel="of goal"
			multiTooltip
			liveTooltip
		/>
	);
}
```

`data.ts`

```ts
export const GOAL = [
	{ id: 'raised', label: 'Raised', value: 74, max: 100, color: '#7048E8', trackColor: '#ECE6FF' },
];
```

### Semicircle Gauge

Set startAngle/endAngle to a 180° sweep for a speedometer-style gauge that fills the space.

```tsx
import { RadialBarChart } from '@plocks/charts';

import { SCORE } from './data';

export function Demo() {
	return (
		<RadialBarChart
			title="Customer Satisfaction"
			subtitle="Rolling 30-day CSAT"
			maw={340}
			h={240}
			startAngle={-90}
			endAngle={90}
			data={SCORE}
			barThickness={24}
			showValueLabels={false}
			centerLabel="82"
			centerSubLabel="out of 100"
			multiTooltip
			liveTooltip
		/>
	);
}
```

`data.ts`

```ts
export const SCORE = [
	{ id: 'csat', label: 'CSAT', value: 82, max: 100, color: '#20C997', trackColor: '#DEF7EE' },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/RidgeChart.md -->

# Ridge Chart

Layered density plots (joyplot) comparing distributions across categories.

## Metadata

- Import: `import { RidgeChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, ridge, density
- Docs: https://plocks.dev/charts/RidgeChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/RidgeChart

## Props

- `series` (required): DensitySeries[] — Density series rendered in the ridge chart
- `samples`: number — Density sample resolution
- `bandwidth`: number — Kernel bandwidth override
- `bandPadding`: number — Fractional padding between ridge bands (0 - 0.8)
- `amplitudeScale`: number — Amplitude scaling applied to each ridge (0.1 - 1)
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid line configuration
- `statsMarkers`: RidgeStatsMarkersConfig — Optional statistic marker configuration

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface DensitySeries {
  /** Unique identifier for the series */
  id?: string | number;
  /** Display name for the series */
  name?: string;
  /** Source values used to compute the density */
  values: number[];
  /** Base color applied to the density curve */
  color?: string;
  /** Whether the series is visible */
  visible?: boolean;
  /** Opacity applied to the filled area */
  fillOpacity?: number;
  /** Stroke color for the ridge outline */
  strokeColor?: string;
  /** Stroke width for the ridge outline */
  strokeWidth?: number;
  /** Unit label appended to tooltip values */
  unit?: string;
  /** Custom formatter for value labels */
  valueFormatter?: (value: number) => string;
  /** Custom tooltip content for each value */
  tooltipFormatter?: (context: RidgeTooltipContext) => ReactNode;
}

export interface RidgeStatsMarkersConfig {
  /** Master enable toggle; defaults to false unless show flags set */
  enabled?: boolean;
  /** Show mean marker (defaults to true when enabled) */
  showMean?: boolean;
  /** Show median marker (defaults to true when enabled) */
  showMedian?: boolean;
  /** Show p90 marker (defaults to false) */
  showP90?: boolean;
  /** Marker line height in px (auto if omitted) */
  markerHeight?: number;
  /** Marker stroke width (defaults to 2) */
  strokeWidth?: number;
  /** Custom colors per statistic */
  colors?: Partial<Record<'mean' | 'median' | 'p90', string>>;
  /** Render value labels near markers */
  showLabels?: boolean;
  /** Offset for labels above marker tip (defaults to 6) */
  labelOffset?: number;
  /** Optional formatter for marker label */
  labelFormatter?: (params: { stat: 'mean' | 'median' | 'p90'; value: number; formattedValue: string; series: DensitySeries }) => string;
}

export interface RidgeTooltipContext {
  value: number;
  /** Normalized (0-1) density height */
  density: number;
  /** Estimated probability mass for this sample */
  probability: number;
  /** Raw probability density function value */
  pdf: number;
  index: number;
  seriesIndex: number;
  series: {
    id?: string | number;
    name?: string;
    color?: string;
    unit?: string;
    stats?: RidgeSeriesStats | null;
  };
}

export interface RidgeSeriesStats {
  mean?: number;
  median?: number;
  p90?: number;
}
```

## Examples

### Basics

Layered density plots (joyplot) comparing distributions across categories.

```tsx
import { RidgeChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
	return (
		<RidgeChart
			title="Customer satisfaction distribution"
			subtitle="Annual NPS density"
			h={360}
			series={SERIES}
			samples={96}
			bandwidth={3}
			statsMarkers={{ enabled: true, showP90: true, showLabels: true }}
		/>
	);
}
```

`data.ts`

```ts
export const SERIES = [
	{
		id: '2019',
		name: '2019',
		values: [
			42, 44, 45, 46, 47, 48, 49, 49, 50, 52, 53, 54, 55, 55, 55, 57, 58, 60, 62,
		],
	},
	{
		id: '2020',
		name: '2020',
		values: [
			38, 39, 40, 41, 42, 43, 44, 46, 48, 50, 51, 51, 52, 53, 53, 54, 55, 57, 59,
		],
	},
	{
		id: '2021',
		name: '2021',
		values: [
			45, 47, 48, 49, 50, 51, 52, 53, 55, 56, 57, 58, 59, 59, 60, 61, 62, 63, 64,
		],
	},
	{
		id: '2022',
		name: '2022',
		values: [
			50, 51, 52, 54, 55, 56, 57, 58, 60, 61, 62, 63, 64, 65, 65, 66, 67, 68, 69,
		],
	},
];
```

### Api Latency Endpoints

```tsx
import { RidgeChart } from '@plocks/charts';

import { SERIES, formatLatency } from './data';

export function Demo() {
  return (
    <RidgeChart
      title="API latency distribution by endpoint"
      subtitle="Density of response times across rolling deployments"
      h={450}
      series={SERIES}
      samples={128}
      bandwidth={16}
      bandPadding={0.24}
      amplitudeScale={0.92}
      grid={{ show: true, showMinor: false }}
      xAxis={{
        show: true,
        title: 'Latency (ms)',
        labelFormatter: (value) => formatLatency(value as number),
      }}
      yAxis={{
        show: true,
        tickLength: 6,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SAMPLE_POINTS = 170;

export const createLatencyProfile = (base: number, jitter: number, tail: number) =>
  Array.from({ length: SAMPLE_POINTS }, (_, index) => {
    const diurnal = Math.sin(index / 7) * jitter;
    const deployWave = Math.max(0, Math.sin((index - 28) / 16)) * tail;
    const background = Math.cos(index / 4.5) * jitter * 0.3;
    const heavyTail = Math.pow(Math.sin((index + 12) / 40), 6) * tail * 1.8;
    const value = base + diurnal + deployWave + background + heavyTail;
    return Number(Math.max(48, value).toFixed(1));
  });

export const formatLatency = (value: number) => `${Math.round(value)} ms`;

export const latencyTooltip = ({ value, density, series }: any) => {
  const p90 = series?.stats?.p90;
  const p90Label = p90 != null ? ` • p90 ${formatLatency(p90)}` : '';
  return `${formatLatency(value)} • density ${(density * 100).toFixed(1)}%${p90Label}`;
};

export const SERIES = [
  {
    id: 'projects',
    name: 'GET /projects',
    values: createLatencyProfile(210, 48, 160),
    fillOpacity: 0.64,
    strokeWidth: 1.2,
    valueFormatter: formatLatency,
    tooltipFormatter: latencyTooltip,
  },
  {
    id: 'reports',
    name: 'GET /reports',
    values: createLatencyProfile(260, 52, 210),
    fillOpacity: 0.64,
    strokeWidth: 1.2,
    valueFormatter: formatLatency,
    tooltipFormatter: latencyTooltip,
  },
  {
    id: 'ingest',
    name: 'POST /ingest',
    values: createLatencyProfile(340, 60, 280),
    fillOpacity: 0.64,
    strokeWidth: 1.2,
    valueFormatter: formatLatency,
    tooltipFormatter: latencyTooltip,
  },
  {
    id: 'search',
    name: 'GET /search',
    values: createLatencyProfile(180, 44, 150),
    fillOpacity: 0.64,
    strokeWidth: 1.2,
    valueFormatter: formatLatency,
    tooltipFormatter: latencyTooltip,
  },
  {
    id: 'billing',
    name: 'POST /billing',
    values: createLatencyProfile(400, 66, 320),
    fillOpacity: 0.64,
    strokeWidth: 1.2,
    valueFormatter: formatLatency,
    tooltipFormatter: latencyTooltip,
  },
];
```

### Daily Active Users Cohorts

```tsx
import { RidgeChart } from '@plocks/charts';

import { SERIES, formatThousands } from './data';

export function Demo() {
  return (
    <RidgeChart
      title="Daily active users across feature cohorts"
      subtitle="Distribution of session counts over the last six months"
      h={480}
      series={SERIES}
      samples={128}
      bandwidth={18}
      bandPadding={0.32}
      amplitudeScale={0.95}
      grid={{ show: true, showMinor: false }}
      xAxis={{
        show: true,
        title: 'Daily active users',
        labelFormatter: (value) => formatThousands.format(Math.round(value as number)),
        tickLength: 6,
      }}
      yAxis={{
        show: true,
        tickLength: 6,
      }}
    />
  );
}
```

`data.ts`

```ts
export const DAYS = 180;

export const createCohort = (base: number, amplitude: number, lift: number) =>
  Array.from({ length: DAYS }, (_, day) => {
    const seasonal = Math.sin(day / 12) * amplitude;
    const adoption = Math.max(0, Math.sin((day - 36) / 28)) * lift;
    const engagementCycle = Math.cos(day / 3.6) * amplitude * 0.18;
    const trend = (day / DAYS) * lift * 0.45;
    const value = base + seasonal + adoption + engagementCycle + trend;
    return Math.max(120, Math.round(value));
  });

export const formatUsers = (value: number) => `${Math.round(value).toLocaleString()} users`;

export const userDensityTooltip = ({ value, density, series }: any) => {
  const median = series?.stats?.median;
  const medianLabel = median != null ? ` • median ${Math.round(median).toLocaleString()} users` : '';
  return `${Math.round(value).toLocaleString()} users • density ${(density * 100).toFixed(1)}%${medianLabel}`;
};

export const SERIES = [
  {
    id: 'core-product',
    name: 'Core product cohort',
    values: createCohort(420, 48, 96),
    fillOpacity: 0.68,
    strokeWidth: 1.4,
    valueFormatter: formatUsers,
    tooltipFormatter: userDensityTooltip,
  },
  {
    id: 'collaboration-suite',
    name: 'Collaboration suite',
    values: createCohort(360, 42, 78),
    fillOpacity: 0.68,
    strokeWidth: 1.4,
    valueFormatter: formatUsers,
    tooltipFormatter: userDensityTooltip,
  },
  {
    id: 'automation',
    name: 'Automation workflows',
    values: createCohort(260, 36, 64),
    fillOpacity: 0.68,
    strokeWidth: 1.4,
    valueFormatter: formatUsers,
    tooltipFormatter: userDensityTooltip,
  },
  {
    id: 'ai-features',
    name: 'AI assistant features',
    values: createCohort(180, 34, 72),
    fillOpacity: 0.68,
    strokeWidth: 1.4,
    valueFormatter: formatUsers,
    tooltipFormatter: userDensityTooltip,
  },
  {
    id: 'mobile-experience',
    name: 'Mobile experience',
    values: createCohort(220, 32, 58),
    fillOpacity: 0.68,
    strokeWidth: 1.4,
    valueFormatter: formatUsers,
    tooltipFormatter: userDensityTooltip,
  },
];

export const formatThousands = new Intl.NumberFormat('en-US', { maximumFractionDigits: 0 });
```

### Employee Satisfaction Survey

```tsx
import { RidgeChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <RidgeChart
      title="Employee satisfaction score distribution"
      subtitle="Quarterly pulse survey responses by team"
      h={420}
      series={SERIES}
      samples={110}
      bandwidth={0.35}
      bandPadding={0.3}
      amplitudeScale={0.85}
      grid={{ show: true, showMinor: false }}
      xAxis={{
        show: true,
        title: 'Satisfaction score (1-5)',
        labelFormatter: (value) => (value as number).toFixed(1),
        tickLength: 6,
      }}
      yAxis={{
        show: true,
        tickLength: 6,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SAMPLE_POINTS = 140;

export const createScoreProfile = (baseline: number, amplitude: number, lift: number) =>
  Array.from({ length: SAMPLE_POINTS }, (_, index) => {
    const seasonal = Math.sin(index / 9.5) * amplitude;
    const programLift = Math.max(0, Math.sin((index - 24) / 20)) * lift;
    const sentimentNoise = Math.cos(index / 3.4) * amplitude * 0.2;
    const value = baseline + seasonal + programLift + sentimentNoise;
    const clamped = Math.min(4.95, Math.max(1.05, value));
    return Number(clamped.toFixed(2));
  });

export const formatScore = (value: number) => `${value.toFixed(1)} / 5`;

export const satisfactionTooltip = ({ value, density, series }: any) => {
  const median = series?.stats?.median;
  const medianLabel = median != null ? ` • median ${formatScore(median)}` : '';
  return `${formatScore(value)} • density ${(density * 100).toFixed(1)}%${medianLabel}`;
};

export const SERIES = [
  {
    id: 'product',
    name: 'Product management',
    values: createScoreProfile(3.8, 0.32, 0.42),
    fillOpacity: 0.7,
    strokeWidth: 1.2,
    valueFormatter: formatScore,
    tooltipFormatter: satisfactionTooltip,
  },
  {
    id: 'platform',
    name: 'Platform engineering',
    values: createScoreProfile(4.1, 0.3, 0.36),
    fillOpacity: 0.7,
    strokeWidth: 1.2,
    valueFormatter: formatScore,
    tooltipFormatter: satisfactionTooltip,
  },
  {
    id: 'success',
    name: 'Customer success',
    values: createScoreProfile(3.6, 0.36, 0.48),
    fillOpacity: 0.7,
    strokeWidth: 1.2,
    valueFormatter: formatScore,
    tooltipFormatter: satisfactionTooltip,
  },
  {
    id: 'gtm',
    name: 'Go-to-market teams',
    values: createScoreProfile(3.4, 0.4, 0.52),
    fillOpacity: 0.7,
    strokeWidth: 1.2,
    valueFormatter: formatScore,
    tooltipFormatter: satisfactionTooltip,
  },
];
```

### Revenue Transaction Density

```tsx
import { RidgeChart } from '@plocks/charts';

import { SERIES, currencyFormatter } from './data';

export function Demo() {
  return (
    <RidgeChart
      title="Revenue per transaction by product line"
      subtitle="Transaction value distributions across seasonal cycles"
      h={440}
      series={SERIES}
      samples={128}
      bandwidth={14}
      bandPadding={0.28}
      amplitudeScale={0.9}
      grid={{ show: true, showMinor: false }}
      xAxis={{
        show: true,
        title: 'Revenue per transaction',
        labelFormatter: (value) => currencyFormatter.format(value as number),
      }}
      yAxis={{
        show: true,
        tickLength: 6,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SAMPLE_POINTS = 180;

export const createRevenueProfile = (base: number, amplitude: number, tail: number) =>
  Array.from({ length: SAMPLE_POINTS }, (_, index) => {
    const seasonal = Math.sin(index / 9) * amplitude;
    const promotional = Math.max(0, Math.sin((index - 24) / 18)) * tail;
    const variability = Math.cos(index / 4.8) * amplitude * 0.22;
    const enterpriseTail = Math.pow(Math.sin((index + 18) / 48), 4) * tail * 1.4;
    const value = base + seasonal + promotional + variability + enterpriseTail;
    return Number(Math.max(12, value).toFixed(2));
  });

export const currencyFormatter = new Intl.NumberFormat('en-US', {
  style: 'currency',
  currency: 'USD',
  maximumFractionDigits: 0,
});

export const formatCurrency = (value: number) => currencyFormatter.format(Math.max(0, Math.round(value)));

export const revenueTooltip = ({ value, density, series }: any) => {
  const p90 = series?.stats?.p90;
  const p90Label = p90 != null ? ` • p90 ${formatCurrency(p90)}` : '';
  return `${formatCurrency(value)} • density ${(density * 100).toFixed(1)}%${p90Label}`;
};

export const SERIES = [
  {
    id: 'starter',
    name: 'Starter tier',
    values: createRevenueProfile(45, 24, 62),
    fillOpacity: 0.62,
    strokeWidth: 1.3,
    valueFormatter: formatCurrency,
    tooltipFormatter: revenueTooltip,
  },
  {
    id: 'growth',
    name: 'Growth tier',
    values: createRevenueProfile(68, 32, 74),
    fillOpacity: 0.62,
    strokeWidth: 1.3,
    valueFormatter: formatCurrency,
    tooltipFormatter: revenueTooltip,
  },
  {
    id: 'enterprise',
    name: 'Enterprise contracts',
    values: createRevenueProfile(110, 42, 96),
    fillOpacity: 0.62,
    strokeWidth: 1.3,
    valueFormatter: formatCurrency,
    tooltipFormatter: revenueTooltip,
  },
  {
    id: 'add-ons',
    name: 'Usage add-ons',
    values: createRevenueProfile(32, 20, 48),
    fillOpacity: 0.62,
    strokeWidth: 1.3,
    valueFormatter: formatCurrency,
    tooltipFormatter: revenueTooltip,
  },
];
```

### Shipping Time Carriers

```tsx
import { RidgeChart } from '@plocks/charts';

import { SERIES, formatDays } from './data';

export function Demo() {
  return (
    <RidgeChart
      title="Shipping time distribution by carrier"
      subtitle="Parcel delivery performance across recent quarters"
      h={420}
      series={SERIES}
      samples={110}
      bandwidth={0.45}
      bandPadding={0.3}
      amplitudeScale={0.9}
      grid={{ show: true, showMinor: false }}
      xAxis={{
        show: true,
        title: 'Delivery time (days)',
        labelFormatter: (value) => formatDays(value as number),
        tickLength: 6,
      }}
      yAxis={{
        show: true,
        tickLength: 6,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SAMPLE_POINTS = 150;

export const createShippingProfile = (base: number, variation: number, tail: number) =>
  Array.from({ length: SAMPLE_POINTS }, (_, index) => {
    const seasonal = Math.sin(index / 8.5) * variation;
    const disruption = Math.max(0, Math.sin((index - 22) / 16)) * tail;
    const trafficNoise = Math.cos(index / 3.1) * variation * 0.26;
    const value = base + seasonal + disruption + trafficNoise;
    const clamped = Math.min(8.2, Math.max(1.1, value));
    return Number(clamped.toFixed(2));
  });

export const formatDays = (value: number) => `${value.toFixed(1)} days`;

export const shippingTooltip = ({ value, density, series }: any) => {
  const p90 = series?.stats?.p90;
  const p90Label = p90 != null ? ` • p90 ${formatDays(p90)}` : '';
  return `${formatDays(value)} • density ${(density * 100).toFixed(1)}%${p90Label}`;
};

export const SERIES = [
  {
    id: 'northstar',
    name: 'NorthStar Logistics',
    values: createShippingProfile(3.6, 0.55, 1.2),
    fillOpacity: 0.66,
    strokeWidth: 1.1,
    valueFormatter: formatDays,
    tooltipFormatter: shippingTooltip,
  },
  {
    id: 'aero',
    name: 'Aero Freight',
    values: createShippingProfile(2.9, 0.5, 1.1),
    fillOpacity: 0.66,
    strokeWidth: 1.1,
    valueFormatter: formatDays,
    tooltipFormatter: shippingTooltip,
  },
  {
    id: 'urban-express',
    name: 'Urban Express',
    values: createShippingProfile(2.4, 0.42, 0.9),
    fillOpacity: 0.66,
    strokeWidth: 1.1,
    valueFormatter: formatDays,
    tooltipFormatter: shippingTooltip,
  },
  {
    id: 'coastal',
    name: 'Coastal Courier',
    values: createShippingProfile(4.2, 0.6, 1.4),
    fillOpacity: 0.66,
    strokeWidth: 1.1,
    valueFormatter: formatDays,
    tooltipFormatter: shippingTooltip,
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/SankeyChart.md -->

# Sankey Chart

Flow diagram showing volume between nodes.

## Metadata

- Import: `import { SankeyChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, flow, sankey
- Docs: https://plocks.dev/charts/SankeyChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/SankeyChart

## Props

- `nodes` (required): SankeyNode[] — Nodes included in the Sankey diagram
- `links` (required): SankeyLink[] — Links connecting the nodes
- `animationDuration`: number = 1000 — Animation duration in milliseconds
- `disabled`: boolean = false — Disable animations
- `nodeWidth`: number — Fixed node width in pixels (auto-calculated if omitted)
- `nodePadding`: number — Vertical gap between nodes (auto-calculated if omitted)
- `chartPadding`: Partial<Record<'top' | 'right' | 'bottom' | 'left', number>> — Override chart padding (defaults to 40px all around)
- `labelFormatter`: (node: SankeyNode) => string — Format display label for a node
- `valueFormatter`: (value: number, node: SankeyNode | undefined) => string — Format value label for a node
- `onNodeHover`: (node: SankeyNode | null) => void — Receive callbacks when a node is hovered/focused
- `onLinkHover`: (link: SankeyLink | null) => void — Receive callbacks when a link is hovered/focused
- `highlightOnHover`: boolean = true — Highlight hovered nodes/links (defaults to true)
- `onDataInconsistency`: (issues: SankeyInconsistency[]) => void — Surfaced when inbound/outbound totals differ for a node

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationEasing` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface SankeyNode {
  /** Unique identifier for the node */
  id: string;
  /** Display name for the node */
  name?: string;
  /** Numeric value associated with the node */
  value?: number;
  /** Color override for the node */
  color?: string;
  /** Additional metadata associated with the node */
  meta?: any;
}

export interface SankeyLink {
  /** Source node identifier */
  source: string;
  /** Target node identifier */
  target: string;
  /** Magnitude of the flow */
  value: number;
  /** Color override for the link */
  color?: string;
  /** Additional metadata associated with the link */
  meta?: any;
}

export interface SankeyInconsistency {
  nodeId: string;
  inbound: number;
  outbound: number;
}
```

## Examples

### Basics

Flow diagram showing volume between nodes.

```tsx
import { SankeyChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
	return (
		<SankeyChart
			title="Renewable energy flow"
			h={360}
			nodes={NODES}
			links={LINKS}
		/>
	);
}
```

`data.ts`

```ts
export const NODES = [
	{ id: 'solar', name: 'Solar' },
	{ id: 'wind', name: 'Wind' },
	{ id: 'hydro', name: 'Hydro' },
	{ id: 'grid', name: 'Grid' },
	{ id: 'battery', name: 'Battery Storage' },
	{ id: 'residential', name: 'Residential' },
	{ id: 'commercial', name: 'Commercial' },
	{ id: 'industrial', name: 'Industrial' },
];

export const LINKS = [
	{ source: 'solar', target: 'grid', value: 32 },
	{ source: 'wind', target: 'grid', value: 28 },
	{ source: 'hydro', target: 'grid', value: 18 },
	{ source: 'solar', target: 'battery', value: 6 },
	{ source: 'wind', target: 'battery', value: 4 },
	{ source: 'battery', target: 'grid', value: 8 },
	{ source: 'grid', target: 'residential', value: 30 },
	{ source: 'grid', target: 'commercial', value: 24 },
	{ source: 'grid', target: 'industrial', value: 16 },
];
```

### Budget Allocation

```tsx
import { SankeyChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
  return (
    <SankeyChart
      title="Budget allocation flow"
      subtitle="FY26 operating plan"
      h={400}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

`data.ts`

```ts
export const NODES = [
  { id: 'corporate-budget', name: 'Corporate Budget' },
  { id: 'gtm', name: 'Go-to-Market' },
  { id: 'product', name: 'Product & Engineering' },
  { id: 'operations', name: 'Operations' },
  { id: 'paid-media', name: 'Paid Media' },
  { id: 'events', name: 'Events' },
  { id: 'product-investment', name: 'Product Investment' },
  { id: 'platform-modernization', name: 'Platform Modernization' },
  { id: 'customer-success', name: 'Customer Success' },
  { id: 'supply-chain', name: 'Supply Chain' },
];

export const LINKS = [
  { source: 'corporate-budget', target: 'gtm', value: 24 },
  { source: 'corporate-budget', target: 'product', value: 32 },
  { source: 'corporate-budget', target: 'operations', value: 18 },
  { source: 'gtm', target: 'paid-media', value: 12 },
  { source: 'gtm', target: 'events', value: 8 },
  { source: 'gtm', target: 'customer-success', value: 4 },
  { source: 'product', target: 'product-investment', value: 14 },
  { source: 'product', target: 'platform-modernization', value: 12 },
  { source: 'operations', target: 'customer-success', value: 6 },
  { source: 'operations', target: 'supply-chain', value: 10 },
];
```

### Cloud Provisioning

```tsx
import { SankeyChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
  return (
    <SankeyChart
      title="Cloud provisioning workflow"
      subtitle="Quarterly environment requests"
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

`data.ts`

```ts
export const NODES = [
  { id: 'request', name: 'Service Request' },
  { id: 'security-review', name: 'Security Review' },
  { id: 'infra-approval', name: 'Infra Approval' },
  { id: 'dev-env', name: 'Dev Cluster' },
  { id: 'staging-env', name: 'Staging Cluster' },
  { id: 'prod-env', name: 'Prod Cluster' },
  { id: 'kubernetes', name: 'Kubernetes Workloads' },
  { id: 'serverless', name: 'Serverless Jobs' },
  { id: 'databases', name: 'Managed Databases' },
];

export const LINKS = [
  { source: 'request', target: 'security-review', value: 60 },
  { source: 'request', target: 'infra-approval', value: 20 },
  { source: 'security-review', target: 'infra-approval', value: 55 },
  { source: 'infra-approval', target: 'dev-env', value: 28 },
  { source: 'infra-approval', target: 'staging-env', value: 20 },
  { source: 'infra-approval', target: 'prod-env', value: 27 },
  { source: 'dev-env', target: 'kubernetes', value: 16 },
  { source: 'dev-env', target: 'serverless', value: 6 },
  { source: 'dev-env', target: 'databases', value: 6 },
  { source: 'staging-env', target: 'kubernetes', value: 10 },
  { source: 'staging-env', target: 'serverless', value: 4 },
  { source: 'staging-env', target: 'databases', value: 6 },
  { source: 'prod-env', target: 'kubernetes', value: 12 },
  { source: 'prod-env', target: 'serverless', value: 7 },
  { source: 'prod-env', target: 'databases', value: 8 },
];
```

### Customer Journey

```tsx
import { SankeyChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
  return (
    <SankeyChart
      title="Customer journey flow"
      subtitle="Q3 acquisition to retention"
      h={420}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

`data.ts`

```ts
export const NODES = [
  { id: 'paid-social', name: 'Paid Social' },
  { id: 'organic-search', name: 'Organic Search' },
  { id: 'email', name: 'Email Nurture' },
  { id: 'events', name: 'Field Events' },
  { id: 'signup', name: 'Sign Up' },
  { id: 'trial', name: 'Trial Activation' },
  { id: 'purchase', name: 'Purchase', color: '#10B981' },
  { id: 'churn', name: 'Churn', color: '#EF4444' },
  { id: 'retain', name: 'Retained' },
];

export const LINKS = [
  { source: 'paid-social', target: 'signup', value: 320 },
  { source: 'organic-search', target: 'signup', value: 420 },
  { source: 'email', target: 'signup', value: 180 },
  { source: 'events', target: 'signup', value: 140 },
  { source: 'signup', target: 'trial', value: 760 },
  { source: 'trial', target: 'purchase', value: 410 },
  { source: 'trial', target: 'churn', value: 350 },
  { source: 'purchase', target: 'retain', value: 290 },
  { source: 'purchase', target: 'churn', value: 120 },
];
```

### Data Lineage

```tsx
import { SankeyChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
  return (
    <SankeyChart
      title="Analytics data lineage"
      subtitle="Daily load pipeline"
      h={420}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

`data.ts`

```ts
export const NODES = [
  { id: 'crm', name: 'CRM' },
  { id: 'product-analytics', name: 'Product Analytics' },
  { id: 'billing', name: 'Billing' },
  { id: 'raw-zone', name: 'Raw Zone' },
  { id: 'staging', name: 'Staging' },
  { id: 'warehouse', name: 'Warehouse' },
  { id: 'marts', name: 'Analytics Marts' },
  { id: 'dashboards', name: 'Executive Dashboards' },
  { id: 'cs-insights', name: 'CS Insights' },
  { id: 'ml-feature-store', name: 'ML Feature Store' },
];

export const LINKS = [
  { source: 'crm', target: 'raw-zone', value: 420 },
  { source: 'product-analytics', target: 'raw-zone', value: 360 },
  { source: 'billing', target: 'raw-zone', value: 280 },
  { source: 'raw-zone', target: 'staging', value: 900 },
  { source: 'staging', target: 'warehouse', value: 860 },
  { source: 'warehouse', target: 'marts', value: 540 },
  { source: 'warehouse', target: 'ml-feature-store', value: 320 },
  { source: 'marts', target: 'dashboards', value: 340 },
  { source: 'marts', target: 'cs-insights', value: 180 },
  { source: 'ml-feature-store', target: 'cs-insights', value: 120 },
];
```

### Talent Pipeline

```tsx
import { SankeyChart } from '@plocks/charts';

import { LINKS, NODES } from './data';

export function Demo() {
  return (
    <SankeyChart
      title="Engineering talent pipeline"
      subtitle="Campus + lateral hiring"
      h={420}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

`data.ts`

```ts
export const NODES = [
  { id: 'campus', name: 'Campus Recruiting' },
  { id: 'bootcamp', name: 'Bootcamp Partners' },
  { id: 'referrals', name: 'Employee Referrals' },
  { id: 'internal', name: 'Internal Mobility' },
  { id: 'screening', name: 'Recruiter Screen' },
  { id: 'technical', name: 'Technical Interview' },
  { id: 'onsite', name: 'Onsite Panel' },
  { id: 'offer', name: 'Offer Stage' },
  { id: 'accepted', name: 'Accepted Offers', color: '#10B981' },
  { id: 'screening-drop', name: 'Screen Drops', color: '#EF4444' },
  { id: 'technical-drop', name: 'Technical Drops', color: '#DC2626' },
  { id: 'onsite-drop', name: 'Onsite Declines', color: '#B91C1C' },
  { id: 'offer-decline', name: 'Offer Declined', color: '#F43F5E' },
  { id: 'product-eng', name: 'Product Engineering' },
  { id: 'platform-eng', name: 'Platform Engineering' },
  { id: 'data-science', name: 'Data Science' },
];

export const LINKS = [
  { source: 'campus', target: 'screening', value: 120 },
  { source: 'bootcamp', target: 'screening', value: 80 },
  { source: 'referrals', target: 'technical', value: 60 },
  { source: 'internal', target: 'technical', value: 30 },
  { source: 'screening', target: 'technical', value: 190 },
  { source: 'screening', target: 'screening-drop', value: 10 },
  { source: 'technical', target: 'onsite', value: 210 },
  { source: 'technical', target: 'technical-drop', value: 70 },
  { source: 'onsite', target: 'offer', value: 180 },
  { source: 'onsite', target: 'onsite-drop', value: 30 },
  { source: 'offer', target: 'accepted', value: 140 },
  { source: 'offer', target: 'offer-decline', value: 40 },
  { source: 'accepted', target: 'product-eng', value: 60 },
  { source: 'accepted', target: 'platform-eng', value: 45 },
  { source: 'accepted', target: 'data-science', value: 35 },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ScatterChart.md -->

# Scatter Chart

Plots data points in two-dimensional space for correlation analysis.

## Metadata

- Import: `import { ScatterChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, scatter, xy
- Docs: https://plocks.dev/charts/ScatterChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/ScatterChart

## Props

- `data` (required): ChartDataPoint[] — Data points
- `series`: ScatterSeries[] — Optional multi-series data (overrides top-level data if provided)
- `pointSize`: number = 6 — Point size
- `pointColor`: string — Point color
- `pointOpacity`: number = 1 — Point opacity
- `allowAddPoints`: boolean = false — Allow adding points by tapping
- `showTrendline`: boolean | 'overall' | 'per-series' = false — Show trend line. true|'overall' for single combined regression, 'per-series' for one per series
- `trendlineColor`: string — Trend line color
- `enablePanZoom`: boolean — Enable pan & zoom interactions
- `zoomMode`: 'x' | 'y' | 'both' — Zoom mode (axes constrained)
- `minZoom`: number — Minimum zoom scale (domain fraction)
- `enableWheelZoom`: boolean — Enable wheel zoom (web)
- `wheelZoomStep`: number — Wheel zoom step
- `invertWheelZoom`: boolean — Invert wheel zoom direction
- `resetOnDoubleTap`: boolean — Reset zoom on double tap
- `clampToInitialDomain`: boolean — Clamp pan/zoom to initial full domain
- `invertPinchZoom`: boolean — Invert pinch gesture direction (scale grows when fingers move closer)
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid configuration
- `legend`: ChartLegend — Legend configuration
- `tooltip`: ChartTooltip<ChartDataPoint> — Tooltip configuration
- `animation`: ChartAnimation — Animation configuration
- `multiTooltip`: boolean — Enable multi-series shared tooltip popover
- `enableCrosshair`: boolean — Enable crosshair
- `liveTooltip`: boolean — Live (follow pointer) tooltip selection
- `xScaleType`: 'linear' | 'log' | 'time' — X scale type
- `yScaleType`: 'linear' | 'log' | 'time' — Y scale type
- `quadrants`: ScatterQuadrantConfig — Optional quadrant overlay configuration

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface ScatterSeries {
  /** Unique identifier for the series */
  id?: string;
  /** Display name for the series */
  name?: string;
  /** Base color applied to the series */
  color?: string;
  /** Data points belonging to the series */
  data: ChartDataPoint[];
  /** Point size override for the series */
  pointSize?: number;
  /** Point color override for the series */
  pointColor?: string;
}

export interface ScatterQuadrantConfig {
  /** X-axis value used to split the chart into left/right quadrants */
  x?: number;
  /** Y-axis value used to split the chart into top/bottom quadrants */
  y?: number;
  /** Background fills applied to the resulting quadrants */
  fills?: {
    topLeft?: string;
    topRight?: string;
    bottomLeft?: string;
    bottomRight?: string;
  };
  /** Background fill opacity */
  fillOpacity?: number;
  /** Whether to render dividing guide lines */
  showLines?: boolean;
  /** Color for the dividing guide lines */
  lineColor?: string;
  /** Thickness for the dividing guide lines */
  lineWidth?: number;
  /** Optional labels describing each quadrant */
  labels?: {
    topLeft?: string;
    topRight?: string;
    bottomLeft?: string;
    bottomRight?: string;
  };
  /** Label color */
  labelColor?: string;
  /** Label font size */
  labelFontSize?: number;
  /** Offset from the quadrant edge for the labels */
  labelOffset?: number;
}
```

## Examples

### Basics

Plots data points in two-dimensional space for correlation analysis.

```tsx
import { ScatterChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <ScatterChart
      title="Spend vs. qualified leads"
      subtitle="Campaign cohort"
      h={340}
      data={SERIES.flatMap((serie) => serie.data)}
      series={SERIES}
      showTrendline="per-series"
      enableCrosshair
      enablePanZoom
      zoomMode="both"
      multiTooltip
      liveTooltip
      xAxis={{
        show: true,
        title: 'Spend (USD thousands)',
        labelFormatter: (value) => `$${value}`,
      }}
      yAxis={{
        show: true,
        title: 'Qualified leads',
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      tooltip={{
        show: true,
        formatter: (point) => `${point.x}k spend → ${point.y} leads`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'marketing',
    name: 'Marketing spend',
    data: [
      { x: 18, y: 42 },
      { x: 22, y: 48 },
      { x: 25, y: 54 },
      { x: 27, y: 58 },
      { x: 30, y: 61 },
      { x: 34, y: 66 },
      { x: 38, y: 70 },
    ],
    pointSize: 8,
  },
  {
    id: 'events',
    name: 'Event sponsorship',
    data: [
      { x: 12, y: 36 },
      { x: 16, y: 41 },
      { x: 19, y: 44 },
      { x: 23, y: 47 },
      { x: 27, y: 55 },
      { x: 32, y: 62 },
      { x: 35, y: 65 },
    ],
    pointSize: 7,
  },
];
```

### Api Error Rate Volume

```tsx
import { ScatterChart } from '@plocks/charts';

import { QUADRANTS, SERIES } from './data';

const describeQuadrant = (x: number, y: number) => {
  const labels = QUADRANTS.labels;
  if (!labels) return null;
  const isRight = x >= QUADRANTS.x;
  const isTop = y >= QUADRANTS.y;

  if (isRight && isTop) return labels.topRight ?? null;
  if (!isRight && isTop) return labels.topLeft ?? null;
  if (isRight && !isTop) return labels.bottomRight ?? null;
  return labels.bottomLeft ?? null;
};

export function Demo() {
  return (
    <ScatterChart
      title="API error rate vs. request volume"
      subtitle="Each point represents a service, sized by throughput"
      h={360}
      data={SERIES.flatMap((serie) => serie.data)}
      series={SERIES}
      quadrants={QUADRANTS}
      pointOpacity={0.9}
      enableCrosshair
      multiTooltip
      liveTooltip
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      xScaleType="log"
      xAxis={{
        show: true,
        title: 'Requests per minute (thousands)',
        labelFormatter: (value: number) => `${Math.round(value)}k`,
      }}
      yAxis={{
        show: true,
        title: 'Error rate (%)',
        labelFormatter: (value: number) => `${value.toFixed(1)}%`,
      }}
      tooltip={{
        show: true,
        backgroundColor: '#12263A',
        textColor: '#F4F6FB',
        formatter: (point) => {
          const quadrantNote = describeQuadrant(point.x, point.y);
          const lines = [
            point.label ?? 'Service',
            `Volume ${Math.round(point.x)}k rpm · Errors ${point.y.toFixed(1)}%`,
          ];
          if (quadrantNote) {
            lines.push(quadrantNote);
          }
          return lines.join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'core-apis',
    name: 'Core services',
    pointSize: 8,
    data: [
      { id: 'core-auth', x: 520, y: 2.9, label: 'Auth' },
      { id: 'core-catalog', x: 480, y: 2.6, label: 'Catalog' },
      { id: 'core-inventory', x: 410, y: 2.4, label: 'Inventory' },
      { id: 'core-profiles', x: 365, y: 2.1, label: 'Profiles' },
      { id: 'core-checkout', x: 445, y: 2.7, label: 'Checkout' },
    ],
  },
  {
    id: 'payment-apis',
    name: 'Payment services',
    pointSize: 8,
    data: [
      { id: 'pay-processing', x: 260, y: 4.1, label: 'Processor' },
      { id: 'pay-ledger', x: 195, y: 3.1, label: 'Ledger' },
      { id: 'pay-invoicing', x: 220, y: 3.6, label: 'Invoicing' },
      { id: 'pay-fx', x: 180, y: 3.4, label: 'FX gateway' },
      { id: 'pay-risk', x: 240, y: 3.9, label: 'Risk scoring' },
    ],
  },
  {
    id: 'edge-apis',
    name: 'Edge and experimental',
    pointSize: 7,
    data: [
      { id: 'edge-recos', x: 120, y: 4.2, label: 'Recommendations' },
      { id: 'edge-search', x: 95, y: 4.5, label: 'Search beta' },
      { id: 'edge-proto', x: 70, y: 3.9, label: 'Prototype API' },
      { id: 'edge-labs', x: 55, y: 3.6, label: 'Labs checkout' },
      { id: 'edge-content', x: 82, y: 4, label: 'Content sync' },
    ],
  },
];

export const QUADRANTS = {
  x: 180,
  y: 3.5,
  fills: {
    topLeft: 'rgba(255, 193, 7, 0.1)',
    topRight: 'rgba(255, 107, 107, 0.12)',
    bottomLeft: 'rgba(63, 142, 252, 0.08)',
    bottomRight: 'rgba(34, 197, 247, 0.08)',
  },
  fillOpacity: 1,
  lineColor: '#B0C4FE',
  lineWidth: 1,
  labels: {
    topLeft: 'High error - lower volume',
    topRight: 'Critical risk',
    bottomLeft: 'Monitor growth',
    bottomRight: 'Healthy scale',
  },
  labelColor: '#1F2933',
  labelFontSize: 11,
  labelOffset: 12,
};
```

### Campaign Spend Revenue

```tsx
import { ScatterChart } from '@plocks/charts';

import { QUADRANTS, SERIES } from './data';

const resolveAction = (x: number, y: number) => {
  const labels = QUADRANTS.labels;
  if (!labels) return null;
  const right = x >= QUADRANTS.x;
  const top = y >= QUADRANTS.y;

  if (!right && top) return labels.topLeft ?? null;
  if (right && top) return labels.topRight ?? null;
  if (!right && !top) return labels.bottomLeft ?? null;
  return labels.bottomRight ?? null;
};

export function Demo() {
  return (
    <ScatterChart
      title="Campaign spend vs. attributed revenue"
      subtitle="Ad set performance, each marker sized by budget grouping"
      h={360}
      data={SERIES.flatMap((serie) => serie.data)}
      series={SERIES}
      quadrants={QUADRANTS}
      pointOpacity={0.86}
      showTrendline="per-series"
      enableCrosshair
      multiTooltip
      liveTooltip
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      xAxis={{
        show: true,
        title: 'Spend (USD thousands)',
        labelFormatter: (value: number) => `$${value}k`,
      }}
      yAxis={{
        show: true,
        title: 'Attributed revenue (USD thousands)',
        labelFormatter: (value: number) => `$${value}k`,
      }}
      tooltip={{
        show: true,
        backgroundColor: '#0B1220',
        textColor: '#F1F5F9',
        formatter: (point) => {
          const action = resolveAction(point.x, point.y);
          const lines = [
            point.label ?? 'Ad set',
            `Spend $${point.x}k · Revenue $${point.y}k`,
          ];
          if (action) {
            lines.push(action);
          }
          return lines.join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'paid-social',
    name: 'Paid social',
    pointSize: 8,
    data: [
  { id: 'social-lifestyle', x: 90, y: 210, size: 9.4, label: 'Lifestyle creatives' },
  { id: 'social-product', x: 78, y: 188, size: 8.9, label: 'Product video' },
  { id: 'social-lookalike', x: 112, y: 265, size: 10.2, label: 'Lookalike expansion' },
  { id: 'social-remarketing', x: 68, y: 160, size: 8.4, label: 'Retargeting carousel' },
  { id: 'social-brand', x: 82, y: 195, size: 9.1, label: 'Brand storytelling' },
    ],
  },
  {
    id: 'paid-search',
    name: 'Paid search',
    pointSize: 7.5,
    data: [
  { id: 'search-brand', x: 55, y: 148, size: 8.1, label: 'Brand keywords' },
  { id: 'search-competitor', x: 72, y: 168, size: 8.8, label: 'Competitor conquest' },
  { id: 'search-feature', x: 48, y: 118, size: 7.8, label: 'Feature launch' },
  { id: 'search-sku', x: 64, y: 152, size: 8.4, label: 'SKU breakout' },
  { id: 'search-automation', x: 60, y: 160, size: 8.2, label: 'Smart bidding' },
    ],
  },
  {
    id: 'display',
    name: 'Programmatic & display',
    pointSize: 7.5,
    data: [
  { id: 'display-ctv', x: 95, y: 205, size: 9.6, label: 'CTV extension' },
  { id: 'display-contextual', x: 74, y: 165, size: 8.7, label: 'Contextual placements' },
  { id: 'display-retarget', x: 88, y: 198, size: 9.3, label: 'High-intent retarget' },
  { id: 'display-prospect', x: 82, y: 170, size: 8.9, label: 'Prospecting bundle' },
  { id: 'display-awareness', x: 90, y: 162, size: 9.2, label: 'Awareness push' },
    ],
  },
];

export const QUADRANTS = {
  x: 80,
  y: 185,
  fills: {
    topLeft: 'rgba(12, 166, 120, 0.12)',
    topRight: 'rgba(66, 99, 235, 0.12)',
    bottomLeft: 'rgba(255, 163, 72, 0.08)',
    bottomRight: 'rgba(255, 107, 107, 0.12)',
  },
  fillOpacity: 1,
  lineColor: '#C0D6FF',
  lineWidth: 1,
  labels: {
    topLeft: 'High ROI champions',
    topRight: 'Scale candidates',
    bottomLeft: 'Creative tune-up',
    bottomRight: 'Pull back spend',
  },
  labelColor: '#1C1D21',
  labelFontSize: 11,
  labelOffset: 14,
};
```

### Customer Ltv Vs Cac

```tsx
import { ScatterChart } from '@plocks/charts';

import { QUADRANTS, SERIES } from './data';

const resolveQuadrantLabel = (x: number, y: number) => {
  const horizontal = x >= QUADRANTS.x ? 'Right' : 'Left';
  const vertical = y >= QUADRANTS.y ? 'Top' : 'Bottom';
  const labels = QUADRANTS.labels;

  if (!labels) return null;
  if (horizontal === 'Left' && vertical === 'Top') return labels.topLeft ?? null;
  if (horizontal === 'Right' && vertical === 'Top') return labels.topRight ?? null;
  if (horizontal === 'Left' && vertical === 'Bottom') return labels.bottomLeft ?? null;
  if (horizontal === 'Right' && vertical === 'Bottom') return labels.bottomRight ?? null;
  return null;
};

export function Demo() {
  return (
    <ScatterChart
      title="Customer LTV vs. Acquisition Cost"
      subtitle="Segment performance across recent cohorts"
      h={360}
      data={SERIES.flatMap((serie) => serie.data)}
      series={SERIES}
      quadrants={QUADRANTS}
      pointOpacity={0.9}
      showTrendline="per-series"
      enableCrosshair
      multiTooltip
      liveTooltip
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      xAxis={{
        show: true,
        title: 'Acquisition cost (USD thousands)',
        labelFormatter: (value: number) => `$${value}k`,
      }}
      yAxis={{
        show: true,
        title: 'Lifetime value (USD thousands)',
        labelFormatter: (value: number) => `$${value}k`,
      }}
      tooltip={{
        show: true,
        backgroundColor: '#101218',
        textColor: '#F8FAFC',
        formatter: (point) => {
          const quadrantLabel = resolveQuadrantLabel(point.x, point.y);
          const lines = [
            point.label ?? 'Segment',
            `CAC $${point.x}k · LTV $${point.y}k`,
          ];
          if (quadrantLabel) {
            lines.push(quadrantLabel);
          }
          return lines.join('\n');
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'enterprise',
    name: 'Enterprise',
    pointSize: 10,
    data: [
      { id: 'ent-a', x: 185, y: 980, label: 'Enterprise A' },
      { id: 'ent-b', x: 172, y: 920, label: 'Enterprise B' },
      { id: 'ent-c', x: 194, y: 1040, label: 'Enterprise C' },
      { id: 'ent-d', x: 168, y: 905, label: 'Enterprise D' },
      { id: 'ent-e', x: 180, y: 965, label: 'Enterprise E' },
    ],
  },
  {
    id: 'mid-market',
    name: 'Mid-market',
    pointSize: 8,
    data: [
      { id: 'mid-a', x: 118, y: 640, label: 'Mid-market A' },
      { id: 'mid-b', x: 110, y: 590, label: 'Mid-market B' },
      { id: 'mid-c', x: 126, y: 705, label: 'Mid-market C' },
      { id: 'mid-d', x: 101, y: 565, label: 'Mid-market D' },
      { id: 'mid-e', x: 134, y: 720, label: 'Mid-market E' },
    ],
  },
  {
    id: 'smb',
    name: 'SMB',
    pointSize: 7,
    data: [
      { id: 'smb-a', x: 72, y: 355, label: 'SMB A' },
      { id: 'smb-b', x: 68, y: 330, label: 'SMB B' },
      { id: 'smb-c', x: 83, y: 410, label: 'SMB C' },
      { id: 'smb-d', x: 58, y: 295, label: 'SMB D' },
      { id: 'smb-e', x: 64, y: 325, label: 'SMB E' },
    ],
  },
];

export const QUADRANTS = {
  x: 110,
  y: 600,
  fills: {
    topLeft: 'rgba(32, 201, 151, 0.12)',
    topRight: 'rgba(76, 110, 245, 0.08)',
    bottomLeft: 'rgba(51, 154, 240, 0.08)',
    bottomRight: 'rgba(255, 107, 107, 0.1)',
  },
  fillOpacity: 1,
  lineColor: '#ADB5FF',
  lineWidth: 1,
  labels: {
    topLeft: 'High value - efficient CAC',
    topRight: 'High value - costly CAC',
    bottomLeft: 'Emerging opportunity',
    bottomRight: 'Reassess acquisition spend',
  },
  labelColor: '#1C1D21',
  labelFontSize: 11,
  labelOffset: 14,
};
```

### Feature Usage Vs Satisfaction

```tsx
import { ScatterChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <ScatterChart
      title="Feature usage vs. satisfaction"
      subtitle="Weekly feature interactions mapped to CSAT by cohort"
      h={360}
      data={SERIES.flatMap((serie) => serie.data)}
      series={SERIES}
      pointOpacity={0.85}
      showTrendline="per-series"
      enableCrosshair
      multiTooltip
      liveTooltip
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom', align: 'center' }}
      xAxis={{
        show: true,
        title: 'Weekly feature uses',
        labelFormatter: (value: number) => `${value}x`,
      }}
      yAxis={{
        show: true,
        title: 'Customer satisfaction (1-10)',
        labelFormatter: (value: number) => value.toFixed(1),
      }}
      tooltip={{
        show: true,
        formatter: (point) =>
          `${point.label ?? 'Cohort'}\nUsage ${point.x.toFixed(1)}x | CSAT ${point.y.toFixed(1)}`,
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'early-adopters',
    name: 'Early adopters',
    pointSize: 8,
    data: [
      { id: 'ea-1', x: 17, y: 9, label: 'Beta squad' },
      { id: 'ea-2', x: 16, y: 8.6, label: 'Automation guild' },
      { id: 'ea-3', x: 18, y: 9.2, label: 'Platform champions' },
      { id: 'ea-4', x: 15, y: 8.8, label: 'Growth lab' },
    ],
  },
  {
    id: 'power-users',
    name: 'Power users',
    pointSize: 7,
    data: [
      { id: 'pu-1', x: 14, y: 8.2, label: 'Analytics crew' },
      { id: 'pu-2', x: 13, y: 7.9, label: 'Delivery ops' },
      { id: 'pu-3', x: 12, y: 8.1, label: 'Mobile pod' },
      { id: 'pu-4', x: 13.5, y: 8.4, label: 'Rev enablement' },
    ],
  },
  {
    id: 'core-users',
    name: 'Core users',
    pointSize: 6.5,
    data: [
      { id: 'cu-1', x: 9.5, y: 7.4, label: 'North America' },
      { id: 'cu-2', x: 8.8, y: 7.2, label: 'Europe' },
      { id: 'cu-3', x: 10.2, y: 7.6, label: 'APAC' },
      { id: 'cu-4', x: 9.8, y: 7.5, label: 'LATAM' },
    ],
  },
  {
    id: 'at-risk',
    name: 'At-risk',
    pointSize: 6,
    data: [
      { id: 'ar-1', x: 5.5, y: 6.2, label: 'Support desk' },
      { id: 'ar-2', x: 6.3, y: 6.5, label: 'Partner success' },
      { id: 'ar-3', x: 4.8, y: 6, label: 'Finance ops' },
      { id: 'ar-4', x: 5.1, y: 6.3, label: 'Field enablement' },
    ],
  },
];
```

### Performance Vs Tenure

```tsx
import { ScatterChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <ScatterChart
      title="Performance rating vs. tenure"
      subtitle="Team-by-team view with marker size scaled to total compensation (USD thousands)"
      h={360}
      data={SERIES.flatMap((serie) => serie.data)}
      series={SERIES}
      pointOpacity={0.88}
      showTrendline="per-series"
      enableCrosshair
      multiTooltip
      liveTooltip
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      xAxis={{
        show: true,
        title: 'Tenure (years)',
        labelFormatter: (value: number) => `${value.toFixed(1)} yrs`,
      }}
      yAxis={{
        show: true,
        title: 'Performance rating (1-5)',
        labelFormatter: (value: number) => value.toFixed(1),
      }}
      tooltip={{
        show: true,
        formatter: (point) => {
          const compensation = point.data?.compensation;
          const compensationText = typeof compensation === 'number' ? `$${compensation}k` : 'n/a';
          return `${point.label ?? 'Team member'}\nRating ${point.y.toFixed(1)} | Tenure ${point.x.toFixed(1)} yrs\nComp ${compensationText}`;
        },
      }}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'engineering',
    name: 'Engineering',
    pointSize: 9,
    data: [
      { id: 'eng-1', x: 5.8, y: 4.6, size: 10.5, label: 'Staff engineer', data: { compensation: 195 } },
      { id: 'eng-2', x: 4.2, y: 4.3, size: 9.5, label: 'Senior engineer', data: { compensation: 172 } },
      { id: 'eng-3', x: 8.1, y: 4.8, size: 11, label: 'Principal engineer', data: { compensation: 230 } },
      { id: 'eng-4', x: 3.4, y: 4.1, size: 8.5, label: 'Platform engineer', data: { compensation: 160 } },
      { id: 'eng-5', x: 6.3, y: 4.5, size: 10, label: 'DevOps lead', data: { compensation: 188 } },
    ],
  },
  {
    id: 'sales',
    name: 'Sales',
    pointSize: 8.5,
    data: [
      { id: 'sales-1', x: 5.1, y: 4.4, size: 10, label: 'Enterprise AE', data: { compensation: 210 } },
      { id: 'sales-2', x: 3.8, y: 4, size: 8.8, label: 'Commercial AE', data: { compensation: 165 } },
      { id: 'sales-3', x: 6.8, y: 4.6, size: 10.5, label: 'Regional director', data: { compensation: 220 } },
      { id: 'sales-4', x: 2.9, y: 3.8, size: 8, label: 'SDR lead', data: { compensation: 140 } },
      { id: 'sales-5', x: 4.6, y: 4.1, size: 9.3, label: 'Channel manager', data: { compensation: 170 } },
    ],
  },
  {
    id: 'customer-success',
    name: 'Customer success',
    pointSize: 8,
    data: [
      { id: 'cs-1', x: 4.9, y: 4.3, size: 8.2, label: 'Strategic CSM', data: { compensation: 150 } },
      { id: 'cs-2', x: 3.6, y: 4, size: 7.5, label: 'Enterprise CSM', data: { compensation: 138 } },
      { id: 'cs-3', x: 5.7, y: 4.5, size: 8.8, label: 'Solution architect', data: { compensation: 162 } },
      { id: 'cs-4', x: 2.8, y: 3.7, size: 7, label: 'Onboarding lead', data: { compensation: 120 } },
      { id: 'cs-5', x: 4.2, y: 4.1, size: 7.8, label: 'Renewals manager', data: { compensation: 132 } },
    ],
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/SparklineChart.md -->

# Sparkline Chart

Compact inline trend indicator for dense data summaries.

## Metadata

- Import: `import { SparklineChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, sparkline, trend
- Docs: https://plocks.dev/charts/SparklineChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/SparklineChart

## Props

- `id`: string | number — Optional unique series ID
- `name`: string — Optional series name (for tooltip)
- `data` (required): number[] | SparklinePoint[] — Data points (plain y values or explicit {x,y} pairs)
- `color`: string — Line color
- `fill`: boolean = true — Fill area under line
- `fillOpacity`: number = 0.3 — Fill opacity
- `strokeWidth`: number = 2 — Stroke width
- `smooth`: boolean = true — Curve smoothing
- `showPoints`: boolean = false — Show data points
- `pointSize`: number = 3 — Point size (for individual data points)
- `domain`: SparklineDomain — Provide min/max to avoid re-scaling jitter across multiple sparklines
- `highlightLast`: boolean = true — Show last value bubble
- `highlightExtrema`: boolean | SparklineExtremaHighlight — Show min/max markers
- `valueFormatter`: (value: number) => string — Format displayed last value
- `liveTooltip`: boolean = true — Compact tooltip when hovered (web)
- `multiTooltip`: boolean = false — Enable aggregated tooltip when multiple sparklines share context
- `thresholds`: SparklineThreshold[] = [] as SparklineThreshold[] — Horizontal threshold guides
- `bands`: SparklineBand[] = [] as SparklineBand[] — Highlight background regions
- `animation`: SparklineAnimationOptions — Control reveal animation

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface SparklinePoint {
  /** X-axis value for the sparkline point */
  x: number;
  /** Y-axis value for the sparkline point */
  y: number;
}

export interface SparklineDomain {
  /** Explicit x-axis domain override */
  x?: [number, number];
  /** Explicit y-axis domain override */
  y?: [number, number];
}

export interface SparklineExtremaHighlight {
  /** Render marker for minimum value */
  showMin?: boolean;
  /** Render marker for maximum value */
  showMax?: boolean;
  /** Marker fill color (defaults to line color) */
  color?: string;
  /** Marker radius */
  radius?: number;
  /** Outline color */
  strokeColor?: string;
  /** Outline width */
  strokeWidth?: number;
}

export interface SparklineThreshold {
  /** Target value to render as a horizontal guide */
  value: number;
  /** Override line color */
  color?: string;
  /** Line opacity (0-1) */
  opacity?: number;
  /** Render as dashed guide */
  dashed?: boolean;
  /** Optional text label */
  label?: string;
  /** Label placement along the line */
  labelPosition?: 'left' | 'right';
  /** Custom label color */
  labelColor?: string;
  /** Offset label vertically (px) */
  labelOffset?: number;
}

export interface SparklineBand {
  /** Lower bound of the band */
  from: number;
  /** Upper bound of the band */
  to: number;
  /** Fill color (defaults to line color) */
  color?: string;
  /** Fill opacity (0-1) */
  opacity?: number;
}

export interface SparklineAnimationOptions {
  /** Enable/disable line animation */
  enabled?: boolean;
  /** Animation duration in ms */
  duration?: number;
  /** Delay in ms before animation starts */
  delay?: number;
  /** Easing preset */
  easing?: SparklineAnimationEasing;
}
```

## Examples

### Basics

Compact inline trend indicator for dense data summaries.

```tsx
import { SparklineChart } from '@plocks/charts';

import { DAILY_SIGNUPS } from './data';

export function Demo() {
  return (
    <SparklineChart
      h={72}
      data={DAILY_SIGNUPS}
      fill
      fillOpacity={0.18}
      smooth
      showPoints={false}
      pointSize={4}
      strokeWidth={2.5}
      highlightLast={false}
      valueFormatter={(value) => `${value} signups`}
      domain={{ y: [20, 80] }}
    />
  );
}
```

`data.ts`

```ts
export const DAILY_SIGNUPS = [
  32, 36, 31, 40, 44, 47, 46, 52, 58, 60, 64, 67, 70, 72,
];
```

### Dashboard Daily Active Users

```tsx
import { Block, Card, Flex, Text, Title } from '@plocks/ui';
import { SparklineChart } from '@plocks/charts';

import { SURFACE_SERIES } from './data';

const formatUsers = (value: number) => `${Math.round(value).toLocaleString()} users`;

const getDeltaLabel = (series: number[]) => {
  if (series.length < 2) return 'Stable vs yesterday';
  const latest = series[series.length - 1];
  const prior = series[series.length - 2];
  const delta = latest - prior;
  if (delta === 0) return 'Stable vs yesterday';
  const prefix = delta > 0 ? '+' : '-';
  return `${prefix}${Math.abs(delta).toLocaleString()} vs yesterday`;
};

export function Demo() {
  return (
    <Card padding="lg" radius="lg">
      <Block mb="md">
        <Title order={5} text="Daily Active Users" />
        <Text size="sm" c="muted">Trailing two weeks, by platform</Text>
      </Block>

      <Flex direction="row" wrap="wrap" gap="md">
        {SURFACE_SERIES.map((series) => {
          const latest = series.data[series.data.length - 1];
          return (
            <Block key={series.id} style={{ width: 200 }}>
              <Text size="sm" fw="semibold">{series.title}</Text>
              <Text size="xs" c="muted">
                {latest.toLocaleString()} · {getDeltaLabel(series.data)}
              </Text>
              <SparklineChart
                h={72}
                data={series.data}
                fill
                fillOpacity={0.18}
                smooth
                highlightLast
                valueFormatter={formatUsers}
                domain={{ y: [900, 2300] }}
                thresholds={[{ value: 2100, label: 'Target', dashed: true, color: '#94A3B8', opacity: 0.7, labelPosition: 'right' }]}
              />
            </Block>
          );
        })}
      </Flex>
    </Card>
  );
}
```

`data.ts`

```ts
export const SURFACE_SERIES = [
  {
    id: 'web',
    title: 'Web',
    data: [1820, 1855, 1880, 1915, 1940, 1975, 2010, 2045, 2070, 2095, 2130, 2165, 2195, 2230],
  },
  {
    id: 'ios',
    title: 'iOS',
    data: [940, 955, 968, 984, 1005, 1018, 1042, 1058, 1075, 1098, 1110, 1126, 1148, 1168],
  },
  {
    id: 'android',
    title: 'Android',
    data: [1280, 1295, 1310, 1335, 1342, 1360, 1385, 1410, 1432, 1455, 1470, 1488, 1512, 1536],
  },
];
```

### Release Train Bug Count

```tsx
import { View, Text } from 'react-native';
import { SparklineChart } from '@plocks/charts';

import { BUG_BACKLOG } from './data';

export function Demo() {
  const latest = BUG_BACKLOG[BUG_BACKLOG.length - 1];
  const peak = Math.max(...BUG_BACKLOG);

  return (
    <View style={{ padding: 16, backgroundColor: '#fff', borderRadius: 12, width: 260 }}>
      <Text style={{ fontSize: 15, fontWeight: '600', marginBottom: 4 }}>Bugs per Release Train</Text>
      <Text style={{ fontSize: 12, color: '#666', marginBottom: 8 }}>
        Spike highlighted at {peak} bugs · Latest train: {latest} open
      </Text>

      <SparklineChart
        h={86}
        data={BUG_BACKLOG}
        color="#F03E3E"
        fill
        fillOpacity={0.12}
        smooth
        highlightLast
        highlightExtrema={{ showMax: true, showMin: false, color: '#F03E3E', radius: 4.5, strokeColor: '#FEE2E2', strokeWidth: 1.5 }}
        thresholds={[{ value: 18, label: 'Notice threshold', color: '#F87171', dashed: true, opacity: 0.8, labelPosition: 'left' }]}
        domain={{ y: [8, 26] }}
        valueFormatter={(value) => `${Math.round(value)} bugs`}
      />
    </View>
  );
}
```

`data.ts`

```ts
export const BUG_BACKLOG = [9, 11, 13, 12, 15, 18, 21, 24, 19, 16, 14, 12, 11, 10];
```

### Storefront Weekly Revenue

```tsx
import { View, Text } from 'react-native';
import { SparklineChart } from '@plocks/charts';

import { STOREFRONTS } from './data';

const formatRevenue = (value: number) => `$${value.toFixed(1)}k`;

export function Demo() {
  return (
    <View style={{ padding: 16, backgroundColor: '#fff', borderRadius: 12 }}>
      <Text style={{ fontSize: 15, fontWeight: '600', marginBottom: 4 }}>Weekly Revenue Snapshot</Text>
      <Text style={{ fontSize: 12, color: '#666', marginBottom: 12 }}>
        Seven-day trailing revenue (k USD) · Goal line at $110k
      </Text>

      <View style={{ flexDirection: 'row', flexWrap: 'wrap' }}>
        {STOREFRONTS.map((store) => {
          const latest = store.data[store.data.length - 1];
          const minimum = Math.min(...store.data);
          return (
            <View key={store.id} style={{ width: 200, marginRight: 16, marginBottom: 18 }}>
              <Text style={{ fontSize: 13, fontWeight: '600' }}>{store.name}</Text>
              <Text style={{ fontSize: 12, color: '#555', marginBottom: 6 }}>
                Latest: {formatRevenue(latest)} · Low: {formatRevenue(minimum)}
              </Text>
              <SparklineChart
                h={76}
                data={store.data}
                color={store.color}
                showPoints
                smooth
                fill
                fillOpacity={0.1}
                domain={{ y: [60, 140] }}
                highlightLast
                highlightExtrema={{ showMin: true, showMax: false, color: store.color, radius: 4, strokeColor: '#FFFFFF', strokeWidth: 1.2 }}
                thresholds={[{ value: 110, label: 'Target', dashed: true, color: '#64748B', opacity: 0.75, labelPosition: 'right' }]}
                valueFormatter={formatRevenue}
              />
            </View>
          );
        })}
      </View>
    </View>
  );
}
```

`data.ts`

```ts
export const STOREFRONTS = [
  {
    id: 'east-market',
    name: 'East Market',
    color: '#0EA5E9',
    data: [96, 98, 101, 99, 104, 112, 118, 121, 124, 129, 131, 136],
  },
  {
    id: 'central-plaza',
    name: 'Central Plaza',
    color: '#F59E0B',
    data: [88, 90, 93, 95, 96, 98, 101, 103, 105, 108, 112, 115],
  },
  {
    id: 'harbor-side',
    name: 'Harbor Side',
    color: '#10B981',
    data: [72, 78, 81, 86, 90, 95, 97, 100, 103, 106, 111, 114],
  },
];
```

### Support Queue Monitor

```tsx
import { View, Text } from 'react-native';
import { SparklineChart } from '@plocks/charts';

import { QUEUE_DEPTH } from './data';

export function Demo() {
  const current = QUEUE_DEPTH[QUEUE_DEPTH.length - 1];
  const peak = Math.max(...QUEUE_DEPTH);

  return (
    <View style={{ padding: 16, backgroundColor: '#fff', borderRadius: 12, width: 260 }}>
      <Text style={{ fontSize: 15, fontWeight: '600', marginBottom: 4 }}>Support Queue Length</Text>
      <Text style={{ fontSize: 12, color: '#666', marginBottom: 8 }}>
        Current queue: {current} tickets · Peak today: {peak}
      </Text>

      <SparklineChart
        h={82}
        data={QUEUE_DEPTH}
        fill
        fillOpacity={0.14}
        smooth
        highlightLast
        highlightExtrema={{ showMin: false, showMax: true, color: '#6366F1', radius: 4.5, strokeColor: '#EEF2FF', strokeWidth: 1.5 }}
        thresholds={[{ value: 12, label: 'SLA ceiling', dashed: true, color: '#A5B4FC', opacity: 0.85, labelPosition: 'right' }]}
        bands={[{ from: 0, to: 8, color: '#C7D2FE', opacity: 0.18 }]}
        domain={{ y: [4, 18] }}
        animation={{ duration: 400, easing: 'easeInOutCubic' }}
        valueFormatter={(value) => `${Math.round(value)} tickets`}
      />
    </View>
  );
}
```

`data.ts`

```ts
export const QUEUE_DEPTH = [6, 7, 8, 9, 11, 13, 15, 14, 12, 10, 9, 8, 7];
```

### Team Deploy Velocity

```tsx
import { View, Text } from 'react-native';
import { SparklineChart } from '@plocks/charts';

import { TEAMS } from './data';

export function Demo() {
  return (
    <View style={{ padding: 16, backgroundColor: '#fff', borderRadius: 12 }}>
      <Text style={{ fontSize: 15, fontWeight: '600', marginBottom: 4 }}>Deploy Velocity by Team</Text>
      <Text style={{ fontSize: 12, color: '#666', marginBottom: 12 }}>
        Rolling 12-day deploy counts · Targets shown as dashed lines
      </Text>

      <View>
        {TEAMS.map((team, index) => (
          <View key={team.id} style={{ marginBottom: index === TEAMS.length - 1 ? 0 : 16 }}>
            <Text style={{ fontSize: 13, fontWeight: '600', marginBottom: 6 }}>{team.name}</Text>
            <SparklineChart
              h={76}
              data={team.data}
              color={team.color}
              smooth
              fill
              fillOpacity={0.08}
              domain={{ y: [0, 9] }}
              highlightLast
              highlightExtrema={{ showMin: true, showMax: true, color: team.color, radius: 4, strokeColor: '#FFFFFF', strokeWidth: 1.2 }}
              thresholds={[{ value: team.target, label: `${team.target} target`, dashed: true, color: '#94A3B8', opacity: 0.85, labelPosition: 'right' }]}
              bands={[{ from: team.target - 0.5, to: team.target + 1, color: '#CBD5F5', opacity: 0.16 }]}
              animation={{ duration: 420, easing: 'easeOutQuad' }}
              valueFormatter={(value) => `${Math.round(value)} deploys`}
            />
          </View>
        ))}
      </View>
    </View>
  );
}
```

`data.ts`

```ts
export const TEAMS = [
  {
    id: 'alpha',
    name: 'Team Alpha',
    color: '#2563EB',
    target: 5,
    data: [3, 4, 5, 6, 5, 5, 6, 7, 6, 6, 7, 7],
  },
  {
    id: 'beta',
    name: 'Team Beta',
    color: '#EC4899',
    target: 4,
    data: [2, 2, 3, 4, 4, 5, 4, 4, 5, 6, 5, 5],
  },
  {
    id: 'gamma',
    name: 'Team Gamma',
    color: '#14B8A6',
    target: 6,
    data: [4, 5, 6, 6, 7, 7, 6, 7, 8, 8, 7, 8],
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/StackedAreaChart.md -->

# Stacked Area Chart

Area chart with multiple series stacked to show cumulative contributions.

## Metadata

- Import: `import { StackedAreaChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, area, stacked
- Docs: https://plocks.dev/charts/StackedAreaChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/StackedAreaChart

## Props

- `series` (required): LineChartSeries[] — Data series to stack
- `stackOrder`: 'normal' | 'reverse' = 'normal' — Order layers are stacked in
- `smooth`: boolean = true — Smooth (curved) area tops
- `opacity`: number = 0.55 — Base opacity for the stacked layers
- `stackMode`: 'absolute' | 'percentage' = 'absolute' — Stack values as absolute totals or normalized to 100%

Plus the `LineChart` props (`lineColor` `lineThickness` `lineStyle` `showPoints` `pointSize` `pointColor` `fillColor` `fillOpacity` `areaFillMode` `xAxis` `yAxis` `grid` `legend` `tooltip` `animation` `enableCrosshair` `enableSeriesToggle` `liveTooltip` `multiTooltip` `enablePanZoom` `zoomMode` `minZoom` `onDomainChange` `enableWheelZoom` `wheelZoomStep` `invertWheelZoom` `resetOnDoubleTap` `clampToInitialDomain` `invertPinchZoom` `disableAnimations` `decimationThreshold` `xScaleType` `yScaleType` `enableBrushZoom` `annotations`): https://plocks.dev/llms/components/LineChart.md

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Examples

### Basics

Area chart with multiple series stacked to show cumulative contributions.

```tsx
import { StackedAreaChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <StackedAreaChart
      title="Active users by surface"
      subtitle="Monthly totals"
      h={340}
      series={SERIES}
      stackOrder="normal"
      opacity={0.65}
      xAxis={{ show: true, title: 'Month', labelFormatter: (value) => `M${value}` }}
      yAxis={{
        show: true,
        title: 'Active users (thousands)',
        labelFormatter: (value) => `${value}`,
      }}
      grid={{ show: true }}
      legend={{ show: true, position: 'bottom' }}
      enableCrosshair
      multiTooltip
      liveTooltip
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'mobile',
    name: 'Mobile',
    data: [
      { x: 1, y: 22 },
      { x: 2, y: 26 },
      { x: 3, y: 28 },
      { x: 4, y: 32 },
      { x: 5, y: 36 },
      { x: 6, y: 38 },
      { x: 7, y: 42 },
      { x: 8, y: 44 },
      { x: 9, y: 47 },
      { x: 10, y: 50 },
      { x: 11, y: 52 },
      { x: 12, y: 55 },
    ],
  },
  {
    id: 'web',
    name: 'Web',
    data: [
      { x: 1, y: 18 },
      { x: 2, y: 20 },
      { x: 3, y: 22 },
      { x: 4, y: 25 },
      { x: 5, y: 26 },
      { x: 6, y: 27 },
      { x: 7, y: 28 },
      { x: 8, y: 30 },
      { x: 9, y: 32 },
      { x: 10, y: 33 },
      { x: 11, y: 34 },
      { x: 12, y: 35 },
    ],
  },
  {
    id: 'api',
    name: 'API',
    data: [
      { x: 1, y: 12 },
      { x: 2, y: 14 },
      { x: 3, y: 15 },
      { x: 4, y: 16 },
      { x: 5, y: 18 },
      { x: 6, y: 19 },
      { x: 7, y: 21 },
      { x: 8, y: 22 },
      { x: 9, y: 23 },
      { x: 10, y: 24 },
      { x: 11, y: 25 },
      { x: 12, y: 27 },
    ],
  },
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/StackedBarChart.md -->

# Stacked Bar Chart

Bar chart with segments stacked to show part-to-whole by category.

## Metadata

- Import: `import { StackedBarChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, bar, stacked
- Docs: https://plocks.dev/charts/StackedBarChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/StackedBarChart

## Props

- `series` (required): StackedBarSeries[] — Stacked bar series to render
- `barSpacing`: number = 0.25 — Gap between stacked groups
- `legend`: ChartLegend = { show: true, position: 'bottom', align: 'center' } — Legend configuration
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid line configuration
- `animation`: ChartAnimation — Animation configuration

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), chart events (`onPress` `onDataPointPress`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface StackedBarSeries {
  /** Unique identifier for the series */
  id?: string | number;
  /** Display name for the series */
  name?: string;
  /** Data points contained in the series */
  data: BarChartDataPoint[];
  /** Base color applied to the series */
  color?: string;
  /** Whether the series is visible */
  visible?: boolean;
}
```

## Examples

### Basics

Bar chart with segments stacked to show part-to-whole by category.

```tsx
import { StackedBarChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
	return (
		<StackedBarChart
			title="Quarterly ARR by motion"
			h={320}
			series={SERIES}
			barSpacing={0.25}
			xAxis={{ show: true, title: 'Quarter' }}
			yAxis={{
				show: true,
				title: 'ARR (USD thousands)',
				labelFormatter: (value) => `$${value}`,
			}}
			grid={{ show: true }}
			legend={{ show: true, position: 'bottom' }}
			animation={{ duration: 500 }}
		/>
	);
}
```

`data.ts`

```ts
export const SERIES = [
	{
		id: 'new-business',
		name: 'New business',
		data: [
			{ id: 'q1-new', category: 'Q1', value: 220 },
			{ id: 'q2-new', category: 'Q2', value: 250 },
			{ id: 'q3-new', category: 'Q3', value: 240 },
			{ id: 'q4-new', category: 'Q4', value: 280 },
		],
	},
	{
		id: 'expansion',
		name: 'Expansion',
		data: [
			{ id: 'q1-exp', category: 'Q1', value: 110 },
			{ id: 'q2-exp', category: 'Q2', value: 135 },
			{ id: 'q3-exp', category: 'Q3', value: 150 },
			{ id: 'q4-exp', category: 'Q4', value: 165 },
		],
	},
	{
		id: 'renewal',
		name: 'Renewal',
		data: [
			{ id: 'q1-renew', category: 'Q1', value: 180 },
			{ id: 'q2-renew', category: 'Q2', value: 172 },
			{ id: 'q3-renew', category: 'Q3', value: 188 },
			{ id: 'q4-renew', category: 'Q4', value: 194 },
		],
	},
];
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/components/ViolinChart.md -->

# Violin Chart

ViolinChart shows a data distribution with a mirrored density shape and summary statistics.

## Metadata

- Import: `import { ViolinChart } from '@plocks/charts';`
- Install: `npm install @plocks/charts` — a separate package from `@plocks/ui`
- Tags: chart, violin, distribution
- Docs: https://plocks.dev/charts/ViolinChart
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/charts/src/components/ViolinChart

## Props

- `series` (required): ViolinDensitySeries[] — Density series rendered within the violin chart
- `samples`: number — Density sample resolution
- `bandwidth`: number — Kernel bandwidth override
- `violinWidthRatio`: number — Relative width multiplier applied to each violin (0.2 - 1)
- `layout`: 'vertical' | 'horizontal' — Layout orientation
- `stackOverlap`: number — Overlap factor between adjacent violins (0 - 0.95)
- `xAxis`: ChartAxis — X-axis configuration
- `yAxis`: ChartAxis — Y-axis configuration
- `grid`: ChartGrid — Grid line configuration
- `statsMarkers`: ViolinStatsMarkersConfig — Statistic marker overlays for each violin
- `valueBands`: ViolinValueBand[] — Value range highlights rendered across the chart
- `legend`: ChartLegend — Legend configuration
- `onSeriesFocus`: (event: ViolinSeriesInteractionEvent) => void — Series focus callback
- `onSeriesBlur`: (event: ViolinSeriesInteractionEvent) => void — Series blur callback
- `onSeriesPress`: (event: ViolinSeriesInteractionEvent) => void — Series press/tap callback

Also accepts the shared props — chart (`w` `h` `aspectRatio` `maw` `miw` `mah` `mih` `testID` `style` `accessibilityLabel` `accessibilityHint` `accessibilityRole` `accessible` `importantForAccessibility` `animationDuration` `animationEasing` `disabled` `title` `subtitle` `useOwnInteractionProvider` `suppressPopover`), spacing (`m` `mt` `mr` `mb` `ml` `mx` `my` `p` `pt` `pr` `pb` `pl` `px` `py`): https://plocks.dev/llms/guides/shared-props.md

## Types

```ts
export interface ViolinDensitySeries extends DensitySeries {
  /** Pre-computed density points (skip internal KDE) */
  preparedDensity?: ViolinDensityPoint[];
  /** Override bandwidth for this series */
  bandwidth?: number;
  /** Adaptive bandwidth heuristic */
  adaptiveBandwidth?: 'scott' | 'silverman';
}

export interface ViolinStatsMarkersConfig {
  /** Master enable toggle; inferred from child flags when omitted */
  enabled?: boolean;
  /** Render median marker */
  showMedian?: boolean;
  /** Render mean marker */
  showMean?: boolean;
  /** Render interquartile band (Q1-Q3) */
  showQuartiles?: boolean;
  /** Render whiskers spanning min/max */
  showWhiskers?: boolean;
  /** Relative width multiplier for markers (0-1, defaults to 0.85) */
  markerWidthRatio?: number;
  /** Stroke width applied to marker lines (defaults to 2) */
  strokeWidth?: number;
  /** Optional colors per statistic */
  colors?: Partial<Record<'median' | 'mean' | 'quartile' | 'whisker', string>>;
  /** Annotate markers with value labels */
  showLabels?: boolean;
  /** Additional offset in px for labels (defaults to 6) */
  labelOffset?: number;
  /** Custom formatter for marker labels */
  labelFormatter?: (params: {
    stat: 'median' | 'mean' | 'q1' | 'q3' | 'whisker-min' | 'whisker-max';
    value: number;
    series: ViolinDensitySeries;
    formattedValue: string;
  }) => string;
}

export interface ViolinValueBand {
  /** Identifier for the value band */
  id?: string;
  /** Human-readable label rendered inside the band */
  label?: string;
  /** Lower bound of the highlighted range */
  from: number;
  /** Upper bound of the highlighted range */
  to: number;
  /** Fill color applied to the band */
  color?: string;
  /** Override opacity for the band (0-1) */
  opacity?: number;
  /** Text color for the label */
  labelColor?: string;
  /** Label anchor position */
  labelPosition?: 'left' | 'right';
}

export interface ViolinSeriesInteractionEvent {
  series: ViolinDensitySeries;
  seriesIndex: number;
  stats: ViolinSeriesStats | null;
  density: ViolinDensityPoint[];
}

export interface ViolinDensityPoint {
  x: number;
  y: number;
}

export interface ViolinSeriesStats {
  min: number;
  max: number;
  mean: number;
  median: number;
  q1: number;
  q3: number;
  p10: number;
  p90: number;
}
```

## Examples

### Basics

ViolinChart shows a data distribution with a mirrored density shape and summary statistics.

```tsx
import { ViolinChart } from '@plocks/charts';

import { SERIES } from './data';

export function Demo() {
  return (
    <ViolinChart
      title="Delivery time distribution"
      h={360}
      series={SERIES}
      samples={128}
      bandwidth={3.5}
    />
  );
}
```

`data.ts`

```ts
export const SERIES = [
  {
    id: 'north',
    name: 'North region',
    values: [
      45, 47, 48, 49, 50, 51, 52, 53, 53, 54, 55, 55, 56, 58, 59, 60, 61,
    ],
  },
  {
    id: 'south',
    name: 'South region',
    values: [
      38, 39, 40, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 52, 53, 54,
    ],
  },
  {
    id: 'west',
    name: 'West region',
    values: [
      52, 53, 54, 55, 56, 57, 58, 59, 60, 60, 61, 62, 63, 64, 65, 65, 66,
    ],
  },
];
```

### Delivery Times

```tsx
import { ViolinChart } from '@plocks/charts';

import { FULFILLMENT_CENTERS, SLA_WINDOW, STATS_MARKERS } from './data';

export function Demo() {
  return (
    <ViolinChart
      title="Delivery time spread by fulfillment center"
      subtitle="Distribution of hours from order capture to doorstep delivery"
      h={460}
      series={FULFILLMENT_CENTERS}
      samples={96}
      bandwidth={1.6}
      violinWidthRatio={0.82}
      statsMarkers={STATS_MARKERS}
      valueBands={SLA_WINDOW}
      yAxis={{ title: 'Hours to deliver', show: true, labelFormatter: (value) => `${value.toFixed(0)}h` }}
    />
  );
}
```

`data.ts`

```ts
import type { DensitySeries, ViolinStatsMarkersConfig, ViolinValueBand } from '@plocks/charts';

export const createDistribution = (mean: number, spread: number, count: number, floor: number) =>
  Array.from({ length: count }, (_, index) => {
    const angle = index * 0.37;
    const wobble = Math.sin(angle) * spread + Math.cos(angle * 0.53) * spread * 0.6;
    const seasonal = ((index % 9) - 4) * 0.12 * spread;
    const value = Math.max(floor, mean + wobble + seasonal);
    return Number(value.toFixed(2));
  });

export const FULFILLMENT_CENTERS: DensitySeries[] = [
  {
    id: 'northeast',
    name: 'Northeast Hub',
    values: createDistribution(27.5, 3.2, 140, 18),
  },
  {
    id: 'pacific',
    name: 'Pacific Hub',
    values: createDistribution(30.4, 3.8, 140, 20),
  },
  {
    id: 'central',
    name: 'Central Sortation',
    values: createDistribution(24.6, 2.9, 140, 16),
  },
  {
    id: 'southern',
    name: 'South Regional',
    values: createDistribution(29.1, 3.4, 140, 18),
  },
];

export const SLA_WINDOW: ViolinValueBand[] = [
  {
    id: 'sla',
    label: 'Target SLA window (22-30 hrs)',
    from: 22,
    to: 30,
    color: '#38D9A9',
    opacity: 0.16,
    labelPosition: 'right',
  },
];

export const STATS_MARKERS: ViolinStatsMarkersConfig = {
  showMedian: true,
  showQuartiles: true,
  showWhiskers: true,
  showLabels: true,
  colors: {
    median: '#0B7285',
    quartile: '#4C6EF5',
    whisker: '#ADB5BD',
  },
};
```

### Experiment Metric Deltas

```tsx
import { ViolinChart } from '@plocks/charts';

import { EXPERIMENT_SERIES, STATS, VALUE_BANDS } from './data';

export function Demo() {
  return (
    <ViolinChart
      title="Experiment metric deltas vs. control"
      subtitle="Percent change in weekly activation compared to holdout"
      h={460}
      series={EXPERIMENT_SERIES}
      samples={88}
      bandwidth={1.5}
      violinWidthRatio={0.68}
      statsMarkers={STATS}
      valueBands={VALUE_BANDS}
      yAxis={{
        title: 'Percent delta',
        labelFormatter: (value) => `${value.toFixed(1)}%`,
      }}
      xAxis={{ show: true, title: 'Variant cohorts' }}
    />
  );
}
```

`data.ts`

```ts
import type { DensitySeries, ViolinStatsMarkersConfig, ViolinValueBand } from '@plocks/charts';

export const createDistribution = (mean: number, spread: number, count: number) =>
  Array.from({ length: count }, (_, index) => {
    const angle = index * 0.39;
    const texture = Math.sin(angle) * spread + Math.cos(angle * 0.57) * spread * 0.52;
    const drift = ((index % 10) - 5) * 0.07 * spread;
    const value = mean + texture + drift;
    return Number(value.toFixed(2));
  });

export const EXPERIMENT_SERIES: DensitySeries[] = [
  {
    id: 'control',
    name: 'Control holdout',
    values: createDistribution(0.1, 0.9, 140),
    strokeColor: '#868E96',
  },
  {
    id: 'variant-a',
    name: 'Variant A — onboarding nudge',
    values: createDistribution(1.8, 1.2, 140),
  },
  {
    id: 'variant-b',
    name: 'Variant B — personalization',
    values: createDistribution(3.6, 1.5, 140),
  },
  {
    id: 'variant-c',
    name: 'Variant C — price emphasis',
    values: createDistribution(-0.6, 1.1, 140),
  },
];

export const VALUE_BANDS: ViolinValueBand[] = [
  {
    id: 'neutral-band',
    from: -1,
    to: 1,
    label: 'Neutral delta corridor',
    color: '#DEE2E6',
    opacity: 0.32,
    labelPosition: 'left',
    labelColor: '#495057',
  },
  {
    id: 'meaningful-lift',
    from: 2,
    to: 6,
    label: 'Meaningful lift zone',
    color: '#51CF66',
    opacity: 0.18,
    labelPosition: 'right',
    labelColor: '#2B8A3E',
  },
];

export const STATS: ViolinStatsMarkersConfig = {
  showMedian: true,
  showMean: true,
  showWhiskers: true,
  showLabels: true,
  markerWidthRatio: 0.72,
  colors: {
    median: '#364FC7',
    mean: '#0B7285',
    whisker: '#868E96',
  },
};
```

### Model Prediction Errors

```tsx
import { ViolinChart } from '@plocks/charts';

import { ERROR_SERIES, STATS, VALUE_BANDS } from './data';

export function Demo() {
  return (
    <ViolinChart
      title="Prediction error distribution per model version"
      subtitle="Mean absolute error (percentage points) across validation folds"
      h={460}
      series={ERROR_SERIES}
      samples={96}
      bandwidth={0.9}
      violinWidthRatio={0.78}
      statsMarkers={STATS}
      valueBands={VALUE_BANDS}
      yAxis={{
        title: 'MAE (%)',
        labelFormatter: (value) => `${value.toFixed(2)}%`,
      }}
    />
  );
}
```

`data.ts`

```ts
import type { DensitySeries, ViolinStatsMarkersConfig, ViolinValueBand } from '@plocks/charts';

export const createDistribution = (mean: number, spread: number, count: number, floor = 0.2) =>
  Array.from({ length: count }, (_, index) => {
    const angle = index * 0.35;
    const variance = Math.sin(angle) * spread + Math.cos(angle * 0.49) * spread * 0.58;
    const drift = ((index % 12) - 6) * 0.04 * spread;
    const value = Math.max(floor, mean + variance + drift);
    return Number(value.toFixed(3));
  });

export const ERROR_SERIES: DensitySeries[] = [
  {
    id: 'v1',
    name: 'Model v1 — baseline',
    values: createDistribution(2.85, 0.45, 150, 1.1),
    strokeColor: '#868E96',
    fillOpacity: 0.28,
  },
  {
    id: 'v2',
    name: 'Model v2 — feature store refresh',
    values: createDistribution(2.12, 0.38, 150, 0.9),
    fillOpacity: 0.32,
  },
  {
    id: 'v3',
    name: 'Model v3 — explainable boosting',
    values: createDistribution(1.46, 0.33, 150, 0.7),
    fillOpacity: 0.34,
  },
  {
    id: 'v4',
    name: 'Model v4 — ensemble',
    values: createDistribution(1.08, 0.28, 150, 0.6),
    fillOpacity: 0.36,
  },
];

export const VALUE_BANDS: ViolinValueBand[] = [
  {
    id: 'target-zone',
    from: 0.8,
    to: 1.6,
    label: 'Target MAE window',
    color: '#69DB7C',
    opacity: 0.18,
    labelPosition: 'right',
    labelColor: '#2F9E44',
  },
  {
    id: 'alert-zone',
    from: 2.4,
    to: 3.4,
    label: 'Alert threshold',
    color: '#FFA8A8',
    opacity: 0.22,
    labelPosition: 'left',
    labelColor: '#C92A2A',
  },
];

export const STATS: ViolinStatsMarkersConfig = {
  showMedian: true,
  showQuartiles: true,
  showMean: true,
  showLabels: true,
  colors: {
    median: '#364FC7',
    quartile: '#15AABF',
    mean: '#0B7285',
  },
  markerWidthRatio: 0.76,
};
```

### Salary Distribution

```tsx
import { ViolinChart } from '@plocks/charts';

import { MARKET_RANGE, SALARY_SERIES, STATS } from './data';

export function Demo() {
  return (
    <ViolinChart
      title="Total compensation distribution by department"
      subtitle="Annual salary including bonus (USD thousands)"
      h={480}
      series={SALARY_SERIES}
      samples={96}
      bandwidth={2.8}
      violinWidthRatio={0.74}
      statsMarkers={STATS}
      valueBands={MARKET_RANGE}
      yAxis={{
        title: 'Total compensation (k$)',
        labelFormatter: (value) => `$${value.toFixed(0)}k`,
      }}
    />
  );
}
```

`data.ts`

```ts
import type { DensitySeries, ViolinStatsMarkersConfig, ViolinValueBand } from '@plocks/charts';

export const createDistribution = (median: number, spread: number, count: number) =>
  Array.from({ length: count }, (_, index) => {
    const angle = index * 0.41;
    const oscillation = Math.sin(angle) * spread + Math.cos(angle * 0.63) * spread * 0.55;
    const progression = ((index % 11) - 5) * 0.09 * spread;
    const value = Math.max(48, median + oscillation + progression);
    return Number(value.toFixed(1));
  });

export const SALARY_SERIES: DensitySeries[] = [
  {
    id: 'engineering',
    name: 'Engineering',
    values: createDistribution(128, 14, 160),
    fillOpacity: 0.32,
  },
  {
    id: 'design',
    name: 'Design',
    values: createDistribution(104, 11, 160),
    fillOpacity: 0.32,
  },
  {
    id: 'product',
    name: 'Product',
    values: createDistribution(118, 12, 160),
    fillOpacity: 0.32,
  },
  {
    id: 'marketing',
    name: 'Marketing',
    values: createDistribution(96, 10, 160),
    fillOpacity: 0.32,
  },
];

export const MARKET_RANGE: ViolinValueBand[] = [
  {
    id: 'market',
    from: 88,
    to: 112,
    label: 'Market reference band',
    color: '#228BE6',
    opacity: 0.14,
    labelPosition: 'left',
    labelColor: '#1C7ED6',
  },
];

export const STATS: ViolinStatsMarkersConfig = {
  showMedian: true,
  showQuartiles: true,
  showMean: true,
  showLabels: true,
  colors: {
    median: '#364FC7',
    quartile: '#1971C2',
    mean: '#2F9E44',
  },
  markerWidthRatio: 0.78,
};
```

### Session Duration By Platform

```tsx
import { ViolinChart } from '@plocks/charts';

import { ENGAGEMENT_BANDS, SESSION_SERIES, STATS } from './data';

export function Demo() {
  return (
    <ViolinChart
      title="Session duration distribution by platform"
      subtitle="Minutes per active session across major surfaces"
      h={440}
      series={SESSION_SERIES}
      samples={88}
      bandwidth={1.9}
      violinWidthRatio={0.7}
      statsMarkers={STATS}
      valueBands={ENGAGEMENT_BANDS}
      yAxis={{
        title: 'Minutes per session',
        labelFormatter: (value) => `${value.toFixed(1)} min`,
      }}
    />
  );
}
```

`data.ts`

```ts
import type { DensitySeries, ViolinStatsMarkersConfig, ViolinValueBand } from '@plocks/charts';

export const createDistribution = (mean: number, spread: number, count: number, floor = 0.6) =>
  Array.from({ length: count }, (_, index) => {
    const angle = index * 0.43;
    const contour = Math.sin(angle) * spread + Math.cos(angle * 0.61) * spread * 0.45;
    const usageCycle = ((index % 13) - 6) * 0.05 * spread;
    const value = Math.max(floor, mean + contour + usageCycle);
    return Number(value.toFixed(2));
  });

export const SESSION_SERIES: DensitySeries[] = [
  {
    id: 'ios',
    name: 'iOS',
    values: createDistribution(6.8, 2.4, 150),
  },
  {
    id: 'android',
    name: 'Android',
    values: createDistribution(7.4, 2.8, 150),
  },
  {
    id: 'web',
    name: 'Web',
    values: createDistribution(5.1, 2.2, 150),
  },
  {
    id: 'tv',
    name: 'Smart TV',
    values: createDistribution(11.2, 3.5, 150, 2.2),
  },
];

export const ENGAGEMENT_BANDS: ViolinValueBand[] = [
  {
    id: 'sweet-spot',
    from: 3,
    to: 8,
    label: 'Engagement sweet spot',
    color: '#94D82D',
    opacity: 0.12,
    labelPosition: 'left',
  },
];

export const STATS: ViolinStatsMarkersConfig = {
  showMedian: true,
  showMean: true,
  showLabels: true,
  colors: {
    median: '#364FC7',
    mean: '#2B8A3E',
  },
  markerWidthRatio: 0.8,
};
```

--------------------------------------------------------------------------------

# HOOKS

<!-- source: https://plocks.dev/llms/hooks/useA11yId.md -->

# useA11yId

A stable, SSR-safe element id for ARIA references like `aria-controls` and `aria-labelledby`. It returns the id you pass, or a sanitized `useId()` that is valid as a DOM id, a CSS selector and a native `nativeID`.

## Metadata

- Import: `import { useA11yId } from '@plocks/ui';`
- Tags: accessibility, id, aria
- Docs: https://plocks.dev/hooks/useA11yId
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/accessibility/useA11yId.ts

## Definition

```ts
export function useA11yId(explicitId?: string, prefix: string = 'plocks'): string;
```

## Examples

### Disclosure ids

`useA11yId(explicitId?, prefix = 'plocks')` returns `explicitId` when you pass one. Otherwise it returns React's `useId()` stripped to `[A-Za-z0-9_-]` behind the prefix (`«r1»` becomes `faq-r1`), which is unique per instance and the same on server and client. Here each trigger points `aria-controls` at its own panel, and the second disclosure passes `id="returns-policy"` through unchanged. Pass the id to an element's `id` prop: it becomes the DOM `id` on web, and React Native maps it to `nativeID`.

```tsx
import { useState } from 'react';
import { Block, Button, Code, Icon, Text, a11yProps, useA11yId } from '@plocks/ui';

interface DisclosureProps {
  id?: string;
  title: string;
  children: string;
}

function Disclosure({ id, title, children }: DisclosureProps) {
  const [open, setOpen] = useState(false);
  const panelId = useA11yId(id, 'faq');

  return (
    <Block gap="xs">
      <Block direction="row" align="center" justify="space-between" gap="md">
        <Button
          variant="subtle"
          endSection={<Icon name={open ? 'chevron-up' : 'chevron-down'} size={16} />}
          onPress={() => setOpen((current) => !current)}
          {...a11yProps({ expanded: open, controls: open ? panelId : undefined })}
        >
          {title}
        </Button>
        <Code>{panelId}</Code>
      </Block>
      {open ? (
        <Block id={panelId} px="md">
          <Text>{children}</Text>
        </Block>
      ) : null}
    </Block>
  );
}

export function Demo() {
  return (
    <Block fullWidth maw={420}>
      <Disclosure title="Shipping">Orders ship within two business days.</Disclosure>
      <Disclosure id="returns-policy" title="Returns">
        Unused items can be returned within 30 days.
      </Disclosure>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useAccessibility.md -->

# useAccessibility

Read the whole `AccessibilityProvider` context at once: `announce()`, the announcement log, focus tracking, and screen reader and reduced-motion state. It re-renders on every change, so when you only need one of these, use `announce` or `useReducedMotion` instead.

## Metadata

- Import: `import { useAccessibility } from '@plocks/ui';`
- Tags: accessibility, announce, screen-reader, provider
- Docs: https://plocks.dev/hooks/useAccessibility
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/accessibility/context.tsx

## Definition

```ts
export function useAccessibility(): AccessibilityContextValue;
```

## Examples

### Announcement log

`announce(message, priority?)` speaks through the screen reader (a live region on web, `AccessibilityInfo` on native) and adds the message to `announcements`, a log that drops each entry after 3 s, or 5 s for `'assertive'`. The value also has `clearAnnouncements`, `prefersReducedMotion`, `screenReaderEnabled` (always `false` on web because browsers do not expose this state), and a focus log, `currentFocusId` / `focusHistory` / `setFocus(id)` / `restoreFocus()`, that records ids without moving focus. `useAccessibility()` throws outside an `AccessibilityProvider`. `PlocksProvider` already mounts one, and `<AccessibilityProvider reducedMotion>` forces reduced motion for its subtree. Because it re-renders on every focus change and announcement, use the standalone `announce(message, { politeness })` or `useReducedMotion()` when that is all you need.

```tsx
import { Block, Button, Text, useAccessibility } from '@plocks/ui';

export function Demo() {
  const { announce, announcements } = useAccessibility();

  return (
    <Block align="flex-start">
      <Button onPress={() => announce(`Draft saved at ${new Date().toLocaleTimeString()}`)}>Save draft</Button>

      {announcements.map((message, index) => (
        <Text key={`${index}-${message}`} size="sm">
          {message}
        </Text>
      ))}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useAdjustable.md -->

# useAdjustable

Make a custom value control (a slider, knob or meter) adjustable. It gives the control `role="slider"` with its value range, arrow/Page/Home/End keys on web, and increment/decrement actions for VoiceOver and TalkBack.

## Metadata

- Import: `import { useAdjustable } from '@plocks/ui';`
- Tags: accessibility, keyboard, slider, value
- Docs: https://plocks.dev/hooks/useAdjustable
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/accessibility/useAdjustable.ts

## Definition

```ts
export interface UseAdjustableOptions {
  value: number;
  min: number;
  max: number;
  /** Arrow-key / accessibility-action step. Default: 1, or 1% of the range if `step <= 0`. */
  step?: number;
  /** PageUp/PageDown distance. Default: 10% of the range. */
  largeStep?: number;
  /** Called with every new value. */
  onChange: (value: number) => void;
  /** Called after each discrete adjustment (keyboard, accessibility action). */
  onChangeEnd?: (value: number) => void;
  /** Accessible name. */
  label?: string;
  labelledBy?: IdRefs;
  describedBy?: IdRefs;
  /** Native hint. */
  hint?: string;
  /** Spoken value (`'40 percent'`), or a formatter. */
  valueText?: string | ((value: number) => string);
  /** Default `'horizontal'`. Only horizontal arrows swap under RTL. */
  orientation?: 'horizontal' | 'vertical';
  disabled?: boolean;
  readOnly?: boolean;
  /** Override reading direction. Default: `useDirection().isRTL`. */
  rtl?: boolean;
  /**
   * Endless controls (a rotary knob with no stops): values are not clamped and
   * Home/End do nothing.
   */
  endless?: boolean;
  /**
   * Custom stepping (detents, marks): the next value from `current` in
   * `direction` for a nudge of `amount`. Result is still clamped (unless endless).
   */
  getNextValue?: (current: number, direction: 1 | -1, amount: number) => number;
  /** Values for Home/End. Default `min` / `max`. */
  getBoundValue?: (bound: 'min' | 'max') => number;
  /** Element id. */
  id?: string;
}

export interface UseAdjustableResult {
  /** Spread on the focusable thumb. */
  adjustableProps: AdjustableProps;
  /** Nudge up by `amount` (default `step`). */
  increment: (amount?: number) => void;
  /** Nudge down by `amount` (default `step`). */
  decrement: (amount?: number) => void;
  /** The key handler, for elements that route keys themselves. Returns true when handled. */
  handleKeyDown: (event: KeyboardEventLike) => boolean;
}

export type AdjustableProps = A11yProps & {
  /** Web only: the thumb is a tab stop unless disabled. */
  tabIndex?: 0 | -1;

export function useAdjustable(options: UseAdjustableOptions): UseAdjustableResult;
```

## Examples

### Custom volume slider

The bar meter is the slider. Tab to it: the arrow keys move by `step` (Shift+arrow by ten steps, and the horizontal arrows swap under RTL), PageUp/PageDown move by `largeStep` (default 10% of the range), and Home/End jump to `min` / `max`. VoiceOver and TalkBack adjust it with their increment/decrement gestures and read `valueText` ("60 percent"). `useAdjustable({ value, min, max, step, onChange, label, valueText })` returns `adjustableProps` for the focusable element, `increment` / `decrement` (the − and + buttons here) and `handleKeyDown`; each change is clamped to the range and calls `onChange`, then `onChangeEnd`. It also takes `disabled`, `readOnly`, `orientation: 'vertical'`, `endless` (no clamping and no Home/End) and `getNextValue` for detents.

```tsx
import { useState } from 'react';
import { Block, IconButton, useAdjustable } from '@plocks/ui';

const LEVELS = 10;

export function Demo() {
  const [level, setLevel] = useState(6);
  const { adjustableProps, increment, decrement } = useAdjustable({
    value: level,
    min: 0,
    max: LEVELS,
    step: 1,
    onChange: setLevel,
    label: 'Volume',
    valueText: (value) => `${value * 10} percent`,
  });

  return (
    <Block direction="row" align="center" gap="sm">
      <IconButton icon="minus" variant="ghost" accessibilityLabel="Quieter" onPress={() => decrement()} />
      <Block {...adjustableProps} direction="row" align="flex-end" gap={4} p="xs" radius="sm">
        {Array.from({ length: LEVELS }, (_, index) => (
          <Block
            key={index}
            w={8}
            h={8 + index * 3}
            radius={2}
            bg={index < level ? 'primary.5' : 'borderStrong'}
          />
        ))}
      </Block>
      <IconButton icon="plus" variant="ghost" accessibilityLabel="Louder" onPress={() => increment()} />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useBreakpoint.md -->

# useBreakpoint

Get the current breakpoint name (`base`, `xs`, `sm`, `md`, `lg` or `xl`) from the theme's breakpoint table, re-rendering only when the viewport crosses a breakpoint rather than on every resize.

## Metadata

- Import: `import { useBreakpoint } from '@plocks/ui';`
- Tags: responsive, breakpoints, viewport
- Docs: https://plocks.dev/hooks/useBreakpoint
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/components/AppShell/hooks/useBreakpoint.ts

## Definition

```ts
export function useBreakpoint(): Breakpoint;
```

## Examples

### Adapt per breakpoint

`useBreakpoint()` returns a `Breakpoint`: `base` below `xs`, then `xs` (480), `sm` (576), `md` (768), `lg` (992) and `xl` (1200) by default. The widths come from `theme.breakpoints`; wrap a subtree in `<BreakpointProvider breakpoints={{ md: 900 }}>` to override some of them there. `resolveResponsiveValue(value, breakpoint)` picks the entry of a `{ base, sm, … }` map defined at or nearest below the current breakpoint, and parses the result as a px number. Breakpoints follow the window, not the preview container, and static rendering assumes `xl` until hydration.

```tsx
import { Badge, Block, Row, resolveResponsiveValue, useBreakpoint } from '@plocks/ui';

export function Demo() {
  const breakpoint = useBreakpoint();
  const columns = resolveResponsiveValue({ base: 1, sm: 2, md: 3, lg: 4 }, breakpoint);

  return (
    <Block fullWidth align="flex-start">
      <Badge size="lg">{breakpoint}</Badge>
      <Row gap="sm" w="full">
        {Array.from({ length: columns }, (_, i) => (
          <Block key={i} grow h={56} radius="md" bg="primary" />
        ))}
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useClipboard.md -->

# useClipboard

Copy values to the system clipboard with optimistic status updates and optional reset timers.

## Metadata

- Import: `import { useClipboard } from '@plocks/ui';`
- Tags: clipboard, copy
- Docs: https://plocks.dev/hooks/useClipboard
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useClipboard/index.ts

## Definition

```ts
export interface UseClipboardOptions {
  /** Time in ms after which the copied state will reset, 2000 by default. `0` keeps it until `reset()`. */
  timeout?: number;
}

export interface UseClipboardReturnValue {
  /**
   * Copies `value` (strings as-is, anything else JSON-stringified). Resolves
   * `true` once the text is on the clipboard, `false` when copying failed —
   * the failure also lands in `error`; it never rejects.
   */
  copy: (value: unknown) => Promise<boolean>;
  /** Function to reset copied state and error */
  reset: () => void;
  /** Error if copying failed */
  error: Error | null;
  /** Boolean indicating if the value was copied successfully */
  copied: boolean;
  /** The last copied value (stringified) */
  lastValue: string | null;
  /**
   * True when there is no way to copy: web without both `navigator.clipboard`
   * and the `execCommand('copy')` fallback, or native without `expo-clipboard`.
   * Always `false` during server rendering and hydration.
   */
  unsupported: boolean;
}

export function useClipboard(options: UseClipboardOptions = {}): UseClipboardReturnValue;
```

## Examples

### Copy invite link

Trigger clipboard writes and expose helpful status text while the hook handles fallbacks and resets.

```tsx
import { useState } from 'react';
import { Badge, Block, Button, Input, useClipboard } from '@plocks/ui';

const INVITE_URL = 'https://app.example.com/invite/engineering';

export function Demo() {
  const { copy, copied, unsupported, lastValue } = useClipboard({ timeout: 1500 });
  const [value, setValue] = useState(INVITE_URL);

  return (
    <Block align="flex-start" maw={460} fullWidth>
      <Input
        label="Invite URL"
        value={value}
        onChangeText={setValue}
        error={unsupported ? 'Clipboard access is not available in this environment.' : undefined}
        description="The copied state resets automatically after 1.5 seconds."
        textInputProps={{ autoCapitalize: 'none' }}
      />
      <Button onPress={() => copy(value)} disabled={unsupported}>
        {copied ? 'Copied!' : 'Copy link'}
      </Button>
      {lastValue ? (
        <Badge variant="subtle" c={copied ? 'success' : 'gray'}>
          Last copied: {lastValue}
        </Badge>
      ) : null}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useColorScheme.md -->

# useColorScheme

Read the operating system's light/dark preference and re-render when it changes (`prefers-color-scheme` on web, `Appearance` on native). It ignores the app's own mode; for the scheme the app is actually rendering, read `useTheme().colorScheme`.

## Metadata

- Import: `import { useColorScheme } from '@plocks/ui';`
- Tags: theme, dark-mode, color-scheme, system
- Docs: https://plocks.dev/hooks/useColorScheme
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/theme/useColorScheme.ts

## Definition

```ts
export type ColorScheme = 'light' | 'dark';

export function useColorScheme(): ColorScheme;
```

## Examples

### System color scheme

`useColorScheme()` returns `'light' | 'dark'` from the OS and needs no provider. Switch your system appearance to see it update; the docs site's own theme toggle doesn't affect it. Static rendering has no OS to ask, so the server renders `'light'` and the client corrects it before first paint.

```tsx
import { Icon, Row, Text, useColorScheme } from '@plocks/ui';

export function Demo() {
  const scheme = useColorScheme();

  return (
    <Row gap="sm" align="center">
      <Icon name={scheme === 'dark' ? 'moon' : 'sun'} size="lg" />
      <Text fw="600">System: {scheme}</Text>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useControllableState.md -->

# useControllableState

Back a value-bearing component with either a controlled `value` prop or internal state, decided by one call.

## Metadata

- Import: `import { useControllableState } from '@plocks/ui';`
- Tags: state, controlled, uncontrolled, forms
- Docs: https://plocks.dev/hooks/useControllableState
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useControllableState/useControllableState.ts

## Definition

```ts
export interface UseControllableStateOptions<T> {
  /**
   * The controlled value. When this is anything other than `undefined` the
   * component is controlled: internal state is never written, and `setValue`
   * only reports the requested value through `onChange`.
   */
  value?: T;
  /**
   * Initial value used while uncontrolled. Accepts a factory, like `useState`,
   * for defaults that are expensive or must not be recomputed every render
   * (`() => new Date()`, a value read back from storage, …).
   *
   * Same caveat as `useState`: a `T` that is itself a function must be wrapped
   * in a factory, since a function argument is always treated as one.
   */
  defaultValue?: T | (() => T);
  /**
   * Value used while uncontrolled when `defaultValue` is also `undefined` —
   * the component's own "empty" value (`''`, `0`, `false`, `[]`, …).
   */
  finalValue?: T;
  /**
   * Called with every requested value, in both modes, synchronously from the
   * caller's event handler. Extra arguments passed to `setValue` are forwarded
   * after the value, so component-specific payloads survive.
   *
   * Declared with method syntax on purpose: method parameters are checked
   * bivariantly, so a handler typed `(value: T, option: MyOption) => void`
   * is accepted without the payload being `any`.
   */
  onChange?(value: T, ...payload: unknown[]): void;
}

export type UseControllableStateReturn<T> = readonly [
  /** The value to render — the controlled prop, or internal state. */
  T,
  /** Request a new value. Accepts a value or an updater function. */
  (next: ControllableStateAction<T>, ...payload: unknown[]) => void,
  /** `true` while the `value` prop is driving the component. */
  boolean,
];

export type ControllableStateAction<T> = T | ((previous: T) => T);

export function useControllableState<T>({ value, defaultValue, finalValue, onChange, }: UseControllableStateOptions<T>): UseControllableStateReturn<T>;
```

## Examples

### Controlled and uncontrolled

`useControllableState` replaces the hand-rolled `isControlled` + `internalValue` + sync-effect trio with one call. A component is **controlled** when its `value` prop is anything other than `undefined` — the parent owns the value and the hook never writes internal state. Otherwise it is **uncontrolled**, and the hook keeps the value in `useState`, seeded from `defaultValue` (falling back to `finalValue`).

The same `StarPicker` is rendered twice below: once with only `defaultValue`, once with `value` + `onChange`.

## Signature

```ts
const [value, setValue, isControlled] = useControllableState({
  value: props.value,           // controlled value (undefined ⇒ uncontrolled)
  defaultValue: props.defaultValue,
  finalValue: 0,                // fallback when neither is provided
  onChange: props.onChange,
});
```

## Behavior

- `onChange` fires **synchronously** from your event handler in both modes — not from an effect — so callbacks land before paint.
- `setValue` accepts a value or an updater function, like `useState`. Several updater calls inside one handler compose against each other.
- Extra arguments are forwarded to `onChange` after the value: `setValue(next, { source: 'keyboard' })` calls `onChange(next, { source: 'keyboard' })`.
- `setValue` is referentially stable for the component's lifetime — safe in dependency arrays and memoized context values.
- Switching controlled → uncontrolled mid-life seeds internal state with the last controlled value so the UI holds its position. Any mode switch logs a warning in development.

## See also

- `useDisclosure` — the boolean-only case, with `open` / `close` / `toggle`
- `useDebouncedValue` — debounce a value before acting on it

```tsx
import { useState } from 'react';
import { Badge, Block, Button, Rating, Row, Text, useControllableState } from '@plocks/ui';

interface StarPickerProps {
  /** Controlled value. Passing this hands ownership to the parent. */
  value?: number;
  /** Initial value while uncontrolled. */
  defaultValue?: number;
  onChange?: (value: number) => void;
}

/** One component that supports both modes — the hook decides which is active. */
function StarPicker({ value, defaultValue, onChange }: StarPickerProps) {
  const [rating, setRating, isControlled] = useControllableState({
    value,
    defaultValue,
    finalValue: 0,
    onChange
  });

  return (
    <Row gap="sm" align="center">
      <Rating value={rating} onChange={setRating} />
      <Badge variant="light" c={isControlled ? 'primary' : 'gray'}>
        {isControlled ? 'controlled' : 'uncontrolled'}
      </Badge>
    </Row>
  );
}

export function Demo() {
  const [rating, setRating] = useState(3);

  return (
    <Block gap="lg">
      <Block gap="xs">
        <Text size="sm" c="muted">No value prop — the hook keeps the rating in internal state.</Text>
        <StarPicker defaultValue={2} />
      </Block>

      <Block gap="xs">
        <Text size="sm" c="muted">A value prop — the parent owns the rating, so it can drive it too.</Text>
        <StarPicker value={rating} onChange={setRating} />
        <Row gap="sm" wrap="wrap">
          <Button size="sm" variant="outline" onPress={() => setRating(5)}>Set 5 from the parent</Button>
          <Button size="sm" variant="ghost" onPress={() => setRating(0)}>Clear</Button>
        </Row>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useDebouncedCallback.md -->

# useDebouncedCallback

Wrap an imperative function in a stable debounced callback that exposes `cancel` and `flush`.

## Metadata

- Import: `import { useDebouncedCallback } from '@plocks/ui';`
- Tags: debounce, callback, performance
- Docs: https://plocks.dev/hooks/useDebouncedCallback
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useDebouncedCallback/useDebouncedCallback.ts

## Definition

```ts
export interface UseDebouncedCallbackReturn<F extends AnyFunction> {
  /** Call to schedule the wrapped function. Identity is stable across renders. */
  (...args: Parameters<F>): void;
  /** Cancel any pending invocation. */
  cancel: () => void;
  /** Run the wrapped function immediately with the most recent args. */
  flush: () => void;
}

export function useDebouncedCallback<F extends AnyFunction>(callback: F, wait: number): UseDebouncedCallbackReturn<F>;
```

## Examples

### Debounced typeahead

`useDebouncedCallback` debounces an *imperative* function. The returned wrapper has stable identity (safe for `useEffect` deps) and exposes `.cancel()` and `.flush()`. Use this when an event handler should fire a request after a quiet period — that's how `<AutoComplete>` does its search internally.

```tsx
import { useState } from 'react';
import { Block, Button, Input, Row, Text, useDebouncedCallback } from '@plocks/ui';

export function Demo() {
  const [query, setQuery] = useState('');
  const [calls, setCalls] = useState<string[]>([]);

  const search = useDebouncedCallback((next: string) => {
    setCalls((prev) => [...prev, next]);
  }, 300);

  return (
    <Block>
      <Input
        label="Search"
        placeholder="Type fast…"
        description="Invocations are debounced by 300ms."
        value={query}
        onChangeText={(next) => {
          setQuery(next);
          search(next);
        }}
      />
      <Row gap="sm" wrap="wrap">
        <Button variant="outline" onPress={() => search.cancel()}>Cancel pending</Button>
        <Button variant="ghost" onPress={() => search.flush()}>Flush now</Button>
        <Button variant="ghost" onPress={() => setCalls([])}>Reset log</Button>
      </Row>
      {calls.length ? (
        calls.map((call, index) => (
          <Text key={index} ff="monospace" size="sm">{`#${index + 1} → "${call}"`}</Text>
        ))
      ) : (
        <Text size="sm" c="muted">No invocations yet.</Text>
      )}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useDebouncedValue.md -->

# useDebouncedValue

Derive a debounced copy of a changing value so renders and effects react only once it settles.

## Metadata

- Import: `import { useDebouncedValue } from '@plocks/ui';`
- Tags: debounce, search, performance
- Docs: https://plocks.dev/hooks/useDebouncedValue
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useDebouncedValue/useDebouncedValue.ts

## Definition

```ts
export interface UseDebouncedValueOptions {
  /** Skip the initial debounce — first value is set immediately. Default: true. */
  leading?: boolean;
}

export function useDebouncedValue<T>(value: T, wait: number, options: UseDebouncedValueOptions = {}): [T, () => void];
```

## Examples

### Debounced search

`useDebouncedValue` is the declarative pattern: derive a debounced copy of state and read from it during render (or from a `useEffect` when a real side-effect is involved). Best when the consumer is React-driven. For imperative event handlers, use `useDebouncedCallback`.

```tsx
import { useMemo, useState } from 'react';
import { Badge, Block, DataList, Input, Row, Text, useDebouncedValue } from '@plocks/ui';

const PACKAGES = ['react', 'react native', 'redux', 'rxjs', 'remix', 'rollup'];

export function Demo() {
  const [query, setQuery] = useState('');
  const [debouncedQuery] = useDebouncedValue(query, 300);

  // Derived from the debounced value, so filtering skips intermediate keystrokes.
  const hits = useMemo(
    () => (debouncedQuery ? PACKAGES.filter((name) => name.includes(debouncedQuery.toLowerCase())) : []),
    [debouncedQuery]
  );

  return (
    <Block>
      <Input
        label="Search packages"
        placeholder="Type to filter…"
        value={query}
        onChangeText={setQuery}
      />
      <DataList
        labelWidth={150}
        data={[
          { label: 'Live', value: query || '—' },
          { label: 'Debounced (300ms)', value: debouncedQuery || '—' }
        ]}
      />
      {hits.length ? (
        <Row gap="xs" wrap="wrap">
          {hits.map((hit) => (
            <Badge key={hit} variant="light">{hit}</Badge>
          ))}
        </Row>
      ) : (
        <Text size="sm" c="muted">No matches.</Text>
      )}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useDeviceInfo.md -->

# useDeviceInfo

Gather a complete snapshot of runtime details, OS metadata, safe area insets, screen metrics, locale, input capabilities, and helper booleans.

All instances share one set of platform listeners, and the hook is hydration-safe: server rendering and the hydration pass see deterministic defaults (`meta.ready` is `false`), then the live values arrive. `appearance.reducedMotion` is the same value `useReducedMotion()` returns.

## Metadata

- Import: `import { useDeviceInfo } from '@plocks/ui';`
- Status: beta
- Tags: device, responsive, platform
- Docs: https://plocks.dev/hooks/useDeviceInfo
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useDeviceInfo/useDeviceInfo.ts

## Definition

```ts
export function useDeviceInfo(options: UseDeviceInfoOptions = {}): DeviceInfo;
```

## Examples

### Device overview dashboard

Visualize OS, runtime, locale, and accessibility signals returned by useDeviceInfo.

```tsx
import { Block, DataList, Text, useDeviceInfo } from '@plocks/ui';

export function Demo() {
  const { runtime, system, screen, appearance, locale, input, safeArea, helpers, network, meta } =
    useDeviceInfo({ enableExtendedData: true });

  return (
    <Block gap="lg">
      <Block gap="xs">
        <Text size="sm" fw="semibold">Platform & runtime</Text>
        <DataList labelWidth={150} withDivider>
          <DataList.Item
            label="Operating system"
            value={`${system.os.name ?? 'Unknown'} ${system.os.version ?? ''}`.trim()}
          />
          <DataList.Item
            label="Device"
            value={[system.device.type, system.device.brand, system.device.model].filter(Boolean).join(' • ')}
          />
          <DataList.Item
            label="Runtime"
            value={runtime.browserName
              ? `${runtime.browserName} ${runtime.browserVersion ?? ''}`.trim()
              : runtime.jsEngine ?? 'Native'}
          />
        </DataList>
      </Block>

      <Block gap="xs">
        <Text size="sm" fw="semibold">Screen & appearance</Text>
        <DataList labelWidth={150} withDivider>
          <DataList.Item
            label="Resolution"
            value={`${Math.round(screen.width)} × ${Math.round(screen.height)} @${screen.scale}x`}
          />
          <DataList.Item label="Orientation" value={screen.orientation} />
          <DataList.Item
            label="Safe area"
            value={`${safeArea.top} / ${safeArea.right} / ${safeArea.bottom} / ${safeArea.left}`}
          />
          <DataList.Item label="Color scheme" value={`${appearance.colorScheme} • contrast ${appearance.contrast}`} />
          <DataList.Item label="Reduced motion" value={appearance.reducedMotion ? 'Enabled' : 'Disabled'} />
        </DataList>
      </Block>

      <Block gap="xs">
        <Text size="sm" fw="semibold">Locale & input</Text>
        <DataList labelWidth={150} withDivider>
          <DataList.Item label="Locale" value={`${locale.language}-${locale.region ?? '??'}`.toUpperCase()} />
          <DataList.Item
            label="Time zone"
            value={`${locale.timeZone} • ${locale.uses24HourClock ? '24h' : '12h'} clock`}
          />
          <DataList.Item label="Pointers" value={input.pointerTypes.join(', ') || 'None'} />
          <DataList.Item
            label="Form factor"
            value={helpers.isMobile ? 'Mobile / touch-first' : helpers.isDesktop ? 'Desktop' : 'Unknown'}
          />
          <DataList.Item
            label="Network"
            value={network?.downlink
              ? `${network.connectionType} • ${network.downlink.toFixed(1)} Mbps`
              : network?.connectionType ?? (meta.ready ? 'Unavailable' : 'Loading…')}
          />
        </DataList>
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useDirection.md -->

# useDirection

Read the text direction (`dir`, `isRTL`) and switch it with `setDirection` or `toggleDirection`, for logic that has to know which way the layout runs. `PlocksProvider` mounts a `DirectionProvider` unless given `direction={false}`; outside one, the hook returns LTR with no-op setters instead of throwing.

## Metadata

- Import: `import { useDirection } from '@plocks/ui';`
- Tags: rtl, direction, layout, i18n
- Docs: https://plocks.dev/hooks/useDirection
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/providers/DirectionProvider.tsx

## Definition

```ts
export interface DirectionContextValue {
  /** Current text direction */
  dir: Direction;
  /** Whether current direction is RTL */
  isRTL: boolean;
  /** Set the text direction */
  setDirection: (direction: Direction) => void;
  /** Toggle between LTR and RTL */
  toggleDirection: () => void;
}

export type Direction = 'ltr' | 'rtl';

export function useDirection(): DirectionContextValue;
```

## Examples

### Toggle direction

`useDirection()` returns `{ dir, isRTL, setDirection, toggleDirection }`. Toggling here flips the whole docs site: on web the provider writes `dir` to `<html>`, while on native it calls `I18nManager.forceRTL`, which takes effect after an app reload. `DirectionProvider` accepts `initialDirection` (otherwise read from `<html dir>` or `I18nManager.isRTL`) plus an async `storage` controller and `storageKey` to persist the choice. Icons and layout props such as `start` / `end` already mirror on their own, so reach for `isRTL` only in logic like gesture math or value direction.

```tsx
import { Block, Button, DataList, useDirection } from '@plocks/ui';

export function Demo() {
  const { dir, isRTL, toggleDirection } = useDirection();

  return (
    <Block align="flex-start" maw={320}>
      <DataList
        labelWidth={80}
        data={[
          { label: 'dir', value: dir },
          { label: 'isRTL', value: String(isRTL) },
        ]}
      />
      <Button onPress={toggleDirection}>Switch to {isRTL ? 'LTR' : 'RTL'}</Button>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useDisclosure.md -->

# useDisclosure

Manage boolean open/close state with `open`, `close`, and `toggle` handlers plus callbacks that fire only on real transitions.

## Metadata

- Import: `import { useDisclosure } from '@plocks/ui';`
- Tags: state, toggle, open-close, modal, dialog
- Docs: https://plocks.dev/hooks/useDisclosure
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useDisclosure/useDisclosure.ts

## Definition

```ts
export interface UseDisclosureCallbacks {
  /** Called when the state transitions from closed → open. */
  onOpen?: () => void;
  /** Called when the state transitions from open → closed. */
  onClose?: () => void;
}

export type UseDisclosureReturn = readonly [boolean, UseDisclosureHandlers];

export interface UseDisclosureHandlers {
  /** Set state to `true`. No-op if already open. */
  open: () => void;
  /** Set state to `false`. No-op if already closed. */
  close: () => void;
  /** Flip the state. */
  toggle: () => void;
}

export function useDisclosure(initialState: boolean = false, callbacks?: UseDisclosureCallbacks): UseDisclosureReturn;
```

## Examples

### Toggle a dialog

Boolean state with `open` / `close` / `toggle` handlers. Optional `onOpen` / `onClose` callbacks fire only on real transitions, never on no-op calls.

```tsx
import { Badge, Block, Button, Dialog, Row, Text, useDisclosure } from '@plocks/ui';

export function Demo() {
  const [opened, { open, close, toggle }] = useDisclosure(false, {
    onOpen: () => console.log('opened'),
    onClose: () => console.log('closed'),
  });

  return (
    <Block align="flex-start">
      <Badge c={opened ? 'success' : 'gray'}>{opened ? 'Open' : 'Closed'}</Badge>

      <Row gap="sm" wrap="wrap">
        <Button onPress={open}>open</Button>
        <Button variant="outline" onPress={close}>close</Button>
        <Button variant="ghost" onPress={toggle}>toggle</Button>
      </Row>

      <Dialog opened={opened} title="Dialog title" onClose={close}>
        <Block p="md">
          <Text>This dialog's open state is managed by useDisclosure.</Text>
          <Button onPress={close}>Close</Button>
        </Block>
      </Dialog>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useDragGesture.md -->

# useDragGesture

The drag gesture behind Slider, RangeSlider, Joystick and Rating: spread its handlers, ref and style onto a View to get pointer samples in that View's own coordinates, which keep tracking after the finger leaves it, without the page or a ScrollView stealing the drag. `getGestureSurfaceStyle` and `GESTURE_RESPONDER_LOCK` are the two pieces it's built on, for a `PanResponder` of your own.

## Metadata

- Import: `import { useDragGesture } from '@plocks/ui';`
- Tags: gesture, drag, pan, touch, scroll
- Docs: https://plocks.dev/hooks/useDragGesture
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/gestures/useDragGesture.ts

## Definition

```ts
export interface UseDragGestureOptions {
  /** Turn the whole gesture off (disabled / read-only controls). Default true. */
  enabled?: boolean;
  /** Directions the surface consumes. Drives `touch-action` on web. Default `both`. */
  axis?: DragAxis;
  /**
   * Claim the gesture the moment the surface is touched, so a tap commits a
   * value and the drag is already ours before the browser or a parent
   * ScrollView can consider the touch a scroll. Default true.
   */
  claimOnStart?: boolean;
  /**
   * Travel (px) required before a *move* claims the gesture. Only consulted
   * when `claimOnStart` is false — controls that must let a tap fall through to
   * something else (a text field that also drag-scrubs) set this.
   */
  activationDistance?: number;
  /** Claim in the capture phase, outranking any child responders. Default false. */
  capture?: boolean;
  /** Hold the web page-scroll lock while dragging. Default true. */
  lockPageScroll?: boolean;
  /** Hold the web text-selection lock while dragging. Default true. */
  lockTextSelection?: boolean;
  /** Web cursor for the idle surface. */
  cursor?: string;
  /** Web cursor while a drag is in flight. Defaults to `cursor`. */
  activeCursor?: string;
  /** Fired once when the gesture is granted, with the press location. */
  onStart?: DragGestureCallback;
  /** Fired for every pointer sample while the gesture is held. */
  onMove?: DragGestureCallback;
  /** Fired once when the pointer is released. */
  onEnd?: DragGestureCallback;
  /** Fired instead of `onEnd` when the gesture is terminated (backgrounded, torn down). */
  onCancel?: () => void;
}

export interface UseDragGestureResult {
  /** Spread onto the View that owns the gesture. */
  panHandlers: GestureResponderHandlers;
  /** Web-only style props (`touch-action`, selection, cursor) for that same View. */
  surfaceStyle: ViewStyle;
  /** Attach to the same View — used to measure the surface's page origin. */
  ref: React.MutableRefObject<View | null>;
  /** Pass to the same View's `onLayout` (compose it if the caller needs its own). */
  onLayout: (event: LayoutChangeEvent) => void;
  /** True between grant and release/terminate. */
  isDragging: boolean;
  /** Latest known surface box, in page coordinates. */
  getSurfaceRect: () => { x: number; y: number; width: number; height: number };
}

export function useDragGesture(options: UseDragGestureOptions = {}): UseDragGestureResult;
```

## Examples

### Drag a knob

`useDragGesture(options)` returns `{ ref, onLayout, surfaceStyle, panHandlers, isDragging, getSurfaceRect }`; put the first four on the same View (composing `onLayout` when you need your own) and give its children `pointerEvents: 'none'` so every press lands on the surface. `onStart`, `onMove` and `onEnd` each receive a `DragPoint` with `x` / `y` relative to the surface, its `width` / `height` (0 until the first layout) and `dx` / `dy` / `distance` travelled since the press, while `onCancel` fires instead of `onEnd` when the gesture is taken away. `axis` sets web `touch-action`: `'x'` here leaves vertical page scrolling alone, `'both'` (the default) claims every direction, and on web a drag also holds page-scroll and text-selection locks until release, cancel or unmount. `claimOnStart: false` with an `activationDistance` lets a tap fall through to something else, and `enabled: false` turns the surface back into ordinary content.

```tsx
import { useState } from 'react';
import { Block, Text, useDragGesture } from '@plocks/ui';
import type { DragPoint } from '@plocks/ui';

const KNOB = 28;
// Children of the surface let the press through, so it always lands on the surface itself.
const PASS_THROUGH = { pointerEvents: 'none' } as const;

export function Demo() {
  const [ratio, setRatio] = useState(0.5);
  const [trackWidth, setTrackWidth] = useState(0);

  const follow = (point: DragPoint) => {
    const travel = point.width - KNOB;
    if (travel <= 0) return;
    setRatio(Math.min(1, Math.max(0, (point.x - KNOB / 2) / travel)));
  };

  const drag = useDragGesture({
    axis: 'x',
    cursor: 'grab',
    activeCursor: 'grabbing',
    onStart: follow,
    onMove: follow,
  });

  return (
    <Block fullWidth maw={360}>
      <Block
        ref={drag.ref}
        onLayout={(event) => {
          drag.onLayout(event);
          setTrackWidth(event.nativeEvent.layout.width);
        }}
        style={drag.surfaceStyle}
        {...drag.panHandlers}
        h={KNOB}
        justify="center"
      >
        <Block h={4} radius="full" bg="border" style={PASS_THROUGH} />
        <Block
          position="absolute"
          top={0}
          left={ratio * Math.max(0, trackWidth - KNOB)}
          w={KNOB}
          h={KNOB}
          radius="full"
          bg="primary.5"
          opacity={drag.isDragging ? 0.8 : 1}
          style={PASS_THROUGH}
        />
      </Block>

      <Text ta="center" ff="monospace">
        {Math.round(ratio * 100)}%
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useElementSize.md -->

# useElementSize

Track an element's rendered width and height through `onLayout`, on web and native, to size children or switch layouts by the space a component actually has rather than the window.

## Metadata

- Import: `import { useElementSize } from '@plocks/ui';`
- Tags: layout, size, measure, onLayout, resize
- Docs: https://plocks.dev/hooks/useElementSize
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useElementSize/useElementSize.ts

## Definition

```ts
export interface UseElementSizeReturn extends ElementSize {
  /** Pass to the measured element's `onLayout`. Stable for the component's lifetime. */
  onLayout: (event: LayoutChangeEvent) => void;
  /** `false` until the first layout event; `width` and `height` are 0 until then. */
  measured: boolean;
}

export interface ElementSize {
  width: number;
  height: number;
}

export function useElementSize(): UseElementSizeReturn;
```

## Examples

### Measure a container

Resize the window to watch the box's own size update. `useElementSize()` returns `{ width, height, measured, onLayout }`: pass `onLayout` to the element to measure. `measured` is `false` until the first layout event, while `width` and `height` are still 0.

On the web React Native Web backs `onLayout` with a ResizeObserver, so the size follows the element, not just the window. The returned object keeps its identity until the size changes. To also run your own `onLayout`, call both from one handler.

```tsx
import { Block, Text, useElementSize } from '@plocks/ui';

export function Demo() {
  const { width, height, onLayout } = useElementSize();

  return (
    <Block fullWidth onLayout={onLayout} bg="surface" p="xl" radius="md" align="center">
      <Text size="lg" fw="600">
        {Math.round(width)} × {Math.round(height)}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useEscapeKey.md -->

# useEscapeKey

Listen for user to press the Escape key to dismiss transient UI like modals, drawers, or menus.

## Metadata

- Import: `import { useEscapeKey } from '@plocks/ui';`
- Tags: keyboard, escape
- Docs: https://plocks.dev/hooks/useEscapeKey
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useEscapeKey/useEscapeKey.ts

## Definition

```ts
export function useEscapeKey(handler: () => void, enabled = true): void;
```

## Examples

### Dismiss panels

Wire the Escape key to close a panel and automatically disable the listener once the panel is dismissed.

```tsx
import { useState } from 'react';
import { Block, Button, Card, Text, useEscapeKey } from '@plocks/ui';

export function Demo() {
  const [open, setOpen] = useState(true);

  // The listener is only registered while the panel is visible.
  useEscapeKey(() => setOpen(false), open);

  return (
    <Block align="flex-start">
      {open ? (
        <Card p="md" maw={360}>
          <Block>
            <Text size="sm" fw="semibold">Escape-enabled panel</Text>
            <Text size="sm" c="muted">
              Press Escape to close this panel without touching the mouse.
            </Text>
            <Button size="sm" onPress={() => setOpen(false)}>Close</Button>
          </Block>
        </Card>
      ) : (
        <Button variant="outline" onPress={() => setOpen(true)}>Reopen panel</Button>
      )}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useFieldA11y.md -->

# useFieldA11y

Wire a custom form control to its label, description, error and helper text, using the same contract as every plocks field. On web it links them with ids and `aria-*` references; on native, where id references don't work, it composes the control's label and hint instead.

## Metadata

- Import: `import { useFieldA11y } from '@plocks/ui';`
- Tags: accessibility, form, label, aria
- Docs: https://plocks.dev/hooks/useFieldA11y
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/accessibility/useFieldA11y.ts

## Definition

```ts
export interface UseFieldA11yOptions {
  /** Base id. The control gets it verbatim; parts get `${id}-label` etc. Generated when omitted. */
  id?: string;
  label?: React.ReactNode;
  description?: React.ReactNode;
  /** Error message. A truthy non-boolean error is rendered and implies `invalid`. */
  error?: React.ReactNode;
  helperText?: React.ReactNode;
  required?: boolean;
  /** Defaults to `!!error`. */
  invalid?: boolean;
  disabled?: boolean;
  readOnly?: boolean;
  /** Explicit accessible name for the control; replaces the label reference. */
  accessibilityLabel?: string;
  /** Extra native hint appended after the composed description/error. */
  accessibilityHint?: string;
  /** Word appended to the native label for required fields. Default `'required'`. */
  requiredText?: string;
}

export interface UseFieldA11yResult {
  ids: FieldA11yIds;
  /** Spread on the focusable control (TextInput, Pressable, ...). */
  controlProps: A11yProps;
  /** Spread on the label text. */
  labelProps: FieldPartProps;
  /** Spread on the description text. */
  descriptionProps: FieldPartProps;
  /** Spread on the error container: role="alert" + aria-live="polite". */
  errorProps: FieldErrorProps;
  /** Spread on the helper text. */
  helperProps: FieldPartProps;
  invalid: boolean;
  /** Whether the footer should render the error (vs. helper text). */
  showError: boolean;
  /** Whether the footer should render helper text. */
  showHelper: boolean;
}

export interface FieldA11yIds {
  control: string;
  label: string;
  description: string;
  error: string;
  helper: string;
}

export interface FieldPartProps {
  id: string;
}

export interface FieldErrorProps extends FieldPartProps {
  role: 'alert';
  'aria-live': 'polite';
}

export function useFieldA11y(options: UseFieldA11yOptions): UseFieldA11yResult;
```

## Examples

### Custom text field

A plain `TextInput` wired like a plocks field. `useFieldA11y({ label, description, error, helperText, required, … })` returns `controlProps` for the control, `labelProps` / `descriptionProps` / `errorProps` / `helperProps` for the text around it, and `showError` / `showHelper`: the error replaces the helper text, and only the text that is rendered is referenced. Web gets `aria-labelledby`, `aria-describedby`, `aria-invalid` and `aria-required`; native gets a composed label ("Username, required") and a hint built from the error, description and helper text. `errorProps` makes the error a polite `role="alert"`, but iOS has no live regions, so call `announce()` for a new error when it must be spoken there.

```tsx
import { useState } from 'react';
import { TextInput } from 'react-native';
import { Block, Text, useFieldA11y, useTheme } from '@plocks/ui';

const LABEL = 'Username';
const HELPER = 'Lowercase letters and numbers, 3–16 characters.';

export function Demo() {
  const theme = useTheme();
  const [value, setValue] = useState('');
  const error = /[^a-z0-9]/.test(value) ? 'Only lowercase letters and numbers are allowed.' : undefined;

  const { controlProps, labelProps, errorProps, helperProps, invalid, showError, showHelper } = useFieldA11y({
    label: LABEL,
    helperText: HELPER,
    error,
    required: true,
  });

  return (
    <Block fullWidth maw={360} gap="xs">
      <Text {...labelProps} fw="600">
        {LABEL}
        <Text c="error" aria-hidden>
          {' *'}
        </Text>
      </Text>

      <TextInput
        {...controlProps}
        value={value}
        onChangeText={setValue}
        autoCapitalize="none"
        autoCorrect={false}
        style={{
          borderWidth: 1,
          borderColor: invalid ? theme.colors.error[5] : theme.backgrounds.borderStrong,
          borderRadius: 8,
          paddingHorizontal: 12,
          paddingVertical: 8,
          fontSize: 14,
          fontFamily: theme.fontFamily,
          color: theme.text.primary,
        }}
      />

      {showError ? (
        <Block {...errorProps} accessible>
          <Text size="sm" c="error">
            {error}
          </Text>
        </Block>
      ) : showHelper ? (
        <Text {...helperProps} size="sm" c="muted">
          {HELPER}
        </Text>
      ) : null}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useFloating.md -->

# useFloating

Anchor a floating element such as a popover, menu or tooltip to a trigger: it places it with flip and shift, renders it through the app's overlay host, registers it in the layer stack for Escape, back, outside press and focus, and returns the ARIA props for both ends. Popover, Menu, Tooltip, HoverCard and Select are built on it.

## Metadata

- Import: `import { useFloating } from '@plocks/ui';`
- Tags: overlay, popover, positioning, floating, aria
- Docs: https://plocks.dev/hooks/useFloating
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/overlay/useFloating.ts

## Definition

```ts
export interface UseFloatingOptions {
  /** Whether the floating element is open. */
  opened: boolean;
  /** Escape / Android back / outside press (or an external close) asked it to close. */
  onDismiss?: (reason: FloatingDismissReason) => void;
  /**
   * Placement relative to the anchor, written for LTR: in RTL `left`/`right`
   * and the `-start`/`-end` alignment of `top`/`bottom` are mirrored.
   * @default 'bottom'
   */
  placement?: PlacementType;
  /** Gap between anchor and floating element, px. @default 8 */
  offset?: number;
  /** Flip to the opposite side when it doesn't fit. @default true */
  flip?: boolean;
  /** Shift along the anchor to stay in the viewport. @default true */
  shift?: boolean;
  /** Match the anchor's width. @default false */
  matchWidth?: boolean;
  /**
   * 'fixed' (default): web `position: fixed`; native plain view in the nearest
   * overlay renderer. 'absolute': web `position: absolute`. 'portal': native
   * RN Modal at the app root (inside an OverlayHost it is a plain view).
   */
  strategy?: 'fixed' | 'absolute' | 'portal';
  /** What opens it. Hover/focus-triggered elements don't take focus or close on outside press. @default 'click' */
  trigger?: FloatingTrigger;
  /** Modal: traps focus, blocks layers below from Escape/back/outside press. @default false */
  modal?: boolean;
  /** Role of the floating element. `null` for none. @default 'dialog' */
  role?: string | null;
  /** The trigger's `aria-haspopup`. @default derived from `role` ('menu', 'listbox', 'tree', 'grid', else 'dialog') */
  popupType?: FloatingPopupType;
  /** Emit role/aria-* props at all. @default true */
  withRoles?: boolean;
  /** id of the floating element (the trigger's `aria-controls` target). @default generated */
  id?: string;
  /** Theme z-index layer. @default 'popover' */
  layer?: FloatingLayer;
  /** Explicit z-index (overrides `layer`). */
  zIndex?: number;
  /** @default true */
  closeOnEscape?: boolean;
  /** @default closeOnEscape */
  closeOnBack?: boolean;
  /** @default true, false for hover/focus triggers */
  closeOnOutsidePress?: boolean;
  /** Trap Tab inside the floating element (web). @default modal */
  trapFocus?: boolean;
  /** Move focus into the floating element on open. @default true for click/contextmenu/manual triggers */
  autoFocus?: boolean;
  /** @default 'first-tabbable' when trapping focus, otherwise 'container' */
  initialFocus?: 'first-tabbable' | 'container';
  initialFocusRef?: RefObject<unknown>;
  /** Return focus on close (when focus is still inside). @default true */
  restoreFocus?: boolean;
  /**
   * Where focus returns on close when `restoreFocus` is on — e.g. an input
   * that should get focus back instead of the anchor. @default the anchor (reference)
   */
  restoreFocusRef?: RefObject<unknown>;
  /** Minimum distance from the viewport edges, px. */
  boundary?: number;
  /** Placements to try when the preferred one doesn't fit (mirrored in RTL too). */
  fallbackPlacements?: PlacementType[];
  viewport?: PositioningOptions['viewport'];
  /** Avoid the on-screen keyboard. @default true */
  keyboardAvoidance?: boolean;
  /** Expected height before measuring, so the first frame picks the right side. */
  desiredHeight?: number;
  /** Reposition on scroll / resize / rotation. @default true */
  autoUpdate?: boolean;
  /** Layout direction override. @default DirectionProvider / platform */
  direction?: 'ltr' | 'rtl';
}

export interface UseFloatingReturn {
  opened: boolean;
  /** id carried by the floating element. */
  floatingId: string;
  /** Physical placement on screen (after RTL mirroring and flipping). */
  placement: PlacementType;
  position: PositionResult | null;
  /** True once the floating element has been measured and placed. */
  isPositioned: boolean;
  zIndex: number;
  /** False when rendering inline because no OverlayProvider is mounted. */
  hasOverlayProvider: boolean;
  refs: FloatingRefs;
  /**
   * Props for the trigger: `aria-haspopup` / `aria-expanded` / `aria-controls`
   * (web; native gets `aria-expanded`) and the reference ref. Pass
   * `{ ref: false }` to omit the ref when another element is the anchor.
   */
  getReferenceProps: (userProps?: AnyProps, options?: { ref?: boolean }) => AnyProps;
  /** Props for the floating element: `id`, `role`, `aria-modal`, ref, `onLayout`, `style`. */
  getFloatingProps: (userProps?: AnyProps) => AnyProps;
  /** Re-measure and reposition now. */
  update: () => Promise<void>;
  /**
   * Returns an element to render anywhere in the component: it opens `content`
   * in the nearest overlay host while open (rendering nothing itself), or
   * renders it inline next to the anchor when there is no OverlayProvider.
   */
  renderFloating: (content: ReactNode, options?: FloatingRenderOptions) => ReactElement | null;
}

export type FloatingLayer = 'dropdown' | 'popover' | 'tooltip';

export type FloatingPopupType = 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | boolean;

export type FloatingTrigger = 'click' | 'hover' | 'focus' | 'contextmenu' | 'manual';

export interface FloatingRefs {
  /**
   * The anchor (measured for positioning, exempt from outside press, focus
   * returns to it): a host view / DOM node, or a point anchor (`createPointAnchor`).
   */
  reference: MutableRefObject<unknown>;
  /** The floating element (measured for its size, focus container). */
  floating: MutableRefObject<unknown>;
  setReference: (node: unknown) => void;
  setFloating: (node: unknown) => void;
}

export function useFloating(options: UseFloatingOptions): UseFloatingReturn;
```

## Examples

### Anchored panel

Spread `getReferenceProps()` on the trigger and `getFloatingProps()` on the panel, then pass the panel to `renderFloating()`, which opens it in the nearest overlay host and renders nothing in place. `placement` (default `'bottom'`, written for LTR and mirrored in RTL) flips when the panel doesn't fit, and the returned `placement` is the side it actually landed on; `offset`, `matchWidth`, `modal`, `role` and `trigger` cover the rest, with `'hover'` / `'focus'` triggers neither taking focus nor closing on outside press. `onDismiss(reason)` fires for Escape, Android back, an outside press, or `'closed-externally'` when something else closed the overlay. Without an `OverlayProvider` (PlocksProvider mounts one) the panel renders inline next to the trigger, without flipping.

```tsx
import { useState } from 'react';
import { Block, Button, Text, useFloating } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  const floating = useFloating({
    opened,
    onDismiss: () => setOpened(false),
    placement: 'bottom-start',
  });

  return (
    <>
      <Button {...floating.getReferenceProps()} onPress={() => setOpened((current) => !current)}>
        {opened ? 'Close' : 'Open'}
      </Button>

      {floating.renderFloating(
        <Block {...floating.getFloatingProps()} p="md" radius="md" bg="elevated" shadow="md" maw={260}>
          <Text fw="600">Anchored panel</Text>
          <Text size="sm" ff="monospace">
            {floating.placement}
          </Text>
        </Block>
      )}
    </>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useGlobalHotkeys.md -->

# useGlobalHotkeys

Attach application-wide shortcuts that persist even when the originating component unmounts.

## Metadata

- Import: `import { useGlobalHotkeys } from '@plocks/ui';`
- Tags: keyboard, global, shortcuts
- Docs: https://plocks.dev/hooks/useGlobalHotkeys
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useHotkeys/index.ts

## Definition

```ts
export type HotkeyItem = [
  /** key combination like 'mod+k', 'escape', 'ctrl+j' */
  string,
  /** handler function */
  (event: KeyboardEvent) => void,
  /** optional modifiers override */
  KeyboardModifiers?,
  /** optional description */
  string[]?
];

export type KeyboardModifiers = {
  /** Whether the Alt key is pressed */
  alt?: boolean;
  /** Whether the Ctrl key is pressed */
  ctrl?: boolean;
  /** Whether the Meta (Cmd) key is pressed */
  meta?: boolean;
  /** Whether the Shift key is pressed */
  shift?: boolean;
}

export function useGlobalHotkeys(id: string, hotkey: HotkeyItem, enabled: boolean = true);
```

## Examples

### Global palette toggle

Keep a command palette hotkey alive across route changes by registering it with the global manager once.

```tsx
import { useCallback, useState } from 'react';
import { Alert, Block, Button, KeyCap, Row, useGlobalHotkeys } from '@plocks/ui';

const NAMESPACE = 'hooks-command-palette';

export function Demo() {
  const [open, setOpen] = useState(false);

  const togglePalette = useCallback(() => {
    setOpen(prev => !prev);
  }, []);

  useGlobalHotkeys(NAMESPACE, ['mod+k', togglePalette]);

  return (
    <Block align="flex-start">
      <Row gap="xs" align="center">
        <KeyCap keyCode="K" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <KeyCap keyCode="K" modifiers={['cmd']} size="sm">K</KeyCap>
      </Row>
      <Button onPress={togglePalette}>{open ? 'Close palette' : 'Open palette'}</Button>
      <Alert severity={open ? 'success' : 'info'} fullWidth>
        {open ? 'Palette is open globally. Press ⌘K again to close.' : 'Palette is currently closed.'}
      </Alert>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useHaptics.md -->

# useHaptics

Trigger platform-native vibration patterns with throttling and graceful fallbacks when haptics are unavailable.

## Metadata

- Import: `import { useHaptics } from '@plocks/ui';`
- Tags: haptics, feedback
- Docs: https://plocks.dev/hooks/useHaptics
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useHaptics/index.ts

## Definition

```ts
export interface UseHapticsOptions {
  /** Whether haptics are disabled */
  disabled?: boolean;
  /** Minimum ms between triggers to avoid flood. */
  throttleMs?: number;
}

export interface UseHapticsReturn {
  /** Medium impact when press starts */
  impactPressIn: () => void;
  /** Light impact on release */
  impactPressOut: () => void;
  /** Convenience for success events (e.g., toast show) */
  notifySuccess: () => void;
  /** Convenience for warning events */
  notifyWarning: () => void;
  /** Convenience for error events */
  notifyError: () => void;
  /** Haptic feedback for selection changes */
  selection: () => void;
}

export function useHaptics(opts: UseHapticsOptions = {}): UseHapticsReturn;
```

## Examples

### Feedback buttons

Map press, selection, and notification events to haptic helpers with built-in throttling.

```tsx
import { Block, Button, Row, Text, useHaptics } from '@plocks/ui';

export function Demo() {
  const { impactPressIn, impactPressOut, notifySuccess, notifyWarning, notifyError, selection } = useHaptics({ throttleMs: 80 });

  return (
    <Block align="flex-start">
      <Row gap="sm" wrap="wrap">
        <Button onPressIn={impactPressIn} onPressOut={impactPressOut}>Press feedback</Button>
        <Button variant="outline" onPress={selection}>Selection feedback</Button>
      </Row>
      <Text size="sm" fw="semibold">Notifications</Text>
      <Row gap="sm" wrap="wrap">
        <Button size="sm" color="success" onPress={notifySuccess}>Success</Button>
        <Button size="sm" color="warning" onPress={notifyWarning}>Warning</Button>
        <Button size="sm" color="error" onPress={notifyError}>Error</Button>
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useHapticsSettings.md -->

# useHapticsSettings

Read and flip the app-wide haptics switch that `useHaptics`, and every component built on it such as Button, Toast and Wheel, obeys: `enabled`, `setEnabled(on)` and `temporarilyDisable(ms)`. `PlocksProvider` mounts the `HapticsProvider` it reads from; `useOptionalHapticsSettings` returns undefined instead of throwing when there is none.

## Metadata

- Import: `import { useHapticsSettings } from '@plocks/ui';`
- Tags: haptics, settings, feedback, native
- Docs: https://plocks.dev/hooks/useHapticsSettings
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/haptics/HapticsProvider.tsx

## Definition

```ts
export interface HapticsContextValue {
  enabled: boolean;
  setEnabled: (v: boolean) => void;
  temporarilyDisable: (ms: number) => void;
}

export function useHapticsSettings(): HapticsContextValue;
```

## Examples

### Haptics switch

`useHaptics` fires the feedback and `useHapticsSettings` gates it: while `enabled` is false every `useHaptics` call is a no-op, including the press feedback built into Button, so one switch in a settings screen silences the whole library. `temporarilyDisable(ms)` turns haptics off for `ms`, then restores the previous setting, which suits a burst of programmatic changes that shouldn't buzz. Set the starting state with `<PlocksProvider haptics={{ defaultEnabled: false }}>`, or pass `haptics={false}` to leave the provider out. Haptics only play on iOS and Android with `expo-haptics` installed, so on web the switch changes nothing you can feel.

```tsx
import { Block, Button, Row, Switch, useHaptics, useHapticsSettings } from '@plocks/ui';

export function Demo() {
  const { enabled, setEnabled, temporarilyDisable } = useHapticsSettings();
  const { notifySuccess } = useHaptics();

  return (
    <Block align="flex-start">
      <Switch label="Haptics" checked={enabled} onChange={setEnabled} />

      <Row gap="sm" wrap="wrap">
        <Button onPress={notifySuccess}>Buzz</Button>
        <Button variant="outline" disabled={!enabled} onPress={() => temporarilyDisable(3000)}>
          Pause 3s
        </Button>
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useHotkeys.md -->

# useHotkeys

Register scoped keyboard shortcuts that only run while the component using them stays mounted.

## Metadata

- Import: `import { useHotkeys } from '@plocks/ui';`
- Tags: keyboard, shortcuts, scoped
- Docs: https://plocks.dev/hooks/useHotkeys
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useHotkeys/index.ts

## Definition

```ts
export type HotkeyItem = [
  /** key combination like 'mod+k', 'escape', 'ctrl+j' */
  string,
  /** handler function */
  (event: KeyboardEvent) => void,
  /** optional modifiers override */
  KeyboardModifiers?,
  /** optional description */
  string[]?
];

export type KeyboardModifiers = {
  /** Whether the Alt key is pressed */
  alt?: boolean;
  /** Whether the Ctrl key is pressed */
  ctrl?: boolean;
  /** Whether the Meta (Cmd) key is pressed */
  meta?: boolean;
  /** Whether the Shift key is pressed */
  shift?: boolean;
}

export function useHotkeys(hotkeys: HotkeyItem[]);
```

## Examples

### Scoped shortcuts

Register multiple keyboard combinations while a view is mounted to keep editor commands local to that surface.

```tsx
import { useCallback, useState } from 'react';
import { Block, KeyCap, Row, Text, useHotkeys } from '@plocks/ui';

export function Demo() {
  const [log, setLog] = useState<string[]>([]);

  const append = useCallback((entry: string) => {
    setLog(prev => [entry, ...prev].slice(0, 4));
  }, []);

  useHotkeys([
    ['mod+b', () => append('Bold toggled')],
    ['mod+shift+p', () => append('Command palette opened')],
    ['escape', () => append('Escape pressed')],
  ]);

  return (
    <Block align="flex-start">
      <Row gap="xs" wrap="wrap">
        <KeyCap keyCode="B" modifiers={['cmd']} size="sm">⌘B</KeyCap>
        <KeyCap keyCode="P" modifiers={['cmd', 'shift']} size="sm">⇧⌘P</KeyCap>
        <KeyCap keyCode="Escape" size="sm">Esc</KeyCap>
      </Row>
      {log.length ? (
        log.map((entry, index) => (
          <Text key={`${entry}-${index}`} size="sm">{entry}</Text>
        ))
      ) : (
        <Text size="sm" c="muted">No shortcuts fired yet.</Text>
      )}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useHover.md -->

# useHover

Track hover state and spread handlers that satisfy both React Native's hover props and the DOM's mouse events.

## Metadata

- Import: `import { useHover } from '@plocks/ui';`
- Tags: hover, pressable, web
- Docs: https://plocks.dev/hooks/useHover
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useHover/useHover.ts

## Definition

```ts
export type UseHoverReturn = readonly [boolean, UseHoverHandlers];

export interface UseHoverHandlers {
  /** Pointer entered the element. Wire to RN `onHoverIn` (Pressable). */
  onHoverIn: () => void;
  /** Pointer left the element. Wire to RN `onHoverOut` (Pressable). */
  onHoverOut: () => void;
  /**
   * Web-only alias for `onHoverIn`, for plain `View`s (react-native-web
   * forwards `onMouseEnter`; native ignores it).
   */
  onMouseEnter: (event?: WebMouseEvent) => void;
  /** Web-only alias for `onHoverOut`, for plain `View`s. */
  onMouseLeave: (event?: WebMouseEvent) => void;
}

export function useHover(): UseHoverReturn;
```

## Examples

### Hover state

`useHover` returns `[hovered, handlers]`. Handlers cover both RN's `onHoverIn` / `onHoverOut` and DOM's `onMouseEnter` / `onMouseLeave`, so they spread cleanly onto a `<Pressable>` or `<View>` regardless of platform. `<ListGroup.Item>` uses this hook for its hover background.

```tsx
import { Pressable } from 'react-native';
import { Block, Card, Text, useHover } from '@plocks/ui';

export function Demo() {
  const [hovered, hoverHandlers] = useHover();

  return (
    <Block align="flex-start">
      <Text size="sm" c="muted">
        Hover the card below (web only — touch devices show no hover state).
      </Text>
      <Pressable {...hoverHandlers}>
        <Card p="md" variant={hovered ? 'elevated' : 'outline'} bg={hovered ? 'primary' : undefined}>
          <Text fw={hovered ? '700' : '500'}>{hovered ? 'Hovered' : 'Hover me'}</Text>
        </Card>
      </Pressable>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useI18n.md -->

# useI18n

Translate keys with `t`, switch the active locale with `setLocale`, and format numbers, dates and relative times for that locale. Reads the nearest `I18nProvider`, which `PlocksProvider` mounts from its `locale` and `i18nResources` props; without one, `t` returns the key itself and formatting uses English.

## Metadata

- Import: `import { useI18n } from '@plocks/ui';`
- Tags: i18n, localization, translation, locale, formatting
- Docs: https://plocks.dev/hooks/useI18n
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/i18n/I18nContext.tsx

## Definition

```ts
export function useI18n(): I18nContextValue;
```

## Examples

### Translate and format

`useI18n()` returns `{ locale, setLocale, t, hasKey, formatNumber, formatDate, formatRelativeTime }`. `t(key, params)` resolves dot-separated keys in the active locale, then the fallback locale, then returns the key itself, and fills `{{name}}` placeholders from `params` (an entry can also be a function of `params`). The formatters use `Intl.NumberFormat`, `Intl.DateTimeFormat` and `Intl.RelativeTimeFormat` for the active locale and take their usual options. If the runtime lacks `Intl.RelativeTimeFormat`, relative time uses an English phrase with a locale-formatted number; install an `Intl.RelativeTimeFormat` polyfill for fully localized relative time on that runtime. The keys here come from the docs site's own resources, passed to `PlocksProvider` via `i18nResources`, so switching locale also switches the site.

```tsx
import { Block, DataList, SegmentedControl, useI18n } from '@plocks/ui';

const LOCALES = [
  { label: 'EN', value: 'en' },
  { label: 'FR', value: 'fr' },
  { label: 'ES', value: 'es' },
];

const RELEASE_DATE = new Date(2026, 0, 15);

export function Demo() {
  const { t, locale, setLocale, formatNumber, formatDate } = useI18n();

  return (
    <Block align="flex-start" fullWidth maw={420}>
      <SegmentedControl data={LOCALES} value={locale} onChange={setLocale} />
      <DataList
        labelWidth={130}
        data={[
          { label: 't()', value: t('localization.exampleGreeting', { name: 'Ada' }) },
          { label: 'formatNumber()', value: formatNumber(1234.5, { style: 'currency', currency: 'EUR' }) },
          {
            label: 'formatDate()',
            value: formatDate(RELEASE_DATE, { year: 'numeric', month: 'long', day: 'numeric' }),
          },
        ]}
      />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useKeyboardHeight.md -->

# useKeyboardHeight

The height of the on-screen keyboard currently covering the app, or 0 when it's hidden, for keeping footers, floating buttons and sheets above the keyboard on native and mobile browsers.

## Metadata

- Import: `import { useKeyboardHeight } from '@plocks/ui';`
- Tags: keyboard, layout, inset, native, mobile
- Docs: https://plocks.dev/hooks/useKeyboardHeight
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useKeyboardHeight/useKeyboardHeight.ts

## Definition

```ts
export interface UseKeyboardHeightOptions {
  /** Set to `false` to stop tracking; the hook then returns 0. @default true */
  enabled?: boolean;
}

export function useKeyboardHeight(options: UseKeyboardHeightOptions = {}): number;
```

## Examples

### Read the keyboard height

Open this page on a phone and focus the input: the readout follows the keyboard. `useKeyboardHeight({ enabled? })` returns a number of pixels; use it as a `paddingBottom` or `bottom` offset. Desktop browsers always report 0.

On native it follows the keyboard show and hide events (iOS reports them before the keyboard animates), and inside a `KeyboardManagerProvider` it reads that provider's metrics instead of adding listeners. On the web it measures how much of the layout viewport the keyboard covers, using `visualViewport`. Every instance shares one set of listeners, and static rendering sees 0.

```tsx
import { Block, Input, Text, useKeyboardHeight } from '@plocks/ui';

export function Demo() {
  const keyboardHeight = useKeyboardHeight();

  return (
    <Block fullWidth gap="sm">
      <Input placeholder="Focus to open the keyboard" />
      <Text c="muted">Keyboard: {keyboardHeight}px</Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useKeyboardManager.md -->

# useKeyboardManager

Read the on-screen keyboard's visibility, height and animation timing from `KeyboardManagerProvider`, dismiss it, or hand focus to an input by id; for layout that only needs the height, `useKeyboardHeight` is simpler. `useKeyboardMetricsOptional` and `useKeyboardFocusOptional` return one half each, so a consumer re-renders only for what it reads, and like `useKeyboardManagerOptional` they return null instead of throwing without a provider.

## Metadata

- Import: `import { useKeyboardManager } from '@plocks/ui';`
- Tags: keyboard, on-screen-keyboard, focus, native
- Docs: https://plocks.dev/hooks/useKeyboardManager
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/providers/KeyboardManagerProvider.tsx

## Definition

```ts
export type KeyboardManagerContextValue = KeyboardMetrics & KeyboardFocusApi;

export interface KeyboardMetrics {
  /** Indicates if the on-screen keyboard is currently visible */
  isKeyboardVisible: boolean;
  /** Height of the keyboard in pixels when visible */
  keyboardHeight: number;
  /** Native end coordinates from the last keyboard event */
  keyboardEndCoordinates?: KeyboardEvent['endCoordinates'];
  /** Reported animation duration (ms) from the native keyboard event */
  keyboardAnimationDuration: number;
  /** Reported animation easing from the native keyboard event */
  keyboardAnimationEasing?: KeyboardEvent['easing'];
}

export interface KeyboardFocusApi {
  /** Latest focus target requested via `setFocusTarget`; null when none pending */
  pendingFocusTarget: string | null;
  /** Imperative helper for dismissing the keyboard */
  dismissKeyboard: () => void;
  /**
   * Sets an optional focus target that can be consumed by an input after the keyboard closes.
   * Passing null clears the stored target.
   */
  setFocusTarget: (componentId: string | null) => void;
  /**
   * Returns true when the provided component id matches the stored focus target.
   * The focus target is cleared after a successful match.
   */
  consumeFocusTarget: (componentId: string) => boolean;
  /**
   * Helper that records a focus target so the next mounted input can restore focus.
   * Consumers can call `dismissKeyboard` separately when they need to drop the keyboard.
   */
  refocus: (componentId: string, options?: { dismiss?: boolean }) => void;
}

export function useKeyboardManager(): KeyboardManagerContextValue;
```

## Examples

### Keyboard readout

`useKeyboardManager()` returns `isKeyboardVisible`, `keyboardHeight`, `keyboardEndCoordinates` and `keyboardAnimationDuration` / `keyboardAnimationEasing`, plus `dismissKeyboard()` and a focus hand-off: `refocus(id)` marks a target, and the Input, PinInput or AutoComplete whose `keyboardFocusId` matches takes focus (Input and PinInput also match on `name` or `testID`). The metrics come from React Native's `Keyboard` events, so they only move on iOS and Android; on web they stay at hidden and 0. `PlocksProvider` doesn't mount a `KeyboardManagerProvider`, so add one near your app root yourself; `useKeyboardManager` throws without it.

```tsx
import { Badge, Block, Button, Input, Row, Text, useKeyboardManager } from '@plocks/ui';

export function Demo() {
  const { isKeyboardVisible, keyboardHeight, dismissKeyboard, refocus } = useKeyboardManager();

  return (
    <Block fullWidth maw={360}>
      <Input label="Message" keyboardFocusId="message" />

      <Row gap="sm" align="center">
        <Badge c={isKeyboardVisible ? 'success' : 'gray'}>
          {isKeyboardVisible ? 'Visible' : 'Hidden'}
        </Badge>
        <Text ff="monospace">{Math.round(keyboardHeight)}px</Text>
      </Row>

      <Row gap="sm">
        <Button onPress={() => refocus('message')}>Focus</Button>
        <Button variant="outline" onPress={dismissKeyboard}>
          Dismiss
        </Button>
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useLatestCallback.md -->

# useLatestCallback

Wrap a callback in a function whose identity never changes but always calls the latest version, so effects, timers and subscriptions that call it don't restart when an inline handler changes.

## Metadata

- Import: `import { useLatestCallback } from '@plocks/ui';`
- Tags: callbacks, effects, stable-identity
- Docs: https://plocks.dev/hooks/useLatestCallback
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/hooks/useLatestCallback.ts

## Definition

```ts
export function useLatestCallback<Args extends unknown[], R>(fn: ((...args: Args) => R) | undefined): (...args: Args) => R | undefined;
```

## Examples

### Stable handler, latest state

The interval is set up once, yet each tick adds the step selected right now: `tick` keeps one identity while always calling the latest closure. `useLatestCallback(fn)` returns `(...args) => ReturnType<fn> | undefined` and accepts `undefined` (the call is then a no-op), which suits optional callback props such as `onComplete`. The latest `fn` is stored in a layout effect after each commit, so call the returned function from effects and event handlers, never during render.

```tsx
import { useEffect, useState } from 'react';
import { Block, SegmentedControl, Text, useLatestCallback } from '@plocks/ui';

const STEPS = [
  { label: '+1', value: '1' },
  { label: '+5', value: '5' },
  { label: '+10', value: '10' },
];

export function Demo() {
  const [step, setStep] = useState('1');
  const [count, setCount] = useState(0);

  const tick = useLatestCallback(() => setCount((c) => c + Number(step)));

  // `tick` never changes identity, so the interval is created once.
  useEffect(() => {
    const id = setInterval(tick, 1000);
    return () => clearInterval(id);
  }, [tick]);

  return (
    <Block align="center">
      <Text size="xl" fw="700">
        {count}
      </Text>
      <SegmentedControl data={STEPS} value={step} onChange={setStep} />
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useLayer.md -->

# useLayer

Register a custom overlay in the app-wide layer stack (no provider needed), so Escape and Android back close only the topmost layer, a press inside a nested layer doesn't close its parent, and focus moves in on open, can be trapped, and returns on close. Wrap its content in `<LayerScope id={id}>` so layers opened from inside it stack above it, and use `useIsTopLayer(id)` to know whether it is currently on top.

## Metadata

- Import: `import { useLayer } from '@plocks/ui';`
- Tags: overlay, layer, dismiss, escape, focus
- Docs: https://plocks.dev/hooks/useLayer
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/overlay/useLayer.tsx

## Definition

```ts
export interface UseLayerOptions {
  /** Whether the layer is open. The layer registers on true and unregisters on false/unmount. */
  active: boolean;
  /** Called when Escape, hardware back, or an outside press asks the layer to close. */
  onDismiss?: (reason: LayerDismissReason) => void;
  /** Dismiss on Escape when this is the topmost layer (web). @default true */
  closeOnEscape?: boolean;
  /** Dismiss on Android hardware back when this is the topmost layer. @default closeOnEscape */
  closeOnBack?: boolean;
  /** Dismiss when a press lands outside the container (web). @default false */
  closeOnOutsidePress?: boolean;
  /**
   * Modal layers block the layers below them: Escape/back never reach past a
   * modal layer, outside presses never dismiss layers under it, and on native
   * the screen reader focus moves into it on open. @default false
   */
  modal?: boolean;
  /** Keep Tab / Shift+Tab focus cycling inside the container (web). @default modal */
  trapFocus?: boolean;
  /** Move focus into the layer when it activates. @default true */
  autoFocus?: boolean;
  /**
   * Where `autoFocus` puts focus when there is no `initialFocusRef`:
   * the first tabbable element, or the container itself (keyboard users then
   * Tab into the content, and no on-screen keyboard pops up for an input).
   * @default 'first-tabbable'
   */
  initialFocus?: 'first-tabbable' | 'container';
  /** Element to focus on activation (takes precedence over `initialFocus`). */
  initialFocusRef?: RefObject<unknown>;
  /**
   * Return focus when the layer closes — only if focus is still inside the
   * layer (or was lost with it), so closing by clicking elsewhere never steals
   * focus back. @default true
   */
  restoreFocus?: boolean;
  /** Where to return focus. @default the element focused when the layer opened */
  restoreFocusRef?: RefObject<unknown>;
  /** The layer's content node. Needed for focus management and outside-press detection. */
  containerRef?: RefObject<unknown>;
  /** Presses inside these don't count as outside (e.g. the trigger, which toggles itself). */
  outsidePressIgnoreRefs?: ReadonlyArray<RefObject<unknown>>;
  /** Parent layer id. @default the enclosing `LayerScope` */
  parentId?: string | null;
  /** Explicit id (otherwise generated). */
  id?: string;
}

export interface UseLayerResult {
  /** Stable id of this layer in the stack. Pass to `LayerScope` / `useIsTopLayer`. */
  id: string;
}

export function useLayer(options: UseLayerOptions): UseLayerResult;
```

## Examples

### Dismissable panel

`useLayer({ active, onDismiss, containerRef, … })` registers the panel while `active` is true and returns its `{ id }`. `onDismiss(reason)` receives `'escape-key'`, `'back-button'` or `'outside-press'`, and the panel stays open until you set `active` back to false; `closeOnOutsidePress` is off by default, and `outsidePressIgnoreRefs` stops a press on the trigger from counting as outside. Escape and outside press are web-only: on native, Android back dismisses the topmost layer, and a tap outside needs your own backdrop. `modal: true` walls off the layers below it and traps Tab, and focus moves into the panel on open and back on close (`autoFocus`, `restoreFocus`, both on by default).

```tsx
import { useRef, useState } from 'react';
import type { View } from 'react-native';
import { Badge, Block, Button, LayerScope, Text, useLayer } from '@plocks/ui';
import type { LayerDismissReason } from '@plocks/ui';

export function Demo() {
  const [opened, setOpened] = useState(false);
  const [reason, setReason] = useState<LayerDismissReason | null>(null);
  const triggerRef = useRef<View>(null);
  const panelRef = useRef<View>(null);

  const { id } = useLayer({
    active: opened,
    onDismiss: (why) => {
      setReason(why);
      setOpened(false);
    },
    closeOnOutsidePress: true,
    containerRef: panelRef,
    outsidePressIgnoreRefs: [triggerRef],
  });

  const toggle = () => {
    setReason(null);
    setOpened((current) => !current);
  };

  return (
    <Block align="flex-start">
      <Button ref={triggerRef} onPress={toggle}>
        {opened ? 'Close panel' : 'Open panel'}
      </Button>

      {opened ? (
        <LayerScope id={id}>
          <Block ref={panelRef} p="md" radius="md" bg="elevated" shadow="md" miw={220}>
            <Text fw="600">Panel</Text>
          </Block>
        </LayerScope>
      ) : null}

      {reason ? <Badge variant="light">{reason}</Badge> : null}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useListNavigation.md -->

# useListNavigation

Keyboard navigation for a combobox or listbox with virtual focus. Real focus stays in the input while `aria-activedescendant` follows the highlighted option.

## Metadata

- Import: `import { useListNavigation } from '@plocks/ui';`
- Tags: accessibility, keyboard, combobox, listbox
- Docs: https://plocks.dev/hooks/useListNavigation
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/accessibility/useListNavigation.ts

## Definition

```ts
export interface UseListNavigationOptions {
  /** Number of options. */
  count: number;
  /** Highlighted option (virtual focus); -1 for none. Controlled. */
  activeIndex: number;
  onActiveChange: (index: number) => void;
  /** Enter on the highlighted option. */
  onSelect?: (index: number) => void;
  /** Wrap past the ends. Default `true`. */
  loop?: boolean;
  /** DOM id of option `i` (referenced by `aria-activedescendant`). */
  getId: (index: number) => string;
  /** Options to skip. */
  isDisabled?: (index: number) => boolean;
  /** Whether the list is showing. Default `true`. Arrows open a closed list via `onOpen`. */
  opened?: boolean;
  onOpen?: () => void;
  /** Escape. */
  onClose?: () => void;
  /** Id of the listbox element (`aria-controls`). */
  listId?: string;
  /**
   * Home/End move the highlight. Default `false`: in an editable combobox they
   * move the text caret. Turn on for non-editable pickers (Select).
   */
  homeEndKeys?: boolean;
  /** Options moved by PageUp/PageDown. Default 10. */
  pageSize?: number;
}

export interface UseListNavigationResult {
  /** Spread on the input / trigger that keeps real focus (combobox). */
  inputProps: ListNavigationInputProps;
  /** Spread on the list container. */
  listProps: A11yProps;
  /** Spread on option `index`. */
  getOptionProps: (index: number) => ListNavigationOptionProps;
  /** The key handler, for inputs that route keys themselves. Returns true when handled. */
  handleKeyDown: (event: KeyboardEventLike) => boolean;
  /** Move virtual focus without a keyboard event. */
  moveNext: () => void;
  movePrevious: () => void;
  /** Select the active option, optionally using the first when none is active. */
  selectActive: (fallbackToFirst?: boolean) => void;
  /** Id of the highlighted option, if any. */
  activeId: string | undefined;
}

export type ListNavigationInputProps = A11yProps & {
  'aria-autocomplete'?: 'list' | 'none' | 'inline' | 'both';

export type ListNavigationOptionProps = A11yProps & { id: string };

export function useListNavigation(options: UseListNavigationOptions): UseListNavigationResult;
```

## Examples

### Filterable list

Type to filter. ↑/↓ move the highlight (skipping disabled options, and wrapping unless `loop: false`), PageUp/PageDown jump by `pageSize` (default 10), and Enter picks the highlighted option. You own the highlight: pass `activeIndex` / `onActiveChange`, `onSelect`, `getId(i)` and `listId`, then spread the returned `inputProps` (combobox role, `aria-expanded`, `aria-controls`, `aria-activedescendant`), `listProps` and `getOptionProps(i)`. react-native-web reports a `TextInput`'s keys through `onKeyPress`, so the demo moves `inputProps.onKeyDown` there; you can also call `handleKeyDown` yourself. For a popup list, pass `opened`, `onOpen` (↑/↓ open it) and `onClose` (Escape closes it), and set `homeEndKeys` for pickers that have no text caret.

```tsx
import { useState } from 'react';
import { Pressable, TextInput } from 'react-native';
import { Block, Text, useA11yId, useListNavigation, useTheme, webProps } from '@plocks/ui';

const FRUITS = ['Apple', 'Apricot', 'Banana', 'Blueberry', 'Cherry', 'Grape', 'Mango', 'Peach'];

// A pointer press on an option must not move focus out of the input.
const keepInputFocus = (event: { preventDefault(): void }) => event.preventDefault();

export function Demo() {
  const theme = useTheme();
  const listId = useA11yId(undefined, 'fruits');
  const [query, setQuery] = useState('');
  const [activeIndex, setActiveIndex] = useState(-1);

  const search = query.trim().toLowerCase();
  const options = FRUITS.filter((fruit) => fruit.toLowerCase().includes(search));

  const pick = (index: number) => {
    setQuery(options[index]);
    setActiveIndex(-1);
  };

  const nav = useListNavigation({
    count: options.length,
    activeIndex,
    onActiveChange: setActiveIndex,
    onSelect: pick,
    getId: (index) => `${listId}-option-${index}`,
    listId,
  });

  // react-native-web reports a TextInput's keys through onKeyPress, not onKeyDown.
  const { onKeyDown, ...comboboxProps } = nav.inputProps;

  return (
    <Block fullWidth maw={320} gap="xs">
      <TextInput
        {...comboboxProps}
        aria-label="Fruit"
        placeholder="Search fruit"
        placeholderTextColor={theme.text.muted}
        value={query}
        onChangeText={(text) => {
          setQuery(text);
          setActiveIndex(-1);
        }}
        onKeyPress={onKeyDown}
        autoCapitalize="none"
        autoCorrect={false}
        style={{
          borderWidth: 1,
          borderColor: theme.backgrounds.borderStrong,
          borderRadius: 8,
          paddingHorizontal: 12,
          paddingVertical: 8,
          fontSize: 14,
          fontFamily: theme.fontFamily,
          color: theme.text.primary,
        }}
      />

      <Block {...nav.listProps} gap={0}>
        {options.map((fruit, index) => (
          <Pressable
            key={fruit}
            {...nav.getOptionProps(index)}
            {...webProps({ tabIndex: -1, onMouseDown: keepInputFocus })}
            onPress={() => pick(index)}
            onHoverIn={() => setActiveIndex(index)}
          >
            <Block px="sm" py="xs" radius="sm" bg={index === activeIndex ? 'hover' : undefined}>
              <Text selectable={false}>{fruit}</Text>
            </Block>
          </Pressable>
        ))}
      </Block>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useMaskedInput.md -->

# useMaskedInput

Keep controlled inputs in sync with formatted masks while exposing the unmasked value and completion status.

## Metadata

- Import: `import { useMaskedInput } from '@plocks/ui';`
- Tags: forms, masking
- Docs: https://plocks.dev/hooks/useMaskedInput
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useMaskedInput/index.ts

## Definition

```ts
export interface UseMaskedInputOptions {
  /** The mask definition, or a mask built with `createMask`. Read once, on mount. */
  mask: MaskDefinition | Mask;
  /** Initial value */
  initialValue?: string;
  /** Callback when value changes */
  onValueChange?: (result: MaskResult) => void;
  /** Callback when unmasked value changes */
  onUnmaskedValueChange?: (unmaskedValue: string, result: MaskResult) => void;
}

export interface UseMaskedInputReturn {
  /** Current masked value for display */
  value: string;
  /** Current unmasked value */
  unmaskedValue: string;
  /** Whether the mask is complete */
  isComplete: boolean;
  /** Handle text input changes */
  handleChangeText: (text: string) => void;
  /** Handle selection change (for cursor positioning) */
  handleSelectionChange: (selection: { start: number; end: number }) => void;
  /** Current cursor position */
  cursorPosition: number;
  /** Reset to initial value */
  reset: () => void;
  /** Set value programmatically */
  setValue: (value: string) => void;
  /** Set unmasked value programmatically */
  setUnmaskedValue: (unmaskedValue: string) => void;
}

export function useMaskedInput(options: UseMaskedInputOptions): UseMaskedInputReturn;
```

## Examples

### Phone number mask

Apply a phone-number mask and show both masked and raw values while users type.

```tsx
import { Badge, Block, Input, Text, useMaskedInput } from '@plocks/ui';

export function Demo() {
  const { value, unmaskedValue, isComplete, handleChangeText, handleSelectionChange } = useMaskedInput({
    mask: { mask: '(000) 000-0000', placeholderChar: '_' }
  });

  return (
    <Block align="flex-start" maw={360} fullWidth>
      <Input
        label="Phone number"
        placeholder="(555) 555-1234"
        value={value}
        onChangeText={handleChangeText}
        textInputProps={{
          keyboardType: 'number-pad',
          onSelectionChange: event => handleSelectionChange(event.nativeEvent.selection)
        }}
      />
      <Badge variant="subtle" c={isComplete ? 'success' : 'gray'}>
        {isComplete ? 'Mask complete' : 'Enter all digits'}
      </Badge>
      <Text size="xs" c="muted">Raw value: {unmaskedValue || '—'}</Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useMediaQuery.md -->

# useMediaQuery

Evaluate a CSS media query on web and width/height queries on native, updating as the viewport changes.

## Metadata

- Import: `import { useMediaQuery } from '@plocks/ui';`
- Tags: media-query, responsive, dimensions
- Docs: https://plocks.dev/hooks/useMediaQuery
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useMediaQuery/useMediaQuery.ts

## Definition

```ts
export function useMediaQuery(query: string, initialValue: boolean = false): boolean;
```

## Examples

### Responsive layout

Web: subscribes to a CSS media query via `window.matchMedia`. Native: parses width/height queries (`(min-width: 640px)`, `(max-height: 480px)`) and watches `Dimensions.addEventListener('change')`. Unparseable queries on native return the supplied `initialValue`.

```tsx
import { Badge, Block, Row, Text, useMediaQuery } from '@plocks/ui';

export function Demo() {
  const isCompact = useMediaQuery('(max-width: 640px)');
  const isWide = useMediaQuery('(min-width: 1024px)');
  const columns = isCompact ? 1 : isWide ? 4 : 2;

  return (
    <Block>
      <Row gap="xs" wrap="wrap">
        <Badge variant={isCompact ? 'light' : 'outline'} c={isCompact ? 'success' : 'gray'}>
          Compact (≤640px)
        </Badge>
        <Badge variant={isWide ? 'light' : 'outline'} c={isWide ? 'success' : 'gray'}>
          Wide (≥1024px)
        </Badge>
      </Row>

      <Row gap="md" wrap="wrap">
        {Array.from({ length: columns }).map((_, i) => (
          <Block key={i} bg="primary" p="md" radius="md" miw={120}>
            <Text c="white">Card {i + 1}</Text>
          </Block>
        ))}
      </Row>

      <Text size="sm" c="muted">
        Resize the viewport (or rotate the device) to see the layout adapt.
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useMergedRef.md -->

# useMergedRef

Combine any number of object or callback refs into one stable callback ref, so a component can keep its own ref to a node and still honor the ref its parent forwarded.

## Metadata

- Import: `import { useMergedRef } from '@plocks/ui';`
- Tags: refs, forwardRef, composition
- Docs: https://plocks.dev/hooks/useMergedRef
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/utils/mergeRefs.ts

## Definition

```ts
export function useMergedRef<T>(...refs: Array<Ref<T> | undefined>);
```

## Examples

### Forward a ref and keep your own

`SearchField` keeps its own ref to the `TextInput` (it blurs itself when Enter is pressed) and forwards the parent's ref to the same node (the button focuses it). `useMergedRef(...refs)` accepts object refs, callback refs and `null` / `undefined` slots, and returns a callback ref whose identity only changes when one of the refs does, so React doesn't detach and re-attach the node on every render. Input, Checkbox, Radio, Tooltip and other library components use it to forward refs they also need internally.

```tsx
import { forwardRef, useRef } from 'react';
import type { TextInput } from 'react-native';
import { Block, Button, Input, useMergedRef } from '@plocks/ui';

const SearchField = forwardRef<TextInput, { placeholder?: string }>(function SearchField({ placeholder }, ref) {
  const ownRef = useRef<TextInput>(null);
  const mergedRef = useMergedRef(ownRef, ref);

  return <Input ref={mergedRef} placeholder={placeholder} onEnter={() => ownRef.current?.blur()} />;
});

export function Demo() {
  const searchRef = useRef<TextInput>(null);

  return (
    <Block align="flex-start" maw={360} fullWidth>
      <SearchField ref={searchRef} placeholder="Search" />
      <Button onPress={() => searchRef.current?.focus()}>Focus search</Button>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useOverlayApi.md -->

# useOverlayApi

Open, update and close overlays imperatively in the nearest `OverlayProvider` (`PlocksProvider` mounts one along with its renderer): `openOverlay(config)` returns an id for `updateOverlay` and `closeOverlay`, and `closeAllOverlays` clears them all. `useOverlays()` returns the configs currently open; both hooks throw outside a provider.

## Metadata

- Import: `import { useOverlayApi } from '@plocks/ui';`
- Tags: overlay, imperative, portal
- Docs: https://plocks.dev/hooks/useOverlayApi
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/providers/OverlayProvider.tsx

## Definition

```ts
export function useOverlayApi(): OverlayApiValue;
```

## Examples

### Open imperatively

`openOverlay` takes the `content` plus an `anchor`, the `{ x, y, width, height }` viewport point its top-left corner is placed at, and returns the overlay's id. The renderer doesn't measure or flip, so work the coordinates out yourself (here with `measureElement`) or use `useFloating`, which does it for you. By default the overlay closes on Escape and outside press (`closeOnEscape`, `closeOnClickOutside`), `anchorNode` keeps presses on the trigger from counting as outside, and `onClose` runs after every close; on native it opens in a transparent React Native `Modal` whose backdrop catches outside taps, and on web it is `position: fixed`. An overlay outlives the component that opened it, so close it on unmount.

```tsx
import { useRef, useState } from 'react';
import type { View } from 'react-native';
import { Block, Button, Text, measureElement, useOverlayApi } from '@plocks/ui';

export function Demo() {
  const { openOverlay, closeOverlay } = useOverlayApi();
  const triggerRef = useRef<View>(null);
  const [overlayId, setOverlayId] = useState<string | null>(null);

  const open = async () => {
    const rect = await measureElement(triggerRef);
    const id = openOverlay({
      anchor: { x: rect.x, y: rect.y + rect.height + 8, width: 0, height: 0 },
      anchorNode: triggerRef.current,
      content: (
        <Block p="md" radius="md" bg="elevated" shadow="md">
          <Text fw="600">Overlay</Text>
        </Block>
      ),
      onClose: () => setOverlayId(null),
    });
    setOverlayId(id);
  };

  return (
    <Button ref={triggerRef} onPress={() => (overlayId ? closeOverlay(overlayId) : open())}>
      {overlayId ? 'Close overlay' : 'Open overlay'}
    </Button>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useOverlayMode.md -->

# useOverlayMode

Return consistent booleans for deciding whether a component should render as a fullscreen modal or an anchored overlay/portal across web and native platforms.

## Metadata

- Import: `import { useOverlayMode } from '@plocks/ui';`
- Status: beta
- Tags: modal, overlay, responsive
- Docs: https://plocks.dev/hooks/useOverlayMode
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useOverlayMode/index.ts

## Definition

```ts
export interface UseOverlayModeOptions {
  /** Force modal presentation regardless of platform */
  forceModal?: boolean;
  /** Force anchored overlay/portal regardless of platform */
  forceOverlay?: boolean;
}

export interface UseOverlayModeResult {
  /** Raw device info reference (forwarded for convenience) */
  deviceInfo: DeviceInfo;
  /** True when running on React Native Web */
  isWeb: boolean;
  /** Consolidated mobile experience flag (native or narrow web) */
  isMobileExperience: boolean;
  /** Inverse of mobile experience flag */
  isDesktopExperience: boolean;
  /** Prefer fullscreen/modal surfaces (native + mobile web) */
  shouldUseModal: boolean;
  /** Prefer anchored overlays/portals (desktop web) */
  shouldUseOverlay: boolean;
}

export function useOverlayMode(options: UseOverlayModeOptions = {}): UseOverlayModeResult;
```

## Examples

### Overlay mode overview

The hook inspects platform + device heuristics and returns booleans you can plug into dialogs, popovers, or sheets. Resize the preview or switch platforms to see the recommendation change.

```tsx
import { Badge, Block, Row, Text, useOverlayMode } from '@plocks/ui';

export function Demo() {
  const { shouldUseModal, shouldUseOverlay, isMobileExperience, isDesktopExperience, isWeb } = useOverlayMode();

  const flags = [
    { label: 'Mobile experience', on: isMobileExperience },
    { label: 'Desktop experience', on: isDesktopExperience },
    { label: 'Web platform', on: isWeb },
    { label: 'Overlay available', on: shouldUseOverlay }
  ];

  return (
    <Block align="flex-start">
      <Badge size="lg" c={shouldUseModal ? 'primary' : 'success'}>
        {shouldUseModal ? 'Render a fullscreen modal' : 'Render an anchored overlay'}
      </Badge>
      <Row gap="xs" wrap="wrap">
        {flags.map(({ label, on }) => (
          <Badge key={label} variant={on ? 'light' : 'outline'} c={on ? 'primary' : 'gray'}>
            {label}
          </Badge>
        ))}
      </Row>
      <Text size="sm" c="muted">
        Resize the preview or switch platforms to see the recommendation change.
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/usePagination.md -->

# usePagination

Headless pagination: the current page, the page numbers to render with ellipses for the gaps, and handlers to move between pages. Build your own pager with it; `Pagination` is built on it.

## Metadata

- Import: `import { usePagination } from '@plocks/ui';`
- Tags: pagination, pager, navigation, headless
- Docs: https://plocks.dev/hooks/usePagination
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/usePagination/usePagination.ts

## Definition

```ts
export interface UsePaginationOptions {
  /** Total number of pages. */
  total: number;
  /** Current page (1-indexed). Controlled. */
  value?: number;
  /** Initial page when uncontrolled. @default 1 */
  defaultValue?: number;
  /** Called with the new page (1-indexed) whenever it changes. */
  onChange?: (page: number) => void;
  /** Pages shown on each side of the current page. @default 1 */
  siblings?: number;
  /** Pages always shown at the start and at the end. @default 1 */
  boundaries?: number;
}

export interface UsePaginationReturn {
  /** The current page, clamped to `1…total`. */
  page: number;
  /**
   * Pages to render, in order, with `'ellipsis'` for each gap. Always the same
   * length for a given `total`, `siblings` and `boundaries`, so the control
   * doesn't change width as the current page moves.
   */
  range: PaginationRangeItem[];
  /** Go to `page` (clamped to `1…total`). No-op when it's already current. */
  setPage: (page: number) => void;
  next: () => void;
  previous: () => void;
  first: () => void;
  last: () => void;
}

export type PaginationRangeItem = number | 'ellipsis';

export function usePagination(options: UsePaginationOptions): UsePaginationReturn;
```

## Examples

### Build a custom pager

`usePagination({ total, value?, defaultValue?, onChange?, siblings?, boundaries? })` returns `{ page, range, setPage, next, previous, first, last }`. `range` lists the page numbers to render, with `'ellipsis'` for each gap. It is always the same length for a given `total`, so the pager keeps its width as you page through.

`siblings` (default 1) sets how many pages show on each side of the current one, and `boundaries` (default 1) how many at each end. An ellipsis never stands in for a single page: that page is shown instead. Pass `value` + `onChange` to control the page. Out-of-range pages are clamped, and moves to the current page are ignored. The plain `getPaginationRange(page, total, siblings, boundaries)` function is exported too.

```tsx
import { Block, Button, IconButton, Row, Text, usePagination } from '@plocks/ui';

export function Demo() {
  const { page, range, setPage, next, previous } = usePagination({ total: 20, defaultValue: 7 });

  return (
    <Block fullWidth align="center">
      <Row gap="xs" align="center" wrap="wrap">
        <IconButton icon="chevron-left" variant="ghost" accessibilityLabel="Previous page" disabled={page === 1} onPress={previous} />
        {range.map((item, index) =>
          item === 'ellipsis' ? (
            <Text key={`gap-${index}`} c="muted">
              …
            </Text>
          ) : (
            <Button key={item} size="sm" variant={item === page ? 'filled' : 'ghost'} onPress={() => setPage(item)}>
              {item}
            </Button>
          )
        )}
        <IconButton icon="chevron-right" variant="ghost" accessibilityLabel="Next page" disabled={page === 20} onPress={next} />
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/usePersistedState.md -->

# usePersistedState

`useState` that survives reloads: the value is saved under a key in `localStorage` on the web (AsyncStorage on native when installed, or any storage you pass) and shared by every component using that key.

## Metadata

- Import: `import { usePersistedState } from '@plocks/ui';`
- Tags: state, storage, localStorage, persistence, AsyncStorage
- Docs: https://plocks.dev/hooks/usePersistedState
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/usePersistedState/usePersistedState.ts

## Definition

```ts
export interface UsePersistedStateOptions<T> {
  /**
   * Where to keep the value. Defaults to `localStorage` on the web and, on
   * native, `@react-native-async-storage/async-storage` when it is installed
   * (otherwise values live in memory until the app restarts). Pass a stable
   * object: one created during render is a new store every render.
   */
  storage?: PersistedStateStorage;
  /** Turns the value into the stored string. @default JSON.stringify */
  serialize?: (value: T) => string;
  /**
   * Turns the stored string back into a value. Throw to reject it (a stale
   * shape, a hand-edited entry); the default value is used instead.
   * @default JSON.parse
   */
  deserialize?: (raw: string) => T;
}

export type UsePersistedStateReturn<T> = readonly [
  T,
  Dispatch<SetStateAction<T>>,
  PersistedStateControls,
];

export interface PersistedStateStorage {
  getItem(key: string): string | null | undefined | Promise<string | null | undefined>;
  setItem(key: string, value: string): void | Promise<void>;
  removeItem(key: string): void | Promise<void>;
}

export interface PersistedStateControls {
  /** Deletes the stored value; the state falls back to the default value. */
  remove: () => void;
  /**
   * `false` until the stored value has been read: during static rendering and
   * hydration, and while an async storage (AsyncStorage) is loading. The state
   * shows the default value until then.
   */
  ready: boolean;
}

export function usePersistedState<T>(key: string, defaultValue: T, options: UsePersistedStateOptions<T> = {}): UsePersistedStateReturn<T>;
```

## Examples

### Remember a view setting

Pick a view, then reload the page: the choice is read back from `localStorage`. `usePersistedState(key, defaultValue, options?)` returns `[value, setValue, { remove, ready }]`. `setValue` takes a value or an updater like `useState`, and `remove()` deletes the stored value so the state falls back to the default.

Values are stored as JSON; pass `serialize` / `deserialize` to change that, and throw from `deserialize` to reject a stale or hand-edited value. `ready` is `false` during static rendering and hydration (the state shows the default so the markup matches) and while an async storage such as AsyncStorage is loading. Pass `storage` for anything else with `getItem` / `setItem` / `removeItem`, for example `sessionStorage` or an MMKV adapter.

```tsx
import { Block, Button, SegmentedControl, usePersistedState } from '@plocks/ui';

const VIEWS = [
  { label: 'Grid', value: 'grid' },
  { label: 'List', value: 'list' },
  { label: 'Table', value: 'table' },
];

export function Demo() {
  const [view, setView, { remove }] = usePersistedState('plocks-demo:view', 'grid');

  return (
    <Block align="center" gap="sm">
      <SegmentedControl data={VIEWS} value={view} onChange={setView} />
      <Button size="sm" variant="subtle" onPress={remove}>
        Reset
      </Button>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/usePopoverPositioning.md -->

# usePopoverPositioning

The measure-and-place engine under `useFloating`: attach `anchorRef` (and `popoverRef`) and it returns where the popover fits in the viewport — coordinates, the side it landed on after flipping, and the space available. `useTooltipPositioning` is a preset with tooltip defaults, and `useDropdownPositioning` adds `showOverlay` / `hideOverlay` to render the result through the overlay host; for most uses, reach for `useFloating` instead.

## Metadata

- Import: `import { usePopoverPositioning } from '@plocks/ui';`
- Tags: overlay, positioning, popover, tooltip, dropdown
- Docs: https://plocks.dev/hooks/usePopoverPositioning
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/hooks/usePopoverPositioning.ts

## Definition

```ts
export interface UsePopoverPositioningOptions extends PositioningOptions {
  /** Whether to automatically reposition on window resize */
  autoUpdate?: boolean;
  /** Debounce delay for resize/scroll updates in ms */
  updateDelay?: number;
  /** Adjust viewport height when on-screen keyboard is visible (default: true) */
  keyboardAvoidance?: boolean;
  /**
   * Layout direction the placement is written for. In `'rtl'` the `left`/`right`
   * sides and the `-start`/`-end` alignment of `top`/`bottom` placements are
   * mirrored, so `bottom-start` hugs the trigger's right edge. The returned
   * `position.placement` is always the physical side. Defaults to the
   * DirectionProvider's direction (or the platform's when there is none).
   */
  direction?: 'ltr' | 'rtl';
}

export interface UsePopoverPositioningReturn<TAnchor = View, TPopover = View> {
  /** Current position result */
  position: PositionResult | null;
  /** Update position manually. Pass `{ silent: true }` to skip the isPositioning flag. */
  updatePosition: (options?: { silent?: boolean }) => Promise<void>;
  /** Whether positioning is currently being calculated */
  isPositioning: boolean;
  /** Ref to attach to the anchor element */
  anchorRef: React.RefObject<TAnchor | null>;
  /** Ref to attach to the popover element for size measurement */
  popoverRef: React.RefObject<TPopover | null>;
}

export function usePopoverPositioning<TAnchor = View, TPopover = View>(isOpen: boolean, options: UsePopoverPositioningOptions = {}): UsePopoverPositioningReturn<TAnchor, TPopover>;
```

## Examples

### Position readout

`usePopoverPositioning(isOpen, options)` returns `{ position, anchorRef, popoverRef, updatePosition, isPositioning }`; while `isOpen` is true, `position` holds the popover's `x` / `y` in viewport coordinates, the physical `placement` (after RTL mirroring and flipping), `flipped` / `shifted` and `maxWidth` / `maxHeight`, and it is `null` while closed. Until `popoverRef` is on a rendered element the popover is assumed to be 200px wide with no height, and drawing it at those coordinates (`position: fixed` on web, a portal on native) is up to you, which is exactly what `useFloating` handles. It re-computes every frame while the page scrolls or resizes on web and after rotation on native, and with `keyboardAvoidance` (on by default) it keeps clear of the keyboard `KeyboardManagerProvider` reports. `useTooltipPositioning(isOpen, placement)` presets `flip`, `shift`, an 8px `offset` and `boundary`, while `useDropdownPositioning({ isOpen, onClose, …options })` also returns `showOverlay(content)` / `hideOverlay()` and closes the overlay when `isOpen` turns false.

```tsx
import { useState } from 'react';
import { Block, Button, Text, usePopoverPositioning } from '@plocks/ui';

export function Demo() {
  const [measuring, setMeasuring] = useState(false);
  const { anchorRef, position } = usePopoverPositioning(measuring, {
    placement: 'top',
    offset: 8,
  });

  return (
    <Block align="center">
      <Button ref={anchorRef} onPress={() => setMeasuring((current) => !current)}>
        {measuring ? 'Stop' : 'Measure'}
      </Button>

      {position ? (
        <Text size="sm" ff="monospace">
          {position.placement} · x {Math.round(position.x)} · y {Math.round(position.y)}
        </Text>
      ) : null}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useReducedMotion.md -->

# useReducedMotion

Whether animations should be reduced: the OS preference (`prefers-reduced-motion` on web, `AccessibilityInfo` on native), or the override set by the nearest `ReducedMotionProvider`. Works without a provider; when it returns `true`, jump to end states instead of animating.

## Metadata

- Import: `import { useReducedMotion } from '@plocks/ui';`
- Tags: motion, animation, accessibility, reduced-motion
- Docs: https://plocks.dev/hooks/useReducedMotion
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/motion/useReducedMotion.ts

## Definition

```ts
export function useReducedMotion(): boolean;
```

## Examples

### Respect reduced motion

`useReducedMotion()` returns a boolean: the square spins while it is `false` and snaps to its resting angle when it turns `true`. With the switch off the value follows your OS setting; switched on, it wraps the square in `<ReducedMotionProvider reducedMotion>`, the way an in-app preference would. The provider takes `true` / `false` to force the value for its subtree or `'system'` to follow the OS, and inherits its parent's setting when the prop is omitted; `PlocksProvider` mounts one from its own `reducedMotion` prop. Server rendering always reads `false`.

```tsx
import { useEffect, useState } from 'react';
import Animated, { Easing, cancelAnimation, useAnimatedStyle, useSharedValue, withRepeat, withTiming } from 'react-native-reanimated';
import { Block, ReducedMotionProvider, Row, Switch, Text, useReducedMotion } from '@plocks/ui';

function SpinningSquare() {
  const reduced = useReducedMotion();
  const rotation = useSharedValue(0);

  useEffect(() => {
    rotation.value = 0;
    if (!reduced) {
      rotation.value = withRepeat(withTiming(360, { duration: 1200, easing: Easing.linear }), -1);
    }
    return () => cancelAnimation(rotation);
  }, [reduced, rotation]);

  const spinStyle = useAnimatedStyle(() => ({ transform: [{ rotate: `${rotation.value}deg` }] }));

  return (
    <Row gap="md" align="center">
      <Animated.View style={spinStyle}>
        <Block w={40} h={40} radius="sm" bg="primary.5" />
      </Animated.View>
      <Text size="sm">useReducedMotion(): {String(reduced)}</Text>
    </Row>
  );
}

export function Demo() {
  const [reduce, setReduce] = useState(false);

  return (
    <Block align="flex-start">
      <Switch label="Reduce motion" checked={reduce} onChange={setReduce} />
      <ReducedMotionProvider reducedMotion={reduce ? true : 'system'}>
        <SpinningSquare />
      </ReducedMotionProvider>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useRovingFocus.md -->

# useRovingFocus

Give a composite widget (toolbar, tab list, radio group, grid) a single tab stop. Arrow keys, Home/End and optional typeahead move focus between its items.

## Metadata

- Import: `import { useRovingFocus } from '@plocks/ui';`
- Tags: accessibility, keyboard, focus
- Docs: https://plocks.dev/hooks/useRovingFocus
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/accessibility/useRovingFocus.ts

## Definition

```ts
export interface UseRovingFocusOptions {
  /** Number of items in the group. */
  count: number;
  /** Which arrow keys move. `'both'` + `columns` makes a grid. Default `'horizontal'`. */
  orientation?: RovingOrientation;
  /** Wrap from the last item to the first and back. Default `true` (grids never wrap vertically). */
  loop?: boolean;
  /** Controlled active (tab-stop) index. */
  activeIndex?: number;
  /** Initial active index when uncontrolled. Default `0`. */
  defaultActiveIndex?: number;
  /** Called with the new index when keyboard/focus moves the active item. */
  onActiveChange?: (index: number) => void;
  /** Text of item `i` for typeahead (type a letter to jump). Omit to disable typeahead. */
  typeahead?: (index: number) => string;
  /** Override reading direction. Default: `useDirection().isRTL`. */
  rtl?: boolean;
  /** Grid width for `orientation: 'both'` (Calendar: 7). Up/Down move by a row. */
  columns?: number;
  /** Items to skip (disabled tabs, options...). */
  isDisabled?: (index: number) => boolean;
  /** Move DOM focus to the new active item (web). Default `true`. */
  moveFocus?: boolean;
}

export interface UseRovingFocusResult {
  /** The current tab stop (first enabled item when the requested one is unusable). */
  activeIndex: number;
  /** Set the active index without moving focus. */
  setActiveIndex: (index: number) => void;
  /** Make `index` active and move focus to it (web). */
  focusItem: (index: number) => void;
  /** Props for item `index` (spread on a Pressable/View). */
  getItemProps: (index: number) => RovingItemProps;
  /** The key handler, for containers that route keys themselves. Returns true when handled. */
  handleKeyDown: (event: KeyboardEventLike, index: number) => boolean;
}

export type RovingOrientation = 'horizontal' | 'vertical' | 'both';

export interface RovingItemProps {
  /** 0 on the active item, -1 on the rest: one tab stop for the whole group. */
  tabIndex: 0 | -1;
  ref: (node: unknown) => void;
  onKeyDown: (event: KeyboardEventLike) => void;
  onFocus: () => void;
}

export function useRovingFocus(options: UseRovingFocusOptions): UseRovingFocusResult;
```

## Examples

### Toolbar with one tab stop

Tab reaches the toolbar once. ←/→ move between the buttons (wrapping at the ends, and swapped under RTL), Home/End jump to the first and last, and Tab leaves the group. `useRovingFocus({ count })` returns `getItemProps(i)` (`tabIndex`, `ref`, `onKeyDown`, `onFocus`) to spread on each item, plus `activeIndex`, `focusItem` and `handleKeyDown` for items that route keys themselves. Other options: `orientation` (`'vertical'`, or `'both'` with `columns` for a grid where ↑/↓ move by a row), `loop`, controlled `activeIndex` / `onActiveChange`, `isDisabled` to skip items, and `typeahead: (i) => label` to jump to an item by typing its first letters. Keys and DOM focus are web-only; on native the item props are inert apart from `tabIndex`.

```tsx
import { useState } from 'react';
import { Block, IconButton, a11yProps, useRovingFocus } from '@plocks/ui';

const TOOLS = [
  { icon: 'bold', label: 'Bold' },
  { icon: 'italic', label: 'Italic' },
  { icon: 'underline', label: 'Underline' },
  { icon: 'strikethrough', label: 'Strikethrough' },
  { icon: 'code', label: 'Code' },
];

export function Demo() {
  const [active, setActive] = useState<string[]>(['Bold']);
  const { getItemProps } = useRovingFocus({ count: TOOLS.length });

  const toggle = (label: string) =>
    setActive((current) =>
      current.includes(label) ? current.filter((item) => item !== label) : [...current, label]
    );

  return (
    <Block
      direction="row"
      gap="xs"
      p="xs"
      radius="md"
      bg="subtle"
      {...a11yProps({ role: 'toolbar', label: 'Text formatting', orientation: 'horizontal' })}
    >
      {TOOLS.map((tool, index) => {
        const on = active.includes(tool.label);
        return (
          <IconButton
            key={tool.label}
            icon={tool.icon}
            variant={on ? 'filled' : 'ghost'}
            accessibilityLabel={tool.label}
            onPress={() => toggle(tool.label)}
            {...getItemProps(index)}
            {...a11yProps({ pressed: on })}
          />
        );
      })}
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useScrollSpy.md -->

# useScrollSpy

Collect headings from the DOM or title registry and track which section is currently visible.

## Metadata

- Import: `import { useScrollSpy } from '@plocks/ui';`
- Tags: toc, navigation
- Docs: https://plocks.dev/hooks/useScrollSpy
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useScrollSpy/index.ts

## Definition

```ts
export interface ScrollSpyOptions {
  /** CSS selector for the headings to track */
  selector?: string;
  /** Margin around the root element */
  rootMargin?: string;
  /** Container to search for headings */
  container?: string | HTMLElement;
  /**
   * Function to get heading depth, defaults to h1=1, h2=2, etc. Accessors may
   * be inline functions: the latest one is used on the next collection, and a
   * new identity alone doesn't trigger one (call `reinitialize()` for that).
   */
  getDepth?: (el: Element) => number;
  /** Function to get text value from element, defaults to textContent */
  getValue?: (el: Element) => string;
  /** Function to get ID from element, defaults to element ID or generated from text */
  getId?: (el: Element) => string;
  /** Disable automatic active ID updates from scroll events */
  disableAutoUpdate?: boolean;
}

export interface TocItem {
  /** Unique identifier for the heading */
  id: string;
  /** Text content of the heading */
  value: string;
  /** Heading depth, e.g. 1 for h1, 2 for h2, etc. */
  depth: number;
  /** Function to get the underlying DOM node, if available (web only) */
  getNode?: () => HTMLElement | null;
}

export interface UseScrollSpyReturn {
  /** Collected heading items */
  items: TocItem[];
  /** Currently active heading ID, or null if none */
  activeId: string | null;
  /** Set the active ID programmatically */
  setActiveId: (id: string | null) => void;
  /** Re-collect headings and re-initialize the observer */
  reinitialize: () => void;
}

export function useScrollSpy(options?: ScrollSpyOptions, initialData: TocItem[] = []): UseScrollSpyReturn;
```

## Examples

### Table of contents

Use the title registry to power a live-updating table of contents that highlights the section currently in view.

```tsx
import { ScrollView, View } from 'react-native';
import { Badge, Block, Row, Text, TitleRegistryProvider, useScrollSpy, useTitleRegistration } from '@plocks/ui';

const SECTIONS = [
  { title: 'Overview', order: 1, copy: 'Introduce the feature and set expectations for what the rest of the document covers.' },
  { title: 'Installation', order: 2, copy: 'List required packages and platform caveats so teams can get started quickly.' },
  { title: 'Usage patterns', order: 3, copy: 'Highlight the most common ways to use the feature with short inline examples.' },
  { title: 'Troubleshooting', order: 4, copy: 'Capture the top issues support sees and the fix steps that usually resolve them.' }
] as const;

function Section({ title, order, copy }: { title: string; order: number; copy: string }) {
  const { elementRef, id } = useTitleRegistration({ text: title, order });

  return (
    <View ref={elementRef} nativeID={id}>
      <Text fw="semibold">{title}</Text>
      <Text size="sm" c="secondary">{copy}</Text>
    </View>
  );
}

function TocList() {
  const { items, activeId } = useScrollSpy();

  if (!items.length) {
    return <Text size="sm" c="muted">No headings detected yet.</Text>;
  }

  return (
    <Row gap="xs" wrap="wrap">
      {items.map(item => (
        <Badge
          key={item.id}
          variant={activeId === item.id ? 'light' : 'outline'}
          c={activeId === item.id ? 'primary' : 'gray'}
        >
          {item.value}
        </Badge>
      ))}
    </Row>
  );
}

export function Demo() {
  return (
    <TitleRegistryProvider>
      <Block gap="lg">
        <TocList />
        <ScrollView style={{ maxHeight: 280 }} contentContainerStyle={{ gap: 24 }}>
          {SECTIONS.map(section => (
            <Section key={section.title} {...section} />
          ))}
        </ScrollView>
      </Block>
    </TitleRegistryProvider>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useSpotlightToggle.md -->

# useSpotlightToggle

Provide a convenience wrapper for the global command palette shortcut so feature teams can open Spotlight without touching implementation details.

## Metadata

- Import: `import { useSpotlightToggle } from '@plocks/ui';`
- Tags: keyboard, spotlight
- Docs: https://plocks.dev/hooks/useSpotlightToggle
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useHotkeys/index.ts

## Definition

```ts
export function useSpotlightToggle(handler: () => void, enabled = true);
```

## Examples

### Spotlight toggle

Expose the shared Mod + K command palette shortcut without importing spotlight internals.

```tsx
import { useCallback, useState } from 'react';
import { Alert, Block, Button, KeyCap, Row, useSpotlightToggle } from '@plocks/ui';

export function Demo() {
  const [open, setOpen] = useState(false);

  const openSpotlight = useCallback(() => {
    setOpen(true);
  }, []);

  useSpotlightToggle(openSpotlight, true);

  return (
    <Block align="flex-start">
      <Row gap="xs" align="center">
        <KeyCap keyCode="K" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <KeyCap keyCode="K" modifiers={['cmd']} size="sm">K</KeyCap>
      </Row>
      <Row gap="sm" wrap="wrap">
        <Button onPress={openSpotlight}>Open Spotlight</Button>
        <Button variant="outline" onPress={() => setOpen(false)} disabled={!open}>Close Spotlight</Button>
      </Row>
      <Alert severity={open ? 'success' : 'info'} fullWidth>
        {open ? 'Spotlight is open. Press Mod + K or use the close button to dismiss.' : 'Spotlight is closed.'}
      </Alert>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useStyleProps.md -->

# useStyleProps

Turn the library's style props (`m`, `p`, `w`, `h`, `bg`, `opacity`, …) into a React Native style resolved against the current theme, so your own components can accept them like the built-in ones do.

## Metadata

- Import: `import { useStyleProps } from '@plocks/ui';`
- Tags: style-props, spacing, theming, custom-components
- Docs: https://plocks.dev/hooks/useStyleProps
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/utils/spacing.ts

## Definition

```ts
export function useStyleProps(props: StyleProps): ViewStyle;
```

## Examples

### Style props on your own component

`Tag` accepts every style prop by typing its props as `StyleProps`, splitting them off with `extractStyleProps(props)` (which returns `{ styleProps, otherProps }`) and resolving them with `useStyleProps(styleProps)`. Spacing tokens resolve through `theme.spacing`, `bg` accepts background tokens (`'surface'`, `'subtle'`), palette names (a subtle tint) or `'primary.5'` shade syntax, and `'full'` sizes become `'100%'`. Horizontal spacing uses logical start/end properties so it mirrors in right-to-left layouts, and edge props win over the shorthands covering them (`pt` over `py` over `p`). The result is memoized on the prop values; `resolveStyleProps(props, theme?)` is the non-hook version.

```tsx
import type { ReactNode } from 'react';
import { StyleSheet, View } from 'react-native';
import { Row, Text, extractStyleProps, useStyleProps } from '@plocks/ui';
import type { StyleProps } from '@plocks/ui';

type TagProps = StyleProps & { children: ReactNode };

function Tag(props: TagProps) {
  const { styleProps, otherProps } = extractStyleProps(props);
  const style = useStyleProps(styleProps);

  return (
    <View style={[styles.tag, style]}>
      <Text>{otherProps.children}</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  tag: { borderRadius: 8 },
});

export function Demo() {
  return (
    <Row gap="sm" align="center">
      <Tag p="xs" bg="primary">xs</Tag>
      <Tag p="md" bg="success">md</Tag>
      <Tag px="xl" py="sm" bg="warning">xl</Tag>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useTheme.md -->

# useTheme

Read the active `PlocksTheme` (color ramps, text and background roles, spacing, radii, font sizes) to style your own primitives; outside a provider it returns `DEFAULT_THEME`. Use `useThemeVisuals()` when a component reads only colors (`colors`, `text`, `backgrounds`, `states`, `colorScheme`, `primaryColor`), so layout-token changes don't re-render it. Use `useThemeLayout()` when it reads only layout tokens (`spacing`, `radii`, `fontSizes`, `shadows`, `breakpoints`, `controlSizes`, `zIndices`, fonts), so color changes don't re-render it.

## Metadata

- Import: `import { useTheme } from '@plocks/ui';`
- Tags: theme, tokens, colors, design-tokens
- Docs: https://plocks.dev/hooks/useTheme
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/theme/ThemeProvider.tsx

## Definition

```ts
export function useTheme(): PlocksTheme;
```

## Examples

### Read theme tokens

`useTheme()` returns the active `PlocksTheme`. The demo renders `theme.colors.primary`, a ten-shade ramp with the base color at index 5, and re-renders when the color scheme switches (dark ramps run darkest to lightest). `theme.text`, `theme.backgrounds` and `theme.surfaces` hold semantic colors; `theme.spacing`, `theme.radii` and `theme.fontSizes` hold CSS pixel strings such as `'16px'`, so convert them with `resolveSpacing` / `resolveRadius` / `resolveFontSize` before handing them to a React Native style. Prefer component props (`c`, `bg`, `p`, `radius`) where they exist.

```tsx
import { Block, Row, Text, readableTextOn, useTheme } from '@plocks/ui';

export function Demo() {
  const theme = useTheme();

  return (
    <Block fullWidth maw={560}>
      <Text size="sm" fw="600">
        colors.primary ({theme.colorScheme})
      </Text>
      <Row gap={4}>
        {theme.colors.primary.map((shade, index) => (
          <Block key={index} grow={1} h={48} radius="sm" bg={shade} align="center" justify="center">
            <Text size="xs" c={readableTextOn(shade)}>
              {index}
            </Text>
          </Block>
        ))}
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useThemedStyles.md -->

# useThemedStyles

Build a style table from the theme once per theme and dependency list instead of on every render. `createThemedStyles` is the module-level variant: a style factory cached per theme and argument list, for tables keyed by size, variant and the like.

## Metadata

- Import: `import { useThemedStyles } from '@plocks/ui';`
- Tags: theme, styles, stylesheet, performance, memoization
- Docs: https://plocks.dev/hooks/useThemedStyles
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/hooks/useThemedStyles.ts

## Definition

```ts
export function useThemedStyles<T>(factory: (theme: PlocksTheme) => T, deps: DependencyList = []): T;
```

## Examples

### Theme-aware styles

`useThemedStyles(factory, deps?)` calls `factory(theme)` and memoizes whatever it returns (a plain style object or a `StyleSheet.create` table) on the theme object plus `deps`, so the card's styles are rebuilt only when the color scheme switches or `compact` changes. List everything the factory closes over in `deps`; the factory itself is not a dependency, so an inline arrow is fine. For styles shared across instances, `createThemedStyles((theme, ...args) => styles)` returns a function cached per theme and per argument list; the extra arguments must be primitives.

```tsx
import { useState } from 'react';
import { Text, View } from 'react-native';
import { Block, Switch, resolveRadius, resolveSpacing, useThemedStyles } from '@plocks/ui';

export function Demo() {
  const [compact, setCompact] = useState(false);

  const styles = useThemedStyles(
    (theme) => ({
      card: {
        padding: resolveSpacing(theme, compact ? 'sm' : 'lg'),
        borderRadius: resolveRadius(theme, 'md'),
        borderWidth: 1,
        borderColor: theme.backgrounds.border,
        backgroundColor: theme.backgrounds.subtle,
      },
      title: { color: theme.text.primary, fontSize: 16 },
      meta: { color: theme.text.muted, fontSize: 13 },
    }),
    [compact]
  );

  return (
    <Block fullWidth maw={360}>
      <Switch label="Compact" checked={compact} onChange={setCompact} />
      <View style={styles.card}>
        <Text style={styles.title}>Weekly report</Text>
        <Text style={styles.meta}>Updated 2 hours ago</Text>
      </View>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useThemeMode.md -->

# useThemeMode

Read and change the user's color-scheme choice (`'light'`, `'dark'` or `'auto'`) along with the scheme it resolves to, for building a theme switcher. Available below a `PlocksProvider` given `themeModeConfig`, which persists the choice (to `localStorage` on web by default); it throws without one.

## Metadata

- Import: `import { useThemeMode } from '@plocks/ui';`
- Tags: theme, dark-mode, color-scheme, persistence
- Docs: https://plocks.dev/hooks/useThemeMode
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/theme/ThemeModeProvider.tsx

## Definition

```ts
export function useThemeMode(): ThemeModeContextValue;
```

## Examples

### Pick a color scheme

`useThemeMode()` returns `{ mode, setMode, cycleMode, actualColorScheme }`: `mode` is the stored choice, `actualColorScheme` the `'light'` / `'dark'` it resolves to (`'auto'` follows the OS), and `cycleMode` steps light → dark → auto. Picking a mode here switches the whole docs site. `themeModeConfig` takes `initialMode` (default `'auto'`), `persistence: { get, set }` (default: `localStorage` on web, none on native, so pass a synchronous store there) and `domConfig` for the class and attribute written to `<html>` on web.

```tsx
import { Block, SegmentedControl, Text, useThemeMode, type ColorSchemeMode } from '@plocks/ui';

const MODES: { label: string; value: ColorSchemeMode }[] = [
  { label: 'Light', value: 'light' },
  { label: 'Dark', value: 'dark' },
  { label: 'Auto', value: 'auto' },
];

export function Demo() {
  const { mode, setMode, actualColorScheme } = useThemeMode();

  return (
    <Block align="center">
      <SegmentedControl data={MODES} value={mode} onChange={(value) => setMode(value as ColorSchemeMode)} />
      <Text size="sm" c="muted">
        actualColorScheme: {actualColorScheme}
      </Text>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useTitleRegistration.md -->

# useTitleRegistration

Register headings with the shared title registry so sticky TOCs and scrollspy hooks stay in sync. To read the registry (`titles`, `registerTitle`, `unregisterTitle`, `clearTitles`) directly, call `useTitleRegistry()`, which throws outside a `TitleRegistryProvider`, or `useTitleRegistryOptional()`, which returns `null` there.

## Metadata

- Import: `import { useTitleRegistration } from '@plocks/ui';`
- Tags: toc, titles
- Docs: https://plocks.dev/hooks/useTitleRegistration
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useTitleRegistration/index.ts

## Definition

```ts
export interface UseTitleRegistrationOptions {
  /** Text content of the title */
  text: string;
  /** Heading level (1–6); titles appear in page order */
  order: number;
  /** Optional ID, if not provided it will be generated from text */
  id?: string;
  /** Whether to automatically register/unregister the title */
  autoRegister?: boolean;
}

export interface UseTitleRegistrationReturn<T = View> {
  /** Attach to the heading's host element (the table of contents scrolls to it on web). */
  elementRef: RefObject<T | null>;
  /** The registry id: `options.id`, or a slug of `text`. */
  id: string;
}

export function useTitleRegistration<T = View>(options: UseTitleRegistrationOptions): UseTitleRegistrationReturn<T>;
```

## Examples

### Register headings

Use the title registry provider to keep downstream navigation components aware of rendered headings.

```tsx
import { View } from 'react-native';
import { Block, DataList, Text, TitleRegistryProvider, useTitleRegistration, useTitleRegistry } from '@plocks/ui';

const SECTIONS = [
  { title: 'Why it matters', order: 1, description: 'Explain how the registry keeps navigation UI in sync with content.' },
  { title: 'When to use it', order: 2, description: 'Wrap large content layouts so scrollspy and tables of contents stay accurate.' },
  { title: 'Implementation tips', order: 3, description: 'Call the hook in section components and pass refs to headings that render in the DOM.' }
] as const;

function Section({ title, order, description }: { title: string; order: number; description: string }) {
  const { elementRef, id } = useTitleRegistration({ text: title, order });

  return (
    <View ref={elementRef} nativeID={id}>
      <Text fw="semibold">{title}</Text>
      <Text size="sm" c="secondary">{description}</Text>
    </View>
  );
}

function RegistryPreview() {
  const { titles } = useTitleRegistry();

  if (!titles.length) {
    return <Text size="sm" c="muted">No titles registered yet.</Text>;
  }

  return (
    <DataList
      labelWidth={180}
      data={titles.map(title => ({ label: title.text, value: `level ${title.order}` }))}
    />
  );
}

export function Demo() {
  return (
    <TitleRegistryProvider>
      <Block gap="lg">
        <Block gap="xs">
          <Text size="sm" fw="semibold">Registered titles</Text>
          <RegistryPreview />
        </Block>
        <Block gap="lg">
          {SECTIONS.map(section => (
            <Section key={section.title} {...section} />
          ))}
        </Block>
      </Block>
    </TitleRegistryProvider>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useToggleColorScheme.md -->

# useToggleColorScheme

Bind a keyboard shortcut to cycle through available color schemes provided by the theme mode context.

## Metadata

- Import: `import { useToggleColorScheme } from '@plocks/ui';`
- Tags: keyboard, theme
- Docs: https://plocks.dev/hooks/useToggleColorScheme
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/hooks/useHotkeys/index.ts

## Definition

```ts
export function useToggleColorScheme(handler: () => void, enabled = true);
```

## Examples

### Cycle theme

Wire the default Ctrl/⌘ + J shortcut to the same handler you use for manual theme toggles.

```tsx
import { Block, Button, DataList, KeyCap, Row, Text, useThemeMode, useToggleColorScheme } from '@plocks/ui';

export function Demo() {
  const { mode, cycleMode, actualColorScheme } = useThemeMode();

  useToggleColorScheme(cycleMode);

  return (
    <Block align="flex-start" maw={420}>
      <DataList
        labelWidth={130}
        data={[
          { label: 'Current mode', value: mode },
          { label: 'Active scheme', value: actualColorScheme }
        ]}
      />
      <Button onPress={cycleMode}>Toggle theme</Button>
      <Row gap="xs" align="center">
        <Text size="xs" c="muted">Or press</Text>
        <KeyCap keyCode="J" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <KeyCap keyCode="J" modifiers={['cmd']} size="sm">J</KeyCap>
        <Text size="xs" c="muted">anywhere in the docs.</Text>
      </Row>
    </Block>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useViewport.md -->

# useViewport

Read the current viewport `{ width, height, breakpoint }` from one shared, hydration-safe store, re-rendering on every resize. Reach for `useBreakpoint` instead when only the breakpoint matters.

## Metadata

- Import: `import { useViewport } from '@plocks/ui';`
- Tags: responsive, viewport, breakpoints, dimensions
- Docs: https://plocks.dev/hooks/useViewport
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/responsive/index.ts

## Definition

```ts
export interface ViewportState extends ViewportSize {
  breakpoint: Breakpoint;
}

export type Breakpoint = 'base' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';

export function useViewport(): ViewportState;
```

## Examples

### Live viewport size

`useViewport()` takes no arguments and returns `{ width, height, breakpoint }`: the window size in px (dp on native) and the breakpoint that width falls in, from `theme.breakpoints` or the nearest `BreakpointProvider` override. Every consumer shares one listener (a `resize` handler coalesced to one update per animation frame on web, `Dimensions` `change` on native) that attaches with the first subscriber and detaches with the last. Static rendering and the hydration pass see a desktop default (1200 × 800, `xl`), then the real size, so markup never mismatches. It re-renders on every size change; `useBreakpoint()` re-renders only when the breakpoint changes.

```tsx
import { Badge, Row, Text, useViewport } from '@plocks/ui';

export function Demo() {
  const { width, height, breakpoint } = useViewport();

  return (
    <Row gap="sm" align="center">
      <Text size="xl" fw="700">
        {Math.round(width)} × {Math.round(height)}
      </Text>
      <Badge size="lg">{breakpoint}</Badge>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/hooks/useVisibility.md -->

# useVisibility

Decide whether your own component should render from the visibility props every library component accepts: `hiddenFrom` and `visibleFrom` (breakpoints) and `lightHidden` and `darkHidden` (color scheme).

## Metadata

- Import: `import { useVisibility } from '@plocks/ui';`
- Tags: visibility, responsive, breakpoints, color-scheme, custom-components
- Docs: https://plocks.dev/hooks/useVisibility
- Source: https://github.com/platform-blocks/plocks/tree/main/packages/ui/src/core/factory/visibility.tsx

## Definition

```ts
export function useVisibility(props: VisibilityProps): boolean;
```

## Examples

### Show and hide by breakpoint

Two of the four tags render at any time: one per breakpoint rule, one per color scheme. `useVisibility(props)` returns `false` when `hiddenFrom="md"` and the viewport is `md` or wider, when `visibleFrom="md"` and it is narrower, or when `lightHidden` / `darkHidden` matches the current scheme; a hidden component should return `null` rather than hide with styles. Components built with `factory` (every library component) already handle these props, so the hook is for components you write yourself. It only subscribes to the viewport while `hiddenFrom` or `visibleFrom` is set, and static rendering assumes the `xl` breakpoint until hydration.

```tsx
import type { ReactNode } from 'react';
import { Badge, Row, useVisibility } from '@plocks/ui';
import type { VisibilityProps } from '@plocks/ui';

type TagProps = VisibilityProps & { children: ReactNode };

function Tag({ children, ...visibility }: TagProps) {
  const visible = useVisibility(visibility);
  if (!visible) return null;

  return <Badge size="lg">{children}</Badge>;
}

export function Demo() {
  return (
    <Row gap="sm">
      <Tag hiddenFrom="md">Below md</Tag>
      <Tag visibleFrom="md">md and up</Tag>
      <Tag darkHidden>Light scheme</Tag>
      <Tag lightHidden>Dark scheme</Tag>
    </Row>
  );
}
```

--------------------------------------------------------------------------------

# OPTIONAL

<!-- source: https://plocks.dev/llms/guides/contributing.md -->

# Contributing to plocks

How the repo is laid out, how to run it locally, and what it takes to land a component, a demo, or a docs page.

Docs: https://plocks.dev/contribute

plocks is developed in the open at [platform-blocks/plocks](https://github.com/platform-blocks/plocks). Issues and pull requests are welcome — this page is the short version of [CONTRIBUTING.md](https://github.com/platform-blocks/plocks/blob/main/CONTRIBUTING.md), which ships with the repo.

## Repo layout

- `packages/ui` — The core library published as `@plocks/ui` — 100+ components, hooks, and the theming system
- `packages/charts` — The charting package published as `@plocks/charts` — 24 chart types on that same theming
- `packages/{dates,code,media,carousel,spotlight}` — The packages built on `@plocks/ui`: date pickers, code and Markdown, audio and video, the carousel, and Spotlight
- `apps/docs` — This documentation site (Expo Router, statically rendered web)
- `scripts/` — Generators: demos, docs metadata, llms.txt, sitemap, exports map, release

## Set up the repo

plocks is one npm workspace. Install from the root — the workspaces are linked, so the docs site runs against your local packages rather than the published ones.

```bash
git clone https://github.com/platform-blocks/plocks.git
cd plocks
npm install
```

Start the docs site. It is the main development surface: every component demo renders there, against the source you are editing.

```bash
npm run dev
```

Press `w` for web, or open the project in Expo Go, an iOS simulator, or an Android emulator.

## Working on the UI package

Each component lives in `packages/<package>/src/components/<Name>/` — most in `packages/ui` — with a conventional shape: tests, docs metadata, and demos beside the source:

`packages/ui/src/components/Button`

```text
Button/
  Button.tsx  types.ts  index.ts
  __tests__/            # jest tests
  meta/component.md     # frontmatter: title, category, tags + prose
  demos/<slug>/         # index.tsx (default-export Demo) + description.md
```

Build, test, and lint the package from the repo root:

```bash
npm run ui:build     # rollup + type declarations
npm run ui:test      # jest (70% coverage threshold)
npm run ui:lint      # eslint
```

## Adding a component

A new component is five steps, and the last one writes most of the docs for you:

1. Create the directory following the shape above.
2. Export it from its package's `src/index.ts`.
3. In `packages/ui`, run `npm run ui:exports` to regenerate the per-component `exports` map in `package.json` — CI fails if it is stale.
4. Add a row to `apps/docs/config/coreComponents.ts`.
5. Run `npm run docs:all` — the docs route, nav entry, props table, demo code blocks, and llms.txt page are all generated.

## Adding a demo

Demos are the examples on a component page, and each one is a real component the site renders. Create `demos/<slug>/index.tsx` with a default-exported `Demo`, plus a `description.md` carrying `title`, `order`, and `tags` frontmatter, then regenerate:

```bash
npm run demos:all
```

The validator that runs afterwards fails on a missing description, a duplicate slug, or a demo that does not compile.

## Working on the docs site

Guide pages keep their copy in JSX-free modules under `apps/docs/config/` — `gettingStarted.ts`, `templates.ts`, `faq.ts`, and this page's `contribute.ts` — so `scripts/generate-llms.ts` can render the same source into `llms.txt` for language models. A new page touches four files:

- the route file under `app/`,
- a config module holding its copy,
- `config/navigationConfig.ts` for the sidebar entry,
- `config/routeSeo.ts` for the title and description — the prerender check fails without them.

Before opening a pull request that changes docs content, regenerate the derived files:

```bash
npm run docs:all
```

## Verifying a change

One command covers both packages — the exports map, the skills check, lint, and the test suites:

```bash
npm run verify:packages
```

## Starter templates & community

The starter templates are separate repositories, listed on the site from one config module.

- Templates live under the [platform-blocks GitHub org](https://github.com/platform-blocks) and are listed via `apps/docs/config/templates.ts`.
- Built a starter with your own stack? [Share it with us](https://github.com/platform-blocks/plocks/issues/new?template=community_template.yml) — accepted templates get listed on the [Getting Started](https://plocks.dev/getting-started) page.

## Releases

Maintainers run `npm run release`, which verifies every package (exports, lint, tests, build) and publishes them to npm together, at one version. Contributors never need to bump a version — say what the change is in the pull request and it lands in the next release.

Stuck on any of this? Open a [discussion](https://github.com/orgs/platform-blocks/discussions) or [issue](https://github.com/platform-blocks/plocks/issues) — a question that needed asking is usually a docs bug worth fixing.

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/faq/what-is.md -->

# What is plocks?

plocks is a React Native UI component library designed for building cross-platform applications with a consistent look and feel. It provides a set of customizable, accessible, and themeable components that work seamlessly on iOS, Android, and web platforms.

Docs: https://plocks.dev/faq

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/faq/expo-compatibility.md -->

# Is plocks compatible with Expo?

Yes! plocks is fully compatible with Expo and works out of the box. All components are designed to work in the Expo environment without requiring any native code modifications.

Docs: https://plocks.dev/faq

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/faq/does-support.md -->

# Does plocks support React Native Web?

Absolutely! plocks is built with React Native Web compatibility in mind. All components work seamlessly across iOS, Android, and web platforms.

Docs: https://plocks.dev/faq

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/faq/can-customize.md -->

# Can I customize the theme?

Yes, plocks has a comprehensive theming system. You can customize colors, typography, spacing, and component variants through the theme configuration. See our Theming guide for detailed instructions.

Docs: https://plocks.dev/faq

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/faq/can-use-custom-fonts.md -->

# Can I use custom fonts?

Yes, you can configure custom fonts through the theme system. plocks's typography system allows you to specify custom font families for different text variants.

Docs: https://plocks.dev/faq

--------------------------------------------------------------------------------

<!-- source: https://plocks.dev/llms/faq/how-report-bugs.md -->

# How do I report bugs or request features?

You can report bugs and request features on our GitHub repository. We welcome community contributions and feedback to make plocks better for everyone.

Docs: https://plocks.dev/faq

--------------------------------------------------------------------------------