@plurid/uitive-dom
On this page
Uitive for pages without React: adapting an application's own markup, and the meta-interface as custom elements.
Install: pnpm add @plurid/uitive-dom, with zod ^4.2.0 as a peer. Guides: Without React.
- Starting:
defineElements,startUitive - Adapting markup:
adaptMarkup,forward,movedOut,orders,MarkupClientLike,MarkupOptions - Elements:
escape,UitiveAsk,UitiveBanner,UitiveConfirm,UitiveElement,UitiveMore,UitiveYourInterface,AskClientLike,ClientLike,ConfirmClientLike,DebugClientLike,MoreClientLike @plurid/uitive-dom/debug:defineDebugElement,UitiveDebug
Starting
defineElements
Registers <uitive-ask>, <uitive-banner>, <uitive-confirm>, <uitive-more> and <uitive-your-interface>.
Safe to call more than once, and a no-op without a DOM, as during server rendering.
function defineElements(): void;startUitive
Starts Uitive on a page without React, once: registers the elements and gives every one the
client, adapts the markup marked with data-uitive-list and data-uitive-item (see adaptMarkup),
starts a new session when the person comes back after a while, plans each session from use once
(see learn), and saves usage whenever the page is hidden or closed. Returns a function that
undoes it all.
function startUitive<C extends AnyContract>(client: Uitive<C>, options?: MarkupOptions): () => void;Uses: AnyContract, MarkupOptions, Uitive.
Adapting markup
adaptMarkup
Adapts an application's own markup to the person's interface, for applications without React.
Mark each list's container with data-uitive-list="<list>" and each item inside it with
data-uitive-item="<action>". Items the person moves out are hidden by one stylesheet, so markup
rendered later, such as a menu's, adapts too; reordered lists set CSS order on their
container's children, which needs a flex or grid box, then or once it shows. Nothing is moved,
so the application's framework keeps its nodes, and keyboard focus and screen readers follow the
markup's own order. Clicks on items record usage. Returns a function that undoes it all.
function adaptMarkup(client: MarkupClientLike, options?: MarkupOptions): () => void;Uses: MarkupClientLike, MarkupOptions.
forward
Clicks an item the person's interface hides, as if they had, without recording it twice.
function forward(element: HTMLElement): void;movedOut
The items the person moved out of a list: the markup shows them unless told otherwise.
function movedOut(client: Pick<Uitive, 'surface' | 'standard'>, list: string): ActionView<string>[];Uses: ActionView, AnyContract, Uitive.
orders
CSS order values that show a flex or grid box's children in a new order without moving them.
positions holds each child's place among the items, or -1 for a child that isn't one. Children
before the first item stay first, children after the last item stay last, and the others follow
the item before them. Without items, nothing moves.
function orders(positions: readonly number[]): number[];MarkupClientLike
What adapting markup needs from a client; a client from createUitive fits as it is.
type MarkupClientLike = Pick<Uitive, 'contract' | 'surface' | 'standard' | 'subscribe' | 'record'>;Uses: Uitive.
MarkupOptions
How adaptMarkup and startUitive work: where the markup is, whether clicks count as use,
and who hears of problems.
| Property | Type | Default | Description |
|---|---|---|---|
root? | Document | ShadowRoot | document | Where the markup lives. |
record? | boolean | true | Whether clicks on items record usage. |
onProblem? | (problem: string) => void | console.warn | Told once about each list that can't adapt as the person asked, such as a reordered list whose container isn't a flex or grid box; a hidden container is checked once it shows. |
Elements
Source: ask.ts, banner.ts, client-like.ts, confirm.ts, element.ts, html.ts, more.ts, your-interface.ts
escape
Escapes any value for HTML text and attribute values. Every interpolation goes through it.
function escape(value: unknown): string;UitiveAsk
<uitive-ask>: where the person asks for a change in their own words, such as "hide Print". Simple
commands work without a model; with a planner, so do requests like "make my home a morning
check". What happened shows here in a line, and in full in <uitive-banner> when there is one.
Emits uitive-asked (detail.adaptation). The placeholder attribute replaces the hint.
class UitiveAsk extends UitiveElement<AskClientLike> {}UitiveBanner
<uitive-banner>: tells the user what just changed in their interface and why, with Revert and
Keep for each change, and answers their commands, including refusals and their reasons.
Floats at the bottom right by default; restyle :host to place it elsewhere, or add docked
to put it in the page's flow, such as inside the application's own notification area.
Emits uitive-dismiss (detail.adaptation: the adaptation's ID) when closed.
class UitiveBanner extends UitiveElement {}Uses: ClientLike.
UitiveConfirm
<uitive-confirm>: asks the person before an action changes data: what it does and to what, and
for a destructive action, the phrase to type. Place it once. While it is in the page, actions
with effects wait for the person's answer; without it, they are refused. It asks in a modal
dialog that holds focus and gives it back when the run is answered.
class UitiveConfirm extends UitiveElement<ConfirmClientLike> {}Uses: ConfirmClientLike.
UitiveElement
The lifecycle shared by Uitive's elements: subscribes to the client while connected,
renders into a shadow root only when what it shows changes, and keeps focus and typing
across renders. Interactive markup declares data-act (and data-on for change or
submit); data-arg carries a value to the handler.
abstract class UitiveElement<Client extends ClientLike = ClientLike> extends HTMLElement {
static useClient(client: ClientLike | undefined): void;
protected readonly content: HTMLElement;
get client(): Client | undefined;
set client(client: Client | undefined);
protected attached(_client: Client): (() => void) | void;
protected styles(): string;
protected abstract key(client: Client): string;
protected abstract template(client: Client): string;
protected abstract act(
action: string,
argument: string | undefined,
target: HTMLElement,
): void | Promise<void>;
protected update(force?: boolean): void;
protected confirm(key: string): boolean;
protected armed(key: string): boolean;
protected emit(type: string, detail: unknown): void;
}Uses: ClientLike.
| Member | Description |
|---|---|
useClient() | The client every element uses when none is set on it, such as elements a framework renders later. startUitive sets it. |
content | The element everything renders into. |
client | The client this element shows and acts on: its own, or the one every element uses. |
attached() | Called when the element starts showing a client; what it returns runs when it stops. |
styles() | Extra CSS for this element. |
key() | Changes whenever what the element shows changes; renders are skipped otherwise. |
template() | The element's markup. Every interpolated value must go through escape. |
act() | Handles an interaction with an element that declares data-act. |
update() | Renders again if what the element shows changed, or always when forced. |
confirm() | For two-step buttons: the first press arms, a second within a few seconds confirms. |
armed() | Whether a two-step button is armed. |
emit() | Dispatches a bubbling event that crosses the shadow boundary, for hosts to listen to. |
UitiveMore
<uitive-more list="toolbar">: a menu of the items the person moved out of a list adapted with
adaptMarkup, so nothing is ever out of reach. Choosing one clicks the hidden original, so the
application's own handler runs; when the original isn't in the page, it emits uitive-open
(detail: { list, action }) for the application to run. Shows nothing while no item is out.
The label attribute names its button (default "More"). Opening it focuses the first item;
the arrow keys, Home and End move between items, and Escape closes it.
class UitiveMore extends UitiveElement<MoreClientLike> {}Uses: MoreClientLike.
UitiveYourInterface
<uitive-your-interface>: the user's own definition, in plain words: every change, who made
it and why, what is suggested and what is waiting, with the controls to keep, revert,
freeze, reset, export and import it, or forget it altogether.
Emits uitive-export (detail.document) when exporting, and uitive-import (detail.adaptation,
or detail.error) after an import. Its heading is ::part(heading), for hosts that title it
themselves.
class UitiveYourInterface extends UitiveElement {
exportDocument(): ReturnType<ClientLike['export']> | undefined;
importDocument(document_: unknown): Adaptation | undefined;
}Uses: Adaptation, ClientLike.
| Member | Description |
|---|---|
exportDocument() | Downloads the user's definition as JSON, and returns it. |
importDocument() | Imports a definition, reporting what applied and what was skipped. |
AskClientLike
What <uitive-ask> needs from a client.
type AskClientLike = ClientLike & Pick<Uitive, 'ask'>;Uses: ClientLike, Uitive.
ClientLike
What the banner and "Your interface" need from a client. A client from createUitive
fits as it is; a remote adapter can offer the same over HTTP.
type ClientLike = Pick<
Uitive,
| 'contract'
| 'getSnapshot'
| 'subscribe'
| 'explain'
| 'revert'
| 'revertAdaptation'
| 'keep'
| 'accept'
| 'dismiss'
| 'preview'
| 'freeze'
| 'setGoal'
| 'setView'
| 'reset'
| 'clearData'
| 'export'
| 'import'
>;Uses: Uitive.
ConfirmClientLike
What <uitive-confirm> needs from a client.
type ConfirmClientLike = ClientLike & Pick<Uitive, 'confirm' | 'cancel' | 'confirmations'>;Uses: ClientLike, Uitive.
DebugClientLike
What the debug panel needs on top: usage, requests and the controls of the loop.
type DebugClientLike = ClientLike &
Pick<
Uitive,
'events' | 'summary' | 'request' | 'plan' | 'nextSession' | 'apply' | 'setAutonomy'
> & {
simulate?(
persona: Persona,
options: {
sessions: number;
seed: number;
},
): Promise<readonly SessionReport[]>;
};Uses: ClientLike, Persona, SessionReport, Uitive.
MoreClientLike
What <uitive-more> needs from a client.
type MoreClientLike = ClientLike & Pick<Uitive, 'surface' | 'standard' | 'record'>;Uses: ClientLike, Uitive.
@plurid/uitive-dom/debug
Source: debug.ts
defineDebugElement
Registers <uitive-debug>. Safe to call more than once, and a no-op without a DOM.
function defineDebugElement(): void;Import from @plurid/uitive-dom/debug.
UitiveDebug
<uitive-debug>: a developer panel over a client: usage events, the summary and the exact
request a planner receives, the definition, pending changes and history, with controls to
plan, start sessions, change autonomy and simulate personas.
Set personas to offer "Simulate a week" buttons. Starts collapsed with the collapsed
attribute. Emits uitive-simulated (detail.persona, detail.reports) after a simulation.
class UitiveDebug extends UitiveElement<DebugClientLike> {
get personas(): readonly Persona[];
set personas(personas: readonly Persona[] | undefined);
simulatePersona(persona: Persona): Promise<readonly SessionReport[]>;
}Import from @plurid/uitive-dom/debug.
Uses: DebugClientLike, Persona, SessionReport.
| Member | Default | Description |
|---|---|---|
personas | [] | Personas offered for "Simulate a week". |
simulatePersona() | Simulates a week of use as a persona, where the client lives. |