@plurid/uitive-react
On this page
React bindings: the provider, hooks, the page renderer and the generic blocks, drawn with a kit you map to your design system. React 18.3 or 19.
Install: pnpm add @plurid/uitive-react, with react ^18.3.0 || ^19.0.0, zod ^4.2.0 as peers. Guides: React, Pages.
- The provider:
Confirmations,UitiveBanner,UitiveContext,UitiveDebug,UitiveProvider,UitiveYourInterface,useUitive,ElementProps,ProviderProps,UitiveContextValue - Hooks:
useAction,useCommand,useConfirmation,useLatest,useLifecycle,useLocation,usePending,usePerform,usePlan,useQueries,useQuery,useRanked,useSnapshot,useStandard,useSurface,useUitiveRouter,useUserPages,useView,Request - Rendering pages:
GenericBlock,Page,BlockComponents,BlockProps,PageProps,RegionComponents - The kit:
createKit,defaultKit,kitStyles,ChartPoint,ChartSeries,Kit,ListItem,TableColumn,TableRow,ValueProps,ValueRenderers - Re-exported
The provider
Source: provider.tsx
Confirmations
Asks the user before a generated interface changes data: the action, every param it will run with, and for destructive actions the phrase to type. Mount it once, inside the provider. Buttons and destructive runs wait for it, and are refused without it; a generated form that shows every value it will send counts as the yes.
function Confirmations(): JSX.Element | null;UitiveBanner
<uitive-banner>: what just changed and why, with Revert and Keep. It floats at the bottom right;
docked puts it in the page's flow.
function UitiveBanner(
props: HTMLAttributes<HTMLElement> & {
client: unknown;
} & {
docked?: boolean;
},
): ReactElement;UitiveContext
The provider's context; useUitive reads it.
const UitiveContext: Context<UitiveContextValue | undefined>;Uses: UitiveContextValue.
UitiveDebug
<uitive-debug>: the developer panel. collapsed starts it folded. Bundlers leave it out of
builds that never render it.
function UitiveDebug(
props: HTMLAttributes<HTMLElement> & {
client: unknown;
} & {
personas?: readonly Persona[];
collapsed?: boolean;
},
): ReactElement;UitiveProvider
Makes a client and a kit available to pages, generic blocks and confirmations below it, and
connects the page's lifecycle (see useLifecycle).
function UitiveProvider<C extends AnyContract>(props: ProviderProps<C>): JSX.Element;Uses: AnyContract, ProviderProps.
UitiveYourInterface
<uitive-your-interface>: the user's definition, readable and revertible.
function UitiveYourInterface(props: ElementProps): ReactElement;Uses: ElementProps.
useUitive
The client and kit from the nearest provider.
function useUitive(): UitiveContextValue;Uses: UitiveContextValue.
ElementProps
What the meta-interface wrappers take: HTML attributes, and the client the element shows.
type ElementProps = HTMLAttributes<HTMLElement> & {
client: unknown;
};ProviderProps
What UitiveProvider takes: the client, and the kit generic blocks draw with.
Uses: AnyContract, Kit, Uitive.
Type parameters: C extends AnyContract.
| Property | Type | Default | Description |
|---|---|---|---|
client | Uitive<C> | The client from createUitive. | |
kit? | Kit | defaultKit | What generic blocks are drawn with. |
styles? | boolean | true | Adds the default kit's styles, which kits built with createKit still use. |
nonce? | string | The nonce of a style-src Content Security Policy, for the kit's styles, when the page allows no inline styles without one. | |
children? | ReactNode | The application. |
UitiveContextValue
What the provider shares below it: the client, and the kit generic blocks draw with.
| Property | Type | Description |
|---|---|---|
client | Uitive | The client pages, hooks and confirmations use. |
kit | Kit | The kit generic blocks draw with. |
Hooks
Source: hooks.ts
useAction
The application's own control for an action: running it records usage (no hand-written
record()), and the application confirms in its own way.
function useAction<C extends AnyContract, A extends ActionIdOf<C>>(
client: Uitive<C>,
action: A,
): (params?: ParamsOf<C, A>, options?: Omit<PerformOptions, 'origin'>) => Promise<PerformResult>;Uses: ActionIdOf, AnyContract, ParamsOf, PerformOptions, PerformResult, Uitive.
useCommand
Asks in the user's own words, tracking the request for the interface.
function useCommand<C extends AnyContract>(
client: Uitive<C>,
): {
ask: (
text: string,
options?: {
goal?: boolean;
},
) => Promise<Adaptation>;
pending: boolean;
result: Adaptation | undefined;
error: unknown;
};Uses: Adaptation, AnyContract, Uitive.
useConfirmation
The run waiting for the user's yes, with the means to answer it.
function useConfirmation<C extends AnyContract>(
client: Uitive<C>,
): {
confirmation: Confirmation | undefined;
confirm: (phrase?: string) => boolean;
cancel: () => void;
};Uses: AnyContract, Confirmation, Uitive.
useLatest
The latest adaptation, for banners. Re-renders only when a new one arrives; none during server rendering.
function useLatest<C extends AnyContract>(client: Uitive<C>): Adaptation | undefined;Uses: Adaptation, AnyContract, Uitive.
useLifecycle
Connects the page's lifecycle to sessions: coming back to a tab after an idle gap applies
pending changes before the user acts, each session is planned from use once (see learn), and
leaving the page writes state to storage. Starts no sessions itself and plans a session only
once, so React's development double-mounting changes nothing. UitiveProvider calls it;
call it yourself only for a client used without the provider.
function useLifecycle<C extends AnyContract>(client: Uitive<C>): void;Uses: AnyContract, Uitive.
useLocation
Where the user is, as the router last reported it.
function useLocation<C extends AnyContract>(client: Uitive<C>): Location | undefined;Uses: AnyContract, Location, Uitive.
usePending
Changes waiting for the next safe moment; none during server rendering.
function usePending<C extends AnyContract>(client: Uitive<C>): readonly Pending[];Uses: AnyContract, Pending, Uitive.
usePerform
Runs actions; writes from generated interfaces wait for the user's yes.
function usePerform<C extends AnyContract>(
client: Uitive<C>,
): <A extends ActionIdOf<C>>(
action: A,
params?: ParamsOf<C, A>,
options?: PerformOptions,
) => Promise<PerformResult>;Uses: AnyContract, ParamsOf, PerformOptions, PerformResult, Uitive.
usePlan
Plans on request, tracking it for the interface.
function usePlan<C extends AnyContract>(
client: Uitive<C>,
): {
plan: () => Promise<Adaptation>;
pending: boolean;
result: Adaptation | undefined;
error: unknown;
};Uses: Adaptation, AnyContract, Uitive.
useQueries
Several queries' results at once, in order; an undefined query reads as loading, as does one
naming $current until the row is known.
function useQueries<C extends AnyContract>(
client: Uitive<C>,
queries: readonly (Query | undefined)[],
scope?: DataScope,
): readonly DataEntry[];Uses: AnyContract, DataEntry, DataScope, Query, Uitive.
useQuery
One query's result, shared with everything else that asks for it. Fetches when there is none
or it went stale; renders from the cache meanwhile. A query naming $current loads until the
row is known.
function useQuery<C extends AnyContract>(
client: Uitive<C>,
query: Query | undefined,
scope?: DataScope,
): DataEntry;Uses: AnyContract, DataEntry, DataScope, Query, Uitive.
useRanked
Every action, ranked for a palette by how the user reaches for them. Server rendering ranks them as for someone new.
function useRanked<C extends AnyContract>(client: Uitive<C>): readonly ActionView<ActionIdOf<C>>[];Uses: ActionIdOf, ActionView, AnyContract, Uitive.
useSnapshot
The client's whole snapshot. It changes with every usage event, so use it for panels, not for
the interface itself; prefer useSurface there. Server rendering and hydration read the
state of a client with nothing stored.
function useSnapshot<C extends AnyContract>(client: Uitive<C>): Snapshot;Uses: AnyContract, Snapshot, Uitive.
useStandard
A surface as the application ships it, whatever the user's definition.
function useStandard<C extends AnyContract, K extends SurfaceIdOf<C>>(
client: Uitive<C>,
id: K,
context?: string,
): SurfaceValueOf<C, K>;Uses: AnyContract, SurfaceIdOf, SurfaceValueOf, Uitive.
useSurface
A surface's value, for the current context unless one is given. Re-renders only when that value changes. Server rendering uses the standard layout, so hydration never mismatches; the user's definition follows on the client.
function useSurface<C extends AnyContract, K extends SurfaceIdOf<C>>(
client: Uitive<C>,
id: K,
context?: string,
): SurfaceValueOf<C, K>;Uses: AnyContract, SurfaceIdOf, SurfaceValueOf, Uitive.
useUitiveRouter
Connects any router: tells the client every route change and lets it follow links through
the router. With React Router, useUitiveRouter(client, { path: pathname + search, navigate }); with Next.js, { path: usePathname(), navigate: useRouter().push }.
function useUitiveRouter<C extends AnyContract>(
client: Uitive<C>,
router: {
path: string;
navigate: (href: string) => void;
},
): void;Uses: AnyContract, Uitive.
useUserPages
The pages the user made; none during server rendering, so hydration never mismatches.
function useUserPages<C extends AnyContract>(client: Uitive<C>): readonly UserPage[];Uses: AnyContract, Uitive, UserPage.
useView
Whether the user is looking at their own interface or the standard one; yours during server
rendering.
function useView<C extends AnyContract>(client: Uitive<C>): View;Uses: AnyContract, Uitive, View.
Request
A request's state, for an interface: whether it is in flight, and its result or error.
Type parameters: T.
| Property | Type | Description |
|---|---|---|
pending | boolean | Whether a request is in flight. |
result | T | undefined | The last result, once there is one. |
error | unknown | Why the last request failed, if it did. |
Rendering pages
Source: generic.tsx, page.tsx
GenericBlock
Draws one generic block from its props, its page's queries and the kit.
function GenericBlock(props: {
element: Element;
page: AnyPage;
current?: string;
}): JSX.Element | null;Page
Renders a page, standard or redesigned, with the application's own components. For styling,
the page and its sections carry data-layout, and each block, or section or tabs nested in a
section, sits in a wrapper with data-block and data-element; a page's top-level sections and
tabs sit directly in the page.
function Page<B extends Record<string, BlockSpec>>(props: PageProps<B>): JSX.Element | null;BlockComponents
One component per block of a page; the types come from the contract's block schemas.
type BlockComponents<B extends Record<string, BlockSpec>> = {
[K in Extract<keyof B, string>]: ComponentType<BlockProps<PropsOf<B[K]>>>;
};Uses: BlockProps, BlockSpec, PropsOf.
BlockProps
Props every block component receives: its own typed props, and the page's context value.
Type parameters: P.
| Property | Type | Description |
|---|---|---|
props | P | The block's props, checked against its schema. |
context | string | undefined | The page's context value, such as the service shown. |
PageProps
What Page takes: the page to draw, the components for the application's blocks and regions, and
the row it is about.
Uses: AnyPage, BlockComponents, BlockSpec, RegionComponents.
Type parameters: B extends Record<string, BlockSpec>.
| Property | Type | Default | Description |
|---|---|---|---|
value | AnyPage | The page, usually from useSurface. | |
blocks | BlockComponents<B> | A component for each of the application's own blocks; generic blocks need none. | |
regions? | RegionComponents | {} | What each region shows, such as the page as it was before Uitive. |
context? | string | The page's context value, such as the service shown. | |
current? | string | the row the location is about | The key of the row the page is about. |
className? | string | 'uitive-page' | The class of the page's wrapper. |
RegionComponents
Components for the contract's regions: parts of the application as it already is.
type RegionComponents = Readonly<
Record<
string,
ComponentType<{
context: string | undefined;
}>
>
>;The kit
Source: kit.tsx
createKit
A kit with some primitives replaced, and some value types drawn differently: start from the default and swap in the design system's parts as they are mapped.
function createKit(
overrides?: Partial<Kit> & {
values?: ValueRenderers;
},
): Kit;Uses: Kit, ValueRenderers.
defaultKit
Semantic HTML with uitive-* classes, themed through --uitive-* custom properties.
const defaultKit: Kit;Uses: Kit.
kitStyles
The default kit's styles, as a string: for a <style>, or a shadow root.
const kitStyles: string;ChartPoint
One point of a chart series.
| Property | Type | Description |
|---|---|---|
x | number | string | A time in milliseconds, or a category; points with the same x line up across series. |
label | string | The point's label, as people read it. |
y | number | Its value; money in major units. |
currency? | string | For money: the currency the value is in. Amounts in different currencies are never added. |
ChartSeries
One series of a kit Chart, such as one value of a split.
Uses: ChartPoint.
| Property | Type | Description |
|---|---|---|
name | string | The series' name, for its legend. |
points | readonly ChartPoint[] | Its points, in order. |
Kit
The presentational parts every generic block is drawn with. Map them to a design system once, one at a time if need be, and Uitive's blocks look native.
interface Kit {
Stack: ComponentType<{
children?: ReactNode;
}>;
Title: ComponentType<{
children?: ReactNode;
}>;
Section: ComponentType<{
title: string;
layout: 'stack' | 'grid' | 'columns';
depth: number;
count: number;
children?: ReactNode;
}>;
Grid: ComponentType<{
children?: ReactNode;
columns?: number;
}>;
Card: ComponentType<{
title?: string;
children?: ReactNode;
}>;
Tabs: ComponentType<{
label?: string;
tabs: readonly {
id: string;
title: string;
content: ReactNode;
}[];
}>;
Text: ComponentType<{
children?: ReactNode;
tone?: 'muted' | 'strong';
}>;
Table: ComponentType<{
columns: readonly TableColumn[];
rows: readonly TableRow[];
density?: 'comfortable' | 'compact';
caption?: string;
}>;
List: ComponentType<{
items: readonly ListItem[];
}>;
Stat: ComponentType<{
label: string;
value: ReactNode;
change?: number;
partial?: boolean;
}>;
Chart: ComponentType<{
kind: 'line' | 'bar' | 'area' | 'pie';
series: readonly ChartSeries[];
stacked?: boolean;
label?: string;
}>;
Badge: ComponentType<{
children?: ReactNode;
tone?: 'neutral' | 'good' | 'warning' | 'bad';
}>;
Value: ComponentType<ValueProps>;
Button: ComponentType<{
children?: ReactNode;
onClick?: () => void;
tone?: 'primary' | 'plain' | 'danger';
size?: 'small' | 'regular' | 'large';
disabled?: boolean;
type?: 'button' | 'submit';
}>;
Link: ComponentType<{
href: string;
children?: ReactNode;
onClick?: () => void;
}>;
Field: ComponentType<{
field: Field;
value: string;
onChange: (value: string) => void;
label?: string;
required?: boolean;
}>;
Dialog: ComponentType<{
title: string;
children?: ReactNode;
onClose: () => void;
}>;
Notice: ComponentType<{
tone: 'success' | 'error';
children?: ReactNode;
}>;
Status: ComponentType<{
state: 'empty' | 'loading' | 'error' | 'partial';
message?: string;
}>;
}Uses: ChartSeries, Field, ListItem, TableColumn, TableRow, ValueProps.
| Property | Description |
|---|---|
Stack | Parts one above another, such as a form's fields and its button. |
Title | A page's title, from its root section; the page's own heading. |
Section | A page's section: its title, and its blocks laid out as a stack, a grid or columns. Map it to the design system's container and heading; depth is 1 for a page's top-level sections. |
Grid | Parts side by side in columns, such as a detail block's fields or a board's columns. |
Card | A framed part with an optional title, such as a note or a board's column. |
Tabs | A section whose children show one at a time, each under its tab. |
Text | A run of text, plain, muted or strong. |
Table | Rows under column headers: the table block, with row actions in its cells. |
List | Rows as a list, each with a title, a subtitle, a badge and its own actions. |
Stat | One figure with its label: the metric block. |
Chart | Series drawn as lines, bars, areas or a pie. A chart never stacks or totals amounts in different currencies, and offers its figures to assistive technology as well as a picture. |
Badge | A short label with a tone, such as a status. |
Value | One value, shown by its type, such as money with its currency or a reference by name. |
Button | A button: row actions, the actions block and dialogs use it. |
Link | A link to a route, followed through the application's router. |
Field | A labeled input for one field, such as an action's param in a form. |
Dialog | A modal with a title, for confirmations and the forms of actions run from a row. It takes focus when it opens, keeps it inside, closes on Escape and gives focus back when it closes. |
Notice | What happened when an action ran from a generated page. Map it to the design system's toast or alert: each run mounts a new one, so a toast can show itself on mount and render nothing. |
Status | What a block shows around or instead of data: no rows, loading, an error, or a partial result. |
ListItem
One item of a kit List: a title, optional details and a badge, its actions, and how to open it.
| Property | Type | Description |
|---|---|---|
key | string | The item's key, for React and for actions. |
title | ReactNode | What the item is called. |
subtitle? | ReactNode | A second line. |
meta? | ReactNode | A detail beside the item, such as a time. |
badge? | ReactNode | A badge, such as a status. |
actions? | ReactNode | Buttons for the item's actions. |
onOpen? | () => void | Opens the item's own page. |
TableColumn
One column of a kit Table: the key its cells are under, its header, and how it aligns.
| Property | Type | Description |
|---|---|---|
key | string | The key each row's cell for this column is under. |
label | string | The column's header. |
align? | 'start' | 'end' | end for figures, so they line up. |
TableRow
One row of a kit Table: its cells by column key, its actions, and how to open it.
| Property | Type | Description |
|---|---|---|
key | string | The row's key, for React and for actions. |
cells | Readonly<Record<string, ReactNode>> | The row's cells, by column key, already formatted. |
actions? | ReactNode | Buttons for the row's actions. |
onOpen? | () => void | Opens the row's own page. |
ValueProps
What a value renderer gets: the field and its value, and the currency for money.
Uses: Field.
| Property | Type | Description |
|---|---|---|
field | Field | The field, with its type and meaning. |
value | unknown | The stored value, such as an amount in cents. |
currency? | string | For money: the currency the value is in. |
ValueRenderers
Value renderers by type (money) or by reference target (ref:customers).
type ValueRenderers = Readonly<Record<string, ComponentType<ValueProps>>>;Uses: ValueProps.
Re-exported
From @plurid/uitive-core: formatValue.