# @plurid/uitive-dom

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](https://uitive.dev/docs/without-react).

- [Starting](https://uitive.dev/docs/api/dom#starting): [`defineElements`](https://uitive.dev/docs/api/dom#defineelements), [`startUitive`](https://uitive.dev/docs/api/dom#startuitive)
- [Adapting markup](https://uitive.dev/docs/api/dom#adapting-markup): [`adaptMarkup`](https://uitive.dev/docs/api/dom#adaptmarkup), [`forward`](https://uitive.dev/docs/api/dom#forward), [`movedOut`](https://uitive.dev/docs/api/dom#movedout), [`orders`](https://uitive.dev/docs/api/dom#orders), [`MarkupClientLike`](https://uitive.dev/docs/api/dom#markupclientlike), [`MarkupOptions`](https://uitive.dev/docs/api/dom#markupoptions)
- [Elements](https://uitive.dev/docs/api/dom#elements): [`escape`](https://uitive.dev/docs/api/dom#escape), [`UitiveAsk`](https://uitive.dev/docs/api/dom#uitiveask), [`UitiveBanner`](https://uitive.dev/docs/api/dom#uitivebanner), [`UitiveConfirm`](https://uitive.dev/docs/api/dom#uitiveconfirm), [`UitiveElement`](https://uitive.dev/docs/api/dom#uitiveelement), [`UitiveMore`](https://uitive.dev/docs/api/dom#uitivemore), [`UitiveYourInterface`](https://uitive.dev/docs/api/dom#uitiveyourinterface), [`AskClientLike`](https://uitive.dev/docs/api/dom#askclientlike), [`ClientLike`](https://uitive.dev/docs/api/dom#clientlike), [`ConfirmClientLike`](https://uitive.dev/docs/api/dom#confirmclientlike), [`DebugClientLike`](https://uitive.dev/docs/api/dom#debugclientlike), [`MoreClientLike`](https://uitive.dev/docs/api/dom#moreclientlike)
- [`@plurid/uitive-dom/debug`](https://uitive.dev/docs/api/dom#pluriduitive-domdebug): [`defineDebugElement`](https://uitive.dev/docs/api/dom#definedebugelement), [`UitiveDebug`](https://uitive.dev/docs/api/dom#uitivedebug)

## Starting

Source: [`define.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/define.ts), [`start.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/start.ts)

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

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

```ts
function startUitive<C extends AnyContract>(client: Uitive<C>, options?: MarkupOptions): () => void;
```

Uses: [`AnyContract`](https://uitive.dev/docs/api/core#anycontract), [`MarkupOptions`](https://uitive.dev/docs/api/dom#markupoptions), [`Uitive`](https://uitive.dev/docs/api/core#uitive).

## Adapting markup

Source: [`markup.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/markup.ts), [`order.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/order.ts)

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

```ts
function adaptMarkup(client: MarkupClientLike, options?: MarkupOptions): () => void;
```

Uses: [`MarkupClientLike`](https://uitive.dev/docs/api/dom#markupclientlike), [`MarkupOptions`](https://uitive.dev/docs/api/dom#markupoptions).

### forward

Clicks an item the person's interface hides, as if they had, without recording it twice.

```ts
function forward(element: HTMLElement): void;
```

### movedOut

The items the person moved out of a list: the markup shows them unless told otherwise.

```ts
function movedOut(client: Pick<Uitive, 'surface' | 'standard'>, list: string): ActionView<string>[];
```

Uses: [`ActionView`](https://uitive.dev/docs/api/core#actionview), [`AnyContract`](https://uitive.dev/docs/api/core#anycontract), [`Uitive`](https://uitive.dev/docs/api/core#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.

```ts
function orders(positions: readonly number[]): number[];
```

### MarkupClientLike

What adapting markup needs from a client; a client from `createUitive` fits as it is.

```ts
type MarkupClientLike = Pick<Uitive, 'contract' | 'surface' | 'standard' | 'subscribe' | 'record'>;
```

Uses: [`Uitive`](https://uitive.dev/docs/api/core#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`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/ask.ts), [`banner.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/banner.ts), [`client-like.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/client-like.ts), [`confirm.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/confirm.ts), [`element.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/element.ts), [`html.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/html.ts), [`more.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/more.ts), [`your-interface.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/your-interface.ts)

### escape

Escapes any value for HTML text and attribute values. Every interpolation goes through it.

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

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

```ts
class UitiveBanner extends UitiveElement {}
```

Uses: [`ClientLike`](https://uitive.dev/docs/api/dom#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.

```ts
class UitiveConfirm extends UitiveElement<ConfirmClientLike> {}
```

Uses: [`ConfirmClientLike`](https://uitive.dev/docs/api/dom#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.

```ts
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`](https://uitive.dev/docs/api/dom#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.

```ts
class UitiveMore extends UitiveElement<MoreClientLike> {}
```

Uses: [`MoreClientLike`](https://uitive.dev/docs/api/dom#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.

```ts
class UitiveYourInterface extends UitiveElement {
  exportDocument(): ReturnType<ClientLike['export']> | undefined;
  importDocument(document_: unknown): Adaptation | undefined;
}
```

Uses: [`Adaptation`](https://uitive.dev/docs/api/core#adaptation), [`ClientLike`](https://uitive.dev/docs/api/dom#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.

```ts
type AskClientLike = ClientLike & Pick<Uitive, 'ask'>;
```

Uses: [`ClientLike`](https://uitive.dev/docs/api/dom#clientlike), [`Uitive`](https://uitive.dev/docs/api/core#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.

```ts
type ClientLike = Pick<
  Uitive,
  | 'contract'
  | 'getSnapshot'
  | 'subscribe'
  | 'explain'
  | 'revert'
  | 'revertAdaptation'
  | 'keep'
  | 'accept'
  | 'dismiss'
  | 'preview'
  | 'freeze'
  | 'setGoal'
  | 'setView'
  | 'reset'
  | 'clearData'
  | 'export'
  | 'import'
>;
```

Uses: [`Uitive`](https://uitive.dev/docs/api/core#uitive).

### ConfirmClientLike

What `<uitive-confirm>` needs from a client.

```ts
type ConfirmClientLike = ClientLike & Pick<Uitive, 'confirm' | 'cancel' | 'confirmations'>;
```

Uses: [`ClientLike`](https://uitive.dev/docs/api/dom#clientlike), [`Uitive`](https://uitive.dev/docs/api/core#uitive).

### DebugClientLike

What the debug panel needs on top: usage, requests and the controls of the loop.

```ts
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`](https://uitive.dev/docs/api/dom#clientlike), [`Persona`](https://uitive.dev/docs/api/core#persona), [`SessionReport`](https://uitive.dev/docs/api/core#sessionreport), [`Uitive`](https://uitive.dev/docs/api/core#uitive).

### MoreClientLike

What `<uitive-more>` needs from a client.

```ts
type MoreClientLike = ClientLike & Pick<Uitive, 'surface' | 'standard' | 'record'>;
```

Uses: [`ClientLike`](https://uitive.dev/docs/api/dom#clientlike), [`Uitive`](https://uitive.dev/docs/api/core#uitive).

## `@plurid/uitive-dom/debug`

Source: [`debug.ts`](https://github.com/plurid/uitive/blob/3cbf3ac33467567dce35b83159d6d3b290f648d3/packages/dom/src/debug.ts)

### defineDebugElement

Registers `<uitive-debug>`. Safe to call more than once, and a no-op without a DOM.

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

```ts
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`](https://uitive.dev/docs/api/dom#debugclientlike), [`Persona`](https://uitive.dev/docs/api/core#persona), [`SessionReport`](https://uitive.dev/docs/api/core#sessionreport).

| Member | Default | Description |
| - | - | - |
| `personas` | `[]` | Personas offered for "Simulate a week". |
| `simulatePersona()` | | Simulates a week of use as a persona, where the client lives. |
