@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

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.

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

ts
function UitiveBanner(
  props: HTMLAttributes<HTMLElement> & {
    client: unknown;
  } & {
    docked?: boolean;
  },
): ReactElement;

UitiveContext

The provider's context; useUitive reads it.

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

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

ts
function UitiveProvider<C extends AnyContract>(props: ProviderProps<C>): JSX.Element;

Uses: AnyContract, ProviderProps.

UitiveYourInterface

<uitive-your-interface>: the user's definition, readable and revertible.

ts
function UitiveYourInterface(props: ElementProps): ReactElement;

Uses: ElementProps.

useUitive

The client and kit from the nearest provider.

ts
function useUitive(): UitiveContextValue;

Uses: UitiveContextValue.

ElementProps

What the meta-interface wrappers take: HTML attributes, and the client the element shows.

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

PropertyTypeDefaultDescription
clientUitive<C>The client from createUitive.
kit?KitdefaultKitWhat generic blocks are drawn with.
styles?booleantrueAdds the default kit's styles, which kits built with createKit still use.
nonce?stringThe nonce of a style-src Content Security Policy, for the kit's styles, when the page allows no inline styles without one.
children?ReactNodeThe application.

UitiveContextValue

What the provider shares below it: the client, and the kit generic blocks draw with.

Uses: Kit, Uitive.

PropertyTypeDescription
clientUitiveThe client pages, hooks and confirmations use.
kitKitThe 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.

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

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

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

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

ts
function useLifecycle<C extends AnyContract>(client: Uitive<C>): void;

Uses: AnyContract, Uitive.

useLocation

Where the user is, as the router last reported it.

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

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

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

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

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

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

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

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

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

ts
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 }.

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

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

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

PropertyTypeDescription
pendingbooleanWhether a request is in flight.
resultT | undefinedThe last result, once there is one.
errorunknownWhy 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.

ts
function GenericBlock(props: {
  element: Element;
  page: AnyPage;
  current?: string;
}): JSX.Element | null;

Uses: AnyPage, Element.

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.

ts
function Page<B extends Record<string, BlockSpec>>(props: PageProps<B>): JSX.Element | null;

Uses: BlockSpec, PageProps.

BlockComponents

One component per block of a page; the types come from the contract's block schemas.

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

PropertyTypeDescription
propsPThe block's props, checked against its schema.
contextstring | undefinedThe 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>.

PropertyTypeDefaultDescription
valueAnyPageThe page, usually from useSurface.
blocksBlockComponents<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?stringThe page's context value, such as the service shown.
current?stringthe row the location is aboutThe 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.

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

ts
function createKit(
  overrides?: Partial<Kit> & {
    values?: ValueRenderers;
  },
): Kit;

Uses: Kit, ValueRenderers.

defaultKit

Semantic HTML with uitive-* classes, themed through --uitive-* custom properties.

ts
const defaultKit: Kit;

Uses: Kit.

kitStyles

The default kit's styles, as a string: for a <style>, or a shadow root.

ts
const kitStyles: string;

ChartPoint

One point of a chart series.

PropertyTypeDescription
xnumber | stringA time in milliseconds, or a category; points with the same x line up across series.
labelstringThe point's label, as people read it.
ynumberIts value; money in major units.
currency?stringFor 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.

PropertyTypeDescription
namestringThe series' name, for its legend.
pointsreadonly 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.

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

PropertyDescription
StackParts one above another, such as a form's fields and its button.
TitleA page's title, from its root section; the page's own heading.
SectionA 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.
GridParts side by side in columns, such as a detail block's fields or a board's columns.
CardA framed part with an optional title, such as a note or a board's column.
TabsA section whose children show one at a time, each under its tab.
TextA run of text, plain, muted or strong.
TableRows under column headers: the table block, with row actions in its cells.
ListRows as a list, each with a title, a subtitle, a badge and its own actions.
StatOne figure with its label: the metric block.
ChartSeries 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.
BadgeA short label with a tone, such as a status.
ValueOne value, shown by its type, such as money with its currency or a reference by name.
ButtonA button: row actions, the actions block and dialogs use it.
LinkA link to a route, followed through the application's router.
FieldA labeled input for one field, such as an action's param in a form.
DialogA 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.
NoticeWhat 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.
StatusWhat 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.

PropertyTypeDescription
keystringThe item's key, for React and for actions.
titleReactNodeWhat the item is called.
subtitle?ReactNodeA second line.
meta?ReactNodeA detail beside the item, such as a time.
badge?ReactNodeA badge, such as a status.
actions?ReactNodeButtons for the item's actions.
onOpen?() => voidOpens the item's own page.

TableColumn

One column of a kit Table: the key its cells are under, its header, and how it aligns.

PropertyTypeDescription
keystringThe key each row's cell for this column is under.
labelstringThe 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.

PropertyTypeDescription
keystringThe row's key, for React and for actions.
cellsReadonly<Record<string, ReactNode>>The row's cells, by column key, already formatted.
actions?ReactNodeButtons for the row's actions.
onOpen?() => voidOpens the row's own page.

ValueProps

What a value renderer gets: the field and its value, and the currency for money.

Uses: Field.

PropertyTypeDescription
fieldFieldThe field, with its type and meaning.
valueunknownThe stored value, such as an amount in cents.
currency?stringFor money: the currency the value is in.

ValueRenderers

Value renderers by type (money) or by reference target (ref:customers).

ts
type ValueRenderers = Readonly<Record<string, ComponentType<ValueProps>>>;

Uses: ValueProps.

Re-exported

From @plurid/uitive-core: formatValue.