zidane-ui 9.1.1 → 9.1.3

package/src/extensions/ExtensionsProvider.tsx

@@ -1,124 +0,0 @@
-/**
- * Puts an `ExtensionsHost` in context, with the loader of the extensions'
- * `ui.tsx` bundles and optional label overrides:
- *
- *   <ExtensionsProvider host={host} loadModule={(id) => import(\`/ext/\${id}/ui.js\`)}>
- *     <ExtensionSlot at="app.statusbar" />
- *     <ExtensionDialogHost />
- *   </ExtensionsProvider>
- *
- * Components below read the host's stores through `useExtensionItems`.
- * Without a provider they draw nothing (no host: no extension UI).
- */
-import { createContext, useCallback, useContext, useEffect, useMemo, type ReactNode } from 'react';
-
-import { constant, useReadable, type Readable } from '../chat/headless/store';
-import { pressChord } from '../keybindings/press';
-import { LabelsProvider, useLabels } from '../labels';
-import { createEffectRouter, type ExtensionEffectRouter } from './headless/effect-router';
-import type { ExtensionsHost } from './headless/host';
-import type { ExtensionsLabels } from './headless/labels';
-import type { ExtensionItem, ExtensionTokenName } from './headless/wire';
-import {
-  ExtensionComponentsProvider,
-  useExtensionModuleLoader,
-  type ExtensionModuleLoader,
-} from './ExtensionComponent';
-
-const HostContext = createContext<ExtensionsHost | null>(null);
-
-/** The kit's keymap route: above an app's default 0, like the kit's other routes (`KIT_EFFECT_PRIORITY`). */
-const KEYMAP_EFFECT_PRIORITY = 10;
-const RouterContext = createContext<ExtensionEffectRouter | null>(null);
-
-/** Props for {@link ExtensionsProvider}. */
-export interface ExtensionsProviderProps {
-  /** What the extensions contribute, and the way back to them. */
-  host: ExtensionsHost;
-  /** Loads an extension's `ui.tsx` module (its exports are the components items name). Absent: items draw their data. */
-  loadModule?: ExtensionModuleLoader;
-  /** Overrides for the built-in strings. Keys you leave out keep the default English label. */
-  labels?: Partial<ExtensionsLabels>;
-  /** The app. */
-  children: ReactNode;
-}
-
-/**
- * Provides an {@link ExtensionsHost}, the `ui.tsx` loader and optional label overrides to the extension components below it.
- *
- * @param props - Provider props: the `host`, an optional `loadModule` and `labels`, and the `children`.
- */
-export function ExtensionsProvider({ host, loadModule, labels, children }: ExtensionsProviderProps) {
-  const body = <LabelsProvider<ExtensionsLabels> labels={labels}>{children}</LabelsProvider>;
-  // One router per host: every part below that applies effects registers on it (`useExtensionEffects`).
-  const effects = host.effects;
-  const router = useMemo(() => (effects ? createEffectRouter(effects) : null), [effects]);
-  // `ctx.keymap.dispatch`: the chord pressed where focus is in this window, the one viewing the session.
-  useEffect(
-    () =>
-      router?.register({
-        accepts: (effect) => effect.kind === 'keymap',
-        apply: (effect) => effect.kind === 'keymap' && pressChord(effect.chord),
-        priority: KEYMAP_EFFECT_PRIORITY,
-      }),
-    [router],
-  );
-  return (
-    <HostContext.Provider value={host}>
-      <RouterContext.Provider value={router}>
-        {loadModule ? <ExtensionComponentsProvider loadModule={loadModule}>{body}</ExtensionComponentsProvider> : body}
-      </RouterContext.Provider>
-    </HostContext.Provider>
-  );
-}
-
-/** The effect router of the nearest {@link ExtensionsProvider}, or `null` (no provider, or a host without `effects`). */
-export function useExtensionEffectRouter(): ExtensionEffectRouter | null {
-  return useContext(RouterContext);
-}
-
-/** The {@link ExtensionsHost} from the nearest {@link ExtensionsProvider}, or `null` outside one. */
-export function useExtensionsHost(): ExtensionsHost | null {
-  return useContext(HostContext);
-}
-
-const NONE: Readable<readonly ExtensionItem[]> = constant([]);
-
-/**
- * The items of one token, re-rendering when they change. Empty outside an {@link ExtensionsProvider}.
- *
- * @param token - The token.
- */
-export function useExtensionItems<N extends ExtensionTokenName>(token: N): readonly ExtensionItem<N>[] {
-  const host = useExtensionsHost();
-  return useReadable((host?.items[token] ?? NONE) as Readable<readonly ExtensionItem<N>[]>);
-}
-
-/**
- * Returns `wrap(node)`, which puts this tree's extensions host, `ui.tsx` loader and labels around a
- * node rendered elsewhere: the app's modal layer sits above the providers, so a dialog or screen
- * opened on it carries them in.
- */
-export function useCarryExtensionsContext(): (node: ReactNode) => ReactNode {
-  const host = useExtensionsHost();
-  const router = useExtensionEffectRouter();
-  const loader = useExtensionModuleLoader();
-  const labels = useLabels();
-  return useCallback(
-    (node: ReactNode) => {
-      const loaded = loader ? (
-        <ExtensionComponentsProvider loadModule={loader}>{node}</ExtensionComponentsProvider>
-      ) : (
-        node
-      );
-      return (
-        <LabelsProvider labels={labels}>
-          <HostContext.Provider value={host}>
-            <RouterContext.Provider value={router}>{loaded}</RouterContext.Provider>
-          </HostContext.Provider>
-        </LabelsProvider>
-      );
-    },
-    [host, router, loader, labels],
-  );
-}

