# plocks — API Reference (compact) Every component, chart and hook in one file: import line, own props with a one-sentence description, sub-components, and one complete example each. Each entry links its full page, which adds every example and the longer prop descriptions. Index of individual pages: https://plocks.dev/llms.txt • Everything in full: https://plocks.dev/llms-full.txt Install: `npm install @plocks/ui` — separate packages, installed alongside it: `@plocks/brands`, `@plocks/carousel`, `@plocks/charts`, `@plocks/code`, `@plocks/dates`, `@plocks/emoji-picker`, `@plocks/media`, `@plocks/qrcode`, `@plocks/spotlight`. A component page's Import line names the package it comes from. Version: generated from the `main` branch — `@plocks/ui` 0.2.0, `@plocks/brands` 0.2.0, `@plocks/carousel` 0.2.0, `@plocks/charts` 0.2.0, `@plocks/code` 0.2.0, `@plocks/dates` 0.2.0, `@plocks/emoji-picker` 0.2.0, `@plocks/media` 0.2.0, `@plocks/qrcode` 0.2.0, `@plocks/spotlight` 0.2.0. The branch can be ahead of the latest npm release; if an API here is missing from your installed version, check the changelog: https://github.com/platform-blocks/plocks/tree/main/changelog Website: https://plocks.dev • GitHub: https://github.com/platform-blocks/plocks • npm: https://www.npmjs.com/package/@plocks/ui **Conventions** - Import from the package root: `import { Button, Row, useToast } from '@plocks/ui'`. Some components live in their own package — `@plocks/dates`, `@plocks/charts`, `@plocks/code`, `@plocks/media`, `@plocks/carousel`, `@plocks/spotlight`, `@plocks/brands`, `@plocks/qrcode`, `@plocks/emoji-picker` — installed alongside `@plocks/ui`; each page's Import line names the package. - Wrap the app once in `` (theme, color scheme, overlays, i18n). `useToast()` and `useDialog()` render through `` / `` — mount those inside it before calling them. Theming: https://plocks.dev/llms/guides/theming.md - Lay out with `Block` in place of `View`, `Row` / `Column` for flex stacks (`gap`, `align`, `justify`, `wrap`), and `Grid` + `GridItem` for columns. `Row` and `Column` are documented on the Flex page. - Most components take the shared style props — spacing (`m`, `p`, `mx`, `py`, …), sizing (`w`, `h`, `fullWidth`, …), `radius`, `shadow` — form inputs share the field props (`label`, `description`, `error`, `helperText`, `required`, …) and charts the chart props. Component pages list their own props and name the shared groups they accept; the groups are defined once here: https://plocks.dev/llms/guides/shared-props.md - `size`, spacing, `radius` and `shadow` take the tokens `xs` `sm` `md` `lg` `xl` `2xl` `3xl` (default `md`) or a number. `color` takes a palette name (`primary`, `secondary`, `tertiary`, `success`, `warning`, `error`, `gray`), a shade (`'primary.6'`), or any CSS color. - `Button` is neutral by default — use `variant="filled"` for the primary action. Events use React Native names: `onPress`, `onChange`, never `onClick`. - `` accepts only names in the built-in Tabler registry — do not guess one: https://plocks.dev/llms/guides/icons.md - Every example is a complete module: real imports from the published packages and an exported `Demo` component. Fixtures it imports (`./data`) are shown beneath it. **Choosing between similar components** - On/off or pick-one input: `Switch` for a setting that applies immediately; `Checkbox` for a choice submitted with a form; `ControlField` wraps either (or `Radio`) in a labelled, pressable row; `SegmentedControl` for 2–5 exclusive options shown inline; `RadioGroup` for a vertical list; `Select` for a long list in a dropdown; `AutoComplete` when the list is searched or loaded async; `ToggleGroup` for toolbar-style single or multi selection. - Tabular data: `Table` for static semantic markup; `DataTable` for sorting, filtering, pagination and row selection; `DataList` for label/value pairs. - Dates and times: `DatePickerInput` / `TimePickerInput` for a form field that opens a picker; `DatePicker` / `TimePicker` for an inline panel; `Calendar` for a full month grid; `MiniCalendar` for a compact month view; `MonthPicker` / `YearPicker` for coarser choices. - Colors: `ColorInput` for a hex field plus palette; `ColorPicker` for a swatch button that opens a palette, with no text field; `ColorSwatch` to display a color. - Floating and transient UI: `Tooltip` for a non-interactive hint; `Popover` for interactive content anchored to a trigger; `Menu` for a list of actions; `ContextMenu` for right-click / long-press; `Dialog` for modal, confirmation or bottom-sheet content; `Toast` (via `useToast()`) for a transient notice; `Alert` for a message that stays inline. - Loading states: `Loader` for a spinner; `Skeleton` for placeholders shaped like the content; `Progress` (linear) or `Ring` (radial) for measurable progress; `LoadingOverlay` to block a region while work runs. - Labels and markers: `Badge` for a status, category or count; `Chip` for a tag the user selects, presses or removes; `Indicator` for a dot or count pinned to the corner of another element. - Containers: `Block` for plain layout; `Card` for a content card (six variants); `Surface` for an elevation level without card chrome; `Space` for a fixed gap where margins do not fit. - Text: `Text` for body copy and inline variants; `Title` for semantic headings (`order={1..6}`); `Highlight` to mark matches in a string; `GradientText` / `ShimmerText` for decorative emphasis. - Actions and navigation: `Button` for actions; `IconButton` for icon-only actions (needs `accessibilityLabel`); `Link` for navigation; `Menu` for several related actions behind one trigger; `Tabs`, `Stepper`, `Pagination`, `Breadcrumbs` and `NavTree` for moving between views. ================================================================================ # GUIDES # Getting started Install plocks, wire up the provider, and render your first component. Docs: https://plocks.dev/getting-started **Prerequisites:** - [Node.js 20.19.4 or newer](https://nodejs.org/en/download) — An active LTS release (22.x or 24.x) is the safest choice - [npm 10 or newer](https://www.npmjs.com) — Bundled with Node.js ## Install with npm Add [@plocks/ui](https://www.npmjs.com/package/@plocks/ui) to your React Native or Expo project: ```bash npm install @plocks/ui ``` Date pickers, charts, code blocks, media players, the carousel, Spotlight, brand logos, QR codes and emoji picking are separate packages — @plocks/dates, @plocks/charts, @plocks/code, @plocks/media, @plocks/carousel, @plocks/spotlight, @plocks/brands, @plocks/qrcode and @plocks/emoji-picker. Install the ones you use. ## Install the peer dependencies plocks builds on a handful of packages your app provides. On Expo, install them with expo install so the versions match your SDK: ```bash npx expo install \ react-native-reanimated \ react-native-safe-area-context \ react-native-svg ``` ## Set up the provider Wrap your root component with PlocksProvider to enable theming: `App.tsx` ```tsx import { PlocksProvider } from '@plocks/ui'; import { YourApp } from './YourApp'; export function Demo() { return ( ); } ``` ## Verify the install Render a component to confirm everything is wired up: `TestComponent.tsx` ```tsx import { Text, Button, Block } from '@plocks/ui'; export function Demo() { return ( ; } export default function App() { return ( ); } ``` ## Custom theme Pass `theme` to change tokens. A partial override is merged onto the built-in theme of the current scheme, so light/dark switching keeps working; an override with an explicit `colorScheme` pins that scheme; a `{ light, dark }` pair gives each scheme its own override. Color ramps have ten shades with the base color at index 5 — light ramps run lightest to darkest, dark ramps darkest to lightest — so a brand palette needs one ramp per scheme. Keep the theme object stable (a module constant or `useMemo`): resolved themes are cached per object. `App.tsx` ```tsx import type { ReactNode } from 'react'; import { DARK_THEME, DEFAULT_THEME, PlocksProvider, createTheme } from '@plocks/ui'; const theme = { light: createTheme({ colors: { ...DEFAULT_THEME.colors, primary: ['#F5F3FF', '#EDE9FE', '#DDD6FE', '#C4B5FD', '#A78BFA', '#7C3AED', '#6D28D9', '#5B21B6', '#4C1D95', '#2E1065'], }, }), dark: createTheme({ colors: { ...DARK_THEME.colors, primary: ['#1E1033', '#2E1065', '#4C1D95', '#5B21B6', '#6D28D9', '#7C3AED', '#8B5CF6', '#A78BFA', '#C4B5FD', '#DDD6FE'], }, }), }; export default function App({ children }: { children: ReactNode }) { return {children}; } ``` ## Reading tokens `useTheme()` returns the active `PlocksTheme` — outside a provider it quietly returns `DEFAULT_THEME`. Prefer component props (`color`, `bg`, `p`, `radius`) over reading tokens; reach for the theme when styling your own primitives. `theme.spacing`, `theme.radii` and `theme.fontSizes` hold CSS pixel strings such as `'16px'`, not numbers. `Callout.tsx` ```tsx import { Block, Text, useTheme } from '@plocks/ui'; export function Callout({ children }: { children: string }) { const theme = useTheme(); return ( {children} ); } ``` ## Elevation Express depth with `Surface` rather than hand-picked backgrounds: `level={0..3}` runs page → resting content (cards, panels) → floating content (menus, popovers) → screen-level content (dialogs, sheets, toasts), and `raised` takes the enclosing Surface's level plus one. Light mode shows elevation mostly with shadow, dark mode with a lighter fill and a hairline border. ## Provider props `PlocksProvider` also mounts the overlay layer, i18n, direction, haptics, reduced motion and a safe-area provider; each has an opt-out below. ```ts export interface PlocksProviderProps { /** Your application */ children: React.ReactNode; /** * Custom theme. Either: * - a partial override — merged onto the built-in theme of the CURRENT color * scheme, so it keeps light/dark switching (`colorSchemeMode`, OS setting); * in a nested provider, merged onto the parent's theme (see `inherit`); * - an override with an explicit `colorScheme` — pins that scheme; * - a `{ light, dark }` pair — each side merged onto the matching built-in * theme and picked by the current scheme. * * Keep the object stable (module constant or memoized): resolved themes are * cached per object. */ theme?: PlocksThemeOverride | PlocksThemePair; /** * Nested providers: merge a partial `theme` onto the parent provider's theme * (default) rather than onto the built-in one. */ inherit?: boolean; /** * Whether to inject CSS variables. The root provider writes them to `:root`; * a nested one only when given its own `cssVariablesSelector`. */ withCSSVariables?: boolean; /** * Render `text` / `backgrounds` / `surfaces` as CSS `var()` references instead * of literal colors (web only, opt-in). * * Pair it with `createThemeColorVariablesCss` inlined in the document head: * statically rendered markup then answers to `prefers-color-scheme` on its * own, so a prerendered page is already in the reader's scheme at first paint * rather than after hydration. Off by default — the rewritten values are CSS * strings, so anything that hands a theme color to a non-CSS consumer (SVG * attributes, Animated interpolation) has to read `literalColors` instead. */ colorsAsCssVariables?: boolean; /** CSS selector where variables should be applied */ cssVariablesSelector?: string; /** * Color scheme mode: * - 'auto': automatically follows OS preference * - 'light': force light mode * - 'dark': force dark mode * * Default `'auto'` at the root; a nested provider follows its parent's scheme. */ colorSchemeMode?: 'auto' | 'light' | 'dark'; /** Root provider only. Whether to enable overlay system (menus, tooltips, etc.) */ withOverlays?: boolean; /** Root provider only. Inject the global web CSS (keyboard focus ring, text-input reset). */ withGlobalCSS?: boolean; /** * Root provider only. Mount a `SafeAreaProvider` so Dialog, the dropdown * sheets and AppShell keep clear of the notch and the home indicator. Skipped * when one is already above (Expo Router's, or your own), so you rarely need * to set this — pass `false` to leave the tree without one. */ withSafeAreaProvider?: boolean; /** * Root provider only. Persist and switch the color-scheme mode; read and set * it with `useThemeMode()`. */ themeModeConfig?: ThemeModeConfig; /** Root provider only. i18n: initial active locale */ locale?: string; /** Root provider only. i18n: fallback locale */ fallbackLocale?: string; /** Root provider only. i18n: resources map */ i18nResources?: I18nResources; /** Direction context configuration (pass false to opt out at the root) */ direction?: false | DirectionProviderConfig; /** Root provider only. Haptics context configuration (pass false to opt out) */ haptics?: false | HapticsProviderConfig; /** * Reduced motion for every library animation: * - `'system'` (default at the root): follow the OS setting * - `true` / `false`: force it on / off (e.g. an in-app setting, screenshots) * Omitted in a nested provider: inherit the parent's setting. */ reducedMotion?: ReducedMotionSetting; } ``` ## Theme object `useTheme()` returns a `PlocksTheme` with these top-level groups: - `primaryColor` — Primary color used for buttons, links, etc. - `colorScheme` — Color scheme - `designTokens` — Design tokens for consistent styling - `colors` — Colors palette - `text` — Semantic text colors - `backgrounds` — Semantic background & surface colors - `literalColors` — The literal colors behind `text`, `backgrounds` and `surfaces` when those have been rewritten to CSS `var()` references for the web — see `withCssVariableColors`. - `surfaces` — Elevation ladder consumed by `Surface` (and, through it, Card, Menu, Popover, Dialog…). - `textRoles` — Typography for titles and group labels (see `TextRoleName`), read through `resolveTextRole` and `Text`'s `textRole` prop. - `states` — Semantic interactive state colors - `fontFamily` — Font family - `fontFamilyMono` — Monospace font family (code, kbd, tabular numbers). - `controlSizes` — The control-size table used by Button, IconButton, Input and every other fixed-height control — read it through `getControlSize(theme, size)`. - `zIndices` — Stacking layers for overlays and sticky chrome — read through `getZIndex(theme, layer)`. - `fontSizes` — Font sizes - extended with new size system - `spacing` — Spacing values - extended with new size system - `radii` — Border radius values - extended with new size system - `shadows` — Shadows - `breakpoints` — Breakpoints for responsive design - `motion` — Motion tokens for animations - `components` — Component default props and styles (override point) - `other` — Any additional custom theme properties (see `PlocksThemeOther`) ## Types ```ts export interface PlocksThemePair { light?: PlocksThemeOverride; dark?: PlocksThemeOverride; } export interface ThemeModeConfig { /** Initial color scheme mode */ initialMode?: ColorSchemeMode; /** Custom persistence functions (optional) */ persistence?: { get: () => ColorSchemeMode | null; set: (mode: ColorSchemeMode) => void; }; /** Custom DOM manipulation (web only, optional) */ domConfig?: { selector: string; lightClass: string; darkClass: string; attribute: string; }; } // Returned by useThemeMode() interface ThemeModeContextValue { mode: ColorSchemeMode; setMode: (mode: ColorSchemeMode) => void; cycleMode: () => void; actualColorScheme: 'light' | 'dark'; // resolved value (no 'auto') } export function useTheme(): PlocksTheme; export function useThemeMode(): ThemeModeContextValue; export function createTheme(themeOverride: PlocksThemeOverride): PlocksThemeOverride; ``` -------------------------------------------------------------------------------- # Shared props and tokens Component pages list each component's own props, then name the shared groups it also accepts in one line — "Also accepts the shared props — field (…), spacing (…), …". The groups are defined here once. ## Style props Every component takes the style props — spacing (`m`, `px`, …) and box props (`w`, `h`, `miw`, `maw`, `mih`, `mah`, `bg`, `opacity`) — plus the visibility props and `style` / `testID` (the base group). They apply to the component's root. Many also take `radius` and `shadow`. Values are theme tokens or numbers: `p="md"`, `mt={12}`, `w="full"`, `bg="subtle"`. Horizontal spacing (`ml`, `pl`, …) follows the leading and trailing edges, so it flips in right-to-left layouts. Each prop has only its short name — there is no `maxWidth` or `backgroundColor` spelling. ```tsx import { Card, Text } from '@plocks/ui'; export function Demo() { return ( Spacing, size, background, radius and shadow come from the shared style props. ); } ``` ```ts export interface SpacingProps { /** Margin on all sides */ m?: SpacingValue; /** Margin top */ mt?: SpacingValue; /** Margin on the trailing edge (right in LTR, left in RTL) */ mr?: SpacingValue; /** Margin bottom */ mb?: SpacingValue; /** Margin on the leading edge (left in LTR, right in RTL) */ ml?: SpacingValue; /** Margin horizontal (both inline edges) */ mx?: SpacingValue; /** Margin vertical (top and bottom) */ my?: SpacingValue; /** Padding on all sides */ p?: SpacingValue; /** Padding top */ pt?: SpacingValue; /** Padding on the trailing edge (right in LTR, left in RTL) */ pr?: SpacingValue; /** Padding bottom */ pb?: SpacingValue; /** Padding on the leading edge (left in LTR, right in RTL) */ pl?: SpacingValue; /** Padding horizontal (both inline edges) */ px?: SpacingValue; /** Padding vertical (top and bottom) */ py?: SpacingValue; } export interface BoxProps { /** Width */ w?: DimensionProp; /** Height */ h?: DimensionProp; /** Minimum width */ miw?: DimensionProp; /** Maximum width */ maw?: DimensionProp; /** Minimum height */ mih?: DimensionProp; /** Maximum height */ mah?: DimensionProp; /** * Background: a `theme.backgrounds` token (`'surface'`, `'subtle'`, * `'elevated'`…), a palette name (its subtle tint), `'primary.5'` shade * syntax, or any CSS color. */ bg?: ThemeColor; /** Opacity, `0`–`1` */ opacity?: number; } export interface BorderRadiusProps { /** Border radius value - supports size tokens, numbers, and special values */ radius?: RadiusValue; } export interface ShadowProps { /** Shadow value - supports size tokens and 'none' */ shadow?: ShadowValue; } export interface VisibilityProps { /** Do not render in the light color scheme. */ lightHidden?: boolean; /** Do not render in the dark color scheme. */ darkHidden?: boolean; /** Do not render when the viewport is at least this breakpoint wide (`width >= theme.breakpoints[bp]`). */ hiddenFrom?: BreakpointToken; /** Render only when the viewport is at least this breakpoint wide. */ visibleFrom?: BreakpointToken; } export type BaseProps = StyleProps & VisibilityProps & { /** Style for the root element — merged last, after the component's own styles. */ style?: StyleProp; /** Test identifier for the root element. */ testID?: string; }; ``` `DimensionProp` is a number (dp / px), a percentage such as `'50%'`, `'auto'`, `'full'` (100%), or on web any CSS length. ## Field props Form inputs — `Input`, `Select`, `Checkbox`, `Radio`, `Switch`, the pickers and the rest — share one field frame: label, description, error and helper text wired to the control for assistive technology. Text inputs add the text-field group (`value`, `onChangeText`, `placeholder`, `clearable`, sections). Inside a `Form.Field`, value, change handler and error are injected for you. ```ts export interface FieldBaseProps extends BaseProps, LayoutProps, DisclaimerSupport { /** Label rendered above (or beside) the control. */ label?: React.ReactNode; /** Short description rendered under the label. */ description?: React.ReactNode; /** Error message. Marks the field invalid and is announced to assistive technology. */ error?: React.ReactNode; /** Helper text rendered under the control when there is no error. */ helperText?: React.ReactNode; /** Marks the field required (announced; shows an asterisk unless `withAsterisk` is false). */ required?: boolean; /** Show the required asterisk. Defaults to `required`. */ withAsterisk?: boolean; disabled?: boolean; readOnly?: boolean; size?: SizeValue; radius?: RadiusValue; variant?: FieldVariant; /** Field name for form integration. */ name?: string; /** Overrides the accessible name composed from `label`. */ accessibilityLabel?: string; accessibilityHint?: string; /** Identifier used with KeyboardManagerProvider to request refocus. */ keyboardFocusId?: string; /** Props applied to the label ``. */ labelProps?: Omit; /** Props applied to the description ``. */ descriptionProps?: Omit; onFocus?: () => void; onBlur?: () => void; } export interface TextFieldBaseProps extends FieldBaseProps { value?: string; defaultValue?: string; onChangeText?: (text: string) => void; placeholder?: string; /** Falls back to `theme.text.muted`. */ placeholderTextColor?: string; /** Show a clear button while the field has a value. */ clearable?: boolean; clearButtonLabel?: string; onClear?: () => void; /** Debounce delay for validation, in milliseconds. */ debounceMs?: number; /** Called when Enter is pressed. */ onEnter?: () => void; startSection?: React.ReactNode; endSection?: React.ReactNode; startSectionProps?: Omit; endSectionProps?: Omit; } export interface DisclaimerSupport { disclaimer?: React.ReactNode; disclaimerProps?: Omit; } ``` ## Chart props Every chart in `@plocks/charts` accepts the chart group (size, title, legend, tooltip, animation and accessibility options) and the chart event callbacks, on top of its own data props. ```ts export interface BaseChartProps extends SpacingProps { /** * Chart width in px. Omit it and the chart fills the box it is placed in, * redrawing when that box changes. A number is honoured up to the width the * container can actually give it — a chart never draws wider than its slot. */ w?: number; /** Chart height in px. Defaults to the chart's resting height, or `width / aspectRatio`. */ h?: number; /** * Height as a fraction of the resolved width (`width / height`), used when * `height` is omitted. `2` keeps the chart twice as wide as it is tall at * every container size. */ aspectRatio?: number; /** Upper bound on the resolved width. Useful for radial charts in wide columns. */ maw?: number; /** Lower bound on the resolved width. */ miw?: number; /** Upper bound on a height derived from `aspectRatio`. */ mah?: number; /** Lower bound on a height derived from `aspectRatio`. */ mih?: number; /** Chart test ID for testing */ testID?: string; /** Additional styles */ style?: any; /** Accessibility label surfaced to assistive tech */ accessibilityLabel?: string; /** Accessibility hint describing chart interaction */ accessibilityHint?: string; /** Accessibility role override */ accessibilityRole?: string; /** Whether the chart container is accessible */ accessible?: boolean; /** Platform specific accessibility importance */ importantForAccessibility?: 'auto' | 'yes' | 'no' | 'no-hide-descendants'; /** Animation duration in ms */ animationDuration?: number; /** Animation easing function */ animationEasing?: string; /** Whether chart is disabled */ disabled?: boolean; /** Chart title */ title?: string; /** Chart subtitle */ subtitle?: string; /** If false, chart expects a parent interaction provider (shared context). */ useOwnInteractionProvider?: boolean; /** Force suppress or show internal popover (auto suppressed when useOwnInteractionProvider=false if undefined). */ suppressPopover?: boolean; } export interface ChartInteractionCallbacks { /** Called when chart is tapped/clicked */ onPress?: (event: ChartInteractionEvent) => void; /** Called when data point is selected */ onDataPointPress?: (dataPoint: TData, event: ChartInteractionEvent) => void; } ``` The option types those props take — a chart's own data types are on its page: ```ts export interface ChartDataPoint { /** Unique identifier for the data point */ id?: string | number; /** X-axis value */ x: number; /** Y-axis value */ y: number; /** Optional label */ label?: string; /** Optional color override */ color?: string; /** Optional size override */ size?: number; /** Custom data for interactions */ data?: any; } export interface ChartAxis { /** Show axis line */ show?: boolean; /** Axis color */ color?: string; /** Axis thickness */ thickness?: number; /** Show tick marks */ showTicks?: boolean; /** Tick positions (auto-calculated if not provided) */ ticks?: number[]; /** Tick color */ tickColor?: string; /** Tick length */ tickLength?: number; /** Show labels */ showLabels?: boolean; /** Label formatter */ labelFormatter?: (value: number) => string; /** Label color */ labelColor?: string; /** Label font size */ labelFontSize?: number; /** Axis title */ title?: string; /** Title color */ titleColor?: string; /** Title font size */ titleFontSize?: number; } export interface ChartGrid { /** Show grid */ show?: boolean; /** Grid color */ color?: string; /** Grid line thickness */ thickness?: number; /** Grid line style */ style?: 'solid' | 'dashed' | 'dotted'; /** Show major grid lines */ showMajor?: boolean; /** Show minor grid lines */ showMinor?: boolean; /** Major grid positions */ majorLines?: number[]; /** Minor grid positions */ minorLines?: number[]; } export interface ChartLegend { /** Show legend */ show?: boolean; /** Legend position */ position?: 'top' | 'bottom' | 'left' | 'right'; /** Legend alignment */ align?: 'start' | 'center' | 'end'; /** Legend items (auto-generated if not provided) */ items?: ChartLegendItem[]; /** Legend item color */ textColor?: string; /** Legend item font size */ fontSize?: number; } export interface ChartTooltip { /** Show tooltip on hover/press */ show?: boolean; /** Tooltip formatter */ formatter?: (dataPoint: TData) => string | React.ReactNode; /** Tooltip background color */ backgroundColor?: string; /** Tooltip text color */ textColor?: string; /** Tooltip font size */ fontSize?: number; /** Tooltip border radius */ borderRadius?: number; /** Tooltip padding */ padding?: number; } export interface ChartAnimation { /** Animation duration */ duration?: number; /** Animation delay */ delay?: number; /** Animation easing */ easing?: string; /** Animation type */ type?: 'fade' | 'scale' | 'slide' | 'draw' | 'drawOn' | 'spiral' | 'bounce' | 'elastic' | 'wave'; /** Stagger animation for multiple elements */ stagger?: number; } export interface ChartAnnotation { /** Unique identifier for the annotation */ id: string | number; /** Visual shape used to render the annotation */ shape: ChartAnnotationShape; /** X coordinate for point or vertical-line annotations */ x?: number; /** Y coordinate for point or horizontal-line annotations */ y?: number; /** Starting x coordinate for range or box annotations */ x1?: number; /** Ending x coordinate for range or box annotations */ x2?: number; /** Starting y coordinate for range or box annotations */ y1?: number; /** Ending y coordinate for range or box annotations */ y2?: number; /** Label displayed near the annotation */ label?: string; /** Stroke or outline color used for the annotation */ color?: string; /** Fill color used for the annotation */ backgroundColor?: string; /** Overall opacity of the annotation */ opacity?: number; /** Stroke width for line-based annotations */ lineWidth?: number; /** Dashed stroke pattern for the annotation */ dashArray?: number[]; /** Font size for any annotation text */ fontSize?: number; /** Text color for the annotation label */ textColor?: string; /** Arbitrary additional data associated with the annotation */ data?: any; } export type ChartFill = string | ChartGradient; ``` ## Token types ```ts /** Size tokens, smallest to largest (also exported as `ComponentSize`). */ export type SizeToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'; /** `SizeValue` is the same type. A number is read in px. */ export type ComponentSizeValue = SizeToken | number; export type SpacingValue = SizeToken | 'auto' | '0' | number; export type DimensionProp = number | 'auto' | 'full' | `${number}%` | (string & {}); export type RadiusValue = SizeToken | 'none' | 'full' | number; export type ShadowValue = | SizeValue | 'none'; export type ThemeColorToken = | 'primary' | 'secondary' | 'tertiary' | 'success' | 'warning' | 'error' | 'gray'; export type ThemeColor = ThemeColorToken | (string & {}); export type BreakpointToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl'; ``` -------------------------------------------------------------------------------- # Icons `@plocks/ui@0.2.0` registers 216 icons by default, using bundled Tabler-derived glyphs. These are the only strings `name` accepts out of the box — anything else renders nothing, so **do not guess an icon name**; pick one from this list or pass a component instead. ```tsx import { Icon, IconButton } from '@plocks/ui'; // Not in the registry? Pass any icon component or element instead: import { IconRocket } from '@tabler/icons-react-native'; ``` There is no public API for registering additional names — `registerIcon` / `registerIcons` exist in the source but are not exported from the package root or from `@plocks/ui/Icon`. Pass a component for anything outside this list. ## Names accordion, alert-circle, alignCenter, alignJustify, alignLeft, alignRight, arrow-down, arrow-left, arrow-right, arrow-up, arrowDown, arrowLeft, arrowRight, arrowUp, autocomplete, avatar, badge, bar-chart, bell, block, bluetooth, bold, bolt, bone, bookmark, breadcrumbs, button, calendar, camera, card, carousel, cart, chart-area, chart-bar, chart-donut, chart-heatmap, chart-line, chart-pie, chart-scatter, chart-sparkline, chat, check, chevron-down, chevron-left, chevron-right, chevron-up, chevronDown, chevronLeft, chevronRight, chevrons-up-down, chevronUp, chip, circle, clock, close, code, cog, color, colors, compress, container, contrast, copy, database, datatable, delete, dialog, divider, dots, download, edit, ellipsis, ellipsis-h, email, emoji, error, exclamation, expand, external-link, eye, eyeOff, file, filter, flag, flex, folder, font, form, funnel, gallery, globe, grid, guitar, heading, headphones, heart, highlight, home, hook, image, image-off, indicator, info, input, italic, keyboard, keycap, knob, knobs, layer-mask, layers, line-chart, linechart, link, list, listOrdered, listUnordered, loader, loading, location, lock, mail, map, markdown, masonry, menu, message, message-circle, mic, microphone, minus, moon, music, number, package, paddingFrame, pagination, palette, paper, pause, person, phone, piano, pin, plan, play, plus, popover, progress, progress-shield, qrcode, question, quote, radio, rating, record, redo, refresh, repeat, richtext, rocket, rotate, save, search, select, selector-vertical, selectorVertical, settings, share, sheild, shop, slider, smile, sort, sparkles, speedometer, splitTrack, spoiler, spotlight, star, stepper, stop, strikethrough, success, sun, support, switch, table, tableofcontents, tabs, target, text, textarea, timeline, times, title, toast, toggle, toggleOff, toggleOn, tooltip, trash, tree, tuning, underline, undo, upload, user, volume-off, volume-up, volumeOff, warning, waveform, web, wifi, x -------------------------------------------------------------------------------- # COMPONENTS # Accordion The Accordion component groups related content into expandable sections. `import { Accordion } from '@plocks/ui';` · Full page: https://plocks.dev/llms/components/Accordion.md ## Props - `items` (required): AccordionItem[] — Ordered list of items to render. - `type`: 'single' | 'multiple' = 'single' — Expansion behavior. 'single' ensures only one item can be… - `defaultExpanded`: string[] = [] — Initial expanded item keys (uncontrolled). - `expanded`: string[] — Controlled set of expanded item keys. - `onExpandedChange`: (expanded: string[]) => void — Called when the expanded keys change (both controlled &… - `onItemToggle`: OnAccordionToggle — Per-item toggle event with rich metadata. - `variant`: 'default' | 'separated' | 'bordered' = 'default' — Visual variant style preset. - `size`: SizeValue = 'md' — Size scale controlling paddings, font sizes, and icon… - `color`: ThemeColor = undefined — Brand accent applied to the expanded item (title, chevron,… - `showChevron`: boolean = true — Whether to render the chevron affordance. - `chevronPosition`: 'start' | 'end' = 'end' — Chevron placement relative to the header text. - `density`: 'comfortable' | 'compact' | 'spacious' = 'comfortable' — Space efficiency / vertical density preset. - `radius`: RadiusValue — Corner radius of the `separated` items / `bordered` frame:… - `persistKey`: string — Explicit persistence key. - `autoPersist`: boolean = true — Enables persistence of expanded state (uncontrolled only)… - `animated`: AccordionAnimationProp = true — Enables animation or accepts a config object for custom… - `transitionDuration`: number = 220 — Length of the expand/collapse transition (chevron spin +… - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` Also: `headerStyle` `contentStyle` `headerTextStyle` `titleProps` Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Example ### Basics Allow only one item to open at a time by setting `type="single"` and passing an items array. ```tsx import { Accordion } from '@plocks/ui'; import { faqItems } from '../data'; export function Demo() { return ; } ``` `data.ts` ```ts import React from 'react'; import { Text } from '@plocks/ui'; import type { AccordionItemType } from '@plocks/ui'; // Wrap body copy in without JSX so this stays a plain `.ts` data module // (a `.tsx` sibling would be picked up as its own demo by the docs generator). const body = (text: string) => React.createElement(Text, { size: 'sm' }, text); export const faqItems: AccordionItemType[] = [ { key: 'foundation', title: 'What is plocks?', content: body('A cross-platform design system for shipping polished React Native apps faster.'), }, { key: 'benefits', // … 85 more lines — full file: https://github.com/platform-blocks/plocks/blob/main/packages/ui/src/components/Accordion/demos/data.ts ``` 4 more examples on the full page. -------------------------------------------------------------------------------- # ActionBar Use ActionBar for actions that apply to selected content. `import { ActionBar } from '@plocks/ui';` · Status: beta · Full page: https://plocks.dev/llms/components/ActionBar.md ## Props - `children`: React.ReactNode — Actions rendered in the bar. - `opened` (required): boolean — Controls visibility. - `onClose`: () => void — Called by the close button or Escape when enabled. - `closeOnEscape`: boolean = false — Let Escape dismiss this bar once layers above it close. - `keepMounted`: boolean = false — Preserve the hidden bar in the tree. - `withinPortal`: boolean = true — Render at the application root. - `position`: { top?: number; bottom?: number; start?: number; end?: number } = { bottom: 24 } — Logical viewport insets. - `radius`: RadiusValue = 'md' — Corner radius. @default 'md' - `shadow`: ShadowToken = 'md' — Surface shadow. @default 'md' - `withBorder`: boolean = true — Draw a border. @default true - `zIndex`: number — Stack order. - `transition`: 'pop' | 'slide-up' | 'fade' = 'pop' — Entrance effect. @default 'pop' - `transitionDuration`: number = 200 — Animation duration in ms. - `aria-label`: string = 'Actions' — Accessible group label. - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Sub-components `import { ActionBarDivider, ActionBarCloseButton } from '@plocks/ui';` ### ActionBarDivider - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### ActionBarCloseButton - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### ActionBar.CloseButton - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### ActionBar.Divider - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Example ### Keep Mounted `keepMounted` preserves child state while the bar is hidden. ```tsx import { useState } from 'react'; import { ActionBar, Block, Button, Checkbox } from '@plocks/ui'; export function Demo() { const [opened, setOpened] = useState(false); return ( setOpened(false)} keepMounted> ); } ``` 4 more examples on the full page. -------------------------------------------------------------------------------- # Alert Alert displays prominent messages with severity styles and optional actions. `import { Alert } from '@plocks/ui';` · Full page: https://plocks.dev/llms/components/Alert.md ## Props - `variant`: 'light' | 'filled' | 'outline' | 'subtle' = 'light' - `color`: ThemeColor = 'primary' — Accent color. Without a `severity`, `error` / `warning`… - `severity`: 'info' | 'success' | 'warning' | 'error' — Severity helper — sets the color, the default icon, and… - `title`: string - `children`: React.ReactNode - `icon`: React.ReactNode | string | null | false - `fullWidth`: boolean = false - `withCloseButton`: boolean = false - `closeButtonLabel`: string = 'Close' — Accessible name of the close button. - `onClose`: () => void - `radius`: RadiusValue = 'md' — Corner radius: theme radius token, px, `'none'` or `'full'`. - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` Also: `titleProps` `bodyProps` Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Example ### Basics Use `severity` to set it — it picks the matching color and icon automatically. ```tsx import { Alert, Block } from '@plocks/ui'; export function Demo() { return ( Use alerts to highlight contextual information inline with page content. Your changes were stored successfully. Retry the action or check the status page for outages. ); } ``` 2 more examples on the full page. -------------------------------------------------------------------------------- # AppShell AppShell arranges an app’s header, navigation, aside, footer, and mobile navigation in a responsive frame. `import { AppShell } from '@plocks/ui';` · Full page: https://plocks.dev/llms/components/AppShell.md ## Props - `layout`: 'default' | 'alt' = 'default' — `'default'`: the header spans the full width and the… - `header`: HeaderConfig - `navbar`: NavbarConfig - `aside`: AsideConfig - `footer`: FooterConfig - `bottomNav`: BottomNavConfig - `showHeader`: boolean = true - `layoutSections`: LayoutVisibilityConfig — Toggle rendering of individual autoLayout sections - `autoLayout`: boolean — Enable AppShell auto-composition. - `headerContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Header when autoLayout… - `navbarContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Navbar when autoLayout… - `asideContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Aside when autoLayout is… - `footerContent`: React.ReactNode | (() => React.ReactNode) — Content to render inside AppShell.Footer when autoLayout… - `bottomNavItems`: BottomAppBarItem[] — Items for a mobile bottom navigation bar when autoLayout… - `mobileMenu`: MobileMenuConfig - `cssGeometry`: boolean = false — Take the shell's geometry from CSS custom properties… - `statusBar`: StatusBarConfig - `padding`: ResponsiveSize = no padding — Padding inside the main content area: a spacing token… - `withBorder`: boolean = true — Default `withBorder` for every section. - `zIndex`: number = each section's `theme.zIndices` layer — Stacking order for every section that doesn't set its own. - `transitionDuration`: number = 200 — Navbar/content transition length in ms (`0` = instant). - `transitionTimingFunction`: string = a cubic ease-in-out — CSS timing function for the navbar/content transitions:… - `disabled`: boolean = false - `children` (required): React.ReactNode - `withSafeArea`: boolean = true - `maxContentWidth`: number | string — Maximum width for main content area to prevent stretching… - `centerContent`: boolean — Center content when maxContentWidth is set - `tableOfContents`: React.ReactNode — Optional table of contents rendered at the end side of the… - `hideTableOfContentsOnMobile`: boolean = true — Hide the table of contents automatically on mobile… - `tableOfContentsWidth`: number | string = 280 — Custom width for the table of contents column - `tableOfContentsWithBorder`: boolean = true — Toggle border between content and table of contents - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` Also: `bottomNavProps` Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Sub-components `import { AppShellHeader, AppShellNavbar, AppShellAside, AppShellFooter, AppShellBottomNav, AppShellMain, AppShellSection, BottomAppBar, StatusBarManager, AppLayoutProvider, AppLayoutRenderer, MobileMenu } from '@plocks/ui';` ### AppShellHeader - `children` (required): React.ReactNode - `withBorder`: boolean = AppShell `withBorder` - `zIndex`: number - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### AppShellNavbar - `drawerMode`: boolean - `accessibilityLabel`: string = 'Main' - `children` (required): React.ReactNode - `withBorder`: boolean = AppShell `withBorder` - `zIndex`: number - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### AppShellAside - `children` (required): React.ReactNode - `withBorder`: boolean = AppShell `withBorder` - `zIndex`: number - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### AppShellFooter - `children` (required): React.ReactNode - `withBorder`: boolean = AppShell `withBorder` - `zIndex`: number - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### AppShellBottomNav - `children`: React.ReactNode - `withBorder`: boolean - `zIndex`: number - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### AppShellMain - `children` (required): React.ReactNode - `id`: string - `role`: Role = 'main' - `maw`: number | string - `centerContent`: boolean - `tableOfContents`: React.ReactNode - `hideTocOnMobile`: boolean - `tocWidth`: number | string - `tocWithBorder`: boolean - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### AppShellSection - `children` (required): React.ReactNode - `grow`: boolean - `withScrollArea`: boolean - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### BottomAppBar - `items`: BottomAppBarItem[] - `activeKey`: string - `onItemPress`: (key: string) => void - `showLabels`: boolean - `variant`: 'solid' | 'surface' | 'elevated' | 'translucent' - `elevation`: number = 4 - `fab`: React.ReactNode - `children`: React.ReactNode - `withBorder`: boolean - `zIndex`: number - `accessibilityLabel`: string - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ### StatusBarManager - `children`: React.ReactNode - `style`: 'auto' | 'light' | 'dark' - `backgroundColor`: string - `translucent`: boolean - `hidden`: boolean ### AppLayoutProvider - `blueprint` (required): AppLayoutBlueprint - `value`: AppLayoutRuntimeOverrides - `children` (required): React.ReactNode ### AppLayoutRenderer - `children` (required): React.ReactNode ### MobileMenu - `opened`: boolean - `onClose` (required): () => void - `children`: React.ReactNode - `config`: MobileMenuConfig - `accessibilityLabel`: string = 'Menu' - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Related hooks - `useAppShell(): AppShellContextValue` — Returns the full state of the enclosing `AppShell` — resolved section sizes, navbar open/collapsed/rail flags, the current `breakpoint` and `isMobile`, and the `openNavbar` / `closeNavbar` / `toggleNavbar` controls — and throws when called outside an `AppShell`. - `useAppShellApi(): AppShellApi` — Returns just the enclosing `AppShell`'s navbar controls (`openNavbar`, `closeNavbar`, `toggleNavbar`) — for menu buttons and links that drive the navbar without re-rendering on layout changes — and throws when called outside an `AppShell`. - `useAppShellLayout(): AppShellLayoutValue` — Returns just the enclosing `AppShell`'s resolved section sizes (`headerHeight`, `navbarWidth`, `asideWidth`, `footerHeight`, `bottomNavHeight`) — for content that has to position itself around the shell chrome — and throws when called outside an `AppShell`. - `useBreakpoint(): Breakpoint` — Returns the current breakpoint name, from the theme's breakpoint table (`theme.breakpoints`, or a `BreakpointProvider` override): `base` below `xs` (480), then `xs`, `sm` (576), `md` (768), `lg` (992), `xl` (1200). - `useNavbarHover(): boolean` — Returns `true` while the pointer is over the `AppShell` navbar rail (web, with `navbar.expandOnHover` on) and `false` otherwise, including outside an `AppShell` — for navbar content that should show its labels only while the collapsed rail is hover-expanded. - `useAppLayoutContext(): AppLayoutProviderValue` — Returns the enclosing `AppLayoutProvider`'s value — the `defineAppLayout` `blueprint` plus the resolved `runtime` (`query`, `pathname`, `navigation`, `platform`, `meta`) — for custom renderers that read the layout the way `AppLayoutRenderer` does, and throws when called outside an `AppLayoutProvider`. ## Example ### Basics Arrange a header and page content inside a responsive app frame. ```tsx import { AppShell, Block, Text } from '@plocks/ui'; export function Demo() { return ( App header} autoLayout withSafeArea={false} > Page content ); } ``` 1 more example on the full page. -------------------------------------------------------------------------------- # AudioPlayer AudioPlayer combines audio playback controls with a seekable waveform. `import { AudioPlayer } from '@plocks/media';` · Status: beta · Full page: https://plocks.dev/llms/components/AudioPlayer.md ## Props - `source`: string | number | { uri: string } — Audio source - can be URL, local file, or asset - `peaks`: number[] — Pre-computed waveform peaks (optional - placeholder peaks… - `w`: number = 300 — Waveform width in px — not the player's, which fills its… - `h`: number = 60 — Waveform height in px. - `autoPlay`: boolean — Whether to auto-play when loaded - `loop`: boolean — Whether to loop the audio - `volume`: number — Initial volume (0-1) - `rate`: number — Playback rate (0.5-2.0) - `showControls`: boolean — Whether to show player controls - `controls`: AudioPlayerControls — Which controls to display; merged over the defaults. - `controlsPosition`: 'top' | 'bottom' | 'overlay' | 'none' — Where the controls sit: above or below the waveform, laid… - `onLoad`: (data: AudioLoadData) => void — Called when audio is loaded and ready - `onPlaybackStateChange`: (state: PlaybackState) => void - `onProgress`: (data: ProgressData) => void — Called during playback with current time - `onEnd`: () => void — Called when playback finishes - `onError`: (error: AudioError) => void — Called on playback error - `generateWaveform`: boolean — Draw placeholder peaks when `peaks` is omitted. - `waveformOptions`: { samples?: number; } — Placeholder waveform options - `showTime`: boolean — Show time labels - `timeFormat`: 'mm:ss' | 'hh:mm:ss' | 'relative' — Time format: `mm:ss`, `hh:mm:ss`, or `relative` (elapsed /… - `showMetadata`: boolean — Show audio metadata - `metadata`: AudioMetadata — Audio metadata - `enableKeyboardShortcuts`: boolean = true — Keyboard shortcuts while the waveform (seek slider) has… - `keyboardShortcuts`: KeyboardShortcuts — Override the shortcut keys (`KeyboardEvent.key` values,… - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` Plus the `Waveform` props: https://plocks.dev/llms/components/Waveform.md Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Example ### Basics Point `source` at a URL or a bundled clip and pass its `peaks` to draw the real waveform; the player handles loading, play/pause, seeking and progress. Playback requires `expo-audio`; without it the controls render but report a missing-module error. ```tsx import { AudioPlayer } from '@plocks/media'; import { Block } from '@plocks/ui'; const MELODY_PEAKS = [ 0.765, 0.683, 0.598, 0.528, 0.464, 0.407, 0.36, 0.316, 0.277, 0.243, 0.949, 0.876, 0.776, 0.698, 0.592, 0.533, 0.477, 0.407, 0.365, 0.323, 0.528, 0.922, 0.851, 0.738, 0.643, 0.569, 0.489, 0.438, 0.383, 0.34, 0.297, 0.954, 0.885, 0.798, 0.693, 0.606, 0.525, 0.468, 0.41, 0.354, 0.308, 0.925, 0.919, 0.828, 0.727, 0.64, 0.557, 0.474, 0.415, 0.376, 0.338, 0.297, 0.997, 0.869, 0.775, 0.667, 0.595, 0.51, 0.444, 0.408, 0.356, 0.316, 1, 0.872, 0.786, 0.691, 0.619, 0.555, 0.483, 0.4, 0.359, 0.322, 0.288, 0.941, 0.835, 0.748, 0.661, 0.588, 0.506, 0.439, 0.39, 0.342, 0.306, 0.272, 0.238, 0.203, 0.148, 0.13, 0.114, 0.101, 0.088, 0.078, 0.068, 0.06, 0.053, 0.047, ]; export function Demo() { return ( ); } ``` -------------------------------------------------------------------------------- # AutoComplete Provide search functionality with suggestions, supporting single/multi-select, async data loading, and rich content display. `import { AutoComplete } from '@plocks/ui';` · Full page: https://plocks.dev/llms/components/AutoComplete.md ## Props - `data`: AutoCompleteOption[] = EMPTY_OPTIONS — Data source for suggestions - `onSearch`: (query: string) => Promise — Async data fetcher - `minSearchLength`: number = 2 — Minimum characters to trigger search - `searchDelay`: number = 300 — Debounce delay for `onSearch`, in ms (local `data` filters… - `renderItem`: ( item: AutoCompleteOption, index: number, options: { query: string; onSelect: (item:… — Custom item renderer (the row stays an accessible option). - `onSelect`: (item: AutoCompleteOption) => void — Selection handler - `renderValue`: ( item: AutoCompleteOption, context: { focused: boolean; clear: () => void; } ) => React.ReactNode — Custom renderer for the selected option shown inside the… - `maxSuggestions`: number = 10 — Maximum number of suggestions to display (0 = no limit). - `showSuggestionsOnFocus`: boolean = true — Whether to show suggestions on focus (default: true) - `renderEmptyState`: () => React.ReactNode - `renderLoadingState`: () => React.ReactNode - `filter`: (item: AutoCompleteOption, query: string) => boolean = defaultFilter — Filter function for local data - `highlightMatches`: boolean = true — Whether to highlight matching text - `highlightColor`: string — Text color for the matched substring when… - `highlightBackgroundColor`: string = 'transparent' — Background color painted behind the matched substring… - `multiSelect`: boolean = false — Enable multi-select mode - `selectedValues`: AutoCompleteOption[] = EMPTY_OPTIONS — Selected values for multi-select mode - `renderSelectedValue`: ( item: AutoCompleteOption, index: number, context: { onRemove: () => void; disabled: boolean;… — Custom renderer for each selected value chip in… - `refocusAfterSelect`: boolean — Controls whether the input regains focus after selecting… - `freeSolo`: boolean = false — Whether to allow free-form input (Enter commits the typed… - `displayProperty`: 'label' | 'value' = 'label' — Which field of the selected option is written into the… - `useModal`: boolean — Present suggestions in a modal sheet (true) or an anchored… - `placement`: 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end' = 'bottom-start' — Placement preference for the suggestions dropdown… - `fallbackPlacements`: PlacementType[] = DEFAULT_FALLBACK_PLACEMENTS — Placements to try when the preferred one doesn't fit. - `offset`: number = 4 — Gap between the field and the dropdown, px (default: 4) - `flip`: boolean = true — Enable flipping to opposite side when dropdown would go… - `shift`: boolean = false — Enable shifting within bounds when dropdown would go… - `boundary`: number = 12 — Distance from viewport edges in pixels (default: 12) - `autoReposition`: boolean = true — Enable automatic repositioning on scroll/resize (default:… - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` Also: `testID` `suggestionsStyle` `suggestionItemStyle` `groupLabelProps` `selectedValuesContainerStyle` `selectedValueChipProps` `textInputProps` Also accepts the shared props — field (`label` `description` `error` `helperText` `required` `withAsterisk` `disabled` `readOnly` `size` `radius` `variant` `name` `accessibilityLabel` `accessibilityHint` `keyboardFocusId` `labelProps` `descriptionProps` `onFocus` `onBlur`), text field (`value` `defaultValue` `onChangeText` `placeholder` `placeholderTextColor` `clearable` `clearButtonLabel` `onClear` `onEnter` `startSection` `endSection` `startSectionProps` `endSectionProps`), base, spacing, sizing, visibility, disclaimer: https://plocks.dev/llms/guides/shared-props.md ## Example ### Variants Compare the default, filled, outline, and unstyled field shells on AutoComplete. ```tsx import { Column, AutoComplete } from '@plocks/ui'; const options = ['Apple', 'Banana', 'Cherry'].map(value => ({ label: value, value: value.toLowerCase() })); const variants = ['default', 'filled', 'outline', 'unstyled'] as const; export function Demo() { return ( {variants.map(variant => ( ))} ); } ``` 9 more examples on the full page. -------------------------------------------------------------------------------- # Avatar Displays user profile images, initials, or icons. `import { Avatar } from '@plocks/ui';` · Full page: https://plocks.dev/llms/components/Avatar.md ## Props - `size`: ComponentSizeValue = 'md' — Size of the avatar: a token or the diameter in px - `src`: string | ImageSourcePropType — Image for the avatar: a remote URL string or a bundled… - `fallback`: React.ReactNode — Fallback shown when no image is provided: initials string… - `bg`: ColorProp = theme.text.muted — Fill of the avatar circle — not the root, which also holds… - `textColor`: ColorProp = a readable color on the background — Text color for the fallback initials. - `online`: boolean — Whether to show online status indicator - `indicatorColor`: ColorProp — Color override for the status indicator - `accessibilityLabel`: string — Accessible name of the avatar ("Jane Doe"). - `label`: React.ReactNode — Primary label displayed beside the avatar (string or… - `description`: React.ReactNode — Secondary description/subtext under the label - `gap`: number = 8 — Spacing between avatar and text block (px) - `showText`: boolean = true — Force horizontal layout off (set false to hide… - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `opacity`: number — Opacity, `0`–`1` Also: `fallbackProps` `labelProps` `descriptionProps` Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Sub-components `import { AvatarGroup } from '@plocks/ui';` ### AvatarGroup - `children` (required): React.ReactNode - `limit`: number - `spacing`: number = -8 - `size`: ComponentSizeValue - `bordered`: boolean - `surplusTooltip`: string - `surplusLabel`: string = `${N} more` - `w`: DimensionProp - `h`: DimensionProp - `miw`: DimensionProp - `maw`: DimensionProp - `mih`: DimensionProp - `mah`: DimensionProp - `bg`: ThemeColor - `opacity`: number Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Example ### Basics Illustrates loading an avatar image with a reliable initials fallback for offline scenarios. ```tsx import { Avatar } from '@plocks/ui'; export function Demo() { return ( ); } ``` 6 more examples on the full page. -------------------------------------------------------------------------------- # BackgroundImage BackgroundImage places content over an image-filled container. `import { BackgroundImage } from '@plocks/ui';` · Status: beta · Full page: https://plocks.dev/llms/components/BackgroundImage.md ## Props - `w`: DimensionProp — Width - `h`: DimensionProp — Height - `miw`: DimensionProp — Minimum width - `maw`: DimensionProp — Maximum width - `mih`: DimensionProp — Minimum height - `mah`: DimensionProp — Maximum height - `bg`: ThemeColor — Background: a `theme.backgrounds` token (`'surface'`,… - `opacity`: number — Opacity, `0`–`1` - `radius`: RadiusValue — Border radius: a `theme.radii` token, px number, `'none'`… - `borderWidth`: number - `borderColor`: string - `borderTopWidth`: number - `borderRightWidth`: number - `borderBottomWidth`: number - `borderLeftWidth`: number - `borderTopColor`: string - `borderRightColor`: string - `borderBottomColor`: string - `borderLeftColor`: string - `borderTopLeftRadius`: number - `borderTopRightRadius`: number - `overflow`: ViewStyle['overflow'] - `aspectRatio`: number - `touchAction`: 'auto' | 'none' | 'pan-x' | 'pan-y' | 'manipulation' — Web touch gesture handling; useful for drag surfaces. - `translateY`: number — Small visual offset without affecting surrounding layout. - `rotate`: string — Rotation around the block center, such as `"45deg"`. - `shadow`: ShadowToken — Shadow: a `theme.shadows` token. - `fullWidth`: boolean — Whether to take full width (100%) - shorthand for… - `fluid`: boolean — Makes block take full available height (flex: 1) - useful… - `grow`: boolean | number — Flex grow - `shrink`: boolean | number — Flex shrink - `basis`: number | string — Flex basis - `direction`: 'row' | 'column' | 'row-reverse' | 'column-reverse' — Flex direction - `align`: 'stretch' | 'flex-start' | 'flex-end' | 'center' | 'baseline' — Align items - `alignSelf`: ViewStyle['alignSelf'] — Alignment of this block within its parent. - `justify`: 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly' — Justify content - `wrap`: boolean | 'nowrap' | 'wrap' | 'wrap-reverse' — Flex wrap - `gap`: number | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' — Gap between children (`theme.spacing` token or px). - `position`: 'relative' | 'absolute' — Position type - `top`: number | string — Top position - `right`: number | string — Right position (physical; use `end` to mirror in… - `bottom`: number | string — Bottom position - `left`: number | string — Left position (physical; use `start` to mirror in… - `inset`: number | string — Shorthand for all four physical insets. - `start`: number | string — Start inset (logical: left in LTR, right in RTL) - `end`: number | string — End inset (logical: right in LTR, left in RTL) - `zIndex`: number - `flex`: boolean | number — Whether to render as a flex container Also: `borderStyle` Plus the `Block` props: https://plocks.dev/llms/components/Block.md Plus the `Image` props: https://plocks.dev/llms/components/Image.md Also accepts the shared props — base, spacing, visibility: https://plocks.dev/llms/guides/shared-props.md ## Example ### Basics BackgroundImage places content over an image-filled container. ```tsx import { BackgroundImage, Text } from '@plocks/ui'; const image = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAgAAAAICAIAAABLbSncAAAALklEQVR42mNITvsIR409P+CIAasokMuAVRQqgSkKksAqiiKB5goGrKJQCawuBgC2Wnfh+zNA9wAAAABJRU5ErkJggg=='; export function Demo() { return ( Content over an image ); } ``` -------------------------------------------------------------------------------- # Badge Badge displays a compact status or count on a parent element. `import { Badge } from '@plocks/ui';` · Full page: https://plocks.dev/llms/components/Badge.md ## Props - `children` (required): React.ReactNode - `size`: ComponentSizeValue — Size token (the badge renders well below a control of the… - `variant`: 'filled' | 'outline' | 'light' | 'subtle' | 'gradient' = 'subtle' - `v`: 'filled' | 'outline' | 'light' | 'subtle' | 'gradient' — Shorthand alias for `variant`. - `color`: ColorProp — Badge color. A palette token, `'primary.6'` shade syntax,… - `c`: ColorProp — Shorthand alias for `color`, resolved identically. - `onPress`: () => void — Makes the badge a button. - `startSection`: React.ReactNode — Content (usually an icon) before the label. - `endSection`: React.ReactNode — Content (usually an icon) after the label. - `onRemove`: () => void — Show a remove (×) button that calls this. - `removePosition`: 'left' | 'right' — Which side the remove button sits on (`left`/`right`… - `removeButtonLabel`: string = `Remove