API reference: @pyric/ui/primitives

Interfaces

BadgeProps

Properties

Property	Type	Description
`ariaLabel?`	`string`	Accessible label. When set, the visible text becomes `aria-hidden` and screen readers announce this instead — useful when the badge is a terse glyph but the meaning is longer.
`children`	`ReactNode`	Badge content — usually a short word like “ALLOW” or “GET”.
`className?`	`string`	Forwarded to the underlying `<span>`.
`kind?`	`string`	Freeform category surfaced as `data-pyric-badge-kind`. The library doesn’t enumerate kinds — the consumer decides what values exist (`allow`, `deny`, `get`, `update`, …) and styles them via `[data-pyric-badge-kind="…"]`.

ConfirmDialogProps

Properties

Property	Type	Description
`body?`	`ReactNode`	Body content — explanation, consequences, paths affected.
`cancelLabel?`	`string`	-
`className?`	`string`	Forwarded to the content node so consumers can style.
`confirmLabel?`	`string`	-
`destructive?`	`boolean`	When `true`, the confirm button carries `data-pyric-destructive` so consumers can style it differently (e.g. red).
`onConfirm`	() => `void`	Fires when the user presses confirm. The component does NOT close itself on confirm — the consumer typically dismisses after the destructive action resolves.
`onOpenChange`	(`open`: `boolean`) => `void`	Called when the user dismisses via overlay click, Escape, or the cancel button. NOT called by `onConfirm`.
`open`	`boolean`	Controlled open state.
`title`	`string`	Heading.

ConfirmOptions

Properties

Property	Type
`body?`	`ReactNode`
`cancelLabel?`	`string`
`confirmLabel?`	`string`
`destructive?`	`boolean`
`title`	`string`

ConfirmProviderProps

Properties

Property	Type	Description
`children`	`ReactNode`	-
`dialogClassName?`	`string`	Forwarded to the rendered `<ConfirmDialog>`.

CopyButtonProps

Properties

Property	Type	Description
`ariaLabel?`	`string`	Forwarded as the button’s accessible label when in the idle state. Defaults to “Copy to clipboard”. The copied state uses a hard-coded “Copied” label so screen readers announce the state change consistently.
`children?`	`ReactNode`	Optional content to render inside the button. Defaults to a short text label that toggles between “Copy” and “Copied”.
`className?`	`string`	Forwarded to the underlying `<button>`. Consumers compose Tailwind classes, CSS-module classes, or whatever they want.
`resetMs?`	`number`	Milliseconds before the `data-copied` state attribute clears. Defaults to 2000.
`text`	`string`	Text to copy to the clipboard on click.

JsonViewProps

Properties

Property	Type	Description
`className?`	`string`	Forwarded to the root container.
`defaultCollapsedDepth?`	`number`	Depth at and below which object/array nodes start collapsed. `0` collapses the root, `1` collapses everything under the root, `Infinity` (default) leaves everything expanded.
`value`	`unknown`	Any JSON-serializable value.

SegmentedControlProps

Type Parameters

Type Parameter
`T` extends `string`

Properties

Property	Type	Description
`ariaLabel?`	`string`	Accessible label for the radiogroup.
`className?`	`string`	Forwarded to the container.
`onChange`	(`value`: `T`) => `void`	Fired with the new value when a segment is clicked.
`options`	readonly `SegmentedOption`<`T`>[]	The selectable segments, rendered left-to-right.
`value`	`T`	The currently-selected value.

SegmentedOption

Type Parameters

Type Parameter
`T` extends `string`

Properties

Property	Type	Description
`label`	`ReactNode`	Visible label.
`tone?`	`string`	Freeform tone surfaced as `data-pyric-segment-tone` — e.g. `ok` / `error` so the consumer can tint the active label. The library doesn’t enumerate tones.
`value`	`T`	The value committed via `onChange` when this segment is picked.

ToastInput

Extended by

ToastRecord

Properties

Property	Type	Description
`body?`	`ReactNode`	-
`duration?`	`number`	Auto-dismiss after this many ms. `0` makes the toast sticky; default is 5000.
`kind?`	`ToastKind`	-
`title`	`string`	-

ToastProviderProps

Properties

Property	Type	Description
`children`	`ReactNode`	-
`className?`	`string`	Forwarded to the rendered container.
`defaultDuration?`	`number`	Default auto-dismiss in ms. Per-toast `duration` overrides. Default 5000; pass `0` to make sticky-by-default.
`regionLabel?`	`string`	Region label for assistive tech. Defaults to “Notifications”.

ToastRecord