package/src/extensions/SettingsWireForm.tsx

@@ -1,182 +0,0 @@
-/**
- * Settings rows over the settings wire (zidane's `WireSettings`): the rows of a
- * form dialog (`ctx.ui.form`) and of an extension's settings page. Booleans are a
- * switch row, enums a select, numbers and strings an input (a secret one hidden,
- * a multiline one a text area), `model` items a free id input. Action rows run on
- * the host. A locked setting (set by a declarative config entry) shows its value,
- * disabled, with why. Enums cycle their options, as in Settings. The rows are controlled: the parent holds the values and
- * decides when they are written (a form on submit, a page at once).
- *
- * The rows are Settings › Extensions' own (`ExtensionConfigRow`, `ExtensionActionRow`
- * from `zidane-ui/settings`), so both screens draw a setting alike.
- */
-import type { CSSProperties } from 'react';
-import type { WireExtensionConfigItem } from 'zidane';
-
-import { FormSection, MetaChip } from '../components/Form';
-import { SettingFocus } from '../settings/section';
-import { ExtensionActionRow, ExtensionConfigRow } from '../settings/sections/extensions/ExtensionConfigRows';
-import type { ExtensionAccessScope } from './headless/host';
-import { isSettingLocked, missingScope, type SettingValue } from './headless/select';
-import type { WireSettings } from './headless/wire';
-import { useExtensionsLabels } from './useExtensionsLabels';
-
-/** An action row's outcome, as the parent reports it. */
-export interface SettingsWireActionState {
-  /** `busy` disables the row's button; `error` draws `text` as a failure. */
-  state: 'busy' | 'done' | 'error';
-  /** Status line under the row. Absent: none. */
-  text?: string;
-}
-
-/** Props for {@link SettingsWireForm}. */
-export interface SettingsWireFormProps {
-  /** The rows. */
-  settings: WireSettings;
-  /** The values shown, by extension then key (`settingsValues` gives the starting ones). */
-  values: Readonly<Record<string, Readonly<Record<string, SettingValue>>>>;
-  /** A row changed (a switch flipped, an input committed). Locked rows never call it. */
-  onChange(extension: string, key: string, value: SettingValue): void;
-  /** Runs an action row. Absent: no action rows. */
-  onRunAction?(extension: string, key: string): void;
-  /** Action rows' outcomes, by `extension:key`. */
-  actionStates?: Readonly<Record<string, SettingsWireActionState>>;
-  /** A message per row (a refused write), by `extension:key`. */
-  errors?: Readonly<Record<string, string>>;
-  /**
-   * The scope this client's token grants (`ExtensionsHost.scope`): an action needing more shows its
-   * button disabled, with why. `null` or absent: never limited (a local or in-process host).
-   */
-  scope?: ExtensionAccessScope | null;
-  /** Extra classes on the root. */
-  className?: string;
-  /** Inline styles on the root. */
-  style?: CSSProperties;
-}
-
-interface Category {
-  id: string;
-  label: string | undefined;
-  items: WireExtensionConfigItem[];
-  actions: WireSettings['actions'];
-}
-
-function categories(settings: WireSettings): Category[] {
-  const labels = new Map(settings.schema.categories.map((c) => [c.id, c.label]));
-  const out = new Map<string, Category>();
-  const ensure = (id: string, extension: string, label?: string): Category => {
-    let cat = out.get(id);
-    if (!cat) {
-      // The implicit category (id === extension) gets no header.
-      cat = { id, label: id === extension ? undefined : (label ?? labels.get(id) ?? id), items: [], actions: [] };
-      out.set(id, cat);
-    }
-    return cat;
-  };
-  for (const item of settings.schema.items) ensure(item.category, item.extension).items.push(item);
-  for (const action of settings.actions)
-    ensure(action.category, action.extension, action.categoryLabel).actions.push(action);
-  return [...out.values()];
-}
-
-/**
- * Draws settings rows over the settings wire.
- *
- * @param props - The rows, their values, the change and action handlers, `className` and `style`.
- */
-export function SettingsWireForm({
-  settings,
-  values,
-  onChange,
-  onRunAction,
-  actionStates,
-  errors,
-  scope,
-  className,
-  style,
-}: SettingsWireFormProps) {
-  const labels = useExtensionsLabels();
-  const cats = categories(settings);
-  if (cats.length === 0) {
-    return (
-      <p className={`m-0 px-1 text-xs text-[var(--zg-text-muted)]${className ? ` ${className}` : ''}`} style={style}>
-        {labels.extensionSettingsNone}
-      </p>
-    );
-  }
-  return (
-    <div className={['space-y-5', className].filter(Boolean).join(' ')} style={style}>
-      {cats.map((cat) => (
-        <FormSection key={cat.id} title={cat.label}>
-          {cat.items.map((item) => {
-            const id = `${item.extension}:${item.key}`;
-            const value = values[item.extension]?.[item.key] ?? item.default;
-            return (
-              // Search lands on the row (`SettingsShell`'s focus): `<extension>:<key>`.
-              <SettingFocus key={id} id={id}>
-                <SettingRow
-                  item={item}
-                  value={value}
-                  locked={isSettingLocked(settings, item.extension, item.key)}
-                  onChange={onChange}
-                />
-                {errors?.[id] && <div className="px-3 pb-1.5 text-xs text-zg-danger">{errors[id]}</div>}
-              </SettingFocus>
-            );
-          })}
-          {onRunAction &&
-            cat.actions.map((action) => {
-              const id = `${action.extension}:${action.key}`;
-              const run = actionStates?.[id];
-              return (
-                <SettingFocus key={id} id={id}>
-                  <ExtensionActionRow
-                    label={action.label}
-                    {...(action.description ? { description: action.description } : {})}
-                    {...(run?.text ? { status: { text: run.text, error: run.state === 'error' } } : {})}
-                    busy={run?.state === 'busy'}
-                    needsScope={missingScope(scope, action.scope)}
-                    onRun={() => onRunAction(action.extension, action.key)}
-                  />
-                </SettingFocus>
-              );
-            })}
-        </FormSection>
-      ))}
-    </div>
-  );
-}
-
-function SettingRow({
-  item,
-  value,
-  locked,
-  onChange,
-}: {
-  item: WireExtensionConfigItem;
-  value: SettingValue;
-  locked: boolean;
-  onChange: SettingsWireFormProps['onChange'];
-}) {
-  const labels = useExtensionsLabels();
-  const lock = locked ? (
-    <MetaChip title={labels.extensionSettingLocked}>
-      <span aria-hidden className="i-ph-lock-simple" />
-      {labels.extensionSettingLocked}
-    </MetaChip>
-  ) : null;
-  return (
-    <ExtensionConfigRow
-      item={item}
-      value={value as string | number | boolean}
-      locked={locked}
-      lock={lock}
-      switchRole
-      maskSecrets
-      // A commit of the value shown is no change.
-      onWrite={(next) => {
-        if (next !== value) onChange(item.extension, item.key, next);
-      }}
-    />
-  );
-}

