UI kit reference

zidane-ui/app/headless

import { … } from 'zidane-ui/app/headless'ui/src/app/headless/index.ts

Functions#

`createResourceStore`Function#

A new resource store over an invalidation source.

TypeScript

function createResourceStore<Topic extends string = string>(
  options?: ResourceStoreOptions<Topic>,
): ResourceStore<Topic>

Type parameters

Type parameters
Name	Type	Default	Description
Topic	`extends string`	`string`

Parameters

Parameters
Name	Type	Default	Description
options?	`ResourceStoreOptions<Topic>`	`{}`	The event source, the watched topics and the focus signal.

Returns

ResourceStore<Topic>

ui/src/app/headless/resource.ts:199

`readableResource`Function#

One resource of a store as a readable value (get + subscribe, the shape hosts hand to components): subscribing keeps it live like a mounted reader. Both methods keep their identity.

TypeScript

function readableResource<T, Topic extends string = string>(
  store: ResourceStore<Topic>,
  spec: ResourceSpec<T, Topic>,
): { get(): ResourceSnapshot<T>; subscribe(listener: () => void): () => void }

Type parameters

Type parameters
Name	Type	Default	Description
T
Topic	`extends string`	`string`

Parameters

Parameters
Name	Type	Description
store	`ResourceStore<Topic>`	The store holding it.
spec	`ResourceSpec<T, Topic>`	The resource.

Returns

{ get(): ResourceSnapshot<T>; subscribe(listener: () => void): () => void }

ui/src/app/headless/resource.ts:439

`resourceEventMatches`Function#

Whether event concerns a resource with options: its topic is listed, and absent fields on either side mean "any"; folders match when one holds the other (a repo root vs a subfolder).

TypeScript

function resourceEventMatches<Topic extends string>(
  event: ResourceEvent<Topic>,
  options: ResourceOptions<Topic>,
): boolean

Type parameters

Type parameters
Name	Type	Description
Topic	`extends string`

Parameters

Parameters
Name	Type	Description
event	`ResourceEvent<Topic>`	An invalidation event.
options	`ResourceOptions<Topic>`	A resource's options.

Returns

boolean

ui/src/app/headless/resource.ts:160

Constants#

`IDLE_RESOURCE`Constant#

What a null spec reads.

TypeScript

const IDLE_RESOURCE: ResourceSnapshot<never>

ui/src/app/headless/resource.ts:137

Interfaces#

`AppHost`Interface#

Every area's host an app offers. An area whose host is absent is not shown.

TypeScript

interface AppHost

Properties

