# React UI Library — Complete Documentation

Every documentation page concatenated in full: component and chart pages with
their props tables and every demo, 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://react-ui-library.com/llms.txt

All code examples use the published package imports (@platform-blocks/react-ui-library, @platform-blocks/charts).

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

# GUIDES

<!-- source: https://react-ui-library.com/llms/guides/getting-started.md -->

# Getting started

Install react-ui-library, wire up the provider, and render your first component.

Docs: https://react-ui-library.com/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 [@platform-blocks/react-ui-library](https://www.npmjs.com/package/@platform-blocks/react-ui-library) to your React Native or Expo project:

```tsx
npm install @platform-blocks/react-ui-library
```

## Install the peer dependencies

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

```tsx
npx expo install \
    react-native-reanimated \
    react-native-safe-area-context \
    react-native-svg \
    @tabler/icons-react-native
```

## Set up the provider

Wrap your root component with PlatformBlocksProvider to enable theming:

`App.tsx`

```tsx
import React from 'react';
import { PlatformBlocksProvider } from '@platform-blocks/react-ui-library';
import { YourApp } from './YourApp';

export default function App() {
  return (
    <PlatformBlocksProvider>
      <YourApp />
    </PlatformBlocksProvider>
  );
}
```

## Verify the install

Render a component to confirm everything is wired up:

`TestComponent.tsx`

```tsx
import React from 'react';
import { Text, Button, Card } from '@platform-blocks/react-ui-library';

export function TestComponent() {
  return (
    <Card variant='outline'>
      <Text variant='h2'>
        Welcome to React UI Library! 🎉
      </Text>
      <Button
        title='It works!'
        variant='filled'
        onPress={() => console.log('Success!')}
      />
    </Card>
  );
}
```

## Templates

To use a template, open it on GitHub and click the "Use this template" button — GitHub creates a fresh repository from it under your account. Expo templates also work with npx create-expo-app@latest my-app --template <repo-url>. Every template ships with React UI Library, its peer dependencies, and the provider already set up.

- [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)
- [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)
- [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)
- [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)
- [web-template](https://github.com/platform-blocks/web-template) — React Native Web only — React UI Library components in a web-first single-page app. (Web, React Native Web)
- react-native-template (coming soon) — Bare React Native (community CLI, no Expo) with native projects checked in and peer dependencies linked. (React Native CLI, iOS, Android)

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

<!-- source: https://react-ui-library.com/llms/guides/accessibility.md -->

# Accessibility at React UI Library

Inclusive design is a baseline requirement across the React UI Library 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://react-ui-library.com/accessibility

## Keyboard & Focus Management

React UI Library 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 '@platform-blocks/react-ui-library';

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://react-ui-library.com/llms/guides/localization.md -->

# Localization

React UI Library 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://react-ui-library.com/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 '@platform-blocks/react-ui-library';
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 '@platform-blocks/react-ui-library';

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).

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

<!-- source: https://react-ui-library.com/llms/guides/contributing.md -->

# Contributing to React UI Library

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://react-ui-library.com/contribute

## Repo layout

- `packages/ui` — The component library published as `@platform-blocks/react-ui-library` — 100+ components, hooks, and the theming system
- `packages/charts` — The charting package published as `@platform-blocks/charts` — 25 chart types on that same theming
- `apps/react-ui-library.com` — This documentation site (Expo Router, statically rendered web)
- `scripts/` — Generators: demos, docs metadata, llms.txt, sitemap, exports map, release

## Set up the repo

React UI Library 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/react-ui-library.git
cd react-ui-library
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/ui/src/components/<Name>/` 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 `packages/ui/src/index.ts`.
3. 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/react-ui-library.com/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/react-ui-library.com/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 org](https://github.com/platform-blocks) and are listed via `apps/react-ui-library.com/config/templates.ts`.
- Built a starter with your own stack? [Share it with us](https://github.com/platform-blocks/react-ui-library/issues/new?template=community_template.yml) — accepted templates get listed on the [Getting Started](https://react-ui-library.com/getting-started) page.

## Releases

Maintainers run `npm run release`, which verifies both packages (exports, lint, tests, build) and publishes `@platform-blocks/react-ui-library` and `@platform-blocks/charts` to npm. 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/react-ui-library/issues) — a question that needed asking is usually a docs bug worth fixing.

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

# COMPONENTS

<!-- source: https://react-ui-library.com/llms/components/Accordion.md -->

# Accordion

The Accordion component groups related content into expandable sections.

## Metadata

- Canonical name: `Accordion`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Accordion } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 0.4.0
- Category: display
- Tags: collapse, expand, panel, ui, content-grouping
- Docs: https://react-ui-library.com/components/Accordion
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Accordion

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | AccordionItem[] | Yes |  | Ordered list of items to render. The `key` for each item must be unique. |
| `type` | AccordionType | No | 'single' | Expansion behavior. 'single' ensures only one item can be expanded at a time; 'multiple' allows independent expansion. |
| `defaultExpanded` | string[] | No | [] as string[] | Initial expanded item keys (uncontrolled). Ignored when `expanded` is provided. For `type="single"` only the first key is used at initialization. |
| `expanded` | string[] | No |  | Controlled set of expanded item keys. Provide alongside `onExpandedChange`. |
| `onExpandedChange` | (expanded: string[]) => void | No |  | Called when the expanded keys change (both controlled & uncontrolled flows). |
| `onItemToggle` | OnAccordionToggle | No |  | Per-item toggle event with rich metadata. Fires after state resolution. |
| `variant` | AccordionVariant | No | 'default' | Visual variant style preset. |
| `size` | SizeValue | No | 'md' | Size scale controlling paddings, font sizes, and icon dimensions. |
| `color` | ThemeColor | No | 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 | No | true | Whether to render the chevron affordance. |
| `chevronPosition` | 'start' \| 'end' | No | 'end' | Chevron placement relative to the header text. |
| `density` | 'comfortable' \| 'compact' \| 'spacious' | No | 'comfortable' | Space efficiency / vertical density preset. |
| `style` | StyleProp<ViewStyle> | No |  | Root container style override. |
| `headerStyle` | StyleProp<ViewStyle> | No |  | Header row style override applied to each item. |
| `contentStyle` | StyleProp<ViewStyle> | No |  | Collapsible content container style override. |
| `headerTextStyle` | StyleProp<TextStyle> | No |  | Text style applied to the header label. |
| `titleProps` | Omit<TextProps, 'children'> | No |  | Override props applied to each item's header `<Text>` (style, weight, ff, size, color). Applies to every item in the accordion. |
| `persistKey` | string | No |  | Explicit persistence key. If omitted, an automatic hash key will be generated when uncontrolled. |
| `autoPersist` | boolean | No | true | Enables persistence of expanded state (uncontrolled only) across remounts in-process. |
| `animated` | AccordionAnimationProp | No | true | Enables animation or accepts a config object for custom durations & easing. |
| `transitionDuration` | number | No | 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. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Single Expansion
ID: `Accordion.basic` • Tags: accordion • Category: usage • Status: stable • Since: 1.0.0

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

```tsx
return <Accordion type="single" items={faqItems} />;
}
```

### Multiple Expansion
ID: `Accordion.multiple` • Tags: accordion, controlled • Category: behavior • Status: stable • Since: 1.0.0

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

```tsx
const [expandedKeys, setExpandedKeys] = useState<string[]>(['collaboration']);
  return (
    <Accordion
      type="multiple"
      expanded={expandedKeys}
      onExpandedChange={setExpandedKeys}
      items={knowledgeBase}
    />
  );
}
```

### Visual Variants
ID: `Accordion.variants` • Tags: accordion, appearance • Category: appearance • Status: stable • Since: 1.0.0

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

```tsx
const variants = ['default', 'separated', 'bordered'] as const;
  return (
    <Block>
      {variants.map((variant) => (
        <Block key={variant}>
          <Text size="xs" weight="600" color="muted" uppercase tracking={1}>
            {variant}
          </Text>
          <Accordion type="single" variant={variant} items={onboardingSteps} />
        </Block>
      ))}
    </Block>
  );
}
```

### Accent Colors
ID: `Accordion.colors` • Tags: accordion, appearance, color • Category: appearance • Status: stable • Since: 0.10.1

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
return (
    <Accordion
      type="multiple"
      variant="separated"
      defaultExpanded={['healthy']}
      items={statusItems}
    />
  );
}
```

### Title customization
ID: `Accordion.title-customization` • Tags: titleProps, customization, slot-props • Category: general • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Accordion
      items={setupSteps}
      titleProps={{ uppercase: true, tracking: 1, weight: '700', size: 'sm' }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Alert.md -->

# Alert

The Alert component displays important messages to users with different severity levels, variants, and optional actions like dismissal. Title and body each accept full `<Text>` props via `titleProps` / `bodyProps`.

## Metadata

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

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | AlertVariant | No | 'light' |  |
| `color` | ThemeColor | No | 'primary' |  |
| `severity` | AlertSeverity | No |  | Severity helper — sets both the color and the default icon (`info \| success \| warning \| error`). More than a color: prefer it over `color` when the alert carries a status, so the icon comes with it. |
| `title` | string | No |  |  |
| `children` | React.ReactNode | No |  |  |
| `icon` | React.ReactNode \| string \| null \| false | No |  |  |
| `fullWidth` | boolean | No | false |  |
| `withCloseButton` | boolean | No | false |  |
| `closeButtonLabel` | string | No |  |  |
| `onClose` | () => void | No |  |  |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `testID` | string | No |  |  |
| `titleProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the title `<Text>` (style, weight, ff, size, color). |
| `bodyProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the body `<Text>` (the `children` content). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `radius` | RadiusValue | No | 'md' | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basics
ID: `Alert.basic` • Tags: alerts • Category: basics • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Alert.variants` • Tags: alerts, variants • Category: styling • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Alert.interactive` • Tags: alerts, dismissible • Category: interaction • Status: stable • Since: 1.0.0

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

```tsx
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://react-ui-library.com/llms/components/AppShell.md -->

# AppShell

High-level layout container orchestrating header, navigation rail/drawer, aside panel, footer, and optional mobile bottom navigation. Provides consistent responsive behavior and safe-area handling across platforms.

## Responsibilities
- Manage responsive breakpoints & derive layout measurements
- Provide context for child sections (header height, navbar width, etc.)
- Support desktop inline collapsing (rail) and mobile drawer presentation
- Coordinate safe-area padding via `SafeAreaProvider`
- Offer configurable animation duration for structural transitions

## Public Sub-Components
- `AppShell.Header` – fixed header region at top
- `AppShell.Navbar` – left navigation (rail / drawer)
- `AppShell.Aside` – right supplemental panel
- `AppShell.Footer` – bottom footer (desktop)
- `AppShell.BottomNav` – mobile-only bottom navigation bar
- `AppShell.Main` – primary scroll/content surface
- `AppShell.Section` – helper container for vertical stacking inside panels

## Key Hooks
- `useAppShell()` – consume computed layout context
- `useBreakpoint()` – current breakpoint token
- `useNavbarHover()` – desktop rail hover expansion state
- `resolveResponsiveValue(value, breakpoint)` – utility to normalize `ResponsiveSize`

## Default Config Reference
See `defaults.ts` for baseline dimension & behavior values and `meta.schema.ts` for a lightweight machine-readable spec.

## Notes
- Hover expansion is intentionally local to navbar to avoid global re-renders
- Rail width defined via `navbar.collapsedWidth` (default 72)
- Future: integrate design token pipeline for breakpoint map & spacing scales.
- `AppShell.Main` supports configurable `maxWidth`, centering, and responsive table-of-contents rail. When `autoLayout` is enabled you can pass `maxContentWidth`, `centerContent`, and table of contents props directly to `AppShell` for convenience.

## Metadata

- Canonical name: `AppShell`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { AppShell } from '@platform-blocks/react-ui-library';`
- Category: layout
- Docs: https://react-ui-library.com/components/AppShell
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/AppShell

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layout` | 'default' \| 'alt' | No |  |  |
| `header` | HeaderConfig | No |  |  |
| `navbar` | NavbarConfig | No |  |  |
| `aside` | AsideConfig | No |  |  |
| `footer` | FooterConfig | No |  |  |
| `bottomNav` | BottomNavConfig | No |  |  |
| `showHeader` | boolean | No | true |  |
| `layoutSections` | LayoutVisibilityConfig | No |  | Toggle rendering of individual autoLayout sections |
| `autoLayout` | boolean | No |  | 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) | No |  | Content to render inside AppShell.Header when autoLayout is enabled |
| `navbarContent` | React.ReactNode \| (() => React.ReactNode) | No |  | Content to render inside AppShell.Navbar when autoLayout is enabled |
| `asideContent` | React.ReactNode \| (() => React.ReactNode) | No |  | Content to render inside AppShell.Aside when autoLayout is enabled |
| `footerContent` | React.ReactNode \| (() => React.ReactNode) | No |  | Content to render inside AppShell.Footer when autoLayout is enabled |
| `bottomNavItems` | BottomAppBarItem[] | No |  | Items for a mobile bottom navigation bar when autoLayout is enabled |
| `bottomNavProps` | Partial<AppShellBottomNavProps> | No |  | Additional props forwarded to BottomAppBar in autoLayout mode (items overridden by bottomNavItems) |
| `mobileMenu` | MobileMenuConfig | No |  |  |
| `cssGeometry` | boolean | No | 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 | No |  |  |
| `padding` | ResponsiveSize | No | 'md' |  |
| `withBorder` | boolean | No | true |  |
| `zIndex` | number | No | 100 |  |
| `transitionDuration` | number | No | 200 |  |
| `transitionTimingFunction` | string | No | 'ease' |  |
| `disabled` | boolean | No | false |  |
| `children` | React.ReactNode | Yes |  |  |
| `backgroundColor` | string | No |  |  |
| `withSafeArea` | boolean | No | true |  |
| `style` | any | No |  |  |
| `testID` | string | No |  |  |
| `maxContentWidth` | number \| string | No |  | Maximum width for main content area to prevent stretching on wide screens |
| `centerContent` | boolean | No | true | Center content when maxContentWidth is set |
| `tableOfContents` | React.ReactNode | No |  | Optional table of contents rendered to the right of the main content |
| `hideTableOfContentsOnMobile` | boolean | No | true | Hide the table of contents automatically on mobile breakpoints |
| `tableOfContentsWidth` | number \| string | No | 280 | Custom width for the table of contents column |
| `tableOfContentsWithBorder` | boolean | No | true | Toggle border between content and table of contents |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Enhanced
ID: `AppShell.enhanced` • Category: general

```tsx
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>
);
  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://react-ui-library.com/llms/components/AudioPlayer.md -->

# AudioPlayer

AudioPlayer wraps `expo-audio` with a seekable [Waveform](/components/Waveform), transport controls and progress callbacks. Times in `PlaybackState`, `ProgressData` and the ref methods are milliseconds.

Playback needs the optional `expo-audio` peer dependency (`npx expo install expo-audio`); without it the component renders and reports a missing-module error rather than throwing.

## Metadata

- Canonical name: `AudioPlayer`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { AudioPlayer } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.11.0
- Category: media
- Tags: audio, player, waveform, media, playback
- Docs: https://react-ui-library.com/components/AudioPlayer
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/AudioPlayer

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `source` | string \| number \| { uri: string } | No |  | Audio source - can be URL, local file, or asset |
| `peaks` | number[] | No |  | Pre-computed waveform peaks (optional - will generate if not provided) |
| `autoPlay` | boolean | No |  | Whether to auto-play when loaded |
| `loop` | boolean | No |  | Whether to loop the audio |
| `volume` | number | No |  | Initial volume (0-1) |
| `rate` | number | No |  | Playback rate (0.5-2.0) |
| `showControls` | boolean | No |  | Whether to show player controls |
| `controls` | { playPause?: boolean; skip?: boolean; volume?: boolean; speed?: boolean; download?: boolean; share?: boolean; waveform?: boolean; } | No |  | Which controls to display |
| `controlsPosition` | 'top' \| 'bottom' \| 'overlay' \| 'none' | No |  | Custom control layout |
| `variant` | 'minimal' \| 'compact' \| 'full' \| 'soundcloud' \| 'spotify' | No |  | Player theme variant |
| `colorScheme` | 'light' \| 'dark' \| 'auto' | No |  | Color scheme |
| `onLoad` | (data: AudioLoadData) => void | No |  | Called when audio is loaded and ready |
| `onPlaybackStateChange` | (state: PlaybackState) => void | No |  | Called when playback state changes |
| `onProgress` | (data: ProgressData) => void | No |  | Called during playback with current time |
| `onEnd` | () => void | No |  | Called when playback finishes |
| `onError` | (error: AudioError) => void | No |  | Called on playback error |
| `onBuffer` | (data: BufferData) => void | No |  | Called when audio buffer updates |
| `generateWaveform` | boolean | No |  | Whether to generate waveform from audio |
| `waveformOptions` | { samples?: number; precision?: number; channel?: 'left' \| 'right' \| 'mix'; } | No |  | Waveform generation options |
| `showTime` | boolean | No |  | Show time labels |
| `timeFormat` | 'mm:ss' \| 'hh:mm:ss' \| 'relative' | No |  | Time format |
| `showMetadata` | boolean | No |  | Show audio metadata |
| `metadata` | AudioMetadata | No |  | Audio metadata |
| `showSpectrum` | boolean | No |  | Show spectrum analyzer |
| `spectrumOptions` | SpectrumOptions | No |  | Spectrum analyzer options |
| `enableKeyboardShortcuts` | boolean | No |  | Enable keyboard shortcuts |
| `keyboardShortcuts` | KeyboardShortcuts | No |  | Custom keyboard shortcuts |
| `enableGestures` | boolean | No |  | Enable gesture controls |
| `gestureConfig` | GestureConfig | No |  | Gesture configuration |
| `enableEffects` | boolean | No |  | Enable audio effects |
| `effects` | AudioEffects | No |  | Audio effects configuration |
| `playlist` | PlaylistItem[] | No |  | Enable playlist support |
| `currentTrack` | number | No |  | Current playlist index |
| `onTrackChange` | (index: number, track: PlaylistItem) => void | No |  | Playlist callbacks |
| `enableExport` | boolean | No |  | Enable audio export |
| `exportOptions` | { formats?: ('mp3' \| 'wav' \| 'aac')[]; quality?: 'low' \| 'medium' \| 'high'; } | No |  | Export options |
| `shareOptions` | { platforms?: ('copy' \| 'email' \| 'social')[]; includeTimestamp?: boolean; } | No |  | Custom share options |
| `w` | number | No |  | Width of the waveform |
| `h` | number | No |  | Height of the waveform |
| `color` | string | No |  | Color of the waveform |
| `size` | ComponentSizeValue | No | '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 | No |  | Width of individual bars (for bar variants) |
| `barGap` | number | No |  | Gap between bars (for bar variants) |
| `strokeWidth` | number | No |  | Stroke width for line variant |
| `gradientColors` | string[] | No |  | Colors for gradient variant |
| `progressColor` | string | No |  | Color for the progress indicator |
| `interactive` | boolean | No |  | Whether the waveform is interactive (clickable for seeking) |
| `onSeek` | (position: number) => void | No |  | Callback fired when user clicks/seeks to a position |
| `onDragStart` | (position: number) => void | No |  | Callback fired when user starts dragging |
| `onDrag` | (position: number) => void | No |  | Callback fired when user is dragging |
| `onDragEnd` | (position: number) => void | No |  | Callback fired when user ends dragging |
| `accessibilityLabel` | string | No |  | Accessibility label for the waveform |
| `accessibilityHint` | string | No |  | Accessibility hint for interactive waveforms |
| `minBarHeight` | number | No |  | Minimum height for bars (prevents invisible bars) |
| `normalize` | boolean | No |  | Whether to normalize waveform heights so the tallest bar uses full height |
| `fullWidth` | boolean | No |  | Whether the waveform should take the full width of its container |
| `maxVisibleBars` | number | No |  | Maximum number of bars to render (for performance with large datasets) |
| `showProgressLine` | boolean | No |  | Whether to show a vertical progress line indicator |
| `progressLineStyle` | { color?: string; width?: number; opacity?: number; } | No |  | Style configuration for the progress line |
| `showTimeStamps` | boolean | No |  | Whether to show time stamps along the waveform |
| `duration` | number | No |  | Duration in seconds for time stamp calculation |
| `timeStampInterval` | number | No |  | Time stamp interval in seconds |
| `loading` | boolean | No |  | Whether the waveform is in a loading state |
| `error` | string | No |  | Error message to display |
| `loadingProgress` | number | No |  | Loading progress (0-1) for progressive loading |
| `selection` | [number, number] | No |  | Selected time range [start, end] in normalized coordinates (0-1) |
| `onSelectionChange` | (selection: [number, number]) => void | No |  | Callback when selection changes |
| `zoomLevel` | number | No |  | Zoom level (1 = normal, 2 = 2x zoom, etc.) |
| `zoomCenter` | number | No |  | Zoom center position (0-1) |
| `onZoomChange` | (zoomLevel: number, center: number) => void | No |  | Callback when zoom changes |
| `enableAnimations` | boolean | No |  | Whether to enable smooth animations |
| `showRMS` | boolean | No |  | Whether to show RMS (average) levels alongside peaks |
| `rmsData` | number[] | No |  | RMS data array (should match peaks length) |
| `markers` | WaveformMarker[] | No |  | Custom markers to display on the waveform |
| `enablePerformanceMonitoring` | boolean | No |  | Enable performance monitoring |
| `onPerformanceMetrics` | (metrics: PerformanceMetrics) => void | No |  | Callback for performance metrics |

## Examples

### Basic Usage
ID: `AudioPlayer.basic` • Tags: audio, playback, peaks, expo-audio • Category: basics • Status: stable • Since: 1.0.0

Point `source` at a URL or a bundled clip and 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
// Peaks measured from the same bundled clip the player loads.
  return (
    <Block gap="sm" w="100%" maxW={520}>
      <AudioPlayer
        source={require('../../../../assets/sounds/melody.mp3')}
        peaks={MELODY_PEAKS}
        h={72}
        showMetadata
        metadata={{ title: 'Arpeggio', artist: 'Demo Tones' }}
        controlsPosition="top"
        controls={{ playPause: true, volume: true, speed: true, waveform: true }}
      />
      <Text variant="small" color="muted">
        Playback runs through `expo-audio`. Pass `peaks` to draw the real waveform, then tap it to
        seek — the progress line follows playback either way.
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/AutoComplete.md -->

# AutoComplete

The AutoComplete component provides search functionality with suggestions, supporting single/multi-select, async data loading, and rich content display

## Metadata

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

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | string | No |  | Input label |
| `description` | string | No |  | Description text below the input |
| `helperText` | string | No |  | Helper text displayed below the field when no error is present |
| `required` | boolean | No |  | Whether the field is required |
| `error` | string | No |  | Error message |
| `value` | string | No |  | Input value |
| `onChangeText` | (text: string) => void | No |  | Change handler |
| `placeholder` | string | No |  | Placeholder text |
| `disabled` | boolean | No |  | Whether the input is disabled |
| `size` | SizeValue | No |  | Controls input size (affects padding and height) |
| `radius` | RadiusValue | No |  | Controls border radius; accepts size tokens or numeric value |
| `clearable` | boolean | No |  | Show built-in clear button when there is text |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `style` | StyleProp<ViewStyle> | No |  | Custom style |
| `data` | AutoCompleteOption[] | No |  | Data source for suggestions |
| `onSearch` | (query: string) => Promise<AutoCompleteOption[]> | No |  | Async data fetcher |
| `minSearchLength` | number | No |  | Minimum characters to trigger search |
| `searchDelay` | number | No |  | Search debounce delay |
| `renderItem` | ( item: AutoCompleteOption, index: number, options: { query: string; onSelect: (item: AutoCompleteOption) => void; isHighlighted?: boolean; isSelected?: boolean; } ) => React.ReactNode | No |  | Custom item renderer |
| `onSelect` | (item: AutoCompleteOption) => void | No |  | Selection handler |
| `renderValue` | ( item: AutoCompleteOption, context: { focused: boolean; clear: () => void; } ) => React.ReactNode | No |  | 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. |
| `allowCustomValue` | boolean | No |  | Whether to allow custom values |
| `maxSuggestions` | number | No |  | Maximum number of suggestions to display |
| `showSuggestionsOnFocus` | boolean | No |  | Whether to show suggestions on focus (default: true) |
| `renderEmptyState` | () => React.ReactNode | No |  | Custom empty state component |
| `renderLoadingState` | () => React.ReactNode | No |  | Custom loading state component |
| `filter` | (item: AutoCompleteOption, query: string) => boolean | No |  | Filter function for local data |
| `highlightMatches` | boolean | No |  | Whether to highlight matching text |
| `highlightColor` | string | No |  | Text color for the matched substring when `highlightMatches` is on. Defaults to a primary-ramp shade chosen for the active color scheme. |
| `highlightBackgroundColor` | string | No |  | Background color painted behind the matched substring (default: transparent — the match is distinguished by color and weight). |
| `suggestionsStyle` | any | No |  | Custom styles for suggestions container |
| `suggestionItemStyle` | any | No |  | Custom styles for suggestion items |
| `multiSelect` | boolean | No |  | Enable multi-select mode |
| `selectedValues` | AutoCompleteOption[] | No |  | 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 | No |  | Custom renderer for each selected value chip in multi-select mode |
| `selectedValuesContainerStyle` | StyleProp<ViewStyle> | No |  | Optional style override for the selected values container |
| `selectedValueChipProps` | Partial<ChipProps> | No |  | Additional props applied to the default Chip renderer for selected values |
| `refocusAfterSelect` | boolean | No |  | Controls whether the input regains focus after selecting an option |
| `freeSolo` | boolean | No |  | Whether to allow free-form input (can add custom values) |
| `displayProperty` | 'label' \| 'value' | No |  | What to display in input after selection - 'label' or 'value' |
| `useModal` | boolean | No |  | Whether to render suggestions in a modal for guaranteed top layering |
| `usePortal` | boolean | No |  | Whether to render suggestions in a portal for proper z-index handling (default: true) |
| `inputWidth` | number \| string | No |  | Explicit width for the input container (overrides layout width) |
| `minWidth` | number | No |  | Minimum width (particularly helpful on Android where intrinsic shrink can occur) |
| `textInputProps` | Omit<TextInputProps, 'value' \| 'onChangeText' \| 'placeholder'> | No |  | Additional TextInput props |
| `autoCapitalize` | RNTextInputProps['autoCapitalize'] | No |  | Text auto-capitalization behavior |
| `autoCorrect` | boolean | No |  | Whether to enable auto-correct |
| `autoFocus` | boolean | No |  | Whether to auto-focus on mount |
| `returnKeyType` | RNTextInputProps['returnKeyType'] | No |  | Return key type for soft keyboard |
| `blurOnSubmit` | boolean | No |  | Whether to blur on submit |
| `selectTextOnFocus` | boolean | No |  | Select all text on focus |
| `textContentType` | RNTextInputProps['textContentType'] | No |  | iOS text content type for autofill |
| `textAlign` | RNTextInputProps['textAlign'] | No |  | Text alignment |
| `spellCheck` | boolean | No |  | Whether spell check is enabled |
| `inputMode` | RNTextInputProps['inputMode'] | No |  | Input mode (modern alternative to keyboardType) |
| `enterKeyHint` | RNTextInputProps['enterKeyHint'] | No |  | Enter key hint |
| `selectionColor` | string | No |  | Color of the text selection handles and highlight |
| `showSoftInputOnFocus` | boolean | No |  | Whether to show the soft keyboard on focus |
| `editable` | boolean | No |  | Whether the field is editable |
| `caretHidden` | boolean | No |  | Hide the blinking text caret (useful for select-like, non-editable fields) |
| `placement` | 'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end' \| 'right-start' \| 'right-end' | No |  | Placement preference for the suggestions dropdown (default: 'bottom-start') |
| `flip` | boolean | No |  | Enable flipping to opposite side when dropdown would go off-screen (default: true) |
| `shift` | boolean | No |  | Enable shifting within bounds when dropdown would go off-screen (default: true) |
| `boundary` | number | No |  | Distance from viewport edges in pixels (default: 12) |
| `autoReposition` | boolean | No |  | Enable automatic repositioning on scroll/resize (default: true) |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>`. |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>`. |
| `placeholderTextColor` | string | No |  | Color of the placeholder text (defaults to `theme.text.muted`). |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | View props applied to the wrapper around startSection (chip area, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | View props applied to the wrapper around endSection (clear button area). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |

## Examples

### Basic
ID: `AutoComplete.basic` • Tags: basic, getting-started, search • Category: usage • Status: stable • Since: 1.0.0

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

```tsx
const [inputValue, setInputValue] = useState('');
  const [selectedSport, setSelectedSport] = useState<AutoCompleteOption | null>(null);
  const displayValue = useMemo(() => selectedSport?.label ?? inputValue, [selectedSport, inputValue]);
  return (
    <Block w={400}>
      <AutoComplete
        label="Choose a sport"
        placeholder="Search for a sport..."
        data={sports}
        value={displayValue}
        onChangeText={(value) => {
          setInputValue(value);
          if (!value) setSelectedSport(null);
        }}
        onSelect={(item) => {
          setSelectedSport(item);
          setInputValue(item.label);
        }}
        displayProperty="label"
        minSearchLength={1}
      />
    </Block>
  );
}
```

### Multi-select tags
ID: `AutoComplete.multi` • Tags: multi-select, multiple, selection • Category: features • Status: stable • Since: 1.0.0

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

```tsx
const [inputValue, setInputValue] = useState('')
  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 w={400}>
      <AutoComplete
        label="Music genres"
        placeholder="Search genres..."
        data={musicGenres}
        value={inputValue}
        onChangeText={setInputValue}
        onSelect={handleToggle}
        multiSelect
        selectedValues={selectedGenres}
        minSearchLength={0}
        clearable
        onClear={() => {
          setSelectedGenres([])
          setInputValue('')
        }}
        selectedValuesContainerStyle={{ flexWrap: 'wrap', gap: 6 }}
        renderSelectedValue={(item, _index, helpers) => (
          <Chip
            key={item.value}
            size="sm"
            variant="surface"
            endIcon={<Icon name="x" size={12} color="currentColor" />}
            onRemove={helpers.onRemove}
          >
            {item.label}
          </Chip>
        )}
        inputWidth={400}
      />
    </Block>
  )
}
```

### Select-Like Behavior
ID: `AutoComplete.select-like` • Tags: select, dropdown, focus, options • Category: usage • Status: stable • Since: 1.0.0

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
const [inputValue, setInputValue] = useState('')
  const [selectedCountry, setSelectedCountry] = useState<AutoCompleteOption | null>(null)
  return (
    <Block w={400}>
      <AutoComplete
        label="Country"
        placeholder="Select a country..."
        data={countries}
        value={inputValue}
        onChangeText={(value) => {
          setInputValue(value)
          if (!value) setSelectedCountry(null)
        }}
        onSelect={(item) => {
          setSelectedCountry(item)
          setInputValue(item.label)
        }}
        minSearchLength={0}
        maxSuggestions={countries.length}
        editable={false}
        caretHidden
        filter={() => true}
        highlightMatches={false}
        fullWidth
      />
    </Block>
  )
}
```

### Async auto-complete
ID: `AutoComplete.async` • Tags: async, loading, api, remote • Category: features • Status: stable • Since: 1.0.0

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

```tsx
const searchLanguages = async (query: string): Promise<AutoCompleteOption[]> => {
  await new Promise((resolve) => setTimeout(resolve, 400))
  const normalized = query.toLowerCase()
  return programmingLanguages.filter((language) =>
    language.label.toLowerCase().includes(normalized),
  )
}
  const [inputValue, setInputValue] = useState('')
  const [selectedLanguage, setSelectedLanguage] = useState<AutoCompleteOption | null>(null)
  return (
    <Block w={400}>
      <AutoComplete
        label="Search programming languages"
        placeholder="Start typing..."
        onSearch={searchLanguages}
        value={inputValue}
        onChangeText={(value) => {
          setInputValue(value)
          if (!value) setSelectedLanguage(null)
        }}
        onSelect={(item) => {
          setSelectedLanguage(item)
          setInputValue(item.label)
        }}
        minSearchLength={2}
        searchDelay={300}
        highlightMatches
        fullWidth
      />
    </Block>
  )
}
```

### Free Solo
ID: `AutoComplete.freesolo` • Tags: freesolo, custom, text-input • Category: features • Status: stable • Since: 1.0.0

Suggests fruits while still accepting custom values.

```tsx
const [value, setValue] = useState('')
  return (
    <Block w={400}>
      <AutoComplete
        label="Favorite fruit"
        placeholder="Type anything..."
        data={fruits}
        value={value}
        onChangeText={setValue}
        onSelect={(item) => setValue(item.label)}
        freeSolo
        minSearchLength={0}
        fullWidth
      />
      <Text size="xs" color="secondary">
        Current value: {value || '(empty)'}
      </Text>
    </Block>
  )
}
```

### Free Solo (multi-select)
ID: `AutoComplete.freesolo-multi` • Tags: freesolo, multi-select, custom, tags • Category: features • Status: stable • Since: 1.0.0

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

```tsx
const [inputValue, setInputValue] = useState('')
  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 w={400}>
      <AutoComplete
        label="Favorite fruits"
        placeholder="Type a fruit and press Enter..."
        data={fruits}
        value={inputValue}
        onChangeText={setInputValue}
        onSelect={handleToggle}
        freeSolo
        multiSelect
        selectedValues={selected}
        minSearchLength={0}
        clearable
        onClear={() => {
          setSelected([])
          setInputValue('')
        }}
        selectedValuesContainerStyle={{ flexWrap: 'wrap', gap: 6 }}
        renderSelectedValue={(item, _index, helpers) => (
          <Chip
            key={item.value}
            size="sm"
            variant="light"
            color="primary"
            endIcon={<Icon name="x" size={8} color="currentColor" />}
            onRemove={helpers.onRemove}
          >
            {item.label}
          </Chip>
        )}
      />
    </Block>
  )
}
```

### Grouped suggestions
ID: `AutoComplete.grouped` • Tags: grouped, categories, sections • Category: features • Status: stable • Since: 1.0.0

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

```tsx
const [value, setValue] = useState('')
  const [selectedCountry, setSelectedCountry] = useState<AutoCompleteOption | null>(null)
  return (
    <Block w={400} >
      <AutoComplete
        label="Search countries"
        placeholder="Search for a country..."
        data={groupedCountries}
        value={value}
        onChangeText={(next) => {
          setValue(next)
          if (!next) setSelectedCountry(null)
        }}
        onSelect={(item) => {
          setSelectedCountry(item)
          setValue(item.label)
        }}
        minSearchLength={1}
        highlightMatches
        fullWidth
      />
    </Block>
  )
}
```

### Rich Content
ID: `AutoComplete.rich` • Tags: rich, custom-render, complex • Category: features • Status: stable • Since: 1.0.0

AutoComplete with custom rendering and complex data structures.

```tsx
interface RichSportOption {
  label: string;
  value: string;
  emoji: string;
  color: string;
  price: number;     // Avg ticket price
  duration: string;  // Typical game length / format
}
// The option colors are plain 6-digit hex, so an 8-digit suffix gives a tint
// that works on both web and native without a color library.
const tint = (hex: string, alpha: string) => `${hex}${alpha}`
  const [value, setValue] = useState('')
  const [selectedSport, setSelectedSport] = useState<RichSportOption | null>(null)
  const richSportData: 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' },
  ];
  // Colored emoji tile — carries the option color instead of a loose dot, and
  // doubles as the leading media for both the dropdown row and the input value.
  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>
  )
  return (
    <Block w={400}>
      <AutoComplete
        label="Search sports"
        placeholder="Search sports with rich details..."
        data={richSportData}
        value={value}
        clearable
        // Drop focus after selecting so the rich value overlay shows immediately.
        refocusAfterSelect={false}
        onChangeText={(next) => {
          setValue(next)
          if (!next) setSelectedSport(null)
        }}
        onSelect={(item) => {
          const sport = item as RichSportOption
          setSelectedSport(sport)
          setValue(sport.label)
        }}
        // Media / title+meta / trailing price — the standard three-slot list row,
        // so the eye scans names down the left and prices down the right.
        renderItem={(item, index, helpers) => {
          const sport = item as RichSportOption
          const isChosen = selectedSport?.value === sport.value
          return (
            <MenuItemButton
              key={sport.value}
              rounded={false}
              compact
              fullWidth
              active={helpers?.isHighlighted || isChosen}
              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" weight="semibold" numberOfLines={1}>
                    {sport.label}
                  </Text>
                  <Text size="xs" color="secondary" numberOfLines={1}>
                    {sport.duration}
                  </Text>
                </Column>
                <Column align="flex-end" gap="xs">
                  <Text size="sm" weight="semibold">
                    ${sport.price.toFixed(2)}
                  </Text>
                  <Text size="xs" color="secondary">
                    avg ticket
                  </Text>
                </Column>
                {isChosen ? (
                  <Icon name="check" size={16} stroke={3} color={sport.color} />
                ) : (
                  <Block w={16} />
                )}
              </Row>
            </MenuItemButton>
          )
        }}
        // Chosen sport inside the input box — same tile, single line so it fits
        // the field height.
        renderValue={(item) => {
          const sport = item as RichSportOption
          return (
            <Row align="center" gap="sm" grow={1}>
              {renderTile(sport, 24)}
              <Text size="sm" weight="semibold">{sport.label}</Text>
              <Text size="xs" color="secondary">
                {sport.duration}
              </Text>
              <Block grow={1} />
              <Text size="sm" weight="semibold">
                ${sport.price.toFixed(2)}
              </Text>
            </Row>
          )
        }}
        minSearchLength={1}
        fullWidth
      />
    </Block>
  )
}
```

### Highlight colours
ID: `AutoComplete.highlight-colors` • Tags: highlight, palette, theme • Category: styling • Status: stable • Since: 1.0.0

`highlightMatches` bolds and tints the part of each suggestion that matches what you typed. That tint is derived from `theme.colors.primary` by default; pass `highlightColor` (and optionally `highlightBackgroundColor`) to override it — here with shades from `theme.colors.highlight`. Pick a swatch while the menu is open to see the match repaint.

```tsx
const sampleData = [
  { label: 'Apple', value: 'apple', description: 'A red or green fruit' },
  { label: 'Banana', value: 'banana', description: 'A yellow curved fruit' },
  { label: 'Cherry', value: 'cherry', description: 'A small red fruit' },
  { label: 'Date', value: 'date', description: 'A sweet brown fruit' },
  { label: 'Elderberry', value: 'elderberry', description: 'A dark purple berry' },
  { label: 'Fig', value: 'fig', description: 'A purple or green fruit' },
  { label: 'Grape', value: 'grape', description: 'Clusters of small berries' },
  { label: 'Honeydew', value: 'honeydew', description: 'A sweet green melon' },
]
  const theme = useTheme()
  const isDark = theme.colorScheme === 'dark'
  // The matched substring sits on the menu surface, so only the shades with
  // enough contrast against it are offered: dark end of the ramp on light
  // surfaces, light end on dark ones.
  const ramp = theme.colors.highlight ?? []
  const shadeIndices = isDark ? [3, 4, 5, 6] : [6, 7, 8, 9]
  const swatches = shadeIndices.map(index => ramp[index]).filter(Boolean)
  // `undefined` = no override, i.e. the primary-derived default AutoComplete
  // uses when `highlightColor` is omitted.
  const [highlightColor, setHighlightColor] = useState<string | undefined>(undefined)
  const tintIndex = isDark ? 8 : 1
  return (
    <Block w={400} gap="md">
      <AutoComplete
        label="Search fruits"
        placeholder="Type to search fruits..."
        data={sampleData}
        highlightMatches
        highlightColor={highlightColor}
        highlightBackgroundColor={highlightColor ? ramp[tintIndex] : undefined}
        minSearchLength={0}
        fullWidth
      />
      <Block gap="xs">
        <Text size="sm" weight="semibold">
          Match colour
        </Text>
        <Row gap="sm" align="center">
          <ColorSwatch
            color={theme.colors.primary[isDark ? 5 : 6]}
            selected={highlightColor === undefined}
            onPress={() => setHighlightColor(undefined)}
            accessibilityLabel="Theme default highlight colour"
          />
          {swatches.map(color => (
            <ColorSwatch
              key={color}
              color={color}
              selected={highlightColor === color}
              onPress={() => setHighlightColor(color)}
              accessibilityLabel={`Highlight colour ${color}`}
            />
          ))}
        </Row>
        <Text size="xs" color="secondary">
          Type a letter or two, then pick a swatch. The first is the default
          (primary ramp); the rest come from `theme.colors.highlight`, paired
          with a soft tint from the same ramp as the match background.
        </Text>
      </Block>
    </Block>
  )
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Avatar.md -->

# Avatar

The Avatar component displays user profile images, initials, or icons. Supports different sizes, colors, and can be grouped together in an AvatarGroup. Each text slot — initials, label, description — accepts the full Text-prop API via `fallbackProps` / `labelProps` / `descriptionProps`.

## Metadata

- Canonical name: `Avatar`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Avatar } from '@platform-blocks/react-ui-library';`
- Category: display
- Tags: avatar, profile, user, image, initials
- Docs: https://react-ui-library.com/components/Avatar
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Avatar

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | ComponentSizeValue | No |  | Size of the avatar |
| `src` | string \| ImageSourcePropType | No |  | Image for the avatar: a remote URL string or a bundled asset (`require('./avatar.png')`) |
| `fallback` | React.ReactNode | No |  | Fallback shown when no image is provided: initials string or a custom React node (e.g. an icon). |
| `backgroundColor` | string | No |  | Background color for the fallback initials |
| `textColor` | string | No |  | Text color for the fallback initials |
| `online` | boolean | No |  | Whether to show online status indicator |
| `indicatorColor` | string | No |  | Color override for the status indicator |
| `style` | StyleProp<ViewStyle> | No |  | Style override for the avatar container |
| `accessibilityLabel` | string | No |  | Accessibility label for the avatar image |
| `label` | React.ReactNode | No |  | Primary label displayed to the right of the avatar (string or custom React node) |
| `description` | React.ReactNode | No |  | Secondary description/subtext under the label |
| `gap` | number | No |  | Spacing between avatar and text block |
| `showText` | boolean | No |  | Force horizontal layout off (set false to hide label/description wrapper) |
| `fallbackProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the fallback initials `<Text>` (style, weight, ff, size, color). |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the adjacent label `<Text>` (only when `label` is a string). |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the secondary description `<Text>` (only when `description` is a string). |

## Examples

### Basics
ID: `Avatar.basic` • Tags: avatars • Category: basics • Status: stable • Since: 1.0.0

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

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

### Sizes
ID: `Avatar.sizes` • Tags: avatars, sizes • Category: styling • Status: stable • Since: 1.0.0

Display every avatar size token with guidance on when to use each scale.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Avatar key={size} size={size} fallback={size} />
      ))}
    </Row>
  );
}
```

### Icon
ID: `Avatar.icon` • Tags: avatars, icon • Category: content • Status: stable • Since: 1.0.0

Render any `<Icon>` inside an avatar by passing it to the `fallback` prop. The icon scales with the avatar size and works alongside labels, descriptions, and status indicators.

```tsx
return (
    <Block>
      <Block>
        <Text size="sm" color="muted">
          Render an icon inside the avatar via the `fallback` prop
        </Text>
        <Row gap="md" align="center">
          <Avatar
            fallback={<Icon name="user" color="white" />}
            backgroundColor="#6366f1"
          />
          <Avatar
            fallback={<Icon name="camera" color="white" />}
            backgroundColor="#10b981"
          />
          <Avatar
            fallback={<Icon name="bell" color="white" />}
            backgroundColor="#f59e0b"
          />
          <Avatar
            fallback={<Icon name="settings" color="white" />}
            backgroundColor="#ef4444"
          />
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Scales with the avatar size
        </Text>
        <Row gap="md" align="center">
          <Avatar
            size="sm"
            fallback={<Icon name="user" size="sm" color="white" />}
            backgroundColor="#6366f1"
          />
          <Avatar
            size="md"
            fallback={<Icon name="user" size="md" color="white" />}
            backgroundColor="#6366f1"
          />
          <Avatar
            size="lg"
            fallback={<Icon name="user" size="lg" color="white" />}
            backgroundColor="#6366f1"
          />
          <Avatar
            size="xl"
            fallback={<Icon name="user" size="xl" color="white" />}
            backgroundColor="#6366f1"
          />
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Icon avatar with label and online status
        </Text>
        <Avatar
          fallback={<Icon name="user" color="white" />}
          backgroundColor="#6366f1"
          label="Jane Doe"
          description="Product Designer"
          online
        />
      </Block>
    </Block>
  );
}
```

### Colors
ID: `Avatar.colors` • Tags: avatars, colors • Category: styling • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Block align="flex-start">
     <Avatar
        fallback="AB"
        backgroundColor="#FF6B6B"
        label="Custom Red Background"
      />
    </Block>
  )
}
```

### Groups
ID: `Avatar.group` • Tags: avatars, groups • Category: features • Status: stable • Since: 1.0.0

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

```tsx
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' }
];
  return (
    <Block>
      <Text weight="medium">Simple group</Text>
      <AvatarGroup>
        {TEAM.map(({ id, initials, color }) => (
          <Avatar key={id} fallback={initials} backgroundColor={color} size="md" />
        ))}
      </AvatarGroup>
      <Text variant="small" color="muted">
        Groups overlap avatars automatically to conserve space.
      </Text>
    </Block>
  );
}
```

### Overflow
ID: `Avatar.overflow` • Tags: avatars, groups, overflow, limit, tooltip • Category: features • Status: stable • Since: 1.0.0

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

```tsx
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;
  const hidden = TEAM.slice(LIMIT).map((member) => member.name);
  return (
    <AvatarGroup limit={LIMIT} size="md" surplusTooltip={hidden.join(', ')}>
      {TEAM.map(({ id, initials, color }) => (
        <Avatar key={id} fallback={initials} backgroundColor={color} />
      ))}
    </AvatarGroup>
  );
}
```

### Status indicator
ID: `Avatar.status` • Tags: avatars, status • Category: behavior • Status: stable • Since: 1.0.0

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

```tsx
type StatusAvatar = Pick<AvatarProps, 'size' | 'src' | 'online' | 'indicatorColor'> & {
  key: string;
  label: string;
  description: string;
};
const STATUS_AVATARS: StatusAvatar[] = [
  {
    key: 'online',
    label: 'Josh',
    description: 'Online',
    src: require('../../../../assets/avatars/avatar-1.png')
  },
  {
    key: 'available',
    label: 'Alice',
    description: 'Available',
    src: require('../../../../assets/avatars/avatar-2.png')
  },
  {
    key: 'focus',
    label: 'Mike',
    description: 'Focus time',
    src: require('../../../../assets/avatars/avatar-3.png'),
    indicatorColor: '#f59e0b'
  },
  {
    key: 'offline',
    label: 'Tori',
    description: 'Last active 5m ago',
    src: require('../../../../assets/avatars/avatar-4.png'),
    online: false
  }
];
  return (
    <Block direction="row" justify="space-evenly" fullWidth>
      {STATUS_AVATARS.map(({ key, indicatorColor, online = true, ...avatar }) => (
        <Avatar
          key={key}
          {...avatar}
          fallback={avatar.label.slice(0, 2).toUpperCase()}
          online={online}
          indicatorColor={indicatorColor}
        />
      ))}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Badge.md -->

# Badge

The Badge component displays compact elements that represent an input, attribute, or action. Supports different colors, sizes, and interactive features like removal. Inner label accepts the full Text-prop API via `labelProps`.

## Metadata

- Canonical name: `Badge`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Badge } from '@platform-blocks/react-ui-library';`
- Category: data
- Tags: chip, tag, badge, label, removable
- Docs: https://react-ui-library.com/components/Badge
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Badge

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | Yes |  |  |
| `size` | ComponentSizeValue | No |  |  |
| `variant` | 'filled' \| 'outline' \| 'light' \| 'subtle' \| 'gradient' | No |  |  |
| `v` | 'filled' \| 'outline' \| 'light' \| 'subtle' \| 'gradient' | No |  | Shorthand alias for `variant`. `variant` wins when both are set. |
| `color` | ThemeColor | No |  | Badge color. A palette token, `'primary.6'` shade syntax, or any CSS color. |
| `c` | ThemeColor | No |  | Shorthand alias for `color`, resolved identically. `color` wins when both are set. |
| `onPress` | () => void | No |  |  |
| `startIcon` | React.ReactNode | No |  |  |
| `endIcon` | React.ReactNode | No |  |  |
| `onRemove` | () => void | No |  |  |
| `removePosition` | 'left' \| 'right' | No |  |  |
| `disabled` | boolean | No |  |  |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `textStyle` | StyleProp<TextStyle> | No |  |  |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the inner label `<Text>` (style, weight, ff, size, color). |
| `radius` | any | No |  |  |
| `shadow` | any | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `Badge.basic` • Tags: badge, getting-started • Category: basics • Status: stable • Since: 1.0.0

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

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

### Semantic colors
ID: `Badge.colors` • Tags: colors, theming • Category: theming • Status: stable • Since: 1.0.0

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

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

### Size scale
ID: `Badge.sizes` • Tags: sizes, density • Category: layout • Status: stable • Since: 1.0.0

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

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  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
ID: `Badge.variants` • Tags: variants, styling • Category: appearance • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Badge.shadow` • Tags: shadow, emphasis • Category: appearance • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Badge.aliases` • Tags: aliases, shorthand • Category: props • Status: stable • Since: 1.0.0

Shorthand props `v` and `c` mirror `variant` and `color`, so you can write more compact JSX without losing any functionality.

```tsx
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
  return (
    <Block>
      <Row gap="sm" wrap="wrap">
        {badges.map((badge) => (
          <Badge
            key={`full-${badge.label}`}
            variant={badge.variant}
            color={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://react-ui-library.com/llms/components/Block.md -->

# Block

A polymorphic building block component that serves as a foundational element to replace View components throughout the application. Similar to a `<div>` in web development. The `bg` prop resolves through the theme — same lookup rules as `<Card bg=...>`.

## Metadata

- Canonical name: `Block`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Block } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: layout
- Tags: layout, building-block, polymorphic, foundational
- Docs: https://react-ui-library.com/components/Block
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Block

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | No |  | Child elements to render inside the block |
| `component` | React.ElementType | No |  | The component to render as |
| `style` | StyleProp<ViewStyle> | No |  | Custom style object |
| `testID` | string | No |  | Test ID for testing purposes |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessible` | boolean | No |  | Whether the element is accessible |
| `accessibilityRole` | string | No |  | Accessibility role |
| `className` | string | No |  | Custom className (for web) |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `bg` | string | No |  | Background color for the block |
| `radius` | number \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full' | No |  | Border radius for rounded corners |
| `borderWidth` | number | No |  | Border width |
| `borderColor` | string | No |  | Border color |
| `shadow` | number \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | No |  | Shadow depth (0-5) |
| `opacity` | number | No |  | Opacity (0-1) |
| `w` | number \| string \| 'auto' \| 'full' | No |  | Width of the block |
| `h` | number \| string \| 'auto' \| 'full' | No |  | Height of the block |
| `fullWidth` | boolean | No |  | Whether to take full width (100%) - shorthand for w="full" |
| `fluid` | boolean | No |  | Makes block take full available height (flex: 1) - useful for scrollable containers |
| `minW` | number \| string | No |  | Minimum width |
| `minH` | number \| string | No |  | Minimum height |
| `maxW` | number \| string | No |  | Maximum width |
| `maxH` | number \| string | No |  | Maximum height |
| `grow` | boolean \| number | No |  | Flex grow |
| `shrink` | boolean \| number | No |  | Flex shrink |
| `basis` | number \| string | No |  | Flex basis |
| `direction` | 'row' \| 'column' \| 'row-reverse' \| 'column-reverse' | No |  | Flex direction |
| `align` | 'stretch' \| 'flex-start' \| 'flex-end' \| 'center' \| 'baseline' | No |  | Align items |
| `justify` | 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly' | No |  | Justify content |
| `wrap` | boolean \| 'nowrap' \| 'wrap' \| 'wrap-reverse' | No |  | Flex wrap |
| `gap` | number \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | No |  | Gap between children. Defaults to `'sm'`; pass `0` to remove it. |
| `position` | 'relative' \| 'absolute' | No |  | Position type |
| `top` | number \| string | No |  | Top position |
| `right` | number \| string | No |  | Right position |
| `bottom` | number \| string | No |  | Bottom position |
| `left` | number \| string | No |  | Left position |
| `start` | number \| string | No |  | Start position (logical property - becomes left in LTR, right in RTL) |
| `end` | number \| string | No |  | End position (logical property - becomes right in LTR, left in RTL) |
| `zIndex` | number | No |  | Z-index |
| `flex` | boolean | No |  | Whether to render as a flex container |

## Examples

### Basic usage
ID: `Block.basic` • Tags: layout, polymorphic • Category: basics • Status: stable • Since: 0.3.0

Combine spacing, layout, and polymorphic props on `Block` to build cards, responsive rows, and button-style actions without custom wrappers.

```tsx
return (
    <Block w="100%" maxW={420}>
      <Block bg="#111827" radius="lg" p="lg">
        <Block>
          <Text weight="semibold" color="white">
            Release summary
          </Text>
          <Text size="sm" color="rgba(255,255,255,0.75)">
            Apply `bg`, `p`, and `radius` props on `Block` to build a card without custom stylesheets.
          </Text>
        </Block>
      </Block>
      <Block direction="row">
        <Block grow bg="#2563eb" radius="md" p="md">
          <Text weight="semibold" color="white">
            Velocity
          </Text>
          <Text size="sm" color="rgba(255,255,255,0.8)">
            Use `grow` so sibling Blocks share remaining space.
          </Text>
        </Block>
        <Block w={140} bg="#f9fafb" radius="md" p="md">
          <Text weight="semibold">Backlog</Text>
          <Text size="sm" color="muted">
            Combine fixed widths with flexible layouts via the `w` prop.
          </Text>
        </Block>
      </Block>
      <Block direction="row">
        <Block component="button" bg="#2563eb" radius="md" px="lg" py="sm">
          <Text color="white" weight="semibold">
            Create project
          </Text>
        </Block>
        <Block
          component="button"
          radius="md"
          px="lg"
          py="sm"
          borderWidth={1}
          borderColor="#2563eb"
        >
          <Text color="#2563eb" weight="semibold">
            View roadmap
          </Text>
        </Block>
      </Block>
    </Block>
  );
}
```

### bg shorthand
ID: `Block.bg-shorthand` • Tags: bg, theme, shorthand, customization • Category: general • Status: stable • Since: 1.0.0

`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
return (
    <Block>
      <Block>
        <Text size="sm" color="muted">Palette names → subtle tint (shade-1)</Text>
        <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>
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Specific shade with `palette.shade` syntax
        </Text>
        <Row gap="sm" wrap="wrap">
          <Block bg="primary.6" p="sm" radius="md">
            <Text c="dimmed" style={{ color: '#fff' }}>primary.6</Text>
          </Block>
          <Block bg="gray.2" p="sm" radius="md">
            <Text>gray.2</Text>
          </Block>
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">Theme background keys</Text>
        <Row gap="sm" wrap="wrap">
          <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>
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">Plain CSS color string still works</Text>
        <Block bg="#a855f7" p="sm" radius="md">
          <Text style={{ color: '#fff' }}>Custom hex</Text>
        </Block>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Blockquote.md -->

# Blockquote

The Blockquote component is used to highlight and stylize quotations or important text within your content. It supports various styles and can be customized to fit the design of your application.

## Metadata

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

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | Yes |  | Core content |
| `variant` | 'default' \| 'testimonial' \| 'featured' \| 'minimal' | No |  | Styling |
| `size` | SizeValue | No |  |  |
| `color` | string | No |  |  |
| `quoteIcon` | string \| React.ReactNode | No |  | Quote icon |
| `quoteIconPosition` | 'top-left' \| 'top-center' \| 'bottom-right' \| 'none' | No |  |  |
| `quoteIconSize` | SizeValue | No |  |  |
| `author` | BlockquoteAuthor | No |  | Author attribution |
| `links` | BlockquoteLinks | No |  | Social/profile links |
| `date` | Date \| string | No |  | Metadata |
| `rating` | BlockquoteRating | No |  |  |
| `source` | BlockquoteSource | No |  | Brand/source |
| `verified` | boolean | No |  | Verification |
| `verifiedTooltip` | string | No |  |  |
| `alignment` | 'left' \| 'center' \| 'right' | No |  | Layout |
| `attributionAlignment` | 'left' \| 'center' \| 'right' | No |  | Which side the attribution block (avatar, name, source, meta) sits on. Defaults to `'right'`, or `'center'` when `alignment` is `'center'`. |
| `border` | boolean | No |  |  |
| `shadow` | boolean | No |  |  |
| `style` | StyleProp<ViewStyle> | No |  | Standard props |
| `onPress` | () => void | No |  |  |

## Examples

### Pull quote
ID: `Blockquote.basic` • Tags: blockquote, testimonial • Category: content • Status: stable • Since: 1.0.0

Frames a simple pull quote with author details.

```tsx
const AUTHOR = {
  name: 'Jamie Ortega',
  title: 'Principal Product Designer',
};
  return (
    <Blockquote author={AUTHOR}>
      The Blockquote component keeps editorial typography consistent so our brand voice always feels elevated.
    </Blockquote>
  );
}
```

### Testimonial card
ID: `Blockquote.testimonial` • Tags: blockquote, testimonial • Category: content • Status: stable • Since: 1.0.0

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

```tsx
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',
        brand: 'google',
      }}
      date="2024-06-12"
      verified
    >
      React UI Library helped us ship an entirely new settings experience in a single sprint. The components feel native on every platform.
    </Blockquote>
  );
}
```

### Social proof
ID: `Blockquote.social` • Tags: blockquote, social • Category: content • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Block>
      <Blockquote
        variant="minimal"
        author={{
          name: '@futureshaper',
          avatar: require('../../../../assets/avatars/avatar-3.png'),
        }}
        source={{
          name: 'X (Twitter)',
          brand: 'x',
          url: 'https://x.com/platform-blocks',
        }}
        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',
          brand: 'linkedin',
        }}
        date="1 day ago"
      >
        Just finished testing the new React UI Library UI library. The component quality and developer experience is outstanding!
      </Blockquote>
      <Blockquote
        variant="testimonial"
        author={{
          name: 'Sasha Lin',
          title: 'Staff Engineer',
        }}
        source={{
          name: 'GitHub',
          brand: 'github',
        }}
        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
ID: `Blockquote.attribution` • Tags: blockquote, attribution, layout • Category: content • Status: stable • Since: 1.0.0

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
return (
    <Block>
      <Block>
        <Text variant="h5" weight="semibold">
          Right (default)
        </Text>
        <Blockquote
          variant="testimonial"
          shadow
          author={AUTHOR}
          source={SOURCE}
        >
          {QUOTE}
        </Blockquote>
      </Block>
      <Block>
        <Text variant="h5" weight="semibold">
          Left
        </Text>
        <Blockquote
          variant="testimonial"
          shadow
          attributionAlignment="left"
          author={AUTHOR}
          source={SOURCE}
        >
          {QUOTE}
        </Blockquote>
      </Block>
    </Block>
  );
}
```

### Variants overview
ID: `Blockquote.variants` • Tags: blockquote, variants • Category: content • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Block>
      <Block>
        <Text variant="h5" weight="semibold">
          Default
        </Text>
        <Blockquote author={{ name: 'Anonymous' }}>
          The best way to predict the future is to create it.
        </Blockquote>
      </Block>
      <Block>
        <Text variant="h5" weight="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" weight="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" weight="semibold">
          Minimal
        </Text>
        <Blockquote
          variant="minimal"
          quoteIconPosition="none"
          author={{ name: '@username' }}
          source={{ name: 'X (Twitter)', brand: 'x' }}
          date="2 hours ago"
        >
          Just discovered this amazing new feature! 🚀
        </Blockquote>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/BrandButton.md -->

# BrandButton

The BrandButton component renders a branded pressable for any platform in the brand icon registry. By default it's a single-line button supporting variants, sizes, icons, loading state, and full-width layout. Pass `primaryText` and `secondaryText` instead of `title` and it renders the two-line store-badge layout ("Download on the / App Store").

## Metadata

- Canonical name: `BrandButton`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { BrandButton } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: action, pressable, interactive, badge, app-store
- Docs: https://react-ui-library.com/components/BrandButton
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/BrandButton

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `brand` | BrandPlatform | Yes |  | The brand/platform to style the button for |
| `iconPosition` | 'left' \| 'right' | No |  | Position of the brand icon |
| `iconVariant` | 'full' \| 'mono' | No |  | Icon variant: 'full' for multi-color, 'mono' for single-color outline |
| `icon` | React.ReactNode | No |  | Override the default brand icon |
| `title` | string | No |  | Button text. Omit when rendering a store badge. |
| `color` | string | No |  | Override icon color (overrides brand default colors) |
| `primaryText` | string | No |  | 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`, `fullWidth` and the spacing props do not apply. |
| `secondaryText` | string | No |  | Badge headline, e.g. "App Store" / "Spotify" |
| `backgroundColor` | string | No |  | Badge shell background (badge layout only) |
| `borderColor` | string | No |  | Badge shell border color (badge layout only) |
| `darkMode` | boolean | No |  | Force the badge's dark-mode styling instead of following the theme |
| `key` | React.Key | No |  | allow React key without complaint in TS where JSX key is forwarded in type checking |
| `children` | React.ReactNode | No |  | Button text content - alternative to title prop |
| `onPress` | () => void | No |  | Called when the button is pressed |
| `onPressIn` | () => void | No |  | Called when the button press starts (for immediate feedback) |
| `onPressOut` | () => void | No |  | Called when the button press ends |
| `onHoverIn` | () => void | No |  | Called when the button is hovered (web/desktop only) |
| `onHoverOut` | () => void | No |  | Called when the button is no longer hovered (web/desktop only) |
| `onLongPress` | () => void | No |  | Called when the button is long-pressed |
| `onLayout` | (event: any) => void | No |  | Called when the button layout is calculated |
| `variant` | 'default' \| 'filled' \| 'light' \| 'subtle' \| 'secondary' \| 'outline' \| 'ghost' \| 'gradient' \| 'link' \| 'none' | No | 'default' | Button visual variant. `default` is a neutral button — the card surface with a hairline border and body text — so an unstyled `<Button>` never claims the accent color. A solid primary fill is opt-in via `filled`. |
| `size` | SizeValue | No |  | Button size |
| `disabled` | boolean | No |  | Whether the button is disabled |
| `loading` | boolean | No |  | Whether button is in loading state (shows loader) |
| `loadingTitle` | string | No |  | Text to show when loading (if not provided, shows empty text but maintains original width) |
| `fullWidth` | boolean | No |  | 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` | string | No |  | Explicit text color override (else derived automatically from variant & color) |
| `tooltip` | TooltipPropValue | No |  | 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…', maxWidth: 320, withArrow: true }}`. |
| `tooltipPosition` | TooltipProps['position'] | No |  | Tooltip position when the string form of `tooltip` is used |
| `transitionDuration` | number | No | 110 | Length of the press / pulse / hover transitions in ms. `0` applies each state instantly (no scale animation). Always 0 under reduced motion. |
| `style` | any | No |  | Style overrides for the button container |
| `testID` | string | No |  | Test ID for testing library queries |
| `accessibilityLabel` | string | No |  | Accessibility label for screen readers |
| `accessibilityHint` | string | No |  | Accessibility hint for screen readers |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the inner label `<Text>` (style, weight, ff, size, color). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |
| `shadow` | ShadowValue | No |  | Shadow value - supports size tokens and 'none' |

## Examples

### BrandButton
ID: `BrandButton.basic` • Tags: basic, getting-started • Category: basics • Status: stable • Since: 1.0.0

Basic Button usage with a title prop.

```tsx
const toast = useToast()
  return <BrandButton
   title="Click Me" 
  brand="facebook"
    onPress={() => toast.warn({ 
      title: 'What the Zuck!',
      message: 'This is a Facebook brand button',
      position: 'top-center'
    })}
  />
}
```

### BrandButton
ID: `BrandButton.colorOverride` • Tags: basic, getting-started • Category: basics • Status: stable • Since: 1.0.0

Basic Button usage with a title prop.

```tsx
return (
      <Flex direction="column" gap="lg">
        <Text variant="h6">Brand Icon Color Override</Text>
        <Text variant="p" color="secondary">
          Use the color prop to override default brand colors with a single color
        </Text>
        <Flex direction="column" gap="md">
          <Text variant="small" weight="600">Default Colors:</Text>
          <Flex direction="row" gap="sm" wrap="wrap">
            <BrandButton brand="google" title="Google" />
            <BrandButton brand="github" title="GitHub" />
            <BrandButton brand="spotify" title="Spotify" />
            <BrandButton brand="microsoft" title="Microsoft" />
          </Flex>
        </Flex>
        <Flex direction="column" gap="md">
          <Text variant="small" weight="600">Custom Color (#666666):</Text>
          <Flex direction="row" gap="sm" wrap="wrap">
            <BrandButton brand="google" title="Google" color="#666666" />
            <BrandButton brand="github" title="GitHub" color="#666666" />
            <BrandButton brand="spotify" title="Spotify" color="#666666" />
            <BrandButton brand="microsoft" title="Microsoft" color="#666666" />
          </Flex>
        </Flex>
        <Flex direction="column" gap="md">
          <Text variant="small" weight="600">Red Override (#E53E3E):</Text>
          <Flex direction="row" gap="sm" wrap="wrap">
            <BrandButton brand="google" title="Google" color="#E53E3E" />
            <BrandButton brand="github" title="GitHub" color="#E53E3E" />
            <BrandButton brand="spotify" title="Spotify" color="#E53E3E" />
            <BrandButton brand="microsoft" title="Microsoft" color="#E53E3E" />
          </Flex>
        </Flex>
        <Flex direction="column" gap="md">
          <Text variant="small" weight="600">Outline Variant with Color Override:</Text>
          <Flex direction="row" gap="sm" wrap="wrap">
            <BrandButton brand="google" title="Google" variant="outline" color="#8B5CF6" />
            <BrandButton brand="github" title="GitHub" variant="outline" color="#8B5CF6" />
            <BrandButton brand="spotify" title="Spotify" variant="outline" color="#8B5CF6" />
            <BrandButton brand="microsoft" title="Microsoft" variant="outline" color="#8B5CF6" />
          </Flex>
        </Flex>
      </Flex>
  );
}
```

### Universal Props Demo
ID: `BrandButton.universalProps` • Tags: basic, getting-started • Category: basics • Status: stable • Since: 1.0.0

These components demonstrate universal props like `lightHidden` and `darkHidden` that work across the entire library. Toggle dark/light mode or resize the window.

```tsx
return (
    <Block>
      <Flex direction="column" gap="md">
        <Text variant="small" weight="600">Light Mode Only (darkHidden):</Text>
        <Flex direction="row" gap="sm" wrap="wrap">
          <BrandButton brand="google" title="Google" darkHidden />
          <BrandButton brand="github" title="GitHub" darkHidden />
        </Flex>
      </Flex>
      <Flex direction="column" gap="md">
        <Text variant="small" weight="600">Dark Mode Only (lightHidden):</Text>
        <Flex direction="row" gap="sm" wrap="wrap">
          <BrandButton brand="spotify" title="Spotify (Dark Only)" lightHidden />
          <BrandButton brand="microsoft" title="Microsoft (Dark Only)" lightHidden />
        </Flex>
      </Flex>
      <Flex direction="column" gap="md">
        <Text variant="small" weight="600">Responsive Visibility:</Text>
        <Flex direction="row" gap="sm" wrap="wrap">
          <BrandButton brand="apple" title="Hidden on Large+" hiddenFrom={1024} />
          <BrandButton brand="amazon" title="Visible on Medium+" visibleFrom={768} />
        </Flex>
      </Flex>
      <Flex direction="column" gap="md">
        <Text variant="small" weight="600">Combined Props:</Text>
        <Flex direction="row" gap="sm" wrap="wrap">
          <BrandButton
            brand="discord"
            title="Dark + Large Screen Only"
            lightHidden
            visibleFrom={1024}
          />
        </Flex>
      </Flex>
    </Block>
  );
}
```

### Store badges
ID: `BrandButton.badge` • Tags: badge, app-store, store • Category: basics • Status: stable • Since: 1.0.0

Supplying `primaryText` and `secondaryText` switches BrandButton from the single-line button to the two-line store-badge layout. Any brand in the icon registry works, and the shell defaults to black until `backgroundColor` says otherwise.

```tsx
const toast = useToast();
  const announce = (store: string) =>
    toast.info({
      title: `${store} pressed`,
      message: `Wire onPress up to Linking.openURL with your ${store} listing.`,
      autoHide: 3000,
    });
  return (
    <Row gap="md" wrap="wrap" justify="center" align="center">
      {/* Passing primaryText/secondaryText switches BrandButton to the badge layout. */}
      <BrandButton
        brand="app-store"
        primaryText="Download on the"
        secondaryText="App Store"
        onPress={() => announce('App Store')}
      />
      <BrandButton
        brand="google-play"
        primaryText="Get it on"
        secondaryText="Google Play"
        onPress={() => announce('Google Play')}
      />
      {/* Badges default to a black shell whatever the brand — `backgroundColor` opts one out. */}
      <BrandButton
        brand="spotify"
        primaryText="Listen on"
        secondaryText="Spotify"
        backgroundColor="#1DB954"
        onPress={() => announce('Spotify')}
      />
    </Row>
  );
}
```

### Badge sizes
ID: `BrandButton.badgeSizes` • Tags: badge, size • Category: basics • Status: stable • Since: 1.0.0

Every badge metric — padding, icon, radius, height — is derived from the size token's headline type, so the proportions hold from `xs` through `3xl`.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Row gap="lg" wrap="wrap" align="flex-end">
      {SIZES.map((size) => (
        <Block key={size} align="center" gap="xs">
          <BrandButton
            brand="app-store"
            primaryText="Download on the"
            secondaryText="App Store"
            size={size}
          />
          <Text variant="small" color="secondary">
            {size}
          </Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Badge colors
ID: `BrandButton.badgeColors` • Tags: badge, color, theming • Category: basics • Status: stable • Since: 1.0.0

Override the badge shell with `backgroundColor`, `textColor`, and `borderColor` to match your brand or design requirements.

```tsx
return (
    <Block direction="row">
      <BrandButton
        brand="github"
        primaryText="View on"
        secondaryText="GitHub"
        backgroundColor="#ffffff"
        textColor="#24292e"
        borderColor="#24292e"
        onPress={() => console.log('GitHub light pressed')}
      />
      <BrandButton
        brand="spotify"
        primaryText="Listen on"
        secondaryText="Spotify"
        backgroundColor="#191414"
        textColor="#1DB954"
        borderColor="#1DB954"
        onPress={() => console.log('Spotify custom pressed')}
      />
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/BrandIcon.md -->

# BrandIcon

Common brand logos rendered as SVG

## Metadata

- Canonical name: `BrandIcon`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { BrandIcon } from '@platform-blocks/react-ui-library';`
- Category: typography
- Tags: action, pressable, interactive
- Docs: https://react-ui-library.com/components/BrandIcon
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/BrandIcon

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `brand` | BrandName | Yes |  | Brand name from the registry. camelCase names are deprecated aliases. |
| `size` | SizeValue | No |  | Size of the icon |
| `color` | string | No |  | Override all colors with a single color |
| `variant` | 'full' \| 'mono' | No |  | Icon variant - 'full' for multi-color, 'mono' for single-color with clipping |
| `style` | StyleProp<ViewStyle> | No |  | Additional styles |
| `label` | string | No |  | Accessibility label |
| `decorative` | boolean | No |  | Whether the icon is purely decorative (skip a11y) |
| `invertInDarkMode` | boolean | No |  | Whether to automatically invert black colors in dark mode |
| `colorScheme` | 'light' \| 'dark' | No |  | Force color scheme for testing (overrides automatic detection) |

## Examples

### Overview
ID: `BrandIcon.basic` • Tags: overview, gallery • Category: basics • Status: stable • Since: 0.3.0

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

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

### Colors & Mono
ID: `BrandIcon.colors` • Tags: colors, branding, mono, custom-colors • Category: theming • Status: stable • Since: 0.3.0

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

```tsx
return (
    <Block>
      <Block>
        <Text variant="small" color="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" color="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" color="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>
  );
}
```

### Sizes
ID: `BrandIcon.sizes` • Tags: sizes, layout • Category: layout • Status: stable • Since: 0.3.0

Size presets from small through extra large for consistent placement.

```tsx
const SIZES: BrandIconProps['size'][] = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'];
  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
ID: `BrandIcon.dark-mode` • Tags: dark-mode, accessibility • Category: theming • Status: stable • Since: 0.3.0

Supported logos automatically invert for dark themes.

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

### All Available Brands
ID: `BrandIcon.all-brands` • Tags: catalog, brands • Category: reference • Status: stable • Since: 0.3.0

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
return (
    <Grid columns={{ base: 3, sm: 4, md: 6, lg: 8 }} gap="md" fullWidth>
      {ALL_BRANDS.map((brand) => (
        <GridItem key={brand} span={1}>
          <Block align="center">
            <BrandIcon brand={brand} size={36} />
            <Text align="center" size={10}>
              {brand}
            </Text>
          </Block>
        </GridItem>
      ))}
    </Grid>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Breadcrumbs.md -->

# Breadcrumbs

The Breadcrumbs component displays hierarchical navigation links to help users understand their current location within the application. Item labels and string separators each accept the full `<Text>` API via `labelProps` / `separatorProps`.

## Metadata

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

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | BreadcrumbItem[] | Yes |  | Array of breadcrumb items |
| `separator` | ReactNode | No | '/' | Custom separator between breadcrumbs (string, icon, or any React component) |
| `maxItems` | number | No |  | Maximum number of items to show (will collapse middle items) |
| `size` | ComponentSizeValue | No | 'md' | Size of the breadcrumbs |
| `showIcons` | boolean | No | true | Whether to show icons |
| `style` | StyleProp<ViewStyle> | No |  | Custom styles |
| `textStyle` | StyleProp<TextStyle> | No |  | Custom text styles |
| `separatorStyle` | StyleProp<ViewStyle> | No |  | Custom separator styles |
| `accessibilityLabel` | string | No | 'Breadcrumb navigation' | Accessibility label |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to each item's label `<Text>` (style, weight, ff, size, color). |
| `separatorProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the separator `<Text>` when it's a string. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Hierarchy
ID: `Breadcrumbs.basic` • Tags: breadcrumbs • Category: navigation • Status: stable • Since: 1.0.0

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

```tsx
const ITEMS = [
  { label: 'Home', href: '/' },
  { label: 'Products', href: '/products' },
  { label: 'Electronics', href: '/products/electronics' },
  { label: 'Smartphones' },
];
  return <Breadcrumbs items={ITEMS} />;
}
```

### Separators
ID: `Breadcrumbs.separators` • Tags: breadcrumbs • Category: navigation • Status: stable • Since: 1.0.0

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

```tsx
const ITEMS = [
  { label: 'Home', href: '/' },
  { label: 'Category', href: '/category' },
  { label: 'Subcategory', href: '/category/subcategory' },
  { label: 'Product' },
];
  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://react-ui-library.com/llms/components/Button.md -->

# Button

The Button component provides a flexible interactive element supporting variants, sizes, icons, loading state, and full-width layout. The inner label `<Text>` accepts the full Text-prop API via `labelProps` (`ff`, `weight`, `tracking`, `uppercase`, `color`, `style`).

Buttons default to the `default` variant — a neutral button (card surface, hairline border, body text) that sizes to its content. Reach for `variant="filled"` on the primary action of a view, and `fullWidth` (or `w`) when the button should span its container.

## Metadata

- Canonical name: `Button`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Button } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: action, pressable, interactive
- Docs: https://react-ui-library.com/components/Button
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Button

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `key` | React.Key | No |  | allow React key without complaint in TS where JSX key is forwarded in type checking |
| `title` | string | No |  | Button text content - can be provided via title prop or children |
| `children` | React.ReactNode | No |  | Button text content - alternative to title prop |
| `onPress` | () => void | No |  | Called when the button is pressed |
| `onPressIn` | () => void | No |  | Called when the button press starts (for immediate feedback) |
| `onPressOut` | () => void | No |  | Called when the button press ends |
| `onHoverIn` | () => void | No |  | Called when the button is hovered (web/desktop only) |
| `onHoverOut` | () => void | No |  | Called when the button is no longer hovered (web/desktop only) |
| `onLongPress` | () => void | No |  | Called when the button is long-pressed |
| `onLayout` | (event: any) => void | No |  | Called when the button layout is calculated |
| `variant` | 'default' \| 'filled' \| 'light' \| 'subtle' \| 'secondary' \| 'outline' \| 'ghost' \| 'gradient' \| 'link' \| 'none' | No | 'default' | Button visual variant. `default` is a neutral button — the card surface with a hairline border and body text — so an unstyled `<Button>` never claims the accent color. A solid primary fill is opt-in via `filled`. |
| `color` | string | No |  | Theme color the button is tinted with. A palette token (`primary`, `success`, `error`, …) 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 | No |  | Button size |
| `disabled` | boolean | No |  | Whether the button is disabled |
| `loading` | boolean | No |  | Whether button is in loading state (shows loader) |
| `loadingTitle` | string | No |  | Text to show when loading (if not provided, shows empty text but maintains original width) |
| `fullWidth` | boolean | No |  | 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` | string | No |  | Explicit text color override (else derived automatically from variant & color) |
| `icon` | React.ReactNode | No |  | Icon to show in the center (for icon-only buttons) |
| `startIcon` | React.ReactNode | No |  | Icon to show on the left side of the button |
| `endIcon` | React.ReactNode | No |  | Icon to show on the right side of the button |
| `tooltip` | TooltipPropValue | No |  | 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…', maxWidth: 320, withArrow: true }}`. |
| `tooltipPosition` | TooltipProps['position'] | No |  | Tooltip position when the string form of `tooltip` is used |
| `transitionDuration` | number | No | 110 | Length of the press / pulse / hover transitions in ms. `0` applies each state instantly (no scale animation). Always 0 under reduced motion. |
| `style` | any | No |  | Style overrides for the button container |
| `testID` | string | No |  | Test ID for testing library queries |
| `accessibilityLabel` | string | No |  | Accessibility label for screen readers |
| `accessibilityHint` | string | No |  | Accessibility hint for screen readers |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the inner label `<Text>` (style, weight, ff, size, color). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |
| `shadow` | ShadowValue | No |  | Shadow value - supports size tokens and 'none' |

## Examples

### Basics
ID: `Button.basic` • Tags: buttons • Category: basics • Status: stable • Since: 1.0.0

Invokes a primary action and surfaces feedback through a toast helper.

```tsx
const toast = useToast();
  return (
    <Block align="flex-start">
      <Button
        title="Launch mission"
        onPress={() => toast.success('Launch command sent')}
      />
      <Button
        title="Abort"
        onPress={() => toast.error('Sequence aborted')}
      />
    </Block>
  );
}
```

### Colors
ID: `Button.colors` • Tags: buttons, colors • Category: styling • Status: stable • Since: 1.0.0

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
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
ID: `Button.loading` • Tags: buttons, loading • Category: feedback • Status: stable • Since: 1.0.0

Demonstrates consistent width preservation, custom `loadingTitle`, and disabling actions while background work completes.

```tsx
const LOADING_DURATION_MS = 2000;
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const [activeKey, setActiveKey] = useState<string | null>(null);
  useEffect(() => () => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
  }, []);
  const triggerLoading = (key: string) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setActiveKey(key);
    timeoutRef.current = setTimeout(() => {
      setActiveKey(null);
      timeoutRef.current = null;
    }, LOADING_DURATION_MS);
  };
  return (
    <Row gap="md" wrap="wrap" align="flex-start">
      <Button loading={activeKey === 'default'} onPress={() => triggerLoading('default')}>
        Submit application
      </Button>
      <Button
        loading={activeKey === 'custom'}
        loadingTitle="Submitting…"
        onPress={() => triggerLoading('custom')}
      >
        Submit application
      </Button>
      <Button
        loading={activeKey === 'disabled'}
        disabled={activeKey === 'disabled'}
        loadingTitle="Loading"
        onPress={() => triggerLoading('disabled')}
      >
        Submit application
      </Button>
    </Row>
  );
}
```

### Variants
ID: `Button.variants` • Tags: buttons, variants • Category: styling • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Button.sizes` • Tags: buttons, sizes • Category: styling • Status: stable • Since: 1.0.0

Preview the available button size tokens for different density requirements.

```tsx
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
ID: `Button.localized-basic` • Tags: buttons, i18n • Category: accessibility • Status: stable • Since: 1.0.0

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

```tsx
const LOCALES = [
  { label: 'English', value: 'en' },
  { label: 'Español', value: 'es' },
  { label: 'Français', value: 'fr' },
];
  const { t, locale, setLocale } = useI18n();
  return (
    <Flex>
      <Select
        options={LOCALES}
        value={locale}
        onChange={(value) => { if (value) setLocale(value); }}
      />
      <Button
        title={t('button.demo.submit')}
        w={200}
      />
    </Flex>
  );
}
```

### Tooltips
ID: `Button.tooltip` • Tags: buttons, tooltip • Category: behavior • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Block>
      <Row gap="md" wrap="wrap" align="flex-start">
        <Button tooltip="Save your current work.">Save</Button>
        <Button
          variant="outline"
          tooltip="Permanently delete this item."
          tooltipPosition="bottom"
        >
          Delete
        </Button>
        <Button
          variant="ghost"
          tooltip="Get help and support resources."
          tooltipPosition="right"
        >
          Help
        </Button>
      </Row>
      <Row gap="md" wrap="wrap" align="flex-start">
        <Button tooltip="Download the file to your device." tooltipPosition="left">
          Download
        </Button>
        <Button icon={<Icon name="settings" />} tooltip="Open the settings panel." accessibilityLabel="Open settings" />
        <Button disabled tooltip="Feature not available in demo mode.">
          Upload
        </Button>
      </Row>
    </Block>
  );
}
```

### Width
ID: `Button.width` • Tags: buttons, layout • Category: layout • Status: stable • Since: 1.0.0

Demonstrates fixed, percentage, and full-width buttons alongside loading states that preserve dimensions.

```tsx
const LOADING_DURATION_MS = 2000;
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const [loadingKey, setLoadingKey] = useState<string | null>(null);
  useEffect(() => () => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
  }, []);
  const triggerLoading = (key: string) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setLoadingKey(key);
    timeoutRef.current = setTimeout(() => {
      setLoadingKey(null);
      timeoutRef.current = null;
    }, LOADING_DURATION_MS);
  };
  return (
    <Block>
      <Block>
        <Block>
          <Button>Default width</Button>
          <Text variant="small" color="muted">
            Buttons size themselves to the label length by default.
          </Text>
        </Block>
        <Block>
          <Button w={200}>Fixed width (200)</Button>
          <Text variant="small" color="muted">
            Provide an exact `w` value for pixel-perfect toolbars.
          </Text>
        </Block>
      </Block>
      <Block>
        <Row gap="md" wrap="wrap" align="flex-start">
          <Button
            loading={loadingKey === 'long'}
            loadingTitle="Loading…"
            onPress={() => triggerLoading('long')}
          >
            Preserve width while loading
          </Button>
          <Button loading={loadingKey === 'short'} onPress={() => triggerLoading('short')}>
            Short text
          </Button>
        </Row>
        <Text variant="small" color="muted">
          When `loading` is true, the button keeps its original width so layouts stay stable.
        </Text>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Calendar.md -->

# Calendar

A versatile calendar component for selecting dates, months, and years with customizable styles and behaviors.

## Metadata

- Canonical name: `Calendar`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Calendar } from '@platform-blocks/react-ui-library';`
- Category: dates
- Docs: https://react-ui-library.com/components/Calendar
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Calendar

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `level` | CalendarLevel | No |  | View control |
| `defaultLevel` | CalendarLevel | No | 'month' |  |
| `onLevelChange` | (level: CalendarLevel) => void | No |  |  |
| `date` | Date | No |  | Date management |
| `defaultDate` | Date | No |  |  |
| `onDateChange` | (date: Date) => void | No |  |  |
| `value` | CalendarValue | No |  | Value handling (for selection) |
| `onChange` | (value: CalendarValue) => void | No |  |  |
| `type` | CalendarType | No | 'single' |  |
| `minDate` | Date | No |  | Constraints |
| `maxDate` | Date | No |  |  |
| `excludeDate` | (date: Date) => boolean | No |  |  |
| `locale` | string | No |  | Localization |
| `firstDayOfWeek` | 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 | No | 0 |  |
| `weekendDays` | number[] | No | [0, 6] |  |
| `withCellSpacing` | boolean | No |  | Display options |
| `hideOutsideDates` | boolean | No | false |  |
| `hideWeekdays` | boolean | No | false |  |
| `highlightToday` | boolean | No | true |  |
| `numberOfMonths` | number | No | 1 |  |
| `getDayProps` | (date: Date) => Partial<DayProps> | No |  | Customization |
| `renderDay` | (date: Date) => React.ReactNode | No |  |  |
| `size` | SizeValue | No | 'md' |  |
| `fullWidth` | boolean | No | false | Stretch to fill the container instead of sizing to the day grid. Default `false`. |
| `static` | boolean | No |  | Static mode (non-interactive) |

## Examples

### Basic selection
ID: `Calendar.basic` • Tags: single, selection • Category: basics • Status: stable • Since: 0.3.0

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

```tsx
const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });
  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" color="secondary">
        Selected date: {selectedDate ? formatter.format(selectedDate) : 'none'}
      </Text>
    </Block>
  );
}
```

### Date constraints
ID: `Calendar.constrained` • Tags: min-date, max-date • Category: rules • Status: stable • Since: 0.3.0

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

```tsx
const monthFormatter = new Intl.DateTimeFormat('en-US', { month: 'long', year: 'numeric' });
const dateFormatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });
  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" color="secondary">
        Selected date: {selectedDate ? dateFormatter.format(selectedDate) : 'none'}
      </Text>
      <Text size="xs" color="secondary">
        Only dates in {monthLabel} are enabled.
      </Text>
    </Block>
  );
}
```

### Multiple selection
ID: `Calendar.multiple` • Tags: multiple, events • Category: selection • Status: stable • Since: 0.3.0

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
const formatter = new Intl.DateTimeFormat('en-US', { month: 'short', day: 'numeric' });
  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" color="secondary">
        {summary}
      </Text>
    </Block>
  );
}
```

### Range selection
ID: `Calendar.range` • Tags: range, bookings • Category: selection • Status: stable • Since: 0.3.0

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
const formatter = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium' });
  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" color="secondary">
        {summary}
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Card.md -->

# Card

The Card component provides a flexible container for displaying content. Six variants (`filled`, `outline`, `elevated`, `subtle`, `ghost`, `gradient`) each set their own background + default shadow. `withBorder`, `borderColor`, `borderWidth`, and `bg` compose on top of any variant, so you can mix and match (`<Card variant="elevated" withBorder bg="primary" />`) without forking a new variant for every combination.

## Metadata

- Canonical name: `Card`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Card } from '@platform-blocks/react-ui-library';`
- Category: display
- Tags: card, container, content, layout
- Docs: https://react-ui-library.com/components/Card
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Card

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | No |  | children optional to reduce noisy TS errors during composition |
| `variant` | 'outline' \| 'filled' \| 'elevated' \| 'subtle' \| 'ghost' \| 'gradient' | No |  | 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 | No |  | Add a 1px border on top of *any* variant. Composes with `variant="elevated"` etc. without forcing you into the `outline` variant. |
| `borderColor` | string | No |  | Custom border color. When set, implies `withBorder` if `borderWidth` isn't 0. |
| `borderWidth` | number | No |  | Custom border width in px. Defaults to 1 when `withBorder` or `borderColor` is set. |
| `clip` | boolean | No |  | 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. |
| `bg` | string | No |  | Background color override. Accepts any CSS color string or a theme color palette name (`'primary' \| 'secondary' \| 'gray' \| 'success' \| 'warning' \| 'error'`), which resolves to that palette's shade-1 (subtle tint). |
| `padding` | SizeValue | No |  | Internal padding. Accepts a size token (`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`) or a pixel number. |
| `style` | any | No |  |  |
| `onPress` | () => void | No |  | Interactive props |
| `disabled` | boolean | No |  |  |
| `onContextMenu` | (e: any) => void | No |  | Web-only events passthrough |
| `testID` | string | No |  |  |
| `accessibilityRole` | AccessibilityRole | No |  | Accessibility role forwarded to the underlying element. Pressable cards default to a button; set `'link'` when the card navigates. |
| `accessibilityLabel` | string | No |  | Accessibility label forwarded to the underlying element. |
| `accessibilityState` | AccessibilityState | No |  | Accessibility state forwarded to the underlying element. Required for the selectable roles — a card with `accessibilityRole="radio"` or `"checkbox"` has to announce its `checked` state or screen readers read every option as unselected. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |
| `shadow` | ShadowValue | No |  | Shadow value - supports size tokens and 'none' |

## Examples

### Basics
ID: `Card.basic` • Tags: content • Category: basics • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Card p="lg" radius="lg" shadow="md" maxW={320}>
      <Block>
        <Block>
          <Text variant="small" color="muted">
            Upcoming match
          </Text>
          <Text variant="h6">Falcons at Bears</Text>
        </Block>
        <Text color="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" onPress={() => {}}>
          View itinerary
        </Button>
      </Block>
    </Card>
  );
}
```

### Variants
ID: `Card.variants` • Tags: surface • Category: theming • Status: stable • Since: 1.0.0

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

```tsx
const VARIANTS = ['filled', 'outline', 'elevated', 'subtle', 'ghost', 'gradient'] as const;
  return (
    <Block>
      {VARIANTS.map((variant) => (
        <Card key={variant} variant={variant} p="lg" radius="lg">
          <Block>
            <Text variant="small" color="muted">
              {String(variant).toUpperCase()} variant
            </Text>
            <Text color="muted">
              Apply the {variant} treatment to match surface contrast needs.
            </Text>
          </Block>
        </Card>
      ))}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Carousel`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Carousel } from '@platform-blocks/react-ui-library';`
- Category: display
- Tags: carousel, slider, gallery, swipe
- Docs: https://react-ui-library.com/components/Carousel
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Carousel

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode[] | Yes |  | Array of carousel slide elements |
| `orientation` | 'horizontal' \| 'vertical' | No |  | Orientation of the carousel |
| `showArrows` | boolean | No |  | Show navigation arrow buttons |
| `showDots` | boolean | No |  | Show navigation dots |
| `autoPlay` | boolean | No |  | Enable autoplay |
| `autoPlayInterval` | number | No |  | Autoplay interval in ms |
| `autoPlayPauseOnTouch` | boolean | No |  | Pause autoplay on user interaction |
| `loop` | boolean | No |  | Enable looping |
| `itemsPerPage` | number | No |  | Number of visible items per page |
| `slidesToScroll` | number | No |  | Number of slides to advance per snap (defaults to itemsPerPage for backwards compatibility) |
| `align` | 'start' \| 'center' \| 'end' | No |  | Align the visible slides within the viewport when there is extra space |
| `containScroll` | false \| 'trimSnaps' \| 'keepSnaps' | No |  | Contain leading/trailing space by trimming or keeping snap points |
| `startIndex` | number | No |  | Initial slide index to show on mount |
| `dragFree` | boolean | No |  | Allow momentum scrolling without forced snaps |
| `skipSnaps` | boolean | No |  | Permit gestures to skip over multiple snap points (default true) |
| `dragThreshold` | number | No |  | Drag distance (in px) required before a swipe is committed |
| `duration` | number | No |  | Duration (ms) for programmatic scroll animations |
| `transitionDuration` | number | No |  | 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>> | No |  | 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; } | No |  | 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 | No |  | Responsive gap between slides (overrides itemGap). Accepts spacing token string or number or responsive map. |
| `itemGap` | number | No |  | Gap between slides in pixels |
| `height` | number | No |  | Fixed height of the carousel container |
| `onSlideChange` | (index: number) => void | No |  | Callback fired when the active slide changes |
| `style` | StyleProp<ViewStyle> | No |  | Style override for the carousel container |
| `itemStyle` | StyleProp<ViewStyle> | No |  | Style override applied to each slide item |
| `snapToItem` | boolean | No |  | Enable snapping to individual items |
| `arrowPosition` | 'inside' \| 'outside' | No |  | Position of navigation arrows relative to the carousel |
| `arrowSize` | ComponentSizeValue | No |  | Size of the navigation arrow buttons |
| `dotSize` | ComponentSizeValue | No |  | Size of the navigation dots |
| `scrollEnabled` | boolean | No |  | Enable or disable scroll gestures |
| `reducedMotion` | boolean | No |  | Disable animated width/color transitions for dots and snapping |
| `windowSize` | number | No |  | Number of logical pages to render for virtualization |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic usage
ID: `Carousel.basic` • Tags: auto-play, loop • Category: basics • Status: stable • Since: 0.3.0

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

```tsx
const slides = ['#4C1D95', '#155E75', '#166534'];
  return (
    <Carousel height={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" color="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Vertical orientation
ID: `Carousel.vertical` • Tags: vertical, navigation • Category: layout • Status: stable • Since: 0.3.0

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 height.

```tsx
const slides = ['#DC2626', '#2563EB', '#0F766E'];
  return (
    <Carousel
      orientation="vertical"
      style={{ height: 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" color="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Image overlay
ID: `Carousel.imageOverlay` • Tags: hero, overlay • Category: media • Status: stable • Since: 0.3.0

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

```tsx
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') },
];
  return (
    <Carousel height={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" color="white">
              {title}
            </Text>
          </Block>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Multiple slides
ID: `Carousel.multi` • Tags: responsive, items-per-page • Category: layout • Status: stable • Since: 0.3.0

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
const slides = ['#1D4ED8', '#0F766E', '#C026D3', '#B45309', '#7C3AED'];
  return (
    <Carousel
      height={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" color="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Performance tuning
ID: `Carousel.performance` • Tags: virtualization, reduced-motion • Category: performance • Status: stable • Since: 0.3.0

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

```tsx
const slides = ['#1E3A8A', '#047857', '#9333EA', '#B91C1C', '#B45309', '#0F766E'];
  return (
    <Carousel height={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" color="white">
            Slide {index + 1}
          </Text>
        </Block>
      ))}
    </Carousel>
  );
}
```

### Drag & motion
ID: `Carousel.motionControls` • Tags: drag-free, motion • Category: behavior • Status: stable • Since: 0.4.0

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

```tsx
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" color="white">
        Slide {index + 1}
      </Text>
    </Block>
  ));
}
  return (
    <Block fullWidth gap="lg">
      <Text variant="h5">Free momentum (dragFree)</Text>
      <Carousel height={160} dragFree itemsPerPage={2} slideGap={12}>
        {slides(['#0EA5E9', '#6366F1', '#8B5CF6', '#A855F7'])}
      </Carousel>
      <Text variant="h5">Locked snaps (skipSnaps off)</Text>
      <Carousel
        height={160}
        itemsPerPage={2}
        slidesToScroll={1}
        skipSnaps={false}
        dragThreshold={45}
        duration={650}
        slideGap={12}
      >
        {slides(['#F97316', '#EA580C', '#C2410C', '#9A3412'])}
      </Carousel>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Checkbox.md -->

# Checkbox

The Checkbox component allows users to select one or more options from a set. Supports different states, colors, and group functionality.

## Metadata

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

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checked` | boolean | No |  | Whether checkbox is checked |
| `defaultChecked` | boolean | No | false | Initial checked value for uncontrolled usage |
| `onChange` | (checked: boolean) => void | No |  | Change handler |
| `indeterminate` | boolean | No | false | Indeterminate state for partial selections |
| `color` | string | No |  | Indicator color. A palette token (`'success'`), `'primary.6'` shade syntax, or any CSS color. |
| `size` | SizeValue | No | 'md' | Checkbox size |
| `label` | React.ReactNode | No |  | Checkbox label |
| `disabled` | boolean | No | false | Whether checkbox is disabled |
| `required` | boolean | No | false | Whether checkbox is required |
| `error` | string | No |  | Error message |
| `description` | string | No |  | Helper text |
| `icon` | React.ReactNode | No |  | Icon to show when checked |
| `indeterminateIcon` | React.ReactNode | No |  | Icon to show when indeterminate |
| `labelPosition` | 'left' \| 'right' \| 'top' \| 'bottom' | No | 'right' | Label position relative to checkbox |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override styles/props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override styles/props applied to the description `<Text>` |
| `transitionDuration` | number | No | 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 | No |  | Checkbox content/children (alternative to label) |
| `accessibilityLabel` | string | No |  | Accessibility label, used when there is no visible text label |
| `testID` | string | No |  | Component test ID for testing |
| `style` | any | No |  | Additional CSS styles |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `Checkbox.basic` • Tags: checkboxes • Category: basics • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Checkbox.sizes` • Tags: checkboxes, sizes • Category: styling • Status: stable • Since: 1.0.0

Explore available checkbox sizes with guidance on where each fits best.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Checkbox size={size} defaultChecked />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Colors
ID: `Checkbox.colors` • Tags: checkboxes, colors • Category: styling • Status: stable • Since: 1.0.0

Toggle checkboxes styled with semantic `color` options and a default-checked example.

```tsx
const COLORS = ['primary', 'secondary', 'success', 'warning', 'error'] as const;
  const [values, setValues] = useState<Record<string, boolean>>({});
  const toggle = (color: string) => {
    setValues((current) => ({
      ...current,
      [color]: !current[color]
    }));
  };
  return (
    <Block>
      <Text weight="medium">Semantic colors</Text>
      <Block>
        {COLORS.map((color) => (
          <Checkbox
            key={color}
            color={color}
            label={`Color: ${color}`}
            checked={Boolean(values[color])}
            onChange={() => toggle(color)}
          />
        ))}
      </Block>
      <Checkbox
        color="success"
        label="Default checked"
        defaultChecked
      />
      <Text variant="small" color="muted">
        Use `color` to match checkbox accents with message intent while keeping labels readable.
      </Text>
    </Block>
  );
}
```

### States
ID: `Checkbox.states` • Tags: checkboxes, states • Category: behavior • Status: stable • Since: 1.0.0

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

```tsx
const [enabled, setEnabled] = useState(true);
  const [required, setRequired] = useState(true);
  const [withError, setWithError] = useState(false);
  return (
    <Block>
      <Checkbox label="Enabled" checked={enabled} onChange={setEnabled} />
      <Checkbox label="Disabled" checked={false} disabled />
      <Checkbox label="Required" required checked={required} onChange={setRequired} />
      <Checkbox
        label="With error"
        error={withError ? 'Selection required' : undefined}
        checked={withError}
        onChange={setWithError}
      />
    </Block>
  );
}
```

### Indeterminate
ID: `Checkbox.indeterminate` • Tags: checkboxes, indeterminate • Category: interaction • Status: stable • Since: 1.0.0

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

```tsx
const [selected, setSelected] = useState<number[]>([]);
  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 (${selected.length}/${ITEMS.length})`}
        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
ID: `Checkbox.withDescription` • Tags: checkboxes, helper-text • Category: usage • Status: stable • Since: 1.0.0

Descriptions and helper text

```tsx
const [newsletter, setNewsletter] = useState(false);
  const [termsAccepted, setTermsAccepted] = useState(false);
  return (
    <Block style={{ maxWidth: 400 }}>
      <Checkbox
        label="Receive product updates"
        description="Get occasional emails about new features and improvements."
        checked={newsletter}
        onChange={setNewsletter}
      />
      <Checkbox
        label="Accept terms of service"
        description="Required before creating an account."
        error={termsAccepted ? undefined : 'Please accept to continue.'}
        checked={termsAccepted}
        onChange={setTermsAccepted}
        required
      />
      <Text variant="small" color="muted">
        Use `description` for supporting copy and pair with `error` to surface validation details.
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Chip.md -->

# Chip

The Chip component displays compact elements that represent an input, attribute, or action. Supports different colors, sizes, and interactive features like removal. Inner label accepts the full Text-prop API via `labelProps`.

## Metadata

- Canonical name: `Chip`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Chip } from '@platform-blocks/react-ui-library';`
- Category: data
- Tags: chip, tag, badge, label, removable
- Docs: https://react-ui-library.com/components/Chip
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Chip

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | Yes |  |  |
| `size` | SizeValue | No |  |  |
| `variant` | 'filled' \| 'outline' \| 'light' \| 'subtle' \| 'surface' \| 'gradient' | No |  | Visual style. `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` | ThemeColor | No |  | Theme palette name or CSS color. Not used by the `surface` variant. |
| `onPress` | () => void | No |  |  |
| `dot` | boolean | No |  | Show a small leading status dot. Defaults to the chip's resolved text color. |
| `dotColor` | string | No |  | Override the dot color (any CSS/theme color string). Only used when `dot` is set. |
| `startIcon` | React.ReactNode | No |  |  |
| `endIcon` | React.ReactNode | No |  |  |
| `onRemove` | () => void | No |  |  |
| `removePosition` | 'left' \| 'right' | No |  |  |
| `disabled` | boolean | No |  |  |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `textStyle` | StyleProp<TextStyle> | No |  |  |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the inner label `<Text>` (style, weight, ff, size, color). |
| `radius` | any | No |  |  |
| `shadow` | any | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `Chip.basic` • Tags: chip, getting-started • Category: basics • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Row gap={8} wrap="wrap">
      <Chip>Design</Chip>
      <Chip>Engineering</Chip>
      <Chip>Research</Chip>
    </Row>
  )
}
```

### Semantic colors
ID: `Chip.colors` • Tags: colors, theming • Category: theming • Status: stable • Since: 1.0.0

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
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
ID: `Chip.sizes` • Tags: sizes, density • Category: layout • Status: stable • Since: 1.0.0

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

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  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
ID: `Chip.variants` • Tags: variants, styling • Category: appearance • Status: stable • Since: 1.0.0

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
return (
    <Row gap={8} wrap="wrap">
      <Chip variant="filled" color="primary">
        Filled
      </Chip>
      <Chip variant="outline" color="primary">
        Outline
      </Chip>
      <Chip variant="light" color="primary">
        Light
      </Chip>
      <Chip variant="subtle" color="primary">
        Subtle
      </Chip>
      <Chip variant="surface">
        Surface
      </Chip>
      <Chip variant="gradient" color="primary">
        Gradient
      </Chip>
    </Row>
  )
}
```

### Status dot
ID: `Chip.dot` • Tags: dot, status, indicator • Category: appearance • Status: stable • Since: 1.0.0

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

```tsx
return (
    <Block fullWidth={false}>
      <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>
      <Text size="xs" color="muted">
        Use <Text size="xs" weight="600">dot</Text> to toggle the indicator and{' '}
        <Text size="xs" weight="600">dotColor</Text> to set a custom color.
      </Text>
    </Block>
  )
}
```

### Shadow depth
ID: `Chip.shadow` • Tags: shadow, emphasis • Category: appearance • Status: stable • Since: 1.0.0

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

```tsx
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
ID: `Chip.interactive` • Tags: interactive, removable • Category: interactions • Status: stable • Since: 1.0.0

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
const initialSports = [
  { label: 'Soccer', emoji: '⚽' },
  { label: 'Basketball', emoji: '🏀' },
  { label: 'Tennis', emoji: '🎾' },
]
  const [chips, setChips] = useState(initialSports)
  const handleRemove = (chipToRemove: string) => {
    setChips((current) => current.filter((chip) => chip.label !== chipToRemove))
  }
  return (
    <Block>
      {chips.map((chip) => (
        <Chip
          key={chip.label}
          onRemove={() => handleRemove(chip.label)}
        >
          {chip.label}
        </Chip>
      ))}
    </Block>
  )
}
```

### Theme Matrix
ID: `Chip.theme-matrix` • Category: general

```tsx
const VARIANTS: NonNullable<ChipProps['variant']>[] = [
  'filled',
  'outline',
  'light',
  'subtle',
  'gradient',
]
// Core palette colors plus one raw custom color, to prove the resolver works for both.
const ROWS: { color: string; label: string }[] = [
  { 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
// A single chip with a leading status dot. The dot defaults to the chip's own
// resolved text color, so the indicator stays legible across every variant +
// scheme without any per-cell color plumbing.
function ChipCell({ variant, color, label }: { variant: NonNullable<ChipProps['variant']>; color: string; label: string }) {
  return (
    <Row justify="center" style={{ width: CELL_W }}>
      <Chip variant={variant} color={color} size="sm" dot>
        {label}
      </Chip>
    </Row>
  )
}
function Matrix() {
  return (
    <Block fullWidth={false}>
      {/* Column headers */}
      <Row gap="xs" align="center">
        <Text style={{ width: LABEL_W }}> </Text>
        {VARIANTS.map((v) => (
          <Text
            key={v}
            size="xs"
            color="muted"
            align="center"
            style={{ width: CELL_W }}
          >
            {v}
          </Text>
        ))}
      </Row>
      {ROWS.map(({ color, label }) => (
        <Row key={color} gap="xs" align="center">
          <Text size="xs" color="muted" style={{ width: LABEL_W }}>
            {label}
          </Text>
          {VARIANTS.map((v) => (
            <ChipCell key={v} variant={v} color={color} label={label} />
          ))}
        </Row>
      ))}
    </Block>
  )
}
function Panel({
  theme,
  title,
  surface,
}: {
  theme: typeof DEFAULT_THEME
  title: string
  surface: string
}) {
  return (
    <PlatformBlocksThemeProvider theme={theme} inherit={false}>
      <Card
        withBorder
        padding="lg"
        radius="lg"
        style={{ flexGrow: 1, flexShrink: 1, flexBasis: 380, minWidth: 300 }}
      >
        <Block fullWidth>
          <Row justify="space-between" align="baseline">
            <Text weight="600">{title}</Text>
            <Text size="xs" color="muted">
              {surface}
            </Text>
          </Row>
          <Matrix />
        </Block>
      </Card>
    </PlatformBlocksThemeProvider>
  )
}
  // Two panels, each locked to a scheme, so every variant can be read side by side
  // on the real light and dark surfaces. Text is resolved by measured contrast, so
  // every variant stays legible on both.
  return (
    <Row gap="md" wrap="wrap" align="stretch">
      <Panel theme={DEFAULT_THEME} title="Light surface" surface="#FFFFFF" />
      <Panel theme={DARK_THEME} title="Dark surface" surface="#1C1C1E" />
    </Row>
  )
}
```

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

<!-- source: https://react-ui-library.com/llms/components/CodeBlock.md -->

# CodeBlock

The CodeBlock component renders source code with optional syntax highlighting, copy-to-clipboard, GitHub integration, line wrapping, and width controls (content-fit by default, with an opt-in full width mode). Set `wrap={false}` to disable soft wrapping and enable horizontal scrolling for long lines. `radius` and `withBorder` control the code surface itself — pair `radius="none"` with `withBorder={false}` to sit flush inside a bordered container such as `Card.Section`.

## Metadata

- Canonical name: `CodeBlock`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { CodeBlock } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: typography
- Tags: code, syntax, formatting, developer, github
- Docs: https://react-ui-library.com/components/CodeBlock
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/CodeBlock

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `language` | string | No | 'tsx' | Optional language for syntax highlighting |
| `children` | string | No |  | Source to display. Optional when `files` is provided. |
| `files` | CodeBlockFile[] | No |  | 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 | No |  | File name that starts active (uncontrolled). Defaults to the first file. |
| `activeFile` | string | No |  | Active file name (controlled). Pair with `onFileChange`. |
| `onFileChange` | (fileName: string) => void | No |  | Fired when the reader switches tabs |
| `title` | string | No |  | Optional title displayed above the code block |
| `showLineNumbers` | boolean | No | false | Show line numbers in the code block |
| `highlight` | boolean | No | true | Enable syntax highlighting |
| `fullWidth` | boolean | No | true | Make the code block take the full width of its container |
| `radius` | RadiusValue | No | 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 | No | true | Draw the code surface's 1px border. Defaults to `true`. |
| `showCopyButton` | boolean | No | true | Show a copy button to copy the code to clipboard |
| `onCopy` | (code: string) => void | No |  | Callback when code is copied |
| `style` | StyleProp<ViewStyle> | No |  | Custom styles for the code block container and text |
| `textStyle` | StyleProp<TextStyle> | No |  | Custom styles for the code text |
| `titleStyle` | StyleProp<TextStyle> | No |  | Custom styles for the title text |
| `highlightLines` | Array<string \| number> | No |  | Lines to highlight, e.g. ["1", "3-5"] or [1, 3] |
| `spoiler` | boolean | No | false | Show a spoiler for the code block |
| `spoilerMaxHeight` | number | No | 160 | Maximum height for the spoiler, if exceeded a "Show More" button appears |
| `variant` | CodeBlockVariant | No | 'code' | Visual variant: default code styling, terminal emulation, or hacker theme |
| `promptSymbol` | string | No | '$' | Optional prompt prefix for terminal variant (ignored if lines already prefixed) |
| `githubUrl` | string | No |  | 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 | No | 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 | No |  | Override base colors (background, text, highlights) |
| `wrap` | boolean | No | true | Control whether long lines wrap (defaults to true). Set to false to enable horizontal scrolling instead. |
| `fontFamily` | string | No |  | Custom font family for the code text (overrides the default monospace stack) |
| `ff` | string | No |  | Shorthand alias for `fontFamily` |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `CodeBlock.basic` • Tags: basic, code, snippet • Category: basics • Status: stable • Since: 1.0.0

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

```tsx
const sample = `import { View, Text } from 'react-native';
  return (
    <View>
      <Text>Hello, World!</Text>
    </View>
  );
}`;
  return (
    <Block fullWidth>
      <Text weight="semibold">Basic code block</Text>
      <Text size="sm" color="secondary">
        The default CodeBlock renders formatted code with copy support and automatic language detection.
      </Text>
      <CodeBlock language="tsx">{sample}</CodeBlock>
    </Block>
  );
}
```

### Interactive
ID: `CodeBlock.interactive` • Tags: interactive, copy, events • Category: features • Status: stable • Since: 1.0.0

Custom onCopy handling with inline feedback and a manual trigger button.

```tsx
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}\`);`;
  const [copiedLength, setCopiedLength] = useState<number | null>(null);
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  useEffect(() => {
    return () => {
      if (timeoutRef.current) {
        clearTimeout(timeoutRef.current);
      }
    };
  }, []);
  const handleCopy = (code: string) => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setCopiedLength(code.length);
    timeoutRef.current = setTimeout(() => {
      setCopiedLength(null);
      timeoutRef.current = null;
    }, 2000);
  };
  return (
    <Block fullWidth>
      <Text weight="semibold">Interactive copy</Text>
      <Text size="sm" color="secondary">
        Attach an onCopy handler to trigger custom feedback and reuse it outside the CodeBlock controls.
      </Text>
      {copiedLength !== null && (
        <Text size="xs" color="success">
          Copied {copiedLength} characters to the clipboard.
        </Text>
      )}
      <CodeBlock language="javascript" title="Interactive copy example" onCopy={handleCopy}>
        {sampleCode}
      </CodeBlock>
      <Button title="Copy code manually" variant="outline" onPress={() => handleCopy(sampleCode)} />
    </Block>
  );
}
```

### File tabs
ID: `CodeBlock.files` • Tags: files, tabs, multi-file • Category: content • Status: stable • Since: 1.0.0

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
const FILES = [
  {
    name: 'index.tsx',
    code: `import { Blockquote } from '@platform-blocks/react-ui-library';
  return <Blockquote author={AUTHOR}>{QUOTE}</Blockquote>;
}`,
  },
  {
    name: 'data.ts',
    code: `export const AUTHOR = {
  name: 'Priya Shah',
  title: 'CTO',
  organization: 'Northwind Labs',
};
  },
  {
    name: 'quote.css',
    code: `.quote {
  border-left: 4px solid var(--primary-5);
  padding: 16px 20px;
}`,
  },
  {
    name: 'theme.json',
    code: `{
  "primaryColor": "blue",
  "defaultRadius": "md"
}`,
  },
];
  return (
    <Block fullWidth>
      <Text size="sm" color="secondary">
        Switch files from the tab strip in the top-left corner.
      </Text>
      <CodeBlock files={FILES} />
    </Block>
  );
}
```

### GitHub
ID: `CodeBlock.github` • Tags: github, toolbar, links • Category: integrations • Status: stable • Since: 1.0.0

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

```tsx
const componentExample = `import { View, Text } from 'react-native';
  return (
    <View>
      <Text>Hello, World!</Text>
    </View>
  );
}`;
const inlineExample = `// This code has both copy and GitHub buttons
  return <div>Hello with GitHub button!</div>;
}`;
const terminalExample = `$ npm install platform-blocks
$ npm start
Server running on http://localhost:3000`;
const floatingExample = `// Floating buttons example (no title)
  return <span>Hover to see buttons</span>;
}`;
  return (
    <Block fullWidth>
      <Text weight="semibold">GitHub actions</Text>
      <Text size="sm" color="secondary">
        Provide a GitHub URL to render quick links beside copy controls across any CodeBlock variant.
      </Text>
      <Block>
        <Block>
          <Text size="sm" weight="semibold">
            Basic component
          </Text>
          <CodeBlock
            title="Basic component"
            githubUrl="https://github.com/platform-blocks/react-ui-library/blob/main/packages/ui/src/components/Button/Button.tsx"
          >
            {componentExample}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            File name and language
          </Text>
          <CodeBlock
            files={[{ name: 'example.tsx' }]}
            githubUrl="https://github.com/platform-blocks/react-ui-library/blob/main/packages/ui/src/components/Text/Text.tsx"
          >
            {inlineExample}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Terminal variant
          </Text>
          <CodeBlock
            variant="terminal"
            title="Terminal example"
            githubUrl="https://github.com/platform-blocks/react-ui-library/blob/main/apps/react-ui-library.com/eas-build-post-install.sh"
          >
            {terminalExample}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Floating controls
          </Text>
          <CodeBlock githubUrl="https://github.com/platform-blocks/react-ui-library/blob/main/packages/ui/src/components/CodeBlock/CodeBlock.tsx">
            {floatingExample}
          </CodeBlock>
        </Block>
      </Block>
    </Block>
  );
}
```

### Languages
ID: `CodeBlock.languages` • Tags: syntax, languages, highlighting • Category: features • Status: stable • Since: 1.0.0

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

```tsx
const tsxExample = `interface Props {
  title: string;
  onPress?: () => void;
}
  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.`;
  return (
    <Block fullWidth>
      <Text weight="semibold">Language presets</Text>
      <Text size="sm" color="secondary">
        CodeBlock detects syntax styles across languages like TypeScript, JSON, and Markdown.
      </Text>
      <Block>
        <CodeBlock language="tsx" title="React component">
          {tsxExample}
        </CodeBlock>
        <CodeBlock language="json" title="Package configuration">
          {jsonExample}
        </CodeBlock>
        <CodeBlock language="markdown" title="Documentation">
          {markdownExample}
        </CodeBlock>
      </Block>
    </Block>
  );
}
```

### Features
ID: `CodeBlock.features` • Tags: line-numbers, full-width, copy • Category: features • Status: stable • Since: 1.0.0

Demonstrates line numbers, full-width layouts, and copy button customization in a single CodeBlock showcase.

```tsx
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 fullWidthExample = `// This code block spans the full width of its container
const data = [
  { id: 1, name: 'Alice', age: 30, city: 'New York' },
  { id: 2, name: 'Bob', age: 25, city: 'San Francisco' },
  { id: 3, name: 'Charlie', age: 35, city: 'Los Angeles' }
];
const processData = (rows) => {
  return rows
    .filter((person) => person.age >= 30)
    .map((person) => ({
      ...person,
      isAdult: true,
      displayName: \`\${person.name} (\${person.age})\`
    }))
    .sort((left, right) => left.name.localeCompare(right.name));
};
console.log(processData(data));`;
const disabledCopyExample = `// This example has the copy button disabled
const message = "Hello, World!";
console.log(message);`;
  return (
    <Block fullWidth>
      <Text weight="semibold">Feature highlights</Text>
      <Text size="sm" color="secondary">
        Combine titles, line numbers, full-width layouts, and copy controls to match different documentation needs.
      </Text>
      <Block>
        <Block>
          <Text size="sm" weight="semibold">
            Title with line numbers
          </Text>
          <CodeBlock title="With title and line numbers" showLineNumbers>
            {fibonacciExample}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Full-width layout
          </Text>
          <CodeBlock title="Full width example" fullWidth language="javascript">
            {fullWidthExample}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Copy button disabled
          </Text>
          <CodeBlock title="No copy button" showCopyButton={false}>
            {disabledCopyExample}
          </CodeBlock>
        </Block>
      </Block>
    </Block>
  );
}
```

### Variants
ID: `CodeBlock.variants` • Tags: variant, terminal, hacker • Category: styling • Status: stable • Since: 1.0.0

Compare the default, terminal, and hacker themes available through the variant prop.

```tsx
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 platform-blocks
$ cd my-app
$ npm start
Server running on port 3000`;
  return (
    <Block fullWidth>
      <Text weight="semibold">Visual variants</Text>
      <Text size="sm" color="secondary">
        Switch between default, terminal, and hacker themes using the variant prop.
      </Text>
      <Block>
        <Block>
          <Text size="sm" weight="semibold">
            Default code block
          </Text>
          <CodeBlock language="javascript" title="matrix.js">
            {sampleCode}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Terminal variant
          </Text>
          <CodeBlock variant="terminal" title="Terminal">
            {terminalCode}
          </CodeBlock>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Hacker variant
          </Text>
          <CodeBlock variant="hacker" language="javascript" title="hack.exe">
            {sampleCode}
          </CodeBlock>
        </Block>
      </Block>
    </Block>
  );
}
```

### Highlighting
ID: `CodeBlock.highlighting` • Tags: highlight, lines, emphasis • Category: features • Status: stable • Since: 1.0.0

Use highlightLines for single lines or ranges to draw attention to important snippets.

```tsx
const sample = `import { View, Text } from 'react-native';
interface User {
  id: number;
  name: string; // highlighted
  active: boolean;
}
  if (!user.active) {
    return null; // early return highlighted
  }
  return (
    <View style={{ padding: 8 }}>
      <Text>{user.name}</Text>
    </View>
  );
}
// Utility function (range highlighted)
  return users.filter((u) => u.active);
}`;
  return (
    <Block fullWidth>
      <Text weight="semibold">Highlighted lines</Text>
      <Text size="sm" color="secondary">
        Combine individual lines and ranges in the highlightLines prop to emphasize key logic.
      </Text>
  <CodeBlock title="Highlighted lines" showLineNumbers highlightLines={['1', '5-9', '11-14', '20-22']}>
        {sample}
      </CodeBlock>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Collapse.md -->

# Collapse

Displays content that can be revealed or hidden with an animation.

## Metadata

- Canonical name: `Collapse`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Collapse } from '@platform-blocks/react-ui-library';`
- Status: beta
- Category: display
- Docs: https://react-ui-library.com/components/Collapse
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Collapse

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `isCollapsed` | boolean | Yes |  | Whether the content is collapsed (hidden). `false` reveals/expands it. |
| `children` | ReactNode | Yes |  | Content to show/hide |
| `duration` | number | No | 300 | Animation duration in milliseconds |
| `transitionDuration` | number | No | 300 | Duration (ms) of the height transition. Cross-component spelling that takes precedence over `duration`; `0` snaps open/closed with no animation. |
| `timing` | 'linear' \| 'ease' \| 'ease-in' \| 'ease-out' \| 'ease-in-out' | No | 'ease-out' | Animation timing function |
| `style` | StyleProp<ViewStyle> | No |  | Style for the container |
| `contentStyle` | StyleProp<ViewStyle> | No |  | Style for the content wrapper |
| `onAnimationStart` | () => void | No |  | Callback fired when animation starts |
| `onAnimationEnd` | () => void | No |  | Callback fired when animation completes |
| `easing` | (value: number) => number | No |  | Custom easing function overriding the timing preset |
| `animateOnMount` | boolean | No | false | Whether to animate on initial mount |
| `collapsedHeight` | number | No | 0 | Custom height when collapsed (useful for partial reveals) |
| `fadeContent` | boolean | No | true | Whether to fade content in/out along with height animation |

## Examples

### Basic
ID: `Collapse.basic` • Tags: basic, collapse • Category: basics • Status: stable • Since: 1.0.0

Basic usage of the Collapse component to show and hide content with animation.

```tsx
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://react-ui-library.com/llms/components/ColorInput.md -->

# ColorInput

The ColorInput component provides an intuitive interface for selecting colors through various input methods including color wheel, hex input, and preset swatches.

## Metadata

- Canonical name: `ColorInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ColorInput } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: input
- Docs: https://react-ui-library.com/components/ColorInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ColorInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | No |  | Current color value in hex format (e.g., "#ff0000") |
| `defaultValue` | string | No | '' | Default color value for uncontrolled usage |
| `onChange` | (color: string) => void | No |  | Callback when color changes |
| `label` | string | No |  | Label for the color picker |
| `placeholder` | string | No | 'Select color' | Placeholder text when no color is selected |
| `disabled` | boolean | No | false | Whether the picker is disabled |
| `required` | boolean | No | false | Whether the picker is required |
| `error` | string | No |  | Error message to display |
| `description` | string | No |  | Help text to display below the picker |
| `size` | ComponentSizeValue | No | 'md' | Size of the picker |
| `variant` | 'default' \| 'filled' \| 'unstyled' | No | 'default' | Variant of the picker |
| `radius` | 'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | No |  | Radius of the picker |
| `showPreview` | boolean | No | true | Whether to show the color preview |
| `showInput` | boolean | No | true | Whether to show the hex input |
| `swatches` | string[] | No | DEFAULT_SWATCHES | Predefined color swatches to show |
| `withSwatches` | boolean | No | true | Whether to show common color swatches |
| `format` | 'hex' \| 'rgb' \| 'hsl' | No | 'hex' | Format for the color value |
| `withAlpha` | boolean | No | false | Whether to include alpha channel |
| `placement` | PlacementType | No |  | Dropdown placement |
| `flip` | boolean | No | true | Whether to flip placement when no space |
| `shift` | boolean | No | true | Whether to shift position to stay in viewport |
| `boundary` | any | No |  | Boundary element for positioning constraints |
| `offset` | number | No | 8 | Offset from anchor element in pixels |
| `autoReposition` | boolean | No | true | Whether to automatically reposition on resize/scroll |
| `fallbackPlacements` | PlacementType[] | No | DEFAULT_FALLBACK_PLACEMENTS | Fallback placements to try |
| `keyboardAvoidance` | boolean | No | true | Whether dropdown should avoid the on-screen keyboard when visible |
| `style` | StyleProp<ViewStyle> | No |  | Custom style for the container |
| `previewStyle` | StyleProp<ViewStyle> | No |  | Custom style for the preview |
| `inputStyle` | StyleProp<TextStyle> | No |  | Custom style for the input |
| `clearable` | boolean | No | false | Whether the picker should display a clear button |
| `clearButtonLabel` | string | No | 'Clear color' | Accessible label for the clear button |
| `testID` | string | No |  | Test ID for testing |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |

## Examples

### Basic Usage
ID: `ColorInput.basic` • Category: general

Simple color picker with default settings.

```tsx
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" color="secondary">
        Selected: {color || 'none'}
      </Text>
    </Block>
  );
}
```

### Custom Swatches
ID: `ColorInput.swatches` • Category: general

Color picker with custom swatch palettes.

```tsx
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" weight="semibold">
          Custom blue palette
        </Text>
        <ColorInput
          value={color1}
          onChange={setColor1}
          swatches={blueSwatches}
          label="Blue shades"
          fullWidth
        />
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Custom green palette
        </Text>
        <ColorInput
          value={color2}
          onChange={setColor2}
          swatches={greenSwatches}
          label="Green shades"
          fullWidth
        />
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Without swatches
        </Text>
        <ColorInput
          value={color3}
          onChange={setColor3}
          withSwatches={false}
          label="Color wheel only"
          fullWidth
        />
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/ColorPicker.md -->

# ColorPicker

ColorPicker is a lightweight alternative to ColorInput for cases where a full hex input and dropdown chrome are unnecessary. It renders a single color preview that toggles a compact popover of preset swatches — no text input, no positioning engine.

## Metadata

- Canonical name: `ColorPicker`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ColorPicker } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: input
- Docs: https://react-ui-library.com/components/ColorPicker
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ColorPicker

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | No |  | Current color value in hex format (controlled) |
| `defaultValue` | string | No | '' | Initial color value for uncontrolled usage |
| `onChange` | (color: string) => void | No |  | Callback fired when a swatch is selected |
| `swatches` | string[] | No | DEFAULT_SWATCHES | Preset colors to choose from |
| `size` | number | No | 28 | Size of the trigger + swatches in pixels |
| `columns` | number | No | 5 | Number of swatches per row in the popover |
| `disabled` | boolean | No | false | Whether the picker is disabled |
| `accessibilityLabel` | string | No |  | Accessibility label for the trigger |
| `style` | StyleProp<ViewStyle> | No |  | Custom style for the outer wrapper |
| `testID` | string | No |  | Test ID |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `ColorPicker.basic` • Category: general

```tsx
const [color, setColor] = useState('#4ECDC4');
  return (
    <Block>
      <Row gap="sm" align="center">
        <ColorPicker value={color} onChange={setColor} />
        <Text size="sm" color="secondary">
          Selected: {color}
        </Text>
      </Row>
      <Block>
        <Text size="sm" weight="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://react-ui-library.com/llms/components/ColorSwatch.md -->

# ColorSwatch

A simple square component for displaying colors, designed as a building block for color pickers and palette interfaces.

## Metadata

- Canonical name: `ColorSwatch`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ColorSwatch } from '@platform-blocks/react-ui-library';`
- Category: display
- Tags: color, swatch, palette, picker
- Docs: https://react-ui-library.com/components/ColorSwatch
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ColorSwatch

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `color` | string | Yes |  | The color value to display (hex, rgb, hsl, etc.) |
| `size` | number | No | 32 | Size of the swatch in pixels |
| `selected` | boolean | No | false | Whether the swatch is selected/active |
| `disabled` | boolean | No | false | Whether the swatch is disabled |
| `onPress` | () => void | No |  | Callback when swatch is pressed |
| `showBorder` | boolean | No | true | Show a border around the swatch |
| `borderColor` | string | No |  | Custom border color (defaults to theme color) |
| `borderWidth` | number | No | 1 | Border width in pixels |
| `borderRadius` | number | No | 4 | Border radius in pixels |
| `showCheckmark` | boolean | No | true | Show a checkmark when selected |
| `checkmarkColor` | string | No |  | Custom checkmark color |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `testID` | string | No |  | Test ID |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Advanced
ID: `ColorSwatch.advanced` • Category: general

```tsx
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 weight="semibold">{selectedColor}</Text>
            <Text size="xs" color="secondary">Click any swatch above to change</Text>
          </Flex>
        </Flex>
      </Flex>
    </Flex>
  );
}
```

### Basic
ID: `ColorSwatch.basic` • Category: general

```tsx
const colors = [
  '#FF6B6B', '#4ECDC4', '#45B7D1', '#96CEB4', '#FFEAA7',
  '#DDA0DD', '#98D8C8', '#F7DC6F', '#BB8FCE', '#85C1E9'
];
  const [selectedColor, setSelectedColor] = useState<string>('#FF6B6B');
  return (
    <Flex direction="column" gap={16} p={16} style={{ maxWidth: 400 }}>
      <Text weight="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" color="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>
  );
}
```

### Palette
ID: `ColorSwatch.palette` • Category: general

```tsx
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 weight="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 weight="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 weight="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://react-ui-library.com/llms/components/ContextMenu.md -->

# ContextMenu

The ContextMenu component provides a context-sensitive menu that appears on right-click (web) or long-press (mobile) with customizable actions.

## Metadata

- Canonical name: `ContextMenu`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ContextMenu } from '@platform-blocks/react-ui-library';`
- Category: overlay
- Tags: menu, context, rightclick, longpress, actions
- Docs: https://react-ui-library.com/components/ContextMenu
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ContextMenu

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | (props: { onContextMenu: (e: any) => void; onPressIn: (e: any) => void }) => React.ReactNode | Yes |  | Render prop for the trigger |
| `items` | ContextMenuItem[] | Yes |  |  |
| `closeOnSelect` | boolean | No |  | Close after selection (default true) |
| `longPressDelay` | number | No |  | Long press duration (ms) for native |
| `maxHeight` | number | No |  | Optional maximum height (scrolls) |
| `onOpen` | () => void | No |  | Called when menu opens |
| `onClose` | () => void | No |  | Called when menu closes |
| `open` | boolean | No |  | Controlled open |
| `position` | { x: number; y: number } | No |  | Controlled position |
| `portalId` | string | No |  | Portal target id (web) - simple placeholder for future portal integration |
| `style` | any | No |  |  |

## Examples

### Basic Usage
ID: `ContextMenu.basic` • Tags: rightclick, longpress • Category: basics • Status: stable • Since: 1.0.0

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
const ITEMS = [
  { id: 'copy', label: 'Copy' },
  { id: 'rename', label: 'Rename' },
  { id: 'delete', label: 'Delete', danger: true },
];
  return (
    <ContextMenu items={ITEMS}>
      {(triggerProps) => (
        <Card {...triggerProps} style={{ padding: 24, alignItems: 'center' }}>
          <Text variant="p">Right-click or long-press me</Text>
        </Card>
      )}
    </ContextMenu>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/ControlField.md -->

# ControlField

ControlField combines a label, description, and a control (Switch, Checkbox, or Radio) into a single pressable row.

## Metadata

- Canonical name: `ControlField`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ControlField } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: control, field, checkbox, switch, radio, toggle, form, selection, row
- Docs: https://react-ui-library.com/components/ControlField
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ControlField

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `isSelected` | boolean | No |  | Controlled selected state |
| `checked` | boolean | No |  | Alias for `isSelected` to match other controls in the library |
| `defaultSelected` | boolean | No |  | Initial selected state for uncontrolled usage |
| `onSelectedChange` | (selected: boolean) => void | No |  | Change handler — fires with the next selected value |
| `onChange` | (selected: boolean) => void | No |  | Alias for `onSelectedChange` to match other controls in the library |
| `isDisabled` | boolean | No |  | Whether the field is disabled |
| `disabled` | boolean | No |  | Alias for `isDisabled` |
| `isInvalid` | boolean | No |  | Whether the field is in an invalid state (defaults to true when `error` is set) |
| `isRequired` | boolean | No |  | Whether the field is required (renders an asterisk on the label) |
| `required` | boolean | No |  | Alias for `isRequired` |
| `variant` | ControlFieldVariant | No |  | Which built-in control renders in the indicator slot |
| `label` | React.ReactNode | No |  | Primary label text |
| `description` | React.ReactNode | No |  | Helper text shown beneath the label |
| `error` | string | No |  | Error message shown below the row when invalid |
| `color` | ColorValue | No |  | Indicator color. A palette token, `'primary.6'` shade syntax, or any CSS color. |
| `size` | SizeValue | No |  | Indicator + label size |
| `indicatorPosition` | 'left' \| 'right' | No |  | Which side the indicator sits on. Defaults to `right`. |
| `control` | React.ReactElement | No |  | Custom control element used instead of the built-in `variant` indicator. `checked` / `disabled` are injected automatically when not already set. |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the description `<Text>` |
| `children` | React.ReactNode | No |  | 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 | No |  | Accessibility label, used when there is no visible text label |
| `testID` | string | No |  | Component test ID for testing |
| `style` | any | No |  | Additional CSS styles |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `ControlField.basic` • Tags: control-field, switch • Category: basics • Status: stable • Since: 1.0.0

A controlled switch row — the whole row is a single tap target.

```tsx
const [enabled, setEnabled] = useState(true);
  return (
    <ControlField
      label="Push notifications"
      description="Get notified when something happens"
      isSelected={enabled}
      onSelectedChange={setEnabled}
    />
  );
}
```

### Checkbox with validation
ID: `ControlField.checkbox-validation` • Tags: control-field, checkbox, validation • Category: basics • Status: stable • Since: 1.0.0

A consent row using the `checkbox` variant. When left unchecked the field shows an error message below the row.

```tsx
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"
      isRequired
      isSelected={agreed}
      onSelectedChange={setAgreed}
      isInvalid={!agreed}
      error={!agreed ? 'This field is required' : undefined}
    />
  );
}
```

### Custom control
ID: `ControlField.custom-control` • Tags: control-field, composition, checkbox • Category: composition • Status: stable • Since: 1.0.0

Compose the row explicitly with `ControlField.Indicator` to drop in a custom control — here a warning-colored checkbox.

```tsx
const [subscribed, setSubscribed] = useState(false);
  return (
    <ControlField isSelected={subscribed} onSelectedChange={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
ID: `ControlField.grouped-surface` • Tags: control-field, group, surface, settings, dividers • Category: composition • Status: stable • Since: 1.0.0

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
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" isSelected={wifi} onSelectedChange={setWifi} />
      <ControlField
        label="Bluetooth"
        isSelected={bluetooth}
        onSelectedChange={setBluetooth}
      />
      <ControlField
        label="Airplane mode"
        description="Turn off all connections"
        isSelected={airplane}
        onSelectedChange={setAirplane}
      />
    </ControlField.Group>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `CopyButton`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { CopyButton } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: input
- Docs: https://react-ui-library.com/components/CopyButton
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/CopyButton

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | Yes |  | The text to copy to clipboard |
| `onCopy` | (value: string) => void | No |  | Callback fired after copy action |
| `iconOnly` | boolean | No |  | If true, only the icon is shown (no button chrome or label) |
| `label` | string | No |  | Accessible label for the button |
| `toastTitle` | string | No |  | Title for the toast |
| `toastMessage` | string | No |  | Detailed message for the toast |
| `size` | ComponentSizeValue | No |  | Visual size token |
| `style` | StyleProp<ViewStyle> | No |  | Style overrides for the button container |
| `disableToast` | boolean | No |  | Disable the "copied to clipboard" toast |
| `tooltip` | TooltipPropValue | No |  | Tooltip text, or a full Tooltip config (`{ label, maxWidth, … }`) |
| `tooltipPosition` | 'top' \| 'bottom' \| 'left' \| 'right' | No |  | Tooltip position when the string form of `tooltip` is used |
| `mode` | 'button' \| 'icon' | No |  | Presentation mode: default button (legacy) or bare icon |
| `buttonVariant` | 'none' \| 'secondary' \| 'ghost' \| 'filled' \| 'outline' \| 'gradient' \| undefined | No |  | Button variant override when in button mode |
| `iconName` | string | No |  | Icon name to display (defaults to copy) when in icon mode |
| `copiedIconName` | string | No |  | Icon name to display after copy (default check) in icon mode |
| `iconColor` | string | No |  | Base icon color (icon mode) |
| `copiedIconColor` | string | No |  | Copied state icon color (icon mode) |

## Examples

### Basic
ID: `CopyButton.basic` • Category: general

Icon-only copy button with default toast feedback.

```tsx
return (
    <Card p={16} variant="outline">
      <Flex direction="row" align="center" gap={12}>
        <Text size="sm">Invite Code:</Text>
        <Text weight="semibold">ABCD-1234</Text>
        <CopyButton value="ABCD-1234" />
      </Flex>
    </Card>
  );
}
```

### Labeled
ID: `CopyButton.labeled` • Category: general

Copy control showing label text instead of icon-only presentation.

```tsx
return (
    <Card p={16} variant="outline">
      <Flex direction="column" gap={12}>
        <Text size="sm" weight="semibold">API Key</Text>
        <Flex direction="row" gap={8} align="center">
          <Text size="xs" style={{ maxWidth: 240 }}>sk_live_1a2b3c4d5e6f7g8h9i10</Text>
          <CopyButton value="sk_live_1a2b3c4d5e6f7g8h9i10" iconOnly={false} label="Copy Key" />
        </Flex>
      </Flex>
    </Card>
  );
}
```

### Long Value
ID: `CopyButton.long-value` • Category: general

Long value truncation in toast (shows ellipsis for >60 chars).

```tsx
const longToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.long.payload.value.with.many.sections.and.characters.for.demo.purposes.only';
  return (
    <Card p={16} variant="outline">
      <Flex direction="column" gap={12}>
        <Text size="sm" weight="semibold">JWT Token</Text>
        <Text size="xs" style={{ maxWidth: 520 }}>{longToken}</Text>
        <CopyButton value={longToken} iconOnly={false} label="Copy Token" />
      </Flex>
    </Card>
  );
}
```

### No Toast
ID: `CopyButton.no-toast` • Category: general

Copy control with toast notifications disabled.

```tsx
const [copiedValue, setCopiedValue] = useState<string | null>(null);
  return (
    <Card p={16} variant="outline">
      <Flex direction="column" gap={12}>
        <Flex direction="row" gap={8} align="center">
          <Text size="sm">Secret:</Text>
          <Text weight="semibold">hunter2</Text>
          <CopyButton value="hunter2" disableToast onCopy={(v) => setCopiedValue(v)} iconOnly={false} label="Copy" />
        </Flex>
        {copiedValue && <Text size="xs" color="success">Copied locally: {copiedValue}</Text>}
      </Flex>
    </Card>
  );
}
```

### Sizes
ID: `CopyButton.sizes` • Category: general

Scale the copy affordance with the `size` prop, from `xs` through `3xl`.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <CopyButton size={size} value="@platform-blocks/react-ui-library" />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/DataList.md -->

# DataList

DataList displays a set of label/value pairs, such as user details or metadata, in a clean, aligned layout. Compose items with `DataList.Item`, `DataList.ItemLabel`, and `DataList.ItemValue`, or pass a `data` array for a quick setup.

## Metadata

- Canonical name: `DataList`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { DataList } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 0.10.1
- Category: data
- Tags: datalist, description, definition, key-value, label, value, details
- Docs: https://react-ui-library.com/components/DataList
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/DataList

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | ReactNode | No |  | `DataList.Item` children. Ignored when `data` is provided. |
| `data` | DataListDataItem[] | No |  | Shorthand for rendering items without composing `DataList.Item` manually |
| `orientation` | DataListOrientation | No |  | Layout direction of each label/value pair |
| `withDivider` | boolean | No |  | Render a divider between items |
| `size` | ComponentSizeValue | No |  | Controls font size and spacing |
| `spacing` | ComponentSizeValue \| number | No |  | Override the vertical gap between items |
| `labelWidth` | number \| string | No |  | Width of the label column in horizontal orientation |
| `labelColor` | string | No |  | Override the label text color for all items |
| `valueColor` | string | No |  | Override the value text color for all items |
| `dividerColor` | string | No |  | Override the divider color when `withDivider` is set |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `DataList.basic` • Tags: datalist • Category: basics • Status: stable • Since: 0.10.1

Compose `DataList.Item` with `DataList.ItemLabel` and `DataList.ItemValue` to render aligned label/value pairs.

```tsx
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
ID: `DataList.vertical` • Tags: datalist, orientation • Category: basics • Status: stable • Since: 0.10.1

Set `orientation="vertical"` to stack each label above its value — useful for longer values or narrow layouts.

```tsx
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
ID: `DataList.dividers` • Tags: datalist, divider • Category: basics • Status: stable • Since: 0.10.1

Enable `withDivider` to separate items with a border, and set `labelWidth` to keep the value column aligned.

```tsx
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
ID: `DataList.sizes` • Tags: datalist, size • Category: basics • Status: stable • Since: 0.10.1

Use the `size` prop (`xs`–`3xl`, or a number) to scale font size and spacing together.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" color="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
ID: `DataList.data` • Tags: datalist, data • Category: basics • Status: stable • Since: 0.10.1

Skip the composition and pass a `data` array of `{ label, value }` objects to render items automatically.

```tsx
const details = [
  { label: 'Order', value: '#SS-10428' },
  { label: 'Placed', value: 'July 3, 2026' },
  { label: 'Total', value: '$248.00' },
  { label: 'Payment', value: 'Visa •••• 4242' },
];
  return <DataList data={details} withDivider labelWidth={100} />;
}
```

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

<!-- source: https://react-ui-library.com/llms/components/DataTable.md -->

# DataTable

The DataTable component provides a feature-rich interface for displaying tabular data with sorting, pagination, row selection, and customizable columns.

## Metadata

- Canonical name: `DataTable`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { DataTable } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: data
- Docs: https://react-ui-library.com/components/DataTable
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/DataTable

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | string | No |  | Stable id for user preference persistence |
| `data` | T[] | Yes |  | Data rows |
| `columns` | DataTableColumn<T>[] | Yes |  | Column definitions |
| `loading` | boolean | No |  | Loading state |
| `error` | string \| null | No |  | Error message (when defined overrides table body) |
| `emptyMessage` | string | No |  | Message to display when there is no data |
| `searchable` | boolean | No |  | Enable global search input |
| `searchPlaceholder` | string | No |  | Placeholder text for global search |
| `searchValue` | string | No |  | Controlled global search value |
| `onSearchChange` | (value: string) => void | No |  | Global search change handler |
| `sortBy` | DataTableSort[] | No |  | Current sorting state |
| `onSortChange` | (sort: DataTableSort[]) => void | No |  | Sorting change callback |
| `filters` | DataTableFilter[] | No |  | Active column filters |
| `onFilterChange` | (filters: DataTableFilter[]) => void | No |  | Filter change callback |
| `showColumnFilters` | boolean | No |  | 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 | No |  | Pagination state |
| `onPaginationChange` | (pagination: DataTablePagination) => void | No |  | Pagination change handler |
| `manualPagination` | boolean | No |  | 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, 'current' \| 'total' \| 'onChange'> | No |  | 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 | No |  | Enable row selection |
| `selectedRows` | (string \| number)[] | No |  | Selected row identifiers |
| `onSelectionChange` | (selected: (string \| number)[]) => void | No |  | Selection change handler |
| `getRowId` | (row: T, index: number) => string \| number | No |  | Function to extract a stable id for each row |
| `onRowClick` | (row: T, index: number) => void | No |  | Row click handler |
| `editMode` | boolean | No |  | Whether table is in edit mode |
| `onEditModeChange` | (editMode: boolean) => void | No |  | Edit mode toggle callback |
| `onCellEdit` | (rowIndex: number, columnKey: string, newValue: any) => void | No |  | Commit cell edit |
| `bulkActions` | Array<{ key: string; label: string; icon?: React.ReactNode; action: (selectedRows: (string \| number)[], data: T[]) => void; }> | No |  | Bulk action definitions |
| `variant` | 'default' \| 'striped' \| 'bordered' | No |  | Visual table variant |
| `density` | 'compact' \| 'normal' \| 'comfortable' | No |  | Row density |
| `height` | number | No |  | Fixed table height (enables internal scroll) |
| `virtual` | boolean | No |  | Enable FlashList-powered virtualization for large datasets |
| `style` | any | No |  | Container style override |
| `enableColumnResizing` | boolean | No |  | Enable interactive column resizing |
| `rowFeatureToggle` | (row: T, index: number) => ({ selectable?: boolean; editable?: boolean; sortable?: boolean; filterable?: boolean; searchable?: boolean; } \| null \| undefined) | No |  | Per-row feature overrides |
| `initialHiddenColumns` | string[] | No |  | Initially hidden column keys |
| `onColumnVisibilityChange` | (hidden: string[]) => void | No |  | Hidden column change callback |
| `showColumnVisibilityManager` | boolean | No |  | Show built-in column visibility manager button |
| `rowsPerPageOptions` | number[] | No |  | Pagination size choices |
| `showRowsPerPageControl` | boolean | No |  | Show rows-per-page selector |
| `rowActions` | (row: T, index: number) => Array<{ key: string; icon?: React.ReactNode; label?: string; onPress?: (row: T, index: number) => void; disabled?: boolean; hidden?: boolean; tooltip?: TooltipPropValue; }> | No |  | Per-row action icon buttons (renders trailing actions column when provided) |
| `actionsColumnWidth` | number | No |  | Width of the actions column |
| `striped` | boolean | No |  | Force striped row backgrounds regardless of variant |
| `headerBackgroundColor` | string | No |  | Custom header background color |
| `enhancedLoading` | boolean | No |  | Show enhanced loading skeletons instead of basic loading text |
| `enhancedEmptyState` | boolean | No |  | Show enhanced empty state with icon and description |
| `enhancedHover` | boolean | No |  | Enable enhanced hover effects |
| `hoverColor` | string | No |  | Custom row hover color |
| `enhancedSelection` | boolean | No |  | Enable enhanced selection styling |
| `showRowDividers` | boolean | No |  | 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 | No |  | Custom border color for enhanced styling |
| `hoverHighlight` | boolean | No |  | Enable simple row background hover highlight |
| `fullWidth` | boolean | No |  | Make table take full width of container |
| `rowBorderWidth` | number | No |  | Row border width. Overrides `showRowDividers` / the variant default, including at 0. |
| `rowBorderColor` | string | No |  | Custom row border color |
| `rowBorderStyle` | 'solid' \| 'dashed' \| 'dotted' | No |  | Row border style |
| `columnBorderWidth` | number | No |  | 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 | No |  | Custom column border color |
| `columnBorderStyle` | 'solid' \| 'dashed' \| 'dotted' | No |  | Column border style |
| `showOuterBorder` | boolean | No |  | Whether to show outer border around entire table. Defaults to `true`. |
| `outerBorderWidth` | number | No |  | Outer border width |
| `outerBorderColor` | string | No |  | Outer border color |
| `expandableRowRender` | (row: T, index: number) => React.ReactNode | No |  | Function to render expanded row content |
| `initialExpandedRows` | (string \| number)[] | No |  | Initially expanded row identifiers |
| `expandedRows` | (string \| number)[] | No |  | Controlled expanded rows |
| `onExpandedRowsChange` | (expanded: (string \| number)[]) => void | No |  | Expanded rows change handler |
| `allowMultipleExpanded` | boolean | No |  | Allow multiple rows to be expanded at once |
| `expandIcon` | React.ReactNode | No |  | Custom expand/collapse icons |
| `collapseIcon` | React.ReactNode | No |  |  |
| `headerTextProps` | Omit<TextProps, 'children'> | No |  | Override props applied to every column header `<Text>` (style, weight, ff, size, color). |
| `cellTextProps` | Omit<TextProps, 'children'> | No |  | Override props applied to default-rendered cell text (cells without a custom `cell` renderer). |
| `ariaLabel` | string | No |  | Accessible name for the grid, exposed as `aria-label` on web (screen readers announce it when entering the table). Defaults to "Data table". |
| `exportable` | boolean | No |  | Show a CSV export button in the toolbar. Exports the current view (filtered + sorted, all pages) using the visible columns. |
| `exportFileName` | string | No |  | File name for the downloaded CSV (default: "data.csv"). |
| `onExport` | (csv: string, rows: T[]) => void | No |  | 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 | No |  | Enable drag-to-reorder of column headers (web). |
| `columnOrder` | string[] | No |  | Controlled column order (array of column keys). |
| `onColumnOrderChange` | (order: string[]) => void | No |  | Called with the new key order after a drag-reorder. |
| `groupBy` | string | No |  | 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 | No |  | Whether groups start expanded (default: true). |
| `renderGroupHeader` | (info: { value: any; rows: T[]; count: number; expanded: boolean; toggle: () => void; }) => React.ReactNode | No |  | Custom renderer for the group-header label cell. |
| `showFooterTotals` | boolean | No |  | Render a footer row with grand-total aggregates for aggregate columns. |
| `footerLabel` | string | No |  | Label shown in the first cell of the footer totals row (default: "Total"). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Getting Started
ID: `DataTable.basic` • Tags: datatable • Category: usage • Status: stable • Since: 1.0.0

Define columns, feed the dataset, and let `DataTable` handle search, sorting, and pagination out of the box.

```tsx
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 },
];
  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"
    />
  );
}
```

### Column Filters
ID: `DataTable.advanced-filtering` • Tags: datatable, filters • Category: behavior • Status: stable • Since: 1.0.0

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
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',
  },
];
  const [filters, setFilters] = useState<DataTableFilter[]>([]);
  return (
    <DataTable
      data={people}
      columns={columns}
      filters={filters}
      onFilterChange={setFilters}
      showColumnFilters
      searchable={false}
    />
  );
}
```

### Row Selection
ID: `DataTable.row-selection` • Tags: datatable, selection • Category: behavior • Status: stable • Since: 1.0.0

Set `selectable` and wire `selectedRows` / `onSelectionChange` to track checked rows. Give `getRowId` so selection survives sorting and paging.

```tsx
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 },
];
  const [pagination, setPagination] = useState<DataTablePagination>({
    page: 1,
    pageSize: 5,
    total: people.length,
  });
  const [selectedRows, setSelectedRows] = useState<(string | number)[]>([]);
  return (
    <Block fullWidth>
      <Text size="sm" color={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>
  );
}
```

### Rich Cells
ID: `DataTable.enhanced-styling` • Tags: datatable, styling • Category: appearance • Status: stable • Since: 1.0.0

Combine avatars, chips, and status cues inside custom `cell` renderers to create a readable, on-brand table.

```tsx
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 weight="semibold">{row.name}</Text>}
        description={<Text variant="small" color="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
        color={value === 'inactive' ? 'error' : value === 'pending' ? 'warning' : 'success'}
        weight="semibold"
      >
        {value.charAt(0).toUpperCase() + value.slice(1)}
      </Text>
    ),
  },
  {
    key: 'performance',
    header: 'Score',
    accessor: 'performance',
    sortable: true,
    align: 'right',
    cell: (value) => <Text weight="semibold">{value.toFixed(1)}</Text>,
  },
];
  return (
    <DataTable
      data={rows}
      columns={columns}
      density="comfortable"
      variant="striped"
      searchable={false}
    />
  );
}
```

### Expandable Rows
ID: `DataTable.expandable-rows` • Tags: datatable, expand • Category: behavior • Status: stable • Since: 1.0.0

Provide `expandedRows`, update them via `onExpandedRowsChange`, and use `expandableRowRender` to reveal supporting context.

```tsx
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',
  },
];
  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 color="muted">{project.summary}</Text>
        </Block>
      )}
      searchable={false}
    />
  );
}
```

### Grouping & Totals
ID: `DataTable.grouping` • Tags: datatable, grouping, aggregation, totals, footer • Category: behavior • Status: stable • Since: 1.0.0

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
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' },
];
  return (
    <DataTable
      data={rows}
      columns={columns}
      groupBy="region"
      showFooterTotals
      footerLabel="All regions"
      searchable={false}
      showColumnVisibilityManager={false}
    />
  );
}
```

### Fixed height & sticky columns
ID: `DataTable.fixed-height` • Tags: datatable, height, scroll, sticky-header, sticky, pinned, columns • Category: layout • Status: stable • Since: 1.0.0

Pass a fixed `height` 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
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 },
];
  return (
    <DataTable
      data={rows}
      columns={columns}
      getRowId={(row) => row.id}
      height={320}
      fullWidth={false}
      searchable={false}
    />
  );
}
```

### Server-side pagination
ID: `DataTable.server-side` • Tags: datatable, pagination, server, api, manual • Category: usage • Status: stable • Since: 1.0.0

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
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' },
];
  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://react-ui-library.com/llms/components/DatePicker.md -->

# DatePicker

DatePicker renders an inline calendar focused on keyboard-friendly, accessible selection flows. Pair it with `DatePickerInput` when you need an input trigger and modal or popover calendar.

## Metadata

- Canonical name: `DatePicker`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { DatePicker } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: dates
- Docs: https://react-ui-library.com/components/DatePicker
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/DatePicker

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | CalendarValue | No |  | Selected value; type depends on `type` prop |
| `defaultValue` | CalendarValue | No |  | Initial value for uncontrolled usage |
| `onChange` | (value: CalendarValue) => void | No |  | Called when value changes |
| `type` | CalendarType | No |  | Selection behavior |
| `calendarProps` | Partial<CoreCalendarProps> | No |  | Pass-through customization for underlying Calendar |
| `style` | StyleProp<ViewStyle> | No |  | Optional container style for the inline calendar |
| `testID` | string | No |  | Test identifier |
| `accessibilityLabel` | string | No |  | Accessibility label for the inline calendar region |
| `accessibilityHint` | string | No |  | Accessibility hint for the inline calendar region |

## Examples

### Basic Date Picker
ID: `DatePicker.basic` • Tags: basic, single-date, label, placeholder • Category: general

Standard single date selection with label and placeholder text.

```tsx
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" color="secondary">
        {value ? `Selected: ${value.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Date Range Picker
ID: `DatePicker.range` • Tags: range, start-date, end-date, date-range • Category: general

Select a range of dates with start and end date selection.

```tsx
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" color="secondary">
        {start && end
          ? `${start.toLocaleDateString()} – ${end.toLocaleDateString()}`
          : 'Select a start and end date'}
      </Text>
    </Block>
  );
}
```

### Date Validation
ID: `DatePicker.validation` • Tags: validation, error, rules, min-date, future-date • Category: general

Date picker with validation rules and error handling for invalid selections.

```tsx
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" color={inlineError ? 'error' : 'secondary'}>
        {inlineError || 'Only dates today or later are enabled'}
      </Text>
    </Block>
  );
}
```

### Multiple Dates Selection
ID: `DatePicker.multiple` • Tags: multiple, independent-dates, array, events • Category: general

Select multiple independent dates for events or availability.

```tsx
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" color="secondary">
        {value.length > 0
          ? value.map((date) => date.toLocaleDateString()).join(', ')
          : 'Select one or more dates'}
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/DatePickerInput.md -->

# DatePickerInput

DatePickerInput wraps the inline `DatePicker` in an accessible input experience. It handles focus management, modal presentation, and formatting so people can choose dates without leaving the form flow.

## Metadata

- Canonical name: `DatePickerInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { DatePickerInput } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: dates
- Docs: https://react-ui-library.com/components/DatePickerInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/DatePickerInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | CalendarValue | No |  | Selected value; type depends on `type` prop |
| `defaultValue` | CalendarValue | No |  | Initial value for uncontrolled usage |
| `onChange` | (value: CalendarValue) => void | No |  | Called when value changes |
| `type` | CalendarType | No |  | Selection behavior |
| `calendarProps` | Partial<CoreCalendarProps> | No |  | Pass-through customization for underlying Calendar |
| `placeholder` | string | No |  | Input placeholder text |
| `displayFormat` | string | No |  | Format string for displaying value in the input |
| `valueFormat` | string | No |  | Serialization/parsing format (reserved for future) |
| `clearable` | boolean | No |  | Show a clear button |
| `size` | SizeValue | No |  | Visual size |
| `disabled` | boolean | No |  | Disable interaction |
| `withAsterisk` | boolean | No |  | Show required indicator |
| `dropdownType` | 'modal' \| 'popover' | No |  | Presentation modality |
| `closeOnSelect` | boolean | No |  | Close picker after single selection (for single mode) |
| `onOpen` | () => void | No |  | Lifecycle events |
| `onClose` | () => void | No |  |  |
| `onFocus` | () => void | No |  |  |
| `onBlur` | () => void | No |  |  |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `required` | boolean | No |  | Whether input is required |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `DatePickerInput.basic` • Category: general

```tsx
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" color="secondary">
        {value ? `Selected: ${value.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Multiple
ID: `DatePickerInput.multiple` • Category: general

```tsx
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" color="secondary">
        {value.length > 0
          ? `Selected: ${value.map((date) => date.toLocaleDateString()).join(', ')}`
          : 'Select one or more dates'}
      </Text>
    </Block>
  );
}
```

### Range
ID: `DatePickerInput.range` • Category: general

```tsx
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" color="secondary">
        {value && value[0] && value[1]
          ? `${value[0].toLocaleDateString()} – ${value[1].toLocaleDateString()}`
          : 'Select a start and end date'}
      </Text>
    </Block>
  );
}
```

### Validation
ID: `DatePickerInput.validation` • Category: general

```tsx
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" color="secondary">
        Past dates show the validation state
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Dialog`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Dialog } from '@platform-blocks/react-ui-library';`
- Status: experimental
- Category: overlay
- Tags: modal, dialog, overlay, sheet
- Docs: https://react-ui-library.com/components/Dialog
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Dialog

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `visible` | boolean | Yes |  | Controls whether the dialog is visible. |
| `variant` | 'modal' \| 'bottomsheet' \| 'fullscreen' | No |  | Presentation style of the dialog. |
| `title` | string \| null | No |  | Optional title text shown in the header area. |
| `children` | ReactNode | Yes |  | Dialog body content. |
| `closable` | boolean | No |  | Allows the user to close the dialog via UI controls or escape/back. |
| `backdrop` | boolean | No |  | Whether to render the dimming backdrop behind the dialog. |
| `backdropClosable` | boolean | No |  | Whether tapping the backdrop should close the dialog. |
| `shouldClose` | boolean | No |  | Triggers close animation when set to true. |
| `onClose` | () => void | No |  | Called when the dialog requests to close. |
| `w` | number | No |  | Optional explicit width for the dialog content (modal/bottomsheet). |
| `h` | number | No |  | Optional explicit height for the dialog content. |
| `radius` | number | No |  | Corner radius for the dialog container (bottom sheet rounds top corners only). |
| `style` | object | No |  | Optional style overrides for the dialog container. |
| `showHeader` | boolean | No |  | Whether to show the styled header area with background and border (default true). |
| `bottomSheetSwipeZone` | 'container' \| 'handle' \| 'none' | No |  | Controls which part of the bottom sheet responds to swipe-to-dismiss gestures |
| `transitionDuration` | number | No | 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'> | No |  | Override props applied to the title `<Text>` (style, weight, ff, size, color). |
| `autoFocus` | DialogAutoFocus | No | false | Moves focus into the dialog once it has finished opening. See {@link DialogAutoFocus}. |
| `trapFocus` | boolean | No | true | Keeps Tab focus cycling inside the dialog while it is open and restores focus to the previously focused element when it closes. Web only. |

## Examples

### Basic Modal
ID: `Dialog.basic` • Tags: dialog, modal, actions • Category: basics • Status: stable • Since: 1.0.0

Call `openDialog` with `variant: 'modal'` to show a titled dialog and wire action buttons to `closeDialog` when the user makes a choice.

```tsx
const { openDialog, closeDialog } = useDialog();
  const showBasicDialog = () => {
    const dialogId = openDialog({
      variant: 'modal',
      title: 'Basic Dialog',
      content: (
        <Block p="md">
          <Text>This is a basic modal dialog with theme-aware styling.</Text>
          <Text size="sm" color="secondary">
            Works in both light and dark mode.
          </Text>
          <Row gap="sm" mt="sm">
            <Block grow={1}>
              <Button fullWidth variant="secondary" onPress={() => closeDialog(dialogId)}>
                Cancel
              </Button>
            </Block>
            <Block grow={1}>
              <Button
                fullWidth
                onPress={() => {
                  console.log('OK button pressed!');
                  closeDialog(dialogId);
                }}
                variant="filled"
              >
                OK
              </Button>
            </Block>
          </Row>
        </Block>
      )
    });
  };
  return (
    <Button onPress={showBasicDialog}>Open Basic Dialog</Button>
  );
}
```

### Bottom Sheet
ID: `Dialog.bottomsheet` • Tags: dialog, bottomsheet, gestures • Category: variants • Status: stable • Since: 1.0.0

Switch the dialog `variant` to `'bottomsheet'` to get swipe-to-dismiss behavior and retain full control with `closeDialog` handlers.

```tsx
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>
          <Block>
            <Text size="sm" color="secondary">
              Drag the handle or surface to move it.
            </Text>
            <Text size="sm" color="secondary">
              Swipe down to dismiss with velocity thresholds.
            </Text>
            <Text size="sm" color="secondary">
              Rubber-band resistance keeps the sheet anchored.
            </Text>
          </Block>
          <Input placeholder="Try typing while dragging..." />
          <Button variant="subtle" onPress={() => closeDialog(dialogId)}>
            Close programmatically
          </Button>
        </Block>
      )
    });
  };
  return (
    <Button onPress={showBottomSheetDialog}>Open Bottom Sheet</Button>
  );
}
```

### Confirmation
ID: `Dialog.confirmation` • Tags: dialog, confirmation, destructive • Category: patterns • Status: stable • Since: 1.0.0

Pair `variant: 'modal'` with a destructive button (`color="error"`) to confirm irreversible actions before calling your business logic.

```tsx
const { openDialog, closeDialog } = useDialog();
  const showConfirmationDialog = () => {
    const dialogId = openDialog({
      variant: 'modal',
      title: 'Confirm Action',
      content: (
        <Block p="md">
          <Text>Are you sure you want to delete this item?</Text>
          <Text size="sm" color="secondary">
            This action cannot be undone.
          </Text>
          <Row gap="sm" mt="sm">
            <Block grow={1}>
              <Button fullWidth variant="subtle" onPress={() => closeDialog(dialogId)}>
                Cancel
              </Button>
            </Block>
            <Block grow={1}>
              <Button
                fullWidth
                variant="filled"
                color="error"
                onPress={() => {
                  console.log('Item has been deleted');
                  closeDialog(dialogId);
                }}
              >
                Delete
              </Button>
            </Block>
          </Row>
        </Block>
      )
    });
  };
  return (
    <Button onPress={showConfirmationDialog}>Show Confirmation</Button>
  );
}
```

### Form Dialog
ID: `Dialog.form` • Tags: dialog, forms, validation • Category: patterns • Status: stable • Since: 1.0.0

Embed inputs in the dialog `content`, collect values via controlled callbacks, and validate before resolving the promise or calling `closeDialog`.

```tsx
const { openDialog, closeDialog } = useDialog();
  const nameRef = useRef<TextInput>(null);
  const showFormDialog = () => {
    let 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 p="md">
          <Text size="sm" color="secondary">
            Fill in your details to create an account.
          </Text>
          <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" mt="sm">
            <Block grow={1}>
              <Button fullWidth variant="secondary" onPress={() => closeDialog(dialogId)}>
                Cancel
              </Button>
            </Block>
            <Block grow={1}>
              <Button
                fullWidth
                onPress={() => {
                  if (!formData.name || !formData.email) {
                    Alert.alert('Error', 'Please fill in all fields');
                    return;
                  }
                  Alert.alert('Success', `Account created for ${formData.name}`);
                  closeDialog(dialogId);
                }}
                variant="filled"
              >
                Create account
              </Button>
            </Block>
          </Row>
        </Block>
      )
    });
  };
  return (
    <Button onPress={showFormDialog}>Open Form Dialog</Button>
  );
}
```

### Title customization
ID: `Dialog.title-customization` • Tags: titleProps, customization, slot-props • Category: general • Status: stable • Since: 1.0.0

`titleProps` accepts any `<Text>` props (`ff`, `weight`, `tracking`, `uppercase`, `size`, `color`, `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
const { openDialog, closeDialog } = useDialog();
  const open = (titleProps: any) => {
    const id = openDialog({
      variant: 'modal',
      title: 'Welcome aboard',
      titleProps,
      content: (
        <Block p="md">
          <Text>Dialog title styled via `titleProps`.</Text>
          <Button onPress={() => closeDialog(id)}>Close</Button>
        </Block>
      ),
    });
  };
  return (
    <Block>
      <Button onPress={() => open(undefined)}>Default</Button>
      <Button
        onPress={() =>
          open({
            uppercase: true,
            tracking: 1.5,
            weight: '700',
            size: 'sm',
          })
        }
      >
        Uppercase tracked
      </Button>
      <Button
        onPress={() =>
          open({
            ff: 'Georgia, serif',
            size: 'xl',
            weight: '600',
          })
        }
      >
        Serif headline
      </Button>
      <Button
        onPress={() =>
          open({
            color: 'primary',
            weight: '700',
            ff: 'monospace',
          })
        }
      >
        Brand-coloured monospace
      </Button>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Divider.md -->

# Divider

The Divider component provides a visual separator between content sections. Supports horizontal and vertical orientations, four visual variants (`solid`, `dashed`, `dotted`, `gradient`), an aligned `color` vocabulary with a soft default tuned for separators, an `opacity` shorthand, and optional labels.

## Metadata

- Canonical name: `Divider`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Divider } from '@platform-blocks/react-ui-library';`
- Category: layout
- Tags: divider, separator, line, section
- Docs: https://react-ui-library.com/components/Divider
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Divider

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `orientation` | DividerOrientation | No |  | Layout direction of the line. `'horizontal'` spans width; `'vertical'` spans height. Defaults to `'horizontal'`. |
| `variant` | DividerVariant | No |  | Visual style of the line. `'gradient'` fades transparent → color → transparent. Defaults to `'solid'`. |
| `color` | ThemeColor | No |  | 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 | No |  | Thickness of the divider (default 1). Accepts a size token or pixel value. |
| `opacity` | number | No |  | Multiplied with the divider's overall opacity. Convenience prop equivalent to `style={{ opacity }}`. |
| `label` | React.ReactNode | No |  | Optional content rendered in the middle of the line. |
| `labelPosition` | 'left' \| 'center' \| 'right' | No |  | Where the `label` sits along the line. Defaults to `'center'`. |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` (only when `label` is a string). |
| `style` | StyleProp<ViewStyle> | No |  | Style override applied to the outer wrapping `View`. |
| `testID` | string | No |  | Test identifier forwarded to the wrapping `View`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Divider.basic` • Tags: solid, dashed • Category: basics • Status: stable • Since: 1.0.0

Insert horizontal dividers between sections to separate content; switch the `variant` prop to toggle between solid and dashed lines.

```tsx
return (
    <Block>
      <Text variant="p" weight="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
ID: `Divider.colors` • Tags: color, label, variant • Category: theming • Status: stable • Since: 1.0.0

Select a `color` to match semantic palettes and combine it with `label` plus `variant` to fit your divider into content sections.

```tsx
const COLORS: Array<{ label: string; tone?: DividerProps['color'] }> = [
  { label: 'Border (default)' },
  { label: 'Subtle', tone: 'subtle' },
  { label: 'Muted', tone: 'muted' },
  { label: 'Gray', tone: 'gray' },
  { label: 'Primary', tone: 'primary' },
  { label: 'Secondary', tone: 'secondary' },
  { label: 'Success', tone: 'success' },
  { label: 'Warning', tone: 'warning' },
  { label: 'Error', tone: 'error' },
];
  return (
    <Block>
      <Block>
        <Text variant="small" weight="medium">
          Semantic color variants
        </Text>
        {COLORS.map(({ label, tone }) => (
          <Block key={label}>
            <Text variant="p" color="muted">
              {label}
            </Text>
            <Divider color={tone} />
          </Block>
        ))}
      </Block>
      <Block>
        <Text variant="small" weight="medium">
          Labeled dividers
        </Text>
        <Divider color="primary" label="Quarterly results" />
        <Divider color="success" label="Customer satisfaction" />
        <Divider color="error" label="Risks" />
      </Block>
      <Block>
        <Text variant="small" weight="medium">
          Variant styles
        </Text>
        <Divider color="primary" variant="solid" label="Solid" />
        <Divider color="primary" variant="dashed" label="Dashed" />
        <Divider color="primary" variant="dotted" label="Dotted" />
        <Divider color="primary" variant="gradient" label="Gradient" />
      </Block>
    </Block>
  );
}
```

### Gradient & opacity
ID: `Divider.gradient-opacity` • Tags: gradient, opacity, customization, variants • Category: general • Status: stable • Since: 1.0.0

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
return (
    <Block>
      <Block>
        <Text variant="small" weight="medium">
          Gradient variant
        </Text>
        <Divider variant="gradient" color="primary" />
        <Divider variant="gradient" color="error" size={2} />
        <Divider variant="gradient" label="Section break" />
      </Block>
      <Block>
        <Text variant="small" weight="medium">
          Opacity prop — same color, different emphasis
        </Text>
        <Divider color="primary" />
        <Divider color="primary" opacity={0.5} />
        <Divider color="primary" opacity={0.25} />
      </Block>
      <Block>
        <Text variant="small" weight="medium">
          Subtle separator (border default + low opacity)
        </Text>
        <Divider opacity={0.4} />
      </Block>
      <Block>
        <Text variant="small" weight="medium">
          Custom color + opacity
        </Text>
        <Divider color="#a855f7" opacity={0.6} size={2} />
      </Block>
    </Block>
  );
}
```

### Labeled Dividers
ID: `Divider.labeled` • Tags: label, labelPosition • Category: layout • Status: stable • Since: 1.0.0

Provide a `label` node and adjust `labelPosition` plus `color` to separate form sections with contextual dividers.

```tsx
return (
    <Block>
      <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
ID: `Divider.vertical` • Tags: vertical, navigation, label • Category: layout • Status: stable • Since: 1.0.0

Switch `orientation="vertical"` to separate horizontal layouts like navigation and add `label` or `color` when you need emphasis.

```tsx
return (
    <Block>
      <Block align="center" direction="row" h={100}>
        <Block align="center">
          <Text variant="p" weight="medium">
            Profile
          </Text>
          <Text variant="small" color="muted">
            View details
          </Text>
        </Block>
        <Divider orientation="vertical" />
        <Block align="center">
          <Text variant="p" weight="medium">
            Settings
          </Text>
          <Text variant="small" color="muted">
            Preferences
          </Text>
        </Block>
        <Divider orientation="vertical" label="Pro" color="success" />
        <Block align="center">
          <Text variant="p" weight="medium">
            Support
          </Text>
          <Text variant="small" color="muted">
            Help center
          </Text>
        </Block>
      </Block>
      <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>
    </Block>
  );
}
```

### Sizes
ID: `Divider.sizes` • Category: general

Demonstrates how the `size` prop accepts both numeric values and spacing tokens so you can dial in subtle, comfortable, or bold divider weights in horizontal and vertical layouts.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Block fullWidth>
      {SIZES.map((size) => (
        <Block key={size} fullWidth>
          <Text variant="small" color="secondary">{size}</Text>
          <Divider size={size} />
        </Block>
      ))}
      <Block fullWidth>
        <Text variant="small" color="secondary">1 (numeric)</Text>
        <Divider size={1} />
      </Block>
    </Block>
  );
}
```

### Variants
ID: `Divider.variants` • Category: general

Showcase solid, dashed, and dotted dividers in both horizontal and vertical layouts to highlight how each variant can communicate different section breaks.

```tsx
return (
    <Block>
      <Block>
        <Text variant="p" weight="medium">
          Release Notes
        </Text>
        <Text variant="p" color="muted">
          Default solid divider keeps sections crisp.
        </Text>
        <Divider variant="solid" />
        <Text variant="p">
          The winter update introduces a revamped queue and faster syncing.
        </Text>
      </Block>
      <Block>
        <Text variant="p" weight="medium">
          Sprint Checklist
        </Text>
        <Text variant="p" color="muted">
          Dashed lines work nicely for in-progress flows.
        </Text>
        <Divider variant="dashed" />
        <Text variant="p">
          QA sign-off, regression pass, and rollout comms are scheduled for Friday.
        </Text>
      </Block>
      <Block>
        <Text variant="p" weight="medium">
          Creator Status
        </Text>
        <Text variant="p" color="muted">
          Dotted borders add a softer visual break.
        </Text>
        <Divider variant="dotted" />
        <Text variant="p">
          Enable payouts once verification documents finish processing.
        </Text>
      </Block>
      <Block>
        <Text variant="p" weight="medium">
          Section break
        </Text>
        <Text variant="p" color="muted">
          Gradient variant fades the line in and out — softer than a hard rule.
        </Text>
        <Divider variant="gradient" color="primary" />
        <Text variant="p">
          The fade keeps long-form content breathable without dropping a horizontal stripe.
        </Text>
      </Block>
      <Block direction="row" align="center" wrap="wrap">
        <Text variant="small" weight="medium">
          Published
        </Text>
        <Divider orientation="vertical" variant="solid" style={{ height: 48 }} />
        <Text variant="small" weight="medium">
          Drafts
        </Text>
        <Divider orientation="vertical" variant="dashed" style={{ height: 48 }} />
        <Text variant="small" weight="medium">
          Scheduled
        </Text>
        <Divider orientation="vertical" variant="dotted" label="Beta" color="warning" style={{ height: 48 }} />
        <Text variant="small" weight="medium">
          Archived
        </Text>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `FileInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { FileInput } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: input
- Docs: https://react-ui-library.com/components/FileInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/FileInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | 'standard' \| 'dropzone' \| 'compact' | No |  | File input variant |
| `accept` | string[] | No |  | Accepted file types (MIME types or extensions) |
| `multiple` | boolean | No |  | Multiple file selection |
| `maxSize` | number | No |  | Maximum file size in bytes |
| `maxFiles` | number | No |  | Maximum number of files |
| `onUpload` | (files: FileInputFile[]) => Promise<void> | No |  | Upload handler |
| `onProgress` | (fileId: string, progress: number) => void | No |  | Upload progress callback |
| `onFilesChange` | (files: FileInputFile[]) => void | No |  | File change handler |
| `onFileRemove` | (fileId: string) => void | No |  | File remove handler |
| `PreviewComponent` | React.ComponentType<{ file: FileInputFile; onRemove: () => void }> | No |  | File preview component |
| `children` | React.ReactNode | No |  | Custom drop zone content |
| `showFileList` | boolean | No |  | Whether to show file list |
| `enableDragDrop` | boolean | No |  | Whether to enable drag and drop |
| `validateFile` | (file: File \| DocumentPickerAssetLike) => string \| null | No |  | Custom validation function |
| `imagePreview` | { enabled?: boolean; maxWidth?: number; maxHeight?: number; quality?: number; } | No |  | Image preview settings |
| `uploadSettings` | { url?: string; method?: 'POST' \| 'PUT'; headers?: Record<string, string>; fieldName?: string; formData?: Record<string, string>; } | No |  | Upload settings |
| `value` | string | No |  | Input value |
| `onChangeText` | (text: string) => void | No |  | Change handler |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `placeholder` | string | No |  | Input placeholder |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No |  | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `FileInput.basic` • Tags: basic, upload, files • Category: basics • Status: stable • Since: 1.0.0

Simple file input with helper text and multiple file selection.

```tsx
const [files, setFiles] = useState<FileInputFile[]>([]);
  return (
    <Block fullWidth>
      <FileInput
        label="Upload files"
        helperText="Choose files from your device"
        onFilesChange={setFiles}
        multiple
        fullWidth
      />
      {files.length > 0 && (
        <Text size="xs" color="secondary">
          Selected: {files.map((file) => file.name).join(', ')}
        </Text>
      )}
    </Block>
  );
}
```

### Dropzone
ID: `FileInput.dropzone` • Tags: dropzone, drag-and-drop, upload • Category: variants • Status: stable • Since: 1.0.0

Drag-and-drop dropzone variant with native fallback instructions and selected file list.

```tsx
const [files, setFiles] = useState<FileInputFile[]>([]);
  const instructions =
    Platform.OS === 'web'
      ? 'Drag files into the dropzone or click Browse files to pick from your desktop.'
      : 'Tap the dropzone to open the native file picker on touch devices.';
  return (
    <Block fullWidth>
      <Text size="sm" color="secondary">
        {instructions}
      </Text>
      <FileInput
        variant="dropzone"
        multiple
        accept={['image/*', '.pdf', '.txt']}
        helperText="Drag & drop on desktop or tap to browse on mobile"
        onFilesChange={setFiles}
        showFileList
        fullWidth
      />
      {files.length > 0 && (
        <Block>
          <Text size="xs" weight="semibold">
            Selected files ({files.length})
          </Text>
          <Block>
            {files.map((file) => (
              <Text key={file.id} size="xs" color="secondary">
                {file.name}
              </Text>
            ))}
          </Block>
        </Block>
      )}
    </Block>
  );
}
```

### File Type Restrictions
ID: `FileInput.fileTypes` • Tags: accept, validation, upload • Category: features • Status: stable • Since: 1.0.0

Configure different file inputs with MIME filters, extension lists, and size limits.

```tsx
const [imageFiles, setImageFiles] = useState<FileInputFile[]>([]);
  const [documentFiles, setDocumentFiles] = useState<FileInputFile[]>([]);
  const [videoFiles, setVideoFiles] = useState<FileInputFile[]>([]);
  return (
    <Block fullWidth>
      <Block>
        <Text weight="semibold">File type restrictions</Text>
        <Text size="sm" color="secondary">
          Limit accepted file types per uploader using MIME types, extensions, and size caps.
        </Text>
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Images only
        </Text>
        <FileInput
          accept={['image/*']}
          helperText="Only image files are allowed"
          onFilesChange={setImageFiles}
          multiple
          fullWidth
        />
        {imageFiles.length > 0 && (
          <Text size="xs" color="secondary">
            Selected: {imageFiles.map((file) => file.name).join(', ')}
          </Text>
        )}
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Documents only
        </Text>
        <FileInput
          accept={['.pdf', '.doc', '.docx', '.txt']}
          helperText="PDF, Word documents, and text files only"
          onFilesChange={setDocumentFiles}
          multiple
          fullWidth
        />
        {documentFiles.length > 0 && (
          <Text size="xs" color="secondary">
            Selected: {documentFiles.map((file) => file.name).join(', ')}
          </Text>
        )}
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Videos (max 50MB)
        </Text>
        <FileInput
          accept={['video/*']}
          maxSize={50 * 1024 * 1024}
          helperText="Video files up to 50MB"
          onFilesChange={setVideoFiles}
          fullWidth
        />
        {videoFiles.length > 0 && (
          <Text size="xs" color="secondary">
            Selected: {videoFiles.map((file) => file.name).join(', ')}
          </Text>
        )}
      </Block>
    </Block>
  );
}
```

### Image Preview
ID: `FileInput.imagePreview` • Category: general

Image upload with preview thumbnails and remove functionality.

```tsx
const [images, setImages] = useState<FileInputFile[]>([]);
  const handleRemoveFile = (index: number) => {
    setImages((prev) => prev.filter((_, itemIndex) => itemIndex !== index));
  };
  return (
    <Block fullWidth>
      <FileInput
        label="Upload images"
        accept={['image/*']}
        helperText="Add images to see inline previews"
        onFilesChange={setImages}
        multiple
        fullWidth
      />
      {images.length > 0 && (
        <Block fullWidth>
          <Text size="sm" weight="semibold">
            Selected images ({images.length})
          </Text>
          <Flex direction="row" gap={12} wrap="wrap">
            {images.map((file, index) => (
              <Card key={file.id ?? file.name} p={8} variant="outline" style={{ width: 150 }}>
                <Block>
                  {file.previewUrl && (
                    <img
                      src={file.previewUrl}
                      alt={file.name}
                      style={{ width: '100%', height: 100, objectFit: 'cover', borderRadius: 4 }}
                    />
                  )}
                  <Text size="xs" weight="medium" align="center">
                    {file.name}
                  </Text>
                  <Button size="xs" variant="outline" onPress={() => handleRemoveFile(index)}>
                    Remove
                  </Button>
                </Block>
              </Card>
            ))}
          </Flex>
        </Block>
      )}
    </Block>
  );
}
```

### Size Variants
ID: `FileInput.variants` • Category: general

Different size variants and customization options.

```tsx
const sizes = [
  { label: 'Small', size: 'sm' as const },
  { label: 'Medium (default)', size: 'md' as const },
  { label: 'Large', size: 'lg' as const },
];
  const [files, setFiles] = useState<Record<string, FileInputFile[]>>({});
  const handleChange = (key: string) => (next: FileInputFile[]) => {
    setFiles((prev) => ({ ...prev, [key]: next }));
  };
  return (
    <Block fullWidth>
      {sizes.map(({ label, size }) => (
        <Block key={label} fullWidth>
          <Text size="sm" weight="semibold">
            {label}
          </Text>
          <FileInput
            label={`${label} input`}
            helperText={`${label} size example`}
            onFilesChange={handleChange(label)}
            size={size}
            multiple={size === 'lg'}
            fullWidth
          />
          {files[label]?.length ? (
            <Text size="xs" color="secondary">
              Selected: {files[label].length}
            </Text>
          ) : null}
        </Block>
      ))}
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Custom placeholder
        </Text>
        <FileInput
          placeholder="Click to select your files"
          helperText="Demonstrates placeholder overrides"
          onFilesChange={handleChange('custom')}
          fullWidth
        />
      </Block>
    </Block>
  );
}
```

### Upload Progress
ID: `FileInput.upload` • Category: general

File upload with progress simulation and bulk actions.

```tsx
const [files, setFiles] = useState<FileInputFile[]>([]);
  const [isUploading, setIsUploading] = useState(false);
  const [uploadProgress, setUploadProgress] = useState<{[key: string]: number}>({});
  const handleUpload = async () => {
    if (files.length === 0) return;
    setIsUploading(true);
    // Simulate upload process for each file
    for (const file of files) {
      // Simulate progress updates
      for (let progress = 0; progress <= 100; progress += 25) {
        setUploadProgress(prev => ({ ...prev, [file.name]: progress }));
        await new Promise(resolve => setTimeout(resolve, 300));
      }
    }
    setIsUploading(false);
    alert('Files uploaded successfully!');
    setFiles([]);
    setUploadProgress({});
  };
  const handleRemove = (index: number) => {
    setFiles(prev => prev.filter((_, i) => i !== index));
  };
  return (
    <Block fullWidth>
      <FileInput
        label="Select files to upload"
        helperText="Choose files and click upload to simulate progress"
        onFilesChange={setFiles}
        multiple
        maxFiles={5}
        maxSize={10 * 1024 * 1024}
        fullWidth
      />
      {files.length > 0 && (
        <Block fullWidth>
          <Text size="sm" weight="semibold">
            Selected files
          </Text>
          <Block>
            {files.map((file, index) => (
              <Flex
                key={file.id ?? file.name}
                direction="row"
                justify="space-between"
                align="center"
                p={8}
                style={{ borderWidth: 1, borderColor: '#e0e0e0', borderRadius: 4 }}
              >
                <Block>
                  <Text size="sm" weight="medium">
                    {file.name}
                  </Text>
                  <Text size="xs" color="secondary">
                    {(file.size / 1024).toFixed(1)} KB
                  </Text>
                  {uploadProgress[file.name] !== undefined && (
                    <Text size="xs" color="primary">
                      Progress: {uploadProgress[file.name]}%
                    </Text>
                  )}
                </Block>
                <Button size="xs" variant="outline" onPress={() => handleRemove(index)} disabled={isUploading}>
                  Remove
                </Button>
              </Flex>
            ))}
          </Block>
          <Flex direction="row" gap={12} wrap="wrap">
            <Button
              variant="gradient"
              onPress={handleUpload}
              disabled={isUploading || files.length === 0}
              loading={isUploading}
            >
              {isUploading ? 'Uploading…' : 'Upload files'}
            </Button>
            <Button
              variant="outline"
              onPress={() => {
                setFiles([]);
                setUploadProgress({});
              }}
              disabled={isUploading}
            >
              Clear all
            </Button>
          </Flex>
        </Block>
      )}
    </Block>
  );
}
```

### Validation & States
ID: `FileInput.validation` • Category: general

File input with various validation rules and states.

```tsx
const [validatedFiles, setValidatedFiles] = useState<FileInputFile[]>([]);
  const [singleFile, setSingleFile] = useState<FileInputFile[]>([]);
  const [limitedFiles, setLimitedFiles] = useState<FileInputFile[]>([]);
  return (
    <Block fullWidth>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Size validation (max 2MB)
        </Text>
        <FileInput
          label="Upload small files"
          helperText="Files must be below 2MB"
          onFilesChange={setValidatedFiles}
          maxSize={2 * 1024 * 1024}
          multiple
          fullWidth
        />
        {validatedFiles.length > 0 && (
          <Text size="xs" color="secondary">
            Selected: {validatedFiles.length}
          </Text>
        )}
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Single file only
        </Text>
        <FileInput
          label="Upload one file"
          helperText="Select a single file"
          onFilesChange={setSingleFile}
          multiple={false}
          fullWidth
        />
        {singleFile[0] && (
          <Text size="xs" color="secondary">
            Selected: {singleFile[0].name}
          </Text>
        )}
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Limited file count
        </Text>
        <FileInput
          label="Upload up to 3 files"
          helperText="Selecting more will show a validation error"
          onFilesChange={setLimitedFiles}
          multiple
          maxFiles={3}
          fullWidth
        />
        {limitedFiles.length > 0 && (
          <Text size="xs" color="secondary">
            Selected: {limitedFiles.length}
          </Text>
        )}
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          With error state
        </Text>
        <FileInput
          label="Required upload"
          helperText="This field is required"
          onFilesChange={() => {}}
          error="Please select at least one file"
          required
          fullWidth
        />
      </Block>
      <Block fullWidth>
        <Text size="sm" weight="semibold">
          Disabled state
        </Text>
        <FileInput
          label="Disabled upload"
          helperText="The uploader is unavailable"
          onFilesChange={() => {}}
          disabled
          fullWidth
        />
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Flex`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Flex } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: layout
- Docs: https://react-ui-library.com/components/Flex
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Flex

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `direction` | 'row' \| 'column' \| 'row-reverse' \| 'column-reverse' | No |  | Flex direction |
| `align` | 'flex-start' \| 'flex-end' \| 'center' \| 'stretch' \| 'baseline' | No |  | Align items on the cross axis |
| `justify` | 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly' | No |  | Justify content on the main axis |
| `wrap` | 'nowrap' \| 'wrap' \| 'wrap-reverse' | No |  | Flex wrap |
| `gap` | SizeValue | No |  | Gap between children (applies to both row and column gap) |
| `rowGap` | SizeValue | No |  | Row gap between children |
| `columnGap` | SizeValue | No |  | Column gap between children |
| `grow` | number | No |  | Flex grow |
| `shrink` | number | No |  | Flex shrink |
| `basis` | DimensionValue | No |  | Flex basis |
| `children` | React.ReactNode | No |  | Children elements |
| `style` | StyleProp<ViewStyle> | No |  | Custom styles |
| `testID` | string | No |  | Test ID for testing |
| `disableRTLMirroring` | boolean | No |  | Disable automatic RTL mirroring for row direction |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |

## Examples

### Align Items
ID: `Flex.align` • Tags: align, items, cross-axis, alignment, stretch • Category: general

Item alignment options along the cross axis (flex-start, center, stretch, etc.).

```tsx
const ALIGNMENTS = ['flex-start', 'center', 'flex-end', 'stretch', 'baseline'] as const;
  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" color="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>
  );
}
```

### Basic Flex Layout
ID: `Flex.basic` • Tags: basic, gap, layout, container • Category: general

Simple flex container with three items and gap spacing.

```tsx
return (
    <Card variant="outline" p="md">
      <Flex gap="md">
        <Card p="sm">
          <Text variant="p">Item 1</Text>
        </Card>
        <Card p="sm">
          <Text variant="p">Item 2</Text>
        </Card>
        <Card p="sm">
          <Text variant="p">Item 3</Text>
        </Card>
      </Flex>
    </Card>
  );
}
```

### Flex Direction
ID: `Flex.direction` • Tags: direction, row, column, arrangement, axis • Category: general

Row and column direction layouts for different item arrangements.

```tsx
return (
    <Block>
      <Block>
        <Text variant="h4">Row Direction</Text>
        <Card variant="outline" p="md">
          <Flex direction="row" gap="md">
            <Card p="sm"><Text variant="p">Item 1</Text></Card>
            <Card p="sm"><Text variant="p">Item 2</Text></Card>
            <Card p="sm"><Text variant="p">Item 3</Text></Card>
          </Flex>
        </Card>
      </Block>
      <Block>
        <Text variant="h4">Column Direction</Text>
        <Card variant="outline" p="md">
          <Flex direction="column" gap="md">
            <Card p="sm"><Text variant="p">Item 1</Text></Card>
            <Card p="sm"><Text variant="p">Item 2</Text></Card>
            <Card p="sm"><Text variant="p">Item 3</Text></Card>
          </Flex>
        </Card>
      </Block>
    </Block>
  );
}
```

### Justify Content
ID: `Flex.justify` • Tags: justify, content, spacing, distribution, main-axis • Category: general

Content justification options along the main axis (flex-start, center, space-between, etc.).

```tsx
const theme = useTheme();
  return (
    <Block align="stretch">
      {[
        { 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' }
      ].map(({ value }) => (
        <Block key={value} align="stretch">
          <Text variant="span" size="sm" color="muted">justify="{value}"</Text>
          <Card variant="ghost" padding={0} style={{ alignSelf: 'stretch', width: '100%' }}>
            <Flex
              direction="row"
              justify={value as any}
              minH={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>
          </Card>
        </Block>
      ))}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Form.md -->

# Form

Form manages values, validation, and submission state for a group of inputs. Wrap each control in a `Form.Field` (which injects value and change handlers via context) and submit with `Form.Submit`.

## Metadata

- Canonical name: `Form`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Form } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: input
- Tags: form, fields, validation, submit
- Docs: https://react-ui-library.com/components/Form
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Form

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `initialValues` | Record<string, any> | No |  | Initial form values |
| `validationSchema` | ValidationSchema | No |  | Form validation schema |
| `onSubmit` | (values: Record<string, any>) => void \| Promise<void> | No |  | Submit handler |
| `validate` | (values: Record<string, any>) => Record<string, string> \| Promise<Record<string, string>> | No |  | Validation handler |
| `disabled` | boolean | No |  | Whether form is disabled |
| `validateOnChange` | boolean | No |  | Whether to validate on change |
| `validateOnBlur` | boolean | No |  | Whether to validate on blur |
| `children` | React.ReactNode | Yes |  | Children components |

## Examples

### Basic Usage
ID: `Form.basic` • Tags: form, fields, validation • Category: basics • Status: stable • Since: 1.0.0

`Form` manages values, validation, and submission state. Wrap each input in a `Form.Field` (which injects value/change handlers via context) and trigger submission with `Form.Submit`.

```tsx
return (
    <Form
      initialValues={{ name: '', email: '' }}
      onSubmit={(values) => console.log('submit', values)}
    >
      <Block style={{ width: '100%', maxWidth: 400 }}>
        <Form.Field name="name">
          <Input label="Full name" placeholder="Ada Lovelace" />
        </Form.Field>
        <Form.Field name="email">
          <Input label="Email" placeholder="ada@example.com" />
        </Form.Field>
        <Form.Submit>Create account</Form.Submit>
      </Block>
    </Form>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Gallery.md -->

# Gallery

The Gallery component displays a collection of images or media with thumbnail navigation, keyboard controls, and optional fullscreen/modal viewing.

## Metadata

- Canonical name: `Gallery`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Gallery } from '@platform-blocks/react-ui-library';`
- Status: experimental
- Category: media
- Tags: gallery, images, thumbnails, media
- Docs: https://react-ui-library.com/components/Gallery
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Gallery

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `images` | GalleryItem[] | Yes |  | Array of images to display in the gallery. |
| `initialIndex` | number | No | 0 | Index of the image shown when the gallery first opens. |
| `onClose` | () => void | No |  | Called when the gallery is closed. |
| `onImageChange` | (index: number, image: GalleryItem) => void | No |  | Called when the active image changes, receiving the new index and image. |
| `onDownload` | (image: GalleryItem) => void | No |  | Called when the download action is triggered for the current image. |
| `showMetadata` | boolean | No | false | Whether to display the metadata panel for the current image. |
| `showThumbnails` | boolean | No | true | Whether to display the thumbnail strip for navigating between images. |
| `showDownloadButton` | boolean | No | true | Whether to display the download button in the gallery controls. |
| `allowKeyboardNavigation` | boolean | No | true | Whether arrow keys and Escape can be used to navigate and close the gallery. |
| `allowSwipeNavigation` | boolean | No | true | Whether swipe gestures can be used to move between images. |
| `overlayOpacity` | number | No | 0.9 | Opacity of the backdrop overlay behind the gallery, from 0 to 1. |
| `animationDuration` | number | No | 250 | Duration of open/close and transition animations, in milliseconds. |

## Examples

### Basic
ID: `Gallery.basic` • Tags: gallery, images, navigation, metadata • Category: basics • Status: stable • Since: 1.0.0

Basic image gallery with navigation and metadata.

```tsx
// `null` closes the gallery; 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>
      <Gallery
        visible={openIndex !== null}
        images={SAMPLE_IMAGES}
        initialIndex={openIndex ?? 0}
        onClose={() => setOpenIndex(null)}
        showMetadata
      />
    </Block>
  );
}
```

### Advanced
ID: `Gallery.advanced` • Tags: advanced, customization, handlers, minimal • Category: features • Status: stable • Since: 1.0.0

Advanced gallery configurations with custom handlers.

```tsx
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. */}
      <Gallery
        visible={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. */}
      <Gallery
        visible={active === 'custom'}
        images={SAMPLE_IMAGES}
        onClose={() => setActive(null)}
        onDownload={(image: GalleryItem) => setDownloaded(image.title ?? image.id)}
        showMetadata
      />
      {downloaded ? (
        <Text size="sm" color="secondary">
          Downloaded {downloaded}
        </Text>
      ) : null}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `GradientText`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { GradientText } from '@platform-blocks/react-ui-library';`
- Category: typography
- Tags: text, gradient, animation, color
- Docs: https://react-ui-library.com/components/GradientText
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/GradientText

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `colors` | string[] | Yes |  | Array of colors for the gradient (at least 2 required) |
| `locations` | number[] | No |  | Color stops (0-1) for each color. If not provided, colors are evenly distributed |
| `angle` | number | No |  | Gradient direction angle in degrees (0 = left to right, 90 = top to bottom, etc.) |
| `start` | [number, number] | No |  | Start point [x, y] (0-1). Overrides angle if provided |
| `end` | [number, number] | No |  | End point [x, y] (0-1). Overrides angle if provided |
| `position` | number | No |  | Gradient position offset (0-1). Moves the gradient along the line |
| `animation` | GradientTextAnimation | No |  | 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 the gradient stays static. |
| `testID` | string | No |  | Custom testID for testing |

## Examples

### Basic
ID: `GradientText.basic` • Category: typography • Status: stable • Since: 1.0.0

Pass two or more `colors` to fill text with a gradient. All other `Text` props still apply.

```tsx
return (
    <GradientText colors={['#FF0080', '#7928CA']}>
      Hello World
    </GradientText>
  );
}
```

### Angles
ID: `GradientText.angles` • Category: typography • Status: stable • Since: 1.0.0

Different gradient directions using the `angle` prop.

```tsx
const angles = [0, 45, 90, 135];
  return (
    <Block gap="md">
      {angles.map((angle) => (
        <GradientText key={angle} colors={['#FF0080', '#7928CA']} angle={angle} size="lg">
          {angle}° gradient
        </GradientText>
      ))}
    </Block>
  );
}
```

### Controlled
ID: `GradientText.controlled` • Category: typography • Status: stable • Since: 1.0.0

Control the gradient position manually using the `position` prop (0.0 to 1.0).

```tsx
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://react-ui-library.com/llms/components/Grid.md -->

# Grid

Responsive 12‑column layout primitive with span-based children. Each `GridItem` declares how many columns it consumes; container controls total columns and gaps. Supports responsive values for `columns` and `span` using breakpoint-aware props.

## Metadata

- Canonical name: `Grid`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Grid } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: layout
- Docs: https://react-ui-library.com/components/Grid
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Grid

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `columns` | ResponsiveProp<number> | No |  | Number of columns (can be responsive) |
| `gap` | SizeValue | No | 0 | Gap between items |
| `rowGap` | SizeValue | No |  | Row gap between items |
| `columnGap` | SizeValue | No |  | Column gap between items |
| `fullWidth` | boolean | No | false | Make the grid take full width (100%) |
| `children` | React.ReactNode | No |  | Children elements |
| `style` | StyleProp<ViewStyle> | No |  | Custom styles |
| `testID` | string | No |  | Test ID for testing |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `Grid.basic` • Category: general

Basic 12-column grid with equal width items.

```tsx
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" align="center">
                {index + 1}
              </Text>
            </Card>
          </GridItem>
        ))}
      </Grid>
      <Text size="sm" color="secondary">
        Twelve even columns, each spanning a single track
      </Text>
    </Block>
  );
}
```

### Gaps
ID: `Grid.gaps` • Category: general

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
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 },
  },
];
  return (
    <Block fullWidth>
      {sections.map(({ label, props }) => (
        <Block key={label} fullWidth>
          <Text size="sm" weight="semibold">
            {label}
          </Text>
          <Grid columns={6} {...props}>
            {Array.from({ length: 12 }).map((_, index) => (
              <GridItem key={index} span={1}>
                <Card>
                  <Text size="sm">Item {index + 1}</Text>
                </Card>
              </GridItem>
            ))}
          </Grid>
        </Block>
      ))}
    </Block>
  );
}
```

### Nesting
ID: `Grid.nesting` • Category: general

Nested grids demonstrating composition inside a grid item.

```tsx
return (
    <Block fullWidth>
      <Grid columns={12} gap="md">
        <GridItem span={8}>
          <Card variant="outline">
            {/* Block's own gap separates the label from the nested grid — no
                margin on either one. */}
            <Block>
              <Text weight="semibold" size="sm">
                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" align="center">
                        Nested {index + 1}
                      </Text>
                    </Card>
                  </GridItem>
                ))}
              </Grid>
            </Block>
          </Card>
        </GridItem>
        <GridItem span={4}>
          <Card variant="outline">
            <Text weight="semibold" size="sm">
              Sidebar span=4
            </Text>
          </Card>
        </GridItem>
      </Grid>
      <Text size="sm" color="secondary">
        GridItem components can render another Grid to illustrate nested layouts
      </Text>
    </Block>
  );
}
```

### Responsive
ID: `Grid.responsive` • Category: general

Responsive columns and item spans using breakpoint-aware props.

```tsx
// Responsive props match the breakpoint configuration used in Grid
  return (
    <Block fullWidth>
      <Grid columns={{ base: 4, md: 8, lg: 12 }} gap="md">
        <GridItem span={{ base: 4, md: 4, lg: 6 }}>
          <Card>
            <Text>Hero (4/8/6)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 4, md: 4, lg: 6 }}>
          <Card>
            <Text>Hero (4/8/6)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 2, md: 4, lg: 3 }}>
          <Card>
            <Text>Side (2/4/3)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 2, md: 4, lg: 3 }}>
          <Card>
            <Text>Side (2/4/3)</Text>
          </Card>
        </GridItem>
        <GridItem span={{ base: 4, md: 8, lg: 12 }}>
          <Card>
            <Text>Footer (4/8/12)</Text>
          </Card>
        </GridItem>
      </Grid>
      <Text size="sm" color="secondary">
        Column and span props adapt at base, md, and lg breakpoints
      </Text>
    </Block>
  );
}
```

### Spans
ID: `Grid.spans` • Category: general

Demonstrates varying column spans within a 12-column grid.

```tsx
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>
              <Text>{`span=${span}`}</Text>
            </Card>
          </GridItem>
        ))}
      </Grid>
      <Text size="sm" color="secondary">
        Mix spans within a 12-column grid to create varied layouts
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Highlight.md -->

# Highlight

Highlight emphasizes matching fragments inside longer strings, reusing the Text component so typography settings stay consistent across platforms.

## Metadata

- Canonical name: `Highlight`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Highlight } from '@platform-blocks/react-ui-library';`
- Category: typography
- Tags: text, emphasis, highlight, mark
- Docs: https://react-ui-library.com/components/Highlight
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Highlight

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `highlight` | HighlightValue \| HighlightValue[] | No |  | Substring or substrings to emphasize within the provided children |
| `highlightStyles` | any \| ((theme: PlatformBlocksTheme) => any) | No |  | 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 | No |  | When provided, overrides the default highlight background/text palette. If the value matches a key from the theme color palettes it will use the related swatch, otherwise the value is treated as a raw color string. |
| `caseSensitive` | boolean | No |  | Toggle case-sensitive matching (defaults to case-insensitive). |
| `trim` | boolean | No |  | Trim highlight values before matching to ignore accidental whitespace. Defaults to true. |
| `highlightProps` | Partial<TextProps> | No |  | Additional props applied to the highlighted Text nodes. |

## Examples

### Basic
ID: `Highlight.basic` • Category: general

Default highlight behavior with a single search term. Matching fragments are wrapped with the theme-aware highlight styles.

```tsx
const PARAGRAPH = 'Highlight This, definitely THIS and also this!';
  return (
    <View>
      <Text variant="h5">Case-insensitive match</Text>
      <Highlight highlight="this">{PARAGRAPH}</Highlight>
    </View>
  );
}
```

### Multiple
ID: `Highlight.multiple` • Category: general

Pass an array to highlight several distinct substrings. Every match shares the same styles by default.

```tsx
const SENTENCE = 'React UI Library brings patterns, blocks, and building tools together.';
  return (
    <View>
      <Text variant="h5">Multiple values</Text>
      <Highlight highlight={['blocks', 'tools']}>{SENTENCE}</Highlight>
    </View>
  );
}
```

### Styles
ID: `Highlight.styles` • Category: general

Swap the marker color with the `highlightColor` prop, passing any theme palette name. The default marker style (yellow background, unchanged text) is preserved.

```tsx
const copy = 'You can switch the highlight color while keeping the default marker style.';
  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://react-ui-library.com/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

- Canonical name: `Icon`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Icon } from '@platform-blocks/react-ui-library';`
- Status: beta
- Category: typography
- Docs: https://react-ui-library.com/components/Icon
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Icon

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `name` | string | No |  | Icon name from the registry |
| `icon` | ExternalIconComponent \| React.ReactElement | No |  | An external icon library component or element, rendered instead of `name`. Enables using any icon library (e.g. Tabler) without registry registration. |
| `size` | IconSize | No | 'md' | Size of the icon |
| `color` | string | No |  | Color of the icon |
| `stroke` | number | No | 1.5 | Stroke thickness for outlined icons. Defaults to 1.5. |
| `variant` | IconVariant | No | 'outlined' | Icon variant - overrides the default variant from icon definition |
| `style` | StyleProp<ViewStyle> | No |  | Additional styles |
| `label` | string | No |  | Accessibility label |
| `decorative` | boolean | No | false | Whether the icon is purely decorative (skip a11y) |
| `mirrorInRTL` | boolean | No |  | Whether to mirror this icon in RTL mode. If not specified, uses auto-detection based on icon name |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `Icon.basic` • Category: general

```tsx
return (
    <ScrollView style={{ flex: 1 }}>
      <View style={{ padding: 20, gap: 24 }}>
        {/* Header */}
        <View>
          <Text variant="h4" style={{ marginBottom: 8 }}>Icon</Text>
          <Text variant="p" color="secondary">
            Scalable vector icons with consistent sizing and theming integration.
          </Text>
        </View>
        {/* Different Sizes */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>Sizes</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Available in multiple sizes using the UI theme system.
          </Text>
          <Flex direction="row" align="center" gap="lg" wrap="wrap">
            <Flex direction="column" align="center" gap="sm">
              <Icon name="home" size="sm" />
              <Text variant="small">sm</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="home" size="md" />
              <Text variant="small">md</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="home" size="lg" />
              <Text variant="small">lg</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="home" size="xl" />
              <Text variant="small">xl</Text>
            </Flex>
          </Flex>
        </Card>
        {/* Navigation Icons */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>Navigation Icons</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Common navigation and directional icons.
          </Text>
          <Flex direction="row" align="center" gap="md" wrap="wrap">
            {['home', 'arrow-left', 'arrow-right', 'arrow-up', 'arrow-down', 'chevron-left', 'chevron-right', 'chevron-up', 'chevron-down', 'menu'].map(iconName => (
              <Flex key={iconName} direction="column" align="center" gap="xs" style={{ minWidth: 80 }}>
                <Icon name={iconName} size="xl" />
                <Text variant="small" style={{ textAlign: 'center', fontSize: 10 }}>
                  {iconName}
                </Text>
              </Flex>
            ))}
          </Flex>
        </Card>
        {/* Action Icons */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>Action Icons</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Icons for common user actions and operations.
          </Text>
          <Flex direction="row" align="center" gap="md" wrap="wrap">
            {['plus', 'minus', 'x', 'check', 'search', 'edit', 'delete', 'save', 'copy', 'funnel', 'phone', 'toggle', 'qrcode', 'pin', 'spotlight'].map(iconName => (
              <Flex key={iconName} direction="column" align="center" gap="xs" style={{ minWidth: 80 }}>
                <Icon name={iconName} size="xl" />
                <Text variant="small" style={{ textAlign: 'center', fontSize: 10 }}>
                  {iconName}
                </Text>
              </Flex>
            ))}
          </Flex>
        </Card>
        {/* UI Icons */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>UI Icons</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Interface and user experience icons.
          </Text>
          <Flex direction="row" align="center" gap="md" wrap="wrap">
            {['eye', 'eyeOff', 'settings', 'user', 'heart', 'star'].map(iconName => (
              <Flex key={iconName} direction="column" align="center" gap="xs" style={{ minWidth: 80 }}>
                <Icon name={iconName} size="xl" />
                <Text variant="small" style={{ textAlign: 'center', fontSize: 10 }}>
                  {iconName}
                </Text>
              </Flex>
            ))}
          </Flex>
        </Card>
        {/* Variants */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>Icon Variants</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Icons can be displayed in outlined or filled variants.
          </Text>
          <Flex direction="column" gap="lg">
            <Flex direction="row" align="center" gap="md" wrap="wrap">
              <Title variant="small" color="secondary">Outlined (Default):</Title>
              <Icon name="star" size="xl" variant="outlined" />
              <Icon name="heart" size="xl" variant="outlined" />
              <Icon name="user" size="xl" variant="outlined" />
            </Flex>
            <Flex direction="row" align="center" gap="md" wrap="wrap">
              <Title variant="small" color="secondary">Filled:</Title>
              <Icon name="star" size="xl" variant="filled" />
              <Icon name="heart" size="xl" variant="filled" />
              <Icon name="user" size="xl" variant="filled" />
            </Flex>
          </Flex>
        </Card>
        {/* Custom Colors */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>Custom Colors</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Override icon colors to match your design.
          </Text>
          <Flex direction="row" align="center" gap="lg" wrap="wrap">
            <Flex direction="column" align="center" gap="sm">
              <Icon name="heart" size="xl" color="#E91E63" />
              <Text variant="small">Pink</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="star" size="xl" color="#FFC107" />
              <Text variant="small">Amber</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="check" size="xl" color="#4CAF50" />
              <Text variant="small">Green</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="settings" size="xl" color="#2196F3" />
              <Text variant="small">Blue</Text>
            </Flex>
          </Flex>
        </Card>
        {/* New Icons */}
        <Card variant="outline" style={{ padding: 20 }}>
          <Text variant="h6" style={{ marginBottom: 16 }}>New Icons</Text>
          <Text variant="p" color="secondary" style={{ marginBottom: 16 }}>
            Recently added icons for common use cases.
          </Text>
          <Flex direction="row" align="center" gap="lg" wrap="wrap">
            <Flex direction="column" align="center" gap="sm">
              <Icon name="link" size="lg" />
              <Text variant="small">link</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="exclamation" size="lg" />
              <Text variant="small">exclamation</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="funnel" size="lg" />
              <Text variant="small">funnel</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="camera" size="lg" />
              <Text variant="small">camera</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="mic" size="lg" />
              <Text variant="small">mic</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="bell" size="lg" />
              <Text variant="small">bell</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="calendar" size="lg" />
              <Text variant="small">calendar</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="phone" size="lg" />
              <Text variant="small">phone</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="email" size="lg" />
              <Text variant="small">email</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="folder" size="lg" />
              <Text variant="small">folder</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="file" size="lg" />
              <Text variant="small">file</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="timeline" size="lg" />
              <Text variant="small">timeline</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="loader" size="lg" />
              <Text variant="small">loader</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="switch" size="lg" />
              <Text variant="small">switch</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="carousel" size="lg" />
              <Text variant="small">carousel</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="avatar" size="lg" />
              <Text variant="small">avatar</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="toggle" size="lg" />
              <Text variant="small">toggle</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="bone" size="lg" />
              <Text variant="small">bone</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="toast" size="lg" />
              <Text variant="small">toast</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="radio" size="lg" />
              <Text variant="small">radio</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="qrcode" size="lg" />
              <Text variant="small">qrcode</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="progress" size="lg" />
              <Text variant="small">progress</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="map" size="lg" />
              <Text variant="small">map</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="list" size="lg" />
              <Text variant="small">list</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="gallery" size="lg" />
              <Text variant="small">gallery</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="pin" size="lg" />
              <Text variant="small">pin</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="tree" size="lg" />
              <Text variant="small">tree</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="keycap" size="lg" />
              <Text variant="small">keycap</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="breadcrumbs" size="lg" />
              <Text variant="small">breadcrumbs</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="pagination" size="lg" />
              <Text variant="small">pagination</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="tableofcontents" size="lg" />
              <Text variant="small">table of contents</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="stepper" size="lg" />
              <Text variant="small">stepper</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="menu" size="lg" />
              <Text variant="small">context menu</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="grid" size="lg" />
              <Text variant="small">grid</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="dialog" size="lg" />
              <Text variant="small">dialog</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="card" size="lg" />
              <Text variant="small">card</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="tooltip" size="lg" />
              <Text variant="small">tooltip</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="slider" size="lg" />
              <Text variant="small">slider</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="input" size="lg" />
              <Text variant="small">input</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="emoji" size="lg" />
              <Text variant="small">emoji</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="button" size="lg" />
              <Text variant="small">button</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="select" size="lg" />
              <Text variant="small">select</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="textarea" size="lg" />
              <Text variant="small">textarea</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="autocomplete" size="lg" />
              <Text variant="small">autocomplete</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="rating" size="lg" />
              <Text variant="small">rating</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="datatable" size="lg" />
              <Text variant="small">datatable</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="chip" size="lg" />
              <Text variant="small">chip</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="markdown" size="lg" />
              <Text variant="small">markdown</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="accordion" size="lg" />
              <Text variant="small">accordion</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="text" size="lg" />
              <Text variant="small">text</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="title" size="lg" />
              <Text variant="small">title</Text>
            </Flex>
            <Flex direction="column" align="center" gap="sm">
              <Icon name="waveform" size="lg" />
              <Text variant="small">waveform</Text>
            </Flex>
          </Flex>
        </Card>
      </View>
    </ScrollView>
  );
}
```

### Stroke
ID: `Icon.stroke` • Category: general

```tsx
const strokeVariants = [
  { label: 'Thin (0.75)', value: 0.75 },
  { label: 'Default (1.5)', value: 1.5 },
  { label: 'Bold (3)', value: 3 },
];
  return (
    <Card variant="outline" style={{ padding: 20 }}>
      <Flex direction="column" gap="md">
        <Text variant="h6">Stroke thickness</Text>
        <Text variant="p" color="secondary">
          Adjust the stroke thickness to match different visual weights. Filled icons that opt in to preserving stroke (like{' '}
          contrast) keep their outline while the fill still applies.
        </Text>
        <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" variant="filled" stroke={value} />
              <Text variant="small" style={{ textAlign: 'center' }}>{label}</Text>
            </Flex>
          ))}
        </Flex>
      </Flex>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/IconButton.md -->

# IconButton

An IconButton is a clickable button that contains an icon and is used to perform actions or trigger events. It is typically used in toolbars, action bars, or as standalone buttons in user interfaces.

## Metadata

- Canonical name: `IconButton`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { IconButton } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: input
- Tags: button, icon, clickable, action
- Docs: https://react-ui-library.com/components/IconButton
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/IconButton

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `icon` | string \| ExternalIconComponent \| React.ReactElement | Yes |  | Icon to render. Accepts a registry name, or an external icon library component/element (e.g. a Tabler icon) for use without registration. |
| `onPress` | () => void | No |  | Called when the button is pressed |
| `onLayout` | (event: any) => void | No |  | Called when the button layout is calculated |
| `variant` | 'default' \| 'filled' \| 'secondary' \| 'outline' \| 'ghost' \| 'gradient' \| 'none' | No | 'default' | Button visual variant. `default` is the neutral surface-plus-hairline button, matching `Button`; a solid primary fill is opt-in via `filled`. |
| `size` | SizeValue | No |  | Button size |
| `disabled` | boolean | No |  | Whether the button is disabled |
| `loading` | boolean | No |  | Whether button is in loading state (shows loader) |
| `color` | string | No |  | Tint for the button. Accepts raw CSS color OR theme token syntax: - 'primary' (palette key -> uses middle shade 5) - 'primary.6' (palette key + shade index) - '#ff0000' / 'rgb(...)' direct colors `filled`, `secondary` and `outline` tint the container; `ghost` and the neutral `default`/`none` keep their chrome and tint only the icon. `gradient` draws its own overlay and ignores this. |
| `iconColor` | string | No |  | Explicit icon color override (else derived automatically from variant & color) |
| `iconVariant` | IconProps['variant'] | No |  | Icon variant override |
| `iconSize` | IconProps['size'] | No |  | Icon size override (defaults to appropriate size for button size) |
| `tooltip` | TooltipPropValue | No |  | Tooltip shown on hover/focus — wraps the button in a `Tooltip`. Pass a string, or a config object (`{ label, maxWidth, withArrow, … }`) for long labels that need a wider bubble. |
| `tooltipPosition` | TooltipProps['position'] | No |  | Tooltip position when the string form of `tooltip` is used |
| `accessibilityLabel` | string | No |  | Accessibility label - highly recommended for icon-only buttons |
| `transitionDuration` | number | No | 100 | Length of the press scale transition in ms. `0` applies the pressed state instantly. Always 0 under reduced motion. |
| `style` | any | No |  | Style overrides for the button container |
| `testID` | string | No |  | Test ID for testing |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |
| `shadow` | ShadowValue | No |  | Shadow value - supports size tokens and 'none' |

## Examples

### Basic
ID: `IconButton.basic` • Category: general

```tsx
const [loading, setLoading] = useState(false);
  const [disabled, setDisabled] = useState(false);
  const handlePress = (action: string) => {
    console.log(`IconButton pressed: ${action}`);
  };
  return (
    <Block p="lg">
      <Text variant="h4">IconButton Component Demo</Text>
      <Text color="muted">
        IconButton is designed specifically for displaying icons in square or circular shapes.
        Use radius="xl" for circular buttons.
      </Text>
      {/* Controls */}
      <Card p="lg" variant="outline">
        <Block>
          <Text variant="h6">Controls</Text>
          <Row gap="lg">
            <Switch
              label="Loading state"
              checked={loading}
              onChange={setLoading}
            />
            <Switch
              label="Disabled state"
              checked={disabled}
              onChange={setDisabled}
            />
          </Row>
        </Block>
      </Card>
      {/* Variants */}
      <Card p="lg" variant="outline">
        <Block>
          <Text variant="h6">Variants</Text>
          <Row gap="md" align="center" wrap="wrap">
            <IconButton
              icon="home"
              variant="default"
              onPress={() => handlePress('default')}
              loading={loading}
              disabled={disabled}
              tooltip="Home (Default)"
            />
            <IconButton
              icon="bell"
              variant="filled"
              onPress={() => handlePress('filled')}
              loading={loading}
              disabled={disabled}
              tooltip="Home (Filled)"
            />
            <IconButton
              icon="heart"
              variant="secondary"
              onPress={() => handlePress('secondary')}
              loading={loading}
              disabled={disabled}
              tooltip="Favorite (Secondary)"
            />
            <IconButton
              icon="settings"
              variant="outline"
              onPress={() => handlePress('outline')}
              loading={loading}
              disabled={disabled}
              tooltip="Settings (Outline)"
            />
            <IconButton
              icon="search"
              variant="ghost"
              onPress={() => handlePress('ghost')}
              loading={loading}
              disabled={disabled}
              tooltip="Search (Ghost)"
            />
            <IconButton
              icon="star"
              variant="gradient"
              onPress={() => handlePress('gradient')}
              loading={loading}
              disabled={disabled}
              tooltip="Star (Gradient)"
            />
          </Row>
        </Block>
      </Card>
      {/* Sizes */}
      <Card p="lg" variant="outline">
        <Block>
          <Text variant="h6">Sizes</Text>
          <Row gap="md" align="center" wrap="wrap">
            <IconButton
              icon="plus"
              size="xs"
              onPress={() => handlePress('xs')}
              tooltip="Extra Small"
            />
            <IconButton
              icon="plus"
              size="sm"
              onPress={() => handlePress('sm')}
              tooltip="Small"
            />
            <IconButton
              icon="plus"
              size="md"
              onPress={() => handlePress('md')}
              tooltip="Medium"
            />
            <IconButton
              icon="plus"
              size="lg"
              onPress={() => handlePress('lg')}
              tooltip="Large"
            />
            <IconButton
              icon="plus"
              size="xl"
              onPress={() => handlePress('xl')}
              tooltip="Extra Large"
            />
          </Row>
        </Block>
      </Card>
      {/* Shape: Square vs Circular */}
      <Card p="lg" variant="outline">
        <Block>
          <Text variant="h6">Shape: Square vs Circular</Text>
          <Row gap="md" align="center" wrap="wrap">
            <Block align="center">
              <IconButton
                icon="download"
                radius="sm"
                onPress={() => handlePress('square-sm')}
                tooltip="Small Radius (Square-ish)"
              />
              <Text size="xs" color="muted">radius="sm"</Text>
            </Block>
            <Block align="center">
              <IconButton
                icon="download"
                radius="md"
                onPress={() => handlePress('square-md')}
                tooltip="Medium Radius"
              />
              <Text size="xs" color="muted">radius="md"</Text>
            </Block>
            <Block align="center">
              <IconButton
                icon="download"
                radius="lg"
                onPress={() => handlePress('square-lg')}
                tooltip="Large Radius"
              />
              <Text size="xs" color="muted">radius="lg"</Text>
            </Block>
            <Block align="center">
              <IconButton
                icon="download"
                radius="xl"
                onPress={() => handlePress('circular')}
                tooltip="Circular (XL Radius)"
              />
              <Text size="xs" color="muted">radius="xl" (circular)</Text>
            </Block>
          </Row>
        </Block>
      </Card>
      {/* Custom Colors */}
      <Card p="lg" variant="outline">
        <Block>
          <Text variant="h6">Custom Colors</Text>
          <Row gap="md" align="center" wrap="wrap">
            <IconButton
              icon="heart"
              color="error"
              onPress={() => handlePress('red')}
              tooltip="Red Heart"
            />
            <IconButton
              icon="check"
              color="success"
              onPress={() => handlePress('green')}
              tooltip="Green Check"
            />
            <IconButton
              icon="info"
              color="primary"
              onPress={() => handlePress('blue')}
              tooltip="Blue Info"
            />
            <IconButton
              icon="warning"
              color="warning"
              onPress={() => handlePress('orange')}
              tooltip="Orange Warning"
            />
            <IconButton
              icon="star"
              color="#9333ea"
              radius="xl"
              onPress={() => handlePress('purple')}
              tooltip="Purple Star (Circular)"
            />
          </Row>
        </Block>
      </Card>
      {/* Common Use Cases */}
      <Card p="lg" variant="outline">
        <Block>
          <Text variant="h6">Common Use Cases</Text>
          {/* Toolbar */}
          <Block>
            <Text size="sm" weight="medium">Toolbar Actions</Text>
            <Row gap="xs" align="center">
              <IconButton icon="undo" variant="ghost" size="sm" tooltip="Undo" />
              <IconButton icon="redo" variant="ghost" size="sm" tooltip="Redo" />
              <Divider orientation="vertical" style={{ height: 24 }} />
              <IconButton icon="bold" variant="ghost" size="sm" tooltip="Bold" />
              <IconButton icon="italic" variant="ghost" size="sm" tooltip="Italic" />
              <IconButton icon="underline" variant="ghost" size="sm" tooltip="Underline" />
              <Divider orientation="vertical" style={{ height: 24 }} />
              <IconButton icon="link" variant="ghost" size="sm" tooltip="Add Link" />
              <IconButton icon="image" variant="ghost" size="sm" tooltip="Add Image" />
            </Row>
          </Block>
          {/* Social Actions */}
          <Block>
            <Text size="sm" weight="medium">Social Actions (Circular)</Text>
            <Row gap="xs" align="center">
              <IconButton 
                icon="heart" 
                variant="outline" 
                radius="xl" 
                color="error"
                tooltip="Like" 
              />
              <IconButton 
                icon="message-circle" 
                variant="outline" 
                radius="xl" 
                color="primary"
                tooltip="Comment" 
              />
              <IconButton 
                icon="share" 
                variant="outline" 
                radius="xl" 
                color="success"
                tooltip="Share" 
              />
              <IconButton 
                icon="bookmark" 
                variant="outline" 
                radius="xl" 
                tooltip="Bookmark" 
              />
            </Row>
          </Block>
          {/* Navigation */}
          <Block>
            <Text size="sm" weight="medium">Navigation</Text>
            <Row gap="xs" align="center">
              <IconButton icon="chevron-left" variant="secondary" tooltip="Previous" />
              <IconButton icon="chevron-right" variant="secondary" tooltip="Next" />
              <IconButton icon="chevron-up" variant="secondary" tooltip="Up" />
              <IconButton icon="chevron-down" variant="secondary" tooltip="Down" />
              <IconButton icon="external-link" variant="secondary" tooltip="Open External" />
            </Row>
          </Block>
        </Block>
      </Card>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Image`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Image } from '@platform-blocks/react-ui-library';`
- Status: beta
- Category: media
- Docs: https://react-ui-library.com/components/Image
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Image

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `src` | string \| ImageSourcePropType | No |  | Remote image URI, or a bundled asset from `require('./photo.png')` |
| `source` | ImageSourcePropType | No |  | Image source object (alternative to src) |
| `alt` | string | No |  | Alternative text for accessibility |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `resizeMode` | 'cover' \| 'contain' \| 'stretch' \| 'repeat' \| 'center' | No |  | Image resize mode |
| `size` | SizeValue \| number | No |  | Image size preset |
| `w` | number \| string | No |  | Custom width |
| `h` | number \| string | No |  | Custom height |
| `aspectRatio` | number | No |  | Aspect ratio |
| `borderWidth` | number | No |  | Border width |
| `borderColor` | ColorValue | No |  | Border color |
| `rounded` | boolean | No |  | Whether image should be rounded |
| `circle` | boolean | No |  | Whether image should be circular |
| `fallback` | React.ReactNode | No |  | Fallback element to show on error |
| `loading` | React.ReactNode | No |  | Loading state element |
| `onLoad` | () => void | No |  | Called when image loads successfully |
| `onError` | (error: any) => void | No |  | Called when image fails to load |
| `onLoadStart` | () => void | No |  | Called when image starts loading |
| `onLoadEnd` | () => void | No |  | Called when image finishes loading (success or error) |
| `containerStyle` | StyleProp<ViewStyle> | No |  | Container style |
| `imageStyle` | StyleProp<ImageStyle> | No |  | Image style overrides |
| `testID` | string | No |  | Component test ID for testing |
| `style` | any | No |  | Additional CSS styles |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Sizes
ID: `Image.sizes` • Tags: size, layout • Category: layout • Status: stable • Since: 0.3.0

Set the `size` prop to any token (`xs`–`3xl`) to scale the image box, or pass `w`/`h` when you need exact dimensions.

```tsx
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==';
  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>
  );
}
```

### Basic
ID: `Image.basic` • Category: general

```tsx
return (
    <Card>
      <Text size="lg" weight="semibold" mb={16}>Basic Image Usage</Text>
      <Block>
        <Image 
          src={require('../../../../assets/images/scene-mountains.png')}
          alt="Mountain landscape"
          w={300}
          h={200}
        />
        <Text size="sm" color="gray.6">
          A simple image with specified dimensions
        </Text>
      </Block>
    </Card>
  );
}
```

### Fallback
ID: `Image.fallback` • Category: general

```tsx
return (
    <Card>
      <Text size="lg" weight="semibold" mb={16}>Image Fallback & Error Handling</Text>
      <Row gap={24} style={{ alignItems: 'flex-start', flexWrap: 'wrap' }}>
        <Block>
          <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 size="sm" mt={8}>With Icon Fallback</Text>
        </Block>
        <Block>
          <Image 
            src="https://another-invalid-url.com/image.jpg"
            w={120}
            h={80}
            fallback={
              <Text size="sm" color="gray.6" style={{ textAlign: 'center' }}>
                Image not found
              </Text>
            }
            alt="Failed to load"
          />
          <Text size="sm" mt={8}>With Text Fallback</Text>
        </Block>
      </Row>
      <Text size="sm" color="gray.6" mt={16}>
        When images fail to load, fallback content is displayed
      </Text>
    </Card>
  );
}
```

### Shapes
ID: `Image.shapes` • Category: general

```tsx
return (
    <Card>
      <Text size="lg" weight="semibold" mb={16}>Image Shapes</Text>
      <Row gap={24} style={{ alignItems: 'flex-start', flexWrap: 'wrap' }}>
        <Block style={{ alignItems: 'center' }}>
          <Image 
            src={require('../../../../assets/images/scene-lake.png')}
            size={80}
            alt="Default"
          />
          <Text size="sm" mt={8}>Default</Text>
        </Block>
        <Block style={{ alignItems: 'center' }}>
          <Image 
            src={require('../../../../assets/images/scene-lake.png')}
            size={80}
            rounded
            alt="Rounded"
          />
          <Text size="sm" mt={8}>Rounded</Text>
        </Block>
        <Block style={{ alignItems: 'center' }}>
          <Image 
            src={require('../../../../assets/images/scene-lake.png')}
            size={80}
            circle
            alt="Circle"
          />
          <Text size="sm" mt={8}>Circle</Text>
        </Block>
      </Row>
      <Text size="sm" color="gray.6" mt={16}>
        Shape variations: default, rounded corners, and circular
      </Text>
    </Card>
  );
}
```

### Spacing
ID: `Image.spacing` • Category: general

```tsx
return (
    <Card>
      <Text size="lg" weight="semibold" mb={16}>Universal Spacing Props</Text>
      <Block>
        {/* Auto margin example */}
        <View>
          <Text size="md" weight="medium" mb={8}>Auto Margin Example</Text>
          <View style={{ backgroundColor: '#f0f0f0', padding: 16 }}>
            <Image 
              src={require('../../../../assets/images/scene-meadow.png')}
              alt="Centered image"
              w={100}
              h={100}
              m="auto"
            />
          </View>
          <Text size="sm" color="gray.6" mt={4}>
            Image with m="auto" should be centered
          </Text>
        </View>
        {/* Theme spacing example */}
        <View>
          <Text size="md" weight="medium" mb={8}>Theme Spacing Values</Text>
          <View style={{ backgroundColor: '#f0f0f0', padding: 16 }}>
            <Image 
              src={require('../../../../assets/images/scene-meadow.png')}
              alt="Image with theme spacing"
              w={80}
              h={80}
              m="lg"
            />
          </View>
          <Text size="sm" color="gray.6" mt={4}>
            Image with m="lg" using theme spacing
          </Text>
        </View>
        {/* Numeric spacing example */}
        <View>
          <Text size="md" weight="medium" mb={8}>Numeric Spacing Values</Text>
          <View style={{ backgroundColor: '#f0f0f0', padding: 16 }}>
            <Image 
              src={require('../../../../assets/images/scene-meadow.png')}
              alt="Image with numeric spacing"
              w={60}
              h={60}
              m={20}
            />
          </View>
          <Text size="sm" color="gray.6" mt={4}>
            Image with m={`{20}`} using numeric spacing
          </Text>
        </View>
        {/* Zero margin example */}
        <View>
          <Text size="md" weight="medium" mb={8}>Zero Margin Example</Text>
          <View style={{ backgroundColor: '#f0f0f0', padding: 16 }}>
            <Image 
              src={require('../../../../assets/images/scene-meadow.png')}
              alt="Image with zero margin"
              w={60}
              h={60}
              m="0"
            />
          </View>
          <Text size="sm" color="gray.6" mt={4}>
            Image with m="0" should have no margin
          </Text>
        </View>
        {/* Mixed spacing props example */}
        <View>
          <Text size="md" weight="medium" mb={8}>Mixed Spacing Props</Text>
          <View style={{ backgroundColor: '#f0f0f0', padding: 16 }}>
            <Image 
              src={require('../../../../assets/images/scene-meadow.png')}
              alt="Image with mixed spacing"
              w={80}
              h={80}
              mx="auto"
              my="md"
              p="sm"
            />
          </View>
          <Text size="sm" color="gray.6" mt={4}>
            Image with mx="auto", my="md", p="sm"
          </Text>
        </View>
      </Block>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Indicator.md -->

# Indicator

The Indicator component renders a small dot or pill-shaped badge in the corner of a parent container — perfect for online status, unread counts, or "new" markers. Pass `label` for text content (the dot auto-expands to fit multi-digit counts); use `children` for arbitrary custom content like icons.

## Metadata

- Canonical name: `Indicator`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Indicator } from '@platform-blocks/react-ui-library';`
- Category: data
- Tags: indicator, badge, status, count, dot
- Docs: https://react-ui-library.com/components/Indicator
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Indicator

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | SizeValue \| number | No |  |  |
| `color` | string | No |  |  |
| `borderColor` | string | No |  |  |
| `borderWidth` | number | No |  |  |
| `placement` | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | No |  |  |
| `offset` | number | No |  |  |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `children` | React.ReactNode | No |  | 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 | No |  | 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'> | No |  | Override props applied to the label `<Text>` (style, weight, ff, size, color). |
| `invisible` | boolean | No |  |  |

## Examples

### Basic usage
ID: `Indicator.basic` • Tags: status, notification • Category: basics • Status: stable • Since: 0.4.0

Use `Indicator` to layer small notices on any container: position it at a corner, pair it with avatars for presence, or wrap children to show counters without building custom badges.

```tsx
return (
    <Block>
      <Block>
        <Text size="sm" weight="medium">
          Corner indicator
        </Text>
        <Block bg="#f5f5f7" radius="lg" p="lg" position="relative">
          <Text size="xs" color="secondary">
            Panel
          </Text>
          <Indicator placement="top-right" />
        </Block>
      </Block>
      <Block>
        <Text size="sm" weight="medium">
          Avatar status
        </Text>
        <Block position="relative" w={72} h={72} align="center" justify="center">
          <Avatar size="lg" fallback="JS" backgroundColor="#6366F1" />
          <Indicator placement="bottom-right" size="md" color="#22c55e" offset={2} />
        </Block>
      </Block>
      <Block>
        <Text size="sm" weight="medium">
          Numeric counter
        </Text>
        <Block
          w={72}
          h={72}
          bg="#e5e7eb"
          radius="lg"
          position="relative"
          align="center"
          justify="center"
        >
          <Text size="xs" color="secondary">
            Inbox
          </Text>
          <Indicator placement="top-right" size={20} offset={4}>
            <Text size="xs" weight="bold" color="white">
              5
            </Text>
          </Indicator>
        </Block>
      </Block>
    </Block>
  );
}
```

### Placements
ID: `Indicator.placements` • Tags: placement, offset • Category: basics • Status: stable • Since: 0.4.0

Control positioning by combining the `placement` prop (top/bottom + left/right) with `offset` to nudge the badge; add children inside `Indicator` when you need numeric or icon content.

```tsx
const cornerPlacements = [
  { label: 'Top left', placement: 'top-left', color: '#F59E0B' },
  { label: 'Top right', placement: 'top-right', color: '#10B981' },
  { label: 'Bottom left', placement: 'bottom-left', color: '#6366F1' },
  { label: 'Bottom right', placement: 'bottom-right', color: '#EF4444' },
] as const;
const offsetPlacements = [
  { label: '9 unread', placement: 'top-right', color: '#6366F1', value: '9', offset: 6 },
  { label: '2 new', placement: 'bottom-right', color: '#10B981', value: '2', offset: 4 },
] as const;
const Tile = ({ children }: { children: ReactNode }) => (
  <Block
    w={88}
    h={88}
    radius="lg"
    bg="#f5f5f7"
    position="relative"
    align="center"
    justify="center"
  >
    {children}
  </Block>
);
  return (
    <Block>
      <Block>
        <Text size="sm" weight="medium">
          Corner placements
        </Text>
        <Row gap="md" wrap="wrap">
          {cornerPlacements.map((placement) => (
            <Tile key={placement.placement}>
              <Text size="xs" color="secondary">
                {placement.label}
              </Text>
              <Indicator placement={placement.placement} color={placement.color} />
            </Tile>
          ))}
        </Row>
      </Block>
      <Block>
        <Text size="sm" weight="medium">
          Offset and content
        </Text>
        <Row gap="md" wrap="wrap">
          {offsetPlacements.map((placement) => (
            <Tile key={placement.label}>
              <Text size="xs" color="secondary">
                {placement.label}
              </Text>
              <Indicator
                placement={placement.placement}
                color={placement.color}
                size={22}
                offset={placement.offset}
              >
                <Text size="xs" weight="bold" color="white">
                  {placement.value}
                </Text>
              </Indicator>
            </Tile>
          ))}
        </Row>
      </Block>
    </Block>
  );
}
```

### Sizes
ID: `Indicator.sizes` • Tags: sizes, tokens • Category: basics • Status: stable • Since: 0.4.0

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
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl', 24] as const;
  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">{typeof size === 'number' ? `${size} (numeric)` : size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Statuses
ID: `Indicator.statuses` • Tags: presence, status • Category: basics • Status: stable • Since: 0.4.0

Map semantic states (online, idle, busy) to palette colors and cap large notification counts by rendering text inside `Indicator`—perfect for presence chips or inbox badges.

```tsx
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;
const notificationCounts = [3, 47, 99, 134, 1005];
  const theme = useTheme();
  const resolveColor = (palette: (typeof presenceStatuses)[number]['palette']) => {
    const swatch = (theme.colors as any)[palette];
    return Array.isArray(swatch) ? swatch[5] : swatch;
  };
  return (
    <Block>
      <Block>
        <Text size="sm" weight="medium">
          Presence indicators
        </Text>
        <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 placement="bottom-right" size={14} color={resolveColor(status.palette)} />
              </Block>
              <Text size="xs" color="secondary">
                {status.label}
              </Text>
            </Block>
          ))}
        </Row>
      </Block>
      <Block>
        <Text size="sm" weight="medium">
          Max count handling
        </Text>
        <Row gap="md" wrap="wrap">
          {notificationCounts.map((count) => {
            const display = count > 99 ? '99+' : `${count}`;
            return (
              <Block key={count} w={72} h={72} position="relative" align="center" justify="center">
                <Indicator placement="top-right" size={24} offset={4} color={theme.colors.error[5]}>
                  <Text size="xs" weight="bold" color="white">
                    {display}
                  </Text>
                </Indicator>
                <Text size="xs" color="secondary">
                  {count}
                </Text>
              </Block>
            );
          })}
        </Row>
      </Block>
    </Block>
  );
}
```

### Labels & counts
ID: `Indicator.labels` • Tags: label, count, labelProps, customization • Category: general • Status: stable • Since: 1.0.0

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
const Anchor = ({ children }: { children?: React.ReactNode }) => (
  <View
    style={{
      width: 48,
      height: 48,
      borderRadius: 24,
      backgroundColor: '#e5e7eb',
      alignItems: 'center',
      justifyContent: 'center',
      position: 'relative',
    }}
  >
    {children}
  </View>
);
  return (
    <Block>
      <Block>
        <Text size="sm" color="muted">Numeric counts</Text>
        <Row gap="lg">
          <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>
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Monospace badge with custom label styling
        </Text>
        <Row gap="lg">
          <Avatar fallback="JS" backgroundColor="#a855f7" />
          <Anchor>
            <Indicator
              size={22}
              color="#0ea5e9"
              label="42"
              labelProps={{ ff: 'monospace', weight: '700' }}
            />
          </Anchor>
          <Anchor>
            <Indicator
              size={22}
              color="#10b981"
              label="NEW"
              labelProps={{ uppercase: true, tracking: 1, size: 9 }}
            />
          </Anchor>
        </Row>
      </Block>
      <Block>
        <Text size="sm" color="muted">Custom child content (children, not label)</Text>
        <Row gap="lg">
          <Anchor>
            <Indicator size={16} color="#10b981">
              {/* anything you want — icon, custom shape, etc. */}
              <View style={{ width: 6, height: 6, borderRadius: 3, backgroundColor: '#fff' }} />
            </Indicator>
          </Anchor>
        </Row>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Input.md -->

# Input

A versatile text input component that provides a consistent interface for text entry across different platforms. The Input component supports various types, validation states, and accessibility features.

## Metadata

- Canonical name: `Input`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Input } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: input
- Tags: input, form, text, validation
- Docs: https://react-ui-library.com/components/Input
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Input

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `type` | 'text' \| 'password' \| 'email' \| 'tel' \| 'number' \| 'search' | No | 'text' | Input type - determines styling and behavior |
| `validation` | ValidationRule[] | No |  | Input validation rules |
| `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' | No |  | Auto-complete type |
| `keyboardType` | KeyboardTypeOptions | No |  | Keyboard type for mobile |
| `multiline` | boolean | No |  | Whether input is multiline |
| `numberOfLines` | number | No |  | Number of lines for multiline input |
| `minLines` | number | No | 1 | Minimum number of lines for multiline input (default: 1) |
| `maxLines` | number | No |  | Maximum number of lines for multiline input |
| `maxLength` | number | No |  | Maximum length |
| `secureTextEntry` | boolean | No |  | Whether to secure text entry |
| `textInputProps` | ExtendedTextInputProps | No |  | Additional TextInput props |
| `inputRef` | React.Ref<any> | No |  | Ref to underlying TextInput (focus control) |
| `autoCapitalize` | RNTextInputProps['autoCapitalize'] | No |  | Text auto-capitalization behavior |
| `autoCorrect` | boolean | No |  | Whether to enable auto-correct |
| `autoFocus` | boolean | No |  | Whether to auto-focus on mount |
| `returnKeyType` | RNTextInputProps['returnKeyType'] | No |  | Return key type for soft keyboard |
| `blurOnSubmit` | boolean | No |  | Whether to blur on submit |
| `selectTextOnFocus` | boolean | No |  | Select all text on focus |
| `textContentType` | RNTextInputProps['textContentType'] | No |  | iOS text content type for autofill |
| `textAlign` | RNTextInputProps['textAlign'] | No |  | Text alignment |
| `spellCheck` | boolean | No |  | Whether spell check is enabled |
| `inputMode` | RNTextInputProps['inputMode'] | No |  | Input mode (modern alternative to keyboardType) |
| `enterKeyHint` | RNTextInputProps['enterKeyHint'] | No |  | Hint for the enter key |
| `selectionColor` | string | No |  | Color of the text selection handles and highlight |
| `showSoftInputOnFocus` | boolean | No |  | Whether to show the soft keyboard on focus |
| `editable` | boolean | No |  | Whether the field is read-only (alias for !editable) |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `value` | string | No |  | Input value |
| `onChangeText` | (text: string) => void | No |  | Change handler |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `placeholder` | string | No |  | Input placeholder |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No | 'md' | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `Input.basic` • Tags: basic, input, text • Category: basics • Status: stable • Since: 1.0.0

Basic text input with label, placeholder, and value handling.

```tsx
const [value, setValue] = useState('');
  return (
    <Input
      label="Full name"
      placeholder="Enter your full name"
      value={value}
      onChangeText={setValue}
    />
  );
}
```

### Variants
ID: `Input.variants` • Tags: variants, filled, outline, unstyled • Category: basics • Status: stable • Since: 1.0.0

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
return (
    <Block>
      <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
ID: `Input.types` • Tags: types, email, password, number, tel • Category: usage • Status: stable • Since: 1.0.0

Set `type` to switch the keyboard and browser behaviour — email, password, number, and tel are all supported.

```tsx
return (
    <Block>
      <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
ID: `Input.validation` • Tags: validation, error, required, helper • Category: usage • Status: stable • Since: 1.0.0

Pass `error` to show a validation message, `required` to mark the field, and `helperText` for guidance. `disabled` blocks editing.

```tsx
const isValidEmail = (email: string) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
  const [email, setEmail] = useState('');
  return (
    <Block>
      <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
ID: `Input.multiline` • Tags: input, multiline • Category: behavior • Status: stable • Since: 1.0.0

Pair `multiline` with `minLines`/`maxLines` to auto-expand, or with `numberOfLines` for a fixed height.

```tsx
const [autoText, setAutoText] = useState('');
  const [fixedText, setFixedText] = useState('');
  return (
    <Block>
      <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
ID: `Input.slot-styling` • Tags: startSection, endSection, clearable, placeholderTextColor, slot-props, customization • Category: usage • Status: stable • Since: 1.0.0

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
const [workspace, setWorkspace] = useState('');
  const [search, setSearch] = useState('');
  return (
    <Block>
      <Input
        label="URL"
        placeholder="my-workspace"
        value={workspace}
        onChangeText={setWorkspace}
        startSection={<Text ff="monospace" color="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://react-ui-library.com/llms/components/Joystick.md -->

# Joystick

Joystick is a two-axis positional input. In its default `circle` shape it behaves like a physical stick — the handle rides the rim at full deflection and springs back to centre when released. As a `square` it becomes an XY pad: each axis clamps on its own so the corners are reachable, and the handle stays where it is left.

Both axes are normalized to −1…1. `y` is up-positive by default, matching how a gamepad axis reads; pass `invertY={false}` to follow screen space instead.

`deadZone` zeroes small deflections and rescales what is left, so the value still spans the full range past the threshold rather than jumping to the dead-zone size. `step` snaps each axis, `lockAxis` restricts travel to one direction, and `showCrosshair` adds accent rules that track the handle — the usual XY-pad readout.

The gesture runs on the shared `useDragGesture` hook, which means a drag that leaves the pad keeps tracking the finger instead of handing the touch back to the page. Arrow keys nudge by `keyboardStep` on web, `Home` and `Escape` recentre, and VoiceOver/TalkBack get increment and decrement actions.

## Metadata

- Canonical name: `Joystick`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Joystick } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: joystick, xy, pad, gesture, two-axis, input
- Docs: https://react-ui-library.com/components/Joystick
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Joystick

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | JoystickValue | No |  | Controlled value. Both axes are normalized to −1…1. |
| `defaultValue` | JoystickValue | No |  | Initial value while uncontrolled. Default `{ x: 0, y: 0 }`. |
| `onChange` | (value: JoystickValue) => void | No |  | Fired for every position change, including each frame of a drag. |
| `onChangeEnd` | (value: JoystickValue) => void | No |  | Fired once when the gesture ends, with the value it settled on. |
| `onChangeStart` | (value: JoystickValue) => void | No |  | Fired when a drag or keyboard interaction begins. |
| `shape` | JoystickShape | No | '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 | No |  | 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' | No |  | Restrict travel to a single axis. |
| `deadZone` | number | No | 0 | Report `0` until the handle travels this far from centre (0–1). Default `0`. |
| `step` | number | No | 0 | Snap each axis to this increment. Default `0` (continuous). |
| `keyboardStep` | number | No |  | Increment applied by a single arrow key press. Defaults to `step` or `0.1`. |
| `invertY` | boolean | No | true | Report a positive `y` when the handle is pushed up. Default `true`. |
| `size` | ComponentSizeValue | No | 'md' | Outer size in px, or a size token. Default `'md'`. |
| `handleSize` | number | No |  | Handle diameter in px. Defaults to ~32% of `size`. |
| `variant` | JoystickVariant | No | 'default' | Visual preset. Default `'default'`. |
| `color` | string | No |  | Accent color: a palette token (`'primary'`), `'primary.6'` shade syntax, or any CSS color. |
| `baseColor` | string | No |  | Base surface color override. |
| `handleColor` | string | No |  | Handle color override. |
| `showGuides` | boolean | No | true | Draw the static centre guides. Default `true`. |
| `showCrosshair` | boolean | No | false | Draw accent rules that track the handle on each axis — the XY-pad readout. Default `false`. |
| `valueLabel` | boolean \| ((value: JoystickValue) => string) | No | false | Render the current value under the pad. Pass a function to format it. |
| `label` | React.ReactNode | No |  | Field label rendered above the pad. |
| `disabled` | boolean | No | false | Ignore all input and dim the control. |
| `readOnly` | boolean | No | false | Ignore all input while keeping full contrast. |
| `transitionDuration` | number | No |  | Spring-back / keyboard transition duration in ms. Default `220`. |
| `style` | StyleProp<ViewStyle> | No |  | Root style. |
| `baseStyle` | StyleProp<ViewStyle> | No |  | Style for the pad surface. |
| `handleStyle` | StyleProp<ViewStyle> | No |  | Style for the handle. |
| `valueLabelStyle` | StyleProp<TextStyle> | No |  | Style for the value label text. |
| `accessibilityLabel` | string | No |  |  |
| `testID` | string | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `Joystick.basic` • Tags: basic, joystick, stick • Category: basics • Status: stable • Since: 1.1.0

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
const [value, setValue] = useState({ x: 0, y: 0 });
  return (
    <Joystick
      value={value}
      onChange={setValue}
      showCrosshair
      valueLabel
    />
  );
}
```

### XY pad
ID: `Joystick.xy-pad` • Tags: xy, pad, square, filter • Category: variants • Status: stable • Since: 1.1.0

`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
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="dimmed">Cutoff {cutoff} Hz · Resonance {resonance}</Text>
    </Flex>
  );
}
```

### Dead zone and steps
ID: `Joystick.dead-zone` • Tags: deadZone, step, snapping • Category: features • Status: stable • Since: 1.1.0

`deadZone` ignores small deflections around centre and rescales the rest, so full travel still reports 1. `step` snaps each axis onto a grid.

```tsx
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
ID: `Joystick.axis-lock` • Tags: lockAxis, single-axis, pan • Category: features • Status: stable • Since: 1.1.0

`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
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="dimmed">{position}</Text>
    </Flex>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/KeyCap.md -->

# KeyCap

A visual component for displaying keyboard keys, shortcuts, and key combinations with proper styling.

## Metadata

- Canonical name: `KeyCap`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { KeyCap } from '@platform-blocks/react-ui-library';`
- Category: typography
- Tags: keycap, keyboard, shortcut, key, hotkey
- Docs: https://react-ui-library.com/components/KeyCap
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/KeyCap

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | ReactNode | Yes |  | The key or text to display |
| `size` | ComponentSizeValue | No | 'md' | Size variant of the key cap |
| `variant` | 'default' \| 'minimal' \| 'outline' \| 'filled' | No | 'default' | Visual variant of the key cap |
| `color` | 'primary' \| 'secondary' \| 'gray' \| 'success' \| 'warning' \| 'error' | No | 'gray' | Color scheme for the key cap |
| `animateOnPress` | boolean | No | true | Whether the key should animate when the actual key is pressed Only works on web platforms |
| `transitionDuration` | number | No | 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 | No |  | The actual key code to listen for (e.g., 'Enter', 'Space', 'Escape') If provided, the component will animate when this key is pressed |
| `modifiers` | Array<'ctrl' \| 'cmd' \| 'alt' \| 'shift' \| 'meta'> | No |  | Modifier keys that must be pressed along with the main key |
| `pressed` | boolean | No |  | Whether the key cap should appear pressed |
| `onKeyPress` | () => void | No |  | Callback when the key combination is pressed |
| `testID` | string | No |  | Custom test ID for testing |
| `fontFamily` | string | No |  | Custom font family (overrides the default monospace stack) |
| `ff` | string | No |  | Shorthand alias for `fontFamily` |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic Usage
ID: `KeyCap.basic` • Tags: basic, keyboard • Category: usage • Status: stable • Since: 1.0.0

Basic keyboard key display for showing shortcuts and key combinations.

```tsx
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
ID: `KeyCap.sizes` • Tags: sizes • Category: usage • Status: stable • Since: 1.0.0

Different sizes for KeyCap components from extra small to extra large.

```tsx
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
ID: `KeyCap.variants` • Tags: variants, styles • Category: usage • Status: stable • Since: 1.0.0

Different visual variants for KeyCap components including default, filled, minimal, and outline styles.

```tsx
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
ID: `KeyCap.modifiers` • Tags: modifiers, shortcuts, combinations • Category: usage • Status: stable • Since: 1.0.0

KeyCap components with modifier keys for displaying keyboard shortcuts and key combinations.

```tsx
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://react-ui-library.com/llms/components/Knob.md -->

# Knob

The Knob component provides a rotary control for adjusting values with touch, mouse, and keyboard input. It supports snapping to marks, internal value labels, and accessible field headers for external labels.

## Metadata

- Canonical name: `Knob`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Knob } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: knob, dial, rotary, gesture, input
- Docs: https://react-ui-library.com/components/Knob
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Knob

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `behavior` | KnobBehavior | No | 'level' | What kind of control this is: how it behaves and what it reads out. @default 'level' |
| `variant` | KnobVariant | No | 'default' | Visual style preset. Merged under `appearance`, so single properties stay overridable. Behavior values (`level`, `stepped`, …) still work here at runtime but are deprecated — pass them to `behavior` instead. @default 'default' |
| `mode` | 'bounded' \| 'endless' | No |  | Interaction mode for bounded or endless rotary behavior |
| `value` | number | No |  | Controlled value |
| `defaultValue` | number | No |  | Uncontrolled initial value |
| `min` | number | No |  | Minimum selectable value |
| `max` | number | No |  | Maximum selectable value |
| `step` | number | No |  | Step increment applied when interacting |
| `onChange` | (value: number) => void | No |  | Called on every value change |
| `onChangeEnd` | (value: number) => void | No |  | Called after interaction completes |
| `onScrubStart` | () => void | No |  | Fired when the user begins dragging |
| `onScrubEnd` | () => void | No |  | Fired when the user ends dragging |
| `size` | ComponentSizeValue | No |  | Size token (`xs`–`3xl`) or an explicit diameter in pixels |
| `thumbSize` | number | No |  | Diameter of the thumb indicator, in pixels. Defaults to a ratio of the resolved size. |
| `disabled` | boolean | No |  | Disable all user interaction |
| `readOnly` | boolean | No |  | Prevent interaction but keep visual state |
| `formatLabel` | (value: number) => ReactNode | No |  | Custom formatter for the value label |
| `withLabel` | boolean | No |  | Render the value label inside the knob |
| `valueLabel` | KnobValueLabelConfig \| false | No |  | Structured configuration for the value label block |
| `marks` | KnobMark[] | No |  | Optional marks rendered around the control |
| `restrictToMarks` | boolean | No |  | Restrict interaction to the supplied marks |
| `label` | ReactNode | No |  | Optional visual label rendered outside the knob |
| `description` | ReactNode | No |  | Optional helper text rendered with the label |
| `labelPosition` | 'left' \| 'right' \| 'top' \| 'bottom' | No |  | Placement for the external label |
| `style` | StyleProp<ViewStyle> | No |  | Style overrides for the outer container |
| `trackStyle` | StyleProp<ViewStyle> | No |  | Style overrides for the circular track |
| `thumbStyle` | StyleProp<ViewStyle> | No |  | Style overrides for the thumb |
| `markLabelStyle` | StyleProp<TextStyle> | No |  | Style overrides for mark labels |
| `testID` | string | No |  | Accessibility identifier |
| `accessibilityLabel` | string | No |  | Screen reader label |
| `appearance` | KnobAppearance | No |  | Unified surface styling and interaction overrides |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |

## Examples

### Basic
ID: `Knob.basic` • Tags: basic, knob, control • Category: basics • Status: experimental • Since: 1.0.0

Controlled knob with percentage formatting and a mirrored readout below the dial.

```tsx
const [value, setValue] = useState(90);
  return (
    <Knob
      value={value}
      onChange={setValue}
      valueLabel={{
        formatter: (current) => Math.round(current),
        suffix: '°',
      }}
    />
  );
}
```

### Events
ID: `Knob.events` • Tags: events, scrubbing, callbacks • Category: behavior • Status: experimental • Since: 1.0.0

Demonstrates live value, committed value, and scrubbing lifecycle callbacks.

```tsx
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
        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
ID: `Knob.variants` • Tags: variant, style, preset • Category: variants • Status: experimental • Since: 1.0.0

`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
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' },
];
  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
              value={value}
              onChange={setValue}
              variant={variant}
            />
            <Text size="sm" weight="600">{variant}</Text>
          </Block>
        ))}
    </Block>
  );
}
```

### Endless
ID: `Knob.endless` • Tags: endless, encoder, rotation • Category: variants • Status: experimental • Since: 1.0.0

Endless mode resets the dial each turn while tracking the cumulative rotation value.

```tsx
const [value, setValue] = useState(0);
  const normalizedAngle = useMemo(() => ((value % 360) + 360) % 360, [value]);
  const rotations = useMemo(() => value / 360, [value]);
  return (
    <Block fullWidth>
      <Knob
        value={value}
        onChange={setValue}
        behavior="endless"
        valueLabel={{
          formatter: () => `${Math.round(normalizedAngle)}°`,
          secondary: {
            formatter: () => `${rotations.toFixed(2)} turns`,
          },
        }}
      />
    </Block>
  );
}
```

### Dual Readout
ID: `Knob.dual-readout` • Tags: dual, valueLabel • Category: variants • Status: experimental • Since: 1.1.0

Demonstrates the `dual` behavior with a center frequency label and a derived percentage below the knob.

```tsx
const [cutoff, setCutoff] = useState(3200);
  const percent = useMemo(() => Math.round(((cutoff - 200) / (8000 - 200)) * 100), [cutoff]);
  return (
    <Block fullWidth>
      <Knob
        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
ID: `Knob.status-selector` • Tags: status, behavior • Category: variants • Status: experimental • Since: 1.1.0

Highlights the `status` behavior with icon-enhanced marks, accent colors, and the active scene named directly beneath the icon in the center slot.

```tsx
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
        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>
  );
}
```

### Segmented Progress
ID: `Knob.segment-progress` • Tags: segments, progress, ring, gauge • Category: features • Status: experimental • Since: 1.0.0

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
const ZONES = [
  { value: 60, color: '#22c55e' },
  { value: 25, color: '#f59e0b' },
  { value: 15, color: '#ef4444' },
];
  const [load, setLoad] = useState(72);
  return (
    <Block align="center">
      <Knob
        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
ID: `Knob.tick-selector` • Tags: ticks, selector, detent, active • Category: features • Status: experimental • Since: 1.0.0

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
// 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 }));
  const [position, setPosition] = useState(3);
  return (
    <Block >
      <Knob
        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>
  );
}
```

### Compound Panning
ID: `Knob.compound-panning` • Category: general

Stereo-style panning knob composed with `Knob.Root`, split progress, and custom tick labels to highlight the compound sub-component API.

```tsx
// 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';
  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
        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" color="secondary">
        Stereo balance · {readout}
      </Text>
    </Block>
  );
}
```

### Pointer Clock
ID: `Knob.pointer-clock` • Category: general

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
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>
);
  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" weight="700">
        {formatTime(time.minutes)}
      </Text>
    </Block>
  );
}
```

### Semicircle Gauge
ID: `Knob.semicircle-gauge` • Category: general

Semicircle gauge layout that uses `Knob.Root` with custom ring thickness, contiguous progress, and a pointer hand for instrumentation-style readouts.

```tsx
const TEMPERATURE_STOPS = [0, 25, 50, 75, 100];
  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
        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" color="secondary">
        Thermal headroom · {status}
      </Text>
    </Block>
  );
}
```

### Tick Layers
ID: `Knob.tick-layers` • Category: general

Stacks two tick layers on one dial: labelled lines driven by `marks`, over a finer dot scale from an explicit step list.

```tsx
const LEVEL_MARKS = [
  { value: 0, label: 'Mute' },
  { value: 25, label: 'Low' },
  { value: 50, label: 'Mid' },
  { value: 75, label: 'High' },
  { value: 100, label: 'Max' },
];
  const [level, setLevel] = useState(48);
  return (
    <Block align="center">
      <Knob
        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
ID: `Knob.interaction-modes` • Tags: interaction, gestures, scroll • Category: behavior • Status: experimental • Since: 1.0.0

Showcases spin, vertical-slide, horizontal-slide, and scroll gestures enabled through `appearance.interaction`, updating the label as each mode locks in.

```tsx
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>);
  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" weight="500">
            Multimodal control
          </Text>
          <Knob
            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
                  color={activeMode === mode.key ? theme.text.primary : theme.text.muted}
                >
                  {mode.name}
                </DataList.ItemLabel>
                <DataList.ItemValue color={theme.text.secondary}>{mode.detail}</DataList.ItemValue>
              </DataList.Item>
            ))}
          </DataList>
        </Block>
      </Row>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Link.md -->

# Link

A versatile component for creating styled hyperlinks and navigation elements with hover states and accessibility features.

## Metadata

- Canonical name: `Link`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Link } from '@platform-blocks/react-ui-library';`
- Category: navigation
- Tags: link, anchor, navigation, url, href
- Docs: https://react-ui-library.com/components/Link
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Link

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | Yes |  | Link text content |
| `href` | string | No |  | URL or handler for the link |
| `onPress` | () => void | No |  | Custom onPress handler (overrides href) |
| `size` | SizeValue | No | 'lg' | Size of the link text (default: 'lg' = 16px to match Text component) |
| `color` | 'primary' \| 'secondary' \| 'success' \| 'warning' \| 'error' \| 'gray' \| 'inherit' \| string | No |  | Color variant or custom color string |
| `variant` | 'default' \| 'subtle' \| 'hover-underline' | No | 'default' | Link variant |
| `disabled` | boolean | No | false | Whether the link is disabled |
| `external` | boolean | No | false | Whether to show external link indicator |
| `style` | ViewStyle | No |  | Custom style for container |
| `textStyle` | TextStyle | No |  | Custom style for text |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `target` | '_blank' \| '_self' | No | '_self' | Whether this link opens in a new tab/window (web only) |
| `fontFamily` | string | No |  | Custom font family (overrides theme font) |
| `ff` | string | No |  | Shorthand alias for `fontFamily` |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Inline Links
ID: `Link.basic` • Tags: link • Category: usage • Status: stable • Since: 1.0.0

Embed links directly inside supporting copy to guide readers toward related resources.

```tsx
const resources = [
  { href: '#brand', label: 'brand guidelines' },
  { href: '#voice', label: 'voice and tone guide' },
  { href: '#releases', label: 'release checklist' },
];
const [brandGuide, voiceGuide, releaseChecklist] = resources;
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Use `Link` inline with body copy to direct readers to additional guidance without breaking the flow of text.
        </Text>
        <Text size="sm">
          Before publishing, review the{' '}
          <Link href={brandGuide.href}>{brandGuide.label}</Link>, consult our{' '}
          <Link href={voiceGuide.href}>{voiceGuide.label}</Link>, and confirm each launch in the{' '}
          <Link href={releaseChecklist.href}>{releaseChecklist.label}</Link>.
        </Text>
      </Block>
    </Card>
  );
}
```

### External Destinations
ID: `Link.external` • Tags: link, external • Category: usage • Status: stable • Since: 1.0.0

Use the `external` prop when pointing to destinations outside the current shell.

```tsx
const references = [
  { href: 'https://reactnative.dev', label: 'React Native documentation', color: 'primary' },
  { href: 'https://expo.dev', label: 'Expo documentation', color: 'secondary' },
  { href: 'mailto:support@example.com', label: 'Email support', color: 'gray' },
];
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Set `external` to ensure the link opens outside the app shell and receives the proper accessibility attributes.
        </Text>
        {references.map((resource) => (
          <Link key={resource.href} href={resource.href} external color={resource.color}>
            {resource.label}
          </Link>
        ))}
      </Block>
    </Card>
  );
}
```

### Size Options
ID: `Link.sizes` • Tags: link, sizing • Category: appearance • Status: stable • Since: 1.0.0

Demonstrate how the `size` token scales link typography and spacing.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  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
ID: `Link.variants` • Tags: link, appearance • Category: appearance • Status: stable • Since: 1.0.0

Compare persistent and hover-only underlines alongside subtle variants.

```tsx
const linkVariants = [
  { label: 'Default underline', variant: 'default' as const, description: 'Underline is always visible for maximum affordance.' },
  { label: 'Hover underline', variant: 'hover-underline' as const, description: 'Underline appears on hover for denser layouts.' },
  { label: 'Subtle primary', variant: 'subtle' as const, color: 'primary', description: 'Muted style that still matches the brand palette.' },
  { label: 'Subtle gray', variant: 'subtle' as const, color: 'gray', description: 'Pair with neutral layouts or footers.' },
];
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Choose a `variant` that matches the surrounding density while keeping the link discoverable.
        </Text>
        {linkVariants.map((entry) => (
          <Block key={entry.label}>
            <Link href="#" variant={entry.variant} color={entry.color}>{entry.label}</Link>
            <Text size="xs" color="secondary">{entry.description}</Text>
          </Block>
        ))}
      </Block>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/ListGroup.md -->

# ListGroup

The ListGroup component provides an organized list structure with items, dividers, and sections for displaying grouped content.

## Metadata

- Canonical name: `ListGroup`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ListGroup } from '@platform-blocks/react-ui-library';`
- Category: display
- Tags: list, group, items, divider, sections
- Docs: https://react-ui-library.com/components/ListGroup
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ListGroup

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | Yes |  |  |
| `variant` | 'default' \| 'bordered' \| 'flush' | No | 'default' |  |
| `size` | ComponentSizeValue | No | 'md' |  |
| `radius` | 'sm' \| 'md' \| 'lg' \| number | No | 'md' |  |
| `dividers` | boolean | No | true |  |
| `insetDividers` | boolean | No | false |  |
| `style` | StyleProp<ViewStyle> | No |  |  |

## Examples

### Basic Usage
ID: `ListGroup.basic` • Tags: list, items • Category: basics • Status: stable • Since: 1.0.0

Compose a vertical list by nesting `ListGroupItem` elements inside a `ListGroup`. Use the `variant` prop to switch between `default`, `bordered`, and `flush` styles.

```tsx
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
ID: `ListGroup.two-line` • Tags: list, label, description, settings • Category: basics • Status: stable • Since: 1.0.0

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
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>
  );
}
```

### Trailing value
ID: `ListGroup.trailing-value` • Tags: list, value, alignment, sections • Category: composition • Status: stable • Since: 1.0.0

`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
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://react-ui-library.com/llms/components/Loader.md -->

# Loader

A animated loading component for indicating ongoing processes and loading states with various sizes and styles.

## Metadata

- Canonical name: `Loader`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Loader } from '@platform-blocks/react-ui-library';`
- Category: feedback
- Tags: loader, loading, progress, indicator, animation
- Docs: https://react-ui-library.com/components/Loader
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Loader

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | SizeValue | No | 'md' | Size of the loader - can be a size token or number |
| `color` | string | No |  | Color of the loader |
| `variant` | LoaderVariant | No | 'oval' | Variant of the loader |
| `speed` | number | No | 1000 | Animation speed in milliseconds |
| `style` | StyleProp<ViewStyle> | No |  | Container style |
| `testID` | string | No |  | Test ID for testing |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Loader.basic` • Tags: variant • Category: basics • Status: stable • Since: 1.0.0

Pick a loader `variant` to match the type of busy indicator you need for a loading state.

```tsx
return (
    <Row gap="lg" align="center">
      <Loader variant="oval" />
      <Loader variant="bars" />
      <Loader variant="dots" />
    </Row>
  );
}
```

### Sizes
ID: `Loader.sizes` • Tags: size • Category: layout • Status: stable • Since: 1.0.0

Set the `size` token to align loaders with other controls, from `xs` indicators up to `3xl` spinners.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  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>
  );
}
```

### Colors
ID: `Loader.colors` • Tags: color, theme • Category: theming • Status: stable • Since: 1.0.0

Pull palette values from `useTheme()` and pass them to the `color` prop to align loaders with your semantic colors.

```tsx
interface LoaderSwatch {
  label: string;
  color: string;
}
  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 minW={88}>
            <Text variant="small" color="muted">
              {label}
            </Text>
          </Block>
          <Loader variant="oval" color={color} />
          <Loader variant="bars" color={color} />
          <Loader variant="dots" color={color} />
        </Row>
      ))}
    </Block>
  );
}
```

### Speed
ID: `Loader.speed` • Category: general

```tsx
// `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 },
];
  return (
    <Block>
      {SPEEDS.map(({ label, value }) => (
        <Row key={value} gap="lg" align="center">
          <Block minW={96}>
            <Text variant="small" weight="semibold">
              {label}
            </Text>
            <Text variant="small" color="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://react-ui-library.com/llms/components/LoadingOverlay.md -->

# LoadingOverlay

`LoadingOverlay` composits the core `Overlay` and `Loader` primitives to create a convenient helper for blocking interactions with a visual indicator during asynchronous operations. Render it inside a relatively positioned container, toggle `visible` during asynchronous work, and customize appearance by passing `overlayProps` or `loaderProps`.

## Metadata

- Canonical name: `LoadingOverlay`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { LoadingOverlay } from '@platform-blocks/react-ui-library';`
- Status: beta
- Category: feedback
- Docs: https://react-ui-library.com/components/LoadingOverlay
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/LoadingOverlay

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `visible` | boolean | No | false | Controls visibility of the loading overlay. |
| `zIndex` | number | No |  | z-index applied to the overlay container. Overrides value defined in overlayProps when provided. |
| `overlayProps` | OverlayProps | No |  | Props forwarded to the underlying Overlay component. |
| `loaderProps` | LoaderProps | No |  | Props forwarded to the Loader component. |
| `loader` | ReactNode | No |  | Custom loader content. When provided, Loader component is not rendered. |

## Examples

### Form blocking
ID: `LoadingOverlay.basic` • Tags: overlays, loading • Category: feedback • Status: stable • Since: 1.0.0

Locks a simple form while background work finishes and keeps the loader aligned with the card container.

```tsx
type TextFieldConfig = {
  key: string;
} & Pick<ComponentProps<typeof Input>, 'label' | 'placeholder' | 'keyboardType' | 'secureTextEntry'>;
const TEXT_FIELDS: TextFieldConfig[] = [
  { key: 'first-name', label: 'First name', placeholder: 'Jane' },
  { key: 'last-name', label: 'Last name', placeholder: 'Doe' },
  {
    key: 'email',
    label: 'Email',
    placeholder: 'jane@react-ui-library.com',
    keyboardType: 'email-address',
  },
  {
    key: 'password',
    label: 'Password',
    placeholder: '••••••••',
    secureTextEntry: true,
  },
];
  const [visible, setVisible] = useState(false);
  return (
    <Block align="center" style={styles.wrapper}>
      <Block style={styles.section}>
        <Card style={styles.card} shadow="lg">
          <LoadingOverlay
            visible={visible}
            overlayProps={{ blur: 12, radius: 'md', backgroundOpacity: 0.4 }}
            loaderProps={{ variant: 'dots', size: 'lg' }}
          />
          <Block>
            <Block>
              <Text variant="h4" weight="semibold">
                Account details
              </Text>
              <Text variant="p" color="muted">
                Pause form interaction while requests finish and keep the layout intact.
              </Text>
            </Block>
            <Block>
              {TEXT_FIELDS.map(({ key, ...field }) => (
                <Input key={key} disabled={visible} {...field} />
              ))}
              <Switch label="Subscribe to product updates" disabled={visible} />
            </Block>
          </Block>
        </Card>
        <Button onPress={() => setVisible((current) => !current)}>
          {visible ? 'Stop loading' : 'Simulate loading'}
        </Button>
      </Block>
      <Text variant="small" color="muted" align="center">
        LoadingOverlay anchors to a relative container and dims the content while the loader animates.
      </Text>
    </Block>
  );
}
const styles = StyleSheet.create({
  wrapper: {
    width: '100%',
  },
  section: {
    width: '100%',
    maxWidth: 480,
    alignSelf: 'center',
  },
  card: {
    width: '100%',
  },
});
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Markdown`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Markdown } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: data
- Docs: https://react-ui-library.com/components/Markdown
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Markdown

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | string | Yes |  |  |
| `defaultCodeLanguage` | string | No |  | Override default code block language guess |
| `maxHeadingLevel` | number | No |  | Max heading level to render (others downgraded) |
| `allowHtml` | boolean | No |  | Whether to render inline HTML literally (ignored for now) |
| `components` | Partial<MarkdownComponentMap> | No |  | Custom renderer overrides |
| `onLinkPress` | (href: string) => void | No |  | Optional handler invoked when a markdown link is pressed |
| `fontFamily` | string | No |  | Custom font family applied to all rendered text (overrides the theme font) |
| `ff` | string | No |  | Shorthand alias for `fontFamily` |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Markdown.basic` • Category: general

Simple markdown rendering with headers, lists, and text formatting.

```tsx
const CONTENT = `# 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;\``;
  return (
    <Block fullWidth>
      <Markdown>{CONTENT}</Markdown>
      <Text size="sm" color="secondary">
        Rendered using the default Markdown renderer
      </Text>
    </Block>
  );
}
```

### Code Blocks
ID: `Markdown.code` • Category: general

Markdown rendering with syntax-highlighted code blocks.

```tsx
const CONTENT = `# Code examples
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);\``;
  return (
    <Block fullWidth>
      <Markdown>{CONTENT}</Markdown>
      <Text size="sm" color="secondary">
        Showcases fenced code blocks with syntax highlighting
      </Text>
    </Block>
  );
}
```

### Custom Components
ID: `Markdown.custom` • Category: general

Custom component mapping for markdown elements.

```tsx
const CUSTOM_COMPONENTS = {
  h1: ({ children, ...props }: any) => (
    <Text size="xl" weight="bold" color="primary" mb={12} {...props}>
      {children}
    </Text>
  ),
  h2: ({ children, ...props }: any) => (
    <Text size="lg" weight="semibold" color="accent" mb={8} {...props}>
      {children}
    </Text>
  ),
  p: ({ children, ...props }: any) => (
    <Text size="md" mb={8} {...props}>
      {children}
    </Text>
  ),
  blockquote: ({ children, ...props }: any) => (
    <Card p={12} variant="outline" bg="muted" mb={8} {...props}>
      <Text size="sm" style={{ fontStyle: 'italic' }}>
        {children}
      </Text>
    </Card>
  ),
};
const CONTENT = `# 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.
`;
  return (
    <Block fullWidth>
      <Markdown components={CUSTOM_COMPONENTS}>{CONTENT}</Markdown>
      <Text size="sm" color="secondary">
        Headings, paragraphs, and quotes use custom renderers
      </Text>
    </Block>
  );
}
```

### Inline Usage
ID: `Markdown.inline` • Category: general

Using markdown inline within other text content.

```tsx
const inlineContent = 'This is **bold text** and this is *italic text* with `inline code`.';
  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>**markdown formatting**</Markdown> and
        back to regular.
      </Text>
      <Text size="md" as="div">
        Code in context: Use <Markdown>`const x = 42;`</Markdown> to declare a variable.
      </Text>
    </Block>
  );
}
```

### Media & Tables
ID: `Markdown.media` • Category: general

Markdown with images, links, tables, and horizontal rules.

```tsx
const CONTENT = `# Media in Markdown
## Images
![PlatformBlocks Logo](https://raw.githubusercontent.com/platform-blocks/react-ui-library/main/apps/react-ui-library.com/assets/favicon.png)
## Links
Visit the [PlatformBlocks Documentation](https://react-ui-library.com) for more examples.
## Tables
| Feature | Status | Notes |
|---------|--------|-------|
| **Text Formatting** | ✅ | Bold, _italic_, \`code\` |
| Code Blocks | ✅ | Syntax highlighting |
| Tables | ✅ | Responsive layout |
| Images | ✅ | Auto-sizing |
| [Links](https://react-ui-library.com) | ✅ | External navigation |
## Horizontal Rule
Content above the line.
---
Content below the line.`;
  return (
    <Block fullWidth>
      <Markdown>{CONTENT}</Markdown>
      <Text size="sm" color="secondary">
        Images, links, tables, and horizontal rules render inline
      </Text>
    </Block>
  );
}
```

### Table Support
ID: `Markdown.table` • Category: general

Markdown tables with proper formatting and styling.

```tsx
const CONTENT = `# Table examples
## Basic table
| Name | Age | City |
|------|-----|------|
| John Doe | 30 | New York |
| Jane Smith | 25 | Los Angeles |
| Bob Johnson | 35 | Chicago |
## Table with formatting
| Feature | Status | **Priority** | Notes |
|---------|--------|-------------|--------|
| Authentication | ✅ | **High** | _Complete_ |
| User Management | 🔄 | **Medium** | In progress |
| Analytics | ❌ | **Low** | \`Not started\` |
| API Integration | ✅ | **High** | [Documentation](https://example.com) |
## Table with code
| Language | Extension | Sample code |
|----------|-----------|-------------|
| TypeScript | \`.tsx\` | \`const x: string = "hello";\` |
| JavaScript | \`.js\` | \`function hello() { return "world"; }\` |
| Python | \`.py\` | \`def hello(): return "world"\` |
## Complex table
| Component | **Props** | _Description_ | Example |
|-----------|----------|-------------|---------|
| Button | \`variant\`, \`size\`, \`disabled\` | Interactive button element | \`<Button variant="filled">Click me</Button>\` |
| Input | \`placeholder\`, \`value\`, \`onChange\` | Text input field | \`<Input placeholder="Enter text" />\` |
| Card | \`variant\`, \`padding\` | Container component | \`<Card variant="outline">Content</Card>\` |`;
  return (
    <Block fullWidth>
      <Markdown>{CONTENT}</Markdown>
      <Text size="sm" color="secondary">
        Multiple table layouts rendered with Markdown
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Masonry.md -->

# Masonry

Masonry provides an efficient way to create Pinterest-style layouts where items are arranged in columns with varying heights. Built on FlashList for optimal performance with large datasets, it automatically handles item positioning and provides smooth scrolling even with hundreds of items. The component supports dynamic heights through the heightRatio property on items, custom renderers, and responsive column counts. Perfect for image galleries, card layouts, or any scenario where you need an organic, space-efficient arrangement of content.

## Metadata

- Canonical name: `Masonry`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Masonry } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: layout
- Docs: https://react-ui-library.com/components/Masonry
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Masonry

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | MasonryItem[] | Yes |  | Array of items to display in masonry layout |
| `numColumns` | number | No |  | Number of columns (default: 2) |
| `gap` | SizeValue | No |  | Spacing between items |
| `optimizeItemArrangement` | boolean | No |  | Whether to optimize for staggered grid layout |
| `renderItem` | (item: MasonryItem, index: number) => ReactNode | No |  | Custom item renderer - receives item and index |
| `contentContainerStyle` | StyleProp<ViewStyle> | No |  | Content container style |
| `style` | StyleProp<ViewStyle> | No |  | Custom styles |
| `testID` | string | No |  | Test ID for testing |
| `loading` | boolean | No |  | Loading state |
| `emptyContent` | ReactNode | No |  | Empty state content |
| `flashListProps` | MasonryFlashListProps | No |  | Flash list props to pass through |
| `onEndReached` | ((info: { distanceFromEnd: number }) => void) \| null | No |  | Callback when the end of the list is reached (for pagination / infinite scroll) |
| `onEndReachedThreshold` | number | No |  | Distance from end (in pixels) to trigger onEndReached (default: FlashList default) |
| `onViewableItemsChanged` | MasonryViewabilityCallback | No |  | Callback when viewable items change |
| `scrollEnabled` | boolean | No |  | Whether scrolling is enabled |
| `ListEmptyComponent` | React.ComponentType<any> \| React.ReactElement \| null | No |  | Component rendered when the list is empty |
| `ListFooterComponent` | React.ComponentType<any> \| React.ReactElement \| null | No |  | Component rendered at the bottom of the list |
| `ListHeaderComponent` | React.ComponentType<any> \| React.ReactElement \| null | No |  | Component rendered at the top of the list |
| `estimatedItemSize` | number | No |  | Estimated size of each item (performance hint) |
| `refreshControl` | React.ReactElement | No |  | Pull-to-refresh control |
| `onScroll` | ScrollViewProps['onScroll'] | No |  | Scroll event callback |
| `scrollEventThrottle` | number | No |  | Throttle interval for scroll events in ms |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Masonry
ID: `Masonry.basic` • Tags: basic, layout, grid, columns, simple • Category: general

Simple masonry layout with uniform item heights arranged in a two-column grid.

```tsx
const theme = useTheme();
  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}
      numColumns={2}
      gap="md"
      style={{ height: 400 }}
    />
  );
}
```

### Custom Columns
ID: `Masonry.custom-columns` • Tags: columns, responsive, grid, arrangement, configurable • Category: general

Masonry layout with configurable number of columns demonstrating different grid arrangements.

```tsx
const theme = useTheme();
  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 (
    <>
      <Row gap="sm" style={{ marginBottom: 16 }}>
        <Button
          title="1 Column"
          size="sm"
          variant={numColumns === 1 ? 'filled' : 'outline'}
          onPress={() => setNumColumns(1)}
        />
        <Button
          title="2 Columns"
          size="sm"
          variant={numColumns === 2 ? 'filled' : 'outline'}
          onPress={() => setNumColumns(2)}
        />
        <Button
          title="3 Columns"
          size="sm"
          variant={numColumns === 3 ? 'filled' : 'outline'}
          onPress={() => setNumColumns(3)}
        />
        <Button
          title="4 Columns"
          size="sm"
          variant={numColumns === 4 ? 'filled' : 'outline'}
          onPress={() => setNumColumns(4)}
        />
      </Row>
      <Masonry
        data={masonryItems}
        numColumns={numColumns}
        gap="md"
        style={{ height: 400 }}
      />
    </>
  );
}
```

### Variable Heights
ID: `Masonry.variable-heights` • Tags: heights, staggered, organic, pinterest, variable • Category: general

Masonry layout with items of different heights creating an organic, Pinterest-style staggered appearance.

```tsx
const theme = useTheme();
  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}
      numColumns={2}
      gap="lg"
      optimizeItemArrangement={true}
      style={{ height: 600 }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Menu.md -->

# Menu

The Menu component provides a dropdown interface for navigation links, actions, and contextual options. It supports flexible positioning, keyboard navigation, and customizable triggers.

## Metadata

- Canonical name: `Menu`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Menu } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: navigation
- Docs: https://react-ui-library.com/components/Menu
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Menu

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `opened` | boolean | No |  | Whether the menu is open |
| `trigger` | 'click' \| 'hover' \| 'contextmenu' | No | 'click' | Menu trigger event type |
| `position` | 'top' \| 'bottom' \| 'left' \| 'right' \| 'auto' \| 'top-start' \| 'top-end' \| 'bottom-start' \| 'bottom-end' \| 'left-start' \| 'left-end' \| 'right-start' \| 'right-end' | No | 'auto' | Position relative to trigger |
| `offset` | number | No | 4 | Offset from trigger element |
| `closeOnClickOutside` | boolean | No | true | Whether to close when clicking outside |
| `closeOnEscape` | boolean | No | true | Whether to close when pressing escape |
| `onOpen` | () => void | No |  | Callback when menu opens |
| `onClose` | () => void | No |  | Callback when menu closes |
| `w` | number \| 'target' \| 'auto' | No | 'auto' | Menu content width |
| `maxH` | number | No | 300 | Maximum height for scrollable content |
| `shadow` | 'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' | No | 'md' | Menu content shadow |
| `radius` | 'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' | No | 'md' | Border radius |
| `children` | React.ReactNode | Yes |  | Menu trigger element and dropdown |
| `testID` | string | No |  | Test ID for testing |
| `disabled` | boolean | No | false | Whether menu is disabled |
| `strategy` | 'absolute' \| 'fixed' \| 'portal' | No | Platform.OS === 'web' ? 'fixed' : 'portal' | Menu placement strategy |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Menu.basic` • Tags: menu • Category: usage • Status: stable • Since: 1.0.0

Pair a trigger with `MenuDropdown` to show primary actions and separators in a compact surface.

```tsx
Button,
  Card,
  Icon,
  Menu,
  MenuDivider,
  MenuDropdown,
  MenuItem,
  Text,
} from '@platform-blocks/react-ui-library';
  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
ID: `Menu.context` • Tags: menu, contextmenu • Category: behavior • Status: stable • Since: 1.0.0

Enable `trigger="contextmenu"` to surface a menu when users right-click or long-press a target.

```tsx
Block,
  Card,
  Icon,
  Menu,
  MenuDivider,
  MenuDropdown,
  MenuItem,
  Text,
} from '@platform-blocks/react-ui-library';
  return (
    <Menu trigger="contextmenu">
      <Card
        p="lg"
        variant="outline"
        style={{
          borderStyle: 'dashed',
          cursor: 'context-menu',
          alignItems: 'center',
          justifyContent: 'center',
          minHeight: 140,
        }}
      >
        <Block align="center">
          <Icon name="star" size="lg" color="gold" />
          <Text size="sm" color="secondary">
            Right-click or long-press this area
          </Text>
        </Block>
      </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
ID: `Menu.positioning` • Tags: menu, position • Category: layout • Status: stable • Since: 1.0.0

Adjust the `position` prop to pin dropdown content to any edge of the trigger.

```tsx
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;
  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>
  );
}
```

### Submenu
ID: `Menu.submenu` • Category: general

```tsx
Button,
  Icon,
  Menu,
  MenuDivider,
  MenuDropdown,
  MenuItem,
  MenuLabel,
  MenuSub,
} from '@platform-blocks/react-ui-library';
  return (
    <Menu w={220}>
      <Button size="sm" variant="outline">
        Actions
      </Button>
      <MenuDropdown>
        <MenuLabel>Document</MenuLabel>
        <MenuItem startSection={<Icon name="edit" size="sm" />}>Rename</MenuItem>
        {/* Flyout submenu — opens to the side on hover (web) or tap */}
        <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>
          {/* Submenus nest arbitrarily deep */}
          <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>
        <MenuDivider />
        <MenuItem color="danger" startSection={<Icon name="trash" size="sm" />}>
          Delete
        </MenuItem>
      </MenuDropdown>
    </Menu>
  );
}
```

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

<!-- source: https://react-ui-library.com/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`, `weight`, `tracking`, `uppercase`, `color`, `style`).

## Metadata

- Canonical name: `MenuItemButton`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { MenuItemButton } from '@platform-blocks/react-ui-library';`
- Category: navigation
- Tags: menu, dropdown, command, item, button
- Docs: https://react-ui-library.com/components/MenuItemButton
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/MenuItemButton

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `title` | string | No |  | Text label (alternative to children) |
| `children` | React.ReactNode | No |  | Custom content |
| `startIcon` | React.ReactNode | No |  | Leading icon |
| `endIcon` | React.ReactNode | No |  | Trailing icon / shortcut hint |
| `onPress` | () => void | No |  | Click handler |
| `disabled` | boolean | No |  | Whether the button is disabled |
| `active` | boolean | No |  | Whether the button is active (selected) |
| `danger` | boolean | No |  | Whether the button has destructive styling |
| `fullWidth` | boolean | No |  | Whether the button should take up full width |
| `size` | ComponentSizeValue | No |  | Size of the button |
| `compact` | boolean | No |  | Whether to use compact styling |
| `rounded` | boolean | No |  | Whether to use fully rounded corners |
| `style` | any | No |  | Custom styles override |
| `onPressIn` | (event: GestureResponderEvent) => void | No |  | Callback fired when press starts |
| `onPressOut` | (event: GestureResponderEvent) => void | No |  | Callback fired when press ends |
| `onMouseDown` | (event: any) => void | No |  | Web-only mouse down handler |
| `onMouseEnter` | (event: any) => void | No |  | Web-only mouse enter handler |
| `onMouseLeave` | (event: any) => void | No |  | Web-only mouse leave handler |
| `onHoverIn` | PressableProps['onHoverIn'] | No |  | Pointer hover start handler (web) |
| `onHoverOut` | PressableProps['onHoverOut'] | No |  | Pointer hover end handler (web) |
| `onFocus` | PressableProps['onFocus'] | No |  | Focus handler |
| `onBlur` | PressableProps['onBlur'] | No |  | Blur handler |
| `color` | MenuItemColor | No |  | Semantic color for menu styling |
| `hoverColor` | MenuItemColor | No |  | Color to apply when hovered |
| `activeColor` | MenuItemColor | No |  | Color to apply when active/pressed |
| `textColor` | string | No |  | Override text color for base state |
| `hoverTextColor` | string | No |  | Override text color when hovered |
| `activeTextColor` | string | No |  | Override text color when active |
| `testID` | string | No |  | Test identifier forwarded to Pressable |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the inner label `<Text>` (style, weight, ff, size, color). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Menu
ID: `MenuItemButton.basic` • Category: general

Simple dropdown menu with icons and dividers.

```tsx
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://react-ui-library.com/llms/components/MiniCalendar.md -->

# MiniCalendar

A compact calendar component for displaying a month view with selectable dates.

## Metadata

- Canonical name: `MiniCalendar`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { MiniCalendar } from '@platform-blocks/react-ui-library';`
- Category: dates
- Docs: https://react-ui-library.com/components/MiniCalendar
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/MiniCalendar

## Props

_No documented props yet._

## Examples

### Basic MiniCalendar
ID: `MiniCalendar.basic` • Category: general

Compact calendar showing a week view with date selection.

```tsx
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" color="secondary">
        {selectedDate ? `Selected: ${selectedDate.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Custom Day Count
ID: `MiniCalendar.customDays` • Category: general

MiniCalendar with configurable number of days displayed.

```tsx
const DAY_OPTIONS = [3, 5, 7];
  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" color="secondary">
        {selectedDate ? `Selected: ${selectedDate.toLocaleDateString()}` : 'No date selected'}
      </Text>
    </Block>
  );
}
```

### Date Constraints
ID: `MiniCalendar.constrained` • Category: general

MiniCalendar with minimum and maximum date restrictions.

```tsx
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" color="secondary">
        {selectedDate ? `Selected: ${selectedDate.toLocaleDateString()}` : 'No date selected'}
      </Text>
      <Text size="xs" color="secondary">
        Only the next seven days are enabled
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `MonthPicker`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { MonthPicker } from '@platform-blocks/react-ui-library';`
- Category: dates
- Tags: date, month, picker, calendar
- Docs: https://react-ui-library.com/components/MonthPicker
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/MonthPicker

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | Date \| null | No |  | Currently selected date (uses the first day of the month) |
| `onChange` | (date: Date \| null) => void | No |  | Called when user picks a new month |
| `year` | number | No |  | Force a specific year to render |
| `onYearChange` | (year: number) => void | No |  | Called when the visible year changes |
| `minDate` | Date | No |  | Minimum selectable date (inclusive) |
| `maxDate` | Date | No |  | Maximum selectable date (inclusive) |
| `locale` | string | No |  | Locale used for month labels |
| `size` | ComponentSizeValue | No |  | Size token that influences typography weight |
| `monthLabelFormat` | 'short' \| 'long' | No |  | Format of month labels |
| `hideHeader` | boolean | No |  | Hide navigation header (used when embedded in Calendar) |
| `monthsPerRow` | ResponsiveProp<number> | No |  | Responsive override for the number of months rendered per row |
| `fullWidth` | boolean | No |  | Stretch to fill the container instead of sizing to the natural grid width. Default `false`. |

## Examples

### Basic
ID: `MonthPicker.basic` • Category: general

```tsx
const [value, setValue] = useState<Date | null>(new Date());
  return (
    <Block fullWidth>
      <MonthPicker value={value} onChange={setValue} monthLabelFormat="long" />
      <Text size="sm" color="secondary">
        {value
          ? value.toLocaleDateString(undefined, { month: 'long', year: 'numeric' })
          : 'No month selected'}
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/MonthPickerInput.md -->

# MonthPickerInput

Form-friendly wrapper around `MonthPicker` that renders an input field and opens the picker in a modal dialog. Mirrors the `DatePickerInput` API for consistency while focusing on month-level selection workflows.

## Metadata

- Canonical name: `MonthPickerInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { MonthPickerInput } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 0.1.0
- Category: dates
- Docs: https://react-ui-library.com/components/MonthPickerInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/MonthPickerInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | Date \| null | No |  | Controlled value for the selected month |
| `defaultValue` | Date \| null | No |  | Default month when uncontrolled |
| `onChange` | (value: Date \| null) => void | No |  | Called when the month selection changes |
| `locale` | string | No |  | Locale used for formatting the input value |
| `formatOptions` | Intl.DateTimeFormatOptions | No |  | Intl format options for rendering the selected month |
| `formatValue` | (value: Date) => string | No |  | Custom formatter for the input value; overrides locale/formatOptions |
| `placeholder` | string | No |  | Placeholder text when no month is selected |
| `clearable` | boolean | No |  | Show a clear button when a month is selected |
| `closeOnSelect` | boolean | No |  | Close the picker after selecting a month |
| `monthPickerProps` | Partial<Omit<MonthPickerProps, 'value'>> | No |  | Additional props forwarded to MonthPicker (except value) |
| `modalTitle` | string | No |  | Dialog title text |
| `onOpen` | () => void | No |  | Called when the picker dialog opens |
| `onClose` | () => void | No |  | Called when the picker dialog closes |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No |  | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `MonthPickerInput.basic` • Category: general

```tsx
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" color="secondary">
        {value
          ? value.toLocaleDateString(undefined, { month: 'long', year: 'numeric' })
          : 'No month selected'}
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/NavTree.md -->

# NavTree

A sidebar that nests itself.

Hand it the flat list of routes an app already has — with a category on each — and it groups, orders and renders them as a tree. The branches above the current page open on their own, the row for that page is marked and scrolled to, and which branches are open survives a reload.

Rows carrying an `href` render as real `<a>` elements on web, so cmd-click, middle-click, "copy link address" and crawlers all work; a plain left-click goes to `onNavigate` for client-side routing. Omit `onNavigate` and the rows stay ordinary links the browser follows.

Built on [Tree](/components/Tree), so keyboard navigation, guide lines, filtering and the ARIA `tree`/`treeitem` roles come along with it.

## Metadata

- Canonical name: `NavTree`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { NavTree } from '@platform-blocks/react-ui-library';`
- Since: 1.1.0
- Category: navigation
- Tags: navigation, sidebar, tree, menu, routes
- Docs: https://react-ui-library.com/components/NavTree
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/NavTree

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | NavTreeItem[] | Yes |  | The destinations, flat. Grouped and nested by `buildNavTree`. |
| `activeHref` | string | No |  | Current route. Marks its row and opens the groups above it. |
| `onNavigate` | (item: NavTreeItem, node: TreeNode) => void | No |  | Where a row press goes. Supply it to route client-side; without it the rows stay plain links and the browser navigates. |
| `size` | ComponentSizeValue | No | 'sm' | Row density. @default 'sm' |
| `collapsed` | boolean | No |  | 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 | No |  | 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 | No | 'Filter…' | Placeholder for the filter field. @default 'Filter…' |
| `highlightMatches` | boolean | No | true | Matched substrings are marked in the row labels. @default true |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `groupOrder` | string[] | No |  | 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> | No |  | Leading icon per group label. |
| `sortLeaves` | 'alpha' \| 'none' | No | '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 | No | 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[] | No |  | Group labels (or full `A/B` paths) to open regardless of `openDepth`. |
| `getGroupNode` | (context: { label: string; path: string[]; depth: number; items: NavTreeItem[]; }) => Partial<TreeNode> | No |  | 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. |

## Examples

### Grouped routes
ID: `NavTree.basic` • Tags: navtree, sidebar • Category: navigation • Status: stable • Since: 1.1.0

A flat list of routes becomes a nested sidebar. The group above the active route is already open, because `activeHref` opened it.

```tsx
// 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'] },
];
  const [route, setRoute] = useState('/components/Select');
  return (
    <NavTree
      items={ROUTES}
      activeHref={route}
      onNavigate={item => setRoute(item.href)}
      showGuides
    />
  );
}
```

### Counts and order
ID: `NavTree.counts` • Tags: navtree, sidebar • Category: navigation • Status: stable • Since: 1.1.0

`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
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' },
];
  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
ID: `NavTree.search` • Tags: navtree, sidebar, search, filter • Category: navigation • Status: stable • Since: 1.1.0

`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
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' },
];
  const [route, setRoute] = useState('/components/Card');
  return (
    <NavTree
      items={ROUTES}
      activeHref={route}
      onNavigate={item => setRoute(item.href)}
      searchable
      searchPlaceholder="Filter components…"
    />
  );
}
```

### Collapsed rail
ID: `NavTree.collapsed` • Tags: navtree, sidebar, rail • Category: navigation • Status: stable • Since: 1.1.0

`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
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} />,
};
  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://react-ui-library.com/llms/components/NumberInput.md -->

# NumberInput

The `NumberInput` component is a numeric text input field that provides built-in step controls for incrementing and decrementing the value. It supports custom formatting and parsing functions, allowing you to display numbers in various formats (e.g., currency, percentages) while maintaining a numeric value internally.

## Metadata

- Canonical name: `NumberInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { NumberInput } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: input, numeric, stepper, formatter
- Docs: https://react-ui-library.com/components/NumberInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/NumberInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | No |  | Number value |
| `onChange` | (value: number \| undefined) => void | No |  | Change handler |
| `allowDecimal` | boolean | No |  | Allow decimal values |
| `allowNegative` | boolean | No |  | Allow negative values |
| `allowLeadingZeros` | boolean | No |  | Allow leading zeros while editing |
| `allowedDecimalSeparators` | string[] | No |  | Additional characters that should be treated as decimal separators |
| `decimalSeparator` | string | No |  | Decimal separator character |
| `decimalScale` | number | No |  | Maximum number of digits after the decimal point |
| `fixedDecimalScale` | boolean | No |  | When true, pads the decimal part with trailing zeros to match decimalScale |
| `min` | number | No |  | Minimum value |
| `max` | number | No |  | Maximum value |
| `step` | number | No |  | Step increment |
| `shiftMultiplier` | number | No |  | Multiplier applied to the step when using modifier keys |
| `precision` | number | No |  | Number of decimal places |
| `thousandSeparator` | string \| boolean | No |  | Thousand separator character or boolean to enable default separator |
| `thousandsGroupStyle` | 'none' \| 'thousand' \| 'lakh' \| 'wan' | No |  | Thousand grouping strategy |
| `prefix` | string | No |  | Prefix string appended before the value when displayed |
| `suffix` | string | No |  | Suffix string appended after the value when displayed |
| `format` | 'integer' \| 'decimal' \| 'currency' \| 'percentage' | No |  | Number format |
| `currency` | string | No |  | Currency code for currency format |
| `isAllowed` | (values: { floatValue?: number; formattedValue: string; value: string }) => boolean | No |  | Optional guard executed before value is committed |
| `startValue` | number | No |  | Value applied when stepping from an empty state |
| `stepHoldDelay` | number | No |  | Delay before step-hold behaviour kicks in (ms) |
| `stepHoldInterval` | number \| ((stepCount: number) => number) | No |  | Interval or function controlling step-hold cadence |
| `withKeyboardEvents` | boolean | No |  | Enable keyboard arrow interactions |
| `withControls` | boolean | No |  | Show increment/decrement buttons |
| `withSideButtons` | boolean | No |  | Render horizontal decrement/increment buttons flanking the input |
| `hideControlsOnMobile` | boolean | No |  | Whether to hide step controls on mobile |
| `withDragGesture` | boolean | No |  | Enable press-drag gesture to adjust value |
| `dragAxis` | 'horizontal' \| 'vertical' | No |  | Axis that determines how drag gestures adjust the value |
| `dragStepDistance` | number | No |  | Pixel distance required to trigger a single step while dragging |
| `dragStepMultiplier` | number | No |  | Multiplier applied to the configured step while dragging |
| `onDragStateChange` | (isDragging: boolean) => void | No |  | Callback fired when the drag gesture activation state changes |
| `formatter` | (value: number) => string | No |  | Custom formatter function |
| `parser` | (value: string) => number | No |  | Custom parser function |
| `clampBehavior` | 'strict' \| 'blur' \| 'none' | No |  | Clamp value to min/max bounds |
| `allowEmpty` | boolean | No |  | Allow empty value |
| `textInputProps` | ExtendedTextInputProps | No |  | Additional TextInput props |
| `autoCapitalize` | RNTextInputProps['autoCapitalize'] | No |  | Text auto-capitalization behavior |
| `autoCorrect` | boolean | No |  | Whether to enable auto-correct |
| `autoFocus` | boolean | No |  | Whether to auto-focus on mount |
| `returnKeyType` | RNTextInputProps['returnKeyType'] | No |  | Return key type for soft keyboard |
| `blurOnSubmit` | boolean | No |  | Whether to blur on submit |
| `selectTextOnFocus` | boolean | No |  | Select all text on focus |
| `textContentType` | RNTextInputProps['textContentType'] | No |  | iOS text content type for autofill |
| `textAlign` | RNTextInputProps['textAlign'] | No |  | Text alignment |
| `spellCheck` | boolean | No |  | Whether spell check is enabled |
| `inputMode` | RNTextInputProps['inputMode'] | No |  | Input mode (modern alternative to keyboardType) |
| `enterKeyHint` | RNTextInputProps['enterKeyHint'] | No |  | Enter key hint |
| `selectionColor` | string | No |  | Color of the text selection handles and highlight |
| `showSoftInputOnFocus` | boolean | No |  | Whether to show the soft keyboard on focus |
| `editable` | boolean | No |  | Whether the field is editable |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `placeholder` | string | No |  | Input placeholder |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No |  | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `NumberInput.basic` • Tags: basic, numeric, step • Category: usage • Status: stable • Since: 1.0.0

Controlled number input with simple step controls and live value preview.

```tsx
const [quantity, setQuantity] = useState<number | undefined>(2);
  return (
    <NumberInput
      label="Quantity"
      placeholder="Enter amount"
      value={quantity}
      onChange={setQuantity}
      min={0}
      step={1}
    />
  );
}
```

### Formats
ID: `NumberInput.formats` • Tags: currency, percent, formatting • Category: usage • Status: stable • Since: 1.0.0

Showcases currency formatting, percentage suffixes, and a derived total.

```tsx
const [price, setPrice] = useState<number | undefined>(249.99);
  const [discount, setDiscount] = useState<number | undefined>(10);
  const finalPrice = price != null && discount != null
    ? price * (1 - discount / 100)
    : undefined;
  return (
    <Block>
      <Block>
        <NumberInput
          label="List price"
          value={price}
          onChange={setPrice}
          format="currency"
          currency="USD"
          fixedDecimalScale
          decimalScale={2}
          min={0}
          allowNegative={false}
        />
        <NumberInput
          label="Discount"
          value={discount}
          onChange={setDiscount}
          suffix="%"
          min={0}
          max={100}
          step={0.5}
          allowDecimal
        />
      </Block>
      <Text size="xs" color="secondary">
        Final price: {finalPrice != null ? `$${finalPrice.toFixed(2)}` : '—'}
      </Text>
    </Block>
  );
}
```

### Side buttons
ID: `NumberInput.side-buttons` • Tags: controls, step, buttons • Category: interaction • Status: stable • Since: 1.0.0

Side button controls with shift multipliers for both fine and coarse adjustments.

```tsx
const EnhancedNumberInput = NumberInput as any;
  const [value, setValue] = useState(32);
  const [step, setStep] = useState(1);
  const effectiveStep = useMemo(() => step || 1, [step]);
  return (
    <Block style={{ maxWidth: 360 }}>
      <Text weight="semibold">Side buttons and shift multiplier</Text>
      <Text size="sm" color="secondary">
        Combine side buttons with the default controls to support coarse and fine adjustments.
      </Text>
      <Block>
        <EnhancedNumberInput
          label="Playback speed"
          value={value}
          min={0}
          max={200}
          step={effectiveStep}
          shiftMultiplier={10}
          suffix="%"
          withSideButtons
          withControls
          onChange={(next: number | undefined) => {
            if (typeof next === 'number') {
              setValue(next);
            }
          }}
        />
        <Row justify="space-between" align="center">
          <Text size="xs" color="secondary">
            Current speed: {value}%
          </Text>
          <Text size="xs" color="secondary">
            Shift-click = ±{effectiveStep * 10}
          </Text>
        </Row>
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          Adjust the base step
        </Text>
        <Text size="sm" color="secondary">
          Update the increment to see how the multiplier scales.
        </Text>
        <EnhancedNumberInput
          label="Base step"
          value={step}
          min={1}
          max={25}
          step={1}
          withSideButtons
          onChange={(next: number | undefined) => {
            if (typeof next === 'number') {
              setStep(next);
            }
          }}
        />
      </Block>
    </Block>
  );
}
```

### Drag gesture
ID: `NumberInput.drag-gesture` • Tags: drag, gesture, adjustment • Category: interaction • Status: stable • Since: 1.0.0

Press-and-drag interactions for horizontal and vertical number adjustments.

```tsx
const [horizontalValue, setHorizontalValue] = useState<number | undefined>(32);
  const [verticalValue, setVerticalValue] = useState<number | undefined>(120);
  const [dragging, setDragging] = useState(false);
  const handleDragStateChange = (state: boolean) => {
    setDragging(state);
  };
  return (
    <Block>
      <Text weight="semibold">Press-and-drag adjustment</Text>
      <Text size="sm" color="secondary">
        Drag across the input to nudge values without lifting your pointer. The status below reflects the current drag state.
      </Text>
      <Text size="xs" color={dragging ? 'primary' : 'secondary'}>
        Dragging: {dragging ? 'active' : 'idle'}
      </Text>
      <Block>
        <Block>
          <Text size="sm" weight="semibold">
            Horizontal drag
          </Text>
          <Text size="sm" color="secondary">
            Step every 14px drag movement with a multiplier for faster adjustments.
          </Text>
          <NumberInput
            label="Temperature"
            value={horizontalValue}
            onChange={setHorizontalValue}
            withDragGesture
            dragAxis="horizontal"
            dragStepDistance={14}
            dragStepMultiplier={2}
            step={1}
            allowDecimal={false}
            min={0}
            suffix=" °C"
            onDragStateChange={handleDragStateChange}
          />
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Vertical drag
          </Text>
          <Text size="sm" color="secondary">
            Drag up or down to adjust between 0 and 200 with built-in controls.
          </Text>
          <NumberInput
            label="Light intensity"
            value={verticalValue}
            onChange={setVerticalValue}
            withDragGesture
            dragAxis="vertical"
            dragStepDistance={18}
            step={5}
            allowDecimal={false}
            min={0}
            max={200}
            withControls
            hideControlsOnMobile={false}
            onDragStateChange={handleDragStateChange}
          />
        </Block>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Overlay.md -->

# Overlay

The Overlay component provides a utility for dimming background content or drawing focus to foreground elements. It supports theme-aware colors, configurable opacity, gradients, and blur to achieve anything from subtle scrims to dramatic glassmorphism. Because Overlay is non-interactive by default, pair it with focus traps or dismiss controls when building dialogs, sheets, or other blocking surfaces.

## Metadata

- Canonical name: `Overlay`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Overlay } from '@platform-blocks/react-ui-library';`
- Status: beta
- Category: overlay
- Docs: https://react-ui-library.com/components/Overlay
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Overlay

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `color` | string | No |  | Background color for the overlay. Accepts raw colors or theme tokens like `primary.6`. |
| `opacity` | number | No |  | Opacity applied to the background color. Defaults to 0.6. |
| `backgroundOpacity` | number | No |  | Opacity applied to the entire overlay, including gradients and blur effects. Defaults to 1. |
| `gradient` | string | No |  | Web-only CSS gradient string. Falls back to `color` on native platforms. |
| `blur` | number \| string | No |  | Amount of backdrop blur (in pixels). Supported on web. |
| `radius` | SizeValue \| number | No |  | Corner radius for the overlay surface. |
| `zIndex` | number | No |  | z-index applied to the overlay container. |
| `fixed` | boolean | No | false | Use viewport-fixed positioning instead of absolute positioning (web only). |
| `center` | boolean | No | false | Center children horizontally and vertically. |
| `style` | StyleProp<ViewStyle> | No |  | Optional style overrides applied after computed styles. |
| `children` | ReactNode | No |  | Overlay content rendered on top of the dimmed background. |

## Examples

### Overlay patterns
ID: `Overlay.basic` • Tags: overlays, effects • Category: surfaces • Status: stable • Since: 1.0.0

Showcases dimming, gradient, and blurred overlays that inherit their parent size for spotlights and modal scrims.

```tsx
const HERO_IMAGE = require('../../../../assets/images/scene-city.png');
const GRADIENT_IMAGE = require('../../../../assets/images/scene-aurora.png');
const BLUR_IMAGE = require('../../../../assets/images/scene-desert.png');
type OverlayExample = {
  key: string;
  image: ImageSourcePropType;
  title: string;
  description: string;
  align?: 'flex-start' | 'center';
  overlayProps: Omit<ComponentProps<typeof Overlay>, 'children'>;
};
const STATIC_EXAMPLES: OverlayExample[] = [
  {
    key: 'gradient',
    image: GRADIENT_IMAGE,
    title: 'Gradient spotlight',
    description: 'When `gradient` is provided, the overlay renders a vivid fade instead of a solid tint.',
    overlayProps: {
      gradient: 'linear-gradient(145deg, rgba(0, 0, 0, 0.95) 0%, rgba(0, 0, 0, 0) 75%)',
      radius: 'xl',
    },
  },
  {
    key: 'blurred',
    image: BLUR_IMAGE,
    title: 'Glass overlay',
    description: 'Blend blur with partial opacity to achieve a glassmorphism effect (blur is web-only).',
    align: 'center',
    overlayProps: {
      color: '#000',
      backgroundOpacity: 0.35,
      blur: 18,
      radius: 'xl',
      center: true,
    },
  },
];
  const [visible, setVisible] = useState(true);
  return (
    <Block align="center" style={styles.wrapper}>
      <Block style={styles.section}>
        <ImageBackground source={HERO_IMAGE} style={styles.image} imageStyle={styles.imageInner}>
          {visible ? <Overlay color="#000" backgroundOpacity={0.8} radius="xl" /> : null}
          <Block align="center" style={styles.overlayContent}>
            <Text variant="h4" weight="semibold" color="white">
              Toggle overlay
            </Text>
            <Text color="white" align="center">
              Overlay fills its parent. Use `backgroundOpacity` to dim the background without affecting children.
            </Text>
          </Block>
        </ImageBackground>
        <Button onPress={() => setVisible((current) => !current)}>
          {visible ? 'Hide overlay' : 'Show overlay'}
        </Button>
      </Block>
      {STATIC_EXAMPLES.map(({ key, image, overlayProps, align = 'flex-start', title, description }) => (
        <Block key={key} style={styles.section}>
          <ImageBackground source={image} style={styles.image} imageStyle={styles.imageInner}>
            <Overlay {...overlayProps}>
              <Block align={align} style={styles.overlayContent}>
                <Text variant="h4" weight="semibold" color="white">
                  {title}
                </Text>
                <Text color="white" align={align === 'center' ? 'center' : 'left'}>
                  {description}
                </Text>
              </Block>
            </Overlay>
          </ImageBackground>
        </Block>
      ))}
      <Text variant="small" color="muted" align="center">
        Overlay inherits the size of its container, making it ideal for dimming media, spotlights, and modal scrims.
      </Text>
    </Block>
  );
}
const styles = StyleSheet.create({
  wrapper: {
    width: '100%',
  },
  section: {
    width: '100%',
    maxWidth: 520,
    alignSelf: 'center',
  },
  image: {
    width: '100%',
    aspectRatio: 16 / 9,
    borderRadius: 24,
    overflow: 'hidden',
    justifyContent: 'flex-end',
  },
  imageInner: {
    borderRadius: 24,
  },
  overlayContent: {
    padding: 24,
  },
});
```

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

<!-- source: https://react-ui-library.com/llms/components/Pagination.md -->

# Pagination

A comprehensive pagination component that provides intuitive navigation through large datasets. The component offers flexible configuration options and consistent styling across different use cases.

## Metadata

- Canonical name: `Pagination`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Pagination } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: navigation
- Tags: pagination, navigation, pages, data
- Docs: https://react-ui-library.com/components/Pagination
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Pagination

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `current` | number | Yes |  | Current page number (1-indexed) |
| `total` | number | Yes |  | Total number of pages |
| `siblings` | number | No | 1 | Number of page items to show on each side of current page |
| `boundaries` | number | No | 1 | Number of page items to show at the boundaries |
| `onChange` | (page: number) => void | Yes |  | Page change handler |
| `size` | ComponentSizeValue | No | 'md' | Size of pagination controls |
| `variant` | 'default' \| 'outline' \| 'subtle' | No | 'default' | Variant style |
| `color` | 'primary' \| 'secondary' \| 'gray' | No | 'primary' | Color scheme |
| `showFirst` | boolean | No | true | Show first/last page buttons |
| `showPrevNext` | boolean | No | true | Show previous/next buttons |
| `labels` | { first?: ReactNode; previous?: ReactNode; next?: ReactNode; last?: ReactNode; } | No | {} | Custom labels for navigation buttons |
| `disabled` | boolean | No | false | Whether pagination is disabled |
| `style` | StyleProp<ViewStyle> | No |  | Custom styles |
| `buttonStyle` | StyleProp<ViewStyle> | No |  | Custom button styles |
| `activeButtonStyle` | StyleProp<ViewStyle> | No |  | Custom active button styles |
| `textStyle` | StyleProp<TextStyle> | No |  | Custom text styles |
| `activeTextStyle` | StyleProp<TextStyle> | No |  | Custom active text styles |
| `hideOnSinglePage` | boolean | No | false | Hide pagination when there's only one page |
| `showSizeChanger` | boolean | No | false | Show page size selector |
| `pageSizeOptions` | number[] | No | [10, 20, 50, 100] | Available page sizes |
| `pageSize` | number | No | 10 | Current page size |
| `onPageSizeChange` | (size: number) => void | No |  | Page size change handler |
| `showTotal` | boolean \| ((total: number, range: [number, number]) => ReactNode) | No | false | Show total count |
| `totalItems` | number | No |  | Total number of items |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to every page-button label `<Text>` (style, weight, ff, size, color). |
| `activeLabelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the active page-button label `<Text>` (merged on top of `labelProps`). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `Pagination.basic` • Tags: basic, pagination, navigation • Category: usage • Status: stable • Since: 1.0.0

Provide `current`, `total`, and an `onChange` handler to keep numbered pagination in sync with surrounding state.

```tsx
const [currentPage, setCurrentPage] = useState(1);
  const totalPages = 10;
  return (
    <Block>
      <Pagination current={currentPage} total={totalPages} onChange={setCurrentPage} />
      <Text size="xs" color="secondary">
        Page {currentPage} of {totalPages}
      </Text>
    </Block>
  );
}
```

### Variants
ID: `Pagination.variants` • Tags: variants, style, appearance • Category: styling • Status: stable • Since: 1.0.0

Switch the `variant` prop between `default`, `outline`, and `subtle` to align pagination with the surrounding surface treatment.

```tsx
const [defaultPage, setDefaultPage] = useState(5);
  const [outlinePage, setOutlinePage] = useState(5);
  const [subtlePage, setSubtlePage] = useState(5);
  return (
    <Block>
      <Block>
        <Pagination current={defaultPage} total={15} onChange={setDefaultPage} variant="default" />
        <Text size="xs" color="secondary">
          Default variant keeps the control fully filled. Page {defaultPage} of 15.
        </Text>
      </Block>
      <Block>
        <Pagination current={outlinePage} total={15} onChange={setOutlinePage} variant="outline" />
        <Text size="xs" color="secondary">
          Outline keeps the surface quiet while the active page gets a stroke. Page {outlinePage} of 15.
        </Text>
      </Block>
      <Block>
        <Pagination current={subtlePage} total={15} onChange={setSubtlePage} variant="subtle" />
        <Text size="xs" color="secondary">
          Subtle removes backgrounds for tinted surfaces. Page {subtlePage} of 15.
        </Text>
      </Block>
    </Block>
  );
}
```

### Sizes
ID: `Pagination.sizes` • Tags: sizes, scale, responsive • Category: styling • Status: stable • Since: 1.0.0

Use the `size` prop (`xs` through `3xl`) to match pagination density to its container without changing behavior.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  const [page, setPage] = useState(3);
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" color="secondary">{size}</Text>
          <Pagination current={page} total={8} onChange={setPage} size={size} />
        </Block>
      ))}
    </Block>
  );
}
```

### Advanced
ID: `Pagination.advanced` • Tags: advanced, controls, boundaries, siblings • Category: usage • Status: stable • Since: 1.0.0

Combine `showFirst`, `showPrevNext`, `siblings`, and `boundaries` to reveal the right amount of context for long result sets.

```tsx
const [page1, setPage1] = useState(10);
  const [page2, setPage2] = useState(15);
  const [page3, setPage3] = useState(25);
  return (
    <Block>
      <Block>
        <Pagination
          current={page1}
          total={30}
          onChange={setPage1}
          showFirst
          showPrevNext
          siblings={2}
          boundaries={2}
        />
        <Text size="xs" color="secondary">
          Includes first and last buttons. Page {page1} of 30.
        </Text>
      </Block>
      <Block>
        <Pagination
          current={page2}
          total={40}
          onChange={setPage2}
          showPrevNext
          siblings={1}
          boundaries={1}
        />
        <Text size="xs" color="secondary">
          Minimal navigation with prev/next only. Page {page2} of 40.
        </Text>
      </Block>
      <Block>
        <Pagination
          current={page3}
          total={50}
          onChange={setPage3}
          showPrevNext
          siblings={0}
          boundaries={1}
          size="sm"
        />
        <Text size="xs" color="secondary">
          Compact layout with tight siblings. Page {page3} of 50.
        </Text>
      </Block>
    </Block>
  );
}
```

### Total & size changer
ID: `Pagination.size-changer` • Tags: pagination, page-size, total • Category: usage • Status: stable • Since: 1.0.0

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
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
        current={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" color="secondary">
        Page {current} of {total} · {pageSize} rows per page
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/PhoneInput.md -->

# PhoneInput

The `PhoneInput` component provides a flexible way to capture telephone numbers with built-in masking and formatting.

## Metadata

- Canonical name: `PhoneInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { PhoneInput } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: phone, input, mask, formatting, international
- Docs: https://react-ui-library.com/components/PhoneInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/PhoneInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | No |  | Phone number value (digits only). Omit for an uncontrolled field. |
| `defaultValue` | string | No |  | Initial value while uncontrolled. |
| `onChange` | (raw: string, formatted: string, meta: PhoneChangeMeta) => void | No |  | Change handler receiving (nationalDigits, formattedDisplay, meta) |
| `country` | PhoneCountryCode | No |  | Country preset to format against. Controlled when provided. |
| `defaultCountry` | PhoneCountryCode | No | 'US' | Initial country while uncontrolled. Defaults to 'US'. |
| `onCountryChange` | (country: PhoneCountryCode) => void | No |  | Called when the country changes (via the picker, or `autoDetect`). |
| `selectableCountry` | boolean | No | false | Render the dial code as a dropdown so the user can change country. |
| `autoDetect` | boolean | No | 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 | No | true | Show the dial code prefix ahead of the field |
| `mask` | string | No |  | 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 | No |  | Additional props forwarded to the underlying TextInput. |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `placeholder` | string | No |  | Input placeholder |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No | 'md' | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `PhoneInput.basic` • Tags: basic, phone, input • Category: basics • Status: experimental • Since: 1.0.0

Controlled PhoneInput example that surfaces both raw digits and the formatted display.

```tsx
const [raw, setRaw] = useState('');
  const [formatted, setFormatted] = useState('');
  const [e164, setE164] = useState('');
  const [complete, setComplete] = useState(false);
  return (
    <Block fullWidth>
      <Text weight="semibold">Basic phone input</Text>
      <Text size="sm" color="secondary">
        Controlled phone field showing the raw national digits, the formatted display
        value, and the submittable E.164 form.
      </Text>
      <PhoneInput
        label="Phone number"
        value={raw}
        onChange={(rawDigits, formattedDisplay, meta) => {
          setRaw(rawDigits);
          setFormatted(formattedDisplay);
          setE164(meta.e164);
          setComplete(meta.isComplete);
        }}
        country="US"
        showCountryCode
      />
      <Card variant="outline" p="sm">
        <Block>
          <Text size="xs" color="secondary">
            Current values
          </Text>
          <Code size="sm">{JSON.stringify({ raw, formatted, e164, complete }, null, 2)}</Code>
        </Block>
      </Card>
    </Block>
  );
}
```

### International
ID: `PhoneInput.international` • Tags: international, auto-detect, phone • Category: features • Status: experimental • Since: 1.0.0

Compare auto-detected formats with a manual international configuration.

```tsx
const [autoDetectValue, setAutoDetectValue] = useState('');
  const [autoDetectE164, setAutoDetectE164] = useState('');
  const [autoDetectCountry, setAutoDetectCountry] = useState('US');
  const [intlValue, setIntlValue] = useState('');
  const [intlFormatted, setIntlFormatted] = useState('');
  return (
    <Block fullWidth>
      <Text weight="semibold">International detection</Text>
      <Text size="sm" color="secondary">
        With autoDetect, an explicit + prefix picks the country: type or paste
        +447911123456 and the mask, dial code and E.164 output follow along. A
        recognized dial code is stripped on paste either way, so a full international
        number never overflows the national mask.
      </Text>
      <Block>
        <PhoneInput
          label="Auto-detect from a + prefix"
          value={autoDetectValue}
          onChange={(raw, _formatted, meta) => {
            setAutoDetectValue(raw);
            setAutoDetectE164(meta.e164);
          }}
          defaultCountry="US"
          onCountryChange={setAutoDetectCountry}
          autoDetect
          showCountryCode
          placeholder="Try +447911123456 or +33123456789"
        />
        <PhoneInput
          label="Manual international"
          country="INTL"
          value={intlValue}
          onChange={(raw, formatted) => {
            setIntlValue(raw);
            setIntlFormatted(formatted);
          }}
          showCountryCode={false}
          placeholder="Enter any international number"
        />
      </Block>
      <Card variant="outline" p="sm">
        <Block>
          <Text size="xs" color="secondary">
            Values
          </Text>
          <Code size="sm">
            {JSON.stringify(
              {
                autoDetect: {
                  country: autoDetectCountry,
                  raw: autoDetectValue,
                  e164: autoDetectE164
                },
                international: { raw: intlValue, formatted: intlFormatted }
              },
              null,
              2
            )}
          </Code>
        </Block>
      </Card>
    </Block>
  );
}
```

### Country Picker
ID: `PhoneInput.country-select` • Tags: country, picker, dial-code, phone • Category: features • Status: experimental • Since: 1.0.0

Let the user pick the country from the dial-code prefix, remasking the number in place.

```tsx
const [country, setCountry] = useState('US');
  const [raw, setRaw] = useState('');
  const [e164, setE164] = useState('');
  return (
    <Block fullWidth>
      <Text weight="semibold">Country picker</Text>
      <Text size="sm" color="secondary">
        With selectableCountry the dial-code prefix becomes a dropdown. Changing the
        country remasks the digits already entered instead of clearing them, and the
        E.164 value is rebuilt against the new dial code.
      </Text>
      <PhoneInput
        label="Phone number"
        selectableCountry
        country={country}
        onCountryChange={setCountry}
        value={raw}
        onChange={(rawDigits, _formatted, meta) => {
          setRaw(rawDigits);
          setE164(meta.e164);
        }}
      />
      <Card variant="outline" p="sm">
        <Block>
          <Text size="xs" color="secondary">
            Current values
          </Text>
          <Code size="sm">{JSON.stringify({ country, raw, e164 }, null, 2)}</Code>
        </Block>
      </Card>
    </Block>
  );
}
```

### Country Formats
ID: `PhoneInput.formats` • Tags: formatting, country, phone • Category: features • Status: experimental • Since: 1.0.0

Showcase of built-in country presets with their localized masks and raw digit output.

```tsx
const [us, setUs] = useState('');
  const [uk, setUk] = useState('');
  const [fr, setFr] = useState('');
  const [br, setBr] = useState('');
  return (
    <Block fullWidth>
      <Text weight="semibold">Country formatting</Text>
      <Text size="sm" color="secondary">
        Compare built-in masks for several countries. Each input stores digits only while rendering a localized format.
      </Text>
      <Block>
        <PhoneInput
          label="United States"
          country="US"
          value={us}
          onChange={(raw) => setUs(raw)}
          showCountryCode
        />
        <PhoneInput
          label="United Kingdom"
          country="GB"
          value={uk}
          onChange={(raw) => setUk(raw)}
          showCountryCode
        />
        <PhoneInput
          label="France"
          country="FR"
          value={fr}
          onChange={(raw) => setFr(raw)}
          showCountryCode
        />
        <PhoneInput
          label="Brazil"
          country="BR"
          value={br}
          onChange={(raw) => setBr(raw)}
          showCountryCode
        />
      </Block>
      <Card variant="outline" p="sm">
        <Block>
          <Text size="xs" color="secondary">
            Raw digit values
          </Text>
          <Code size="sm">{JSON.stringify({ us, uk, fr, br }, null, 2)}</Code>
        </Block>
      </Card>
    </Block>
  );
}
```

### Mask Visibility
ID: `PhoneInput.mask-visibility` • Tags: country-code, placeholder • Category: features • Status: experimental • Since: 1.0.0

Demonstrates showing or hiding the country code prefix while preserving raw digits.

```tsx
const [withCountryCode, setWithCountryCode] = useState('');
  const [withoutCountryCode, setWithoutCountryCode] = useState('');
  return (
    <Block fullWidth>
      <Text weight="semibold">Country code visibility</Text>
      <Text size="sm" color="secondary">
        Toggle the country prefix while keeping the same underlying digits.
      </Text>
      <Block>
        <Block>
          <PhoneInput
            label="With country code"
            value={withCountryCode}
            onChange={(raw) => setWithCountryCode(raw)}
            country="US"
            showCountryCode
          />
          <Text size="xs" color="secondary">
            Raw digits: {withCountryCode || '—'}
          </Text>
        </Block>
        <Block>
          <PhoneInput
            label="Without country code"
            value={withoutCountryCode}
            onChange={(raw) => setWithoutCountryCode(raw)}
            country="US"
            showCountryCode={false}
          />
          <Text size="xs" color="secondary">
            Raw digits: {withoutCountryCode || '—'}
          </Text>
        </Block>
      </Block>
    </Block>
  );
}
```

### Validation
ID: `PhoneInput.validation` • Tags: validation, feedback, phone • Category: features • Status: experimental • Since: 1.0.0

Length-based validation for US and international formats with inline messaging.

```tsx
const [usRaw, setUsRaw] = useState('');
  const [usFormatted, setUsFormatted] = useState('');
  const [internationalRaw, setInternationalRaw] = useState('');
  const [internationalFormatted, setInternationalFormatted] = useState('');
  const isValidUs = useMemo(() => usRaw.length === 10, [usRaw]);
  const isValidInternational = useMemo(
    () => internationalRaw.length >= 7 && internationalRaw.length <= 15,
    [internationalRaw]
  );
  return (
    <Block fullWidth>
      <Text weight="semibold">Validation states</Text>
      <Text size="sm" color="secondary">
        Surface validation messages based on raw digit counts for domestic and international numbers.
      </Text>
      <Block>
        <Block>
          <PhoneInput
            label="US phone (10 digits required)"
            value={usRaw}
            onChange={(raw, formatted) => {
              setUsRaw(raw);
              setUsFormatted(formatted);
            }}
            country="US"
            showCountryCode
            error={usRaw.length > 0 && !isValidUs ? 'Enter a 10-digit US phone number' : undefined}
          />
          <Text size="xs" color={isValidUs || usRaw.length === 0 ? 'success' : 'error'}>
            {usRaw.length === 0
              ? 'Enter a phone number'
              : isValidUs
                ? `✓ ${usFormatted}`
                : `${usRaw.length}/10 digits entered`}
          </Text>
        </Block>
        <Block>
          <PhoneInput
            label="International phone (7-15 digits)"
            value={internationalRaw}
            onChange={(raw, formatted) => {
              setInternationalRaw(raw);
              setInternationalFormatted(formatted);
            }}
            defaultCountry="INTL"
            autoDetect
            showCountryCode
            error={
              internationalRaw.length > 0 && !isValidInternational
                ? 'International numbers should be 7-15 digits'
                : undefined
            }
          />
          <Text
            size="xs"
            color={isValidInternational || internationalRaw.length === 0 ? 'success' : 'error'}
          >
            {internationalRaw.length === 0
              ? 'Enter an international phone number'
              : isValidInternational
                ? `✓ ${internationalFormatted}`
                : 'Adjust to 7-15 digits'}
          </Text>
        </Block>
      </Block>
    </Block>
  );
}
```

### Advanced Masking
ID: `PhoneInput.advanced-masking` • Tags: mask, formatting, advanced • Category: features • Status: experimental • Since: 1.0.0

Custom mask patterns for international formats and extension fields.

```tsx
const [intlRaw, setIntlRaw] = useState('');
  const [intlFormatted, setIntlFormatted] = useState('');
  const [extensionRaw, setExtensionRaw] = useState('');
  const [extensionFormatted, setExtensionFormatted] = useState('');
  return (
    <Block fullWidth>
      <Text weight="semibold">Advanced masking</Text>
      <Text size="sm" color="secondary">
        Apply custom mask patterns to control formatting for international numbers and extension fields.
      </Text>
      <Block>
        <PhoneInput
          label="International format"
          value={intlRaw}
          onChange={(raw, formatted) => {
            setIntlRaw(raw);
            setIntlFormatted(formatted);
          }}
          autoDetect={false}
          showCountryCode={false}
          mask="+00 (000) 000-0000"
          placeholder="+44 (7911) 123-456"
        />
        <Text size="xs" color="secondary">
          Raw digits: {intlRaw || '—'}
        </Text>
        <Text size="xs" color="secondary">
          Formatted: {intlFormatted || '—'}
        </Text>
      </Block>
      <Block>
        <PhoneInput
          label="North America with extension"
          value={extensionRaw}
          onChange={(raw, formatted) => {
            setExtensionRaw(raw);
            setExtensionFormatted(formatted);
          }}
          autoDetect={false}
          showCountryCode={false}
          mask="000-000-0000 x0000"
          placeholder="555-123-4567 x1234"
        />
        <Text size="xs" color="secondary">
          Raw digits: {extensionRaw || '—'}
        </Text>
        <Text size="xs" color="secondary">
          Formatted: {extensionFormatted || '—'}
        </Text>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/PinInput.md -->

# PinInput

A specialized input component designed for entering PIN codes, one-time passwords (OTP), verification codes, and other sequential character inputs. The component provides an intuitive interface with automatic focus management.

## Metadata

- Canonical name: `PinInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { PinInput } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: input
- Tags: pin, otp, security, input, verification
- Docs: https://react-ui-library.com/components/PinInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/PinInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `length` | number | No | 4 | Number of PIN digits |
| `keyboardFocusId` | string | No |  | Stable id used by KeyboardManager to restore focus |
| `value` | string | No |  | PIN value (controlled) |
| `defaultValue` | string | No | '' | Uncontrolled initial value (used when `value` is not provided) |
| `onChange` | (pin: string) => void | No |  | Change handler |
| `mask` | boolean | No | false | Whether to mask PIN |
| `maskChar` | string | No | '•' | Character to use for masking |
| `manageFocus` | boolean | No | true | Whether to focus next input automatically |
| `enforceOrderInitialOnly` | boolean | No |  | Enforce sequential entry (forces focus to first empty). If false, user can edit any position after complete |
| `type` | 'alphanumeric' \| 'numeric' | No | 'numeric' | Type of input |
| `placeholder` | string | No | '' | Placeholder for each input |
| `allowPaste` | boolean | No | true | Whether to allow paste |
| `oneTimeCode` | boolean | No | false | One-time code auto-complete |
| `spacing` | number | No | 8 | Input spacing |
| `borderRadius` | number | No |  | Input border radius |
| `onComplete` | (pin: string) => void | No |  | Complete handler - called when all digits are filled |
| `textInputProps` | Omit<TextInputProps, keyof BaseInputProps> | No |  | Additional TextInput props for each input |
| `autoCapitalize` | RNTextInputProps['autoCapitalize'] | No |  | Text auto-capitalization behavior |
| `autoCorrect` | boolean | No |  | Whether to enable auto-correct |
| `autoFocus` | boolean | No |  | Whether to auto-focus on first input on mount |
| `selectTextOnFocus` | boolean | No |  | Select all text on focus |
| `textContentType` | RNTextInputProps['textContentType'] | No |  | iOS text content type for autofill |
| `textAlign` | RNTextInputProps['textAlign'] | No |  | Text alignment |
| `spellCheck` | boolean | No |  | Whether spell check is enabled |
| `selectionColor` | string | No |  | Color of the text selection handles and highlight |
| `showSoftInputOnFocus` | boolean | No |  | Whether to show the soft keyboard on focus |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No | false | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No | 'md' | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `PinInput.basic` • Tags: basic, pin, code • Category: usage • Status: stable • Since: 1.0.0

Controlled 4-digit PIN input with automatic focus handoff and live preview.

```tsx
const [value, setValue] = useState('');
  return (
    <PinInput
      value={value}
      onChange={setValue}
      label="PIN code"
      keyboardFocusId="pin-demo-basic"
    />
  );
}
```

### Types
ID: `PinInput.types` • Tags: types, numeric, alphanumeric • Category: usage • Status: stable • Since: 1.0.0

Contrast numeric-only PIN entry with an alphanumeric option for recovery codes.

```tsx
const [numericValue, setNumericValue] = useState('');
  const [alphanumericValue, setAlphanumericValue] = useState('');
  return (
    <Block>
      <Text weight="semibold">PIN input types</Text>
      <Block>
        <Text size="sm" weight="semibold">
          Numeric (default)
        </Text>
        <Text size="sm" color="secondary">
          Restricts entry to digits 0-9 for PIN and OTP flows.
        </Text>
        <PinInput
          value={numericValue}
          onChange={setNumericValue}
          type="numeric"
          label="Numeric PIN"
        />
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          Alphanumeric
        </Text>
        <Text size="sm" color="secondary">
          Allow letters and numbers for recovery or backup codes.
        </Text>
        <PinInput
          value={alphanumericValue}
          onChange={setAlphanumericValue}
          type="alphanumeric"
          label="Alphanumeric code"
          length={6}
        />
      </Block>
    </Block>
  );
}
```

### Sizes
ID: `PinInput.sizes` • Tags: sizes, scale, responsive • Category: styling • Status: stable • Since: 1.0.0

Demonstrates xs through lg PIN inputs and when each token fits best.

```tsx
type SizeToken = 'xs' | 'sm' | 'md' | 'lg';
  const [xsValue, setXsValue] = useState('');
  const [smValue, setSmValue] = useState('');
  const [mdValue, setMdValue] = useState('');
  const [lgValue, setLgValue] = useState('');
  const sizeExamples: Array<{
    id: SizeToken;
    label: string;
    helper: string;
    size: SizeToken;
    value: string;
    setValue: (value: string) => void;
  }> = [
    {
      id: 'xs',
      label: 'Extra small (xs)',
      helper: 'Use for dense layouts or compact verification prompts.',
      size: 'xs',
      value: xsValue,
      setValue: setXsValue,
    },
    {
      id: 'sm',
      label: 'Small (sm)',
      helper: 'Pairs well with mobile forms and inline flows.',
      size: 'sm',
      value: smValue,
      setValue: setSmValue,
    },
    {
      id: 'md',
      label: 'Medium (md)',
      helper: 'Default size for most experiences.',
      size: 'md',
      value: mdValue,
      setValue: setMdValue,
    },
    {
      id: 'lg',
      label: 'Large (lg)',
      helper: 'Highlight critical actions with spacious fields.',
      size: 'lg',
      value: lgValue,
      setValue: setLgValue,
    },
  ];
  return (
    <Block>
      <Text weight="semibold">PIN input sizes</Text>
      {sizeExamples.map((example) => (
        <Block key={example.id}>
          <Text size="sm" weight="semibold">
            {example.label}
          </Text>
          <Text size="sm" color="secondary">
            {example.helper}
          </Text>
          <PinInput
            value={example.value}
            onChange={example.setValue}
            size={example.size}
            label={`${example.label} PIN`}
          />
        </Block>
      ))}
    </Block>
  );
}
```

### Lengths
ID: `PinInput.lengths` • Tags: length, digits, fields • Category: usage • Status: stable • Since: 1.0.0

Compare 4, 6, and 8-digit PIN inputs tailored for common authentication flows.

```tsx
const [fourDigit, setFourDigit] = useState('');
  const [sixDigit, setSixDigit] = useState('');
  const [eightDigit, setEightDigit] = useState('');
  const lengthExamples = [
    {
      length: 4,
      title: '4-digit PIN (default)',
      helper: 'Common for ATM and device security codes.',
      label: '4-digit PIN',
      value: fourDigit,
      setValue: setFourDigit,
    },
    {
      length: 6,
      title: '6-digit verification',
      helper: 'Typical for SMS-based one-time codes.',
      label: 'Verification code',
      value: sixDigit,
      setValue: setSixDigit,
    },
    {
      length: 8,
      title: '8-digit code',
      helper: 'Use for longer recovery or backup codes.',
      label: 'Security code',
      value: eightDigit,
      setValue: setEightDigit,
    },
  ];
  return (
    <Block>
      <Text weight="semibold">PIN input lengths</Text>
      {lengthExamples.map((example) => (
        <Block key={example.length}>
          <Text size="sm" weight="semibold">
            {example.title}
          </Text>
          <Text size="sm" color="secondary">
            {example.helper}
          </Text>
          <PinInput
            value={example.value}
            onChange={example.setValue}
            length={example.length}
            label={example.label}
          />
        </Block>
      ))}
    </Block>
  );
}
```

### Security
ID: `PinInput.security` • Tags: security, mask, validation, otp • Category: usage • Status: stable • Since: 1.0.0

Highlights masking, automatic OTP completion, and validation flows with inline messaging.

```tsx
const [maskedValue, setMaskedValue] = useState('');
  const [otpValue, setOtpValue] = useState('');
  const [otpStatus, setOtpStatus] = useState('');
  const [validationValue, setValidationValue] = useState('');
  const [validationMessage, setValidationMessage] = useState('');
  const [error, setError] = useState('');
  const [disabled, setDisabled] = useState(false);
  const correctPin = '1234';
  const handleValidate = () => {
    if (validationValue !== correctPin) {
      setError('Incorrect PIN. Try again.');
      setValidationMessage('');
      return;
    }
    setError('');
    setValidationMessage('PIN verified successfully.');
  };
  const handleOtpComplete = (value: string) => {
    setOtpStatus(`OTP entered: ${value}`);
  };
  const handleToggleDisabled = () => {
    setDisabled((prev) => !prev);
    setError('');
    setValidationMessage('');
  };
  const handleClear = () => {
    setValidationValue('');
    setError('');
    setValidationMessage('');
  };
  return (
    <Block>
      <Text weight="semibold">Security-focused PIN inputs</Text>
      <Block>
        <Text size="sm" weight="semibold">
          Masked PIN input
        </Text>
        <Text size="sm" color="secondary">
          Conceal characters as they are typed.
        </Text>
        <PinInput
          value={maskedValue}
          onChange={setMaskedValue}
          mask
          label="Secure PIN"
        />
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          OTP with auto-complete
        </Text>
        <Text size="sm" color="secondary">
          Automatically completes once all digits are entered.
        </Text>
        <PinInput
          value={otpValue}
          onChange={(value) => {
            setOtpValue(value);
            if (otpStatus) setOtpStatus('');
          }}
          onComplete={handleOtpComplete}
          oneTimeCode
          length={6}
          label="One-time password"
        />
        {otpStatus ? (
          <Text size="xs" color="secondary">
            {otpStatus}
          </Text>
        ) : null}
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          PIN validation state
        </Text>
        <Text size="sm" color="secondary">
          Enter the correct PIN: 1234
        </Text>
        <PinInput
          value={validationValue}
          onChange={(newValue) => {
            setValidationValue(newValue);
            if (error) setError('');
            if (validationMessage) setValidationMessage('');
          }}
          label="Enter PIN"
          error={error}
          disabled={disabled}
          helperText={!error ? 'Enter the correct 4-digit PIN' : undefined}
        />
        <Row gap="sm" wrap="wrap">
          <Button
            variant="filled"
            onPress={handleValidate}
            disabled={validationValue.length !== 4}
          >
            Validate
          </Button>
          <Button variant="outline" onPress={handleToggleDisabled}>
            {disabled ? 'Enable input' : 'Disable input'}
          </Button>
          <Button variant="outline" onPress={handleClear}>
            Clear
          </Button>
        </Row>
        {validationMessage ? (
          <Text size="xs" color="secondary">
            {validationMessage}
          </Text>
        ) : null}
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Popover`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Popover } from '@platform-blocks/react-ui-library';`
- Status: beta
- Category: overlay
- Docs: https://react-ui-library.com/components/Popover
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Popover

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | ReactNode | Yes |  |  |
| `opened` | boolean | No |  | Controlled open state |
| `defaultOpened` | boolean | No | false | Initial open state in uncontrolled mode |
| `onChange` | (opened: boolean) => void | No |  | Called when open state changes |
| `onOpen` | () => void | No |  | Called when popover opens |
| `onClose` | () => void | No |  | Called when popover closes |
| `onDismiss` | () => void | No |  | Called when popover is dismissed via outside click or escape |
| `trigger` | 'click' \| 'hover' | No | 'click' | How the popover is triggered: 'click' (default) or 'hover' (mostly useful for devices with a mouse) |
| `disabled` | boolean | No | false | Disable popover entirely |
| `closeOnClickOutside` | boolean | No | true | Close when clicking outside |
| `closeOnEscape` | boolean | No | true | Close when pressing Escape |
| `clickOutsideEvents` | string[] | No |  | Events considered for outside click detection (web only) |
| `trapFocus` | boolean | No |  | Trap focus within dropdown (web only) |
| `keepMounted` | boolean | No | false | Keep dropdown mounted when hidden |
| `returnFocus` | boolean | No | false | Return focus to target after close |
| `withinPortal` | boolean | No | true | Render dropdown within portal |
| `withOverlay` | boolean | No | false | Render overlay/backdrop |
| `overlayProps` | Record<string, unknown> | No |  | Overlay component props |
| `w` | number \| 'target' | No |  | Dropdown width, number or 'target' to match target width |
| `maxW` | number | No |  | Dropdown max-width |
| `maxH` | number | No |  | Dropdown max-height |
| `minW` | number | No |  | Dropdown min-width |
| `minH` | number | No |  | Dropdown min-height |
| `radius` | RadiusValue \| number | No |  | Border radius |
| `shadow` | ShadowValue | No |  | Box shadow |
| `zIndex` | number | No | 300 | Dropdown z-index |
| `position` | PlacementType | No | 'bottom' | Popover position relative to target |
| `offset` | number \| { mainAxis?: number; crossAxis?: number } | No | 8 | Offset from target |
| `floatingStrategy` | FloatingStrategy | No | 'fixed' | Floating strategy for positioning |
| `middlewares` | PopoverMiddlewares | No |  | Custom positioning options |
| `preventPositionChangeWhenVisible` | boolean | No | false | Prevent flipping/shifting when visible |
| `hideDetached` | boolean | No | true | Hide dropdown when target becomes detached |
| `viewport` | PositioningOptions['viewport'] | No |  | Override viewport padding |
| `keyboardAvoidance` | boolean | No | true | Whether positioning should avoid the on-screen keyboard |
| `fallbackPlacements` | PlacementType[] | No |  | Override fallback placements |
| `boundary` | number | No |  | Override boundary padding |
| `withRoles` | boolean | No | true | Render ARIA roles |
| `id` | string | No |  | Unique id base for accessibility |
| `withArrow` | boolean | No | false | Render arrow |
| `arrowSize` | number | No | DEFAULT_ARROW_SIZE | Arrow size |
| `arrowRadius` | number | No | 0 | Arrow border radius |
| `arrowOffset` | number | No | 5 | Arrow offset |
| `arrowPosition` | ArrowPosition | No | 'center' | Arrow position for start/end placements |
| `onPositionChange` | (placement: PlacementType) => void | No |  | Called when dropdown position changes |
| `testID` | string | No |  | Test identifier |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Popover.basic` • Tags: popover • Category: usage • Status: stable • Since: 1.0.0

Popover targets wrap an interactive element and render dropdown content within `Popover.Dropdown`.

```tsx
return (
    <Popover>
      <Popover.Target>
        <Button>
          Toggle popover
        </Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Block p="sm" style={{ maxWidth: 240 }}>
          <Text weight="semibold">Quick actions</Text>
          <Text variant="small" color="secondary">
            Popovers expose more content than tooltips without leaving the page.
          </Text>
          <Button size="xs" variant="ghost">
            Create new entry
          </Button>
          <Button size="xs" variant="ghost">
            View documentation
          </Button>
        </Block>
      </Popover.Dropdown>
    </Popover>
  );
}
```

### Hover Trigger
ID: `Popover.hover` • Tags: popover, hover, trigger • Category: usage • Status: stable • Since: 1.0.0

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
return (
    <Popover trigger="hover">
      <Popover.Target>
        <Button>
          Hover over me
        </Button>
      </Popover.Target>
      <Popover.Dropdown>
        <Block p="sm" style={{ maxWidth: 240 }}>
          <Text weight="semibold">Hover popover</Text>
          <Text variant="small" color="secondary">
            This popover opens on hover, ideal for mouse users who want quick access to additional content.
          </Text>
        </Block>
      </Popover.Dropdown>
    </Popover>
  );
}
```

### Controlled State
ID: `Popover.controlled` • Tags: popover, state • Category: behavior • Status: stable • Since: 1.0.0

Control the `opened` prop and respond to `onChange` when the popover needs to sync with surrounding form state.

```tsx
const [opened, setOpened] = useState(false);
  const [email, setEmail] = useState('team@example.com');
  return (
    <Block>
      <Checkbox
        label="Show popover"
        checked={opened}
        onChange={setOpened}
      />
      <Popover opened={opened} onChange={setOpened} trapFocus>
        <Popover.Target>
          <Button>
            Invite teammate
          </Button>
        </Popover.Target>
        <Popover.Dropdown>
          <Block p="sm" >
            <Text weight="semibold">Invite team member</Text>
            <Input
              label="Email"
              placeholder="name@example.com"
              value={email}
              onChangeText={setEmail}
              size="sm"
              fullWidth
            />
            <Button size="xs" onPress={() => setOpened(false)}>
              Send invite
            </Button>
          </Block>
        </Popover.Dropdown>
      </Popover>
    </Block>
  );
}
```

### Placement Options
ID: `Popover.placements` • Tags: popover, position • Category: layout • Status: stable • Since: 1.0.0

Set the `position` prop to control where the dropdown renders relative to its trigger.

```tsx
const OPTIONS = [
  { label: 'Top', position: 'top', description: 'Appears above the trigger.' },
  { label: 'Right', position: 'right', description: 'Anchors to the right edge.' },
  { label: 'Bottom', position: 'bottom', description: 'Drops below the trigger.' },
  { label: 'Left', position: 'left', description: 'Anchors to the left edge.' },
] as const;
  return (
    <Block direction="row">
      {OPTIONS.map(({ label, position, description }) => (
        <Popover key={position} position={position} withArrow>
          <Popover.Target>
            <Button>
              {label}
            </Button>
          </Popover.Target>
          <Popover.Dropdown>
            <Block p="sm" style={{ maxWidth: 220 }}>
              <Text weight="semibold">{label} placement</Text>
              <Text variant="small" color="secondary">
                {description}
              </Text>
            </Block>
          </Popover.Dropdown>
        </Popover>
      ))}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Progress.md -->

# Progress

The Progress component displays the completion progress of a task or process. Supports different variants, colors, and animations.

## Label and description

Progress accepts the same field props as the input components, rendered outside the track:

```tsx
<Progress
  value={64}
  label="Uploading assets"
  description="12 of 18 files"
  required
  labelPosition="top"
/>
```

`description` is the sublabel beneath the label, `error` replaces it and renders below the bar, `required` adds an asterisk (suppress it with `withAsterisk={false}`), and `labelPosition` accepts `top` (default), `bottom`, `left`, or `right`. `labelGap` tunes the space between the block and the bar, and `labelProps` / `descriptionProps` pass through to the underlying `<Text>` elements. `Progress.Root` takes the same props, so a segmented bar can be labelled the same way.

Don't confuse this with `Progress.Label`, which renders text *inside* a filled section.

## Compound components

For multi-part bars, compose `Progress.Root` with one `Progress.Section` per segment, and optionally a `Progress.Label` inside each section:

```tsx
<Progress.Root size="xl">
  <Progress.Section value={35} color="primary">
    <Progress.Label>35%</Progress.Label>
  </Progress.Section>
  <Progress.Section value={28} color="success">
    <Progress.Label>28%</Progress.Label>
  </Progress.Section>
</Progress.Root>
```

Each section takes its `value` as a percentage of the whole track, so sections may sum to less than 100 and leave the remainder unfilled. Sections support `color`, `striped`, `animate`, `radius`, and `transitionDuration` (inherited from `Progress.Root` when omitted).

## Tooltips

Use the section's own `tooltip` prop — a string, or a config object for full `Tooltip` props:

```tsx
<Progress.Section value={35} color="primary" tooltip="Documents — 35%" />
<Progress.Section value={28} color="success" tooltip={{ label: 'Photos — 28%', withArrow: true }} />
```

Do not wrap a section in `Tooltip` yourself. `Tooltip` renders a wrapper view, which then becomes the flex item inside `Progress.Root` and sizes itself to its content — collapsing the section's percentage width. The `tooltip` prop renders the tooltip *inside* the already-sized section instead. If you do need a manual wrapper, give it the width explicitly: `<Tooltip style={{ width: '35%' }}>`.

Sections also forward `onPress` and hover/focus handlers, so they can be made interactive directly.

## Vertical orientation

Pass `orientation="vertical"` to `Progress` or `Progress.Root` to fill from the bottom up. Vertical bars have no intrinsic length, so they default to 160 — set `length` (or the `h` layout prop) to size them, and `size` controls the thickness.

```tsx
<Progress value={82} orientation="vertical" length={120} size="sm" />
```

## Metadata

- Canonical name: `Progress`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Progress } from '@platform-blocks/react-ui-library';`
- Category: feedback
- Tags: progress, loading, status, indicator, completion, segments, vertical
- Docs: https://react-ui-library.com/components/Progress
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Progress

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | Yes |  | 0-100 |
| `size` | SizeValue | No | 'md' |  |
| `color` | ThemeColor | No | 'primary' |  |
| `radius` | SizeValue | No | 'md' |  |
| `striped` | boolean | No | false |  |
| `animate` | boolean | No | false |  |
| `transitionDuration` | number | No | 0 | ms |
| `orientation` | ProgressOrientation | No | 'horizontal' | Axis the bar fills along. Vertical bars fill bottom-up. @default 'horizontal' |
| `length` | number \| `${number}%` | No |  | Length along the main axis. Vertical bars default to 160. |
| `trackColor` | string | No |  | Track (unfilled) color. Defaults to the theme's `gray[1]`. |
| `style` | StyleProp<ViewStyle> | No |  | Styles applied to the track. Spacing/layout props stay on the outermost element. |
| `testID` | string | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `label` | React.ReactNode | No |  | Label rendered outside the track. Strings are styled; nodes render as-is. |
| `description` | React.ReactNode | No |  | Helper text ("sublabel") rendered directly beneath the label. Hidden while `error` is set. |
| `error` | React.ReactNode | No |  | Error message rendered below the bar. Replaces `description` when present. |
| `required` | boolean | No | false | Marks the field as required, rendering an asterisk beside the label. @default false |
| `withAsterisk` | boolean | No | true | Whether the required marker is drawn. @default true |
| `labelPosition` | ProgressLabelPosition | No | 'top' | Placement of the label block relative to the bar. @default 'top' |
| `labelGap` | SizeValue \| number | No | 'xs' | Gap between the label block and the bar — a theme size token or pixel value. @default 'xs' |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the description `<Text>` |

## Examples

### Basics
ID: `Progress.basic` • Tags: progress • Category: basics • Status: stable • Since: 1.0.0

Track a single completion percentage. Set `transitionDuration` so the bar animates its width whenever `value` changes instead of snapping to it.

```tsx
const TRANSITION_MS = 400;
  const [completion, setCompletion] = useState<number>(50);
  return (
    <Block fullWidth >
      <Progress value={completion} transitionDuration={TRANSITION_MS} />
      <Button onPress={() => setCompletion(randomValue)}>
        randomize value
      </Button>
    </Block>
  );
}
```

### Label and description
ID: `Progress.label` • Tags: label, description, error, field • Category: basics • Status: stable • Since: 0.11.0

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
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
ID: `Progress.advanced` • Tags: animation, striped • Category: behavior • Status: stable • Since: 1.0.0

Combine `striped` and `animate` to represent indeterminate work.

```tsx
const [value, setValue] = useState<number>(0);
  useEffect(() => {
    // Hold on the completed state for a beat, then start the run over.
    if (value >= 100) {
      const restart = setTimeout(() => setValue(0), 1800);
      return () => clearTimeout(restart);
    }
    const tick = setTimeout(() => {
      setValue((current) => Math.min(100, current + stageFor(current).speed));
    }, TICK_MS);
    return () => clearTimeout(tick);
  }, [value]);
  const done = value >= 100;
  const stage = stageFor(value);
  return (
    <Block fullWidth>
      <Progress
        value={value}
        label={done ? 'Upload complete' : `${stage.label} — ${Math.round(value)}%`}
        description={done ? `18 files · ${TOTAL_MB} MB` : describe(value)}
        color={done ? 'success' : stage.color}
        striped={!done && stage.striped}
        animate={!done && stage.striped}
        transitionDuration={TICK_MS + 20}
        size="lg"
        radius="xl"
      />
    </Block>
  );
}
```

### Compound sections
ID: `Progress.compound` • Tags: compound, sections, label • Category: composition • Status: stable • Since: 0.10.2

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
return (
    <Block gap="lg">
      <Block gap="xs">
        <Text variant="small" color="muted">
          Sections with inline labels
        </Text>
        <Progress.Root size="xl">
          <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>
        <Text variant="small" color="muted">
          Sections take a share of the track, so the remaining 22% stays unfilled.
        </Text>
      </Block>
      <Block gap="xs">
        <Text variant="small" color="muted">
          Striped and animated sections
        </Text>
        <Progress.Root size="lg" radius="xl">
          <Progress.Section value={45} color="primary" />
          <Progress.Section value={25} color="secondary" striped animate />
        </Progress.Root>
        <Text variant="small" color="muted">
          `striped` and `animate` work per section, marking in-flight work.
        </Text>
      </Block>
    </Block>
  );
}
```

### With tooltips
ID: `Progress.tooltips` • Tags: tooltip, sections, hover • Category: composition • Status: stable • Since: 0.10.2

```tsx
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 }
];
  return (
      <Progress.Root size="xl">
        {SECTIONS.map((section) => (
          <Progress.Section
            key={section.label}
            value={section.value}
            color={section.color}
            tooltip={`${section.label} — ${section.value}%`}
          >
            <Progress.Label>{section.value}%</Progress.Label>
          </Progress.Section>
        ))}
      </Progress.Root>
  );
}
```

### Example — segments with legend
ID: `Progress.segments` • Tags: segments, legend, storage • Category: composition • Status: stable • Since: 0.10.2

Custom-colored segments with tooltips and legend.

```tsx
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 used = USAGE.reduce((sum, segment) => sum + segment.value, 0);
const formatSize = (percent: number) => {
  const gb = (percent / 100) * TOTAL_GB;
  return gb < 1 ? `${Math.round(gb * 1024)} MB` : `${Math.round(gb)} GB`;
};
  return (
    <Block gap="md" fullWidth>
      <Row justify="space-between" align="center">
        <Text weight="600">Project storage</Text>
        <Text variant="small" color="muted">
          {formatSize(used)} of {TOTAL_GB} GB used
        </Text>
      </Row>
      <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" color="muted">
              {segment.value}%
            </Text>
          </Row>
        ))}
      </Block>
    </Block>
  );
}
```

### Vertical orientation
ID: `Progress.vertical` • Tags: orientation, vertical • Category: composition • Status: stable • Since: 0.10.2

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
const CHANNELS = [
  { label: 'Kick', value: 82, color: 'primary' as const },
  { label: 'Snare', value: 64, color: 'success' as const },
  { label: 'Bass', value: 91, color: 'warning' as const },
  { label: 'Vox', value: 47, color: 'error' as const }
];
  return (
    <Block gap="lg">
      <Block gap="sm">
        <Text variant="small" color="muted">
          Vertical bars fill from the bottom up
        </Text>
        <Row gap="md" align="flex-end">
          {CHANNELS.map((channel) => (
            <Block key={channel.label} gap="xs" align="center">
              <Progress
                value={channel.value}
                orientation="vertical"
                length={120}
                size="sm"
                radius="xl"
                color={channel.color}
                transitionDuration={600}
              />
              <Text variant="small" color="muted">
                {channel.label}
              </Text>
            </Block>
          ))}
          <Progress.Root orientation="vertical" length={140} size="md" radius="md">
            <Progress.Section value={40} color="primary" />
            <Progress.Section value={25} color="success" />
            <Progress.Section value={15} color="warning" striped animate />
          </Progress.Root>
        </Row>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `QRCode`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { QRCode } from '@platform-blocks/react-ui-library';`
- Category: data
- Tags: qrcode, barcode, scan, data, encoding
- Docs: https://react-ui-library.com/components/QRCode
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/QRCode

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | Yes |  | The data/text to encode in the QR code |
| `label` | React.ReactNode | No |  | 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 | No |  | Secondary line rendered under the label, for the longer explanation. |
| `labelPosition` | 'top' \| 'bottom' | No | 'bottom' | Which side of the code the caption sits on. @default 'bottom' |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the description `<Text>` |
| `size` | ComponentSizeValue | No |  | Size of the QR code (both width and height). Accepts a size token (`xs`–`3xl`) or an explicit pixel value. |
| `backgroundColor` | string | No |  | Background color of the QR code |
| `color` | string | No |  | Foreground color (the QR code pattern color) |
| `moduleShape` | 'square' \| 'rounded' \| 'diamond' | No |  | Module shape variant for data modules. Note: Finder patterns (corner anchors) always remain square for optimal scanner compatibility. |
| `finderShape` | 'square' \| 'rounded' | No |  | Corner (finder) shape variant - DEPRECATED: Finder patterns always remain square |
| `cornerRadius` | number | No |  | Rounded corner radius factor (0-1) applied when moduleShape='rounded' |
| `gradient` | { type?: 'linear' \| 'radial'; from: string; to: string; rotation?: number; } | No |  | Gradient fill (overrides color) |
| `errorCorrectionLevel` | 'L' \| 'M' \| 'Q' \| 'H' | No |  | Error correction level |
| `quietZone` | number | No |  | Quiet zone size (border modules around the QR code). Defaults to 1 for compact layouts. Set to 4 for strict 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; } | No |  | Logo to display in the center of the QR code |
| `style` | StyleProp<ViewStyle> | No |  | Custom container style |
| `testID` | string | No |  | Test ID for testing |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `onError` | (error: Error) => void | No |  | Callback when QR code generation fails |
| `onLoadStart` | () => void | No |  | Callback when QR code starts loading |
| `onLoadEnd` | () => void | No |  | Callback when QR code finishes loading |
| `copyOnPress` | boolean \| { value?: string } | No |  | If true (or object), tapping the QR copies the value (or provided value). |
| `showCopyButton` | boolean | No |  | Show a floating copy button overlay |
| `copyToastTitle` | string | No |  | Custom toast title when copied |
| `copyToastMessage` | string | No |  | Custom toast message when copied |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |

## Examples

### Basics
ID: `QRCode.basic` • Tags: qr-code • Category: basics • Status: stable • Since: 1.0.0

Render a single QR code for a link or payload and provide helper text for scanning context.

```tsx
return (
    <QRCode
      value="https://react-ui-library.com"
      size={168}
      quietZone={2}
      label="Scan to open the React UI Library docs."
    />
  );
}
```

### Sizes
ID: `QRCode.sizes` • Tags: size • Category: layout • Status: stable • Since: 1.0.0

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
return (
    <Block>
      <Row align="flex-end" gap="lg" wrap="wrap">
        {SIZES.map((size) => (
          <QRCode
            key={size}
            value="https://react-ui-library.com"
            size={size}
            quietZone={2}
            label={size}
          />
        ))}
      </Row>
      <QRCode
        value="https://react-ui-library.com"
        size={144}
        quietZone={2}
        label="144 (numeric)"
      />
    </Block>
  );
}
```

### Spacing
ID: `QRCode.spacing` • Tags: quiet-zone • Category: layout • Status: stable • Since: 1.0.0

Compare quiet zone values and pair them with outer spacing props when embedding codes in dense layouts.

```tsx
const theme = useTheme();
  return (
    <Block align="center">
      {QUIET_ZONES.map(({ label, quietZone }) => (
        <QRCode
          key={label}
          value="https://react-ui-library.com"
          size={150}
          quietZone={quietZone}
          label={label}
        />
      ))}
      <Block align="center">
        <Block bg={theme.backgrounds.subtle} radius="lg" p="sm">
          <QRCode
            value="https://react-ui-library.com"
            size={150}
            quietZone={0}
            m="xs"
          />
        </Block>
        <Text variant="small" color="muted">
          Use spacing props and container styling to pad the QR code externally.
        </Text>
      </Block>
    </Block>
  );
}
```

### Colors
ID: `QRCode.colors` • Tags: palette • Category: theming • Status: stable • Since: 1.0.0

Derive QR foreground and background colors from theme palettes to keep scans on brand.

```tsx
const theme = useTheme();
  return (
    <Block>
      <Text variant="small" color="muted">
        Theme-aligned palettes
      </Text>
      <Row gap="lg" wrap="wrap" justify="center">
        {SCHEMES.map(({ key, label }) => {
          const palette = theme.colors[key];
          const foreground = palette?.[6] ?? theme.colors.primary[6];
          const background = palette?.[0] ?? theme.backgrounds.surface;
          return (
            <QRCode
              key={key}
              value="https://react-ui-library.com"
              size={144}
              backgroundColor={background}
              color={foreground}
              quietZone={2}
              label={label}
            />
          );
        })}
      </Row>
    </Block>
  );
}
```

### Shapes
ID: `QRCode.shapes` • Tags: modules • Category: features • Status: stable • Since: 1.0.0

Switch between square, rounded, and diamond module shapes while keeping finder patterns scanner-safe.

```tsx
return (
    <Block>
      <Text variant="small" color="muted">
        Module geometry
      </Text>
      <Row gap="lg" wrap="wrap" justify="center">
        {SHAPES.map(({ label, value, moduleShape, cornerRadius }) => (
          <QRCode
            key={label}
            value={value}
            size={150}
            moduleShape={moduleShape}
            cornerRadius={cornerRadius}
            quietZone={1}
            label={label}
          />
        ))}
      </Row>
    </Block>
  );
}
```

### Gradients
ID: `QRCode.gradient` • Tags: gradient • Category: theming • Status: stable • Since: 1.0.0

Blend theme colors with linear or radial gradients to add polish without hurting scan reliability.

```tsx
const theme = useTheme();
  const gradients = createGradientExamples(theme);
  return (
    <Block>
      <Text variant="small" color="muted">
        Gradient fills
      </Text>
      <Row gap="lg" wrap="wrap" justify="center">
        {gradients.map(({ label, value, gradient, moduleShape, cornerRadius }) => (
          <QRCode
            key={label}
            value={value}
            size={160}
            gradient={gradient}
            moduleShape={moduleShape}
            cornerRadius={cornerRadius}
            quietZone={2}
            label={label}
          />
        ))}
      </Row>
    </Block>
  );
}
```

### Interactive
ID: `QRCode.interactive` • Tags: controls • Category: interaction • Status: stable • Since: 1.0.0

Let editors tweak the payload, size, error correction, and module shape while previewing the QR code live.

```tsx
const [value, setValue] = useState<string>(PRESETS[0].value);
  const [size, setSize] = useState<(typeof SIZES)[number]>(SIZES[1]);
  const [errorLevel, setErrorLevel] = useState<(typeof ERROR_LEVELS)[number]>('M');
  const [moduleShape, setModuleShape] = useState<(typeof MODULE_SHAPES)[number]>('square');
  return (
    <Block>
      <Block>
        <Text variant="small" color="muted">
          Source content
        </Text>
        <Input
          value={value}
          onChangeText={setValue}
          placeholder="Enter text, URL, or contact info"
          multiline
          minLines={1}
          maxLines={3}
        />
        <Row gap="xs" wrap="wrap">
          {PRESETS.map(({ label, value: preset }) => (
            <Button
              key={label}
              size="xs"
              variant={value === preset ? 'filled' : 'outline'}
              onPress={() => setValue(preset)}
            >
              {label}
            </Button>
          ))}
        </Row>
        <Text variant="small" color="muted">
          {value.length} characters
        </Text>
      </Block>
      <Row gap="lg" wrap="wrap" align="flex-start">
        <Block maxW={320} w="full">
          <Block>
            <Block>
              <Text variant="small" color="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" color="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>
              <Text variant="small" color="muted">
                L≈7% • M≈15% • Q≈25% • H≈30% recovery
              </Text>
            </Block>
            <Block>
              <Text variant="small" color="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.charAt(0).toUpperCase() + shape.slice(1)}
                  </Button>
                ))}
              </Row>
            </Block>
          </Block>
        </Block>
        <QRCode
          value={value || 'React UI Library'}
          size={size}
          quietZone={2}
          errorCorrectionLevel={errorLevel}
          moduleShape={moduleShape}
          cornerRadius={moduleShape === 'rounded' ? 0.4 : undefined}
          copyOnPress={{ value }}
          label={`${size}px • Level ${errorLevel} • ${moduleShape} modules`}
          labelProps={{ style: { textAlign: 'center' } }}
        />
      </Row>
    </Block>
  );
}
```

### Logos
ID: `QRCode.logo` • Tags: logo • Category: branding • Status: stable • Since: 1.0.0

Embed brand marks inside the QR code while preserving quiet zones and scanner-friendly contrast.

```tsx
const theme = useTheme();
  return (
    <Row gap="lg" wrap="wrap" justify="center">
      {LOGO_EXAMPLES.map(({ label, value, moduleShape, cornerRadius, logo }) => (
        <QRCode
          key={label}
          value={value}
          size={176}
          moduleShape={moduleShape}
          cornerRadius={cornerRadius}
          quietZone={2}
          logo={{
            ...logo,
            backgroundColor: theme.backgrounds.surface
          }}
          label={label}
        />
      ))}
    </Row>
  );
}
```

### QR Code Variants
ID: `QRCode.variants` • Tags: variants, error-correction, quiet-zone • Category: usage • Status: stable • Since: 1.0.0

Compare how error correction levels and quiet zone widths influence scannability.

```tsx
return (
    <Block>
      <Block>
        <Text variant="small" color="muted">
          Error correction levels
        </Text>
        <Row gap="lg" wrap="wrap" justify="center">
          {ERROR_LEVELS.map(({ label, value }) => (
            <QRCode
              key={value}
              value={`https://react-ui-library.com/ecc/${value}`}
              errorCorrectionLevel={value}
              size={140}
              label={label}
            />
          ))}
        </Row>
      </Block>
      <Block>
        <Text variant="small" color="muted">
          Quiet zone widths
        </Text>
        <Row gap="lg" wrap="wrap" justify="center">
          {QUIET_ZONES.map((quietZone) => (
            <QRCode
              key={quietZone}
              value={`https://react-ui-library.com/quiet-zone/${quietZone}`}
              quietZone={quietZone}
              size={140}
              label={`Quiet zone: ${quietZone}`}
            />
          ))}
        </Row>
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Radio.md -->

# Radio

Radio buttons allow users to select a single option from a group of mutually exclusive choices.

## Metadata

- Canonical name: `Radio`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Radio } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: input
- Tags: input, form, selection, choice
- Docs: https://react-ui-library.com/components/Radio
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Radio

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | Yes |  | Radio value |
| `checked` | boolean | No |  | Whether radio is selected |
| `onChange` | (value: string) => void | No |  | Change handler |
| `name` | string | No |  | Radio group name |
| `size` | SizeValue | No |  | Radio size |
| `color` | ColorValue | No |  | Radio color theme |
| `label` | React.ReactNode | No |  | Radio label |
| `disabled` | boolean | No |  | Whether radio is disabled |
| `required` | boolean | No |  | Whether radio is required |
| `error` | string | No |  | Error message |
| `description` | string | No |  | Helper text |
| `labelPosition` | 'left' \| 'right' | No |  | Label position relative to radio |
| `children` | React.ReactNode | No |  | Radio content/children (alternative to label) |
| `icon` | React.ReactNode \| string | No |  | Optional icon displayed alongside the label |
| `onKeyDown` | (event: any) => void | No |  | Key handler for accessibility/keyboard support |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the description `<Text>` |
| `transitionDuration` | number | No | 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. |
| `testID` | string | No |  | Component test ID for testing |
| `style` | any | No |  | Additional CSS styles |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Radio.basic` • Tags: Radio, RadioGroup • Category: basics • Status: stable • Since: 1.0.0

Use standalone `Radio` components for custom layouts or pass an `options` array to `RadioGroup` for quick single-selection forms.

```tsx
const TEAMS = ['Falcons', 'Tigers', 'Sharks'] as const;
  const [favoriteTeam, setFavoriteTeam] = useState<string>('Tigers');
  const [ticketType, setTicketType] = useState<string>('reserved');
  return (
    <Block>
      <Block>
        <Text variant="small" color="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" color="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
ID: `Radio.variants` • Tags: variants, radio, radiogroup, segmented, chip, card • Category: usage • Status: stable • Since: 1.0.0

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
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' },
];
  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" color="muted">default</Text>
        <RadioGroup
          variant="default"
          value={defaultValue}
          onChange={setDefaultValue}
          options={FREQUENCY_OPTIONS}
        />
      </Block>
      <Block>
        <Text variant="small" color="muted">card</Text>
        <RadioGroup
          variant="card"
          value={planValue}
          onChange={setPlanValue}
          options={PLAN_OPTIONS}
        />
      </Block>
      <Block>
        <Text variant="small" color="muted">segmented</Text>
        <RadioGroup
          variant="segmented"
          value={frequencyValue}
          onChange={setFrequencyValue}
          options={FREQUENCY_OPTIONS}
        />
      </Block>
      <Block>
        <Text variant="small" color="muted">chip</Text>
        <RadioGroup
          variant="chip"
          value={filterValue}
          onChange={setFilterValue}
          options={FILTER_OPTIONS}
        />
      </Block>
    </Block>
  );
}
```

### Theming
ID: `Radio.theming` • Tags: size, color, state • Category: theming • Status: stable • Since: 1.0.0

Combine the `size`, `color`, and validation props to align radios with your UI tokens and state requirements.

```tsx
const COLOR_OPTIONS = ['primary', 'secondary', 'success', 'error'] as const;
  const [sizeValue, setSizeValue] = useState<string>('club');
  const [colorValue, setColorValue] = useState<typeof COLOR_OPTIONS[number]>('primary');
  return (
    <Block>
      <Block>
        <Text variant="small" color="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" color="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" color="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
ID: `Radio.orientations` • Tags: horizontal, vertical • Category: layout • Status: stable • Since: 1.0.0

Toggle `orientation` between `horizontal` and `vertical` to adapt radio groups to the available space.

```tsx
const [favoriteSport, setFavoriteSport] = useState<string>('soccer');
  const [skillLevel, setSkillLevel] = useState<string>('intermediate');
  return (
    <Block>
      <Block>
        <Text variant="small" color="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" color="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
ID: `Radio.forms` • Tags: form, validation • Category: advanced • Status: stable • Since: 1.0.0

Pair `RadioGroup` with `required` and `error` messaging to validate selections before submitting a form workflow.

```tsx
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' }
];
  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" color="success">
          {confirmation}
        </Text>
      )}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Rating.md -->

# Rating

An interactive component for displaying star ratings and allowing users to provide ratings with customizable appearance.

## Metadata

- Canonical name: `Rating`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Rating } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: rating, stars, review, score, feedback
- Docs: https://react-ui-library.com/components/Rating
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Rating

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | No |  | Current rating value |
| `defaultValue` | number | No | 0 | Initial rating value for uncontrolled component |
| `count` | number | No | 5 | Number of rating items (stars) to render |
| `readOnly` | boolean | No | false | Disables input — the rating only displays its value |
| `disabled` | boolean | No | false | Disables the rating. Like `readOnly` it blocks input, but it also dims the control and reports a disabled state to assistive technology. |
| `allowFraction` | boolean | No | false | Allows partial values so a star can be filled fractionally |
| `precision` | number | No | 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 \| number | No | 'md' | Size of each rating item — a theme size token or an explicit pixel size |
| `color` | string | No |  | Color of filled items. Defaults to the theme warning color. |
| `emptyColor` | string | No |  | Color of empty items. Defaults to the theme gray color. |
| `hoverColor` | string | No |  | Color of items while hovering/dragging. Defaults to a darker theme warning color. |
| `onChange` | (value: number) => void | No |  | Called with the new value when the rating changes |
| `onHover` | (value: number) => void | No |  | Called with the previewed value while hovering (web only) |
| `clearable` | boolean | No | false | Allows clearing the rating by selecting the value that is already set |
| `required` | boolean | No | false | Marks the field as required. Renders an asterisk beside the label and reports the requirement to assistive technology on web. |
| `error` | React.ReactNode | No |  | Error message rendered below the rating |
| `description` | React.ReactNode | No |  | Helper text rendered below the rating |
| `showTooltip` | boolean | No | false | Shows a tooltip with the current value out of `count` while hovering |
| `getTooltipLabel` | (value: number, count: number) => string | No |  | Formats the tooltip text. Receives the previewed value and `count`; defaults to `4.5 / 5`. |
| `icon` | RatingIcon | No |  | 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 | No |  | 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 | No | '★' | 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 | No | '☆' | Character or node rendered for empty items. Ignored when `icon` or `emptyIcon` is set. |
| `gap` | SizeValue \| number | No | 'xs' | Spacing between rating items — a theme size token or an explicit pixel value |
| `style` | StyleProp<ViewStyle> | No |  | Additional styles applied to the root element |
| `testID` | string | No |  | Test ID for testing |
| `accessibilityLabel` | string | No |  | Custom accessibility label. Defaults to `Rating: {value} out of {count} stars`. |
| `accessibilityHint` | string | No |  | Custom accessibility hint. Defaults to an adjust hint unless `readOnly`. |
| `label` | React.ReactNode | No |  | Label rendered next to the rating. Strings are wrapped in a secondary `Text`. |
| `labelPosition` | 'left' \| 'right' \| 'above' \| 'below' | No | 'above' | Placement of the label relative to the rating |
| `labelGap` | SizeValue \| number | No | 'xs' | Spacing between the label and the rating — a theme size token or pixel value |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `Rating.basic` • Tags: interactive • Category: basics • Status: stable • Since: 1.0.0

Capture a single rating value with an interactive control and mirror the current score in helper text.

```tsx
const [score, setScore] = useState<number>(3);
  return (
    <Block>
      <Rating
        value={score}
        onChange={setScore}
        size="lg"
        label="Rate the broadcast quality"
      />
      <Text variant="small" color="muted">
        Current score: {score} out of 5.
      </Text>
    </Block>
  );
}
```

### Sizes
ID: `Rating.sizes` • Tags: size • Category: layout • Status: stable • Since: 1.0.0

Compare the available `size` tokens side by side to pick the right scale for your scene.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  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
ID: `Rating.colors` • Tags: palette • Category: theming • Status: stable • Since: 1.0.0

Derive filled, hover, and empty colors from the theme palette to align ratings with product semantics.

```tsx
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'];
  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" color="muted">
              {label}
            </Text>
            }
            />
          </Block>
        );
      })}
    </Block>
  );
}
```

### Fractions
ID: `Rating.fractions` • Tags: precision • Category: features • Status: stable • Since: 1.0.0

Enable fractional ratings with configurable `precision` values to capture nuanced feedback.

```tsx
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'];
  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" color="muted">
            {label}
          </Text>
          <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" color="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Custom Icons
ID: `Rating.icons` • Tags: icon, character • Category: theming • Status: stable • Since: 0.11.0

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
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
ID: `Rating.variants` • Tags: interactive, read-only • Category: behavior • Status: stable • Since: 1.0.0

Contrast interactive, read-only, and tooltip-enabled ratings to decide which fits your feedback flow.

```tsx
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
ID: `Rating.form-field` • Tags: validation, required, clearable • Category: features • Status: stable • Since: 0.11.0

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
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" color="muted">
        {score === 0 ? 'No rating selected.' : `You rated ${score} out of 5.`}
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Ring.md -->

# Ring

The Ring component displays progress or status using a radial indicator. It supports custom labels, color stops, neutral states, and fully customized center content.

## Metadata

- Canonical name: `Ring`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Ring } from '@platform-blocks/react-ui-library';`
- Category: feedback
- Tags: ring, progress, indicator, radial
- Docs: https://react-ui-library.com/components/Ring
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Ring

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | Yes |  | Current value represented by the ring |
| `min` | number | No | 0 | Lower bound for normalization. Defaults to 0. |
| `max` | number | No | 100 | Upper bound for normalization. Defaults to 100. |
| `size` | number | No | 100 | Diameter of the ring in pixels. Defaults to 100. |
| `thickness` | number | No | 12 | Stroke thickness in pixels. Defaults to 12. |
| `caption` | React.ReactNode | No |  | Optional caption rendered beneath the ring |
| `label` | React.ReactNode | No |  | Main label rendered in the ring center |
| `subLabel` | React.ReactNode | No |  | Secondary label rendered below the main label |
| `showValue` | boolean | No | true | Displays the computed percentage when no label/subLabel is provided. Defaults to true. |
| `valueFormatter` | (value: number, percent: number) => React.ReactNode | No |  | Formats the displayed value or percentage |
| `trackColor` | string | No |  | Track color behind the progress stroke |
| `progressColor` | string \| ((value: number, percent: number) => string) | No |  | Progress stroke color or resolver |
| `colorStops` | RingColorStop[] | No |  | Optional color stops evaluated against the computed percent |
| `neutral` | boolean | No | false | Forces the ring into a neutral state, disabling the progress stroke |
| `roundedCaps` | boolean | No | true | Controls whether the progress stroke has rounded caps. Defaults to true. |
| `style` | StyleProp<ViewStyle> | No |  | Container style for the outer wrapper |
| `ringStyle` | StyleProp<ViewStyle> | No |  | Style applied to the ring wrapper |
| `contentStyle` | StyleProp<ViewStyle> | No |  | Style applied to the center content container |
| `labelStyle` | StyleProp<TextStyle> | No |  | Style overrides for the main label |
| `subLabelStyle` | StyleProp<TextStyle> | No |  | Style overrides for the secondary label |
| `captionStyle` | StyleProp<TextStyle> | No |  | Style overrides for the caption |
| `labelColor` | string | No |  | Color override for the main label |
| `subLabelColor` | string | No |  | Color override for the secondary label |
| `captionColor` | string | No |  | Color override for the caption |
| `children` | React.ReactNode \| ((context: RingRenderContext) => React.ReactNode) | No |  | Custom center content. Receives value info when passed as a function |
| `testID` | string | No |  | Test identifier for end-to-end tests |
| `accessibilityLabel` | string | No |  | Accessibility label describing the ring |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Interactive Presets
ID: `Ring.basic` • Tags: ring • Category: usage • Status: stable • Since: 1.0.0

Drive multiple ring presentations from a single stateful value and expose how sizing and labels adapt.

```tsx
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
ID: `Ring.color-stops` • Tags: ring • Category: styling • Status: stable • Since: 1.0.0

Display how `colorStops` shift the progress color as values cross threshold ranges.

```tsx
const colorStops = [
  { value: 0, color: '#f87171' },
  { value: 60, color: '#f59e0b' },
  { value: 90, color: '#14b8a6' },
];
  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
ID: `Ring.custom-content` • Tags: ring • Category: customization • Status: stable • Since: 1.0.0

Showcase the render-prop API for injecting icons, text, or status badges inside the ring.

```tsx
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 weight="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" color="secondary">
            On hold
          </Text>
        </Block>
      </Ring>
    </Row>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/RollingNumber.md -->

# RollingNumber

RollingNumber displays a number and animates every digit that changes, rolling it to its new position. Use it for counters, live totals, prices and metric readouts where the change itself is part of the information.

## Metadata

- Canonical name: `RollingNumber`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { RollingNumber } from '@platform-blocks/react-ui-library';`
- Category: display
- Tags: number, counter, animation, odometer, metric
- Docs: https://react-ui-library.com/components/RollingNumber
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/RollingNumber

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | Yes |  | Value to display. Each digit that changes rolls to its new position. |
| `prefix` | string | No |  | Static text rendered before the number (e.g. `"$ "`). |
| `suffix` | string | No |  | Static text rendered after the number (e.g. `" USD"`). |
| `thousandSeparator` | boolean \| string | No | false | `true` for `,`, or an explicit separator string. |
| `decimalSeparator` | string | No | '.' | Character between the integer and decimal parts. Default `.`. |
| `decimalScale` | number | No |  | Number of decimal places to render. |
| `fixedDecimalScale` | boolean | No | false | Pad the decimal part with zeros up to `decimalScale`. |
| `transitionDuration` | number | No |  | Roll duration in ms. Default `600`. `0` — and an active reduced-motion preference — snap straight to the new digits. |
| `animationDuration` | number | No |  | alias for `transitionDuration`. |
| `timingFunction` | RollingNumberTimingFunction | No | 'ease' | Easing curve for the roll. Default `ease`. |
| `stagger` | number | No | 0 | Per-column delay in ms, applied right-to-left so the least significant digit leads. Default `0` (all columns move together). |
| `animateOnMount` | boolean | No | false | Animate from zero on first render instead of appearing settled. Default `false`. |
| `size` | SizeValue | No | 'md' | Font size token or explicit number. Default `'md'`. |
| `color` | string | No |  | Text color. Accepts theme palette syntax (`'primary.6'`, `'dimmed'`) or any CSS color. |
| `c` | string | No |  | Shorthand alias for `color`, resolved identically. `color` wins when both are set. |
| `weight` | TextStyle['fontWeight'] \| 'normal' \| 'medium' \| 'semibold' \| 'bold' | No |  | Font weight. |
| `fontFamily` | string | No |  | Custom font family. |
| `ff` | string | No |  | Shorthand alias for `fontFamily`. |
| `tabularNums` | boolean | No | true | Use tabular (fixed-width) figures so columns do not shift width as digits change. Default `true`. |
| `style` | StyleProp<ViewStyle> | No |  | Style for the row that wraps prefix, digits and suffix. |
| `textStyle` | StyleProp<TextStyle> | No |  | Style applied to every glyph — digits, separators, prefix and suffix. |
| `digitStyle` | StyleProp<TextStyle> | No |  | Style applied to digit glyphs only. |
| `accessibilityLabel` | string | No |  | 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 | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `RollingNumber.basic` • Tags: basic, counter, number • Category: basics • Status: stable • Since: 1.1.0

A counter whose digits roll to their new positions. Only the columns that changed move.

```tsx
const [value, setValue] = useState(1234);
  return (
    <Flex direction="column" align="center" gap="md">
      <RollingNumber value={value} size={48} weight="bold" thousandSeparator />
      <Flex gap="sm">
        <Button variant="outline" onPress={() => setValue((current) => current - 1)}>-1</Button>
        <Button variant="outline" onPress={() => setValue((current) => current + 1)}>+1</Button>
        <Button onPress={() => setValue(Math.floor(Math.random() * 100000))}>Random</Button>
      </Flex>
    </Flex>
  );
}
```

### Currency
ID: `RollingNumber.currency` • Tags: currency, prefix, suffix, decimals • Category: features • Status: stable • Since: 1.1.0

`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
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}
        weight="semibold"
      />
      <Button variant="outline" onPress={() => setTotal((current) => current + 149.5)}>
        Add item
      </Button>
    </Flex>
  );
}
```

### Timing
ID: `RollingNumber.timing` • Tags: animation, duration, easing, stagger • Category: features • Status: stable • Since: 1.1.0

`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
const [value, setValue] = useState(407219);
  return (
    <Flex direction="column" gap="lg">
      <Flex direction="column" gap="xs">
        <Text size="xs" c="dimmed">Snappy — 200ms, no stagger</Text>
        <RollingNumber value={value} transitionDuration={200} size={32} thousandSeparator />
      </Flex>
      <Flex direction="column" gap="xs">
        <Text size="xs" c="dimmed">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>
  );
}
```

### Live metric
ID: `RollingNumber.live-metric` • Tags: metric, dashboard, live • Category: examples • Status: stable • Since: 1.1.0

A ticking metric tile. Values that change faster than the roll retarget mid-flight rather than snapping.

```tsx
const [requests, setRequests] = useState(84213);
  useEffect(() => {
    const timer = setInterval(() => {
      setRequests((current) => current + Math.floor(Math.random() * 40));
    }, 1200);
    return () => clearInterval(timer);
  }, []);
  return (
    <Card p="lg" style={{ minWidth: 220 }}>
      <Flex direction="column" gap="xs">
        <Text size="xs" c="dimmed" uppercase>Requests today</Text>
        <RollingNumber
          value={requests}
          thousandSeparator
          size={40}
          weight="bold"
          transitionDuration={500}
          stagger={40}
        />
      </Flex>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Search.md -->

# Search

The Search component provides a search input with debouncing, loading states, and customizable clear functionality.

## Metadata

- Canonical name: `Search`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Search } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: search, input, filter, debounce
- Docs: https://react-ui-library.com/components/Search
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Search

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | string | No |  |  |
| `defaultValue` | string | No |  |  |
| `onChange` | (value: string) => void | No |  |  |
| `onSubmit` | (value: string) => void | No |  |  |
| `placeholder` | string | No |  |  |
| `size` | SizeValue | No |  |  |
| `radius` | any | No |  |  |
| `autoFocus` | boolean | No |  |  |
| `debounce` | number | No |  |  |
| `clearButton` | boolean | No |  |  |
| `loading` | boolean | No |  |  |
| `endSection` | React.ReactNode | No |  |  |
| `accessibilityLabel` | string | No |  |  |
| `style` | any | No |  |  |
| `buttonMode` | boolean | No |  | When true, renders as a button that opens the spotlight instead of a typeable input |
| `onPress` | () => void | No |  | Callback when search button is pressed (only used in buttonMode) |
| `rightComponent` | React.ReactNode | No |  | Component to render on the right side (useful for button mode to show shortcuts like CMD+K) |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic search
ID: `Search.basic` • Tags: controlled, input • Category: basics • Status: stable • Since: 0.3.0

Control the `Search` value with local state so you can react to user input and mirror the query elsewhere in your UI.

```tsx
const [query, setQuery] = useState('');
  return (
    <Block maxW={320} w="100%">
      <Search value={query} onChange={setQuery} placeholder="Search docs" />
      <Text size="xs" color="muted">
        Current query: {query || '—'}
      </Text>
    </Block>
  );
}
```

### Button mode
ID: `Search.button-mode` • Tags: spotlight, shortcuts • Category: behavior • Status: stable • Since: 0.3.0

Set `buttonMode` to turn `Search` into a pressable launcher and pass a `rightComponent` with `KeyCap` shortcuts so users discover keyboard access.

```tsx
const toast = useToast();
  const handleCustomPress = () => {
    toast.show({ message: 'Launching saved search…' });
  };
  return (
    <Block maxW={420} w="100%">
      <Block>
        <Text size="xs" color="muted">
          Default Spotlight launcher
        </Text>
        <Search
          buttonMode
          placeholder="Search the workspace"
          rightComponent={(
            <Row gap="xs" align="center">
              <KeyCap size="xs">⌘</KeyCap>
              <KeyCap size="xs">K</KeyCap>
            </Row>
          )}
        />
      </Block>
      <Block>
        <Text size="xs" color="muted">
          Custom handler with shortcut hint
        </Text>
        <Search
          buttonMode
          placeholder="Search analytics"
          onPress={handleCustomPress}
          rightComponent={(
            <Row gap="xs" align="center">
              <KeyCap size="xs" variant="outline">
                Ctrl
              </KeyCap>
              <KeyCap size="xs" variant="outline">
                F
              </KeyCap>
            </Row>
          )}
        />
      </Block>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/SegmentedControl.md -->

# SegmentedControl

Segmented controls present a small set of exclusive options. The indicator animates between segments with support for horizontal and vertical layouts, optional auto contrast for filled variants, and reduced motion awareness for accessibility.

## Metadata

- Canonical name: `SegmentedControl`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { SegmentedControl } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 1.0.0
- Category: input
- Tags: input, segmentation, toggle, selection
- Docs: https://react-ui-library.com/components/SegmentedControl
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/SegmentedControl

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | SegmentedControlData[] | Yes |  | Data that defines the segments |
| `value` | string | No |  | Controlled value |
| `defaultValue` | string | No |  | Uncontrolled initial value |
| `onChange` | (value: string) => void | No |  | Called when value changes |
| `size` | SizeValue | No |  | Control size, maps to height and font size |
| `color` | string | No |  | Indicator color token or hex |
| `orientation` | 'horizontal' \| 'vertical' | No |  | Layout orientation |
| `fullWidth` | boolean | No |  | Stretch across available width |
| `disabled` | boolean | No |  | Disable entire control |
| `readOnly` | boolean | No |  | Prevent user interaction but keep visual state |
| `autoContrast` | boolean | No |  | Adjust text color automatically for filled/outline variants |
| `withItemsBorders` | boolean | No |  | Render dividers between items |
| `transitionDuration` | number | No |  | Indicator transition duration (ms) |
| `transitionTimingFunction` | string | No |  | Indicator transition easing |
| `name` | string | No |  | Optional radio group name hint |
| `variant` | 'default' \| 'filled' \| 'outline' \| 'ghost' | No |  | Visual style variant |
| `indicatorStyle` | StyleProp<ViewStyle> | No |  | Custom style for indicator |
| `itemStyle` | StyleProp<ViewStyle> | No |  | Custom style applied to every item |
| `style` | StyleProp<ViewStyle> | No |  | Style applied to the container |
| `testID` | string | No |  | Test identifier applied to container |
| `accessibilityLabel` | string | No |  | Accessibility label for the entire control |
| `label` | ReactNode | No |  | Optional label rendered alongside the control |
| `description` | ReactNode | No |  | Supplementary description text rendered with the label |
| `labelPosition` | 'left' \| 'right' \| 'top' \| 'bottom' | No |  | Placement of the label relative to the control |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic Usage
ID: `SegmentedControl.basic` • Tags: segmented-control, selection, uncontrolled • Category: basics • Status: stable • Since: 1.0.0

Set `defaultValue` to preselect a segment and let the control manage focus and selection state internally.

```tsx
return (
    <SegmentedControl defaultValue="react" data={frameworks} />
  );
}
```

### Controlled Value
ID: `SegmentedControl.controlled` • Tags: segmented-control, controlled, state • Category: usage • Status: stable • Since: 1.0.0

Provide `value` and `onChange` to synchronize the selected segment with external state or companion controls.

```tsx
const [value, setValue] = useState('react');
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Drive the segmented control from external state to synchronize its value with other inputs.
        </Text>
        <SegmentedControl value={value} onChange={setValue} data={frameworks} />
        <Text size="xs" color="secondary">
          Selected value: <Text as="span" weight="600">{value}</Text>
        </Text>
        <Row gap="sm" wrap="wrap">
          <Button size="xs" onPress={() => setValue('react')}>
            Select React
          </Button>
          <Button size="xs" variant="outline" onPress={() => setValue('angular')}>
            Select Angular
          </Button>
          <Button size="xs" variant="outline" onPress={() => setValue('vue')}>
            Select Vue
          </Button>
        </Row>
      </Block>
    </Card>
  );
}
```

### Sizes
ID: `SegmentedControl.sizes` • Tags: segmented-control, sizes, density • Category: layout • Status: stable • Since: 1.0.0

Use the `size` prop to match dense toolbars or spacious layouts without changing the underlying data.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" color="secondary">{size}</Text>
          <SegmentedControl size={size} data={frameworkNames} defaultValue="React" />
        </Block>
      ))}
    </Block>
  );
}
```

### Full Width
ID: `SegmentedControl.full-width` • Tags: segmented-control, layout, full-width • Category: layout • Status: stable • Since: 1.0.0

Apply `fullWidth` to let segments expand and distribute evenly across the available horizontal space.

```tsx
return (
    <SegmentedControl fullWidth defaultValue="preview" data={panes} />
  );
}
```

### Orientation
ID: `SegmentedControl.orientation` • Tags: segmented-control, layout, orientation • Category: layout • Status: stable • Since: 1.0.0

Toggle the `orientation` prop to rotate the control vertically for sidebars or keep it horizontal for toolbars.

```tsx
return (
      <Block>
        <Row gap="lg" align="flex-start" wrap="wrap">
          <SegmentedControl
            label="Horizontal (default)"
            orientation="horizontal"
            defaultValue="react"
            data={frameworks}
          />
          <SegmentedControl
            label="Vertical"
            orientation="vertical"
            defaultValue="code"
            data={panes}
          />
        </Row>
      </Block>
  );
}
```

### Custom Colors
ID: `SegmentedControl.colors` • Tags: segmented-control, colors, theming • Category: theming • Status: stable • Since: 1.0.0

Set the `color` prop to pull semantic tokens or pass custom values, and enable `autoContrast` when you need readable labels on vivid fills.

```tsx
const palettes = [
  { key: 'primary', color: 'primary', defaultValue: 'react', data: frameworks },
  { key: 'success', color: 'success', defaultValue: 'code', data: panes },
  { key: 'purple', color: 'purple', defaultValue: 'settings', data: accountSections },
  { key: 'custom', color: '#FF6B6B', defaultValue: 'medium', data: priorities },
];
  return (
    <Block>
      {palettes.map((palette) => (
        <SegmentedControl
          key={palette.key}
          defaultValue={palette.defaultValue}
          color={palette.color}
          data={palette.data}
        />
      ))}
    </Block>
  );
}
```

### Interaction States
ID: `SegmentedControl.states` • Tags: segmented-control, states, disabled, readonly • Category: behavior • Status: stable • Since: 1.0.0

Combine `disabled`, `readOnly`, or per-item `disabled` flags to signal availability without changing layout or selection rules.

```tsx
const scenarios = [
  { key: 'default', label: 'Interactive', props: {}, defaultValue: 'react', data: frameworks },
  { key: 'disabled', label: 'Disabled', props: { disabled: true }, defaultValue: 'code', data: panes },
  { key: 'readOnly', label: 'Read only', props: { readOnly: true }, defaultValue: 'medium', data: priorities },
  // `languages` carries the disabled flag on its last item.
  { key: 'itemDisabled', label: 'Single option disabled', props: {}, defaultValue: 'typescript', data: languages },
];
  return (
    <Card p="md">
      <Block>
        <Block>
          {scenarios.map((scenario) => (
            <SegmentedControl
              key={scenario.key}
              label={scenario.label}
              defaultValue={scenario.defaultValue}
              data={scenario.data}
              {...scenario.props}
            />
          ))}
        </Block>
      </Block>
    </Card>
  );
}
```

### Visual Variants
ID: `SegmentedControl.variants` • Tags: segmented-control, variants, styling • Category: theming • Status: stable • Since: 1.0.0

Choose between `default`, `filled`, `outline`, or `ghost` variants and pair them with semantic `color` tokens to match the surrounding surface.

```tsx
const variants = [
  {
    key: 'default',
    label: 'Default',
    props: { variant: 'default' as const },
    defaultValue: 'react',
    description: 'Baseline segmented control with tonal contrast.',
    data: frameworks,
  },
  {
    key: 'filledPrimary',
    label: 'Filled',
    props: { variant: 'filled' as const, color: 'primary' as const },
    defaultValue: 'code',
    description: 'Solid background that matches the selected color token.',
    data: panes,
  },
  {
    key: 'filledContrast',
    label: 'Filled with auto-contrast',
    props: {
      variant: 'filled' as const,
      color: 'warning' as const,
      autoContrast: true,
    },
    defaultValue: 'medium',
    description: 'Enable autoContrast when using vivid palettes to keep labels legible.',
    data: priorities,
  },
  {
    key: 'outline',
    label: 'Outline',
    props: { variant: 'outline' as const, color: 'secondary' as const },
    defaultValue: 'weekly',
    description: 'Focus on outlining the chosen tab while keeping the surface quiet.',
    data: cadences,
  },
  {
    key: 'ghost',
    label: 'Ghost',
    props: { variant: 'ghost' as const, color: 'success' as const },
    defaultValue: 'published',
    description: 'Ghost removes the segment background until selection, ideal on tinted surfaces.',
    data: publishStates,
  },
];
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Change the variant to match the surface and emphasis level of the surrounding layout.
        </Text>
        <Block>
          {variants.map((variant) => (
            <Block key={variant.key}>
              <Text size="xs" color="secondary">
                {variant.label}
              </Text>
              <SegmentedControl
                defaultValue={variant.defaultValue}
                data={variant.data}
                {...variant.props}
              />
              <Text size="xs" color="muted">
                {variant.description}
              </Text>
            </Block>
          ))}
        </Block>
      </Block>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Select`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Select } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: input
- Docs: https://react-ui-library.com/components/Select
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Select

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | T \| null | No |  | Current value when the component is controlled. |
| `defaultValue` | T \| null | No |  | Initial value when the component manages its own state. |
| `onChange` | (value: T \| null, option?: SelectOption<T> \| null) => void | No |  | Callback fired whenever the selection changes. |
| `options` | SelectOption<T>[] | Yes |  | Collection of options available to choose from. |
| `placeholder` | string | No |  | Placeholder text shown when no value is selected. |
| `size` | SizeValue | No |  | Size token controlling trigger height and typography. |
| `radius` | any | No |  | Corner radius token applied to the trigger and dropdown. |
| `disabled` | boolean | No |  | Disables the control when set to true. |
| `label` | string | No |  | Optional label rendered above the trigger. |
| `description` | string | No |  | Optional short descriptive text shown directly under the label (above the field). |
| `helperText` | string | No |  | Helper copy displayed beneath the control. |
| `error` | string | No |  | Error message shown beneath the control in error state. |
| `searchable` | boolean | No |  | Enables client-side filtering of options. |
| `renderOption` | (opt: SelectOption<T>, active: boolean, selected: boolean) => React.ReactNode | No |  | Custom renderer for an individual option row. |
| `fullWidth` | boolean | No |  | Stretches the trigger to occupy the full width of its container. |
| `maxH` | number | No |  | Maximum height the dropdown may reach before it scrolls. |
| `closeOnSelect` | boolean | No |  | Whether the dropdown should close immediately after selection. |
| `clearable` | boolean | No |  | Allows the user to clear the current selection. |
| `clearButtonLabel` | string | No |  | Accessible label announced for the clear button when present. |
| `onClear` | () => void | No |  | Handler invoked after the selection is cleared. |
| `refocusAfterSelect` | boolean | No |  | Controls whether the trigger regains focus after selecting an option. |
| `keyboardAvoidance` | boolean | No |  | Whether dropdown positioning should avoid the on-screen keyboard. |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the description `<Text>` |
| `variant` | InputVariant | No |  | Visual variant of the trigger shell — `'default' \| 'filled' \| 'outline' \| 'unstyled'`. Mirrors `<Input variant>`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `minH` | DimensionValue | No |  | Sets the minimum height |

## Examples

### Basic
ID: `Select.basic` • Tags: basic, label, placeholder, single • Category: usage • Status: stable • Since: 1.0.0

Simple single-value select with helper copy and live selection feedback.

```tsx
return (
    <Select
      label="Favorite sport"
      description="Choose your favorite sport"
      placeholder="Choose a sport"
      options={sports}
    />
  )
}
```

### Variants
ID: `Select.variants` • Tags: variants, filled, outline, unstyled • Category: general • Status: stable • Since: 1.0.0

`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
const variants = [
  { variant: 'default', label: 'Default' },
  { variant: 'filled', label: 'Filled' },
  { variant: 'outline', label: 'Outline' },
  { variant: 'unstyled', label: 'Unstyled' },
] as const
  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>
  )
}
```

### Custom rendering
ID: `Select.custom` • Tags: render, option, custom • Category: customization • Status: stable • Since: 1.0.0

Render each option with additional detail and selection styling using `renderOption`.

```tsx
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 weight={selected ? '900' : '600'}>{name}</Text>
                <Text size="sm" color="secondary">
                  {description}
                </Text>
              </Block>
              {selected ? <Icon name="check" size={16} color={accent} /> : null}
            </Block>
          )
        }}
      />
    </Block>
  )
}
```

### Disabled states
ID: `Select.disabled` • Tags: disabled, options, state • Category: states • Status: stable • Since: 1.0.0

Disable individual options or the full control to reflect availability.

```tsx
// 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,
)
  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>
  )
}
```

### Persistent menu
ID: `Select.noCloseOnSelect` • Tags: persistent, close-on-select, comparison • Category: interaction • Status: stable • Since: 1.0.0

Keep the dropdown open after each choice for quick comparisons.

```tsx
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}
    />
  )
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `ShimmerText`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { ShimmerText } from '@platform-blocks/react-ui-library';`
- Category: typography
- Tags: text, shimmer, animation, gradient
- Docs: https://react-ui-library.com/components/ShimmerText
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/ShimmerText

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | ReactNode | No |  | Text node children. Overrides `text` when provided |
| `text` | string | No |  | Text content to render when not using children |
| `color` | string | No |  | Base text color rendered underneath the shimmer |
| `colors` | string[] | No |  | Optional gradient stops override |
| `shimmerColor` | string | No |  | Highlight color used for the shimmer pass |
| `spread` | number | No |  | 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 | No |  | Duration of a single shimmer cycle in seconds |
| `delay` | number | No |  | Delay before the shimmer starts (seconds) |
| `repeatDelay` | number | No |  | Pause held at the end of each cycle, with the band off screen (seconds) |
| `repeat` | boolean | No |  | Whether the shimmer should repeat indefinitely |
| `once` | boolean | No |  | Animate only once after becoming visible |
| `direction` | ShimmerDirection | No |  | Direction of shimmer movement |
| `debug` | boolean | No |  | Enable verbose logging for debugging |
| `onLayout` | TextProps['onLayout'] | No |  | Called with the layout of the shimmer container |
| `startOnView` | boolean | No |  | Start shimmering once the component enters the viewport (web only) |
| `inViewMargin` | string | No |  | `rootMargin` for the `startOnView` IntersectionObserver (web only) |
| `containerStyle` | any | No |  | Optional container style |
| `testID` | string | No |  | Optional test identifier |

## Examples

### Basic shimmer
ID: `ShimmerText.basic` • Tags: animation, text • Category: basics • Status: stable • Since: 0.3.0

Wrap text in `ShimmerText` to add the default looping highlight with no additional configuration.

```tsx
return (
    <Block align="flex-start">
      <ShimmerText size="xl" weight="bold">
        Weekly highlights go live
      </ShimmerText>
      <ShimmerText>
        New arrivals shimmer into view every Friday at noon.
      </ShimmerText>
    </Block>
  );
}
```

### Interactive controls
ID: `ShimmerText.controls` • Tags: animation, controls • Category: behavior • Status: stable • Since: 0.3.0

Expose `spread`, `repeat`, and `once` controls to let readers tune the shimmer loop at runtime.

```tsx
const MIN_SPREAD = 1;
const MAX_SPREAD = 4;
const SPREAD_STEP = 0.1;
  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"
        weight="bold"
        size="lg"
      >
        Interactive shimmer headline
      </ShimmerText>
      <Block w="100%">
        <Text variant="small" weight="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>
  );
}
```

### Customization options
ID: `ShimmerText.customization` • Tags: color, timing • Category: theming • Status: stable • Since: 0.3.0

Combine custom color stops, timing tweaks, and direction to align the shimmer with your brand voice.

```tsx
return (
    <Block align="flex-start">
      <ShimmerText shimmerColor="#facc15" spread={3} weight="bold" size="xl">
        Golden spotlight offer
      </ShimmerText>
      <ShimmerText
        color="#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://react-ui-library.com/llms/components/Skeleton.md -->

# Skeleton

Skeleton components provide visual placeholders for text, avatars, and blocks to reduce perceived loading time.

## Metadata

- Canonical name: `Skeleton`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Skeleton } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: feedback
- Tags: loading, placeholder, skeleton
- Docs: https://react-ui-library.com/components/Skeleton
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Skeleton

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `shape` | SkeletonShape | No | 'rectangle' | Shape of the skeleton placeholder |
| `w` | DimensionValue | No |  | Width of the skeleton component |
| `h` | DimensionValue | No |  | Height of the skeleton component |
| `size` | SizeValue | No | 'md' | Size of the skeleton component (overrides width/height) |
| `radius` | SizeValue \| number | No |  | Border radius for rectangle/rounded shapes |
| `animate` | boolean | No | true | Whether to show the loading animation |
| `animationDuration` | number | No | 1500 | Duration of the loading animation in milliseconds |
| `colors` | [string, string] | No |  | Gradient colors for the shimmer effect |
| `style` | StyleProp<ViewStyle> | No |  | Style overrides for the skeleton container |
| `testID` | string | No |  | Optional test identifier |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `Skeleton.basic` • Tags: loading, placeholder • Category: basics • Status: stable • Since: 1.0.0

Stack text, avatar, and block placeholders to preview the structure of incoming content while data loads.

```tsx
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
ID: `Skeleton.shapes` • Tags: avatar, text, button • Category: features • Status: stable • Since: 1.0.0

Preview the available skeleton shapes for avatars, typography lines, actions, and media blocks.

```tsx
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
ID: `Skeleton.card` • Tags: card, layout • Category: composition • Status: stable • Since: 1.0.0

Combine avatar, text, and action placeholders to preview a rich card layout ahead of remote content.

```tsx
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://react-ui-library.com/llms/components/Slider.md -->

# Slider

The Slider component allows users to select a value or range of values by moving a handle along a track. Supports single values, ranges, vertical layouts, and rich customization hooks for the value-label tooltip.

## Metadata

- Canonical name: `Slider`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Slider } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: slider, range, input, numeric, control
- Docs: https://react-ui-library.com/components/Slider
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Slider

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | No |  | Slider value |
| `defaultValue` | number | No | 0 | Uncontrolled initial value |
| `onChange` | (value: number) => void | No |  | Change handler |
| `min` | number | No | 0 | Minimum value |
| `max` | number | No | 100 | Maximum value |
| `step` | number | No | 1 | Step increment |
| `orientation` | 'horizontal' \| 'vertical' | No | 'horizontal' | Slider orientation |
| `trackColor` | ColorValue | No |  | Track color |
| `activeTrackColor` | ColorValue | No |  | Active track color |
| `thumbColor` | ColorValue | No |  | Thumb color |
| `trackSize` | number | No |  | Track height/width |
| `thumbSize` | number | No |  | Thumb size |
| `color` | ThemeColor | No |  | Color driving the active track, thumb, and active ticks. A palette token, `'primary.6'` shade syntax, or any CSS color. |
| `variant` | SliderVariant | No | 'default' | Visual variant of the slider track + thumb. Defaults to `'default'`. |
| `trackStyle` | StyleProp<ViewStyle> | No |  | Additional styling for the inactive track |
| `activeTrackStyle` | StyleProp<ViewStyle> | No |  | Additional styling for the active track |
| `thumbStyle` | StyleProp<ViewStyle> | No |  | Additional styling for the thumb |
| `tickColor` | ColorValue | No |  | Override inactive tick color |
| `activeTickColor` | ColorValue | No |  | Override active tick color |
| `tickStyle` | StyleProp<ViewStyle> | No |  | Style applied to inactive tick marks (merged on top of color/size defaults). |
| `activeTickStyle` | StyleProp<ViewStyle> | No |  | Style applied to active tick marks. |
| `tickLabelProps` | Omit<TextProps, 'children'> | No |  | Props applied to the `<Text>` rendered for each tick label (style, ff, weight, size, color). |
| `label` | React.ReactNode | No |  | Input label (above the slider) |
| `valueLabel` | ((value: number) => string) \| null | No |  | Value label formatter function, set to null to disable value label |
| `valueLabelAlwaysOn` | boolean | No | false | If true, value label will always be displayed |
| `valueLabelPosition` | 'top' \| 'bottom' \| 'left' \| 'right' | No |  | Where the value label sits relative to the thumb. For horizontal sliders: 'top' (above) or 'bottom' (below). For vertical: 'left' or 'right'. Defaults to 'top' / 'left'. |
| `valueLabelOffset` | number | No |  | Pixel gap between the thumb and the value label (default: 6 for top/bottom, 16 for left/right). |
| `valueLabelStyle` | StyleProp<ViewStyle> | No |  | Style applied to the value label wrapper (Card/View). |
| `valueLabelProps` | Omit<TextProps, 'children'> | No |  | Props applied to the value label `<Text>` (style, weight, ff, size, color). |
| `valueLabelAsCard` | boolean | No | true | When true (default) the value label is wrapped in a `<Card>`. Set to false to render only the bare `<Text>` for a flat tooltip. |
| `showMarks` | boolean | No |  | Show min/max labels |
| `ticks` | SliderTick[] | No |  | Custom ticks/marks to display on the slider |
| `containerSize` | number | No |  | Slider container size (width for horizontal, height for vertical) |
| `showTicks` | boolean | No | false | Whether to show automatic tick marks based on step |
| `restrictToTicks` | boolean | No | false | Restrict value changes to only tick positions |
| `inverted` | boolean | No |  | Inverted slider (right-to-left or top-to-bottom) |
| `precision` | number | No |  | Precision for value display |
| `tooltip` | 'always' \| 'hover' \| 'never' | No |  | Tooltip visibility |
| `fullWidth` | boolean | No | true | Make slider stretch to fill parent width/height |
| `disabled` | boolean | No | false | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `placeholder` | string | No |  | Input placeholder |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No | 'md' | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic Usage
ID: `Slider.basic` • Tags: basic, slider • Category: usage • Status: stable • Since: 1.0.0

Basic slider usage for selecting numeric values within a range.

```tsx
const [value, setValue] = useState(25);
  return (
    <Block fullWidth>
      <Slider
        value={value}
        onChange={setValue}
        min={0}
        max={100}
      />
    </Block>
  );
}
```

### Slider variants
ID: `Slider.variants` • Tags: variants, slider, styling • Category: usage • Status: stable • Since: 1.0.0

```tsx
const VARIANTS = ['default', 'filled', 'outline', 'minimal', 'segmented', 'unstyled'] as const;
  const [value, setValue] = useState(40);
  return (
    <Block fullWidth>
      {VARIANTS.map((variant) => (
        <Slider
          key={variant}
          label={variant}
          variant={variant}
          value={value}
          onChange={setValue}
          min={0}
          max={100}
          step={5}
          showTicks={variant === 'segmented'}
          restrictToTicks={variant === 'segmented'}
          fullWidth
        />
      ))}
    </Block>
  );
}
```

### Ticks and Marks
ID: `Slider.ticks` • Tags: ticks, marks, scale • Category: usage • Status: stable • Since: 1.0.0

Slider with visible tick marks and labeled values for better precision.

```tsx
const [value, setValue] = useState(50);
  return (
    <Block w={400}>
      <Slider
        value={value}
        onChange={setValue}
        min={0}
        max={100}
        showTicks
        restrictToTicks
        ticks={[
          { value: 0, label: 'Min' },
          { value: 25 },
          { value: 50, label: 'Mid' },
          { value: 75 },
          { value: 100, label: 'Max' },
        ]}
      />
    </Block>
  );
}
```

### Range Slider
ID: `Slider.range` • Tags: range, multiple, dual-thumb • Category: usage • Status: stable • Since: 1.0.0

Range slider for selecting a range of values with two handles on a single track. Perfect for filtering, price ranges, and any scenario where you need to select minimum and maximum values. Features demonstrated: - Basic range selection with two thumbs - Custom value formatting and labels - Tick marks and step increments - Minimum range constraints - Real-time range span calculation

```tsx
const [priceRange, setPriceRange] = useState<[number, number]>([25, 75]);
  const [temperatureRange, setTemperatureRange] = useState<[number, number]>([18, 24]);
  const [scoreRange, setScoreRange] = useState<[number, number]>([60, 90]);
  return (
    <Block fullWidth>
       <Card>
        <Block>
          <Text size="lg" weight="semibold">Price Range</Text>
          <Block>
            <Flex justify="space-between">
              <Text size="sm">Min: ${priceRange[0]}</Text>
              <Text size="sm">Max: ${priceRange[1]}</Text>
            </Flex>
            <RangeSlider
              value={priceRange}
              onChange={setPriceRange}
              min={0}
              max={100}
              step={5}
              label="Price Filter ($)"
              showTicks
            />
            <Text size="sm" style={{ color: '#666' }}>
              Budget range: ${priceRange[1] - priceRange[0]}
            </Text>
          </Block>
        </Block>
        </Card>
      <Card>
        <Block>
          <Text size="lg" weight="semibold">Temperature Range</Text>
          <Block>
            <RangeSlider
              value={temperatureRange}
              onChange={setTemperatureRange}
              min={10}
              max={30}
              step={0.5}
              label="Comfortable Temperature (°C)"
              valueLabel={(value) => `${value}°C`}
              valueLabelAlwaysOn
            />
            <Text size="sm" style={{ color: '#666' }}>
              Range: {temperatureRange[0]}°C - {temperatureRange[1]}°C
            </Text>
          </Block>
        </Block>
      </Card>
    </Block>
  );
}
```

### Value label customization
ID: `Slider.valueLabel` • Tags: tooltip, valueLabel, valueLabelProps, valueLabelPosition, customization • Category: general • Status: stable • Since: 1.0.0

`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`, `weight`, `size`, `color`, `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
const [a, setA] = useState(40);
  const [b, setB] = useState(60);
  const [c, setC] = useState(72);
  const [d, setD] = useState<[number, number]>([20, 80]);
  return (
    <Block>
      <Text weight="semibold">Value label position & styling</Text>
      <Block>
        <Text size="sm" color="muted">Default — tooltip above the thumb</Text>
        <Slider value={a} onChange={setA} valueLabelAlwaysOn />
      </Block>
      <Block>
        <Text size="sm" color="muted">valueLabelPosition="bottom"</Text>
        <Slider
          value={b}
          onChange={setB}
          valueLabelAlwaysOn
          valueLabelPosition="bottom"
          valueLabelOffset={2}
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Custom Text styling — `ff`, `weight`, `size`, `color`
        </Text>
        <Slider
          value={c}
          onChange={setC}
          valueLabelAlwaysOn
          valueLabelProps={{
            ff: 'monospace',
            weight: '700',
            size: 'md',
            color: 'primary',
          }}
          valueLabel={(v) => `${Math.round(v)}%`}
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Flat tooltip (no Card) with custom wrapper style
        </Text>
        <Slider
          value={c}
          onChange={setC}
          valueLabelAlwaysOn
          valueLabelAsCard={false}
          valueLabelStyle={{
            backgroundColor: 'rgba(15, 23, 42, 0.92)',
            paddingHorizontal: 8,
            paddingVertical: 4,
            borderRadius: 6,
          }}
          valueLabelProps={{ ff: 'monospace', weight: '600', color: '#fff' }}
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          RangeSlider — both thumbs share placement + styling
        </Text>
        <RangeSlider
          value={d}
          onChange={setD}
          valueLabelAlwaysOn
          valueLabelPosition="bottom"
          valueLabelProps={{ weight: '700', size: 'sm' }}
          valueLabel={(v, i) => (i === 0 ? `min ${Math.round(v)}` : `max ${Math.round(v)}`)}
        />
      </Block>
      <Block align="center" direction="row">
        <Block style={{ height: 200 }}>
            <Slider
              value={a}
              onChange={setA}
              orientation="vertical"
              valueLabelAlwaysOn
              valueLabelPosition="left"
              valueLabelProps={{ weight: '700' }}
              minH={80}
            />
          </Block>
        <Block style={{ height: 200 }}>
            <Slider
              value={b}
              onChange={setB}
              orientation="vertical"
              valueLabelAlwaysOn
              valueLabelPosition="right"
              valueLabelProps={{ weight: '700' }}
            />
            <Text size="xs" color="muted">right</Text>
          </Block>
      </Block>
    </Block>
  );
}
```

### Decimal steps & precision
ID: `Slider.precision` • Tags: precision, step, decimal, valueLabel, tooltip • Category: general • Status: stable • Since: 1.0.0

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
const [position, setPosition] = useState(0.25);
  const [temp, setTemp] = useState(21.5);
  const [ratio, setRatio] = useState(0.5);
  return (
    <Block>
      <Block>
        <Text size="sm" color="muted">
          Fractional `step={0.01}` — decimals are inferred from the step
        </Text>
        <Slider
          value={position}
          onChange={setPosition}
          min={0}
          max={1}
          step={0.01}
          valueLabelAlwaysOn
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          `step={0.5}` — half steps
        </Text>
        <Slider
          value={temp}
          onChange={setTemp}
          min={16}
          max={30}
          step={0.5}
          valueLabelAlwaysOn
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Force decimals with `precision={2}` (independent of step)
        </Text>
        <Slider
          value={ratio}
          onChange={setRatio}
          min={0}
          max={1}
          step={0.1}
          precision={2}
          valueLabelAlwaysOn
        />
      </Block>
    </Block>
  );
}
```

### Slot styling
ID: `Slider.slotStyling` • Tags: trackStyle, activeTrackStyle, thumbStyle, tickStyle, slot-props, customization • Category: general • Status: stable • Since: 1.0.0

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
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,
        // per-tick override wins over the global tickStyle / activeTickStyle
        style: {
          width: 4,
          height: 14,
          backgroundColor: '#facc15',
          borderRadius: 2,
          top: 11,
        },
      }
    : t,
);
  const [a, setA] = useState(35);
  const [b, setB] = useState(60);
  const [c, setC] = useState(50);
  const [d, setD] = useState<[number, number]>([20, 80]);
  return (
    <Block>
      <Text weight="semibold">Slot styling</Text>
      <Block>
        <Text size="sm" color="muted">
          Track + thumb overrides — taller track, square thumb
        </Text>
        <Slider
          value={a}
          onChange={setA}
          trackStyle={{ height: 10, borderRadius: 2 }}
          activeTrackStyle={{ height: 10, borderRadius: 2 }}
          thumbStyle={{ borderRadius: 4, borderWidth: 0 }}
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Branded thumb — gradient-style fill via solid color + shadow
        </Text>
        <Slider
          value={b}
          onChange={setB}
          activeTrackColor="#10b981"
          thumbStyle={{
            backgroundColor: '#0ea5e9',
            borderColor: '#0369a1',
            borderWidth: 2,
            shadowColor: '#0ea5e9',
            shadowOffset: { width: 0, height: 0 },
            shadowOpacity: 0.4,
            shadowRadius: 8,
          }}
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Tick + label styling (`tickStyle`, `activeTickStyle`, `tickLabelProps`)
        </Text>
        <Slider
          value={c}
          onChange={setC}
          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', weight: '700' }}
        />
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Per-tick override — the tick at 50 is taller and yellow
        </Text>
        <Slider
          value={c}
          onChange={setC}
          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 size="sm" color="muted">
          RangeSlider — same slot props work on both thumbs and the active band
        </Text>
        <RangeSlider
          value={d}
          onChange={setD}
          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', color: 'muted' }}
          valueLabelAlwaysOn
          valueLabelProps={{ weight: '700', size: 'sm' }}
        />
      </Block>
    </Block>
  );
}
```

### Vertical Orientation
ID: `Slider.vertical` • Tags: vertical, orientation • Category: usage • Status: stable • Since: 1.0.0

Vertical slider orientation for space-efficient layouts and different use cases.

```tsx
const [value, setValue] = useState(60);
  return (
    <Card>
      <Row gap={16} align="center">
        <Block style={{ height: 200 }}>
          <Slider
            value={value}
            onChange={setValue}
            min={0}
            max={100}
            step={1}
            orientation="vertical"
          />
        </Block>
        <Block>
          <Text size="lg" weight="semibold">Vertical Slider</Text>
          <Text size="sm" style={{ color: '#666' }}>
            Value: {value}
          </Text>
        </Block>
      </Row>
    </Card>
  );
}
```

### CustomStyles
ID: `Slider.customStyles` • Category: general

Showcases how to restyle the Slider using the new color scheme, sizing, and style override props for both single-value and range scenarios.

```tsx
const [volume, setVolume] = useState(65);
  const [range, setRange] = useState<[number, number]>([20, 80]);
  return (
    <Block fullWidth>
      <Card>
        <Block>
          <Text size="lg" weight="semibold">Palette-driven slider</Text>
          <Text size="sm" style={{ color: '#555' }}>
            `colorScheme`, sizing overrides, and style props let the slider carry product branding.
          </Text>
          <Slider
            value={volume}
            onChange={setVolume}
            min={0}
            max={100}
            step={1}
            showTicks
            tickColor="rgba(52, 199, 89, 0.2)"
            activeTickColor="#34C759"
            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 }}
            valueLabel={(val) => `${Math.round(val)}%`}
            valueLabelAlwaysOn
            label="Success palette"
          />
          <Flex justify="space-between">
            <Text size="sm">Volume: {Math.round(volume)}%</Text>
            <Text size="sm" style={{ color: '#1F5520' }}>Styled thumb + ticks</Text>
          </Flex>
        </Block>
      </Card>
      <Card>
        <Block>
          <Text size="lg" weight="semibold">Custom range slider</Text>
          <Text size="sm" style={{ color: '#555' }}>
            RangeSlider shares the same overrides, making it easy to mix palettes per context.
          </Text>
          <RangeSlider
            value={range}
            onChange={setRange}
            min={0}
            max={120}
            step={5}
            showTicks
            color="warning"
            trackSize={10}
            thumbSize={26}
            trackStyle={{ opacity: 0.2 }}
            activeTrackStyle={{ opacity: 0.55 }}
            thumbStyle={{ borderColor: '#B45309', borderWidth: 2 }}
            tickColor="rgba(251, 191, 36, 0.25)"
            activeTickColor="#F59E0B"
            valueLabel={(val, idx) => `${idx === 0 ? 'Min' : 'Max'} ${val}`}
            valueLabelAlwaysOn
            label="Warning palette"
          />
          <Flex justify="space-between">
            <Text size="sm">Range: {range[0]} – {range[1]}</Text>
            <Text size="sm" style={{ color: '#B45309' }}>Custom palette + styles</Text>
          </Flex>
        </Block>
      </Card>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Space`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Space } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: layout
- Tags: spacing, layout, utility
- Docs: https://react-ui-library.com/components/Space
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Space

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `h` | SizeValue | No |  | Height of the spacer. Accepts theme spacing tokens or raw numbers. |
| `w` | SizeValue | No |  | Width of the spacer. Accepts theme spacing tokens or raw numbers. |
| `size` | SizeValue | No | 'md' | Fallback size when neither `h` nor `w` is provided. Defaults to `md` so the component always occupies some space. |
| `style` | StyleProp<ViewStyle> | No |  | Optional style overrides. |
| `children` | never | No |  | Space is presentational only, so children are not supported. |

## Examples

### Vertical spacing
ID: `Space.basic` • Tags: spacing, layout • Category: basics • Status: stable • Since: 1.0.0

Compare token-based and numeric vertical gaps between stacked content blocks.

```tsx
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;
  const theme = useTheme();
  return (
    <Block>
      {EXAMPLES.map(({ label, gap, helper }) => (
        <Block key={label}>
          <Text weight="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" color="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Horizontal spacing
ID: `Space.horizontal` • Tags: spacing, layout • Category: layout • Status: stable • Since: 1.0.0

Use `Space` to control gutters between inline buttons with tokens or fixed widths.

```tsx
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;
  const theme = useTheme();
  return (
    <Block>
      {GROUPS.map(({ label, gap, helper }) => (
        <Block key={label}>
          <Text weight="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" color="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Spoiler.md -->

# Spoiler

The Spoiler component automatically collapses content that exceeds a specified height, providing a show/hide toggle to reveal the full content.

## Metadata

- Canonical name: `Spoiler`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Spoiler } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: display
- Docs: https://react-ui-library.com/components/Spoiler
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Spoiler

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | Yes |  | Content to hide/show |
| `maxHeight` | number | No |  | Max height (in px) when collapsed |
| `initiallyOpen` | boolean | No |  | Whether component starts initially opened |
| `showLabel` | string | No |  | Label for show more |
| `hideLabel` | string | No |  | Label for hide |
| `transitionDuration` | number | No |  | Transition duration ms |
| `size` | SizeValue | No |  | Size token for the show/hide control font size |
| `opened` | boolean | No |  | Optional controlled open state |
| `onToggle` | (opened: boolean) => void | No |  | Callback when toggle |
| `disabled` | boolean | No |  | Disable toggle |
| `style` | any | No |  | Optional style |
| `renderControl` | (args: { opened: boolean; toggle: () => void; showLabel: string; hideLabel: string }) => React.ReactNode | No |  | Render custom control |
| `transparentFade` | boolean | No |  | If true (default) fade bottom of clamped content to transparent using CSS mask on web |
| `fadeColor` | string | No |  | Fallback overlay gradient end color (used only when transparentFade=false) |
| `disableFadeAnimation` | boolean | No |  | Disable gradient fade animation (debug / perf). Default false (animation enabled). |
| `controlProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the show/hide control `<Text>` (style, weight, ff, size, color). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Spoiler.basic` • Tags: spoiler, collapse, content • Category: basics • Status: stable • Since: 1.0.0

Set `maxHeight` to reveal a preview of long copy while the rest stays accessible behind the built-in toggle.

```tsx
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.',
];
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Keep the initial height short to hint that more detail is available without overwhelming the layout.
        </Text>
        <Spoiler maxHeight={96}>
          <Block>
            {paragraphs.map((paragraph) => (
              <Text key={paragraph} size="sm">
                {paragraph}
              </Text>
            ))}
          </Block>
        </Spoiler>
      </Block>
    </Card>
  );
}
```

### Initial State
ID: `Spoiler.initiallyOpen` • Tags: spoiler, state, initially-open • Category: behavior • Status: stable • Since: 1.0.0

Flip the `initiallyOpen` prop to choose whether content renders expanded on mount or waits for user interaction.

```tsx
const examples = [
  {
    key: 'open',
    label: 'Initially open',
    description:
      'Starts expanded by default so the reader sees the full content on first render.',
    props: { initiallyOpen: true },
  },
  {
    key: 'closed',
    label: 'Initially closed',
    description:
      'Keeps the section compact to emphasize surrounding UI until the user opts in.',
    props: {},
  },
];
const bodyCopy =
  'Vivamus fermentum orci eget tortor facilisis, eu egestas eros maximus. Fusce vitae semper libero. Pellentesque habitant morbi tristique senectus et netus.';
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Control whether the content renders expanded on mount or waits for user input. Both states remain accessible to assistive tech.
        </Text>
        <Block>
          {examples.map((example) => (
            <Block key={example.key}>
              <Text size="xs" color="secondary">
                {example.label}
              </Text>
              <Spoiler maxHeight={72} {...example.props}>
                <Text size="sm">{bodyCopy}</Text>
              </Spoiler>
              <Text size="xs" color="muted">
                {example.description}
              </Text>
            </Block>
          ))}
        </Block>
      </Block>
    </Card>
  );
}
```

### Max Heights
ID: `Spoiler.sizes` • Tags: spoiler, layout, sizes • Category: layout • Status: stable • Since: 1.0.0

Dial the `maxHeight` value up or down to control how much content stays visible before the toggle appears.

```tsx
const longText =
  'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Integer tincidunt condimentum risus, sit amet cursus massa fermentum non.';
const examples = [
  { key: 'small', label: '60px height', maxHeight: 60 },
  { key: 'medium', label: '100px height', maxHeight: 100 },
  { key: 'large', label: '150px height', maxHeight: 150 },
];
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Adjust maxHeight to control how much text stays visible before the rest collapses behind the toggle.
        </Text>
        <Block>
          {examples.map((example) => (
            <Block key={example.key}>
              <Text size="xs" color="secondary">
                {example.label}
              </Text>
              <Spoiler maxHeight={example.maxHeight}>
                <Text size="sm">{longText}</Text>
              </Spoiler>
            </Block>
          ))}
        </Block>
      </Block>
    </Card>
  );
}
```

### Custom Control
ID: `Spoiler.customControl` • Tags: spoiler, render-control, controlled • Category: advanced • Status: stable • Since: 1.0.0

Use the `renderControl` callback alongside `opened` and `onToggle` to drive expansion with your own button or analytics hooks.

```tsx
const [isOpen, setIsOpen] = useState(false);
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Drive the spoiler state yourself to sync analytics or a sibling component. Use renderControl when you need a bespoke trigger.
        </Text>
        <Spoiler
          maxHeight={80}
          opened={isOpen}
          onToggle={setIsOpen}
          renderControl={({ opened, toggle }) => (
            <Button size="xs" variant="outline" onPress={toggle}>
              {opened ? 'Collapse content' : 'Expand content'}
            </Button>
          )}
        >
          <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>
    </Card>
  );
}
```

### Control customization
ID: `Spoiler.control-customization` • Tags: controlProps, customization, slot-props • Category: general • Status: stable • Since: 1.0.0

`controlProps` accepts any `<Text>` props (`ff`, `weight`, `tracking`, `uppercase`, `size`, `color`) 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
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.';
  return (
    <Block>
      <Block>
        <Text size="sm" color="muted">Default control</Text>
        <Spoiler maxHeight={60}>
          <Text>{longText}</Text>
        </Spoiler>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Uppercase tracked control
        </Text>
        <Spoiler
          maxHeight={60}
          showLabel="Read more"
          hideLabel="Hide"
          controlProps={{ uppercase: true, tracking: 1.5, weight: '700', size: 'xs' }}
        >
          <Text>{longText}</Text>
        </Spoiler>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          Monospace control
        </Text>
        <Spoiler
          maxHeight={60}
          showLabel="$ expand"
          hideLabel="$ collapse"
          controlProps={{ ff: 'monospace', weight: '600' }}
        >
          <Text>{longText}</Text>
        </Spoiler>
      </Block>
    </Block>
  );
}
```

### Newspaper
ID: `Spoiler.newspaper` • Category: general

Combine imagery with long-form copy to mimic a newspaper-style reveal where the reader can expand to see the full story.

```tsx
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.',
];
  const isWeb = Platform.OS === 'web';
  return (
    <Card p="md">
      <Spoiler maxHeight={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>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Spotlight.md -->

# Spotlight

The Spotlight component provides a fast, keyboard-driven interface for searching commands, routes, and entities. Supports arrow key navigation, Enter to select, and Escape to dismiss.

## Metadata

- Canonical name: `Spotlight`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Spotlight } from '@platform-blocks/react-ui-library';`
- Status: experimental
- Category: navigation
- Tags: command-palette, search, quick actions
- Docs: https://react-ui-library.com/components/Spotlight
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Spotlight

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `actions` | SpotlightItem[] | Yes |  |  |
| `nothingFound` | string | No |  |  |
| `highlightQuery` | boolean \| HighlightComponentProps['highlight'] | No |  |  |
| `limit` | number | No |  |  |
| `scrollable` | boolean | No |  |  |
| `maxHeight` | number | No |  |  |
| `shortcut` | string \| string[] \| null | No |  |  |
| `searchProps` | any | No |  |  |
| `store` | any | No |  |  |
| `variant` | 'modal' \| 'bottomsheet' \| 'fullscreen' | No |  |  |
| `width` | number | No |  |  |
| `height` | number | No |  |  |

## Examples

### Keyboard Palette
ID: `Spotlight.basic` • Tags: spotlight • Category: usage • Status: stable • Since: 1.0.0

Open the Spotlight command palette through the shared store and a primary trigger button.

```tsx
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'),
  },
];
  const [store] = useSpotlightStoreInstance();
  return (
    <Block>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Spotlight provides a keyboard-driven command palette. Open it with `⌘K` or `Ctrl+K`, or trigger it imperatively from a button.
          </Text>
          <Button onPress={() => store.open()}>Open spotlight</Button>
          <Text size="xs" color="secondary">
            You can reuse the same store across multiple triggers.
          </Text>
        </Block>
      </Card>
      <Spotlight actions={actions} store={store} />
    </Block>
  );
}
```

### Custom Icons
ID: `Spotlight.custom-icons` • Tags: spotlight • Category: customization • Status: stable • Since: 1.0.0

Swap `icon` definitions with custom React nodes to render richer action affordances.

```tsx
const actions: SpotlightProps['actions'] = [
  {
    id: 'deploy',
    label: 'Deploy service',
    description: 'Trigger the CI/CD pipeline',
    icon: <Icon name="bolt" size="md" />,
    onPress: () => console.log('deploy service'),
  },
  {
    id: 'logs',
    label: 'Inspect logs',
    description: 'Open the latest runtime logs',
    icon: <Icon name="code" size="md" />,
    onPress: () => console.log('view logs'),
  },
  {
    id: 'alerts',
    label: 'Review alerts',
    description: 'Check active incidents',
    icon: <Icon name="bell" size="md" />,
    onPress: () => console.log('open alerts'),
  },
];
  const [store] = useSpotlightStoreInstance();
  return (
    <Block>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Icons accept full React nodes, so you can swap in composable UI like `Icon`, avatars, or status badges for richer visuals.
          </Text>
          <Button variant="outline" onPress={() => store.open()}>
            Open spotlight
          </Button>
        </Block>
      </Card>
      <Spotlight actions={actions} store={store} />
    </Block>
  );
}
```

### Grouped Actions
ID: `Spotlight.groups` • Tags: spotlight • Category: organization • Status: stable • Since: 1.0.0

Organize actions into named groups so related commands render under semantic headers.

```tsx
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'),
      },
    ],
  },
];
  const [store] = useSpotlightStoreInstance();
  return (
    <Block>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Group actions to create semantic sections inside the results list. Each group renders a header before its nested actions.
          </Text>
          <Button variant="secondary" onPress={() => store.open()}>
            Open spotlight
          </Button>
        </Block>
      </Card>
      <Spotlight actions={actions} store={store} />
    </Block>
  );
}
```

### Highlight Matches
ID: `Spotlight.highlight-query` • Tags: spotlight • Category: feedback • Status: stable • Since: 1.0.0

Enable `highlightQuery` so matching substrings glow while you refine command searches.

```tsx
// Actions intentionally share overlapping substrings to show highlighting effect
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'),
  },
];
  const [store] = useSpotlightStoreInstance();
  return (
    <Block>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Passing `highlightQuery` emphasizes matching substrings across labels and descriptions, reinforcing why a result surfaced.
          </Text>
          <Button onPress={() => store.open()}>Open spotlight</Button>
          <Text size="xs" color="secondary">
            Try typing “proj” or “create” to see the inline highlights.
          </Text>
        </Block>
      </Card>
      <Spotlight actions={actions} highlightQuery store={store} />
    </Block>
  );
}
```

### Limit Results
ID: `Spotlight.limit-results` • Tags: spotlight • Category: behavior • Status: stable • Since: 1.0.0

Restrict how many matching actions render by applying the `limit` prop.

```tsx
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),
}));
  const [store] = useSpotlightStoreInstance();
  return (
    <Block>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Set the `limit` prop to constrain how many results render, even if more actions match the query.
          </Text>
          <Button onPress={() => store.open()}>Open spotlight</Button>
          <Text size="xs" color="secondary">
            This demo caps the list at 8 items.
          </Text>
        </Block>
      </Card>
      <Spotlight actions={actions} limit={8} store={store} />
    </Block>
  );
}
```

### Fullscreen Mobile
ID: `Spotlight.fullscreen-mobile` • Tags: spotlight • Category: layouts • Status: stable • Since: 1.0.0

Pin the `fullscreen` variant to mimic native command palettes on handheld devices.

```tsx
// Reuse a moderate list to showcase vertical scroll in fullscreen
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),
}));
  const [store] = useSpotlightStoreInstance();
  const isMobile = Platform.OS !== 'web';
  return (
    <Block>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Force the `fullscreen` variant to mimic a native sheet on touch devices while keeping the modal layout on web for comparison.
          </Text>
          <Button onPress={() => store.open()}>
            {isMobile ? 'Open fullscreen spotlight' : 'Open spotlight'}
          </Button>
          <Text size="xs" color="secondary">
            The component already auto-detects mobile surfaces; this demo pins the variant for clarity.
          </Text>
        </Block>
      </Card>
      <Spotlight actions={actions} variant="fullscreen" store={store} />
    </Block>
  );
}
```

### Programmatic Stores
ID: `Spotlight.programmatic` • Tags: spotlight • Category: advanced • Status: stable • Since: 1.0.0

Showcase scoped Spotlight stores, dynamic actions, and the global `spotlight` helper working together.

```tsx
Block,
  Button,
  Card,
  Row,
  spotlight,
  Spotlight,
  SpotlightProvider,
  Text,
  type SpotlightProps,
  useSpotlightStoreInstance,
} from '@platform-blocks/react-ui-library';
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'),
  },
];
  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>
        <Card p="md">
          <Block>
            <Text size="sm" color="secondary">
              Combine local stores with the global `spotlight` helper. This demo adds actions to its scoped store while still toggling the shared palette.
            </Text>
            <Row gap="sm" wrap="wrap">
              <Button onPress={() => store.open()}>Open demo store</Button>
              <Button variant="outline" onPress={() => spotlight.toggle()}>
                Toggle global spotlight
              </Button>
            </Row>
            <Text size="xs" color="secondary">
              Select “Add dynamic action” to append more commands on the fly.
            </Text>
          </Block>
        </Card>
        <Spotlight actions={actions} store={store} />
        <Spotlight actions={globalActions} />
      </Block>
    </SpotlightProvider>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Stepper.md -->

# Stepper

The Stepper component provides a step-by-step navigation interface, perfect for multi-step forms, wizards, and progress tracking.

## Metadata

- Canonical name: `Stepper`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Stepper } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: navigation
- Docs: https://react-ui-library.com/components/Stepper
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Stepper

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `active` | number | Yes |  | Active step index |
| `onStepClick` | (stepIndex: number) => void | No |  | Called when step is clicked |
| `orientation` | 'horizontal' \| 'vertical' | No |  | Step orientation |
| `iconPosition` | 'left' \| 'right' | No |  | Icon position relative to step body |
| `iconSize` | number | No |  | Icon size |
| `size` | ComponentSizeValue | No |  | Component size |
| `color` | string | No |  | Component color |
| `completedIcon` | ReactNode | No |  | Icon to display when step is completed |
| `allowNextStepsSelect` | boolean | No |  | Whether next steps (steps with higher index) can be selected |
| `children` | ReactNode | Yes |  | Step content |
| `ref` | React.Ref<HTMLDivElement> | No |  | Accessibility label Component reference |

## Examples

### Controlled Flow
ID: `Stepper.basic` • Tags: stepper • Category: usage • Status: stable • Since: 1.0.0

Control the active step with local state and show completion messaging once the flow finishes.

```tsx
const totalSteps = steps.length;
  const [activeStep, setActiveStep] = useState(1);
  const handleStepChange = (nextIndex: number) => {
    if (nextIndex < 0 || nextIndex > totalSteps) {
      return;
    }
    setActiveStep(nextIndex);
  };
  const goPrevious = () => handleStepChange(activeStep - 1);
  const goNext = () => handleStepChange(activeStep + 1);
  return (
    <Block fullWidth>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Control the current step with the `active` prop and provide completion content with `Stepper.Completed`.
          </Text>
          <Stepper active={activeStep} onStepClick={handleStepChange}>
            {steps.map((step) => (
              <Stepper.Step key={step.label} label={step.label} description={step.description}>
                {step.details}
              </Stepper.Step>
            ))}
            <Stepper.Completed>
              All onboarding tasks are complete. You can continue to the dashboard.
            </Stepper.Completed>
          </Stepper>
          <Row gap="sm" justify="space-between">
            <Button variant="outline" onPress={goPrevious} disabled={activeStep === 0}>
              Back
            </Button>
            <Button onPress={goNext} disabled={activeStep === totalSteps}>
              {activeStep === totalSteps - 1 ? 'Finish' : 'Next step'}
            </Button>
          </Row>
        </Block>
      </Card>
    </Block>
  );
}
```

### Visited Step Selection
ID: `Stepper.allowSelect` • Tags: stepper, selection • Category: behavior • Status: stable • Since: 1.0.0

Limit navigation to completed steps using `allowStepSelect`, while preserving forward progress through the flow.

```tsx
const totalSteps = steps.length;
  const [activeStep, setActiveStep] = useState(0);
  const [highestVisitedStep, setHighestVisitedStep] = useState(0);
  const handleStepChange = (nextIndex: number) => {
    if (nextIndex < 0 || nextIndex > totalSteps) {
      return;
    }
    setActiveStep(nextIndex);
    setHighestVisitedStep((previous) => Math.max(previous, Math.min(nextIndex, totalSteps - 1)));
  };
  const canSelectStep = (stepIndex: number) => highestVisitedStep >= stepIndex && activeStep !== stepIndex;
  const goPrevious = () => handleStepChange(activeStep - 1);
  const goNext = () => handleStepChange(activeStep + 1);
  return (
    <Block fullWidth>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Gate step selection with `allowStepSelect` so people can revisit completed steps without skipping ahead.
          </Text>
          <Stepper active={activeStep} onStepClick={handleStepChange}>
            {steps.map((step, index) => (
              <Stepper.Step
                key={step.label}
                label={step.label}
                description={step.description}
                allowStepSelect={canSelectStep(index)}
              >
                {step.details}
              </Stepper.Step>
            ))}
            <Stepper.Completed>
              Setup is complete. You can always return to earlier steps from the navigation.
            </Stepper.Completed>
          </Stepper>
          <Row gap="sm" justify="space-between">
            <Button variant="outline" onPress={goPrevious} disabled={activeStep === 0}>
              Back
            </Button>
            <Button onPress={goNext} disabled={activeStep === totalSteps}>
              {activeStep === totalSteps - 1 ? 'Finish' : 'Next step'}
            </Button>
          </Row>
        </Block>
      </Card>
    </Block>
  );
}
```

### Icon Overrides
ID: `Stepper.customIcons` • Tags: stepper, icons • Category: appearance • Status: stable • Since: 1.0.0

Swap icons for both active steps and the completed state to reinforce the status of each milestone.

```tsx
const totalSteps = steps.length;
  const [activeStep, setActiveStep] = useState(1);
  const handleStepChange = (nextIndex: number) => {
    if (nextIndex < 0 || nextIndex > totalSteps) {
      return;
    }
    setActiveStep(nextIndex);
  };
  const goPrevious = () => handleStepChange(activeStep - 1);
  const goNext = () => handleStepChange(activeStep + 1);
  return (
    <Block fullWidth>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Provide `icon` and `completedIcon` overrides to visually align each step with its stage.
          </Text>
          <Stepper
            active={activeStep}
            onStepClick={handleStepChange}
            completedIcon={<Icon name="check" size={18} color="white" />}
          >
            {steps.map((step) => (
              <Stepper.Step
                key={step.label}
                label={step.label}
                description={step.description}
                icon={<Icon name={step.icon} size={18} />}
              >
                {step.details}
              </Stepper.Step>
            ))}
            <Stepper.Completed>
              All setup tasks are complete with custom indicators for each stage.
            </Stepper.Completed>
          </Stepper>
          <Row gap="sm" justify="space-between">
            <Button variant="outline" onPress={goPrevious} disabled={activeStep === 0}>
              Back
            </Button>
            <Button onPress={goNext} disabled={activeStep === totalSteps}>
              {activeStep === totalSteps - 1 ? 'Finish' : 'Next step'}
            </Button>
          </Row>
        </Block>
      </Card>
    </Block>
  );
}
```

### Vertical Orientation
ID: `Stepper.vertical` • Tags: stepper, layout • Category: layout • Status: stable • Since: 1.0.0

Switch the orientation to vertical when you need more room for descriptive copy under each step.

```tsx
const totalSteps = steps.length;
  const [activeStep, setActiveStep] = useState(1);
  const handleStepChange = (nextIndex: number) => {
    if (nextIndex < 0 || nextIndex >= totalSteps) {
      return;
    }
    setActiveStep(nextIndex);
  };
  const goPrevious = () => handleStepChange(activeStep - 1);
  const goNext = () => handleStepChange(activeStep + 1);
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Switch to `orientation="vertical"` when steps need additional room for supporting copy.
        </Text>
        <Stepper active={activeStep} onStepClick={handleStepChange} orientation="vertical">
          {steps.map((step, index) => (
            <Stepper.Step key={step.label} label={step.label} description={step.description}>
              {step.details}
            </Stepper.Step>
          ))}
        </Stepper>
        <Row gap="sm" justify="space-between">
          <Button variant="outline" onPress={goPrevious} disabled={activeStep === 0}>
            Back
          </Button>
          <Button onPress={goNext} disabled={activeStep === totalSteps - 1}>
            Next step
          </Button>
        </Row>
      </Block>
    </Card>
  );
}
```

### Loading Indicator
ID: `Stepper.loading` • Tags: stepper, feedback • Category: feedback • Status: stable • Since: 1.0.0

Replace the step icon with a spinner during long-running work by toggling the `loading` prop.

```tsx
const totalSteps = 3;
  const [activeStep, setActiveStep] = useState(1);
  const [isLoading, setIsLoading] = useState(false);
  const timeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const handleStepChange = (nextIndex: number) => {
    if (nextIndex < 0 || nextIndex >= totalSteps) {
      return;
    }
    setActiveStep(nextIndex);
  };
  const simulateProcessing = () => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
    setIsLoading(true);
    timeoutRef.current = setTimeout(() => {
      setIsLoading(false);
      handleStepChange(2);
    }, 2000);
  };
  useEffect(() => () => {
    if (timeoutRef.current) {
      clearTimeout(timeoutRef.current);
    }
  }, []);
  return (
    <Block fullWidth>
      <Card p="md">
        <Block>
          <Text size="sm" color="secondary">
            Apply the `loading` prop to a step when a background task is running to replace the icon with a spinner.
          </Text>
          <Stepper active={activeStep} onStepClick={handleStepChange}>
            <Stepper.Step label="Collect details" description="Complete form">
              Share your project information to kick off the workflow.
            </Stepper.Step>
            <Stepper.Step label="Processing" description="Sync data" loading={isLoading}>
              We are syncing your data and preparing the workspace.
            </Stepper.Step>
            <Stepper.Step label="Ready" description="Launch">
              Setup is complete and the workspace is ready for collaborators.
            </Stepper.Step>
          </Stepper>
          <Row justify="center">
            <Button onPress={simulateProcessing} disabled={isLoading}>
              {isLoading ? 'Processing...' : 'Simulate processing'}
            </Button>
          </Row>
        </Block>
      </Card>
    </Block>
  );
}
```

### Size Variants
ID: `Stepper.sizes` • Tags: stepper, sizing • Category: appearance • Status: stable • Since: 1.0.0

Compare the `size` prop across the full `xs`–`3xl` scale while reusing the same steps.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Block fullWidth>
      {SIZES.map((size) => (
        <Block key={size} fullWidth>
          <Text variant="small" color="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://react-ui-library.com/llms/components/Surface.md -->

# Surface

The base container the rest of the library's elevated components are built from
— what other libraries call "paper".

A Surface owns exactly one decision: **how far off the page it sits.** `level`
resolves background, border color and default shadow as a set from
`theme.surfaces`, so a component can't end up with a level-3 shadow over a
level-0 fill, and no component has to pick a background color itself.

## Why a numeric ladder

Elevation is ordered and nestable, so the scale is numeric rather than a set of
named slots (`secondary`, `tertiary`, …). Two things fall out of that:

- **Nesting composes.** `raised` reads the enclosing Surface's level and adds
  one, so a popover opened inside a card lands a step above the card without
  either one knowing the other's number.
- **Scheme differences live in one place.** Light mode conveys elevation mostly
  with shadow; dark mode can't — shadows are invisible on a near-black page — so
  it uses a progressively lighter fill plus a hairline border. Encoding that in
  the ladder means call sites never branch on `colorScheme`.

## Theming

Override `surfaces` on your theme to retune every elevated component at once:

```ts
createTheme({
  surfaces: {
    0: { background: '#0B0B0F', border: '#1A1A20', shadow: 'none' },
    1: { background: '#16161C', border: '#26262E', shadow: 'xs' },
    2: { background: '#1E1E26', border: '#2E2E38', shadow: 'md' },
    3: { background: '#26262F', border: '#363642', shadow: 'xl' },
  },
})
```

Themes that don't define `surfaces` get a ladder derived from `backgrounds`
(`base` → `surface` → `elevated`), so existing custom themes keep working.

## Used by

Card sits at level 1 (2 for `variant="elevated"`); Menu, Select dropdowns and
Popover at level 2; Dialog at level 3. `useSurfaceLevel()` reports the level of
the surface the caller is rendered on, and `surfaceInteractionTint()` returns
hover/pressed/selected overlays that read correctly at any level.

## Metadata

- Canonical name: `Surface`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Surface } from '@platform-blocks/react-ui-library';`
- Category: layout
- Tags: surface, paper, elevation, container, layout
- Docs: https://react-ui-library.com/components/Surface
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Surface

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | No |  |  |
| `level` | SurfaceLevel | No |  | 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 | No |  | 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' | No |  | 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 | No |  | Border color override. Implies a border. |
| `borderWidth` | number | No |  | Border width override in px. Implies a border. |
| `bg` | string | No |  | Background override — CSS color, a `theme.backgrounds` key, or a palette name/`palette.shade`. Wins over the level's fill. |
| `padding` | SizeValue | No |  | Internal padding — size token or px. Surfaces have none by default. |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `testID` | string | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |
| `shadow` | ShadowValue | No |  | Shadow value - supports size tokens and 'none' |

## Examples

### Elevation levels
ID: `Surface.levels` • Tags: elevation, levels • Category: basics • Status: stable • Since: 0.11.0

Each level 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
const LEVELS = [
  { level: 0 as const, label: 'Level 0 — the page' },
  { level: 1 as const, label: 'Level 1 — resting content' },
  { level: 2 as const, label: 'Level 2 — floating over content' },
  { level: 3 as const, label: 'Level 3 — takes over the screen' },
];
  return (
    <Block fullWidth>
      {LEVELS.map(({ level, label }) => (
        <Surface key={level} level={level} padding="md" radius="lg" fullWidth>
          <Text size="sm">{label}</Text>
        </Surface>
      ))}
    </Block>
  );
}
```

### Nesting with raised
ID: `Surface.nesting` • Tags: nesting, raised, elevation • Category: basics • Status: stable • Since: 0.11.0

`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
return (
    <Surface level={0} padding="md" radius="lg" fullWidth>
      <Block>
        <Text size="sm" color="muted">
          Level 0 — the page
        </Text>
        <Surface raised padding="md" radius="lg" fullWidth>
          <Block>
            <Text size="sm">Raised once → level 1</Text>
            <Surface raised padding="md" radius="md" fullWidth>
              <Text size="sm">Raised again → level 2</Text>
            </Surface>
          </Block>
        </Surface>
      </Block>
    </Surface>
  );
}
```

### Surface vs Card
ID: `Surface.as-card` • Tags: card, composition • Category: usage • Status: stable • Since: 0.11.0

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
return (
    <Block fullWidth>
      <Surface level={1} padding="md" radius="lg" fullWidth>
        <Row align="center" justify="space-between">
          <Text size="sm">Surface — elevation only</Text>
          <Text size="sm" color="muted">
            level 1
          </Text>
        </Row>
      </Surface>
      <Card variant="elevated" padding="md" radius="lg" fullWidth>
        <Row align="center" justify="space-between">
          <Text size="sm">Card — Surface + padding + sections</Text>
          <Text size="sm" color="muted">
            level 2
          </Text>
        </Row>
      </Card>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Switch.md -->

# Switch

Switch components provide a way to toggle between two states, typically representing on/off or enabled/disabled states.

## Metadata

- Canonical name: `Switch`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Switch } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: input
- Tags: input, form, toggle, switch, boolean
- Docs: https://react-ui-library.com/components/Switch
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Switch

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `checked` | boolean | No |  | Whether switch is on |
| `defaultChecked` | boolean | No | false | Initial checked state for uncontrolled usage |
| `onChange` | (checked: boolean) => void | No |  | Change handler |
| `size` | SizeValue | No | 'md' | Switch size |
| `variant` | 'filled' \| 'outline' \| 'ios' \| 'android' | No | 'filled' | Visual style of the switch. - `filled` (default): solid track that fills with `color` when on, white thumb. - `outline`: transparent track with a colored border and a colored thumb when on. - `ios`: iOS-style pill — a large white thumb that nearly fills a rounded track. - `android`: Material-3-style — an outlined track with a small dot thumb that grows and turns white as the switch turns on. |
| `color` | ThemeColor | No | 'primary' | Switch color when on. A palette token, `'primary.6'` shade syntax, or any CSS color. |
| `transitionDuration` | number | No |  | 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. |
| `label` | React.ReactNode | No |  | Switch label |
| `disabled` | boolean | No | false | Whether switch is disabled |
| `required` | boolean | No | false | Whether switch is required |
| `error` | string | No |  | Error message |
| `description` | string | No |  | Helper text |
| `labelPosition` | 'left' \| 'right' \| 'top' \| 'bottom' | No | 'right' | Label position relative to switch |
| `children` | React.ReactNode | No |  | Switch content/children (alternative to label) |
| `onIcon` | React.ReactNode | No |  | Icon to show when on |
| `offIcon` | React.ReactNode | No |  | Icon to show when off |
| `onLabel` | string | No | 'On' | Labels for on/off states |
| `offLabel` | string | No | 'Off' |  |
| `controls` | string | No |  | Controlled component to show/hide |
| `accessibilityLabel` | string | No |  | Custom accessibility label (overrides label-based default) |
| `accessibilityHint` | string | No |  | Accessibility hint to describe what happens |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the description `<Text>` |
| `testID` | string | No |  | Component test ID for testing |
| `style` | any | No |  | Additional CSS styles |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Switch.basic` • Tags: controlled, label • Category: basics • Status: stable • Since: 1.0.0

Control a `Switch` with local state and surface its status with supporting text and the `description` prop.

```tsx
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" color="muted">
        Notices are {enabled ? 'enabled' : 'disabled'}.
      </Text>
    </Block>
  );
}
```

### Sizes
ID: `Switch.sizes` • Tags: size • Category: layout • Status: stable • Since: 1.0.0

Choose a `size` token to scale the switch track and thumb; `defaultChecked` seeds uncontrolled switches.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Row align="center" gap="lg" wrap="wrap">
      {SIZES.map((size) => (
        <Block key={size} align="center">
          <Switch size={size} defaultChecked />
          <Text variant="small">{size}</Text>
        </Block>
      ))}
    </Row>
  );
}
```

### Variants
ID: `Switch.variants` • Tags: variant, filled, outline • Category: appearance • Status: stable • Since: 1.0.0

Choose between a solid `filled` track (default) and an `outline` track whose border and thumb take on the active color.

```tsx
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;
  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" color="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
ID: `Switch.thumb-label` • Tags: thumb, onIcon, offIcon, label • Category: appearance • Status: stable • Since: 1.0.0

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
const theme = useTheme();
  const [wifi, setWifi] = useState<boolean>(true);
  const [available, setAvailable] = useState<boolean>(true);
  return (
    <Block>
      <Block>
        <Text variant="small" color="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.colors.gray[5]} stroke={3} />}
        />
      </Block>
      <Block>
        <Text variant="small" color="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.colors.gray[5] }}>
              OFF
            </Text>
          }
        />
      </Block>
    </Block>
  );
}
```

### Colors
ID: `Switch.colors` • Tags: color, semantic • Category: theming • Status: stable • Since: 1.0.0

Provide a `color` token to align switches with semantic palettes such as `primary`, `success`, or `error` states.

```tsx
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;
  return (
    <Block>
      <Text variant="small" color="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
ID: `Switch.states` • Tags: state, disabled, validation • Category: behavior • Status: stable • Since: 1.0.0

Present interactive, disabled, and validation states by combining `checked`, `disabled`, `required`, and `error` props.

```tsx
const [homeAlerts, setHomeAlerts] = useState(true);
  const [awayAlerts, setAwayAlerts] = useState(false);
  return (
    <Block>
      <Block>
        <Text variant="small" color="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" color="muted">
          Disabled states
        </Text>
        <Switch defaultChecked label="Lineup lock" disabled />
        <Switch label="Sound effects" disabled />
      </Block>
      <Block>
        <Text variant="small" color="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
ID: `Switch.sync` • Tags: controlled, summary • Category: behavior • Status: stable • Since: 1.0.0

Coordinate multiple switches with a shared state object and reflect the current selections in supporting copy.

```tsx
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
};
  const [settings, setSettings] = useState<Record<PreferenceKey, boolean>>(
    () => ({ ...INITIAL_SETTINGS })
  );
  return (
    <Block>
      <Block>
        <Text variant="small" color="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" color="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://react-ui-library.com/llms/components/Table.md -->

# Table

The Table component offers a minimal semantic wrapper (thead, tbody, tr, th, td) useful for simple static tabular data when the full DataTable is unnecessary.

## Metadata

- Canonical name: `Table`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Table } from '@platform-blocks/react-ui-library';`
- Status: experimental
- Category: data
- Tags: table, layout, semantic
- Docs: https://react-ui-library.com/components/Table
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Table

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | No |  |  |
| `data` | TableData | No |  | Table data for automatic generation of rows |
| `horizontalSpacing` | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number | No |  | Horizontal spacing between cells |
| `verticalSpacing` | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| number | No |  | Vertical spacing between cells |
| `striped` | boolean | No |  | Add striped styling to rows |
| `highlightOnHover` | boolean | No |  | Highlight rows on hover/press |
| `withTableBorder` | boolean | No |  | Add borders around table |
| `withColumnBorders` | boolean | No |  | Add borders between columns |
| `withRowBorders` | boolean | No |  | Add borders between rows |
| `captionSide` | 'top' \| 'bottom' | No |  | Caption position |
| `layout` | 'auto' \| 'fixed' | No |  | Table layout mode |
| `variant` | 'default' \| 'vertical' | No |  | Variant of table layout |
| `tabularNums` | boolean | No |  | Enable tabular numbers for better number alignment |
| `fullWidth` | boolean | No |  | Make table take full width of container |
| `columns` | Array<{ key?: string; width?: number \| string \| 'auto' \| 'min-content' \| 'max-content'; minWidth?: number; maxWidth?: number; flex?: number; }> | No |  | Column width configuration for auto-sizing |
| `style` | any | No |  | Additional styles |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Data Prop
ID: `Table.basic` • Tags: table • Category: usage • Status: stable • Since: 1.0.0

Pass a dataset to the `data` prop to render the caption, header, and body without composing subcomponents.

```tsx
return (
    <Block>
      <Text size="sm" color="secondary">
        Provide the `data` prop to render the caption, header, and body automatically.
      </Text>
      <Table data={data} withTableBorder fullWidth />
    </Block>
  );
}
```

### Border Options
ID: `Table.borders` • Tags: table, borders • Category: appearance • Status: stable • Since: 1.0.0

Enable `withTableBorder`, `withColumnBorders`, and `withRowBorders` to emphasize cell boundaries.

```tsx
return (
    <Block>
      <Text size="sm" color="secondary">
        Combine table, column, and row borders to separate dense numeric data.
      </Text>
      <Table
        data={data}
        withTableBorder
        withColumnBorders
        withRowBorders
        striped
        fullWidth
      />
    </Block>
  );
}
```

### Manual Composition
ID: `Table.custom` • Tags: table, composition • Category: usage • Status: stable • Since: 1.0.0

Use the table subcomponents when you need custom cells, alignments, or dynamic rows beyond the `data` helper.

```tsx
return (
    <Block>
      <Text size="sm" color="secondary">
        Compose tables manually for rich cells, spanning, or custom headers.
      </Text>
      <Table withTableBorder fullWidth>
        <Table.Caption>Manually composed table with rich cell content</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
ID: `Table.scroll` • Tags: table, scroll • Category: layout • Status: stable • Since: 1.0.0

Use `Table.ScrollContainer` to clamp table width and let users horizontally scroll large matrices.

```tsx
return (
    <Block>
      <Text size="sm" color="secondary">
        Wrap wide datasets in `Table.ScrollContainer` to enable horizontal scrolling.
      </Text>
      <Table.ScrollContainer minW={900}>
        <Table
          data={{ head: columns, body, caption: 'Wide matrix sample (scroll to explore)' }}
          withTableBorder
          striped
        />
      </Table.ScrollContainer>
    </Block>
  );
}
```

### Column Sizing
ID: `Table.sizing` • Tags: table, columns • Category: layout • Status: stable • Since: 1.0.0

Define the `columns` array to set fixed widths, min widths, or flex growth for responsive tables.

```tsx
return (
    <Block>
      <Text size="sm" color="secondary">
        Pass column sizing rules to control flex growth, widths, and minimums.
      </Text>
      <Table data={data} columns={columns} withTableBorder fullWidth />
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/TableOfContents.md -->

# TableOfContents

The `TableOfContents` component automatically discovers headings on the page (h1–h6) and renders a navigable outline with active section tracking. It supports scroll‑spy highlighting, deep-link copying, custom initial data (SSR / virtual docs), indentation control, appearance variants, and external active state notifications.

## Metadata

- Canonical name: `TableOfContents`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { TableOfContents } from '@platform-blocks/react-ui-library';`
- Since: 1.0.0
- Category: navigation
- Docs: https://react-ui-library.com/components/TableOfContents
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/TableOfContents

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | 'filled' \| 'outline' \| 'ghost' \| 'none' | No | 'none' | Visual style variant for the table of contents |
| `color` | string | No |  | Background color for filled variant. Falls back to theme primary color if not specified |
| `size` | SizeValue | No | 'sm' | Text size for table of contents items |
| `radius` | any | No |  | Border radius value for the container |
| `scrollSpyOptions` | ScrollSpyOptions | No |  | Configuration options for scroll spy behavior |
| `getControlProps` | (payload: { data: TocItem; active: boolean; index: number }) => any | No |  | Function to customize props for each table of contents item control |
| `initialData` | TocItem[] | No |  | Initial data for table of contents items (useful for SSR or pre-rendering) |
| `minDepthToOffset` | number | No | 1 | Minimum depth level at which to start applying depth offset indentation |
| `depthOffset` | number | No | 20 | Pixel offset to apply for each depth level (indentation amount) |
| `reinitializeRef` | React.RefObject<() => void> | No |  | Ref to expose the reinitialize function for manually triggering TOC refresh |
| `autoContrast` | boolean | No | false | Automatically adjust text color for contrast when using filled variant |
| `style` | any | No |  | Additional styles to apply to the container |
| `onActiveChange` | (id: string \| null, item?: TocItem) => void | No |  | Callback fired when the active item changes |
| `container` | string \| HTMLElement | No | 'main, [role="main"], .main-content, #main-content, article, .content, #content' | CSS selector string or HTMLElement to use as the scroll container |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basics
ID: `TableOfContents.basic` • Tags: navigation • Category: basics • Status: stable • Since: 0.3.0

Drop a table of contents beside your main article and it will register headings automatically through the shared title registry.

```tsx
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.' },
];
  const contentRef = useRef<HTMLDivElement | null>(null);
  return (
    <TitleRegistryProvider>
      <Row gap="xl" align="flex-start">
        <TableOfContents
          container={contentRef.current ?? undefined}
          variant="outline"
          size="sm"
          p="sm"
          style={{ width: 240 }}
        />
        <Block ref={contentRef} component="div" grow={1} style={{ maxWidth: 560 }}>
          {SECTIONS.map((section, index) => (
            <Block key={section.id}>
              <Title order={index === 0 ? 1 : 2}>{section.title}</Title>
              <Text color="secondary">{section.summary}</Text>
            </Block>
          ))}
        </Block>
      </Row>
    </TitleRegistryProvider>
  );
}
```

### Variants
ID: `TableOfContents.variants` • Tags: variants, color • Category: theming • Status: stable • Since: 0.3.0

Choose between the `outline`, `ghost`, `filled`, and `none` variants. Pair `filled` with `autoContrast` to keep labels legible against a brand color.

```tsx
const ITEMS = [
  { id: 'overview', value: 'Overview', depth: 1 },
  { id: 'tokens', value: 'Color tokens', depth: 2 },
  { id: 'accessibility', value: 'Accessibility', depth: 1 },
];
  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
ID: `TableOfContents.custom-initial` • Tags: ssr • Category: basics • Status: stable • Since: 0.3.0

Seed the table of contents with `initialData` so servers and prerender jobs can render the navigation before headings mount.

```tsx
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 },
];
  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
ID: `TableOfContents.depth-offset` • Tags: indentation • Category: theming • Status: stable • Since: 0.3.0

Use `minDepthToOffset` and `depthOffset` to indent nested headings so deep sections are easy to scan.

```tsx
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 },
];
  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
ID: `TableOfContents.active-callback` • Tags: navigation • Category: advanced • Status: stable • Since: 0.3.0

Subscribe to `onActiveChange` to surface the currently highlighted section, perfect for syncing status chips or analytics.

```tsx
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.' },
];
  const [activeId, setActiveId] = useState<string | null>(null);
  const contentRef = useRef<HTMLDivElement | 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={contentRef.current ?? undefined}
            variant="outline"
            size="xs"
            p="sm"
            style={{ width: 240 }}
            onActiveChange={setActiveId}
          />
          <Block ref={contentRef} component="div" grow={1} style={{ maxWidth: 560 }}>
            {SECTIONS.map((section, index) => (
              <Block key={section.id}>
                <Title order={index === 0 ? 1 : 2}>{section.title}</Title>
                <Text color="secondary">{section.summary}</Text>
              </Block>
            ))}
          </Block>
        </Row>
      </Block>
    </TitleRegistryProvider>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Tabs`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Tabs } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: navigation
- Docs: https://react-ui-library.com/components/Tabs
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Tabs

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `items` | TabItem[] | Yes |  | Array of tab definitions to render. The first item becomes active by default when uncontrolled. |
| `activeTab` | string | No |  | Controlled active tab key. When omitted the component manages internal state. |
| `onTabChange` | (tabKey: string) => void | No |  | Called whenever the active tab changes. Fires for both controlled and uncontrolled usage. |
| `onDisabledTabPress` | (tabKey: string, item: TabItem) => void | No |  | Invoked when a disabled tab is pressed, allowing custom messaging or recovery flows. |
| `variant` | 'line' \| 'chip' \| 'card' \| 'folder' | No | 'line' | Visual style of the tabs. |
| `size` | SizeValue | No | 'sm' | Size token controlling text and padding. |
| `color` | ThemeColor | No | 'primary' | Theme color token or custom color used for indicators and active states. |
| `orientation` | 'horizontal' \| 'vertical' | No | 'horizontal' | Orientation of the tab list. |
| `location` | 'start' \| 'end' | No | 'start' | Placement of the tabs relative to their content. Influences indicator positioning. |
| `scrollable` | boolean | No | false | Enables scrolling when tabs overflow the available axis. |
| `animated` | boolean | No | true | Enables animated indicator transitions between tabs. |
| `animationDuration` | number | No | 250 | Duration (ms) for indicator animations when `animated` is true. |
| `transitionDuration` | number | No | 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. |
| `style` | StyleProp<ViewStyle> | No |  | Style overrides for the outer container. |
| `tabStyle` | StyleProp<ViewStyle> | No |  | Style overrides applied to each tab pressable. |
| `contentStyle` | StyleProp<ViewStyle> | No |  | Style for the active tab content wrapper. |
| `textStyle` | StyleProp<TextStyle> | No |  | Additional text style applied to tab labels. |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to each tab's label `<Text>` (style, weight, ff, size, color). Applies to all tabs in the strip; per-tab styling can still be done via `TabItem.label` (custom node). |
| `disabledKeys` | string[] | No | [] | Array of tab keys that should be rendered disabled. |
| `tabCornerRadius` | number | No |  | Corner radius applied to the tab elements (variant dependent). |
| `contentCornerRadius` | number | No |  | Corner radius applied to the content panel. Falls back to theme defaults when omitted. |
| `indicatorThickness` | number | No |  | Thickness (px) of the line indicator. Applies to `line` variant primarily. |
| `tabGap` | number | No |  | Gap (px) inserted between tabs. |
| `activeTabBackgroundColor` | string | No |  | Override background color for the active tab. Accepts theme tokens. |
| `inactiveTabBackgroundColor` | string | No |  | Override background color for inactive tabs. |
| `activeTabTextColor` | string | No |  | Explicit text color for the active tab label. |
| `persistKey` | string | No |  | Key used to persist the active tab selection across sessions. |
| `autoPersist` | boolean | No | true | Determines whether internal persistence should be enabled when `persistKey` is provided. |
| `navigationOnly` | boolean | No | false | When true, the component only renders the tab list and forwards children for custom content. |
| `children` | ReactNode | No |  | Optional custom content rendered below the tab list when `navigationOnly` is enabled. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `radius` | number \| string | No |  |  |

## Examples

### Basics
ID: `Tabs.basic` • Tags: tabs • Category: basics • Status: stable • Since: 1.0.0

Render the default tabs experience with inline content and a short caption explaining the pattern.

```tsx
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>
  }
];
  return (
    <Block>
      <Tabs items={ITEMS} />
      <Text variant="small" color="muted">
        Tabs render inline content directly below the active trigger by default.
      </Text>
    </Block>
  );
}
```

### Animated transitions
ID: `Tabs.animated` • Tags: animation, tabs • Category: behavior • Status: stable • Since: 1.0.0

Demonstrates motion-enabled tabs using the `animated` flag and custom duration to smooth the switch between panels.

```tsx
const ITEMS = [
  {
    key: 'home',
    label: 'Home',
    content: (
      <Block>
        <Text weight="medium">Welcome back</Text>
        <Text color="muted">
          Animated transitions ease between dashboard sections and reinforce context shifts.
        </Text>
      </Block>
    )
  },
  {
    key: 'analytics',
    label: 'Analytics',
    content: (
      <Block>
        <Text weight="medium">Analytics overview</Text>
        <Text color="muted">
          Surface key charts and KPIs while the motion guides attention to new content.
        </Text>
      </Block>
    )
  },
  {
    key: 'settings',
    label: 'Settings',
    content: (
      <Block>
        <Text weight="medium">Account settings</Text>
        <Text color="muted">
          Manage notifications, billing, and other preferences without abrupt content swaps.
        </Text>
      </Block>
    )
  }
];
  return (
    <Block>
      <Tabs
        variant="line"
        animated
        animationDuration={250}
        items={ITEMS}
      />
      <Text variant="small" color="muted">
        Enable `animated` to add motion and use `animationDuration` to moderate the easing speed.
      </Text>
    </Block>
  );
}
```

### Disabled tabs
ID: `Tabs.disabled` • Tags: tabs, access-control • Category: behavior • Status: stable • Since: 1.0.0

Show how to disable a tab while capturing interaction attempts through `onDisabledTabPress` for auditing or messaging.

```tsx
const PANELS = [
  {
    key: 'overview',
    label: 'Overview',
    body: 'High-level snapshot of product activity and health.'
  },
  {
    key: 'analytics',
    label: 'Analytics',
    body: 'Dive into usage metrics, adoption trends, and retention.'
  },
  {
    key: 'billing',
    label: 'Billing',
    body: 'Billing is temporarily disabled while invoices reconcile.',
    disabled: true
  },
  {
    key: 'settings',
    label: 'Settings',
    body: 'Manage workspace preferences and security controls.'
  }
];
  const theme = useTheme();
  const [activeTab, setActiveTab] = useState('overview');
  const [lastAttempt, setLastAttempt] = useState<string | null>(null);
  return (
    <Block>
      <Tabs
        activeTab={activeTab}
        onTabChange={(tab) => {
          setActiveTab(tab);
          setLastAttempt(null);
        }}
        onDisabledTabPress={(key) => {
          const label = PANELS.find((panel) => panel.key === key)?.label ?? key;
          setLastAttempt(`${label} is currently disabled.`);
        }}
        variant="line"
        size="md"
        items={PANELS.map(({ body, ...panel }) => ({
          ...panel,
          content: (
            <Block bg={theme.backgrounds.surface} borderColor={theme.backgrounds.border} radius="lg" p="md">
              <Text>{body}</Text>
            </Block>
          )
        }))}
      />
      <Text variant="small" color="muted">
        Disable sensitive tabs while keeping the `onDisabledTabPress` callback to track attempted access.
        {lastAttempt ? ` ${lastAttempt}` : ''}
      </Text>
    </Block>
  );
}
```

### Controlled state
ID: `Tabs.interactive` • Tags: tabs, controlled • Category: behavior • Status: stable • Since: 1.0.0

Demonstrates controlled tabs that surface the active label and rely on external state updates via `onTabChange`.

```tsx
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>
  }
];
  const [activeTab, setActiveTab] = useState('dashboard');
  const activeLabel = ITEMS.find((item) => item.key === activeTab)?.label ?? activeTab;
  return (
    <Block>
      <Tabs activeTab={activeTab} onTabChange={setActiveTab} items={ITEMS} />
      <Text variant="small" color="muted">
        Active tab: {activeLabel}
      </Text>
    </Block>
  );
}
```

### Location
ID: `Tabs.location` • Tags: tabs, layout • Category: layout • Status: stable • Since: 1.0.0

Switch tab placement between `start` and `end` to position triggers above or below the associated content.

```tsx
type Location = 'start' | 'end';
const SECTIONS: Array<{ label: string; location: Location; helper: string }> = [
  {
    label: 'Tabs above content (start)',
    location: 'start',
    helper: 'Default placement keeps triggers directly above the active view.'
  },
  {
    label: 'Tabs below content (end)',
    location: 'end',
    helper: 'Use end placement when the content should lead and controls follow.'
  }
];
const buildItems = (location: Location) => [
  {
    key: 'home',
    label: 'Home',
    content: (
      <Text>
        Home content rendered with tabs {location === 'start' ? 'above' : 'below'} the panel.
      </Text>
    )
  },
  {
    key: 'settings',
    label: 'Settings',
    content: (
      <Text>
        Update configurations while keeping the tabs {location === 'start' ? 'up top' : 'after the details'}.
      </Text>
    )
  },
  {
    key: 'profile',
    label: 'Profile',
    content: (
      <Text>
        Profile information with navigation {location === 'start' ? 'leading into' : 'following'} the content.
      </Text>
    )
  }
];
  return (
    <Block>
      {SECTIONS.map(({ label, location, helper }) => (
        <Block key={location}>
          <Text weight="medium">{label}</Text>
          <Tabs variant="line" location={location} items={buildItems(location)} />
          <Text variant="small" color="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Navigation only
ID: `Tabs.navigation-only` • Tags: tabs, navigation • Category: layout • Status: stable • Since: 1.0.0

Demonstrates `navigationOnly` tabs that render the triggers separately while a custom container handles the content region.

```tsx
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.'
};
  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>
      <Tabs
        items={items}
        activeTab={activeTab}
        onTabChange={(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>
      <Text variant="small" color="muted">
        `navigationOnly` renders just the triggers so you can manage layout and transitions for the content area yourself.
      </Text>
    </Block>
  );
}
```

### Orientation
ID: `Tabs.orientation` • Tags: tabs, orientation • Category: layout • Status: stable • Since: 1.0.0

Compare horizontal and vertical tab lists to understand how orientation influences page layout.

```tsx
type Orientation = 'horizontal' | 'vertical';
const buildItems = (orientation: Orientation) => [
  {
    key: 'general',
    label: 'General',
    content: (
      <Text>
        Broad overview content rendered with a {orientation} tab list.
      </Text>
    )
  },
  {
    key: 'security',
    label: 'Security',
    content: (
      <Text>
        Security controls and permissions laid out for a {orientation} arrangement.
      </Text>
    )
  },
  {
    key: 'notifications',
    label: 'Notifications',
    content: (
      <Text>
        Configure alerts and digests with triggers stacked {orientation === 'vertical' ? 'in a column' : 'in a row'}.
      </Text>
    )
  }
];
const ORIENTATIONS: Array<{ label: string; orientation: Orientation; helper: string }> = [
  {
    label: 'Horizontal orientation',
    orientation: 'horizontal',
    helper: 'Default layout presents tabs in a row for top-level navigation.'
  },
  {
    label: 'Vertical orientation',
    orientation: 'vertical',
    helper: 'Vertical tab lists are ideal for settings sidebars and dense menus.'
  }
];
  return (
    <Block>
      {ORIENTATIONS.map(({ label, orientation, helper }) => (
        <Block key={orientation}>
          <Text weight="medium">{label}</Text>
          <Tabs orientation={orientation} items={buildItems(orientation)} />
          <Text variant="small" color="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

### Variants
ID: `Tabs.variants` • Tags: tabs, variants • Category: styling • Status: stable • Since: 1.0.0

Compare the `line`, `chip`, and `folder` visual variants to match tabs with different design aesthetics.

```tsx
type Variant = NonNullable<ComponentProps<typeof Tabs>['variant']>;
const VARIANT_DEMOS: Array<{
  heading: string;
  variant: Variant;
  helper: string;
  items: Array<{ key: string; label: string; description: string }>;
}> = [
  {
    heading: 'Line variant',
    variant: 'line',
    helper: 'Minimal underline style aligns with primary navigation patterns.',
    items: [
      { key: 'documents', label: 'Documents', description: 'Underline emphasizes the active document view.' },
      { key: 'images', label: 'Images', description: 'Great for media browsers with subtle hierarchy.' },
      { key: 'videos', label: 'Videos', description: 'Pairs well with narrow tab bars and dense content.' }
    ]
  },
  {
    heading: 'Chip variant',
    variant: 'chip',
    helper: 'Rounded pills feel tactile and work well for filters or secondary navigation.',
    items: [
      { key: 'overview', label: 'Overview', description: 'Pills highlight the selected state with a filled background.' },
      { key: 'details', label: 'Details', description: 'Suitable for segmented controls or inline filters.' },
      { key: 'settings', label: 'Settings', description: 'Works nicely for preference toggles.' }
    ]
  },
  {
    heading: 'Folder variant',
    variant: 'folder',
    helper: 'Raised folder styling evokes classic tabbed interfaces.',
    items: [
      { key: 'overview-folder', label: 'Overview', description: 'Ideal for dashboards with nested content.' },
      { key: 'details-folder', label: 'Details', description: 'Tabs feel like document dividers for data-heavy views.' },
      { key: 'settings-folder', label: 'Settings', description: 'Keeps controls organized in admin interfaces.' }
    ]
  }
];
  return (
    <Block>
      {VARIANT_DEMOS.map(({ heading, variant, helper, items }) => (
        <Block key={variant}>
          <Text weight="medium">{heading}</Text>
          <Tabs
            variant={variant}
            items={items.map(({ description, ...item }) => ({
              ...item,
              content: <Text>{description}</Text>
            }))}
          />
          <Text variant="small" color="muted">
            {helper}
          </Text>
        </Block>
      ))}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Text.md -->

# Text

Text component provides consistent typography with various variants, colors, and styling options for displaying content.

## Metadata

- Canonical name: `Text`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Text } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: typography
- Tags: text, typography, content, display
- Docs: https://react-ui-library.com/components/Text
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Text

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | React.ReactNode | No |  | Text node children. Optional if using translation via `tx`. |
| `tx` | string | No |  | Translation key (if provided, overrides children when found) |
| `txParams` | Record<string, any> | No |  | Params for translation interpolation |
| `variant` | HTMLTextVariant | No |  | Text variant (mirrors semantic HTML tags) |
| `size` | SizeValue | No |  | Size can be a size token or number (overrides variant fontSize) |
| `color` | string | No |  | Text color. Accepts a `theme.text` role (`'primary'`, `'secondary'`, `'muted'`, `'disabled'`, `'link'`), `'dimmed'` for the muted token, a palette name (`'success'` → its readable shade), `'primary.6'` shade syntax, or any CSS color string. |
| `c` | string | No |  | Shorthand alias for `color`, resolved identically. `color` wins when both are set. |
| `weight` | 'normal' \| 'medium' \| 'semibold' \| 'bold' \| 'light' \| 'black' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' \| number | No |  | Font weight (supports all CSS font-weight values) |
| `align` | 'left' \| 'center' \| 'right' \| 'justify' | No |  | Text alignment |
| `lineHeight` | number | No |  | Line height as a multiplier (e.g., 1.5) or absolute value |
| `tracking` | number | No |  | Letter spacing (tracking) in pixels or em units |
| `uppercase` | boolean | No |  | Convert text to uppercase |
| `style` | any | No |  | Additional styles (overrides computed styles) |
| `fontFamily` | string | No |  | Custom font family (overrides theme font) |
| `ff` | string | No |  | Shorthand alias for `fontFamily` |
| `as` | HTMLTextVariant | No |  | For platform-specific rendering on web |
| `selectable` | boolean | No |  | Whether text is selectable (default: true) |
| `onPress` | () => void | No |  | Called when text is pressed |
| `onLayout` | (event: any) => void | No |  | Called when the text layout is calculated |
| `value` | string \| number | No |  | Value to display (overrides children, useful for numbers) |
| `numberOfLines` | RNTextProps['numberOfLines'] | No |  | Maximum number of lines to display (native + web) |
| `ellipsizeMode` | RNTextProps['ellipsizeMode'] | No |  | Ellipsis strategy when text exceeds available space |
| `id` | string | No |  | Element id. On web this is the DOM `id` — headings need one to be a link target. |
| `nativeID` | string | No |  | React Native alias for `id`; used when the two platforms need different values. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Text.basic` • Tags: basic, typography • Category: usage • Status: stable • Since: 1.0.0

Basic text usage with different variants and semantic elements.

```tsx
return (
    <Block>
      <Card p="md">
        <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>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p">Body text is the default variant for paragraphs.</Text>
          <Text variant="small">Caption text keeps supporting details readable.</Text>
          <Text variant="small">Small text works well for fine print or metadata.</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text>Default text without a variant falls back to body styling.</Text>
          <Text>
            This paragraph shows natural wrapping behavior when the content spans multiple lines in a layout.
          </Text>
        </Block>
      </Card>
    </Block>
  );
}
```

### Colors
ID: `Text.colors` • Tags: colors, theming • Category: usage • Status: stable • Since: 1.0.0

Text color variants and custom color options for different contexts.

```tsx
return (
    <Block>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Semantic colors
          </Text>
          <Text color="primary">Primary color text</Text>
          <Text color="secondary">Secondary color text</Text>
          <Text color="muted">Muted color text</Text>
          <Text color="disabled">Disabled color text</Text>
          <Text color="link">Link color text</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Custom palette
          </Text>
          <Text color="#ff6b6b">Custom red text</Text>
          <Text color="#4ecdc4">Custom teal text</Text>
          <Text color="#45b7d1">Custom blue text</Text>
          <Text color="#96ceb4">Custom green text</Text>
          <Text color="#feca57">Custom yellow text</Text>
        </Block>
      </Card>
    </Block>
  );
}
```

### c (color shorthand)
ID: `Text.c-shorthand` • Tags: c, color, shorthand, theme • Category: general • Status: stable • Since: 1.0.0

`c` is a shorthand for `color` that resolves through the theme. Accepts: - `'dimmed'` → maps to `theme.text.muted` - Theme text keys (`'primary'`, `'secondary'`, `'muted'`, `'disabled'`, `'link'`) - Palette names (`'primary'`, `'success'`, …) → palette shade-6 (readable text) - `'palette.shade'` syntax (`'primary.6'`) - Any CSS color string

```tsx
return (
    <Block>
      <Text weight="semibold">c (color shorthand)</Text>
      <Text c="dimmed">c="dimmed" — maps to theme.text.muted</Text>
      <Text c="primary">c="primary" — primary palette text shade</Text>
      <Text c="error">c="error" — error palette readable shade</Text>
      <Text c="success">c="success"</Text>
      <Text c="primary.5">c="primary.5" — explicit shade</Text>
      <Text c="error.7">c="error.7" — darker error</Text>
      <Text c="#a855f7">c="#a855f7" — raw CSS color</Text>
      <Text>
        Inline composition:{' '}
        <Text c="dimmed">subtle inline text</Text> next to{' '}
        <Text c="primary" weight="600">brand text</Text>.
      </Text>
    </Block>
  );
}
```

### Weights
ID: `Text.weights` • Tags: weights, typography • Category: usage • Status: stable • Since: 1.0.0

Different font weight options from light to bold.

```tsx
return (
    <Block>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Named weights
          </Text>
          <Text weight="light">Light weight text</Text>
          <Text weight="normal">Normal weight text (default)</Text>
          <Text weight="medium">Medium weight text</Text>
          <Text weight="semibold">Semibold weight text</Text>
          <Text weight="bold">Bold weight text</Text>
          <Text weight="black">Black weight text</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Numeric weights
          </Text>
          <Text weight="100">Weight 100 (Thin)</Text>
          <Text weight="300">Weight 300 (Light)</Text>
          <Text weight="400">Weight 400 (Normal)</Text>
          <Text weight="600">Weight 600 (Semibold)</Text>
          <Text weight="700">Weight 700 (Bold)</Text>
          <Text weight="900">Weight 900 (Black)</Text>
        </Block>
      </Card>
    </Block>
  );
}
```

### Font family (ff shorthand)
ID: `Text.ff` • Tags: font, fontFamily, ff, typography • Category: usage • Status: stable • Since: 1.0.0

`ff` is the shorthand alias for `fontFamily`. Both forms work; `ff` wins when both are set. The same alias is also accepted by Title, the H1–H6 / Code / Kbd / Bold / Italic aliases, Highlight, GradientText, ShimmerText, and the field components via `labelProps` / `descriptionProps` / `disclaimerProps`.

```tsx
return (
    <Block>
      <Text weight="semibold">ff (font family) shorthand</Text>
      <Block>
        <Text size="sm" color="muted">Default theme font (no override)</Text>
        <Text>The quick brown fox jumps over the lazy dog</Text>
      </Block>
      <Block>
        <Text size="sm" color="muted">ff="monospace"</Text>
        <Text ff="monospace">The quick brown fox jumps over the lazy dog</Text>
      </Block>
      <Block>
        <Text size="sm" color="muted">ff="Georgia, serif" — also works on Title aliases</Text>
        <H3 ff="Georgia, serif">Heading in Georgia</H3>
      </Block>
      <Block>
        <Text size="sm" color="muted">
          fontFamily still works (ff takes precedence when both are set)
        </Text>
        <Text fontFamily="Courier New">Inline using `fontFamily` — long form</Text>
        <Text ff="Georgia" fontFamily="Courier New">
          Both set: `ff="Georgia"` wins
        </Text>
      </Block>
      <Block>
        <Text size="sm" color="muted">Inline Code/Kbd inherit ff too</Text>
        <Text>
          Press <Code ff="ui-monospace, monospace">cmd+k</Code> to open spotlight
        </Text>
      </Block>
    </Block>
  );
}
```

### Sizes
ID: `Text.sizes` • Tags: sizes, scale • Category: usage • Status: stable • Since: 1.0.0

Different text sizes from small to large.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  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
ID: `Text.heights` • Tags: line-height, spacing • Category: usage • Status: stable • Since: 1.0.0

Line height control for text content using the `lineHeight` prop. ## Usage The `lineHeight` prop accepts: - **Multipliers** (e.g., `1.5`) - multiplied by the font size - **Absolute values** (e.g., `24`) - treated as pixel values when > 3 ```tsx <Text lineHeight={1.2}>Tight line height</Text> <Text lineHeight={1.5}>Normal line height</Text> <Text lineHeight={24}>Absolute line height (24px)</Text> ``` This provides precise control over text spacing and readability.

```tsx
const SAMPLE_TEXT =
  'This paragraph shows how line height changes the spacing between lines of text when content wraps across multiple lines.';
  return (
    <Card p="md">
      <Block>
        <Block>
          <Text variant="p" weight="medium">
            Tight line height (1.2)
          </Text>
          <Text lineHeight={1.2}>{SAMPLE_TEXT}</Text>
        </Block>
        <Block>
          <Text variant="p" weight="medium">
            Standard line height (1.5)
          </Text>
          <Text lineHeight={1.5}>{SAMPLE_TEXT}</Text>
        </Block>
        <Block>
          <Text variant="p" weight="medium">
            Relaxed line height (1.8)
          </Text>
          <Text lineHeight={1.8}>{SAMPLE_TEXT}</Text>
        </Block>
        <Block>
          <Text variant="p" weight="medium">
            Loose line height (2.0)
          </Text>
          <Text lineHeight={2}>{SAMPLE_TEXT}</Text>
        </Block>
        <Block>
          <Text variant="p" weight="medium">
            Absolute line height (24px)
          </Text>
          <Text lineHeight={24}>{SAMPLE_TEXT}</Text>
        </Block>
      </Block>
    </Card>
  );
}
```

### Tracking
ID: `Text.tracking` • Tags: tracking, letter-spacing • Category: styling • Status: stable • Since: 1.0.0

Use the `tracking` prop to adjust letter spacing for text. Negative values tighten spacing, positive values loosen it, and numeric tokens work alongside size and variant changes. - Combine tracking with different `size` values to balance compact and spacious typography. - Headings can use subtle negative tracking for denser compositions. - Uppercase text often benefits from wider tracking to maintain legibility.

```tsx
return (
    <Block>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Negative tracking (tighter)
          </Text>
          <Text tracking={-1}>This text uses -1px letter spacing.</Text>
          <Text tracking={-0.5}>This text uses -0.5px letter spacing.</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Default tracking
          </Text>
          <Text>This text keeps the default letter spacing.</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Positive tracking (looser)
          </Text>
          <Text tracking={0.5}>This text uses 0.5px letter spacing.</Text>
          <Text tracking={1}>This text uses 1px letter spacing.</Text>
          <Text tracking={2}>This text uses 2px letter spacing.</Text>
          <Text tracking={4}>This text uses 4px letter spacing.</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Different sizes with tracking
          </Text>
          <Text size="xs" tracking={1}>Extra small with 1px tracking.</Text>
          <Text size="sm" tracking={1}>Small with 1px tracking.</Text>
          <Text size="md" tracking={1}>Medium with 1px tracking.</Text>
          <Text size="lg" tracking={1}>Large with 1px tracking.</Text>
          <Text size="xl" tracking={2}>Extra large with 2px tracking.</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Headings with tracking
          </Text>
          <Text variant="h1" tracking={-1}>H1 heading with -1px tracking</Text>
          <Text variant="h2" tracking={0}>H2 heading with default tracking</Text>
          <Text variant="h3" tracking={1}>H3 heading with 1px tracking</Text>
        </Block>
      </Card>
      <Card p="md">
        <Block>
          <Text variant="p" weight="medium">
            Uppercase spacing
          </Text>
          <Text weight="bold" tracking={3} uppercase>
            Uppercase text with wide tracking
          </Text>
        </Block>
      </Card>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `TextArea`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { TextArea } from '@platform-blocks/react-ui-library';`
- Category: input
- Tags: input, textarea, multiline, text, form, validation
- Docs: https://react-ui-library.com/components/TextArea
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/TextArea

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `defaultValue` | string | No |  | Default value for uncontrolled mode |
| `rows` | number | No |  | Number of rows (height) for the textarea |
| `minRows` | number | No |  | Minimum number of rows |
| `maxRows` | number | No |  | Maximum number of rows |
| `autoResize` | boolean | No |  | Whether to automatically resize based on content |
| `maxLength` | number | No |  | Character limit |
| `showCharCounter` | boolean | No |  | Show character counter |
| `h` | number | No |  | Fixed height for the TextArea |
| `resize` | 'none' \| 'vertical' \| 'horizontal' \| 'both' | No |  | Resize behavior |
| `textInputProps` | Omit<TextInputProps, keyof BaseInputProps> | No |  | Additional TextInput props |
| `autoCapitalize` | RNTextInputProps['autoCapitalize'] | No |  | Text auto-capitalization behavior |
| `autoCorrect` | boolean | No |  | Whether to enable auto-correct |
| `autoFocus` | boolean | No |  | Whether to auto-focus on mount |
| `returnKeyType` | RNTextInputProps['returnKeyType'] | No |  | Return key type for soft keyboard |
| `blurOnSubmit` | boolean | No |  | Whether to blur on submit |
| `selectTextOnFocus` | boolean | No |  | Select all text on focus |
| `textContentType` | RNTextInputProps['textContentType'] | No |  | iOS text content type for autofill |
| `textAlign` | RNTextInputProps['textAlign'] | No |  | Text alignment |
| `spellCheck` | boolean | No |  | Whether spell check is enabled |
| `inputMode` | RNTextInputProps['inputMode'] | No |  | Input mode (modern alternative to keyboardType) |
| `enterKeyHint` | RNTextInputProps['enterKeyHint'] | No |  | Enter key hint |
| `selectionColor` | string | No |  | Color of the text selection handles and highlight |
| `showSoftInputOnFocus` | boolean | No |  | Whether to show the soft keyboard on focus |
| `editable` | boolean | No |  | Whether the field is editable |
| `scrollEnabled` | boolean | No |  | Whether scroll is enabled (multiline) |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `value` | string | No |  | Input value |
| `onChangeText` | (text: string) => void | No |  | Change handler |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `placeholder` | string | No |  | Input placeholder |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No |  | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearable` | boolean | No |  | Show built-in clear button when input has value |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `TextArea.basic` • Tags: basic, multiline, textarea • Category: usage • Status: stable • Since: 1.0.0

Controlled text area with helper copy and inline character count feedback.

```tsx
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."
        error={value.length > 120 ? 'Message is too long. Keep it under 120 characters.' : undefined}
        rows={4}
        fullWidth
      />
      {value ? (
        <Text size="xs" color="secondary">
          Character count: {value.length}
        </Text>
      ) : null}
    </Block>
  );
}
```

### Features
ID: `TextArea.features` • Tags: features, counter, resize, autoresize • Category: features • Status: stable • Since: 1.0.0

Showcases auto-resize, character counting, validation, disabled, and required helper scenarios.

```tsx
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
        />
      <Block>
        <Text size="sm" weight="semibold">
          Character counter
        </Text>
        <Text size="sm" color="secondary">
          Enforces a maximum length while surfacing a live counter.
        </Text>
        <TextArea
          label="Support message"
          placeholder="Type to see the counter (max 100 characters)"
          value={counterValue}
          onChangeText={setCounterValue}
          maxLength={100}
          showCharCounter
          rows={3}
          helperText="Helpful for concise feedback or short-form inputs."
          fullWidth
        />
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          Error and required states
        </Text>
        <Text size="sm" color="secondary">
          Show validation messaging when the field is empty.
        </Text>
        <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
        />
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          Disabled field
        </Text>
        <Text size="sm" color="secondary">
          Communicates when editing is not allowed.
        </Text>
        <TextArea
          label="Disabled text area"
          placeholder="Disabled state"
          value="This text area is disabled and cannot be edited."
          disabled
          rows={2}
          fullWidth
        />
      </Block>
      <Block>
        <Text size="sm" weight="semibold">
          Required helper copy
        </Text>
        <Text size="sm" color="secondary">
          Pair helper text with the required badge to give extra guidance.
        </Text>
        <TextArea
          label="Required with helper"
          placeholder="Add details"
          required
          rows={2}
          helperText="Required fields display an asterisk and supporting guidance."
          fullWidth
        />
      </Block>
    </Block>
  );
}
```

### Sizes
ID: `TextArea.sizes` • Tags: sizes, dimensions, height • Category: styling • Status: stable • Since: 1.0.0

Walks the full `size` scale, `xs` through `3xl`, so the field matches the surrounding form density.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Block fullWidth>
      {SIZES.map((size) => (
        <Block key={size} fullWidth>
          <Text variant="small" color="secondary">{size}</Text>
          <TextArea size={size} rows={3} placeholder="Write a message" fullWidth />
        </Block>
      ))}
    </Block>
  );
}
```

### Validation
ID: `TextArea.validation` • Tags: validation, error, required, feedback • Category: states • Status: stable • Since: 1.0.0

Demonstrates required validation, length limits, inline success messaging, and error summaries.

```tsx
type ValidationErrors = {
  feedback?: string;
  message?: string;
};
  const [feedback, setFeedback] = useState('');
  const [message, setMessage] = useState('');
  const [errors, setErrors] = useState<ValidationErrors>({});
  const [status, setStatus] = useState('');
  const validateForm = () => {
    const nextErrors: ValidationErrors = {};
    if (!feedback.trim()) {
      nextErrors.feedback = 'Feedback is required.';
    } else if (feedback.trim().length < 10) {
      nextErrors.feedback = 'Feedback must be at least 10 characters.';
    }
    if (message.length > 500) {
      nextErrors.message = 'Message cannot exceed 500 characters.';
    }
    setErrors(nextErrors);
    return Object.keys(nextErrors).length === 0;
  };
  const handleSubmit = () => {
    if (validateForm()) {
      setStatus('Feedback submitted successfully.');
      return;
    }
    setStatus('');
  };
  return (
    <Block fullWidth>
      <Block>
        <Text size="sm" weight="semibold">
          Required feedback
        </Text>
        <Text size="sm" color="secondary">
          Must include at least ten characters before the form can submit.
        </Text>
        <TextArea
          label="Feedback"
          placeholder="Share your thoughts (minimum 10 characters)"
          value={feedback}
          onChangeText={(value) => {
            setFeedback(value);
            if (errors.feedback) {
              setErrors((prev) => ({ ...prev, feedback: undefined }));
            }
          }}
          error={errors.feedback}
          required
          rows={4}
          helperText="Tell us what went well and what could improve."
          fullWidth
        />
      </Block>
      <Button variant="filled" onPress={handleSubmit}>
        Submit feedback
      </Button>
      {status ? (
        <Text size="xs" color="success">
          {status}
        </Text>
      ) : null}
      {Object.keys(errors).length > 0 && (
        <Block
          style={{
            borderRadius: 8,
            borderWidth: 1,
            borderColor: '#FCA5A5',
            backgroundColor: '#FEF2F2',
            padding: 12,
          }}
        >
          <Text size="sm" weight="semibold" color="error">
            Please fix the following before submitting:
          </Text>
          {Object.values(errors)
            .filter(Boolean)
            .map((errorMessage) => (
              <Text key={errorMessage} size="xs" color="error">
                • {errorMessage}
              </Text>
            ))}
        </Block>
      )}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Timeline.md -->

# Timeline

Timeline component displays a sequence of events or steps in chronological order with customizable styling and layout options.

## Metadata

- Canonical name: `Timeline`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Timeline } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: data
- Tags: timeline, chronological, events, history, steps
- Docs: https://react-ui-library.com/components/Timeline
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Timeline

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `children` | ReactNode | Yes |  | Timeline items |
| `active` | number | No |  | Active item index - items before this will be highlighted |
| `color` | string | No |  | Timeline color. Palette token, `'primary.5'` shade syntax, or any CSS color. |
| `titleColor` | string | No |  | Default title color for all items |
| `descriptionColor` | string | No |  | Default description color for all items |
| `timestampColor` | string | No |  | Default timestamp color for all items |
| `lineWidth` | number | No |  | Line width |
| `bulletSize` | number | No |  | Bullet size |
| `align` | 'left' \| 'right' | No |  | Alignment of timeline |
| `reverseActive` | boolean | No |  | Reverse active highlighting |
| `size` | ComponentSizeValue | No |  | Component size |
| `centerMode` | boolean | No |  | Center mode renders a single central spine allowing items on both sides via itemAlign prop |

## Examples

### Project Milestones
ID: `Timeline.basic` • Tags: timeline • Category: basics • Status: stable • Since: 1.0.0

Use `Timeline.Item` components to communicate major project milestones alongside short descriptions.

```tsx
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',
  },
];
  return (
      <Timeline active={2}>
        {events.map((event) => (
          <Timeline.Item key={event.title} title={event.title}>
            <Text color="secondary" size="xs">
              {event.timestamp}
            </Text>
            <Text size="sm">{event.description}</Text>
          </Timeline.Item>
        ))}
      </Timeline>
  );
}
```

### Alignment Options
ID: `Timeline.alignment` • Tags: timeline, layout • Category: layout • Status: stable • Since: 1.0.0

Showcase left, right, and centered layouts by toggling `align` or `centerMode` on the timeline.

```tsx
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.' },
];
const signals = [
  { title: 'All Clear', description: 'No blockers detected.', align: 'left' as const, color: 'success.5' },
  { title: 'Caution', description: 'Risk detected for timeline.', align: 'right' as const, color: 'warning.5' },
  { title: 'Stop', description: 'Escalate critical issues before shipping.', align: 'left' as const, color: 'error.5' },
];
  return (
    <Block>
      <Text size="sm" color="secondary">
        Adjust alignment with the `align` prop or enable `centerMode` for timelines that alternate between sides.
      </Text>
      <Block>
        <Text weight="semibold">Left aligned (default)</Text>
        <Timeline>
          {phases.map((phase) => (
            <Timeline.Item key={`left-${phase.title}`} title={phase.title}>
              <Text size="sm">{phase.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
      <Block>
        <Text weight="semibold">Right aligned</Text>
        <Timeline align="right" active={1}>
          {phases.map((phase) => (
            <Timeline.Item key={`right-${phase.title}`} title={phase.title}>
              <Text size="sm">{phase.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
      <Block>
        <Text weight="semibold">Centered spine with per-item alignment</Text>
        <Timeline centerMode active={1}>
          {signals.map((signal) => (
            <Timeline.Item
              key={signal.title}
              title={signal.title}
              itemAlign={signal.align}
              color={signal.color}
            >
              <Text size="sm">{signal.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
    </Block>
  );
}
```

### Bullet Customization
ID: `Timeline.bullets` • Tags: timeline, customization • Category: appearance • Status: stable • Since: 1.0.0

Swap bullet content or adjust bullet sizing using the `bullet` and `bulletSize` props.

```tsx
const bulletContent = [
  {
    title: 'Default bullet',
    description: 'Uses the configured timeline size for spacing.',
  },
  {
    title: 'Numbered bullet',
    description: 'Render a custom label with the `bullet` prop.',
    bullet: <Text size="xs" weight="semibold">1</Text>,
  },
  {
    title: 'Completed bullet',
    description: 'Swap in an icon to reinforce status.',
    bullet: <Icon name="check" size={12} color="#0E8A16" />,
  },
  {
    title: 'Pending bullet',
    description: 'Show remaining work with a clock icon.',
    bullet: <Icon name="clock" size={12} color="#F59E0B" />,
  },
];
const bulletSizes = [
  { label: 'Compact bullet (18px)', bulletSize: 18 },
  { label: 'Large bullet (28px)', bulletSize: 28 },
];
  return (
    <Block>
      <Text size="sm" color="secondary">
        Override bullet content or scale it with the `bullet` and `bulletSize` props.
      </Text>
      <Block>
        <Text weight="semibold">Custom bullet content</Text>
        <Timeline bulletSize={22}>
          {bulletContent.map((item) => (
            <Timeline.Item key={item.title} title={item.title} bullet={item.bullet}>
              <Text size="sm">{item.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
      <Block>
        <Text weight="semibold">Adjust bullet size</Text>
        {bulletSizes.map((entry) => (
          <Timeline key={entry.label} bulletSize={entry.bulletSize}>
            <Timeline.Item title={entry.label}>
              <Text size="sm">Connector and spacing track with the bullet size.</Text>
            </Timeline.Item>
            <Timeline.Item title="Follow-up task">
              <Text size="sm">An additional item retains the same sizing.</Text>
            </Timeline.Item>
          </Timeline>
        ))}
      </Block>
    </Block>
  );
}
```

### Line Styling
ID: `Timeline.lineProps` • Tags: timeline, appearance • Category: appearance • Status: stable • Since: 1.0.0

Demonstrate how `color` and `lineWidth` affect the connector line.

```tsx
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.' },
];
  return (
    <Block>
      <Text size="sm" color="secondary">
        Customize the connector line globally with the `color` and `lineWidth` props on `Timeline`.
      </Text>
      <Block>
        <Text weight="semibold">Theme color</Text>
        <Timeline color="primary.6">
          {launches.map((milestone) => (
            <Timeline.Item key={`color-${milestone.title}`} title={milestone.title}>
              <Text size="sm">{milestone.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
      <Block>
        <Text weight="semibold">Thicker connector</Text>
        <Timeline lineWidth={4}>
          {launches.slice(0, 2).map((milestone) => (
            <Timeline.Item key={`width-${milestone.title}`} title={milestone.title}>
              <Text size="sm">{milestone.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
      <Block>
        <Text weight="semibold">Combined styling</Text>
        <Timeline color="success.6" lineWidth={3}>
          {launches.slice(1).map((milestone) => (
            <Timeline.Item key={`combined-${milestone.title}`} title={milestone.title}>
              <Text size="sm">{milestone.description}</Text>
            </Timeline.Item>
          ))}
        </Timeline>
      </Block>
    </Block>
  );
}
```

### Line Variants
ID: `Timeline.lineVariants` • Tags: timeline, appearance • Category: appearance • Status: stable • Since: 1.0.0

Compare solid, dashed, and dotted connectors, including mixed variants within a single flow.

```tsx
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 },
];
  return (
    <Block direction="row" justify="space-between" fullWidth>
      {variantExamples.map((example) => (
        <Block key={example.label}>
          <Text weight="semibold">{example.label}</Text>
          <Timeline>
            {phases.map((title) => (
              <Timeline.Item key={`${example.label}-${title}`} title={title} lineVariant={example.variant} />
            ))}
          </Timeline>
        </Block>
      ))}
      <Block>
        <Text weight="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://react-ui-library.com/llms/components/TimePicker.md -->

# TimePicker

Inline panel for selecting a time with hour/minute (and optional seconds) precision, rendered directly in the page rather than in a dialog — the time counterpart to `MonthPicker` and `YearPicker`. Supports 12-hour or 24-hour clocks, a meridiem column on 12-hour clocks, and custom step intervals for minutes and seconds. Works in controlled and uncontrolled modes.

For a form field that displays the selected time and opens this panel in a dialog, use [`TimePickerInput`](/components/TimePickerInput).

## Metadata

- Canonical name: `TimePicker`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { TimePicker } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: dates
- Docs: https://react-ui-library.com/components/TimePicker
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/TimePicker

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | TimePickerValue \| null | No |  |  |
| `defaultValue` | TimePickerValue \| null | No |  |  |
| `onChange` | (next: TimePickerValue) => void | No |  | Fired on every column selection. |
| `onChangeComplete` | (next: TimePickerValue) => void | No |  | 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 | No |  |  |
| `withSeconds` | boolean | No |  |  |
| `minuteStep` | number | No |  |  |
| `secondStep` | number | No |  |  |
| `columnWidth` | number | No |  | Width of each scroll column (hours/minutes/seconds). |
| `columnHeight` | number | No |  | Max height of each scroll column. |
| `disabled` | boolean | No |  |  |
| `style` | any | No |  |  |

## Examples

### Basic
ID: `TimePicker.basic` • Category: general

Basic controlled usage of the inline TimePicker panel with 24-hour format.

```tsx
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" color="secondary">{`Selected: ${formatted}`}</Text>
    </Block>
  );
}
```

### Format 12h
ID: `TimePicker.format-12h` • Category: general

Using 12-hour clock format with AM/PM toggle.

```tsx
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" color="secondary">
        {`Internal (24h): ${formatted}`}
      </Text>
    </Block>
  );
}
```

### With Seconds
ID: `TimePicker.with-seconds` • Category: general

Including seconds selection in the TimePicker panel.

```tsx
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" color="secondary">{`Selected: ${formatted}`}</Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/TimePickerInput.md -->

# TimePickerInput

Form field for selecting a time. Presents an input showing the formatted value and opens a [TimePicker](/components/TimePicker) panel in a dialog, mirroring the behavior of `DatePickerInput`, `MonthPickerInput` and `YearPickerInput`. Adds the field concerns the inline panel has no notion of — label, validation, clearing, and manual text entry — and supports the full `<Input>` slot-prop API.

## Metadata

- Canonical name: `TimePickerInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { TimePickerInput } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: dates
- Docs: https://react-ui-library.com/components/TimePickerInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/TimePickerInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | any | No |  | Size of the field itself; the panel columns are fixed-width. |
| `value` | TimePickerValue \| null | No |  |  |
| `defaultValue` | TimePickerValue \| null | No |  |  |
| `onChange` | (next: TimePickerValue \| null) => void | No |  | Emits `null` when the field is cleared, which the inline panel never does. |
| `allowInput` | boolean | No |  | Allow typing a time directly into the field. |
| `panelWidth` | number \| string | No |  | Width of the dialog holding the panel. |
| `inputWidth` | number \| string | No |  |  |
| `label` | string | No |  |  |
| `description` | string | No |  |  |
| `error` | string | No |  |  |
| `helperText` | string | No |  |  |
| `style` | any | No |  |  |
| `onOpen` | () => void | No |  |  |
| `onClose` | () => void | No |  |  |
| `title` | string | No |  |  |
| `autoClose` | boolean | No |  | Close the dialog as soon as the last column is picked, hiding the Done button. |
| `fullWidth` | boolean | No |  |  |
| `clearable` | boolean | No |  |  |
| `clearButtonLabel` | string | No |  |  |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>`. |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>`. |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | View props applied to the wrapper around startSection. |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | View props applied to the wrapper around endSection (the clock icon by default). |

## Examples

### Basic
ID: `TimePickerInput.basic` • Category: general

```tsx
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" color="secondary">
        {formatted ? `Selected: ${formatted}` : 'No time selected'}
      </Text>
    </Block>
  );
}
```

### Validation
ID: `TimePickerInput.validation` • Category: general

Validation example showing custom error when outside allowed business hours (09:00-17:00).

```tsx
const withinBusiness = (v: TimePickerValue) => {
  const totalMinutes = v.hours * 60 + v.minutes;
  return totalMinutes >= 9 * 60 && totalMinutes <= 17 * 60; // 09:00 - 17:00 inclusive
};
  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" color="secondary">
          Selected: {value.hours.toString().padStart(2, '0')}:{value.minutes.toString().padStart(2, '0')}
        </Text>
      )}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Title`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Title } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: typography
- Docs: https://react-ui-library.com/components/Title
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Title

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `text` | string | No |  | The text content to display in the title |
| `order` | 1 \| 2 \| 3 \| 4 \| 5 \| 6 | No |  | The heading level (1-6), determines the semantic importance and default styling |
| `underline` | boolean | No |  | Whether to show an underline decoration below the title |
| `afterline` | boolean | No |  | Whether to show a line after the title text |
| `underlineColor` | string | No |  | Color of the underline decoration |
| `underlineStroke` | number | No |  | Thickness/stroke width of the underline in pixels |
| `afterlineGap` | number | No |  | Gap between the title text and afterline in pixels |
| `underlineOffset` | number | No |  | Vertical offset of the underline from the text baseline in pixels |
| `prefix` | boolean \| React.ReactNode | No |  | Prefix decoration - can be a boolean to show default prefix or a custom React element |
| `prefixVariant` | 'bar' \| 'dot' | No |  | Style variant for the default prefix decoration |
| `prefixColor` | string | No |  | Color of the prefix decoration |
| `prefixSize` | number | No |  | Size of the prefix decoration in pixels |
| `prefixLength` | number | No |  | Length of the prefix decoration (for bar variant) in pixels |
| `prefixGap` | number | No |  | Gap between the prefix and title text in pixels |
| `prefixRadius` | number | No |  | Border radius of the prefix decoration in pixels |
| `style` | any | No |  | Additional styles to apply to the title text element |
| `variant` | TextProps['variant'] | No |  | Text variant to use, inherits from TextProps variant system |
| `containerStyle` | any | No |  | Additional styles to apply to the container wrapping the entire title |
| `startIcon` | React.ReactNode | No |  | Icon element to display on the left side of the title |
| `endIcon` | React.ReactNode | No |  | Icon element to display on the right side of the title |
| `action` | React.ReactNode | No |  | Action button or element positioned at the far right of the title |
| `subtitle` | React.ReactNode | No |  | Optional subtitle displayed below the title |
| `subtitleProps` | Partial<TextProps> | No |  | Additional Text props applied to the subtitle when rendered as Text |
| `subtitleSpacing` | number | No |  | Spacing between the title and subtitle in pixels (default: 8) |
| `children` | React.ReactNode | No |  | Text node children. Optional if using translation via `tx`. |
| `tx` | string | No |  | Translation key (if provided, overrides children when found) |
| `txParams` | Record<string, any> | No |  | Params for translation interpolation |
| `size` | SizeValue | No |  | Size can be a size token or number (overrides variant fontSize) |
| `color` | string | No |  | Text color. Accepts a `theme.text` role (`'primary'`, `'secondary'`, `'muted'`, `'disabled'`, `'link'`), `'dimmed'` for the muted token, a palette name (`'success'` → its readable shade), `'primary.6'` shade syntax, or any CSS color string. |
| `c` | string | No |  | Shorthand alias for `color`, resolved identically. `color` wins when both are set. |
| `weight` | 'normal' \| 'medium' \| 'semibold' \| 'bold' \| 'light' \| 'black' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' \| number | No |  | Font weight (supports all CSS font-weight values) |
| `align` | 'left' \| 'center' \| 'right' \| 'justify' | No |  | Text alignment |
| `lineHeight` | number | No |  | Line height as a multiplier (e.g., 1.5) or absolute value |
| `tracking` | number | No |  | Letter spacing (tracking) in pixels or em units |
| `uppercase` | boolean | No |  | Convert text to uppercase |
| `fontFamily` | string | No |  | Custom font family (overrides theme font) |
| `ff` | string | No |  | Shorthand alias for `fontFamily` |
| `as` | HTMLTextVariant | No |  | For platform-specific rendering on web |
| `selectable` | boolean | No |  | Whether text is selectable (default: true) |
| `onPress` | () => void | No |  | Called when text is pressed |
| `onLayout` | (event: any) => void | No |  | Called when the text layout is calculated |
| `value` | string \| number | No |  | Value to display (overrides children, useful for numbers) |
| `numberOfLines` | RNTextProps['numberOfLines'] | No |  | Maximum number of lines to display (native + web) |
| `ellipsizeMode` | RNTextProps['ellipsizeMode'] | No |  | Ellipsis strategy when text exceeds available space |
| `id` | string | No |  | Element id. On web this is the DOM `id` — headings need one to be a link target. |
| `nativeID` | string | No |  | React Native alias for `id`; used when the two platforms need different values. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Usage
ID: `Title.basic` • Tags: title, headings • Category: usage • Status: stable • Since: 1.0.0

Default Title usage shows the h2-style heading produced by the component without additional props.

```tsx
return (
    <Card p="md">
      <Block>
        <Title>Default section heading</Title>
        <Text size="sm" color="secondary">
          Titles default to order 2, making them a natural choice for section headings.
        </Text>
      </Block>
    </Card>
  );
}
```

### Heading Levels
ID: `Title.levels` • Tags: headings, semantics • Category: usage • Status: stable • Since: 1.0.0

Set the `order` prop to align Title with semantic heading levels from h1 through h6.

```tsx
return (
    <Card p="md">
      <Block>
        <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>
    </Card>
  );
}
```

### Prefix Styles
ID: `Title.prefix` • Tags: prefix, decoration • Category: theming • Status: stable • Since: 1.0.0

Enable the `prefix` prop to add visual markers, switching variants or supplying a custom icon for emphasis.

```tsx
return (
    <Card p="md">
      <Block>
        <Title prefix>Default bar prefix</Title>
        <Title prefix prefixVariant="dot">Dot prefix</Title>
        <Title prefix prefixVariant="bar" 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>
    </Card>
  );
}
```

### Underlines
ID: `Title.underline` • Tags: underline, afterline • Category: theming • Status: stable • Since: 1.0.0

Toggle `underline` and `afterline` to add emphasis and separation, including custom color and stroke weights.

```tsx
return (
    <Card p="md">
      <Block>
        <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>
    </Card>
  );
}
```

### Actions
ID: `Title.action` • Tags: actions, layout • Category: usage • Status: stable • Since: 1.0.0

Pass an `action` element to align buttons or toggles alongside the heading.

```tsx
return (
    <Card p="md">
      <Block>
        <Title action={<Button title="Action" size="sm" />}>Basic with action</Title>
        <Title underline action={<Button title="Edit" size="sm" variant="outline" />}>
          Underline with action
        </Title>
        <Title afterline action={<Button title="Settings" size="sm" variant="ghost" />}>
          Afterline with action
        </Title>
        <Title underline afterline action={<Button title="More" size="sm" />}>
          Full layout with action
        </Title>
      </Block>
    </Card>
  );
}
```

### Combined Accents
ID: `Title.combined` • Tags: prefix, underline, afterline • Category: theming • Status: stable • Since: 1.0.0

Mix prefix, underline, and afterline props to create a primary heading and aligned subsection titles with consistent accents.

```tsx
return (
    <Card p="md">
      <Block>
        <Title
          prefix
          underline
          afterline
          prefixVariant="bar"
          prefixSize={6}
          prefixLength={48}
          prefixColor="#10b981"
          underlineStroke={3}
        >
          Analytics overview
        </Title>
        <Text size="sm" color="secondary">
          Combine prefixes, underline, and afterline to create a structured page heading with a strong visual anchor.
        </Text>
        <Block>
          <Title
            order={3}
            prefix
            prefixVariant="dot"
            prefixColor="#ef4444"
            underline
            underlineColor="#ef4444"
            underlineStroke={2}
          >
            Active users
          </Title>
          <Title
            order={3}
            prefix
            prefixVariant="dot"
            prefixColor="#6366f1"
            underline
            underlineColor="#6366f1"
            underlineStroke={2}
          >
            Conversion rate
          </Title>
        </Block>
      </Block>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Toast.md -->

# Toast

The Toast component provides non-blocking notification messages that appear temporarily to give feedback about an operation or event. Title and body each accept full `<Text>` props via `titleProps` / `bodyProps` — also forwarded by every `useToast()` shortcut.

## Metadata

- Canonical name: `Toast`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Toast } from '@platform-blocks/react-ui-library';`
- Category: feedback
- Tags: toast, notification, alert, message, feedback
- Docs: https://react-ui-library.com/components/Toast
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Toast

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `variant` | ToastVariant | No | 'light' | Toast variant |
| `size` | ComponentSizeValue | No | '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 | No | 'gray' | Toast color - can be theme color or custom color string |
| `severity` | ToastSeverity | No |  | 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 | No |  | Toast title |
| `children` | React.ReactNode | No |  | Toast content |
| `icon` | React.ReactNode | No |  | Icon to display |
| `withCloseButton` | boolean | No | true | Whether to show close button |
| `loading` | boolean | No | false | Whether to show loading indicator |
| `closeButtonLabel` | string | No | 'Close notification' | Close button accessibility label |
| `onClose` | () => void | No |  | Callback when close button is pressed |
| `onExited` | () => void | No |  | 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 | No | false | Whether the toast is visible |
| `animationDuration` | number | No | 300 | Animation duration in ms |
| `transitionDuration` | number | No | 300 | Show/hide transition length in ms. Cross-component spelling that takes precedence over `animationDuration`; `0` shows and hides with no animation. |
| `autoHide` | number | No | 4000 | Auto hide duration in ms (0 to disable) |
| `paused` | boolean | No | 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` | ToastPosition | No | 'top' | Position of the toast for animation direction |
| `style` | StyleProp<ViewStyle> | No |  | Container style |
| `testID` | string | No |  | Test ID for testing |
| `actions` | ToastAction[] | No |  | Action buttons |
| `dismissOnTap` | boolean | No | false | Whether toast can be dismissed by tapping |
| `maxWidth` | number | No |  | Maximum width for toast |
| `persistent` | boolean | No | false | Persist toast until manually dismissed |
| `keepMounted` | boolean | No | true | Keep toast mounted in the tree when hidden |
| `animationConfig` | ToastAnimationConfig | No |  | Animation configuration |
| `swipeConfig` | ToastSwipeConfig | No |  | Swipe to dismiss configuration |
| `onSwipeDismiss` | () => void | No |  | Callback when toast is dismissed via swipe |
| `selectable` | boolean | No | 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'> | No |  | Override props applied to the title `<Text>` (style, weight, ff, size, color). |
| `bodyProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the body `<Text>` (the `children` content). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic Usage
ID: `Toast.basic` • Tags: toast, notifications • Category: basics • Status: stable • Since: 1.0.0

Call `toast.success` with a title, message, and optional `autoHide` value to show a standard confirmation toast.

```tsx
const toast = useToast();
  const handlePress = () => {
    toast.success({
      title: 'Success!',
      message: 'The operation finished without issues.',
      autoHide: 4000,
    });
  };
  return <Button onPress={handlePress}>Show success toast</Button>;
}
```

### Positions
ID: `Toast.positions` • Tags: toast, layout, placement • Category: layout • Status: stable • Since: 1.0.0

Set the `position` option to anchor the toast stack to any corner or edge of the viewport.

```tsx
const toastPositions = [
  'top-left',
  'top-center', 
  'top-right',
  'bottom-left',
  'bottom-center',
  'bottom-right',
] as const;
  const toast = useToast();
  const showToastAtPosition = (position: typeof toastPositions[number]) => {
    toast.show({
      title: `Toast at ${position}`,
      message: `This toast appears at ${position} position.`,
      position,
    });
  };
  return (
    <Block>
      <Text size="xs" color="secondary">
        Pass `position` to align the toast container with your layout.
      </Text>
      <Row gap="xs" wrap="wrap">
        {toastPositions.map((position) => (
          <Button key={position} size="sm" onPress={() => showToastAtPosition(position)}>
            {position}
          </Button>
        ))}
      </Row>
    </Block>
  );
}
```

### Visual Variants
ID: `Toast.visual-variants` • Tags: toast, variant, styling, filled, outline, light • Category: theming • Status: stable • Since: 1.0.0

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
const VARIANTS = ['light', 'filled', 'outline'] as const;
type ToastVariant = (typeof VARIANTS)[number];
const COPY: Record<ToastVariant, string> = {
  light: 'Subtle surface with a colored left accent.',
  filled: 'Solid fill with auto-contrast text.',
  outline: 'Surface with a full colored border.',
};
  const toast = useToast();
  return (
    <Block gap="md">
      <Text size="xs" color="secondary">
        The `variant` prop controls the toast surface. Each preview below pairs
        the variant with the `success` severity — swap `severity` or `color` to
        recolor any of them.
      </Text>
      {VARIANTS.map((variant) => (
        <Block key={variant} gap="xs">
          <Text variant="small" color="secondary">
            {variant}
          </Text>
          <Toast
            visible
            persistent
            autoHide={0}
            variant={variant}
            severity="success"
            title="Changes saved"
            icon={<Icon name="success" variant="filled" />}
            withCloseButton={false}
          >
            {COPY[variant]}
          </Toast>
        </Block>
      ))}
      <Row gap="xs" wrap="wrap">
        {VARIANTS.map((variant) => (
          <Button
            key={variant}
            variant={variant === 'filled' ? 'filled' : 'outline'}
            onPress={() =>
              toast.success({
                variant,
                title: `${variant} toast`,
                message: COPY[variant],
              })
            }
          >
            Show {variant}
          </Button>
        ))}
      </Row>
    </Block>
  );
}
```

### Size Tokens
ID: `Toast.sizes` • Tags: toast, size, sizing, tokens • Category: appearance • Status: stable • Since: 1.0.0

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
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  const toast = useToast();
  return (
    <Block gap="md">
      <Text size="xs" color="secondary">
        `size` accepts all seven component tokens. Padding, title and body type,
        the leading icon, and the close button all scale together — pass a
        number instead of a token to scale from a custom title size. The
        previews are static; the buttons below fire real toasts at each size.
      </Text>
      {SIZES.map((size) => (
        <Block key={size} gap="xs">
          <Text variant="small" color="secondary">
            {size}
          </Text>
          <Toast
            visible
            persistent
            autoHide={0}
            size={size}
            variant="light"
            severity="info"
            title="Sync complete"
            icon={<Icon name="info" variant="filled" />}
            withCloseButton={false}
          >
            Everything is up to date.
          </Toast>
        </Block>
      ))}
      <Row gap="xs" wrap="wrap">
        {SIZES.map((size) => (
          <Button
            key={size}
            size="sm"
            variant="outline"
            onPress={() =>
              toast.info({
                size,
                title: `Size ${size}`,
                message: 'Toasts keep their proportions at every token.',
              })
            }
          >
            {size}
          </Button>
        ))}
      </Row>
    </Block>
  );
}
```

### Severity Helpers
ID: `Toast.variants` • Tags: toast, severity, styling • Category: theming • Status: stable • Since: 1.0.0

Use `toast.success`, `toast.warning`, `toast.error`, and `toast.info` to render consistent styling and icons for each severity.

```tsx
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 (
    <Block>
      <Text size="xs" color="secondary">
        Use the severity helpers to render consistent styling for each toast type.
      </Text>
      <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>
    </Block>
  );
}
```

### Interactive Features
ID: `Toast.interactive` • Tags: toast, actions, persistence • Category: behavior • Status: stable • Since: 1.0.0

Add `actions`, toggle `persistent`, or shorten `autoHide` to tailor toast interactions for acknowledgements, warnings, and ephemeral notices.

```tsx
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 = () => {
    let toastId = '';
    toastId = toast.show({
      title: 'Important notice',
      message: 'This toast stays visible until dismissed.',
      persistent: true,
      actions: [
        {
          label: 'Dismiss',
          onPress: () => toast.hide(toastId),
        },
      ],
    });
  };
  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
ID: `Toast.stacking` • Tags: toast, stack, queue, limit • Category: behavior • Status: stable • Since: 1.1.0

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
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>
      <Button variant="outline" onPress={() => toast.hideAll()}>
        Dismiss all
      </Button>
      <Text size="xs" color="secondary">
        Hover the stack to hold every toast open.
      </Text>
    </Block>
  );
}
```

### Enhanced Features
ID: `Toast.enhanced` • Tags: toast, animations, batching • Category: advanced • Status: stable • Since: 1.0.0

Combine swipe gestures, custom `animationConfig`, batch helpers, and `toast.promise` to coordinate rich toast experiences.

```tsx
const toast = useToast();
  const [loading, setLoading] = useState(false);
  const showSwipeableToast = () => {
    toast.info({
      title: 'Swipe me!',
      message: 'Drag horizontally to dismiss this toast.',
      swipeConfig: {
        enabled: true,
        threshold: 150,
        direction: 'horizontal',
      },
      onSwipeDismiss: () => {
        console.log('Toast dismissed via swipe');
      },
      persistent: true,
    });
  };
  const showAnimatedToast = () => {
    toast.success({
      title: 'Spring motion',
      message: 'Bounce animation with custom spring physics.',
      animationConfig: {
        type: 'bounce',
        springConfig: {
          damping: 10,
          stiffness: 100,
        },
      },
    });
  };
  const showScaleToast = () => {
    toast.warning({
      title: 'Scale in',
      message: 'Combines scale animation with bidirectional swipe.',
      animationConfig: {
        type: 'scale',
        duration: 500,
      },
      swipeConfig: {
        enabled: true,
        direction: 'both',
      },
    });
  };
  const showToastWithActions = () => {
    toast.info({
      title: 'Actions',
      message: 'Toasts can render multiple CTA buttons.',
      actions: [
        {
          label: 'Retry',
          onPress: () => toast.success('Retrying…'),
        },
        {
          label: 'Cancel',
          onPress: () => toast.error('Cancelled'),
        },
      ],
      persistent: true,
    });
  };
  const showBatchToasts = () => {
    toast.batch([
      {
        title: 'Batch 1',
        message: 'First toast in batch',
        severity: 'info',
        groupId: 'batch-demo',
      },
      {
        title: 'Batch 2',
        message: 'Second toast in batch',
        severity: 'success',
        groupId: 'batch-demo',
      },
      {
        title: 'Batch 3',
        message: 'Third toast in batch',
        severity: 'warning',
        groupId: 'batch-demo',
      },
    ]);
  };
  const hideBatchToasts = () => {
    toast.hideGroup('batch-demo');
  };
  const showPromiseToast = async () => {
    setLoading(true);
    const mockApiCall = () =>
      new Promise<string>((resolve, reject) => {
        setTimeout(() => {
          if (Math.random() > 0.5) {
            resolve('Success!');
          } else {
            reject('Failed!');
          }
        }, 2000);
      });
    try {
      await toast.promise(mockApiCall(), {
        pending: 'Loading data…',
        success: (data) => `Operation completed: ${data}`,
        error: (error) => `Operation failed: ${error.message}`,
      });
    } finally {
      setLoading(false);
    }
  };
  return (
    <Block>
      <Button onPress={showSwipeableToast}>Swipe to dismiss</Button>
      <Button variant="outline" onPress={showAnimatedToast}>
        Bounce animation
      </Button>
      <Button variant="outline" onPress={showScaleToast}>
        Scale animation + swipe
      </Button>
      <Button variant="outline" onPress={showToastWithActions}>
        Toast with actions
      </Button>
      <Button variant="outline" onPress={showBatchToasts}>
        Show batch toasts
      </Button>
      <Button variant="outline" onPress={hideBatchToasts}>
        Hide batch toasts
      </Button>
      <Button variant="outline" loading={loading} onPress={showPromiseToast}>
        Promise integration
      </Button>
      <Block>
        <Text size="xs" color="secondary">
          Tap-to-dismiss example:
        </Text>
        <Toast
          visible
          title="Tap me!"
          severity="info"
          dismissOnTap
          onClose={() => console.log('Tapped!')}
          position="bottom"
        >
          This toast can be dismissed by tapping.
        </Toast>
      </Block>
    </Block>
  );
}
```

### Text customization
ID: `Toast.text-customization` • Tags: titleProps, bodyProps, customization, slot-props • Category: general • Status: stable • Since: 1.0.0

`titleProps` and `bodyProps` accept any `<Text>` props (`ff`, `weight`, `size`, `color`, `style`…) and apply them to the toast title and body slots. Useful for matching toast typography to your brand.

```tsx
const toast = useToast();
  return (
    <Block>
      <Button
        onPress={() => {
          toast.show({
            title: 'Default styling',
            message: 'No custom title or body props.',
            severity: 'info',
            autoHide: 4000,
          });
        }}
      >
        Default toast
      </Button>
      <Button
        onPress={() => {
          toast.show({
            title: 'Bold uppercase title',
            message: 'Title rendered with monospace + tracking.',
            severity: 'success',
            autoHide: 4000,
            titleProps: {
              ff: 'monospace',
              weight: '700',
              uppercase: true,
              tracking: 1,
              size: 'sm',
            },
            bodyProps: { size: 'sm' },
          });
        }}
      >
        Tracked uppercase title
      </Button>
      <Button
        onPress={() => {
          toast.show({
            title: 'Brand serif title',
            message: 'Title in Georgia, body in default font.',
            severity: 'warning',
            autoHide: 4000,
            titleProps: { ff: 'Georgia, serif', size: 'lg' },
          });
        }}
      >
        Custom font on title
      </Button>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Toggle`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Toggle } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: input
- Docs: https://react-ui-library.com/components/Toggle
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Toggle

## Props

_No documented props yet._

## Examples

### Basic Group
ID: `Toggle.basic` • Tags: toggle, alignment • Category: basics • Status: stable • Since: 1.0.0

Render a simple `ToggleGroup` and listen for `onChange` to track the active value.

```tsx
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" color="secondary">
        Selected alignment: {alignment}
      </Text>
    </Block>
  );
}
```

### Exclusive Mode
ID: `Toggle.exclusive` • Tags: toggle, exclusive • Category: behavior • Status: stable • Since: 1.0.0

Enable the `exclusive` prop so the group behaves like radio buttons with a single active value.

```tsx
const [alignment, setAlignment] = useState('center');
  const handleChange = (value: string | number | (string | number)[]) => {
    // For exclusive mode, value should be a single string or number
    if (typeof value === 'string' || typeof value === 'number') {
      setAlignment(String(value));
    }
  };
  return (
    <Block>
      <Block>
        <Text weight="semibold">Exclusive selection</Text>
        <Text size="xs" color="secondary">
          Set `exclusive` to enforce a single active value at a time.
        </Text>
      </Block>
      <ToggleGroup value={alignment} exclusive onChange={handleChange}>
        <ToggleButton value="left">Left</ToggleButton>
        <ToggleButton value="center">Center</ToggleButton>
        <ToggleButton value="right">Right</ToggleButton>
        <ToggleButton value="justify">Justify</ToggleButton>
      </ToggleGroup>
      <Text size="xs" color="secondary">
        Active option: {alignment}
      </Text>
    </Block>
  );
}
```

### Multiple Values
ID: `Toggle.multiple` • Tags: toggle, multi-select • Category: behavior • Status: stable • Since: 1.0.0

Read the array returned by `onChange` to keep several toggles activated together.

```tsx
const [formats, setFormats] = useState(['bold']);
  const handleChange = (value: string | number | (string | number)[]) => {
    if (Array.isArray(value)) {
      setFormats(value.map(String));
    }
  };
  return (
    <Block>
      <Block>
        <Text weight="semibold">Multiple selection</Text>
        <Text size="xs" color="secondary">
          The default mode returns an array of selected values.
        </Text>
      </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" color="secondary">
        Active formatting: {formats.length > 0 ? formats.join(', ') : 'none'}
      </Text>
    </Block>
  );
}
```

### Orientation
ID: `Toggle.orientation` • Tags: toggle, orientation • Category: layout • Status: stable • Since: 1.0.0

Use the `orientation` prop to switch between horizontal rows and vertical stacks of toggle buttons.

```tsx
const [view, setView] = useState('list');
  const handleChange = (value: string | number | (string | number)[]) => {
    if (typeof value === 'string') {
      setView(value);
    }
  };
  return (
    <Block>
      <Block>
        <Text weight="semibold">Toggle orientations</Text>
        <Text size="xs" color="secondary">
          Swap the `orientation` prop to lay buttons out horizontally or vertically.
        </Text>
      </Block>
      <Row gap="lg" align="flex-start" wrap="wrap">
        <Block>
          <Text size="sm" weight="semibold">
            Horizontal (default)
          </Text>
          <ToggleGroup value={view} exclusive onChange={handleChange} orientation="horizontal">
            <ToggleButton value="list">List</ToggleButton>
            <ToggleButton value="grid">Grid</ToggleButton>
            <ToggleButton value="card">Card</ToggleButton>
          </ToggleGroup>
        </Block>
        <Block>
          <Text size="sm" weight="semibold">
            Vertical
          </Text>
          <ToggleGroup value={view} exclusive onChange={handleChange} orientation="vertical">
            <ToggleButton value="list">List</ToggleButton>
            <ToggleButton value="grid">Grid</ToggleButton>
            <ToggleButton value="card">Card</ToggleButton>
          </ToggleGroup>
        </Block>
      </Row>
      <Text size="xs" color="secondary">
        Selected view: {view}
      </Text>
    </Block>
  );
}
```

### Size Variants
ID: `Toggle.sizes` • Tags: toggle, size • Category: appearance • Status: stable • Since: 1.0.0

Set the `size` prop (`xs` through `3xl`) to match the footprint of surrounding controls.

```tsx
const SIZES = ['xs', 'sm', 'md', 'lg', 'xl', '2xl', '3xl'] as const;
  return (
    <Block>
      {SIZES.map((size) => (
        <Block key={size}>
          <Text variant="small" color="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
ID: `Toggle.standalone` • Tags: toggle, standalone • Category: basics • Status: stable • Since: 1.0.0

Drive a single toggle by managing its `selected` state without a surrounding group.

```tsx
const [selected, setSelected] = useState(false);
  return (
    <Block>
      <Block>
        <Text weight="semibold">Standalone toggle</Text>
        <Text size="xs" color="secondary">
          Control an individual toggle by pairing `selected` with `onPress`.
        </Text>
      </Block>
      <Row gap="sm" align="center">
        <ToggleButton
          value="favorite"
          selected={selected}
          onPress={() => setSelected((current) => !current)}
        >
          Mark favorite
        </ToggleButton>
        <Text size="xs" color="secondary">
          Status: {selected ? 'Favorited' : 'Not favorited'}
        </Text>
      </Row>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `Tooltip`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Tooltip } from '@platform-blocks/react-ui-library';`
- Status: stable
- Category: overlay
- Docs: https://react-ui-library.com/components/Tooltip
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Tooltip

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `label` | React.ReactNode | Yes |  | Tooltip label |
| `position` | TooltipPositionType | No | 'top' | Position of the tooltip |
| `withArrow` | boolean | No | false | Whether to show an arrow |
| `color` | string | No |  | Tooltip color |
| `radius` | SizeValue | No | 'md' | Border radius |
| `offset` | number | No | 8 | Offset from target |
| `width` | number | No |  | Fixed bubble width. Omit to size to content (capped by `maxWidth`). |
| `maxWidth` | number | No | 280 | Largest width the bubble may grow to before the label wraps. Also clamped by the available viewport space. |
| `lineClamp` | number | No |  | Clamp the label to N lines with an ellipsis. Unset = wrap freely. |
| `opened` | boolean | No |  | Whether tooltip is controlled |
| `openDelay` | number | No | 0 | Open delay in ms |
| `closeDelay` | number | No | 0 | Close delay in ms |
| `events` | { hover?: boolean; focus?: boolean; touch?: boolean; } | No |  | Events that trigger tooltip |
| `children` | React.ReactElement | Yes |  | Children element to attach tooltip to |
| `style` | StyleProp<ViewStyle> | No |  | Container style |
| `testID` | string | No |  | Test ID for testing |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the label `<Text>` (style, weight, ff, size, color). |

## Examples

### Advanced
ID: `Tooltip.advanced` • Category: general

title: Advanced Tooltip Features description: Advanced tooltip options including delays, wrapped labels, width control, and the object form of the tooltip prop. tags: ["advanced", "delays", "wrapping", "maxWidth", "controlled", "custom-color", "width"] --- title: Delays and Content category: behavior order: 40 tags: [delays, wrapping] highlightLines: [11-44] status: stable since: 1.0.0 hidden: false --- Tune `openDelay`/`closeDelay` to reduce flicker. Long labels wrap on their own — use `maxWidth` to move the wrap point, `width` for a fixed bubble, or `lineClamp` to truncate on purpose.

```tsx
return (
    <Card p="md">
      <Block>
        <Block>
          <Text size="sm" color="secondary">
            Add open and close delays to avoid flicker when the pointer briefly leaves the trigger.
          </Text>
          <Tooltip label="Opens after 400ms" openDelay={400} closeDelay={200}>
            <Button size="sm" variant="outline">
              Delayed tooltip
            </Button>
          </Tooltip>
        </Block>
        <Block>
          <Text size="sm" color="secondary">
            Long labels wrap automatically. Tighten or widen the wrap point with `maxWidth`.
          </Text>
          <Tooltip
            label="This tooltip wraps across multiple lines so you can surface longer instructions without truncation."
            maxWidth={220}
            withArrow
          >
            <Button size="sm">
              Wrapped tooltip
            </Button>
          </Tooltip>
        </Block>
        <Block>
          <Text size="sm" color="secondary">
            Components with a `tooltip` prop take a string, or an object to pass any Tooltip option.
          </Text>
          <Button
            size="sm"
            variant="outline"
            tooltip={{
              label: 'The object form forwards straight to Tooltip, so you can widen the bubble or add an arrow.',
              maxWidth: 320,
              position: 'right',
              withArrow: true
            }}
          >
            Tooltip via prop
          </Button>
        </Block>
      </Block>
    </Card>
  );
}
```

### Basic
ID: `Tooltip.basic` • Category: general

title: Basic Tooltip description: Simple tooltip display on hover/press with different trigger events. tags: ["basic", "events", "hover", "focus", "touch", "triggers"] --- title: Basic Usage category: usage order: 10 tags: [tooltip] highlightLines: [9-15] status: stable since: 1.0.0 hidden: false --- Wrap a control in `Tooltip` to display concise helper text on hover, focus, or touch.

```tsx
return (
    <Card p="md">
      <Block align="flex-start">
        <Text size="sm" color="secondary">
          Wrap interactive elements with `Tooltip` to introduce short helper text.
        </Text>
        <Tooltip label="Invite teammates" withArrow>
          <Button size="sm" variant="outline">
            Invite teammates
          </Button>
        </Tooltip>
      </Block>
    </Card>
  );
}
```

### Positions
ID: `Tooltip.positions` • Category: general

title: Tooltip Positions description: Different positioning options for tooltips with smart edge detection and arrow indicators. tags: ["positions", "positioning", "arrows", "edge-detection", "alignment"] --- title: Positions category: behavior order: 30 tags: [positioning] highlightLines: [12-31] status: stable since: 1.0.0 hidden: false --- Set `position` to top, bottom, left, or right to anchor the tooltip relative to its trigger.

```tsx
return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Pass a `position` value to choose where the tooltip appears.
        </Text>
        <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>
      </Block>
    </Card>
  );
}
```

### Simple
ID: `Tooltip.simple` • Category: general

title: Simple Tooltip description: Basic tooltip demonstration with different positions, arrows, and multiline text. tags: ["simple", "basic", "positions", "arrow", "multiline"] --- title: Trigger Modes category: behavior order: 20 tags: [events, interaction] highlightLines: [13-33] status: stable since: 1.0.0 hidden: false --- Configure the `events` prop to decide whether tooltips appear on hover, focus, or touch interactions.

```tsx
return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Adjust the `events` prop to control which interactions display the tooltip.
        </Text>
        <Block>
          <Row gap="sm" align="center">
            <Tooltip label="Default hover and focus behavior">
              <Button size="sm">Hover or focus</Button>
            </Tooltip>
          </Row>
          <Row gap="sm" align="center">
            <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>
          </Row>
          <Row gap="sm" align="center">
            <Tooltip
              label="Shows on touch interactions"
              events={{ hover: false, focus: false, touch: true }}
            >
              <Button size="sm" variant="ghost">
                Touch only
              </Button>
            </Tooltip>
          </Row>
        </Block>
      </Block>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Tree.md -->

# Tree

Tree component for displaying hierarchical data structures like file systems, navigation menus, or any nested content.

## Metadata

- Canonical name: `Tree`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Tree } from '@platform-blocks/react-ui-library';`
- Since: 1.0.0
- Category: navigation
- Docs: https://react-ui-library.com/components/Tree
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Tree

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | TreeNode<T>[] | Yes |  |  |
| `onNavigate` | (node: TreeNode<T>) => void | No |  | Called when a leaf is activated, or when any node carrying `href` is pressed |
| `onNodePress` | (node: TreeNode<T>, context: { isBranch: boolean; event?: any }) => boolean \| void | No |  | Called when a node row is pressed. Return false to prevent default handling (selection, expand). |
| `collapsible` | boolean | No |  | Allow collapsing/expanding |
| `disclosure` | TreeDisclosure | No | '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 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 | No |  | Row density. Drives height, padding, indent and icon size. |
| `indent` | number | No |  | Indent size in px for each depth level. Defaults to the `size` scale. |
| `showGuides` | boolean | No |  | Draw vertical guide lines connecting a branch to its descendants |
| `accordion` | boolean | No |  | Keep only one branch open per parent level |
| `expandAll` | boolean | No |  | Expand every branch. Reactive: flipping it back restores the initial expansion. |
| `renderLabel` | ( node: TreeNode<T>, depth: number, isOpen: boolean, state: TreeNodeState ) => React.ReactNode | No |  | Custom render for label |
| `renderEndSection` | (node: TreeNode<T>, state: TreeNodeState) => React.ReactNode | No |  | Trailing slot rendered at the end of a row (actions, counts, badges) |
| `style` | StyleProp<ViewStyle> | No |  |  |
| `rowStyle` | StyleProp<ViewStyle> | No |  | Style applied to every row container |
| `selectionMode` | 'none' \| 'single' \| 'multiple' | No |  | Selection mode |
| `selectedIds` | string[] | No |  | Controlled selected ids |
| `defaultSelectedIds` | string[] | No |  | Uncontrolled default selected ids |
| `onSelectionChange` | (ids: string[], node: TreeNode<T>) => void | No |  | Selection change callback |
| `onActiveNodeChange` | (node: TreeNode<T> \| null, ids: string[]) => void | No |  | Fired after selection changes with the node considered primary (first in selection) |
| `checkboxes` | boolean | No |  | Enable checkboxes |
| `checkedIds` | string[] | No |  | Controlled checked ids |
| `defaultCheckedIds` | string[] | No |  | Uncontrolled default checked ids |
| `onCheckedChange` | (ids: string[], node: TreeNode<T>) => void | No |  | Checked change callback |
| `cascadeCheck` | boolean | No |  | Cascade checking to descendants |
| `expandOnClick` | boolean | No |  | Expand branches also when pressing label area (not just chevron) |
| `expandedIds` | string[] | No |  | Controlled external expansion state |
| `defaultExpandedIds` | string[] | No |  | Uncontrolled initial expansion, overriding each node's `startOpen` |
| `onExpandedIdsChange` | (ids: string[]) => void | No |  | Fired with the full expanded set whenever expansion changes |
| `onToggle` | (node: TreeNode<T>, expanded: boolean) => void | No |  | Expansion change callback for a single node |
| `loadChildren` | (node: TreeNode<T>) => Promise<TreeNode<T>[]> | No |  | Fetch a branch's children on first expand. Node needs `hasChildren` to show a caret. |
| `filterQuery` | string | No |  | Filter query to highlight / hide unmatched nodes |
| `hideFiltered` | boolean | No |  | If true, nodes that don't match filter are hidden; otherwise all shown with highlight |
| `autoExpandOnFilter` | boolean | No |  | Open the branches leading to filter matches while a query is active |
| `noResultsFallback` | React.ReactNode | No |  | Content when no results after filtering |
| `highlight` | (label: string, query: string) => React.ReactNode | No |  | Custom highlight function for labels (return ReactNode) |
| `striped` | boolean | No |  | Apply alternating background stripes to rows |
| `useAnimations` | boolean | No |  | Animate branch expansion/collapse using the Collapse component |
| `virtualized` | boolean | No |  | Render rows through a virtualized list. Disables expand/collapse animation. |
| `height` | number | No |  | Viewport height for the virtualized list |
| `keyboardNavigation` | boolean | No |  | Arrow-key navigation, type-ahead and roving focus (web). Defaults to on. |
| `activeId` | string | No |  | 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`. |
| `activeHref` | string | No |  | `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 | No | 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 | No | true | Scroll the active row into view once it becomes visible (web only). |
| `persistKey` | string | No |  | 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 | No |  | Base color for selection / focus affordances. Defaults to the primary palette. |
| `accessibilityLabel` | string | No |  | Accessible name for the tree container |

## Examples

### Basic Tree
ID: `Tree.basic` • Tags: tree, navigation • Category: basics • Status: stable • Since: 1.0.0

Render a hierarchical dataset with collapsing branches. Use `indent` to control how far each level is inset.

```tsx
return <Tree data={TREE_DATA} collapsible indent={20} />;
}
```

### Tree with Checkboxes
ID: `Tree.checkboxes` • Tags: tree, checkboxes • Category: behavior • Status: stable • Since: 1.0.0

Enable `checkboxes` with `cascadeCheck` to keep parent and child nodes synchronized while tracking checked ids.

```tsx
const [checkedIds, setCheckedIds] = useState<string[]>(['react', 'css']);
  return (
    <Tree
      data={TREE_DATA}
      checkboxes
      cascadeCheck
      checkedIds={checkedIds}
      onCheckedChange={setCheckedIds}
      expandAll
    />
  );
}
```

### Tree Selection
ID: `Tree.selection` • Tags: tree, selection • Category: behavior • Status: stable • Since: 1.0.0

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
const [selectedIds, setSelectedIds] = useState<string[]>([]);
  return (
    <Block fullWidth>
      <Tree
        data={TREE_DATA}
        selectionMode="multiple"
        selectedIds={selectedIds}
        onSelectionChange={setSelectedIds}
        expandAll
      />
      <Text size="xs" color="secondary">
        {selectedIds.length === 0
          ? 'Click a row, shift-click for a range, or Cmd/Ctrl-click to toggle.'
          : `${selectedIds.length} selected`}
      </Text>
    </Block>
  );
}
```

### Tree Filtering
ID: `Tree.filtering` • Tags: tree, filtering • Category: behavior • Status: stable • Since: 1.0.0

Provide `filterQuery` with `hideFiltered` to search the tree. A `highlight` renderer and `noResultsFallback` are also available for custom match styling and empty states.

```tsx
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>
  );
}
```

### Lazy Loading
ID: `Tree.lazy` • Tags: tree, async, loading • Category: behavior • Status: stable • Since: 1.0.0

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
const loadChildren = (node: TreeNode) =>
    node.id.includes('-web') ? fetchVolumes(node.id) : fetchInstances(node.id);
  return <Tree data={TREE_DATA} loadChildren={loadChildren} selectionMode="single" showGuides />;
}
```

### Custom Tree Rendering
ID: `Tree.custom` • Tags: tree, custom-render • Category: customization • Status: stable • Since: 1.0.0

Pass `renderLabel` to build custom rows with icons and badges while keeping the tree interactions intact.

```tsx
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" color={status.color}>
          {status.label}
        </Badge>
      </Row>
    );
  };
  return <Tree data={TREE_DATA} renderLabel={renderCustomLabel} selectionMode="single" expandAll />;
}
```

### Virtualized Tree
ID: `Tree.virtualized` • Tags: tree, performance, virtualization • Category: performance • Status: stable • Since: 1.0.0

Pass `virtualized` with a `height` 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
return <Tree data={TREE_DATA} virtualized height={320} size="sm" striped showGuides />;
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Video.md -->

# Video

A comprehensive video player component that supports YouTube videos, MP4 files, and file buffers with advanced timeline synchronization capabilities.

## Metadata

- Canonical name: `Video`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Video } from '@platform-blocks/react-ui-library';`
- Since: 1.0.0
- Category: media
- Docs: https://react-ui-library.com/components/Video
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Video

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `source` | VideoSource | Yes |  | Video source configuration |
| `w` | number \| string | No |  | Display and sizing |
| `h` | number \| string | No |  |  |
| `aspectRatio` | number | No |  |  |
| `poster` | string | No |  |  |
| `autoPlay` | boolean | No |  | Playback configuration |
| `loop` | boolean | No |  |  |
| `muted` | boolean | No |  |  |
| `volume` | number | No |  |  |
| `playbackRate` | VideoPlaybackRate | No |  |  |
| `quality` | VideoQuality | No |  |  |
| `controls` | boolean \| VideoControls | No |  | Controls configuration |
| `timeline` | VideoTimelineEvent[] | No |  | Timeline events for synchronization |
| `youtubeOptions` | { start?: number; end?: number; modestbranding?: boolean; rel?: boolean; iv_load_policy?: number; } | No |  | YouTube specific options |
| `onPlay` | (state: VideoState) => void | No |  | Event handlers |
| `onPause` | (state: VideoState) => void | No |  |  |
| `onSeek` | (time: number, state: VideoState) => void | No |  |  |
| `onTimeUpdate` | (state: VideoState) => void | No |  |  |
| `onDurationChange` | (duration: number) => void | No |  |  |
| `onVolumeChange` | (volume: number) => void | No |  |  |
| `onPlaybackRateChange` | (rate: VideoPlaybackRate) => void | No |  |  |
| `onQualityChange` | (quality: VideoQuality) => void | No |  |  |
| `onFullscreenChange` | (fullscreen: boolean) => void | No |  |  |
| `onError` | (error: string) => void | No |  |  |
| `onLoad` | (state: VideoState) => void | No |  |  |
| `onLoadStart` | () => void | No |  |  |
| `onBuffer` | (buffering: boolean) => void | No |  |  |
| `onTimelineEvent` | (event: VideoTimelineEvent, state: VideoState) => void | No |  |  |
| `style` | StyleProp<ViewStyle> | No |  | Styling |
| `videoStyle` | StyleProp<ImageStyle> | No |  |  |
| `controlsStyle` | StyleProp<ViewStyle> | No |  |  |
| `accessibilityLabel` | string | No |  | Accessibility |
| `testID` | string | No |  |  |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic Playback
ID: `Video.basic` • Tags: video, playback, controls • Category: basics • Status: stable • Since: 1.0.0

Render `Video` with a local source, default transport controls, and custom buttons wired to the imperative ref for play, pause, and seeking.

```tsx
// `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;
  const videoRef = useRef<VideoRef>(null);
  const [status, setStatus] = useState('Ready');
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);
  const actions = useMemo(
    () => [
      { label: 'Play', onPress: () => videoRef.current?.play() },
      { label: 'Pause', onPress: () => videoRef.current?.pause() },
      { label: 'Skip to 4s', onPress: () => videoRef.current?.seek(4) },
      { label: 'Volume 50%', onPress: () => videoRef.current?.setVolume(0.5) },
  { label: 'Mute', onPress: () => videoRef.current?.setVolume(0) },
  { label: 'Unmute', onPress: () => videoRef.current?.setVolume(1) },
      { label: '1.5× speed', onPress: () => videoRef.current?.setPlaybackRate(1.5) },
      { label: 'Reset status', onPress: () => setStatus('Ready') },
    ],
    []
  );
  const formatTime = (seconds: number) => {
    const mins = Math.floor(seconds / 60)
      .toString()
      .padStart(2, '0');
    const secs = Math.floor(seconds % 60)
      .toString()
      .padStart(2, '0');
    return `${mins}:${secs}`;
  };
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Combine default transport controls with imperative helpers to script playback, adjust volume, and toggle captions from surrounding UI.
        </Text>
        <Video
          ref={videoRef}
          source={SOURCE}
          w="100%"
          h={300}
          controls={{
            play: true,
            pause: true,
            progress: true,
            time: true,
            volume: true,
            fullscreen: true,
            playbackRate: true,
            quality: true,
            autoHide: true,
            autoHideTimeout: 3000,
          }}
          onPlay={() => setStatus('Playing')}
          onPause={() => setStatus('Paused')}
          onLoad={() => setStatus('Loaded')}
          onBuffer={(buffering) => setStatus(buffering ? 'Buffering…' : 'Playing')}
          onTimeUpdate={(state) => setCurrentTime(state.currentTime)}
          onDurationChange={(value) => setDuration(value)}
          onError={(error) => setStatus(`Error: ${error}`)}
        />
        <Block>
          <Text size="xs" color="secondary">
            Status: {status}
          </Text>
          {duration > 0 && (
            <Text size="xs" color="secondary">
              Progress: {formatTime(currentTime)} / {formatTime(duration)}
            </Text>
          )}
        </Block>
        <Row gap="sm" wrap="wrap">
          {actions.map((action) => (
            <Button key={action.label} size="xs" variant="outline" onPress={action.onPress}>
              {action.label}
            </Button>
          ))}
        </Row>
      </Block>
    </Card>
  );
}
```

### Timeline Events
ID: `Video.timeline` • Tags: video, timeline, events • Category: advanced • Status: stable • Since: 1.0.0

Pass `timeline` markers to fire callbacks at specific timestamps and keep a log of playback milestones without polling the player.

```tsx
// `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;
  const [log, setLog] = useState<string[]>([]);
  const timelineEvents = useMemo<VideoTimelineEvent[]>(
    () => [
      {
        id: 'intro',
        time: 2,
        type: 'chapter',
        data: { label: 'Introduction', description: 'Video introduction starts' },
        callback: (_, state) => {
          console.log('Introduction reached!', state.currentTime);
          setLog((entries) => [...entries, 'Reached introduction at 2s']);
        },
      },
      {
        id: 'main-content',
        time: 5,
        type: 'chapter',
        data: { label: 'Main content', description: 'Main content begins' },
        callback: (_, state) => {
          console.log('Main content reached!', state.currentTime);
          setLog((entries) => [...entries, 'Reached main content at 5s']);
        },
      },
    ],
    []
  );
  const handleTimelineEvent = (event: VideoTimelineEvent, state: VideoState) => {
    console.log('Timeline event triggered:', event.id, 'at time:', state.currentTime);
  };
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Attach `timeline` markers to run callbacks as playback crosses those timestamps. Use the `onTimelineEvent` hook for analytics or syncing UI.
        </Text>
        <Video
          source={SOURCE}
          w="100%"
          h={300}
          controls
          timeline={timelineEvents}
          onTimelineEvent={handleTimelineEvent}
        />
        <Block>
          <Text size="xs" color="secondary">
            Timeline log
          </Text>
          {log.length === 0 ? (
            <Text size="xs" color="secondary">
              Press play to fire registered markers.
            </Text>
          ) : (
            <Block>
              {log.map((entry, index) => (
                <Text key={`${entry}-${index}`} size="xs">
                  {entry}
                </Text>
              ))}
            </Block>
          )}
          {log.length > 0 && (
            <Button size="xs" variant="outline" onPress={() => setLog([])}>
              Clear log
            </Button>
          )}
        </Block>
      </Block>
    </Card>
  );
}
```

### YouTube Source
ID: `Video.youtube` • Tags: video, youtube, providers • Category: integrations • Status: stable • Since: 1.0.0

Point `Video` at a YouTube URL to stream hosted media while keeping the same control surface and status callbacks as native sources.

```tsx
const YOUTUBE_SOURCE = { youtube: 'dQw4w9WgXcQ' } as const;
  const [status, setStatus] = useState('Paused');
  const [currentTime, setCurrentTime] = useState(0);
  const [duration, setDuration] = useState(0);
  return (
    <Card p="md">
      <Block>
        <Text size="sm" color="secondary">
          Stream YouTube content by pointing `source.youtube` to an ID. Playback state stays in sync so you can react to buffering or progress updates.
        </Text>
        <Video
          source={YOUTUBE_SOURCE}
          w={420}
          h={280}
          controls={{
            play: true,
            pause: true,
            progress: true,
            time: true,
            volume: true,
            fullscreen: true,
            playbackRate: true,
            quality: true,
          }}
          youtubeOptions={{
            modestbranding: true,
            rel: false,
          }}
          onPlay={() => setStatus('Playing')}
          onPause={() => setStatus('Paused')}
          onBuffer={(buffering) => setStatus(buffering ? 'Buffering…' : 'Playing')}
          onError={() => setStatus('Error')}
          onTimeUpdate={(state) => {
            setCurrentTime(state.currentTime);
            setDuration(state.duration);
          }}
        />
        <Row gap="sm" justify="space-between" align="center">
          <Text size="xs" color="secondary">
            Status: {status}
          </Text>
          <Text size="xs" color="secondary">
            {Math.floor(currentTime)}s / {Math.floor(duration)}s
          </Text>
        </Row>
        <Row gap="sm" wrap="wrap">
          <Button size="xs" variant="outline" onPress={() => setStatus('Paused')}>
            Reset status
          </Button>
        </Row>
      </Block>
    </Card>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/Waveform.md -->

# Waveform

Waveform component provides visualization and interaction capabilities for audio data, supporting various display modes and interactive features.

## Metadata

- Canonical name: `Waveform`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { Waveform } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: media
- Tags: audio, waveform, visualization, media, interactive
- Docs: https://react-ui-library.com/components/Waveform
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/Waveform

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `peaks` | number[] | Yes |  | Array of peak values (normalized between -1 and 1) |
| `w` | number | No |  | Width of the waveform |
| `h` | number | No |  | Height of the waveform |
| `color` | string | No |  | Color of the waveform |
| `variant` | 'bars' \| 'line' \| 'rounded' \| 'gradient' | No |  | Visual variant of the waveform |
| `size` | ComponentSizeValue | No | '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 | No |  | Width of individual bars (for bar variants) |
| `barGap` | number | No |  | Gap between bars (for bar variants) |
| `strokeWidth` | number | No |  | Stroke width for line variant |
| `gradientColors` | string[] | No |  | Colors for gradient variant |
| `progress` | number | No |  | Progress value (0-1) to show playback position |
| `progressColor` | string | No |  | Color for the progress indicator |
| `interactive` | boolean | No |  | Whether the waveform is interactive (clickable for seeking) |
| `onSeek` | (position: number) => void | No |  | Callback fired when user clicks/seeks to a position |
| `onDragStart` | (position: number) => void | No |  | Callback fired when user starts dragging |
| `onDrag` | (position: number) => void | No |  | Callback fired when user is dragging |
| `onDragEnd` | (position: number) => void | No |  | Callback fired when user ends dragging |
| `accessibilityLabel` | string | No |  | Accessibility label for the waveform |
| `accessibilityHint` | string | No |  | Accessibility hint for interactive waveforms |
| `minBarHeight` | number | No |  | Minimum height for bars (prevents invisible bars) |
| `normalize` | boolean | No |  | Whether to normalize waveform heights so the tallest bar uses full height |
| `fullWidth` | boolean | No |  | Whether the waveform should take the full width of its container |
| `maxVisibleBars` | number | No |  | Maximum number of bars to render (for performance with large datasets) |
| `showProgressLine` | boolean | No |  | Whether to show a vertical progress line indicator |
| `progressLineStyle` | { color?: string; width?: number; opacity?: number; } | No |  | Style configuration for the progress line |
| `showTimeStamps` | boolean | No |  | Whether to show time stamps along the waveform |
| `duration` | number | No |  | Duration in seconds for time stamp calculation |
| `timeStampInterval` | number | No |  | Time stamp interval in seconds |
| `loading` | boolean | No |  | Whether the waveform is in a loading state |
| `error` | string | No |  | Error message to display |
| `loadingProgress` | number | No |  | Loading progress (0-1) for progressive loading |
| `selection` | [number, number] | No |  | Selected time range [start, end] in normalized coordinates (0-1) |
| `onSelectionChange` | (selection: [number, number]) => void | No |  | Callback when selection changes |
| `zoomLevel` | number | No |  | Zoom level (1 = normal, 2 = 2x zoom, etc.) |
| `zoomCenter` | number | No |  | Zoom center position (0-1) |
| `onZoomChange` | (zoomLevel: number, center: number) => void | No |  | Callback when zoom changes |
| `enableAnimations` | boolean | No |  | Whether to enable smooth animations |
| `showRMS` | boolean | No |  | Whether to show RMS (average) levels alongside peaks |
| `rmsData` | number[] | No |  | RMS data array (should match peaks length) |
| `markers` | WaveformMarker[] | No |  | Custom markers to display on the waveform |
| `enablePerformanceMonitoring` | boolean | No |  | Enable performance monitoring |
| `onPerformanceMetrics` | (metrics: PerformanceMetrics) => void | No |  | Callback for performance metrics |

## Examples

### Basic Usage
ID: `Waveform.basic` • Tags: peaks, progress • Category: basics • Status: stable • Since: 1.0.0

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
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>
  );
}
```

### Full Width
ID: `Waveform.fullWidth` • Tags: responsive, fullWidth • Category: layout • Status: stable • Since: 1.0.0

Enable the `fullWidth` prop to let the waveform stretch to its container; wrap it in a constrained parent when you need a fixed width.

```tsx
return (
    <Block>
      <Block w="100%" maxW={320}>
        <Text variant="small">Fixed width waveform</Text>
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} progress={0.35} h={56} />
      </Block>
      <Block w="100%">
        <Text variant="small">`fullWidth` stretches to the container</Text>
        <Waveform
          peaks={WAVEFORM_DEMO_PEAKS}
          progress={0.6}
          h={56}
          fullWidth
          color="primary"
        />
      </Block>
    </Block>
  );
}
```

### Variants
ID: `Waveform.variants` • Tags: color, variant, normalize • Category: theming • Status: stable • Since: 1.0.0

`variant` picks the render style — `bars`, `rounded`, `line`, or `gradient` — and `color` and `normalize` restyle the result. All four are drawn from the same peak data.

```tsx
const VARIANTS = [
  { variant: 'bars', hint: 'Square bars — the default.' },
  { variant: 'rounded', hint: 'Bars with pill caps.' },
  { variant: 'line', hint: 'Continuous stroked path.' },
  { variant: 'gradient', hint: 'Bars filled with a color ramp.' },
] as const;
  return (
    <Block gap="lg">
      <Block gap="sm">
        <Text variant="small" weight="medium">
          Variant styles
        </Text>
        {VARIANTS.map(({ variant, hint }) => (
          <Block key={variant} gap="xs">
            <Row gap="xs" align="baseline" wrap="wrap">
              <Text variant="small" weight="medium">
                {variant}
              </Text>
              <Text size="xs" color="secondary">
                {hint}
              </Text>
            </Row>
            <Waveform
              peaks={WAVEFORM_DEMO_PEAKS}
              h={64}
              progress={0.4}
              variant={variant}
              color="primary"
            />
          </Block>
        ))}
        <Text size="xs" color="secondary">
          The gradient ramp is derived from `color`; pass `gradientColors` to
          supply your own stops.
        </Text>
      </Block>
      <Block gap="sm">
        <Text variant="small" weight="medium">
          Semantic colors
        </Text>
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={56} progress={0.25} color="primary" />
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={56} progress={0.5} color="success" />
        <Waveform peaks={WAVEFORM_DEMO_PEAKS} h={56} progress={0.75} color="warning" />
      </Block>
      <Block gap="sm">
        <Text variant="small" weight="medium">
          Normalized quiet tracks
        </Text>
        <Waveform peaks={QUIET_WAVEFORM_PEAKS} h={56} progress={0.45} color="surface" />
        <Waveform
          peaks={QUIET_WAVEFORM_PEAKS}
          h={56}
          progress={0.45}
          normalize
          color="surface"
        />
      </Block>
    </Block>
  );
}
```

### Synchronized
ID: `Waveform.synchronized` • Tags: multi-track, shared-state • Category: advanced • Status: stable • Since: 1.0.0

Drive multiple waveforms from the same `progress` state so scrubbing either track keeps every timeline aligned.

```tsx
const CUE_POINTS: number[] = [0, 0.25, 0.5, 0.75, 1];
  const [progress, setProgress] = useState<number>(0.35);
  const handleSeek = (value: number) => {
    setProgress(value);
  };
  return (
    <Block>
      <Block>
        <Text variant="small">Narration track</Text>
        <Waveform
          peaks={WAVEFORM_DEMO_PEAKS}
          progress={progress}
          h={80}
          fullWidth
          color="primary"
          interactive
          onSeek={handleSeek}
        />
      </Block>
      <Block>
        <Text variant="small">Background score</Text>
        <Waveform
          peaks={TRACK_TWO_PEAKS}
          progress={progress}
          h={80}
          fullWidth
          color="secondary"
          interactive
          onSeek={handleSeek}
        />
      </Block>
      <Row gap="sm" wrap="wrap">
        {CUE_POINTS.map((value) => (
          <Button key={value} variant="outline" onPress={() => handleSeek(value)}>
            {Math.round(value * 100)}%
          </Button>
        ))}
      </Row>
      <Text variant="small">Shared progress: {Math.round(progress * 100)}%</Text>
    </Block>
  );
}
```

### Audio playback
ID: `Waveform.audioPlayback` • Tags: audio, expo-audio, progress, onSeek • Category: advanced • Status: stable • Since: 1.0.0

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
const TRACKS = [
  {
    id: 'melody',
    label: 'Arpeggio',
    peaks: MELODY_PEAKS,
    source: require('../../../../assets/sounds/melody.mp3'),
  },
  {
    id: 'chime',
    label: 'Chime',
    peaks: CHIME_PEAKS,
    source: require('../../../../assets/sounds/chime.mp3'),
  },
  {
    id: 'rain',
    label: 'Rainfall',
    peaks: RAIN_PEAKS,
    source: require('../../../../assets/sounds/rain.mp3'),
  },
];
const formatTime = (seconds: number) => {
  const total = Math.max(0, Math.floor(seconds));
  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, '0')}`;
};
  const [index, setIndex] = useState(0);
  const track = TRACKS[index];
  // expo-audio rebuilds the player whenever the source changes, so selecting a
  // track loads that clip.
  const player = useAudioPlayer(track.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 gap="sm">
      <Row gap="xs" wrap="wrap">
        {TRACKS.map((item, itemIndex) => (
          <Button
            key={item.id}
            size="sm"
            variant={itemIndex === index ? 'filled' : 'outline'}
            onPress={() => setIndex(itemIndex)}
          >
            {item.label}
          </Button>
        ))}
      </Row>
      <Waveform
        peaks={track.peaks}
        progress={progress}
        h={96}
        fullWidth
        variant="rounded"
        color="primary"
        interactive
        onSeek={handleSeek}
        showProgressLine
        showTimeStamps
        duration={duration}
        accessibilityLabel={`${track.label} waveform`}
        accessibilityHint="Tap or drag to seek within the clip"
      />
      <Row gap="sm" align="center" wrap="wrap">
        <Button size="sm" onPress={togglePlayback}>
          {status.playing ? 'Pause' : 'Play'}
        </Button>
        <Text variant="small" color="muted">
          {formatTime(status.currentTime)} / {formatTime(duration)}
        </Text>
      </Row>
    </Block>
  );
}
```

### Synced to video
ID: `Waveform.videoSync` • Tags: video, sync, progress, onSeek • Category: advanced • Status: stable • Since: 1.0.0

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
// `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;
  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 gap="sm" w="100%" maxW={640}>
      <Video
        ref={videoRef}
        source={{ url: CLIP_URL }}
        w="100%"
        aspectRatio={640 / 426}
        controls
        muted={false}
        onLoad={track}
        onTimeUpdate={track}
        onDurationChange={(duration) => setPlayback((prev) => ({ ...prev, duration }))}
      />
      <Waveform
        peaks={CLIP_PEAKS}
        progress={progress}
        h={72}
        fullWidth
        color="primary"
        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"
      />
      <Text variant="small" color="muted">
        The peaks were measured from this clip's audio track. `onTimeUpdate` feeds `progress`, and
        scrubbing the waveform calls `seek()` on the video ref — so the two stay in step in both
        directions.
      </Text>
    </Block>
  );
}
```

### Interactive
ID: `Waveform.interactive` • Tags: interactive, onSeek, progress • Category: advanced • Status: stable • Since: 1.0.0

Turn on the `interactive` prop and handle `onSeek`/drag callbacks to update shared playback progress as the user scrubs the waveform.

```tsx
const SEEK_PRESETS: number[] = [0.25, 0.5, 0.75];
  const [progress, setProgress] = useState<number>(0.2);
  const [isScrubbing, setIsScrubbing] = useState<boolean>(false);
  const handleSeek = (value: number) => {
    setProgress(value);
  };
  return (
    <Block>
      <Waveform
        peaks={WAVEFORM_DEMO_PEAKS}
        progress={progress}
        fullWidth
        h={72}
        color="primary"
        interactive
        showProgressLine
        onSeek={handleSeek}
        onDragStart={() => setIsScrubbing(true)}
        onDrag={handleSeek}
        onDragEnd={(value) => {
          setIsScrubbing(false);
          handleSeek(value);
        }}
        accessibilityLabel="Audio timeline"
        accessibilityHint="Drag or tap to seek"
      />
      <Row gap="sm" wrap="wrap">
        {SEEK_PRESETS.map((value) => (
          <Button key={value} variant="outline" onPress={() => handleSeek(value)}>
            Jump to {Math.round(value * 100)}%
          </Button>
        ))}
      </Row>
      <Text variant="small">
        {isScrubbing ? 'Scrubbing…' : 'Progress:'} {Math.round(progress * 100)}%
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `YearPicker`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { YearPicker } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: dates
- Docs: https://react-ui-library.com/components/YearPicker
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/YearPicker

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | Date \| null | No |  | Currently selected date |
| `onChange` | (date: Date \| null) => void | No |  | Called when a year is selected |
| `decade` | number | No |  | Decade anchor that should be displayed |
| `onDecadeChange` | (decade: number) => void | No |  | Called when the visible decade changes |
| `minDate` | Date | No |  | Minimum selectable date (inclusive) |
| `maxDate` | Date | No |  | Maximum selectable date (inclusive) |
| `size` | SizeValue | No |  | Typography size token |
| `yearsPerRow` | ResponsiveProp<number> | No |  | Responsive override for number of years per row |
| `hideHeader` | boolean | No |  | Hide navigation header when embedding the picker |
| `totalYears` | number | No |  | Total number of years to render (defaults to 20) |
| `fullWidth` | boolean | No |  | Stretch to fill the container instead of sizing to the natural grid width. Default `false`. |

## Examples

### Basic
ID: `YearPicker.basic` • Category: general

```tsx
const [value, setValue] = useState<Date | null>(new Date());
  return (
    <Block fullWidth>
      <YearPicker value={value} onChange={setValue} totalYears={20} />
      <Text size="sm" color="secondary">
        {value ? `Selected: ${value.getFullYear()}` : 'No year selected'}
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/YearPickerInput.md -->

# YearPickerInput

Input component that opens `YearPicker` inside a modal dialog. Ideal for settings where only the year matters (fiscal periods, graduation year, etc.) while keeping the UI aligned with the rest of our picker inputs.

## Metadata

- Canonical name: `YearPickerInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { YearPickerInput } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.1.0
- Category: dates
- Docs: https://react-ui-library.com/components/YearPickerInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/components/YearPickerInput

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | Date \| null | No |  | Controlled value for the selected year |
| `defaultValue` | Date \| null | No |  | Default year when uncontrolled |
| `onChange` | (value: Date \| null) => void | No |  | Called when the year selection changes |
| `formatValue` | (value: Date) => string | No |  | Custom formatter for the input value |
| `placeholder` | string | No |  | Placeholder text when no year is selected |
| `clearable` | boolean | No |  | Show a clear button when a year is selected |
| `closeOnSelect` | boolean | No |  | Close the picker after selecting a year |
| `yearPickerProps` | Partial<Omit<YearPickerProps, 'value'>> | No |  | Additional props forwarded to YearPicker (except value) |
| `modalTitle` | string | No |  | Dialog title text |
| `onOpen` | () => void | No |  | Called when the picker dialog opens |
| `onClose` | () => void | No |  | Called when the picker dialog closes |
| `variant` | InputVariant | No |  | Visual variant of the input. `default` (light surface + border), `filled` (gray fill, no border), `outline` (transparent fill, border only), `unstyled` (no border, no fill). |
| `label` | React.ReactNode | No |  | Input label (string or component) |
| `disabled` | boolean | No |  | Whether input is disabled |
| `required` | boolean | No |  | Whether input is required |
| `error` | string | No |  | Error message |
| `helperText` | string | No |  | Helper text |
| `description` | string | No |  | Optional short description displayed directly under the label (above the field) |
| `size` | SizeValue | No |  | Input size |
| `withAsterisk` | boolean | No |  | Whether to show required indicator |
| `name` | string | No |  | Input name for form integration |
| `startSection` | React.ReactNode | No |  | Left section content |
| `endSection` | React.ReactNode | No |  | Right section content |
| `style` | any | No |  | Additional styling |
| `accessibilityLabel` | string | No |  | Accessibility label |
| `accessibilityHint` | string | No |  | Accessibility hint |
| `testID` | string | No |  | Test ID for testing |
| `debounceMs` | number | No |  | Debounce delay for validation in milliseconds |
| `onFocus` | () => void | No |  | Focus handler |
| `onBlur` | () => void | No |  | Blur handler |
| `onEnter` | () => void | No |  | Enter key press handler |
| `clearButtonLabel` | string | No |  | Accessible label for the clear button |
| `onClear` | () => void | No |  | Callback when the clear button is pressed |
| `keyboardFocusId` | string | No |  | Identifier used with KeyboardManagerProvider to request refocus |
| `labelProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field label `<Text>` (style, weight, ff, etc.) |
| `descriptionProps` | Omit<TextProps, 'children'> | No |  | Override props applied to the field description `<Text>` |
| `placeholderTextColor` | string | No |  | Color of the placeholder text. Falls back to `theme.text.muted`. |
| `startSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `startSection` (style, accessibility, etc.). |
| `endSectionProps` | Omit<ViewProps, 'children'> | No |  | Props applied to the wrapping `<View>` around `endSection`. |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `fullWidth` | boolean | No |  | Makes the component fill the full width of its parent |
| `w` | DimensionValue | No |  | Sets a specific width |
| `h` | DimensionValue | No |  | Sets a specific height |
| `maxW` | DimensionValue | No |  | Sets the maximum width |
| `minW` | DimensionValue | No |  | Sets the minimum width |
| `maxH` | DimensionValue | No |  | Sets the maximum height |
| `minH` | DimensionValue | No |  | Sets the minimum height |
| `radius` | RadiusValue | No |  | Border radius value - supports size tokens, numbers, and special values |

## Examples

### Basic
ID: `YearPickerInput.basic` • Category: general

```tsx
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" color="secondary">
        {value ? `Selected: ${value.getFullYear()}` : 'No year selected'}
      </Text>
    </Block>
  );
}
```

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

# CHARTS

<!-- source: https://react-ui-library.com/llms/components/AreaChart.md -->

# Area Chart

Area (filled) chart for visualizing cumulative or stacked trends.

## Metadata

- Canonical name: `AreaChart`
- Package: `@platform-blocks/charts`
- Import: `import { AreaChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, area, timeseries
- Docs: https://react-ui-library.com/components/AreaChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/AreaChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layout` | AreaChartLayout | No | 'overlap' | Controls how multiple series are rendered. - `overlap` leaves each area independent (default). - `stacked` cumulatively stacks values and renders using stacked layers. |
| `areaOpacity` | number | No |  | Opacity used when rendering stacked layers (if not provided defaults to fillOpacity). |
| `stackOrder` | 'normal' \| 'reverse' | No |  | Adjust the stacking order when using stacked layouts. |
| `data` | ChartDataPoint[] | No |  | Data points (single series) or array of series (multiseries) |
| `series` | LineChartSeries[] | No |  | Multiple data series |
| `lineColor` | string | No |  | Line color (for single series) |
| `lineThickness` | number | No |  | Line thickness (for single series) |
| `lineStyle` | 'solid' \| 'dashed' \| 'dotted' | No |  | Line style (for single series) |
| `showPoints` | boolean | No |  | Show data points (for single series) |
| `pointSize` | number | No |  | Point size (for single series) |
| `pointColor` | string | No |  | Point color (for single series) |
| `smooth` | boolean | No |  | Smooth curve |
| `fill` | boolean | No |  | Fill area under line |
| `fillColor` | string | No |  | Fill color |
| `fillOpacity` | number | No |  | Fill opacity |
| `areaFillMode` | 'single' \| 'series' | No |  | How to distribute fill across series when multiple are present |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<ChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `enableCrosshair` | boolean | No |  | Show a vertical crosshair that follows the nearest point |
| `enableSeriesToggle` | boolean | No |  | Enable toggling series visibility from legend |
| `liveTooltip` | boolean | No |  | Update tooltip continuously while moving (not just on press) |
| `multiTooltip` | boolean | No |  | Show multi-series aggregated tooltip aligned to crosshair |
| `enablePanZoom` | boolean | No |  | Enable pan and pinch zoom interactions |
| `zoomMode` | 'x' \| 'y' \| 'both' | No |  | Which axes can zoom |
| `minZoom` | number | No |  | Minimum zoom factor relative to original domain (e.g. 0.1 = 10%) |
| `onDomainChange` | (xDomain: [number, number], yDomain: [number, number]) => void | No |  | Callback when visible data domain changes |
| `enableWheelZoom` | boolean | No |  | Enable wheel zoom on web |
| `wheelZoomStep` | number | No |  | Wheel zoom step factor (default 0.1) |
| `invertWheelZoom` | boolean | No |  | Invert wheel zoom direction |
| `resetOnDoubleTap` | boolean | No |  | Double-tap (or double-click on web) resets zoom |
| `clampToInitialDomain` | boolean | No |  | Clamp pan/zoom so domains never exceed original data bounds |
| `invertPinchZoom` | boolean | No |  | Invert pinch gesture direction (scale grows when fingers move closer) |
| `disableAnimations` | boolean | No |  | Disable all Reanimated-driven animations (debug / perf fallback) |
| `decimationThreshold` | number | No |  | Apply LTOB data decimation above this point count |
| `xScaleType` | 'linear' \| 'log' \| 'time' | No |  | X axis scale type |
| `yScaleType` | 'linear' \| 'log' \| 'time' | No |  | Y axis scale type |
| `enableBrushZoom` | boolean | No |  | Enable shift+drag brush to zoom (web) |
| `annotations` | ChartAnnotation[] | No |  | Optional chart annotations/markers |
| `width` | number | No |  | 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. |
| `height` | number | No |  | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `AreaChart.basic` • Category: charts

Simple random data area chart with title.

```tsx
return (
    <AreaChart
      title="Weekly signups"
      subtitle="Organic vs virality"
      height={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
    />
  );
}
```

### Inventory Levels Warehouses
ID: `AreaChart.inventory-levels-warehouses` • Category: charts

```tsx
return (
    <AreaChart
      title="Inventory Levels by Warehouse"
      subtitle="Safety stock adjustments across the first half"
      height={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
    />
  );
}
```

### Mobile Device Sessions
ID: `AreaChart.mobile-device-sessions` • Category: charts

```tsx
const formatPhase = (index: number) => PHASE_LABELS[index] ?? `Week ${index + 1}`;
  return (
    <AreaChart
      title="Active Sessions During Launch"
      subtitle="Layered by device platform"
      height={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
    />
  );
}
```

### Renewable Energy Mix
ID: `AreaChart.renewable-energy-mix` • Category: charts

Stacks monthly solar, wind, and hydro production to highlight how policy shifts increase clean generation share over the first half of 2025.

```tsx
const formatMonth = (index: number) => MONTH_LABELS[index] ?? `M${index + 1}`;
  return (
    <AreaChart
      layout="stacked"
      title="Renewable Energy Generation"
      subtitle="Utility-scale output by source"
      height={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
    />
  );
}
```

### Streaming Minutes Campaign
ID: `AreaChart.streaming-minutes-campaign` • Category: charts

**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
return (
    <AreaChart
      title="Streaming Minutes During Campaign"
      subtitle="Share of viewing time by content category"
      height={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
    />
  );
}
```

### Support Severity Over Time
ID: `AreaChart.support-severity-over-time` • Category: charts

**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
const formatWeek = (index: number) => WEEKS[index] ?? `Week ${index + 1}`;
  return (
    <AreaChart
      title="Quarterly Support Ticket Mix"
      subtitle="Stacked by severity level"
      height={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
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/BarChart.md -->

# Bar Chart

Discrete / categorical bar chart visualization component.

## Metadata

- Canonical name: `BarChart`
- Package: `@platform-blocks/charts`
- Import: `import { BarChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, bar, categorical
- Docs: https://react-ui-library.com/components/BarChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/BarChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | BarChartDataPoint[] | Yes |  | Data points |
| `series` | BarChartSeries[] | No |  | Optional multi-series data |
| `barColor` | string | No |  | Bar color |
| `barSpacing` | number | No | 0.2 | Bar spacing (0-1) |
| `barBorderRadius` | number | No | 4 | Bar border radius |
| `orientation` | 'vertical' \| 'horizontal' | No | 'vertical' | Orientation |
| `layout` | 'single' \| 'grouped' \| 'stacked' | No |  | Layout strategy for multi-series data |
| `stackMode` | 'normal' \| '100%' | No | 'normal' | Stacked layout mode |
| `valueFormatter` | (value: number, datum: BarChartDataPoint, index: number) => string | No |  | Optional value formatter for tooltip display |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid configuration |
| `legend` | ChartLegend | No | { show: true, position: 'bottom', align: 'center' } | Legend configuration |
| `legendToggleEnabled` | boolean | No |  | Allow toggling series visibility from the legend |
| `thresholds` | BarChartThreshold[] | No |  | Reference lines overlaid on the chart |
| `valueLabel` | BarChartValueLabelConfig | No |  | Value label configuration |
| `colorScale` | (context: { datum: BarChartDataPoint; series: BarChartSeries; seriesIndex: number; categoryIndex: number; }) => string \| undefined | No |  | Custom color scale resolver |
| `tooltip` | ChartTooltip<BarChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `multiTooltip` | boolean | No |  | Shared multi-series tooltip |
| `enableCrosshair` | boolean | No |  | Crosshair enable |
| `liveTooltip` | boolean | No |  | Live pointer-follow tooltip |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### BarChart Basic
ID: `BarChart.basic` • Tags: basic, getting-started • Category: charts • Status: stable • Since: 1.0.0

Basic BarChart usage with a title.

```tsx
return (
    <BarChart
      title="Quarterly revenue"
      subtitle="North America"
      height={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
    />
  );
}
```

### Feature Adoption By Tier
ID: `BarChart.feature-adoption-by-tier` • Category: charts

```tsx
const formatAccounts = (value: number) => `${value.toLocaleString()} accounts`;
  return (
    <BarChart
      title="Feature adoption by customer tier"
      subtitle="Accounts live on the experimentation canvas within 45 days"
      height={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');
        },
      }}
    />
  );
}
```

### Marketing Spend Multi Touch
ID: `BarChart.marketing-spend-multi-touch` • Category: charts

```tsx
const formatSpend = (value: number) => `$${value.toLocaleString()}k`;
  return (
    <BarChart
      title="Marketing spend by channel"
      subtitle="Multi-touch journey campaign mix"
      height={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');
        },
      }}
    />
  );
}
```

### New Hire Recruiting Cycles
ID: `BarChart.new-hire-recruiting-cycles` • Category: charts

```tsx
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`;
};
  return (
    <BarChart
      title="New hires secured this recruiting cycle"
      subtitle="Compared with winter intake"
      height={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');
        },
      }}
    />
  );
}
```

### Quarterly Revenue Variance
ID: `BarChart.quarterly-revenue-variance` • Category: charts

```tsx
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`;
};
  return (
    <BarChart
      title="Quarterly Revenue by Region"
      subtitle="Q3 actuals with variance to plan"
      height={420}
      data={REGIONAL_REVENUE}
      barSpacing={0.32}
      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');
        },
      }}
    />
  );
}
```

### Sla Compliance By Team
ID: `BarChart.sla-compliance-by-team` • Category: charts

```tsx
const formatPercent = (value: number) => `${value.toFixed(1)}%`;
  return (
    <BarChart
      title="SLA compliance by response team"
      subtitle="Rolling 12-month attainment"
      height={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');
        },
      }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/BubbleChart.md -->

# Bubble Chart

Scatter-style plot where point radius encodes a third quantitative dimension.

## Metadata

- Canonical name: `BubbleChart`
- Package: `@platform-blocks/charts`
- Import: `import { BubbleChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, bubble, scatter
- Docs: https://react-ui-library.com/components/BubbleChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/BubbleChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | T[] | Yes | [] | Dataset to render |
| `dataKey` | BubbleChartDataKey<T> | Yes |  | Mapping between dataset keys and chart dimensions |
| `range` | [number, number] | No | [36, 576] | Bubble area range (min/max) used to derive radius. Defaults to [36, 576]. |
| `minBubbleSize` | number | No |  | Optional minimum bubble radius override (px). |
| `maxBubbleSize` | number | No |  | Optional maximum bubble radius override (px). |
| `color` | string | No |  | Base fill color when data does not provide one. |
| `colorScale` | (value: any, record: T, index: number) => string \| undefined | No |  | Optional color scale function allowing categorical values to resolve to palette entries. |
| `bubbleOpacity` | number | No |  | Bubble fill opacity. Defaults to 0.85. |
| `bubbleStrokeColor` | string | No | 'rgba(0,0,0,0.12)' | Bubble outline color. |
| `bubbleStrokeWidth` | number | No | 1 | Bubble outline width. Defaults to 1. |
| `textColor` | string | No |  | Axis/grid text color override. |
| `gridColor` | string | No |  | Grid line color override. |
| `label` | string | No |  | Optional label shown inside the plot area. |
| `valueFormatter` | (value: number, record: T, index: number) => string | No |  | Custom formatter for bubble size values (tooltip + legend). |
| `withTooltip` | boolean | No | 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; }> | No |  | Advanced tooltip configuration |
| `grid` | ChartGrid \| boolean | No | true | Supply custom grid configuration or disable grid entirely. |
| `legend` | ChartLegend | No |  | Legend configuration. |
| `xAxis` | ChartAxis | No | {} | X axis configuration (ticks, formatting, labels). |
| `yAxis` | ChartAxis | No | {} | Y axis configuration (ticks, formatting, labels). |
| `h` | number | No |  | Height alias |
| `width` | number | No | 400 | 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. |
| `height` | number | No |  | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `BubbleChart.basic` • Category: charts

```tsx
return (
    <BubbleChart
      title="Revenue vs Growth"
      subtitle="Bubble size shows valuation (in millions)"
      height={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]}
    />
  );
}
```

### Cities Talent Footprint
ID: `BubbleChart.cities-talent-footprint` • Category: charts

```tsx
const formatFootprint = (value: number) => `${value.toFixed(0)}k sq ft`;
  return (
    <BubbleChart
      title="Global Talent Hubs"
      subtitle="Talent depth vs cost of living — bubble size represents active office footprint"
      height={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' }}
    />
  );
}
```

### Customer Account Health
ID: `BubbleChart.customer-account-health` • Category: charts

```tsx
const formatArr = (value: number) => `$${value.toFixed(2)}M ARR`;
  return (
    <BubbleChart
      title="Customer Account Health vs Expansion"
      subtitle="Bubble size reflects current ARR; use upper-right quadrant to spot ready-to-expand logos"
      height={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]}
    />
  );
}
```

### Engineering Epic Risk
ID: `BubbleChart.engineering-epic-risk` • Category: charts

```tsx
const formatMultiplier = (value: number) => `${value.toFixed(1)}× risk`;
  return (
    <BubbleChart
      title="Epic Risk Landscape"
      subtitle="Story points vs defect density — bubble area communicates composite risk multiplier"
      height={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' }}
    />
  );
}
```

### Product Strategy Portfolio
ID: `BubbleChart.product-strategy-portfolio` • Category: charts

```tsx
const formatMillions = (value: number) => `$${value.toFixed(1)}M`;
  return (
    <BubbleChart
      title="Product Initiative Portfolio"
      subtitle="Strategic value vs execution effort — bubble scales with projected revenue"
      height={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]}
    />
  );
}
```

### Vendor Contracts Scoring
ID: `BubbleChart.vendor-contracts-scoring` • Category: charts

```tsx
const formatSpend = (value: number) => `$${value.toFixed(1)}M`;
  return (
    <BubbleChart
      title="Vendor Contract Health"
      subtitle="Compliance vs renewal probability — bubble area encodes annual spend"
      height={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' }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/CandlestickChart.md -->

# Candlestick Chart

Visualizes financial OHLC price movements over time.

## Metadata

- Canonical name: `CandlestickChart`
- Package: `@platform-blocks/charts`
- Import: `import { CandlestickChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, financial, ohlc
- Docs: https://react-ui-library.com/components/CandlestickChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/CandlestickChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | CandlestickSeries[] | Yes |  | One or more candlestick series to render |
| `movingAveragePeriods` | number[] | No | [] | Periods for moving average overlay lines (e.g. [20,50]) |
| `movingAverageColors` | string[] | No | [] | Colors for moving average overlays (falls back to series palette) |
| `showMovingAverages` | boolean | No | true | Show moving average overlays (defaults true if periods provided) |
| `showVolume` | boolean | No | false | Show volume bars underneath (reserved) |
| `volumeHeightRatio` | number | No | 0.22 | Relative height ratio for volume sub-chart (0-0.5) |
| `xAxis` | ChartAxis | No |  | Configuration for the horizontal axis |
| `yAxis` | ChartAxis | No |  | Configuration for the vertical axis |
| `grid` | ChartGrid | No |  | Background grid configuration |
| `legend` | ChartLegend | No |  | Legend display options |
| `tooltip` | ChartTooltip<CandlestickDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `enableCrosshair` | boolean | No |  | Enable crosshair indicator |
| `multiTooltip` | boolean | No |  | Enable shared tooltip for multiple series |
| `liveTooltip` | boolean | No |  | Follow pointer live with tooltip |
| `enablePanZoom` | boolean | No |  | Allow interactive pan and zoom |
| `zoomMode` | 'x' \| 'y' \| 'both' | No |  | Which axes support zooming |
| `minZoom` | number | No |  | Minimum zoom factor relative to original domain |
| `enableWheelZoom` | boolean | No |  | Enable wheel-based zooming (web only) |
| `wheelZoomStep` | number | No |  | Step factor applied to wheel zoom operations |
| `invertWheelZoom` | boolean | No |  | Invert wheel zoom direction |
| `resetOnDoubleTap` | boolean | No |  | Reset zoom on double-tap or double-click |
| `clampToInitialDomain` | boolean | No |  | Clamp panning to the initial data domain |
| `invertPinchZoom` | boolean | No |  | Invert pinch zoom direction |
| `xScaleType` | 'linear' \| 'log' \| 'time' | No | 'time' | Scale type used for the x axis |
| `yScaleType` | 'linear' \| 'log' \| 'time' | No | 'linear' | Scale type used for the y axis |
| `annotations` | ChartAnnotation[] | No |  | Additional annotations to render on the chart |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `CandlestickChart.basic` • Category: charts

```tsx
return (
    <CandlestickChart
      title="AAPL daily candles"
      subtitle="Includes 3 & 5-day moving averages"
      height={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"
    />
  );
}
```

### Battery Material Pricing
ID: `CandlestickChart.battery-material-pricing` • Category: charts

```tsx
const formatWeek = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  day: 'numeric',
});
  return (
    <CandlestickChart
      title="Battery Material Pricing"
      subtitle="Negotiation window tracked across lithium and nickel contracts"
      height={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"
    />
  );
}
```

### Cloud Infra Cost Swings
ID: `CandlestickChart.cloud-infra-cost-swings` • Category: charts

```tsx
return (
    <CandlestickChart
      title="Cloud Spend Volatility"
      subtitle="Optimization window captured a 4.7% cost reduction"
      height={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"
    />
  );
}
```

### Crypto Treasury Balances
ID: `CandlestickChart.crypto-treasury-balances` • Category: charts

```tsx
const formatWeek = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  day: 'numeric',
});
  return (
    <CandlestickChart
      title="Crypto Treasury Balances"
      subtitle="Weekly BTC position changes with treasury policy markers"
      height={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"
    />
  );
}
```

### Saas Usage Peaks
ID: `CandlestickChart.saas-usage-peaks` • Category: charts

```tsx
const formatDay = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  day: 'numeric',
});
  return (
    <CandlestickChart
      title="SaaS Usage Peaks"
      subtitle="Daily active sessions during phased launch with capacity guardrails"
      height={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"
    />
  );
}
```

### Subscription Mrr Dynamics
ID: `CandlestickChart.subscription-mrr-dynamics` • Category: charts

```tsx
const formatMonth = (value: number) => new Date(value).toLocaleDateString('en-US', {
  month: 'short',
  year: 'numeric',
});
  return (
    <CandlestickChart
      title="Subscription MRR Momentum"
      subtitle="Expansion revenue outpaced churn across a pricing refresh"
      height={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"
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/ComboChart.md -->

# Combo Chart

Combines multiple chart types (e.g., bars and line) for richer comparison.

## Metadata

- Canonical name: `ComboChart`
- Package: `@platform-blocks/charts`
- Import: `import { ComboChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, combo, mixed
- Docs: https://react-ui-library.com/components/ComboChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/ComboChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `layers` | ComboChartLayer[] | Yes |  | Ordered set of layers to render in the combo chart |
| `enableCrosshair` | boolean | No | true | Enable crosshair indicator across layers |
| `multiTooltip` | boolean | No | true | Enable multi-series tooltip aggregation |
| `liveTooltip` | boolean | No | true | Follow pointer live with tooltip |
| `xDomain` | [number, number] | No |  | Explicit override for the shared x-domain |
| `yDomain` | [number, number] | No |  | Explicit override for the primary y-domain |
| `yDomainRight` | [number, number] | No |  | Explicit override for the secondary y-domain |
| `xAxis` | ChartAxis | No |  | Axis configuration for the shared x-axis |
| `yAxis` | ChartAxis | No |  | Axis configuration for the primary y-axis |
| `yAxisRight` | ChartAxis | No |  | Axis configuration for the secondary y-axis |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `legend` | ChartLegend | No |  | Legend display options |
| `width` | number | No | 520 | 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. |
| `height` | number | No | 320 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `ComboChart.basic` • Category: charts

```tsx
return (
		<ComboChart
			title="Revenue vs. active users"
			subtitle="First half of FY25"
			height={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' }}
		/>
	);
}
```

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

<!-- source: https://react-ui-library.com/llms/components/DonutChart.md -->

# Donut Chart

Circular proportional chart with a hollow center (variant of pie chart).

## Metadata

- Canonical name: `DonutChart`
- Package: `@platform-blocks/charts`
- Import: `import { DonutChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, donut, circular
- Docs: https://react-ui-library.com/components/DonutChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/DonutChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | DonutChartDataPoint[] | No |  | Data points rendered in the donut |
| `rings` | DonutChartRing[] | No |  | Optional multi-ring configuration. When provided, the top-level data acts as a fallback |
| `size` | number | No | 280 | Convenience size that sets both width and height when explicit values are omitted |
| `innerRadiusRatio` | number | No | 0.55 | Ratio (0-1) of the inner radius relative to the outer radius when thickness is not provided |
| `thickness` | number | No |  | Explicit ring thickness override (outerRadius - innerRadius) |
| `ringGap` | number | No |  | Gap in chart units between concentric rings (defaults to 8 for multi-ring charts) |
| `padAngle` | number | No | 1.5 | Padding between slices in degrees |
| `startAngle` | number | No | -90 | Starting angle for the first slice (degrees) |
| `endAngle` | number | No | 270 | Ending angle for the last slice (degrees) |
| `primaryRingIndex` | number | No | 0 | Index of the ring used for center totals and value formatting (defaults to 0) |
| `legendRingIndex` | number | No |  | Index of the ring whose slices feed the legend (defaults to primaryRingIndex) |
| `inheritColorByLabel` | boolean | No | true | When true, slices across rings reuse colors based on their label/id |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<DonutChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `centerLabel` | string \| DonutCenterLabelFormatter | No |  | Primary label rendered in the center (string or formatter) |
| `centerSubLabel` | string \| DonutCenterLabelFormatter | No |  | Secondary label rendered beneath the primary center label |
| `centerValueFormatter` | DonutCenterValueFormatter | No |  | Formatter for the numerical value shown in the center |
| `renderCenterContent` | DonutChartCenterRenderer | No |  | Custom renderer for the center content. When provided, overrides default labels |
| `emptyLabel` | string | No | 'No data' | Label displayed when no data is provided |
| `padding` | { top: number; right: number; bottom: number; left: number } | No |  | Optional padding override for the chart container |
| `isolateOnClick` | boolean | No | false | When true, clicking a slice isolates it (toggles other slices off) and another click restores |
| `labels` | DonutChartLabelsConfig | No |  | Global label rendering configuration |
| `width` | number | No |  | 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. |
| `height` | number | No |  | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Annual Expense Allocation
ID: `DonutChart.annual-expense-allocation` • Category: charts

```tsx
const formatBudget = (value: number) => `$${Intl.NumberFormat('en-US', { maximumFractionDigits: 0 }).format(value)}M`;
  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)}
    />
  );
}
```

### Basic
ID: `DonutChart.basic` • Category: charts

```tsx
return (
		<DonutChart
			title="Team allocation"
			size={260}
			data={SEGMENTS}
		/>
	);
}
```

### Customer Segment Growth
ID: `DonutChart.customer-segment-growth` • Category: charts

```tsx
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;
  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 Center Power
ID: `DonutChart.data-center-power` • Category: charts

```tsx
const formatMegawatts = (value: number) => `${value.toFixed(1)} MW`;
  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 },
      }}
    />
  );
}
```

### Employee Geography Workstyle
ID: `DonutChart.employee-geography-workstyle` • Category: charts

```tsx
const formatHeadcount = (value: number) => Intl.NumberFormat('en-US', { maximumFractionDigits: 0 }).format(value);
  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' }}
    />
  );
}
```

### Marketplace Fulfillment Mix
ID: `DonutChart.marketplace-fulfillment-mix` • Category: charts

```tsx
const formatOrders = (value: number) => `${value.toFixed(2)}M`;
  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`}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/FunnelChart.md -->

# Funnel Chart

Shows progressive reduction of data through stages (conversion pipeline).

## Metadata

- Canonical name: `FunnelChart`
- Package: `@platform-blocks/charts`
- Import: `import { FunnelChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, funnel, conversion
- Docs: https://react-ui-library.com/components/FunnelChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/FunnelChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | FunnelChartSeries \| FunnelChartSeries[] | Yes |  | Funnel data series to render |
| `layout` | FunnelLayoutConfig | No |  | Layout customization options |
| `valueFormatter` | FunnelValueFormatter | No |  | Formatter for step values |
| `tooltip` | ChartTooltip<FunnelStep> | No |  | Tooltip configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `enableCrosshair` | boolean | No | true | Enable crosshair indicator |
| `multiTooltip` | boolean | No | true | Enable aggregated tooltip for multiple series |
| `liveTooltip` | boolean | No | false | Keep tooltip following the pointer |
| `accessibilityTable` | FunnelAccessibilityTableOptions | No |  | Render hidden accessibility table |
| `onDataTable` | (payloads: FunnelDataTablePayload[]) => void | No |  | Callback invoked with data table payload |
| `width` | number | No | 360 | 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. |
| `height` | number | No | 420 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `FunnelChart.basic` • Category: charts

```tsx
const compact = (value: number) => {
	const abs = Math.abs(value);
	if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
	if (abs >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, '')}K`;
	return `${value}`;
};
	return (
		<FunnelChart
			title="Product acquisition funnel"
			maxWidth={420}
			height={420}
			series={SALES_FUNNEL}
			layout={{
				shape: 'trapezoid',
				gap: 8,
				showConversion: false,
				align: 'center',
				connectors: { show: false },
			}}
			valueFormatter={(value) => compact(value)}
			legend={{ show: false }}
			tooltip={{
				show: true,
				formatter: (step) => `${step.label}: ${step.value.toLocaleString()}`,
			}}
		/>
	);
}
```

### Data Pipeline Quality
ID: `FunnelChart.data-pipeline-quality` • Category: charts

```tsx
const compact = (value: number) => {
  const abs = Math.abs(value);
  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
  if (abs >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, '')}K`;
  return `${value}`;
};
  return (
    <FunnelChart
      title="Data pipeline quality checks"
      subtitle="From ingestion to certified datasets"
      maxWidth={520}
      height={440}
      series={PIPELINE_QUALITY}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => compact(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');
        },
      }}
    />
  );
}
```

### Ecommerce Checkout Payments
ID: `FunnelChart.ecommerce-checkout-payments` • Category: charts

```tsx
const compact = (value: number) => {
  const abs = Math.abs(value);
  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
  if (abs >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, '')}K`;
  return `${value}`;
};
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`;
};
  return (
    <FunnelChart
      title="Ecommerce checkout conversion"
      subtitle="Drop-off by stage"
      maxWidth={520}
      height={440}
      series={CHECKOUT_FUNNEL}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => compact(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');
        },
      }}
    />
  );
}
```

### Hiring Funnel Role Family
ID: `FunnelChart.hiring-funnel-role-family` • Category: charts

```tsx
const compact = (value: number) => {
  const abs = Math.abs(value);
  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
  if (abs >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, '')}K`;
  return `${value}`;
};
const findSeriesContext = (step: unknown) => STEP_LOOKUP.get(step as any) ?? null;
  return (
    <FunnelChart
      title="Hiring funnel — Staff engineer"
      subtitle="External candidates vs. internal transfers"
      maxWidth={620}
      height={480}
      series={HIRING_SERIES}
      layout={{
        shape: 'bar',
        gap: 10,
        align: 'center',
        showConversion: false,
        seriesMode: 'grouped',
        connectors: { show: false },
      }}
      valueFormatter={(value) => compact(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');
        },
      }}
    />
  );
}
```

### Incident Response Workflow
ID: `FunnelChart.incident-response-workflow` • Category: charts

```tsx
const compact = (value: number) => {
  const abs = Math.abs(value);
  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
  if (abs >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, '')}K`;
  return `${value}`;
};
  return (
    <FunnelChart
      title="Incident response workflow"
      subtitle="Volume flowing through each stage"
      maxWidth={520}
      height={460}
      series={INCIDENT_RESPONSE}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => compact(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');
        },
      }}
    />
  );
}
```

### Saas Trial Conversion
ID: `FunnelChart.saas-trial-conversion` • Category: charts

```tsx
const compact = (value: number) => {
  const abs = Math.abs(value);
  if (abs >= 1_000_000) return `${(value / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
  if (abs >= 1_000) return `${(value / 1_000).toFixed(1).replace(/\.0$/, '')}K`;
  return `${value}`;
};
  return (
    <FunnelChart
      title="SaaS trial-to-paid conversion"
      subtitle="Retention from sign-up to paid"
      maxWidth={520}
      height={440}
      series={TRIAL_CONVERSION}
      layout={{
        shape: 'trapezoid',
        gap: 8,
        align: 'center',
        showConversion: false,
        connectors: { show: false },
      }}
      valueFormatter={(value) => compact(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');
        },
      }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/GaugeChart.md -->

# GaugeChart

Visualises progress toward a bounded target using a semicircular gauge with configurable ranges, ticks, labels, and animated needle. Ported from the UI Gauge component to the charts package so it can slot into chart demos, interaction providers, and theming helpers.

The chart also supports `markers` for spotlighting thresholds (for example SLO limits or compliance baselines). Markers can render as secondary ticks or complementary needles, emit focus callbacks, and feed into the legend so demos can narrate multiple guardrails on the same gauge.

Additional niceties include gradient range fills, `innerRadiusRatio` for donut style layouts, and interaction hooks (`onValueChange`, `onMarkerFocus`) so dashboards can synchronise copy or annotations as the gauge updates.

## Metadata

- Canonical name: `GaugeChart`
- Package: `@platform-blocks/charts`
- Import: `import { GaugeChart } from '@platform-blocks/charts';`
- Category: charts
- Docs: https://react-ui-library.com/components/GaugeChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/GaugeChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | number | Yes |  | Current value |
| `min` | number | No | 0 | Minimum value |
| `max` | number | No | 100 | Maximum value |
| `startAngle` | number | No |  | Gauge start angle (degrees, 0 = top) |
| `endAngle` | number | No | 135 | Gauge end angle (degrees, 0 = top) |
| `rotationOffset` | number | No | 0 | Rotation offset applied to the entire gauge |
| `thickness` | number | No | 12 | Base arc thickness |
| `innerRadiusRatio` | number | No |  | Ratio of inner radius to outer radius when rendering donut style gauges |
| `track` | GaugeChartTrackConfig | No |  | Track configuration |
| `ranges` | GaugeChartRange[] | No | [] | Value ranges displayed on the gauge |
| `ticks` | GaugeChartTickConfig | No |  | Tick configuration |
| `labels` | GaugeChartLabelConfig | No |  | Label configuration |
| `needle` | GaugeChartNeedleConfig | No |  | Needle configuration |
| `centerLabel` | GaugeChartCenterLabelConfig | No |  | Center label configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `markers` | GaugeChartMarker[] | No |  | Discrete markers rendered along the gauge arc |
| `markerFocusStrategy` | 'closest' \| 'leading' | No | 'closest' | Strategy used to decide which marker is considered focused |
| `markerFocusThreshold` | number | No |  | Threshold in value units before switching focus when using the closest strategy |
| `valueFormatter` | (value: number, percentage: number) => string | No |  | Optional formatted output for external display |
| `onValueChange` | (value: number, percentage: number, previousValue: number) => void | No |  | Fired when the gauge value updates |
| `onMarkerFocus` | (marker: GaugeChartMarker \| null) => void | No |  | Fired when the active marker changes |
| `width` | number | No | 320 | 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. |
| `height` | number | No | 240 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 600 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `GaugeChart.basic` • Category: charts

```tsx
return (
    <GaugeChart
      title="System Health"
      subtitle="Live CPU utilisation"
      maxWidth={320}
      height={240}
      value={68}
      min={0}
      max={100}
      thickness={16}
      track={{ opacity: 0.2 }}
      ranges={RANGES}
      ticks={{ major: 5, minor: 4, color: '#94A3B8' }}
      labels={{ formatter: (v) => `${Math.round(v)}%`, offset: 26 }}
      needle={{ length: 0.85, centerSize: 6, showCenter: true }}
      centerLabel={{ show: true, formatter: (val) => `${Math.round(val)}%`, secondaryText: (_, pct) => `${Math.round(pct * 100)}% of max` }}
      legend={{ show: true, position: 'bottom' }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/GroupedBarChart.md -->

# Grouped Bar Chart

Bar chart grouping multiple series side-by-side for comparison.

## Metadata

- Canonical name: `GroupedBarChart`
- Package: `@platform-blocks/charts`
- Import: `import { GroupedBarChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, bar, grouped
- Docs: https://react-ui-library.com/components/GroupedBarChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/GroupedBarChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | StackedBarSeries[] | Yes |  | Grouped series data to render |
| `barSpacing` | number | No | 0.2 | Gap between grouped categories |
| `innerBarSpacing` | number | No | 0.1 | Gap between bars inside a group |
| `legend` | ChartLegend | No | { show: true, position: 'bottom', align: 'center' } | Legend configuration |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `colorOptions` | GroupedBarColorOptions | No |  | Palette and hashing options for bar colors |
| `valueLabels` | GroupedBarValueLabelConfig | No |  | Optional bar value label configuration |
| `multiTooltip` | boolean | No |  | Enable multi-series aggregated tooltip content |
| `liveTooltip` | boolean | No |  | Keep tooltip visible while pointer moves within chart |
| `enableCrosshair` | boolean | No |  | Toggle crosshair overlay and events (defaults to enabled) |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `GroupedBarChart.basic` • Category: charts

```tsx
return (
		<GroupedBarChart
			title="Product revenue by segment"
			subtitle="Comparison vs targets"
			height={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 }}
		/>
	);
}
```

### Experiment Variant By Geo
ID: `GroupedBarChart.experiment-variant-by-geo` • Category: charts

```tsx
return (
    <GroupedBarChart
      title="Experiment conversion uplift by region"
      subtitle="Completed purchases per 100 sessions"
      height={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 }}
    />
  );
}
```

### Feature Usage By Platform
ID: `GroupedBarChart.feature-usage-by-platform` • Category: charts

```tsx
return (
    <GroupedBarChart
      title="Feature usage by platform"
      subtitle="Weekly active users per capability (in thousands)"
      height={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 }}
    />
  );
}
```

### Sales Pipeline By Industry
ID: `GroupedBarChart.sales-pipeline-by-industry` • Category: charts

```tsx
return (
    <GroupedBarChart
      title="Sales pipeline by industry"
      subtitle="Qualified pipeline this quarter (USD millions)"
      height={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 }}
    />
  );
}
```

### Student Assessment By Grade
ID: `GroupedBarChart.student-assessment-by-grade` • Category: charts

```tsx
return (
    <GroupedBarChart
      title="Assessment results by grade level"
      subtitle="Spring benchmark proficiency rates"
      height={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 }}
    />
  );
}
```

### Supplier On Time By Partner
ID: `GroupedBarChart.supplier-on-time-by-partner` • Category: charts

```tsx
return (
    <GroupedBarChart
      title="On-time delivery by logistics partner"
      subtitle="Share of shipments delivered within committed window"
      height={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 }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/HeatmapChart.md -->

# Heatmap Chart

Color-coded matrix for intensity visualization across two dimensions.

## Metadata

- Canonical name: `HeatmapChart`
- Package: `@platform-blocks/charts`
- Import: `import { HeatmapChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, heatmap, matrix
- Docs: https://react-ui-library.com/components/HeatmapChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/HeatmapChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | HeatmapCell[] \| HeatmapMatrixInput | Yes |  | Heatmap data points or matrix-style input |
| `colorScale` | HeatmapColorScaleConfig | No |  | Color scale configuration |
| `cellSize` | HeatmapCellSize | No |  | Explicit cell size overrides |
| `gap` | number | No | 2 | Gap between cells in pixels |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `legend` | ChartLegend | No |  | Legend configuration (often used for color scales) |
| `tooltip` | ChartTooltip<HeatmapCell> \| HeatmapTooltipOptions | No |  | Tooltip configuration or simplified toggle |
| `enableCrosshair` | boolean | No | true | Highlight row/column under the cursor |
| `multiTooltip` | boolean | No | true | Enable aggregated tooltip for multiple cells |
| `liveTooltip` | boolean | No | false | Keep tooltip following the pointer |
| `annotations` | any[] | No |  | Additional annotations to display |
| `maxAnimatedCells` | number | No | 400 | Maximum number of cells to animate before switching to fast static rendering |
| `disableAnimation` | boolean | No | false | When true, force fast static rendering (no per-cell animation) |
| `showCellLabels` | boolean \| HeatmapCellVisibilityPredicate \| HeatmapLabelDisplayRule | No |  | Control whether cell labels render |
| `valueFormatter` | HeatmapValueFormatter \| HeatmapValueFormatPreset \| { preset: HeatmapValueFormatPreset; decimals?: number; suffix?: string } | No |  | Custom formatter for cell labels and tooltip values |
| `cellCornerRadius` | number | No | 2 | Corner radius applied to heatmap cells |
| `hoverHighlight` | HeatmapHoverHighlightConfig | No |  | Customize hover highlight overlays |
| `gradientLegend` | HeatmapGradientLegendConfig | No |  | Enable and customize gradient legend display |
| `accessibilityTable` | HeatmapAccessibilityTableOptions | No |  | Render hidden accessible table representation |
| `onDataTable` | (payload: HeatmapDataTablePayload) => void | No |  | Callback invoked with flattened data table payload |
| `width` | number | No | 420 | 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. |
| `height` | number | No | 320 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic Heatmap
ID: `HeatmapChart.basic` • Category: charts

```tsx
return (
    <HeatmapChart
      title="Support ticket load"
      subtitle="Average tickets per hour"
      height={320}
      data={{ rows: SESSIONS, cols: DAYS, values: UTILIZATION }}
      cellSize={{ width: 48, height: 44 }}
      gap={4}
      colorScale={{
        min: 0,
        max: 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 }}
    />
  );
}
```

### GitHub Contributions
ID: `HeatmapChart.contributions` • Category: charts

GitHub-style contribution calendar generated with a 7x53 grid (weeks x weekdays) and a 5-step color scale.

```tsx
return (
    <HeatmapChart
      title="Weekly contributions"
      subtitle="GitHub-style activity calendar"
      height={280}
      data={{ rows: WEEKDAY_LABELS, cols: COLUMNS, values: CONTRIBUTION_MATRIX }}
      cellSize={{ width: 12, height: 12 }}
      gap={2}
      colorScale={{ min: 0, max: 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 }}
    />
  );
}
```

### Employee Engagement Scores
ID: `HeatmapChart.employee-engagement-scores` • Category: charts

Visualizes employee engagement survey scores per team across key dimensions to spotlight strengths and low-score focus areas.

```tsx
return (
    <HeatmapChart
      title="Employee engagement survey"
      subtitle="Dimension scores (1-5) by team"
      height={360}
      data={{ rows: TEAMS, cols: DIMENSIONS, values: SCORES }}
      cellSize={{ width: 96, height: 48 }}
      gap={4}
      colorScale={{
        min: 1,
        max: 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 }}
    />
  );
}
```

### Infrastructure Cpu Utilization
ID: `HeatmapChart.infrastructure-cpu-utilization` • Category: charts

Heatmap of average CPU utilization across infrastructure clusters and daily time blocks, highlighting hotspots that approach saturation bands.

```tsx
return (
    <HeatmapChart
      title="Infrastructure CPU utilization"
      subtitle="Average utilization (%) across compute clusters"
      height={360}
      data={{ rows: CLUSTERS, cols: TIME_BLOCKS, values: CPU_UTILIZATION }}
      cellSize={{ width: 90, height: 44 }}
      gap={6}
      colorScale={{
        min: 0,
        max: 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 }}
    />
  );
}
```

### Marketing Email Performance
ID: `HeatmapChart.marketing-email-performance` • Category: charts

Tracks marketing email click-through rates by segment and day of week to quickly surface best-performing send windows.

```tsx
return (
    <HeatmapChart
      title="Email click-through performance"
      subtitle="Daily CTR (%) across audience segments"
      height={320}
      data={{ rows: SEGMENTS, cols: DAYS, values: CLICK_RATES }}
      cellSize={{ width: 80, height: 44 }}
      gap={4}
      colorScale={{
        min: 10,
        max: 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 }}
    />
  );
}
```

### Quality Assurance Pass Rates
ID: `HeatmapChart.quality-assurance-pass-rates` • Category: charts

Shows quality assurance pass rates for each regression suite across release candidates, emphasizing areas that fall below the team’s quality threshold.

```tsx
return (
    <HeatmapChart
      title="QA pass rates by release"
      subtitle="Regression suites vs. release candidates"
      height={340}
      data={{ rows: SUITES, cols: RELEASES, values: PASS_RATES }}
      cellSize={{ width: 110, height: 48 }}
      gap={4}
      colorScale={{
        min: 80,
        max: 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 }}
    />
  );
}
```

### Support Backlog Priority
ID: `HeatmapChart.support-backlog-priority` • Category: charts

Maps support ticket backlog volume across product modules and priority levels to expose severity hot spots.

```tsx
return (
    <HeatmapChart
      title="Support backlog by module"
      subtitle="Open tickets by severity priority"
      height={360}
      data={{ rows: MODULES, cols: PRIORITIES, values: BACKLOG }}
      cellSize={{ width: 108, height: 48 }}
      gap={6}
      colorScale={{
        type: 'log',
        min: 1,
        max: 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 }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/HistogramChart.md -->

# Histogram Chart

Distribution of continuous data split into bins.

## Interaction highlights

- Emits `HistogramBinSummary` via `onBinFocus` / `onBinBlur` so external UI can react to the active bin.
- Pointer metadata now includes cumulative counts, density ratios, and percentile—ideal for shared popovers.

## Metadata

- Canonical name: `HistogramChart`
- Package: `@platform-blocks/charts`
- Import: `import { HistogramChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, histogram, distribution
- Docs: https://react-ui-library.com/components/HistogramChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/HistogramChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | number[] | Yes |  | Raw values used to build the histogram |
| `bins` | number | No |  | Explicit number of bins (overrides method) |
| `binMethod` | 'sturges' \| 'sqrt' \| 'fd' | No | 'sturges' | Bin selection heuristic |
| `showDensity` | boolean | No | true | Show density (KDE) overlay line |
| `bandwidth` | number | No |  | Gaussian kernel bandwidth (auto if not provided) |
| `density` | boolean | No | true | Normalize histogram to probability density (area=1) |
| `barColor` | string | No |  | Color for bars |
| `barOpacity` | number | No | 0.8 | Opacity for bars (0-1) |
| `densityColor` | string | No | '#ef4444' | Density line color |
| `densityThickness` | number | No | 2 | Density line thickness |
| `barRadius` | number | No | 2 | Rounded bar corners |
| `barGap` | number | No | 0.08 | Gap ratio between bars (0-1) |
| `multiTooltip` | boolean | No | true | Enable multi-series tooltip aggregation |
| `liveTooltip` | boolean | No | true | Keep tooltip following the pointer |
| `enableCrosshair` | boolean | No | true | Enable crosshair indicator |
| `tooltip` | ChartTooltip<HistogramBin> | No |  | Tooltip configuration |
| `valueFormatter` | (count: number, bin: HistogramBin) => string | No |  | Custom value formatter for tooltips |
| `xAxis` | ChartAxis | No |  | Customise X axis presentation |
| `yAxis` | ChartAxis | No |  | Customise Y axis presentation |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `annotations` | ChartAnnotation[] | No |  | Render annotation markers (thresholds, targets) |
| `rangeHighlights` | Array<{ id: string \| number; start: number; end: number; color?: string; opacity?: number; }> | No |  | Highlight value ranges with background fills |
| `onBinFocus` | (bin: HistogramBinSummary) => void | No |  | Called whenever the active bin under the pointer changes |
| `onBinBlur` | (bin: HistogramBinSummary \| null) => void | No |  | Called when focus leaves the current bin |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 260 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `HistogramChart.basic` • Category: charts

```tsx
return (
		<HistogramChart
			title="Session duration distribution"
			subtitle="Product analytics cohort"
			height={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
		/>
	);
}
```

### Contract Length Retention
ID: `HistogramChart.contract-length-retention` • Category: charts

```tsx
return (
    <HistogramChart
      title="Customer contract length distribution"
      subtitle="Used to calibrate retention and renewal strategy"
      height={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`}
    />
  );
}
```

### Employee Tenure Distribution
ID: `HistogramChart.employee-tenure-distribution` • Category: charts

```tsx
return (
    <HistogramChart
      title="Employee tenure distribution"
      subtitle="Helps spot retention risks and succession depth"
      height={320}
      data={TENURE_YEARS}
      bins={12}
      binMethod="sqrt"
      showDensity
      densityThickness={2.5}
      densityColor="#22C55E"
      barOpacity={0.8}
      rangeHighlights={[
        { id: 'new-hires', start: 0, end: 1.5, color: '#FACC15', opacity: 0.18 },
        { id: 'veterans', start: 8, end: 15, color: '#22C55E', opacity: 0.12 },
      ]}
      annotations={[
        {
          id: 'median-tenure',
          shape: 'vertical-line',
          x: Number(medianTenure.toFixed(2)),
          color: '#F97316',
          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)}`}
    />
  );
}
```

### Page Load Performance
ID: `HistogramChart.page-load-performance` • Category: charts

```tsx
const [focusedBin, setFocusedBin] = useState<HistogramBinSummary | null>(null);
  return (
  <View>
      <HistogramChart
        title="Page load time distribution"
        subtitle="Week after performance optimization rollout"
        height={340}
        data={LOAD_TIMES}
        bins={14}
        binMethod="fd"
        showDensity
        densityThickness={3}
        barOpacity={0.78}
        densityColor="#12B886"
        rangeHighlights={[{ id: 'slo-window', start: 0, end: SLO_TARGET, color: '#38BDF8', opacity: 0.12 }]}
        annotations={[
          {
            id: 'slo-target',
            shape: 'vertical-line',
            x: SLO_TARGET,
            color: '#0EA5E9',
            label: 'SLO 2.5s',
          },
          {
            id: 'avg-load',
            shape: 'vertical-line',
            x: Number(AVERAGE_LOAD.toFixed(2)),
            color: '#F97316',
            label: `Avg ${AVERAGE_LOAD.toFixed(2)}s`,
          },
        ]}
        xAxis={{
          title: 'Page load time (seconds)',
          labelFormatter: (value) => `${value.toFixed(1)}s`,
        }}
        yAxis={{
          title: 'Probability density',
          labelFormatter: (value) => value.toFixed(2),
        }}
        grid={{ show: true }}
        tooltip={{
          show: true,
          formatter: (bin) => `${bin.count} page views between ${bin.start.toFixed(1)}–${bin.end.toFixed(1)}s`,
        }}
        valueFormatter={(count, bin) => `${count} views · pdf ${bin.density.toFixed(3)}`}
        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>
  );
}
```

### Sensor Battery Upgrade
ID: `HistogramChart.sensor-battery-upgrade` • Category: charts

```tsx
return (
    <HistogramChart
      title="Sensor battery voltage after firmware upgrade"
      subtitle="Monitoring pack health across deployed field units"
      height={320}
      data={BATTERY_VOLTAGES}
      bins={12}
      binMethod="sturges"
      showDensity
      densityThickness={2.8}
      densityColor="#34D399"
      barOpacity={0.78}
      rangeHighlights={[
        { id: 'low-voltage', start: 3.0, end: REPLACEMENT_THRESHOLD, color: '#EF4444', opacity: 0.14 },
        { id: 'target-band', start: TARGET_VOLTAGE, end: 4.1, color: '#22C55E', opacity: 0.12 },
      ]}
      annotations={[
        {
          id: 'replacement-line',
          shape: 'vertical-line',
          x: REPLACEMENT_THRESHOLD,
          color: '#DC2626',
          label: 'Replace below 3.5V',
        },
        {
          id: 'target-line',
          shape: 'vertical-line',
          x: TARGET_VOLTAGE,
          color: '#16A34A',
          label: 'Target 3.9V+',
        },
      ]}
      xAxis={{
        title: 'Voltage (V)',
        labelFormatter: (value) => `${value.toFixed(2)}V`,
      }}
      yAxis={{
        title: 'Probability density',
        labelFormatter: (value) => value.toFixed(2),
      }}
      grid={{ show: true }}
      tooltip={{
        show: true,
        formatter: (bin) => `${bin.count} sensors between ${bin.start.toFixed(2)}–${bin.end.toFixed(2)}V`,
      }}
      valueFormatter={(count, bin) => `${count} sensors · pdf ${bin.density.toFixed(3)}`}
    />
  );
}
```

### Transaction Amount Fraud
ID: `HistogramChart.transaction-amount-fraud` • Category: charts

```tsx
return (
    <HistogramChart
      title="Transaction amount distribution"
      subtitle="Identifying anomalous high-value purchases"
      height={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)}`}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/LineChart.md -->

# Line Chart

Basic line chart visualization component.

## Metadata

- Canonical name: `LineChart`
- Package: `@platform-blocks/charts`
- Import: `import { LineChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, line, timeseries
- Docs: https://react-ui-library.com/components/LineChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/LineChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | ChartDataPoint[] | No |  | Data points (single series) or array of series (multiseries) |
| `series` | LineChartSeries[] | No |  | Multiple data series |
| `lineColor` | string | No |  | Line color (for single series) |
| `lineThickness` | number | No | 2 | Line thickness (for single series) |
| `lineStyle` | 'solid' \| 'dashed' \| 'dotted' | No | 'solid' | Line style (for single series) |
| `showPoints` | boolean | No | true | Show data points (for single series) |
| `pointSize` | number | No | 4 | Point size (for single series) |
| `pointColor` | string | No |  | Point color (for single series) |
| `smooth` | boolean | No | false | Smooth curve |
| `fill` | boolean | No | false | Fill area under line |
| `fillColor` | string | No |  | Fill color |
| `fillOpacity` | number | No | 0.3 | Fill opacity |
| `areaFillMode` | 'single' \| 'series' | No | 'single' | How to distribute fill across series when multiple are present |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<ChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `enableCrosshair` | boolean | No |  | Show a vertical crosshair that follows the nearest point |
| `enableSeriesToggle` | boolean | No |  | Enable toggling series visibility from legend |
| `liveTooltip` | boolean | No |  | Update tooltip continuously while moving (not just on press) |
| `multiTooltip` | boolean | No |  | Show multi-series aggregated tooltip aligned to crosshair |
| `enablePanZoom` | boolean | No |  | Enable pan and pinch zoom interactions |
| `zoomMode` | 'x' \| 'y' \| 'both' | No |  | Which axes can zoom |
| `minZoom` | number | No |  | Minimum zoom factor relative to original domain (e.g. 0.1 = 10%) |
| `onDomainChange` | (xDomain: [number, number], yDomain: [number, number]) => void | No |  | Callback when visible data domain changes |
| `enableWheelZoom` | boolean | No |  | Enable wheel zoom on web |
| `wheelZoomStep` | number | No |  | Wheel zoom step factor (default 0.1) |
| `invertWheelZoom` | boolean | No |  | Invert wheel zoom direction |
| `resetOnDoubleTap` | boolean | No |  | Double-tap (or double-click on web) resets zoom |
| `clampToInitialDomain` | boolean | No |  | Clamp pan/zoom so domains never exceed original data bounds |
| `invertPinchZoom` | boolean | No |  | Invert pinch gesture direction (scale grows when fingers move closer) |
| `disableAnimations` | boolean | No |  | Disable all Reanimated-driven animations (debug / perf fallback) |
| `decimationThreshold` | number | No |  | Apply LTOB data decimation above this point count |
| `xScaleType` | 'linear' \| 'log' \| 'time' | No |  | X axis scale type |
| `yScaleType` | 'linear' \| 'log' \| 'time' | No |  | Y axis scale type |
| `enableBrushZoom` | boolean | No |  | Enable shift+drag brush to zoom (web) |
| `annotations` | ChartAnnotation[] | No |  | Optional chart annotations/markers |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 1000 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `LineChart.basic` • Category: charts

Simple random data line chart with title.

```tsx
return (
    <LineChart
      title="Monthly active customers"
      subtitle="FY25"
      height={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}
    />
  );
}
```

### Smooth Area
ID: `LineChart.smooth-area` • Category: charts

Smoothed dual-series line chart with gradient fill and custom legend.

```tsx
return (
    <LineChart
      title="Revenue trajectory"
      subtitle="Smoothed forecast vs. actuals"
      height={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],
        },
      ]}
    />
  );
}
```

### Time Series
ID: `LineChart.time-series` • Category: charts

Time-series interaction example with brush zoom and custom tooltip formatting.

```tsx
return (
    <LineChart
      title="Web analytics"
      subtitle="Sessions and goals over time"
      height={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)',
        },
      ]}
    />
  );
}
```

### Zoom & pan
ID: `LineChart.zoom` • Tags: zoom, pan, wheel, brush, interaction • Category: charts • Status: stable • Since: 1.0.0

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
return (
    <LineChart
      title="Product engagement"
      subtitle="Scroll to zoom · drag to pan · Shift-drag to box-zoom · double-click to reset"
      height={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}
    />
  );
}
```

### Arr Progress Forecast
ID: `LineChart.arr-progress-forecast` • Category: charts

**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
return (
    <LineChart
      title="ARR Progression vs. Forecast"
      subtitle="GTM regions actualized ARR with forward-looking plans"
      height={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
    />
  );
}
```

### Cohort Retention Curves
ID: `LineChart.cohort-retention-curves` • Category: charts

**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
return (
    <LineChart
      title="Cohort Retention Across Milestones"
      subtitle="Weekly retention milestones by signup quarter"
      height={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
    />
  );
}
```

### Energy Consumption Portfolio
ID: `LineChart.energy-consumption-portfolio` • Category: charts

**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
return (
    <LineChart
      title="Energy Consumption Across Office Portfolio"
      subtitle="Monthly MWh usage benchmarking against 360 MWh target"
      height={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
    />
  );
}
```

### Incident Volume Moving Average
ID: `LineChart.incident-volume-moving-average` • Category: charts

**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
return (
    <LineChart
      title="Incident Volume with Moving Averages"
      subtitle="SRE daily incident intake and trailing trends"
      height={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
    />
  );
}
```

### Nps Trend Release Markers
ID: `LineChart.nps-trend-release-markers` • Category: charts

**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
return (
    <LineChart
      title="NPS Trend with Product Releases"
      subtitle="Quarterly sentiment lift alongside major launches"
      height={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
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/MarimekkoChart.md -->

# Marimekko Chart

Visualize categorical mix alongside overall weight with a mosaic-style variable-width column chart.

## Metadata

- Canonical name: `MarimekkoChart`
- Package: `@platform-blocks/charts`
- Import: `import { MarimekkoChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, marimekko, mosaic
- Docs: https://react-ui-library.com/components/MarimekkoChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/MarimekkoChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | MarimekkoCategory[] | Yes |  | Categories rendered as variable-width columns. |
| `legend` | ChartLegend | No |  | Optional legend configuration. |
| `xAxis` | ChartAxis | No |  | Optional x-axis configuration. |
| `yAxis` | ChartAxis | No |  | Optional y-axis configuration (defaults to percentage scale). |
| `grid` | ChartGrid | No |  | Grid configuration applied to the background. |
| `columnGap` | number | No | 12 | Gap (in pixels) inserted between columns. |
| `segmentBorderRadius` | number | No | 2 | Corner radius applied to each segment rectangle. |
| `padding` | { top: number; right: number; bottom: number; left: number } | No |  | Override padding around the chart plot area. |
| `categoryLabelFormatter` | (category: MarimekkoCategory, index: number) => string | No |  | Formatter applied to categorical labels along the x-axis. |
| `width` | number | No | 640 | 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. |
| `height` | number | No | 400 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | DEFAULT_ANIMATION_DURATION | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `MarimekkoChart.basic` • Category: charts

Variable-width columns reveal how each pipeline channel and region contributes to total qualified pipeline.

```tsx
return (
    <MarimekkoChart
      title="Pipeline contribution by segment"
      subtitle="Quarter to date"
      height={440}
      data={PIPELINE_COMPOSITION}
      columnGap={16}
      legend={{ show: true, position: 'bottom' }}
      yAxis={{ title: 'Segment share (%)' }}
      grid={{ show: true, style: 'dotted' }}
      categoryLabelFormatter={(category) => category.label}
    />
  );
}
```

### Budget Allocation
ID: `MarimekkoChart.budget-allocation` • Category: charts

Lay out the company plan to see both department budgets and how each team invests within their allocation.

```tsx
return (
    <MarimekkoChart
      title="FY26 budget allocation"
      subtitle="Percentage of total discretionary spend"
      height={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)}%)`}
    />
  );
}
```

### Product Portfolio
ID: `MarimekkoChart.product-portfolio` • Category: charts

Compare how revenue mixes across product tiers and sales motions within a single view.

```tsx
return (
    <MarimekkoChart
      title="ARR by product tier and motion"
      subtitle="Current quarter"
      height={460}
      data={PRODUCT_MIX}
      segmentBorderRadius={4}
      legend={{ show: true, position: 'right' }}
      yAxis={{ title: 'Revenue share (%)' }}
      categoryLabelFormatter={(category) => `${category.label}\n(${category.data?.region ?? 'Global'})`}
    />
  );
}
```

### Regional Mix
ID: `MarimekkoChart.regional-mix` • Category: charts

Explore regional totals and the mix of revenue streams side by side.

```tsx
return (
    <MarimekkoChart
      title="Revenue mix by region"
      subtitle="Trailing twelve months"
      height={440}
      data={REGIONAL_REVENUE}
      columnGap={20}
      legend={{ show: true, position: 'bottom', align: 'start' }}
      grid={{ show: true, style: 'dotted' }}
      yAxis={{ title: 'Share within region (%)' }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/NetworkChart.md -->

# Network Chart

Graph structure visualization (nodes & links) for relationships.

### Highlights
- Force, coordinate, circular, or radial layouts with optional axis/grid controls.
- Scale node radius by value or custom accessor via `nodeRadiusRange` and `nodeValueAccessor`.
- Style links dynamically with `linkWidthRange`, curved or straight `linkShape`, palette fallbacks, and opacity/width accessors.
- Hook into `onNodeFocus` / `onLinkFocus` to drive tooltips or external panels without forking the component.

## Metadata

- Canonical name: `NetworkChart`
- Package: `@platform-blocks/charts`
- Import: `import { NetworkChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, network, graph
- Docs: https://react-ui-library.com/components/NetworkChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/NetworkChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `nodes` | NetworkNode[] | Yes |  | Nodes to render in the network |
| `links` | NetworkLink[] | Yes |  | Links connecting the nodes |
| `layout` | NetworkLayoutMode | No | 'force' | Layout engine mode |
| `grid` | ChartGrid \| boolean | No |  | Optional grid configuration for coordinate layouts |
| `xAxis` | ChartAxis | No |  | X axis configuration when using coordinate layouts |
| `yAxis` | ChartAxis | No |  | Y axis configuration when using coordinate layouts |
| `padding` | Partial<{ top: number; right: number; bottom: number; left: number }> | No |  | Optional padding overrides |
| `coordinateAccessor` | { x?: (node: NetworkNode, index: number) => number; y?: (node: NetworkNode, index: number) => number; } | No |  | Accessor overrides for coordinate layouts |
| `showLabels` | boolean | No | true | Show node labels |
| `nodeRadius` | number | No | 12 | Radius override for nodes |
| `nodeRadiusRange` | [number, number] | No |  | Optional range that scales node radius by node value |
| `nodeValueAccessor` | (node: NetworkNode, index: number) => number | No |  | Optional accessor to extract numeric value for node sizing |
| `linkWidthRange` | [number, number] | No |  | Optional range that maps link weights to stroke width |
| `linkColorAccessor` | (link: NetworkLink, index: number) => string \| undefined | No |  | Accessor for custom link colors |
| `linkOpacityAccessor` | (link: NetworkLink, index: number) => number \| undefined | No |  | Accessor for custom link opacity |
| `linkShape` | NetworkLinkShape | No |  | Link rendering shape |
| `linkCurveStrength` | number | No |  | Curvature strength multiplier when using curved links |
| `linkPalette` | string[] | No |  | Palette used when a link does not provide an explicit color |
| `onNodeFocus` | (event: NetworkNodeInteractionEvent) => void | No |  | Node focus callback for hover/focus interactions |
| `onNodeBlur` | (event: NetworkNodeInteractionEvent) => void | No |  | Node blur callback |
| `onNodePress` | (event: NetworkNodeInteractionEvent) => void | No |  | Node press callback |
| `onLinkFocus` | (event: NetworkLinkInteractionEvent) => void | No |  | Link focus callback for hover/focus interactions |
| `onLinkBlur` | (event: NetworkLinkInteractionEvent) => void | No |  | Link blur callback |
| `onLinkPress` | (event: NetworkLinkInteractionEvent) => void | No |  | Link press callback |
| `width` | number | No | 600 | 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. |
| `height` | number | No | 400 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `NetworkChart.basic` • Category: charts

```tsx
return (
		<NetworkChart
			title="Cross-team collaboration"
			height={420}
			nodes={NODES}
			links={LINKS}
		/>
	);
}
```

### Customer Referral Network
ID: `NetworkChart.customer-referral-network` • Category: charts

```tsx
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;
};
  return (
    <NetworkChart
      title="Customer referral influence network"
      subtitle="Referral pathways by activation wave"
      height={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))}
    />
  );
}
```

### Knowledge Sharing Connections
ID: `NetworkChart.knowledge-sharing-connections` • Category: charts

```tsx
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;
  }
};
  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"
        height={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>
      )}
    </>
  );
}
```

### Microservice Latency
ID: `NetworkChart.microservice-latency` • Category: charts

```tsx
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;
};
  return (
    <NetworkChart
      title="Microservice latency map"
      subtitle="Edge-to-core call graph with weighted latency"
      height={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))}
    />
  );
}
```

### Risk Propagation
ID: `NetworkChart.risk-propagation` • Category: charts

```tsx
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;
  }
};
  return (
    <NetworkChart
      title="Risk propagation path"
      subtitle="Simulated attack progression across services"
      height={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)}
    />
  );
}
```

### Supply Chain Relationships
ID: `NetworkChart.supply-chain-relationships` • Category: charts

```tsx
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;
  }
};
  return (
    <NetworkChart
      title="Supply chain relationship map"
      subtitle="Tiered flow from suppliers to regional distribution"
      height={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 }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `ParetoChart`
- Package: `@platform-blocks/charts`
- Import: `import { ParetoChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, pareto, quality
- Docs: https://react-ui-library.com/components/ParetoChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/ParetoChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | ParetoChartDatum[] | Yes |  | Raw categories to render inside the Pareto analysis. |
| `sortDirection` | 'desc' \| 'asc' \| 'none' | No | 'desc' | Sorting direction applied before calculating cumulative percentages. |
| `valueSeriesLabel` | string | No | 'Frequency' | Display label for the bar series. |
| `cumulativeSeriesLabel` | string | No | 'Cumulative %' | Display label for the cumulative line series. |
| `barColor` | string | No |  | Base color used for the bar series when data points do not provide one. |
| `lineColor` | string | No |  | Base color used for the cumulative line series. |
| `categoryLabelFormatter` | (category: string, index: number) => string | No |  | Optional formatter applied to the categorical axis labels. |
| `enableCrosshair` | boolean | No |  | Enable crosshair indicator across layers |
| `multiTooltip` | boolean | No |  | Enable multi-series tooltip aggregation |
| `liveTooltip` | boolean | No |  | Follow pointer live with tooltip |
| `xDomain` | [number, number] | No |  | Explicit override for the shared x-domain |
| `yDomain` | [number, number] | No |  | Explicit override for the primary y-domain |
| `yDomainRight` | [number, number] | No |  | Explicit override for the secondary y-domain |
| `xAxis` | ChartAxis | No |  | Axis configuration for the shared x-axis |
| `yAxis` | ChartAxis | No |  | Axis configuration for the primary y-axis |
| `yAxisRight` | ChartAxis | No |  | Axis configuration for the secondary y-axis |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `legend` | ChartLegend | No |  | Legend display options |
| `width` | number | No | 640 | 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. |
| `height` | number | No | 360 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `ParetoChart.basic` • Category: charts

Simple Pareto chart showing how cumulative contribution highlights the dominant defect categories.

```tsx
return (
    <ParetoChart
      title="Monthly defect analysis"
      subtitle="Product QA triage"
      height={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' }}
    />
  );
}
```

### Customer Support Hotspots
ID: `ParetoChart.customer-support-hotspots` • Category: charts

Highlight how a handful of ticket categories drive the majority of support backlog volume.

```tsx
return (
    <ParetoChart
      title="Support backlog concentration"
      subtitle="Top ten case drivers this quarter"
      height={440}
      data={SUPPORT_CASES}
      valueSeriesLabel="Cases"
      cumulativeSeriesLabel="Cumulative ticket share"
      yAxis={{ title: 'Case volume' }}
      yAxisRight={{ title: 'Cumulative share' }}
    />
  );
}
```

### Incident Root Causes
ID: `ParetoChart.incident-root-causes` • Category: charts

Root-cause analysis illustrating which failure modes dominate incident volume.

```tsx
return (
    <ParetoChart
      title="Incident root causes"
      subtitle="Rolling twelve months"
      height={420}
      data={POSTMORTEM_CAUSES}
      valueSeriesLabel="Incidents"
      cumulativeSeriesLabel="Cumulative impact"
      sortDirection="none"
      categoryLabelFormatter={(label) => label.replace(' ', '\n')}
      legend={{ show: true, position: 'right' }}
    />
  );
}
```

### Revenue Concentration
ID: `ParetoChart.revenue-concentration` • Category: charts

Examine how a few strategic accounts make up the bulk of recurring revenue.

```tsx
return (
    <ParetoChart
      title="Annual revenue concentration"
      subtitle="Top enterprise accounts"
      height={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',
      }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/PieChart.md -->

# Pie Chart

Proportional slice chart for categorical part-to-whole representation.

## Metadata

- Canonical name: `PieChart`
- Package: `@platform-blocks/charts`
- Import: `import { PieChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, pie, categorical
- Docs: https://react-ui-library.com/components/PieChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/PieChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | PieChartDataPoint[] | Yes |  | Data points |
| `innerRadius` | number | No |  | Inner radius (for donut chart) |
| `outerRadius` | number | No |  | Outer radius |
| `startAngle` | number | No |  | Start angle in degrees |
| `endAngle` | number | No |  | End angle in degrees |
| `padAngle` | number | No |  | Padding between slices |
| `showLabels` | boolean | No |  | Show labels |
| `labelPosition` | 'inside' \| 'outside' \| 'center' | No |  | Label position |
| `labelStrategy` | 'auto' \| 'inside' \| 'outside' \| 'center' | No |  | Automatically choose label placement |
| `labelAutoSwitchAngle` | number | No |  | Minimum slice angle (deg) to keep label inside when strategy is auto |
| `wrapLabels` | boolean | No |  | Automatically wrap labels that exceed width |
| `labelMaxCharsPerLine` | number | No |  | Maximum characters per label line when wrapping |
| `labelMaxLines` | number | No |  | Maximum number of lines when wrapping |
| `showLeaderLines` | boolean | No |  | Render leader lines for outside labels |
| `leaderLineColor` | string | No |  | Leader line stroke color |
| `leaderLineWidth` | number | No |  | Leader line stroke width |
| `labelTextStyle` | PieChartLabelTextStyle | No |  | Style overrides applied to rendered labels |
| `labelFormatter` | (dataPoint: PieChartDataPoint) => string | No |  | Label formatter |
| `showValues` | boolean | No |  | Show values |
| `valueFormatter` | (value: number, total: number) => string | No |  | Value formatter |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<PieChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `highlightOnHover` | boolean | No |  | Enable hover highlighting |
| `onSliceHover` | (slice: PieChartDataPoint \| null) => void | No |  | Callback when hover target changes |
| `defaultSliceStyle` | PieChartSliceStyle | No |  | Default style applied to slices |
| `layers` | PieChartLayer[] | No |  | Additional rings rendered around the base series |
| `legendToggleEnabled` | boolean | No |  | Allow toggling slice visibility from the legend |
| `keyboardNavigation` | boolean | No |  | Enable keyboard navigation between slices |
| `ariaLabelFormatter` | (slice: PieChartDataPoint, percentage: number) => string | No |  | Accessible label formatter |
| `width` | number | No |  | 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. |
| `height` | number | No |  | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `PieChart.basic` • Category: charts

```tsx
return (
    <PieChart
      title="Traffic sources"
      maxWidth={560}
      height={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}
    />
  );
}
```

### Browser Usage Share
ID: `PieChart.browser-usage-share` • Category: charts

```tsx
const formatLabel = (slice: PieChartDataPoint) => `${slice.label} ${slice.value}%`;
const formatTooltip = (slice: PieChartDataPoint) => `${slice.label}: ${slice.value}% of sessions`;
  return (
    <PieChart
      title="Browser usage share"
      subtitle="Active sessions"
      maxWidth={520}
      height={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}
    />
  );
}
```

### Bug Type Distribution
ID: `PieChart.bug-type-distribution` • Category: charts

```tsx
const formatLabel = (slice: PieChartDataPoint) => `${slice.label} ${slice.value}%`;
const formatTooltip = (slice: PieChartDataPoint) => `${slice.label}: ${slice.value}% of release defects`;
  return (
    <PieChart
      title="Bug type distribution"
      subtitle="Latest release cycle"
      maxWidth={560}
      height={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}
    />
  );
}
```

### Operating Expense Composition
ID: `PieChart.operating-expense-composition` • Category: charts

```tsx
const formatTooltip = (slice: PieChartDataPoint) => {
  const share = Math.round((slice.value / TOTAL_EXPENSE) * 100);
  return `${slice.label}: $${slice.value}M (${share}%)`;
};
  return (
    <PieChart
      title="Operating expense mix"
      subtitle="FY25 year-to-date"
      maxWidth={520}
      height={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}
    />
  );
}
```

### Support Channel Share
ID: `PieChart.support-channel-share` • Category: charts

```tsx
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}%)`;
};
  return (
    <PieChart
      title="Support contact mix"
      subtitle="Last 30 days"
      maxWidth={580}
      height={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}
    />
  );
}
```

### Training Completion Share
ID: `PieChart.training-completion-share` • Category: charts

```tsx
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}%)`;
};
  return (
    <PieChart
      title="Training completion share"
      subtitle="Annual compliance program"
      maxWidth={520}
      height={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}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/RadarChart.md -->

# Radar Chart

Displays multivariate data across axes starting from the same origin.

## Metadata

- Canonical name: `RadarChart`
- Package: `@platform-blocks/charts`
- Import: `import { RadarChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, radar, polar
- Docs: https://react-ui-library.com/components/RadarChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/RadarChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | RadarChartSeries[] | Yes |  | Radar series to display |
| `maxValue` | number | No |  | Maximum value displayed across axes |
| `radialGrid` | RadarGridConfig | No |  | Grid styling configuration |
| `smooth` | boolean \| number | No |  | Smooth the polygon edges; pass a number between 0 and 1 to control tension |
| `fill` | boolean | No | true | Fill the radar area |
| `enableCrosshair` | boolean | No |  | Enable radial crosshair highlights |
| `multiTooltip` | boolean | No |  | Enable multi-series tooltip aggregation |
| `liveTooltip` | boolean | No |  | Follow pointer with tooltip |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<RadarAxisPoint> | No |  | Tooltip configuration |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 400 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Skill Comparison
ID: `RadarChart.skill-comparison` • Category: charts

Comparison of three engineering guilds with polygon grid, crosshair, and aggregated tooltip.

```tsx
return (
    <RadarChart
      title="Engineering guild comparison"
      subtitle="Quarterly capability radar"
      maxWidth={700}
      height={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)}%`,
      }}
    />
  );
}
```

### Product Health
ID: `RadarChart.product-health` • Category: charts

Product health snapshot with circular grid, point markers, and custom tooltip messaging.

```tsx
return (
    <RadarChart
      title="Product health radar"
      subtitle="Operational score vs. strategic goal"
      maxWidth={580}
      height={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`,
      }}
    />
  );
}
```

### Basic
ID: `RadarChart.basic` • Category: charts

```tsx
return (
    <RadarChart
      title="Team capability radar"
      maxWidth={560}
      height={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 Platform Maturity
ID: `RadarChart.data-platform-maturity` • Category: charts

```tsx
return (
    <RadarChart
      title="Data platform maturity"
      subtitle="Governance and enablement dimensions"
      maxWidth={620}
      height={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`,
      }}
    />
  );
}
```

### Engineering Readiness
ID: `RadarChart.engineering-readiness` • Category: charts

```tsx
return (
    <RadarChart
      title="Engineering readiness radar"
      subtitle="Security, reliability, scalability, performance, maintainability"
      maxWidth={600}
      height={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`,
      }}
    />
  );
}
```

### Market Perception Interviews
ID: `RadarChart.market-perception-interviews` • Category: charts

```tsx
return (
    <RadarChart
      title="Market perception signal"
      subtitle="Customer interview scorecard"
      maxWidth={700}
      height={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`,
      }}
    />
  );
}
```

### Product Capability Benchmark
ID: `RadarChart.product-capability-benchmark` • Category: charts

```tsx
return (
    <RadarChart
      title="Product capability vs. competition"
      subtitle="Benchmarking core differentiators"
      maxWidth={620}
      height={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`,
      }}
    />
  );
}
```

### Skills Gap Role Family
ID: `RadarChart.skills-gap-role-family` • Category: charts

```tsx
return (
    <RadarChart
      title="Role family skills gap analysis"
      subtitle="Percent attainment against competency targets"
      maxWidth={720}
      height={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`,
      }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/RadialBarChart.md -->

# Radial Bar Chart

Circular bar segments representing values radially.

## Metadata

- Canonical name: `RadialBarChart`
- Package: `@platform-blocks/charts`
- Import: `import { RadialBarChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, radial, bar
- Docs: https://react-ui-library.com/components/RadialBarChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/RadialBarChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | RadialBarDatum[] | Yes |  | Radial bar data to render |
| `radius` | number | No |  | Radius of outer ring (auto if not provided) |
| `barThickness` | number | No | 14 | Thickness of each arc |
| `gap` | number | No | 8 | Gap (px) between concentric bars |
| `startAngle` | number | No | -90 | Start angle in degrees (default -90 = top) |
| `endAngle` | number | No | 270 | End angle in degrees (default 270 for full circle) |
| `showValueLabels` | boolean | No | true | Show value labels at the tip of each arc |
| `valueFormatter` | (value: number, datum: RadialBarDatum, index: number) => string | No |  | Format value for label |
| `centerLabel` | string | No |  | Primary text rendered in the empty center (e.g. an aggregate value) |
| `centerSubLabel` | string | No |  | Secondary text rendered beneath the center label |
| `multiTooltip` | boolean | No | true | Enable aggregated tooltip across arcs |
| `liveTooltip` | boolean | No | true | Keep tooltip following the pointer |
| `enableCrosshair` | boolean | No | false | Highlight the hovered ring (dim the others) on pointer interaction. Default false. |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<RadialBarDatum> | No |  | Tooltip configuration |
| `width` | number | No | 240 | 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. |
| `height` | number | No | 240 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Multi-Metric KPIs
ID: `RadialBarChart.basic` • Category: charts

Concentric rings compare progress across several metrics, with tip labels and a center average.

```tsx
return (
		<RadialBarChart
			title="Quarterly KPIs"
			subtitle="Progress toward goals"
			maxWidth={400}
			height={400}
			data={METRICS}
			barThickness={18}
			gap={12}
			showValueLabels
			valueFormatter={(value) => `${value}%`}
			centerLabel={`${AVG}%`}
			centerSubLabel="Avg score"
			multiTooltip
			liveTooltip
			legend={{ show: true, position: 'bottom' }}
		/>
	);
}
```

### Goal Progress Ring
ID: `RadialBarChart.goal-progress` • Category: charts

A single thick ring with a center readout — ideal for one headline metric.

```tsx
return (
		<RadialBarChart
			title="Fundraising Goal"
			subtitle="$74k raised of $100k"
			maxWidth={300}
			height={300}
			data={GOAL}
			barThickness={24}
			showValueLabels={false}
			centerLabel="74%"
			centerSubLabel="of goal"
			multiTooltip
			liveTooltip
		/>
	);
}
```

### Semicircle Gauge
ID: `RadialBarChart.satisfaction-gauge` • Category: charts

Set startAngle/endAngle to a 180° sweep for a speedometer-style gauge that fills the space.

```tsx
return (
		<RadialBarChart
			title="Customer Satisfaction"
			subtitle="Rolling 30-day CSAT"
			maxWidth={340}
			height={240}
			startAngle={-90}
			endAngle={90}
			data={SCORE}
			barThickness={24}
			showValueLabels={false}
			centerLabel="82"
			centerSubLabel="out of 100"
			multiTooltip
			liveTooltip
		/>
	);
}
```

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

<!-- source: https://react-ui-library.com/llms/components/RidgeChart.md -->

# Ridge Chart

Layered density plots (joyplot) comparing distributions across categories.

## Metadata

- Canonical name: `RidgeChart`
- Package: `@platform-blocks/charts`
- Import: `import { RidgeChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, ridge, density
- Docs: https://react-ui-library.com/components/RidgeChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/RidgeChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | DensitySeries[] | Yes |  | Density series rendered in the ridge chart |
| `samples` | number | No |  | Density sample resolution |
| `bandwidth` | number | No |  | Kernel bandwidth override |
| `bandPadding` | number | No |  | Fractional padding between ridge bands (0 - 0.8) |
| `amplitudeScale` | number | No |  | Amplitude scaling applied to each ridge (0.1 - 1) |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `statsMarkers` | RidgeStatsMarkersConfig | No |  | Optional statistic marker configuration |
| `width` | number | No |  | 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. |
| `height` | number | No |  | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Api Latency Endpoints
ID: `RidgeChart.api-latency-endpoints` • Category: charts

```tsx
return (
    <RidgeChart
      title="API latency distribution by endpoint"
      subtitle="Density of response times across rolling deployments"
      height={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,
      }}
    />
  );
}
```

### Basic
ID: `RidgeChart.basic` • Category: charts

```tsx
return (
		<RidgeChart
			title="Customer satisfaction distribution"
			subtitle="Annual NPS density"
			height={360}
			series={SERIES}
			samples={96}
			bandwidth={3}
			statsMarkers={{ enabled: true, showP90: true, showLabels: true }}
		/>
	);
}
```

### Daily Active Users Cohorts
ID: `RidgeChart.daily-active-users-cohorts` • Category: charts

```tsx
return (
    <RidgeChart
      title="Daily active users across feature cohorts"
      subtitle="Distribution of session counts over the last six months"
      height={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,
      }}
    />
  );
}
```

### Employee Satisfaction Survey
ID: `RidgeChart.employee-satisfaction-survey` • Category: charts

```tsx
return (
    <RidgeChart
      title="Employee satisfaction score distribution"
      subtitle="Quarterly pulse survey responses by team"
      height={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,
      }}
    />
  );
}
```

### Revenue Transaction Density
ID: `RidgeChart.revenue-transaction-density` • Category: charts

```tsx
return (
    <RidgeChart
      title="Revenue per transaction by product line"
      subtitle="Transaction value distributions across seasonal cycles"
      height={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,
      }}
    />
  );
}
```

### Shipping Time Carriers
ID: `RidgeChart.shipping-time-carriers` • Category: charts

```tsx
return (
    <RidgeChart
      title="Shipping time distribution by carrier"
      subtitle="Parcel delivery performance across recent quarters"
      height={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,
      }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/SankeyChart.md -->

# Sankey Chart

Flow diagram showing volume between nodes.

## Metadata

- Canonical name: `SankeyChart`
- Package: `@platform-blocks/charts`
- Import: `import { SankeyChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, flow, sankey
- Docs: https://react-ui-library.com/components/SankeyChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/SankeyChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `nodes` | SankeyNode[] | Yes |  | Nodes included in the Sankey diagram |
| `links` | SankeyLink[] | Yes |  | Links connecting the nodes |
| `animationDuration` | number | No | 1000 | Animation duration in milliseconds |
| `disabled` | boolean | No | false | Disable animations |
| `nodeWidth` | number | No |  | Fixed node width in pixels (auto-calculated if omitted) |
| `nodePadding` | number | No |  | Vertical gap between nodes (auto-calculated if omitted) |
| `chartPadding` | Partial<Record<'top' \| 'right' \| 'bottom' \| 'left', number>> | No |  | Override chart padding (defaults to 40px all around) |
| `labelFormatter` | (node: SankeyNode) => string | No |  | Format display label for a node |
| `valueFormatter` | (value: number, node: SankeyNode \| undefined) => string | No |  | Format value label for a node |
| `onNodeHover` | (node: SankeyNode \| null) => void | No |  | Receive callbacks when a node is hovered/focused |
| `onLinkHover` | (link: SankeyLink \| null) => void | No |  | Receive callbacks when a link is hovered/focused |
| `highlightOnHover` | boolean | No | true | Highlight hovered nodes/links (defaults to true) |
| `onDataInconsistency` | (issues: SankeyInconsistency[]) => void | No |  | Surfaced when inbound/outbound totals differ for a node |
| `width` | number | No | 600 | 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. |
| `height` | number | No | 400 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationEasing` | string | No |  | Animation easing function |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `SankeyChart.basic` • Category: charts

```tsx
return (
		<SankeyChart
			title="Renewable energy flow"
			height={360}
			nodes={NODES}
			links={LINKS}
		/>
	);
}
```

### Budget Allocation
ID: `SankeyChart.budget-allocation` • Category: charts

```tsx
return (
    <SankeyChart
      title="Budget allocation flow"
      subtitle="FY26 operating plan"
      height={400}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

### Cloud Provisioning
ID: `SankeyChart.cloud-provisioning` • Category: charts

```tsx
return (
    <SankeyChart
      title="Cloud provisioning workflow"
      subtitle="Quarterly environment requests"
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

### Customer Journey
ID: `SankeyChart.customer-journey` • Category: charts

```tsx
return (
    <SankeyChart
      title="Customer journey flow"
      subtitle="Q3 acquisition to retention"
      height={420}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

### Data Lineage
ID: `SankeyChart.data-lineage` • Category: charts

```tsx
return (
    <SankeyChart
      title="Analytics data lineage"
      subtitle="Daily load pipeline"
      height={420}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

### Talent Pipeline
ID: `SankeyChart.talent-pipeline` • Category: charts

```tsx
return (
    <SankeyChart
      title="Engineering talent pipeline"
      subtitle="Campus + lateral hiring"
      height={420}
      nodes={NODES}
      links={LINKS}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/ScatterChart.md -->

# Scatter Chart

Plots data points in two-dimensional space for correlation analysis.

## Metadata

- Canonical name: `ScatterChart`
- Package: `@platform-blocks/charts`
- Import: `import { ScatterChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, scatter, xy
- Docs: https://react-ui-library.com/components/ScatterChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/ScatterChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | ChartDataPoint[] | Yes |  | Data points |
| `series` | ScatterSeries[] | No |  | Optional multi-series data (overrides top-level data if provided) |
| `pointSize` | number | No | 6 | Point size |
| `pointColor` | string | No |  | Point color |
| `pointOpacity` | number | No | 1 | Point opacity |
| `allowAddPoints` | boolean | No | false | Allow adding points by tapping |
| `showTrendline` | boolean \| 'overall' \| 'per-series' | No | false | Show trend line. true\|'overall' for single combined regression, 'per-series' for one per series |
| `trendlineColor` | string | No |  | Trend line color |
| `enablePanZoom` | boolean | No |  | Enable pan & zoom interactions |
| `zoomMode` | 'x' \| 'y' \| 'both' | No |  | Zoom mode (axes constrained) |
| `minZoom` | number | No |  | Minimum zoom scale (domain fraction) |
| `enableWheelZoom` | boolean | No |  | Enable wheel zoom (web) |
| `wheelZoomStep` | number | No |  | Wheel zoom step |
| `invertWheelZoom` | boolean | No |  | Invert wheel zoom direction |
| `resetOnDoubleTap` | boolean | No |  | Reset zoom on double tap |
| `clampToInitialDomain` | boolean | No |  | Clamp pan/zoom to initial full domain |
| `invertPinchZoom` | boolean | No |  | Invert pinch gesture direction (scale grows when fingers move closer) |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<ChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `multiTooltip` | boolean | No |  | Enable multi-series shared tooltip popover |
| `enableCrosshair` | boolean | No |  | Enable crosshair |
| `liveTooltip` | boolean | No |  | Live (follow pointer) tooltip selection |
| `xScaleType` | 'linear' \| 'log' \| 'time' | No |  | X scale type |
| `yScaleType` | 'linear' \| 'log' \| 'time' | No |  | Y scale type |
| `quadrants` | ScatterQuadrantConfig | No |  | Optional quadrant overlay configuration |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Api Error Rate Volume
ID: `ScatterChart.api-error-rate-volume` • Category: charts

```tsx
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;
};
  return (
    <ScatterChart
      title="API error rate vs. request volume"
      subtitle="Each point represents a service, sized by throughput"
      height={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');
        },
      }}
    />
  );
}
```

### Basic
ID: `ScatterChart.basic` • Category: charts

```tsx
return (
    <ScatterChart
      title="Spend vs. qualified leads"
      subtitle="Campaign cohort"
      height={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`,
      }}
    />
  );
}
```

### Campaign Spend Revenue
ID: `ScatterChart.campaign-spend-revenue` • Category: charts

```tsx
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;
};
  return (
    <ScatterChart
      title="Campaign spend vs. attributed revenue"
      subtitle="Ad set performance, each marker sized by budget grouping"
      height={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');
        },
      }}
    />
  );
}
```

### Customer Ltv Vs Cac
ID: `ScatterChart.customer-ltv-vs-cac` • Category: charts

```tsx
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;
};
  return (
    <ScatterChart
      title="Customer LTV vs. Acquisition Cost"
      subtitle="Segment performance across recent cohorts"
      height={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');
        },
      }}
    />
  );
}
```

### Feature Usage Vs Satisfaction
ID: `ScatterChart.feature-usage-vs-satisfaction` • Category: charts

```tsx
return (
    <ScatterChart
      title="Feature usage vs. satisfaction"
      subtitle="Weekly feature interactions mapped to CSAT by cohort"
      height={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)}`,
      }}
    />
  );
}
```

### Performance Vs Tenure
ID: `ScatterChart.performance-vs-tenure` • Category: charts

```tsx
return (
    <ScatterChart
      title="Performance rating vs. tenure"
      subtitle="Team-by-team view with marker size scaled to total compensation (USD thousands)"
      height={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}`;
        },
      }}
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/SparklineChart.md -->

# Sparkline Chart

Compact inline trend indicator for dense data summaries.

## Metadata

- Canonical name: `SparklineChart`
- Package: `@platform-blocks/charts`
- Import: `import { SparklineChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, sparkline, trend
- Docs: https://react-ui-library.com/components/SparklineChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/SparklineChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | string \| number | No |  | Optional unique series ID |
| `name` | string | No |  | Optional series name (for tooltip) |
| `data` | number[] \| SparklinePoint[] | Yes |  | Data points (plain y values or explicit {x,y} pairs) |
| `color` | string | No |  | Line color |
| `fill` | boolean | No | true | Fill area under line |
| `fillOpacity` | number | No | 0.3 | Fill opacity |
| `strokeWidth` | number | No | 2 | Stroke width |
| `smooth` | boolean | No | true | Curve smoothing |
| `showPoints` | boolean | No | false | Show data points |
| `pointSize` | number | No | 3 | Point size (for individual data points) |
| `domain` | SparklineDomain | No |  | Provide min/max to avoid re-scaling jitter across multiple sparklines |
| `highlightLast` | boolean | No | true | Show last value bubble |
| `highlightExtrema` | boolean \| SparklineExtremaHighlight | No |  | Show min/max markers |
| `valueFormatter` | (value: number) => string | No |  | Format displayed last value |
| `liveTooltip` | boolean | No | true | Compact tooltip when hovered (web) |
| `multiTooltip` | boolean | No | false | Enable aggregated tooltip when multiple sparklines share context |
| `thresholds` | SparklineThreshold[] | No | [] as SparklineThreshold[] | Horizontal threshold guides |
| `bands` | SparklineBand[] | No | [] as SparklineBand[] | Highlight background regions |
| `animation` | SparklineAnimationOptions | No |  | Control reveal animation |
| `width` | number | No | 120 | 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. |
| `height` | number | No | 48 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `SparklineChart.basic` • Category: charts

```tsx
return (
    <SparklineChart
      height={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] }}
    />
  );
}
```

### Dashboard Daily Active Users
ID: `SparklineChart.dashboard-daily-active-users` • Category: charts

```tsx
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`;
};
  return (
    <Card padding="lg" radius="lg">
      <Block mb="md">
        <Title order={5} text="Daily Active Users" />
        <Text size="sm" c="dimmed">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" weight="semibold">{series.title}</Text>
              <Text size="xs" c="dimmed">
                {latest.toLocaleString()} · {getDeltaLabel(series.data)}
              </Text>
              <SparklineChart
                height={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>
  );
}
```

### Release Train Bug Count
ID: `SparklineChart.release-train-bug-count` • Category: charts

```tsx
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
        height={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>
  );
}
```

### Storefront Weekly Revenue
ID: `SparklineChart.storefront-weekly-revenue` • Category: charts

```tsx
const formatRevenue = (value: number) => `$${value.toFixed(1)}k`;
  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
                height={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>
  );
}
```

### Support Queue Monitor
ID: `SparklineChart.support-queue-monitor` • Category: charts

```tsx
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
        height={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>
  );
}
```

### Team Deploy Velocity
ID: `SparklineChart.team-deploy-velocity` • Category: charts

```tsx
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
              height={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>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/StackedAreaChart.md -->

# Stacked Area Chart

Area chart with multiple series stacked to show cumulative contributions.

## Metadata

- Canonical name: `StackedAreaChart`
- Package: `@platform-blocks/charts`
- Import: `import { StackedAreaChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, area, stacked
- Docs: https://react-ui-library.com/components/StackedAreaChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/StackedAreaChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | LineChartSeries[] | Yes |  | Data series to stack |
| `stackOrder` | 'normal' \| 'reverse' | No | 'normal' | Order layers are stacked in |
| `smooth` | boolean | No | true | Smooth (curved) area tops |
| `opacity` | number | No | 0.55 | Base opacity for the stacked layers |
| `stackMode` | 'absolute' \| 'percentage' | No | 'absolute' | Stack values as absolute totals or normalized to 100% |
| `lineColor` | string | No |  | Line color (for single series) |
| `lineThickness` | number | No |  | Line thickness (for single series) |
| `lineStyle` | 'solid' \| 'dashed' \| 'dotted' | No |  | Line style (for single series) |
| `showPoints` | boolean | No |  | Show data points (for single series) |
| `pointSize` | number | No |  | Point size (for single series) |
| `pointColor` | string | No |  | Point color (for single series) |
| `fillColor` | string | No |  | Fill color |
| `fillOpacity` | number | No |  | Fill opacity |
| `areaFillMode` | 'single' \| 'series' | No |  | How to distribute fill across series when multiple are present |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid configuration |
| `legend` | ChartLegend | No |  | Legend configuration |
| `tooltip` | ChartTooltip<ChartDataPoint> | No |  | Tooltip configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `enableCrosshair` | boolean | No |  | Show a vertical crosshair that follows the nearest point |
| `enableSeriesToggle` | boolean | No |  | Enable toggling series visibility from legend |
| `liveTooltip` | boolean | No |  | Update tooltip continuously while moving (not just on press) |
| `multiTooltip` | boolean | No |  | Show multi-series aggregated tooltip aligned to crosshair |
| `enablePanZoom` | boolean | No |  | Enable pan and pinch zoom interactions |
| `zoomMode` | 'x' \| 'y' \| 'both' | No |  | Which axes can zoom |
| `minZoom` | number | No |  | Minimum zoom factor relative to original domain (e.g. 0.1 = 10%) |
| `onDomainChange` | (xDomain: [number, number], yDomain: [number, number]) => void | No |  | Callback when visible data domain changes |
| `enableWheelZoom` | boolean | No |  | Enable wheel zoom on web |
| `wheelZoomStep` | number | No |  | Wheel zoom step factor (default 0.1) |
| `invertWheelZoom` | boolean | No |  | Invert wheel zoom direction |
| `resetOnDoubleTap` | boolean | No |  | Double-tap (or double-click on web) resets zoom |
| `clampToInitialDomain` | boolean | No |  | Clamp pan/zoom so domains never exceed original data bounds |
| `invertPinchZoom` | boolean | No |  | Invert pinch gesture direction (scale grows when fingers move closer) |
| `disableAnimations` | boolean | No |  | Disable all Reanimated-driven animations (debug / perf fallback) |
| `decimationThreshold` | number | No |  | Apply LTOB data decimation above this point count |
| `xScaleType` | 'linear' \| 'log' \| 'time' | No | 'linear' | X axis scale type |
| `yScaleType` | 'linear' \| 'log' \| 'time' | No | 'linear' | Y axis scale type |
| `enableBrushZoom` | boolean | No |  | Enable shift+drag brush to zoom (web) |
| `annotations` | ChartAnnotation[] | No |  | Optional chart annotations/markers |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `StackedAreaChart.basic` • Category: charts

```tsx
return (
    <StackedAreaChart
      title="Active users by surface"
      subtitle="Monthly totals"
      height={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
    />
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/components/StackedBarChart.md -->

# Stacked Bar Chart

Bar chart with segments stacked to show part-to-whole by category.

## Metadata

- Canonical name: `StackedBarChart`
- Package: `@platform-blocks/charts`
- Import: `import { StackedBarChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, bar, stacked
- Docs: https://react-ui-library.com/components/StackedBarChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/StackedBarChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | StackedBarSeries[] | Yes |  | Stacked bar series to render |
| `barSpacing` | number | No | 0.25 | Gap between stacked groups |
| `legend` | ChartLegend | No | { show: true, position: 'bottom', align: 'center' } | Legend configuration |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `animation` | ChartAnimation | No |  | Animation configuration |
| `width` | number | No | 400 | 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. |
| `height` | number | No | 300 | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No | 800 | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No | false | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |
| `onPress` | (event: ChartInteractionEvent<TData>) => void | No |  | Called when chart is tapped/clicked |
| `onDataPointPress` | (dataPoint: TData, event: ChartInteractionEvent<TData>) => void | No |  | Called when data point is selected |

## Examples

### Basic
ID: `StackedBarChart.basic` • Category: charts

```tsx
return (
		<StackedBarChart
			title="Quarterly ARR by motion"
			height={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 }}
		/>
	);
}
```

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

<!-- source: https://react-ui-library.com/llms/components/ViolinChart.md -->

# Violin Chart

Distribution visualization combining box plot and kernel density.

### Highlights
- Adjustable violin width ratio to balance spacing in dense comparisons.
- Overlay statistic markers (median, mean, quartiles, whiskers) with optional value labels.
- Add chart-wide value bands to spotlight SLA windows, target ranges, or alert thresholds.

## Metadata

- Canonical name: `ViolinChart`
- Package: `@platform-blocks/charts`
- Import: `import { ViolinChart } from '@platform-blocks/charts';`
- Category: charts
- Tags: chart, violin, distribution
- Docs: https://react-ui-library.com/components/ViolinChart
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/charts/src/components/ViolinChart

## Props

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `series` | ViolinDensitySeries[] | Yes |  | Density series rendered within the violin chart |
| `samples` | number | No |  | Density sample resolution |
| `bandwidth` | number | No |  | Kernel bandwidth override |
| `violinWidthRatio` | number | No |  | Relative width multiplier applied to each violin (0.2 - 1) |
| `layout` | ViolinLayout | No |  | Layout orientation |
| `stackOverlap` | number | No |  | Overlap factor between adjacent violins (0 - 0.95) |
| `xAxis` | ChartAxis | No |  | X-axis configuration |
| `yAxis` | ChartAxis | No |  | Y-axis configuration |
| `grid` | ChartGrid | No |  | Grid line configuration |
| `statsMarkers` | ViolinStatsMarkersConfig | No |  | Statistic marker overlays for each violin |
| `valueBands` | ViolinValueBand[] | No |  | Value range highlights rendered across the chart |
| `showLegend` | boolean | No |  | Legacy legend toggle (prefer `legend` prop) |
| `legendPosition` | 'top' \| 'bottom' | No |  | Legacy legend position option |
| `legend` | ChartLegend | No |  | Legend configuration |
| `onSeriesFocus` | (event: ViolinSeriesInteractionEvent) => void | No |  | Series focus callback |
| `onSeriesBlur` | (event: ViolinSeriesInteractionEvent) => void | No |  | Series blur callback |
| `onSeriesPress` | (event: ViolinSeriesInteractionEvent) => void | No |  | Series press/tap callback |
| `width` | number | No |  | 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. |
| `height` | number | No |  | Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. |
| `aspectRatio` | number | No |  | 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. |
| `maxWidth` | number | No |  | Upper bound on the resolved width. Useful for radial charts in wide columns. |
| `minWidth` | number | No |  | Lower bound on the resolved width. |
| `maxHeight` | number | No |  | Upper bound on a height derived from `aspectRatio`. |
| `minHeight` | number | No |  | Lower bound on a height derived from `aspectRatio`. |
| `testID` | string | No |  | Chart test ID for testing |
| `style` | any | No |  | Additional styles |
| `accessibilityLabel` | string | No |  | Accessibility label surfaced to assistive tech |
| `accessibilityHint` | string | No |  | Accessibility hint describing chart interaction |
| `accessibilityRole` | string | No |  | Accessibility role override |
| `accessible` | boolean | No |  | Whether the chart container is accessible |
| `importantForAccessibility` | 'auto' \| 'yes' \| 'no' \| 'no-hide-descendants' | No |  | Platform specific accessibility importance |
| `animationDuration` | number | No |  | Animation duration in ms |
| `animationEasing` | string | No |  | Animation easing function |
| `disabled` | boolean | No |  | Whether chart is disabled |
| `title` | string | No |  | Chart title |
| `subtitle` | string | No |  | Chart subtitle |
| `useOwnInteractionProvider` | boolean | No |  | If false, chart expects a parent interaction provider (shared context). |
| `suppressPopover` | boolean | No |  | Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). |
| `m` | number | No |  | Margin applied to all sides |
| `mt` | number | No |  | Margin applied to the top side |
| `mr` | number | No |  | Margin applied to the right side |
| `mb` | number | No |  | Margin applied to the bottom side |
| `ml` | number | No |  | Margin applied to the left side |
| `mx` | number | No |  | Horizontal margin applied to left and right sides |
| `my` | number | No |  | Vertical margin applied to top and bottom sides |
| `p` | number | No |  | Padding applied to all sides |
| `pt` | number | No |  | Padding applied to the top side |
| `pr` | number | No |  | Padding applied to the right side |
| `pb` | number | No |  | Padding applied to the bottom side |
| `pl` | number | No |  | Padding applied to the left side |
| `px` | number | No |  | Horizontal padding applied to left and right sides |
| `py` | number | No |  | Vertical padding applied to top and bottom sides |

## Examples

### Basic
ID: `ViolinChart.basic` • Category: charts

```tsx
return (
    <ViolinChart
      title="Delivery time distribution"
      height={360}
      series={SERIES}
      samples={128}
      bandwidth={3.5}
    />
  );
}
```

### Delivery Times
ID: `ViolinChart.delivery-times` • Category: charts

```tsx
return (
    <ViolinChart
      title="Delivery time spread by fulfillment center"
      subtitle="Distribution of hours from order capture to doorstep delivery"
      height={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` }}
    />
  );
}
```

### Experiment Metric Deltas
ID: `ViolinChart.experiment-metric-deltas` • Category: charts

```tsx
return (
    <ViolinChart
      title="Experiment metric deltas vs. control"
      subtitle="Percent change in weekly activation compared to holdout"
      height={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' }}
    />
  );
}
```

### Model Prediction Errors
ID: `ViolinChart.model-prediction-errors` • Category: charts

```tsx
return (
    <ViolinChart
      title="Prediction error distribution per model version"
      subtitle="Mean absolute error (percentage points) across validation folds"
      height={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)}%`,
      }}
    />
  );
}
```

### Salary Distribution
ID: `ViolinChart.salary-distribution` • Category: charts

```tsx
return (
    <ViolinChart
      title="Total compensation distribution by department"
      subtitle="Annual salary including bonus (USD thousands)"
      height={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`,
      }}
    />
  );
}
```

### Session Duration By Platform
ID: `ViolinChart.session-duration-by-platform` • Category: charts

```tsx
return (
    <ViolinChart
      title="Session duration distribution by platform"
      subtitle="Minutes per active session across major surfaces"
      height={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`,
      }}
    />
  );
}
```

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

# HOOKS

<!-- source: https://react-ui-library.com/llms/hooks/useClipboard.md -->

# useClipboard

Copy values to the system clipboard with optimistic status updates and optional reset timers.

## Metadata

- Canonical name: `useClipboard`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useClipboard } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: productivity
- Tags: clipboard, copy
- Docs: https://react-ui-library.com/hooks/useClipboard
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useClipboard

## Definition

```ts
export interface UseClipboardOptions {
  /** Time in ms after which the copied state will reset, 2000 by default */
  timeout?: number;
}

export interface UseClipboardReturnValue {
  /** Function to copy value to clipboard */
  copy: (value: any) => Promise<void> | void;
  /** 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 if clipboard API not available */
  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 '@platform-blocks/react-ui-library';

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" maxW={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" color={copied ? 'success' : 'gray'}>
          Last copied: {lastValue}
        </Badge>
      ) : null}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/hooks/useControllableState.md -->

# useControllableState

Back a value-bearing component with either a controlled `value` prop or internal state, decided by one call.

## Metadata

- Canonical name: `useControllableState`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useControllableState } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 0.11.0
- Category: state
- Tags: state, controlled, uncontrolled, forms
- Docs: https://react-ui-library.com/hooks/useControllableState
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useControllableState

## 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.
   */
  onChange?: (value: T, ...payload: any[]) => 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: any[]) => 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 '@platform-blocks/react-ui-library';

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" color={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" color="muted">No value prop — the hook keeps the rating in internal state.</Text>
        <StarPicker defaultValue={2} />
      </Block>

      <Block gap="xs">
        <Text size="sm" color="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://react-ui-library.com/llms/hooks/useDebouncedCallback.md -->

# useDebouncedCallback

Wrap an imperative function in a stable debounced callback that exposes `cancel` and `flush`.

## Metadata

- Canonical name: `useDebouncedCallback`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useDebouncedCallback } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: state
- Tags: debounce, callback, performance
- Docs: https://react-ui-library.com/hooks/useDebouncedCallback
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useDebouncedCallback

## Definition

```ts
export interface UseDebouncedCallbackReturn<F extends (...args: any[]) => any> {
  /** 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 (...args: any[]) => any>(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 '@platform-blocks/react-ui-library';

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" color="muted">No invocations yet.</Text>
      )}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/hooks/useDebouncedValue.md -->

# useDebouncedValue

Derive a debounced copy of a changing value so renders and effects react only once it settles.

## Metadata

- Canonical name: `useDebouncedValue`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useDebouncedValue } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: state
- Tags: debounce, search, performance
- Docs: https://react-ui-library.com/hooks/useDebouncedValue
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useDebouncedValue

## 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 '@platform-blocks/react-ui-library';

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" color="muted">No matches.</Text>
      )}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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.

## Metadata

- Canonical name: `useDeviceInfo`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useDeviceInfo } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 0.4.0
- Category: platform
- Tags: device, responsive, platform
- Docs: https://react-ui-library.com/hooks/useDeviceInfo
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useDeviceInfo

## Definition

```ts
export interface DeviceInfo {
  runtime: {
    platform: 'browser' | 'native';
    browserName: string | null;
    browserVersion: string | null;
    jsEngine: 'Hermes' | 'JSC' | 'V8' | null;
    engineVersion: string | null;
  };
  system: {
    os: {
      name: string | null;
      version: string | null;
      buildId?: string | null;
    };
    device: {
      type: 'phone' | 'tablet' | 'desktop' | 'tv' | 'console' | 'wearable' | 'unknown';
      brand: string | null;
      model: string | null;
      isVirtual?: boolean;
    };
  };
  screen: {
    width: number;
    height: number;
    scale: number;
    fontScale?: number;
    orientation: 'portrait' | 'landscape';
  };
  locale: {
    language: string;
    region: string | null;
    full: string;
    timeZone: string;
    uses24HourClock: boolean;
  };
  appearance: {
    colorScheme: 'light' | 'dark' | 'no-preference';
    contrast: 'more' | 'less' | 'no-preference';
    reducedMotion: boolean;
    fontScale: number;
  };
  input: {
    primaryPointer: 'touch' | 'mouse' | 'pen' | 'unknown';
    pointerTypes: Array<'touch' | 'mouse' | 'pen'>;
    hasTouch: boolean;
    hasMouse: boolean;
    hasKeyboard: boolean | null;
  };
  safeArea: {
    top: number;
    bottom: number;
    left: number;
    right: number;
  };
  network?: {
    ipAddress?: string | null;
    macAddress?: string | null;
    connectionType?: 'wifi' | 'cellular' | 'ethernet' | 'unknown';
    downlink?: number | null;
  };
  capabilities?: {
    hdr: boolean | null;
    gpu: string | null;
  };
  platform: {
    isWeb: boolean;
    isNative: boolean;
    isIOS: boolean;
    isAndroid: boolean;
    isMobile: boolean;
    isTablet: boolean;
    isPhone: boolean;
    isDesktop: boolean;
    isConsole: boolean;
    isTV: boolean;
    isWearable: boolean;
  };
  helpers: {
    isPhone: boolean;
    isTablet: boolean;
    isMobile: boolean;
    isDesktop: boolean;
    isDarkMode: boolean;
    isLandscape: boolean;
    getOS: () => string;
    getBrand: () => string | null;
  };
  meta: {
    updatedAt: number;
    ready: boolean;
  };
}

export interface UseDeviceInfoOptions {
  enableExtendedData?: boolean;
}

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 '@platform-blocks/react-ui-library';

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" weight="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" weight="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" weight="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://react-ui-library.com/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

- Canonical name: `useDisclosure`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useDisclosure } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: state
- Tags: state, toggle, open-close, modal, dialog
- Docs: https://react-ui-library.com/hooks/useDisclosure
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useDisclosure

## 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 '@platform-blocks/react-ui-library';

export function Demo() {
  const [opened, { open, close, toggle }] = useDisclosure(false, {
    onOpen: () => console.log('opened'),
    onClose: () => console.log('closed'),
  });

  return (
    <Block align="flex-start">
      <Badge color={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 visible={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://react-ui-library.com/llms/hooks/useEscapeKey.md -->

# useEscapeKey

Listen for user to press the Escape key to dismiss transient UI like modals, drawers, or menus.

## Metadata

- Canonical name: `useEscapeKey`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useEscapeKey } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: keyboard
- Tags: keyboard, escape
- Docs: https://react-ui-library.com/hooks/useEscapeKey
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useEscapeKey

## Definition

```ts
export function useEscapeKey(handler: () => void, enabled = true);
```

## 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 '@platform-blocks/react-ui-library';

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" maxW={360}>
          <Block>
            <Text size="sm" weight="semibold">Escape-enabled panel</Text>
            <Text size="sm" color="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://react-ui-library.com/llms/hooks/useGlobalHotkeys.md -->

# useGlobalHotkeys

Attach application-wide shortcuts that persist even when the originating component unmounts.

## Metadata

- Canonical name: `useGlobalHotkeys`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useGlobalHotkeys } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: keyboard
- Tags: keyboard, global, shortcuts
- Docs: https://react-ui-library.com/hooks/useGlobalHotkeys
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useGlobalHotkeys

## 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);
```

## 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 '@platform-blocks/react-ui-library';

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://react-ui-library.com/llms/hooks/useHaptics.md -->

# useHaptics

Trigger platform-native vibration patterns with throttling and graceful fallbacks when haptics are unavailable.

## Metadata

- Canonical name: `useHaptics`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useHaptics } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: feedback
- Tags: haptics, feedback
- Docs: https://react-ui-library.com/hooks/useHaptics
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useHaptics

## Definition

```ts
export interface UseHapticsOptions {
  /** Whether haptics are disabled */
  disabled?: boolean;
  /** Minimum ms between triggers to avoid flood. */
  throttleMs?: number;
}

export interface UseHapticsReturn {
  /** Light impact when press starts */
  impactPressIn: () => void;
  /** A second impact on release (slightly heavier) */
  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 '@platform-blocks/react-ui-library';

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" weight="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://react-ui-library.com/llms/hooks/useHotkeys.md -->

# useHotkeys

Register scoped keyboard shortcuts that only run while the component using them stays mounted.

## Metadata

- Canonical name: `useHotkeys`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useHotkeys } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: keyboard
- Tags: keyboard, shortcuts, scoped
- Docs: https://react-ui-library.com/hooks/useHotkeys
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useHotkeys

## 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[], dependencies: React.DependencyList = []);
```

## 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 '@platform-blocks/react-ui-library';

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')],
    ],
    [append]
  );

  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" color="muted">No shortcuts fired yet.</Text>
      )}
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `useHover`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useHover } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: interaction
- Tags: hover, pressable, web
- Docs: https://react-ui-library.com/hooks/useHover
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useHover

## Definition

```ts
export type UseHoverReturn = readonly [boolean, UseHoverHandlers];

export interface UseHoverHandlers {
  /** Pointer entered the element. Wire to RN `onHoverIn` / `onMouseEnter`. */
  onHoverIn: () => void;
  /** Pointer left the element. Wire to RN `onHoverOut` / `onMouseLeave`. */
  onHoverOut: () => void;
  /** Web-only alias for `onHoverIn`. */
  onMouseEnter: () => void;
  /** Web-only alias for `onHoverOut`. */
  onMouseLeave: () => 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 '@platform-blocks/react-ui-library';

export function Demo() {
  const [hovered, hoverHandlers] = useHover();

  return (
    <Block align="flex-start">
      <Text size="sm" color="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 weight={hovered ? '700' : '500'}>{hovered ? 'Hovered' : 'Hover me'}</Text>
        </Card>
      </Pressable>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/hooks/useMaskedInput.md -->

# useMaskedInput

Keep controlled inputs in sync with formatted masks while exposing the unmasked value and completion status.

## Metadata

- Canonical name: `useMaskedInput`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useMaskedInput } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: forms
- Tags: forms, masking
- Docs: https://react-ui-library.com/hooks/useMaskedInput
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useMaskedInput

## Definition

```ts
export interface UseMaskedInputOptions {
  /** The mask definition */
  mask: MaskDefinition | ReturnType<typeof createMask>;
  /** 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 '@platform-blocks/react-ui-library';

export function Demo() {
  const { value, unmaskedValue, isComplete, handleChangeText, handleSelectionChange } = useMaskedInput({
    mask: { mask: '(000) 000-0000', placeholderChar: '_' }
  });

  return (
    <Block align="flex-start" maxW={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" color={isComplete ? 'success' : 'gray'}>
        {isComplete ? 'Mask complete' : 'Enter all digits'}
      </Badge>
      <Text size="xs" color="muted">Raw value: {unmaskedValue || '—'}</Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/hooks/useMediaQuery.md -->

# useMediaQuery

Evaluate a CSS media query on web and width/height queries on native, updating as the viewport changes.

## Metadata

- Canonical name: `useMediaQuery`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useMediaQuery } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: platform
- Tags: media-query, responsive, dimensions
- Docs: https://react-ui-library.com/hooks/useMediaQuery
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useMediaQuery

## 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 '@platform-blocks/react-ui-library';

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'} color={isCompact ? 'success' : 'gray'}>
          Compact (≤640px)
        </Badge>
        <Badge variant={isWide ? 'light' : 'outline'} color={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" minW={120}>
            <Text c="white">Card {i + 1}</Text>
          </Block>
        ))}
      </Row>

      <Text size="sm" color="muted">
        Resize the viewport (or rotate the device) to see the layout adapt.
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/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

- Canonical name: `useOverlayMode`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useOverlayMode } from '@platform-blocks/react-ui-library';`
- Status: beta
- Since: 1.0.0
- Category: layout
- Tags: modal, overlay, responsive
- Docs: https://react-ui-library.com/hooks/useOverlayMode
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useOverlayMode

## 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: ReturnType<typeof useDeviceInfo>;
  /** 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;
  /** Alias for shouldUseOverlay for popover/portal driven surfaces */
  shouldUsePortal: 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 '@platform-blocks/react-ui-library';

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" color={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'} color={on ? 'primary' : 'gray'}>
            {label}
          </Badge>
        ))}
      </Row>
      <Text size="sm" color="muted">
        Resize the preview or switch platforms to see the recommendation change.
      </Text>
    </Block>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/hooks/useScrollSpy.md -->

# useScrollSpy

Collect headings from the DOM or title registry and track which section is currently visible.

## Metadata

- Canonical name: `useScrollSpy`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useScrollSpy } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: navigation
- Tags: toc, navigation
- Docs: https://react-ui-library.com/hooks/useScrollSpy
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useScrollSpy

## 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. */
  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 */
  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 '@platform-blocks/react-ui-library';

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 weight="semibold">{title}</Text>
      <Text size="sm" color="secondary">{copy}</Text>
    </View>
  );
}

function TocList() {
  const { items, activeId } = useScrollSpy();

  if (!items.length) {
    return <Text size="sm" color="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'}
          color={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://react-ui-library.com/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

- Canonical name: `useSpotlightToggle`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useSpotlightToggle } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: keyboard
- Tags: keyboard, spotlight
- Docs: https://react-ui-library.com/hooks/useSpotlightToggle
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useSpotlightToggle

## 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 '@platform-blocks/react-ui-library';

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://react-ui-library.com/llms/hooks/useTitleRegistration.md -->

# useTitleRegistration

Register headings with the shared title registry so sticky TOCs and scrollspy hooks stay in sync.

## Metadata

- Canonical name: `useTitleRegistration`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useTitleRegistration } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: navigation
- Tags: toc, titles
- Docs: https://react-ui-library.com/hooks/useTitleRegistration
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useTitleRegistration

## Definition

```ts
export interface UseTitleRegistrationOptions {
  /** Text content of the title */
  text: string;
  /** Order for sorting titles, lower numbers appear first */
  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 const useTitleRegistration = (options: UseTitleRegistrationOptions);
```

## 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 '@platform-blocks/react-ui-library';

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 weight="semibold">{title}</Text>
      <Text size="sm" color="secondary">{description}</Text>
    </View>
  );
}

function RegistryPreview() {
  const { titles } = useTitleRegistry();

  if (!titles.length) {
    return <Text size="sm" color="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" weight="semibold">Registered titles</Text>
          <RegistryPreview />
        </Block>
        <Block gap="lg">
          {SECTIONS.map(section => (
            <Section key={section.title} {...section} />
          ))}
        </Block>
      </Block>
    </TitleRegistryProvider>
  );
}
```

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

<!-- source: https://react-ui-library.com/llms/hooks/useToggleColorScheme.md -->

# useToggleColorScheme

Bind a keyboard shortcut to cycle through available color schemes provided by the theme mode context.

## Metadata

- Canonical name: `useToggleColorScheme`
- Package: `@platform-blocks/react-ui-library`
- Import: `import { useToggleColorScheme } from '@platform-blocks/react-ui-library';`
- Status: stable
- Since: 1.0.0
- Category: keyboard
- Tags: keyboard, theme
- Docs: https://react-ui-library.com/hooks/useToggleColorScheme
- Source: https://github.com/platform-blocks/react-ui-library/tree/main/packages/ui/src/hooks/useToggleColorScheme

## 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 '@platform-blocks/react-ui-library';

export function Demo() {
  const { mode, cycleMode, actualColorScheme } = useThemeMode();

  useToggleColorScheme(cycleMode);

  return (
    <Block align="flex-start" maxW={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" color="muted">Or press</Text>
        <KeyCap keyCode="J" modifiers={['cmd']} size="sm">⌘</KeyCap>
        <KeyCap keyCode="J" modifiers={['cmd']} size="sm">J</KeyCap>
        <Text size="xs" color="muted">anywhere in the docs.</Text>
      </Row>
    </Block>
  );
}
```

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

# FAQ

<!-- source: https://react-ui-library.com/llms/faq/what-is.md -->

# What is React UI Library?

React UI Library 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://react-ui-library.com/faq

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

<!-- source: https://react-ui-library.com/llms/faq/expo-compatibility.md -->

# Is React UI Library compatible with Expo?

Yes! React UI Library 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://react-ui-library.com/faq

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

<!-- source: https://react-ui-library.com/llms/faq/does-support.md -->

# Does React UI Library support React Native Web?

Absolutely! React UI Library is built with React Native Web compatibility in mind. All components work seamlessly across iOS, Android, and web platforms.

Docs: https://react-ui-library.com/faq

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

<!-- source: https://react-ui-library.com/llms/faq/can-customize.md -->

# Can I customize the theme?

Yes, React UI Library 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://react-ui-library.com/faq

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

<!-- source: https://react-ui-library.com/llms/faq/can-use-custom-fonts.md -->

# Can I use custom fonts?

Yes, you can configure custom fonts through the theme system. React UI Library's typography system allows you to specify custom font families for different text variants.

Docs: https://react-ui-library.com/faq

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

<!-- source: https://react-ui-library.com/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 React UI Library better for everyone.

Docs: https://react-ui-library.com/faq

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