Extends

ToastInput

Properties

Property	Type	Description
`body?`	`ReactNode`	-
`duration?`	`number`	Auto-dismiss after this many ms. `0` makes the toast sticky; default is 5000.
`id`	`string`	-
`kind?`	`ToastKind`	-
`title`	`string`	-

UpdateHighlight

Properties

Property	Type
`cycle`	`0` \| `1`
`kind`	`UpdateHighlightKind`

UseContainerSizeOptions

Properties

Property	Type	Description
`mediumBreakpoint?`	`number`	Width (px) below which the bucket is `'medium'` (and above which it is `'wide'`). Default 768.
`narrowBreakpoint?`	`number`	Width (px) below which the bucket is `'narrow'`. Default 480.

UseUpdateHighlightsOptions

Type Parameters

Type Parameter
`T`

Properties

Property	Type
`durationMs?`	`number`
`entries`	`ReadonlyMap`<`string`, `T`>
`equals?`	(`previous`: `T`, `next`: `T`) => `boolean`
`ready?`	`boolean`
`scope`	`string`

VirtualListProps

Type Parameters

Type Parameter
`T`

Properties

Property	Type	Description
`className?`	`string`	Forwarded to the scroll container.
`estimateSize`	`number` \| (`index`: `number`) => `number`	Estimated row height in px. `useVirtualizer` measures actual rendered heights via ResizeObserver — this is just the guess used before measurement. Pass a function for variable sizing.
`getItemKey?`	(`item`: `T`, `index`: `number`) => `string` \| `number`	Optional `key` resolver. Defaults to the index. Use when rows reorder so React can preserve component state across moves.
`height?`	`string` \| `number`	Height the scroll container fills. Default `100%` — the consumer’s parent typically constrains height.
`items`	readonly `T`[]	-
`overscan?`	`number`	Number of off-screen rows to render on each side. TanStack default is 5; bump for smoother fast scrolling.
`renderItem`	(`item`: `T`, `index`: `number`) => `ReactNode`	Render one row. The library handles positioning + key-by-index.

Type Aliases

ConfirmFn()

type ConfirmFn = (options: ConfirmOptions) => Promise<boolean>;

Parameters

Parameter	Type
`options`	`ConfirmOptions`

Returns

Promise<boolean>

ContainerSize

type ContainerSize = "narrow" | "medium" | "wide";

ToastKind

type ToastKind = "info" | "success" | "warning" | "error";

UpdateHighlightKind

type UpdateHighlightKind = "added" | "modified";

Functions

Badge()

function Badge(__namedParameters: BadgeProps): Element;

Headless pill / tag. Renders an inline <span> carrying data-pyric-badge and (when kind is set) data-pyric-badge-kind so consumers can style categories with attribute selectors. Ships no visual styling of its own.

Parameters

Parameter	Type
`__namedParameters`	`BadgeProps`

Returns

Element

ConfirmDialog()

function ConfirmDialog(__namedParameters: ConfirmDialogProps): ReactPortal;