AppHost properties
Name	Type	Description
appearance?	`AppearanceHost`	Where the appearance preferences live, the extra themes, the pre-paint snapshot and the window effects. Absent: the app applies no appearance (the stylesheet's defaults).
approvals?	`ApprovalsHost`	Tool approvals (safe mode): the pending approvals, the decisions and the safelist. Absent: no approval UI.
chat?	`ChatHost`	The chat area: sessions, transcripts, sending and interactions. Absent: no chat.
composer?	`ComposerHost`	The rich composer's host: shared drafts, completions, ghost text and next-prompt suggestions. Absent: those stay off (`zidane-ui/chat/rich-composer`).
extensions?	`ExtensionsHost`	What the extensions behind the app contribute (slots, screens, renderers, dialogs, settings pages, webviews) and the way back to them. Absent: no extension UI.
files?	`FilesHost`	The Files and Diffs tabs' host: listing, reading, writing and searching files, git status, the working-tree diff and the editor preferences. Absent: no Files or Diffs tab.
git?	`GitHost`	The git area's host: branches and pull requests, worktrees, environment kinds and remote folders. Absent: no branch menu, no remote folder picker.
keybindings?	`KeybindingsHost`	Where the user's keybinding overrides live. Absent: the default bindings.
machines?	`MachinesHost`	Which agent hosts the app talks to and how they are: servers, machines, self-update, tokens, the local daemon. Absent: no host status, banners or server settings.
onboarding?	`OnboardingHost`	The setup wizard's host: detection, settings, sign-in and the commit. Absent: no onboarding.
palette?	`PaletteHost`	The command palette's host: commands, files, extension items, settings and recents. Absent: the palette lists only the app's own sources.
session?	`SessionHost`	The session panels' host: todos, the message queue and artifacts. Absent: no session panels.
settings?	`SettingsHost`	The zidane settings document: read, written through when this connection may. Absent: no settings rows.
sidebar?	`SidebarHost`	The session sidebar's platform members: Finder, standalone windows, environment commands. Absent: those menu rows hide.
terminal?	`TerminalHost`	The terminals: listing, opening and viewing them per scope. Absent: no terminal drawer or tab.
workspace?	`WorkspaceHost<WorkspaceScope>`	Where the side panel's layouts live, and the extension panels. Absent: layouts last as long as the page, no extension panels.

ui/src/app/headless/app-host.ts:28

`ResourceEvent`Interface#

An invalidation event: a topic, and the scope it is about (absent fields: any).

TypeScript

interface ResourceEvent<Topic extends string = string> extends ResourceScope

Type parameters

ResourceEvent type parameters
Name	Type	Default	Description
Topic	`extends string`	`string`

Properties

ResourceEvent properties
Name	Type	Description
cwd?from `ResourceScope`	`string`	The folder (an event about a folder that holds it, or that it holds, concerns it).
hostId?from `ResourceScope`	`string`	The host (this computer's or a server's id).
sessionId?from `ResourceScope`	`string`	The session.
topic	`Topic`	What changed.

ui/src/app/headless/resource.ts:46

`ResourceInvalidation`Interface#

Where invalidation events come from (an app's IPC, a server's signals).

TypeScript

interface ResourceInvalidation<Topic extends string = string>

Type parameters

ResourceInvalidation type parameters
Name	Type	Default	Description
Topic	`extends string`	`string`

Properties

ResourceInvalidation properties
Name	Type	Description
onInvalidate	`(listener: (event: ResourceEvent<Topic>) => void) => () => void`	Calls `listener` with each event; returns the unsubscribe.
unwatch?	`(topic: Topic, cwd: string) => unknown`	Stop emitting it.
watch?	`(topic: Topic, cwd: string) => unknown`	Start emitting a watched topic for a folder.

ui/src/app/headless/resource.ts:91

`ResourceOptions`Interface#

How a resource stays current.

TypeScript

interface ResourceOptions<Topic extends string = string>

Type parameters

ResourceOptions type parameters
Name	Type	Default	Description
Topic	`extends string`	`string`

Properties

ResourceOptions properties
Name	Type	Description
revalidateOnFocus?	`boolean`	Refetch (when old) as the window regains focus.
scope?	`ResourceScope`	What the data is about.
topics?	`readonly Topic[]`	Topics whose events stale this resource.
ttl?	`number`	A new reader refetches data older than this (ms).

ui/src/app/headless/resource.ts:52

`ResourceScope`Interface#

What a resource's data is about; an event naming another folder, server or session leaves it alone.

TypeScript

interface ResourceScope

Properties

ResourceScope properties
Name	Type	Description
cwd?	`string`	The folder (an event about a folder that holds it, or that it holds, concerns it).
hostId?	`string`	The host (this computer's or a server's id).
sessionId?	`string`	The session.

ui/src/app/headless/resource.ts:36

`ResourceSnapshot`Interface#

A resource as read: immutable, replaced only when something changed.

TypeScript

interface ResourceSnapshot<T>

Type parameters

ResourceSnapshot type parameters
Name	Description
T

Properties

ResourceSnapshot properties
Name	Type	Description
data	`T \| undefined`	The last data fetched.
error	`unknown`	The last fetch's error.
refresh	`() => Promise<void>`	Refetch now; keeps its identity for the life of the entry.
stale	`boolean`	`data` is known out of date (invalidated, refetching).
status	`ResourceStatus`	See `ResourceStatus`.

ui/src/app/headless/resource.ts:77

`ResourceSpec`Interface#

One kind of data: the same key and fetcher wherever it is read.

TypeScript

interface ResourceSpec<T, Topic extends string = string>

Type parameters

ResourceSpec type parameters
Name	Type	Default	Description
T
Topic	`extends string`	`string`

Properties

ResourceSpec properties
Name	Type	Description
fetcher	`() => Promise<T>`	Reads the data.
key	`ResourceKey`	The resource's identity.
options?	`ResourceOptions<Topic>`	How it stays current; the first read of a key decides.

ui/src/app/headless/resource.ts:64

`ResourceStore`Interface#

A store of resources; see the top of this file.

TypeScript

interface ResourceStore<Topic extends string = string>

Type parameters

ResourceStore type parameters
Name	Type	Default	Description
Topic	`extends string`	`string`

Properties

ResourceStore properties
Name	Type	Description
fetch	`<T>(spec: ResourceSpec<T, Topic>) => Promise<T>`	The data now: a fresh value is reused and an in-flight fetch joined. Rejects with the fetch's error.
keyOf	`(key: ResourceKey) => string`	The serialized form of a key: what `ResourceStore.peekKey` takes.
peek	`<T>(spec: ResourceSpec<T, Topic>) => ResourceSnapshot<T>`	The snapshot `spec` holds now, without reading or subscribing.
peekKey	`(id: string) => ResourceSnapshot<unknown>`	The snapshot a serialized key holds now (`loading` before anyone subscribed).
reset	`() => void`	Forget every entry and listener, and unhook the event source (tests).
subscribe	`<T>(spec: ResourceSpec<T, Topic>, onChange: (snapshot: ResourceSnapshot<T>) => void) => () => void`	Keep `spec` live; `onChange` gets the current snapshot now and every new one. Returns the unsubscribe.
subscribeInvalidation	`(options: ResourceOptions<Topic>, listener: (event: ResourceEvent<Topic>) => void) => () => void`	`listener` hears the events `options` matches (as a resource with them would), watched topics watched meanwhile.
watch	`<T>(spec: ResourceSpec<T, Topic>, listener: () => void) => () => void`	Keep `spec` live; `listener` hears each new snapshot (not the current one). Returns the unsubscribe.

ui/src/app/headless/resource.ts:114

`ResourceStoreOptions`Interface#

Options of createResourceStore.

TypeScript

interface ResourceStoreOptions<Topic extends string = string>

Type parameters

ResourceStoreOptions type parameters
Name	Type	Default	Description
Topic	`extends string`	`string`

Properties

ResourceStoreOptions properties
Name	Type	Description
invalidation?	`() => ResourceInvalidation<Topic> \| undefined`	The event source, read when the store first needs it (and again after `reset`), so an app can install it after the store is made. Absent or `undefined`: no invalidation, only TTL and refresh.
onFocus?	`(listener: () => void) => () => void`	Calls `listener` when the window regains focus; returns the unsubscribe. Default: the window's `focus` event.
watchedTopics?	`readonly Topic[]`	Topics only emitted while watched for a folder.

ui/src/app/headless/resource.ts:101

Types#

`ResourceKey`Type#

A resource's identity: a string, or values serialized as JSON.

TypeScript

type ResourceKey = string | readonly unknown[]

ui/src/app/headless/resource.ts:33

`ResourceStatus`Type#

Where a resource is: idle (nothing asked), loading (the first fetch runs), then the last fetch's outcome.

TypeScript

type ResourceStatus = 'idle' | 'loading' | 'success' | 'error'

ui/src/app/headless/resource.ts:74

Functions#

createResourceStoreFunction#

Type parameters

Parameters

Returns

readableResourceFunction#

Type parameters

Parameters

Returns

resourceEventMatchesFunction#

Type parameters

Parameters

Returns

Constants#

IDLE_RESOURCEConstant#

Interfaces#

AppHostInterface#

Properties

ResourceEventInterface#

Type parameters

Properties

ResourceInvalidationInterface#

Type parameters

Properties

ResourceOptionsInterface#

Type parameters

Properties

ResourceScopeInterface#

Properties

ResourceSnapshotInterface#

Type parameters

Properties

ResourceSpecInterface#

Type parameters

Properties

ResourceStoreInterface#

Type parameters

Properties

ResourceStoreOptionsInterface#

Type parameters

Properties

Types#

ResourceKeyType#

ResourceStatusType#

`createResourceStore`Function#

`readableResource`Function#

`resourceEventMatches`Function#

`IDLE_RESOURCE`Constant#

`AppHost`Interface#

`ResourceEvent`Interface#

`ResourceInvalidation`Interface#

`ResourceOptions`Interface#

`ResourceScope`Interface#

`ResourceSnapshot`Interface#

`ResourceSpec`Interface#

`ResourceStore`Interface#

`ResourceStoreOptions`Interface#

`ResourceKey`Type#

`ResourceStatus`Type#