package/src/extensions/headless/dialog-queue.ts

@@ -1,92 +0,0 @@
-/**
- * The client half of `ctx.ui` dialogs, for hosts to build `ExtensionsHost.dialogs` on: the
- * backend's request lands in `show` (zidane's `DialogPort.show` on this client), waits in the
- * queue, and resolves with what the user answers. An aborted request leaves the queue unanswered.
- */
-import { writable } from '../../chat/headless/store';
-import type { ExtensionDialog, ExtensionDialogs } from './host';
-import type { DialogRequestWire } from './wire';
-
-/** Where a request comes from. */
-export interface DialogQueueShowContext {
-  /** The extension that asked. */
-  extensionId: string;
-  /** The session the dialog belongs to, when it has one. */
-  sessionId?: string;
-  /** Aborts when the backend withdraws the dialog (timeout, abort, the extension unloaded). */
-  signal?: AbortSignal;
-  /** The dialog's id; default: a fresh one. */
-  id?: string;
-}
-
-/** A dialog queue: the stores the UI reads, and the entry the backend calls. */
-export interface DialogQueue {
-  /** `ExtensionsHost.dialogs`. */
-  dialogs: ExtensionDialogs;
-  /** Queues a dialog; resolves with the answer (`undefined` for a cancel), rejects with the signal's reason. */
-  show(request: DialogRequestWire, ctx: DialogQueueShowContext): Promise<unknown>;
-  /** Drops every pending dialog unanswered (the client goes away). */
-  clear(): void;
-}
-
-interface Pending {
-  dialog: ExtensionDialog;
-  resolve: (answer: unknown) => void;
-  done: () => void;
-}
-
-/** Creates an empty {@link DialogQueue}. */
-export function createDialogQueue(): DialogQueue {
-  let seq = 0;
-  const pending: Pending[] = [];
-  const current = writable<ExtensionDialog | null>(null);
-  const toasts = writable<readonly ExtensionDialog[]>([]);
-  const publish = (): void => {
-    current.set(pending.find((p) => p.dialog.request.kind !== 'toast')?.dialog ?? null);
-    const next = pending.filter((p) => p.dialog.request.kind === 'toast').map((p) => p.dialog);
-    const prev = toasts.get();
-    if (next.length !== prev.length || next.some((d, i) => d !== prev[i])) toasts.set(next);
-  };
-  const take = (id: string): Pending | undefined => {
-    const index = pending.findIndex((p) => p.dialog.id === id);
-    if (index < 0) return undefined;
-    const [p] = pending.splice(index, 1);
-    p!.done();
-    publish();
-    return p;
-  };
-  return {
-    dialogs: {
-      current,
-      toasts,
-      answer: async (id, answer) => {
-        take(id)?.resolve(answer);
-      },
-    },
-    show(request, ctx) {
-      if (ctx.signal?.aborted) return Promise.reject(ctx.signal.reason);
-      const id = ctx.id ?? `dialog-${++seq}`;
-      const dialog: ExtensionDialog = {
-        id,
-        extensionId: ctx.extensionId,
-        ...(ctx.sessionId ? { sessionId: ctx.sessionId } : {}),
-        request,
-      };
-      return new Promise<unknown>((resolve, reject) => {
-        const onAbort = (): void => {
-          if (take(id)) reject(ctx.signal!.reason);
-        };
-        ctx.signal?.addEventListener('abort', onAbort, { once: true });
-        pending.push({ dialog, resolve, done: () => ctx.signal?.removeEventListener('abort', onAbort) });
-        publish();
-      });
-    },
-    clear() {
-      for (const p of pending.splice(0)) {
-        p.done();
-        p.resolve(undefined);
-      }
-      publish();
-    },
-  };
-}

