Contracts

ImportCopy Anchor Link

import { STATE_ATTR_NAMES, details, mergeProps, renderElement, stateAttrs, toRenderFn } from '@nizivo/react/contracts';

ExportsCopy Anchor Link

Align type

import type { Align } from '@nizivo/react/contracts'

type Align = (typeof ALIGNS)[number]

ChangeDetails type

import type { ChangeDetails } from '@nizivo/react/contracts'

The second argument of every on<X>Change(value, details). reason is Nizivo-owned: where the engine reports no cause, it is 'unknown', never a guess.

Name	Type	Default	Description
event	Event	–
reasonrequired	R | "unknown"	–

OpenReason type

import type { OpenReason } from '@nizivo/react/contracts'

Why an overlay opened or closed (§12.2).

type OpenReason = "trigger" | "escape" | "outside-press" | "close-part" | "item-press" | "hidden" | "programmatic"

Orientation type

import type { Orientation } from '@nizivo/react/contracts'

type Orientation = (typeof ORIENTATIONS)[number]

RenderProp type

import type { RenderProp } from '@nizivo/react/contracts'

Composition without asChild or a polymorphic as: - element form: render={<Link href="/orders" />}, serializable from Server Components; - function form: render={(props, state) => <a {...props} />}, client code only.

type RenderProp<S> = ReactElement | ((props: Record<string, unknown>, state: S) => ReactElement)

STATE_ATTR_NAMES constant

import { STATE_ATTR_NAMES } from '@nizivo/react/contracts'

Every attribute name stateAttrs() can emit.

const STATE_ATTR_NAMES: readonly string[]

Side type

import type { Side } from '@nizivo/react/contracts'

type Side = (typeof SIDES)[number]

StateAttrs type

import type { StateAttrs } from '@nizivo/react/contracts'

data-* attributes keyed by name; presence attributes carry "".

type StateAttrs = Record<`data-${string}`, string>

StateInput type

import type { StateInput } from '@nizivo/react/contracts'

Engine-independent state, as adapters derive it from the engine's render state.

Name	Type	Default	Description
align	Align "start" | "center" | "end"	–
checked	boolean	–
disabled	boolean	–
empty	boolean	–
entering	boolean	–
error	boolean	–
exiting	boolean	–
focusVisible	boolean	–
highlighted	boolean	–
indeterminate	boolean	–
invalid	boolean	–
loading	boolean	–
mirror	(typeof MIRRORS)[number] "rtl"	–
nestedOpen	boolean	–
open	boolean	–
orientation	Orientation "horizontal" | "vertical"	–
pending	boolean	–
placeholder	boolean	–
pressed	boolean	–
readOnly	boolean	–
required	boolean	–
selected	boolean	–
side	Side "top" | "right" | "bottom" | "left"	–

details function

import { details } from '@nizivo/react/contracts'

function details<R extends string = never>(reason: NoInfer<R> | "unknown", event?: Event): ChangeDetails<R>

mergeProps function

import { mergeProps } from '@nizivo/react/contracts'

Merges prop objects from left ("ours") to right ("theirs"): - className is concatenated, ours first, without repeating a class; - style is shallow-merged, theirs winning; - on* handlers are chained theirs-first, and ours skip when the event was defaultPrevented; - refs are merged into one callback ref; - any other key: the right-most defined value wins, and undefined never overrides.

A function is created only when both sides supply one, so a server component that merges a consumer element never synthesises a handler or ref (functions cannot cross the RSC boundary).

function mergeProps(...sources: ReadonlyArray<Props | undefined>): Props

renderElement function

import { renderElement } from '@nizivo/react/contracts'

Renders tag with props, or the consumer's element/function with props merged in (ours first). Element form: mergeProps semantics (the element's props win), except that the part's own PART_OWNED attributes win over the element's.

function renderElement<S>(tag: string, render: RenderProp<S> | undefined, state: S, props: Record<string, unknown>): ReactElement

stateAttrs function

import { stateAttrs } from '@nizivo/react/contracts'

Maps state to vocabulary attributes. False and absent states emit nothing.

function stateAttrs(state: StateInput): StateAttrs

toRenderFn function

import { toRenderFn } from '@nizivo/react/contracts'

Normalises any render prop to the function form that engine adapters receive.

function toRenderFn<S>(render: RenderProp<S> | undefined, tag: string): (props: Record<string, unknown>, state: S) => ReactElement