Headless confirmation dialog. Hand-rolled (we evaluated Radix Dialog at M4 but Radix’s Presence + Portal stack doesn’t render under our bun:test + JSDOM env — see plan section 7 risk #1).

Provides:

Portal to document.body (so the dialog can escape parent stacking contexts)
Escape-to-close
Overlay click to close
ARIA role="dialog" aria-modal="true" wiring
Focus restoration to the previously-focused element on close
Initial focus on the confirm button when opening

Ships no visual CSS. Consumers style via the structural data-pyric-* attributes.

Parameters

Parameter	Type
`__namedParameters`	`ConfirmDialogProps`

Returns

ReactPortal

ConfirmProvider()

function ConfirmProvider(__namedParameters: ConfirmProviderProps): Element;

Mounts a single managed <ConfirmDialog> and exposes the imperative confirm() API through context. Scoped — multiple providers can coexist in different subtrees, each managing its own dialog.

Parameters

Parameter	Type
`__namedParameters`	`ConfirmProviderProps`

Returns

Element

CopyButton()

function CopyButton(__namedParameters: CopyButtonProps): Element;

Headless copy-to-clipboard button. Exposes its copied state via the data-copied attribute on the underlying <button> so consumers can style the success state with [data-copied] (or data-[copied]:bg-green-500 in Tailwind’s arbitrary-variant syntax). Ships no visual styling of its own.

Parameters

Parameter	Type
`__namedParameters`	`CopyButtonProps`

Returns

Element

JsonView()

function JsonView(__namedParameters: JsonViewProps): Element;

Headless collapsible JSON tree. One structural step above a <pre> dump: object/array nodes are independently expandable, but there’s no editing and no syntax-color theme — just data-pyric-* hooks for the consumer to style.

Styling hooks:

[data-pyric-ui="json-view"] — root
[data-pyric-json-node] — every node, with data-pyric-json-type
[data-pyric-json-toggle] — the expand/collapse button (containers only)
[data-pyric-json-node][data-pyric-collapsed] — a collapsed container
[data-pyric-json-key] — the key/index label
[data-pyric-json-value] — a primitive value
[data-pyric-json-summary] — the {…} / […] placeholder when collapsed

Parameters

Parameter	Type
`__namedParameters`	`JsonViewProps`

Returns

Element

SegmentedControl()

function SegmentedControl<T>(__namedParameters: SegmentedControlProps<T>): Element;

Headless segmented control — a single-select group of pill buttons that reads as one widget. Wired as an ARIA radiogroup.

Ships no visual styling. Consumers style via:

[data-pyric-ui="segmented-control"] — the container
[data-pyric-segment] — each option button
[data-pyric-segment][data-pyric-active] — the selected one
[data-pyric-segment-tone="…"] — tone-tinted options

Type Parameters

Type Parameter
`T` extends `string`

Parameters

Parameter	Type
`__namedParameters`	`SegmentedControlProps`<`T`>

Returns

Element

ToastProvider()

function ToastProvider(__namedParameters: ToastProviderProps): Element;

Toast queue host. Mounts a single live region into document.body via portal and exposes the imperative API via context. Scoped — a subtree can host its own provider for isolated queues if needed.

Headless: every node carries structural data-* attributes, no shipped CSS. Auto-dismiss timers are kept per-toast.

Parameters

Parameter	Type
`__namedParameters`	`ToastProviderProps`

Returns

Element

useConfirm()

function useConfirm(): ConfirmFn;

Imperative confirmation hook. Returns a function that opens the provider-managed dialog and resolves to true on confirm, false on cancel/dismiss.

const confirm = useConfirm(); const ok = await confirm({ title: ‘Delete?’, destructive: true }); if (ok) await deleteDoc(ref);

Requires a <ConfirmProvider> ancestor.

Returns

ConfirmFn

useContainerSize()

function useContainerSize<T>(options?: UseContainerSizeOptions): {
  ref: RefObject<T>;
  size: ContainerSize;
};

Container-query helper. Returns the current size bucket ('narrow' | 'medium' | 'wide') of the element pointed at by the returned ref. Re-fires on resize via ResizeObserver.

const { ref, size } = useContainerSize(); return

…

;

Headless: the consumer styles via [data-size='narrow'] selectors. The library’s feature components use this hook to stamp their roots with data-size, which is the policy the survey’s modern-CSS subsection landed on (no viewport media queries, no library-side breakpoints — push the threshold decision to the consumer via data attributes).

Type Parameters

Type Parameter	Default type
`T` extends `HTMLElement`	`HTMLDivElement`

Parameters

Parameter	Type
`options?`	`UseContainerSizeOptions`

Returns

{
  ref: RefObject<T>;
  size: ContainerSize;
}

ref

ref: RefObject<T>;

size

size: ContainerSize;

useToast()

function useToast(): ToastContextValue;

Imperative toast hook. Returns { toast, dismiss, toasts }.

const { toast } = useToast(); toast({ title: ‘Saved.’, kind: ‘success’ });

Requires a <ToastProvider> ancestor.

Returns

ToastContextValue

useUpdateHighlights()

function useUpdateHighlights<T>(__namedParameters: UseUpdateHighlightsOptions<T>): ReadonlyMap<string, UpdateHighlight>;

Tracks transient additions and modifications between keyed snapshots. The first ready snapshot in each scope is a silent baseline.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`__namedParameters`	`UseUpdateHighlightsOptions`<`T`>

Returns

ReadonlyMap<string, UpdateHighlight>

VirtualList()

function VirtualList<T>(__namedParameters: VirtualListProps<T>): Element;

Thin wrapper around @tanstack/react-virtual. Renders a scrollable container with absolutely-positioned rows, drawing only the rows currently in view (plus overscan neighbors).

Headless — no shipped CSS beyond what’s structurally required to position rows (the inner spacer’s height + each row’s position: absolute; top: …px). Consumers style via the className prop and standard CSS targeting [data-pyric-ui= "virtual-list"] on the scroll container and [data-pyric-virtual-row] on each row.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`__namedParameters`	`VirtualListProps`<`T`>

Returns

Element