package/src/extensions/headless/effect-channel.ts

@@ -1,50 +0,0 @@
-/**
- * The client half of zidane's `UiClientPort`, for hosts to build `ExtensionsHost.effects` on: the
- * backend's call lands in `apply`, every app listener hears it, and the first `settle` answers it.
- * With no listener the call answers "did nothing" (`false`, or no panels).
- */
-import type { ExtensionUiEffect, ExtensionUiEffectRequest, ExtensionUiEffects } from './host';
-
-/** What applying an effect gave: whether it did, the open panels, or nothing for a notification. */
-export type ExtensionUiEffectResult = boolean | readonly string[] | undefined;
-
-/** An effect channel. */
-export interface UiEffectChannel {
-  /** `ExtensionsHost.effects`. */
-  effects: ExtensionUiEffects;
-  /** Hands an effect to the app; resolves with what it settled. */
-  apply(effect: ExtensionUiEffect): Promise<ExtensionUiEffectResult>;
-}
-
-const idle = (effect: ExtensionUiEffect): ExtensionUiEffectResult =>
-  effect.kind === 'notify' ? undefined : effect.kind === 'panel-state' ? [] : false;
-
-/** Creates a {@link UiEffectChannel}. */
-export function createUiEffectChannel(): UiEffectChannel {
-  let seq = 0;
-  const listeners = new Set<(request: ExtensionUiEffectRequest) => void>();
-  const waiting = new Map<string, (result: ExtensionUiEffectResult) => void>();
-  return {
-    effects: {
-      subscribe(listener) {
-        listeners.add(listener);
-        return () => listeners.delete(listener);
-      },
-      settle(id, result) {
-        const resolve = waiting.get(id);
-        waiting.delete(id);
-        resolve?.(result);
-      },
-    },
-    apply(effect) {
-      if (listeners.size === 0) return Promise.resolve(idle(effect));
-      const request: ExtensionUiEffectRequest = { id: `effect-${++seq}`, effect };
-      const done =
-        effect.kind === 'notify'
-          ? Promise.resolve(undefined)
-          : new Promise<ExtensionUiEffectResult>((resolve) => waiting.set(request.id, resolve));
-      for (const listener of [...listeners]) listener(request);
-      return done;
-    },
-  };
-}

package/src/extensions/headless/effect-router.ts

@@ -1,107 +0,0 @@
-/**
- * Routes the `ctx.ui` / `ctx.composer` calls a host hands this client
- * (`ExtensionsHost.effects`) to the one part of the app that applies each:
- * the kit's own parts (the composer an edit is for, the modal layer for a
- * screen) and the app's handlers. Each call goes to exactly one route, so
- * an edit is never applied twice: the highest `priority` route that accepts
- * it, the earliest registered among equals. A call no route accepts is
- * answered "did nothing" at once (`false`, no panels), never left waiting.
- *
- * The router listens to the host only while a route is registered: with
- * none, the host's own "no listener" answer stands.
- *
- * The kit sends its own requests the same way (`apply`): a session row in a
- * panel the kit draws opens the session through the app's `navigate` route.
- */
-import type { ExtensionUiEffect, ExtensionUiEffects } from './host';
-
-/** What applying an effect gave: whether it did, the open panel ids for `panel-state`, nothing for `notify`. */
-export type ExtensionEffectOutcome = boolean | readonly string[] | void;
-
-/** Applies one effect. A throw or a rejection reports "did nothing". */
-export type ExtensionEffectApply = (
-  effect: ExtensionUiEffect,
-) => ExtensionEffectOutcome | Promise<ExtensionEffectOutcome>;
-
-/** One route: what it applies, and which effects it takes. */
-export interface ExtensionEffectRoute {
-  /** Applies an effect it accepted. */
-  apply: ExtensionEffectApply;
-  /** Whether it takes this effect. Absent: every effect. */
-  accepts?(effect: ExtensionUiEffect): boolean;
-  /** Higher first. Default 0 (an app's handler); the kit's narrow routes use more, so they win. */
-  priority?: number;
-}
-
-/** An effect router. */
-export interface ExtensionEffectRouter {
-  /** Adds a route. Returns its removal. */
-  register(route: ExtensionEffectRoute): () => void;
-  /**
-   * Applies an effect this client asks for itself (no extension sent it), through the route that takes it.
-   * Resolves with what it gave: "did nothing" (`false`, no panels) when no route takes it or the route failed.
-   * Session ids are the ones the host's own effects carry.
-   */
-  apply(effect: ExtensionUiEffect): Promise<boolean | readonly string[]>;
-}
-
-const idle = (effect: ExtensionUiEffect): boolean | readonly string[] => (effect.kind === 'panel-state' ? [] : false);
-
-/**
- * Creates an {@link ExtensionEffectRouter} over a host's effects.
- *
- * @param effects - The host's `effects`.
- */
-export function createEffectRouter(effects: ExtensionUiEffects): ExtensionEffectRouter {
-  let seq = 0;
-  const routes = new Map<number, ExtensionEffectRoute>();
-  let unsubscribe: (() => void) | null = null;
-
-  const pick = (effect: ExtensionUiEffect): ExtensionEffectRoute | undefined => {
-    let best: ExtensionEffectRoute | undefined;
-    // Map order is registration order: a later route wins only with a higher priority.
-    for (const route of routes.values()) {
-      if (route.accepts && !route.accepts(effect)) continue;
-      if (!best || (route.priority ?? 0) > (best.priority ?? 0)) best = route;
-    }
-    return best;
-  };
-
-  /** Runs `effect` on the route that takes it; "did nothing" without one. */
-  const run = (effect: ExtensionUiEffect): Promise<boolean | readonly string[]> => {
-    const route = pick(effect);
-    if (!route) return Promise.resolve(idle(effect));
-    return Promise.resolve()
-      .then(() => route.apply(effect))
-      .then(
-        (result) => (result ?? idle(effect)) as boolean | readonly string[],
-        () => idle(effect),
-      );
-  };
-
-  const listen = () =>
-    effects.subscribe(({ id, effect }) => {
-      const settle = (result: boolean | readonly string[]) => {
-        if (effect.kind !== 'notify') effects.settle(id, result);
-      };
-      // No route: answered at once, not a tick later.
-      if (!pick(effect)) settle(idle(effect));
-      else void run(effect).then(settle);
-    });
-
-  return {
-    apply: run,
-    register(route) {
-      const key = ++seq;
-      routes.set(key, route);
-      unsubscribe ??= listen();
-      return () => {
-        if (!routes.delete(key)) return;
-        if (routes.size === 0 && unsubscribe) {
-          unsubscribe();
-          unsubscribe = null;
-        }
-      };
-    },
-  };
-}