zidane-ui 9.1.1 → 9.1.3

package/src/extensions/testing/contract.ts

@@ -1,382 +0,0 @@
-/**
- * What every `ExtensionsHost` implementation does alike, as a vitest suite: the in-memory fixture
- * (`createFixtureExtensionsHost`), the desktop app's over IPC, `adapters/`' over zidane-server.
- *
- * An implementation's test calls {@link describeExtensionsHostContract} with a harness factory. The
- * contract hands it an {@link ExtensionsHostContractBackend}: the items there at the start and what
- * the extensions behind the host answer. The harness builds the host over a backend that does that
- * (a fixture, a fake server, a mocked IPC bridge) and returns an {@link ExtensionsHostContractControl}
- * that drives the backend from outside: items coming and going, dialogs and `ctx.ui` calls routed
- * to this client, another client writing a store. The capabilities list says which optional members
- * the host offers: the suite checks the others are undefined and skips what needs them.
- *
- *   describeExtensionsHostContract('createServerExtensionsHost', (backend) => ({ host, control }), [
- *     'invoke', 'dialogs', 'rpc',
- *   ]);
- */
-import { afterEach, describe, expect, it, vi } from 'vitest';
-
-import type { ExtensionUiEffectResult } from '../headless/effect-channel';
-import {
-  ExtensionsHostError,
-  type ExtensionCallbackId,
-  type ExtensionCallbacks,
-  type ExtensionCommandWire,
-  type ExtensionIntegrationWire,
-  type ExtensionSettingsWire,
-  type ExtensionStoreRef,
-  type ExtensionsHost,
-  type ExtensionUiEffect,
-  type ExtensionUiEffectRequest,
-} from '../headless/host';
-import { EXTENSION_TOKENS, type DialogRequestWire, type ExtensionItem } from '../headless/wire';
-
-/** An optional `ExtensionsHost` member. `settings.set` is the settings' write. */
-export type ExtensionsHostCapability =
-  'invoke' | 'dialogs' | 'effects' | 'rpc' | 'storage' | 'settings' | 'settings.set' | 'integrations' | 'commands';
-
-const MEMBERS = ['invoke', 'dialogs', 'effects', 'rpc', 'storage', 'settings', 'integrations', 'commands'] as const;
-
-/** A scripted RPC method: returns its output, or throws `{ type, message, data? }` to answer that error. */
-export type ContractRpcMethod = (input: unknown) => unknown;
-
-/** What the backend behind the host holds and does. */
-export interface ExtensionsHostContractBackend {
-  /** The items there at the start. */
-  items: readonly ExtensionItem[];
-  /** What each callback answers. A callback that throws answers `failed` with its message. */
-  callbacks: { [K in ExtensionCallbackId]?: (args: ExtensionCallbacks[K]['args']) => ExtensionCallbacks[K]['result'] };
-  /** RPC methods, by contract then method. */
-  rpc: Readonly<Record<string, Readonly<Record<string, ContractRpcMethod>>>>;
-  /** The stored value of {@link CONTRACT_STORE}. */
-  storeValue: unknown;
-  /** The settings. The backend refuses a write to a locked key (`refused` / `locked`). */
-  settings: ExtensionSettingsWire;
-  /**
-   * The integrations. `connect` with the key {@link CONTRACT_GOOD_KEY} adds the account `demo` (the first
-   * connection becomes the default); any other key is refused (`refused` / `invalid`). `disconnect` removes
-   * one account, or all with none named; `setDefault` moves an account first and makes it the default. The
-   * list keeps the default first, the only one with `isDefault`, also as `connection`.
-   */
-  integrations: readonly ExtensionIntegrationWire[];
-  /** The commands. Running an unknown id answers `false`. */
-  commands: readonly ExtensionCommandWire[];
-}
-
-/** Drives the backend from outside. */
-export interface ExtensionsHostContractControl {
-  /** An extension added or changed an item. */
-  upsert(entry: ExtensionItem): void;
-  /** An extension withdrew an item. */
-  remove(key: string): void;
-  /** An extension asked for a dialog routed to this client; resolves with the answer. */
-  dialog(
-    request: DialogRequestWire,
-    ctx: { extensionId: string; sessionId?: string; signal?: AbortSignal },
-  ): Promise<unknown>;
-  /** An extension's `ctx.ui` / `ctx.composer` call routed to this client; resolves with what the app settled. */
-  effect(effect: ExtensionUiEffect): Promise<ExtensionUiEffectResult>;
-  /** Another client wrote {@link CONTRACT_STORE}. */
-  writeStore(value: unknown): void;
-  /** {@link CONTRACT_STORE}'s value in the backend now. */
-  readStore(): unknown;
-  /** The commands the backend ran. */
-  ran(): readonly { id: string; args?: string; sessionId?: string }[];
-}
-
-/** A host built over a backend, the backend's control, and how to tear them down. */
-export interface ExtensionsHostHarness {
-  /** The host under test. */
-  host: ExtensionsHost;
-  /** Drives the backend the host talks to. */
-  control: ExtensionsHostContractControl;
-  /** Tears the host and its backend down after the test. */
-  dispose?(): void;
-}
-
-/** Builds a fresh host (and its backend) for one test. */
-export type ExtensionsHostHarnessFactory = (
-  backend: ExtensionsHostContractBackend,
-) => ExtensionsHostHarness | Promise<ExtensionsHostHarness>;
-
-/** The store the storage tests read and write. */
-export const CONTRACT_STORE: ExtensionStoreRef = { extensionId: 'demo', name: 'counter', scope: 'user' };
-/** The API key the backend's integrations accept. */
-export const CONTRACT_GOOD_KEY = 'good-key';
-
-const GITHUB_WORK = { methodId: 'oauth', account: 'work', label: 'Work', isDefault: true, connectedAt: 1 };
-
-const STATUS: ExtensionItem<'slot'> = {
-  key: 'slot:demo:1',
-  token: 'slot',
-  extension: 'demo',
-  item: { at: 'app.statusbar', text: 'Synced', order: 100 },
-};
-const PANEL: ExtensionItem<'panel'> = {
-  key: 'panel:demo:2',
-  token: 'panel',
-  extension: 'demo',
-  item: { id: 'demo/board', label: 'Board', surfaces: ['side'], live: false, actions: true },
-};
-
-const SETTINGS: ExtensionSettingsWire = {
-  schema: {
-    categories: [],
-    items: [
-      { key: 'enabled', label: 'Enabled', type: 'boolean', default: true, category: 'demo', extension: 'demo' },
-      { key: 'token', label: 'Token', type: 'string', default: '', category: 'demo', extension: 'demo' },
-    ],
-  },
-  actions: [],
-  values: { demo: { enabled: false } },
-  locked: ['demo:token'],
-};
-
-function backend(): ExtensionsHostContractBackend {
-  return {
-    items: [STATUS, PANEL],
-    callbacks: {
-      'panel.load': ({ panelId }) =>
-        ({ sections: [{ items: [{ kind: 'markdown', text: `hello from ${panelId}` }] }] }) as never,
-      'panel.action': () => {
-        throw new Error('the board is read-only');
-      },
-    },
-    rpc: {
-      'demo.counter': {
-        add: (input) => (input as { n: number }).n + 1,
-        fail: () => {
-          throw { type: 'demo.too-big', message: 'too big', data: { max: 3 } };
-        },
-      },
-    },
-    storeValue: { count: 1 },
-    settings: SETTINGS,
-    integrations: [
-      { id: 'linear', name: 'Linear', extensionId: 'demo', methods: [{ type: 'apiKey', id: 'key', label: 'API key' }] },
-      {
-        id: 'github',
-        name: 'GitHub',
-        extensionId: 'demo',
-        methods: [{ type: 'oauth', id: 'oauth', label: 'Sign in' }],
-        connection: GITHUB_WORK,
-        connections: [GITHUB_WORK, { methodId: 'oauth', account: 'home', connectedAt: 2 }],
-      },
-    ],
-    commands: [{ id: 'demo.sync', title: 'Sync now', extensionId: 'demo' }],
-  };
-}
-
-async function rejection(promise: Promise<unknown>): Promise<ExtensionsHostError> {
-  try {
-    await promise;
-  } catch (err) {
-    expect(err).toBeInstanceOf(ExtensionsHostError);
-    return err as ExtensionsHostError;
-  }
-  throw new Error('expected a rejection');
-}
-
-/**
- * Declares the shared `ExtensionsHost` suite for one implementation.
- *
- * @param name - The implementation's name, shown in the suite title.
- * @param makeHarness - Builds a fresh host over a backend that does what it is given, once per test.
- * @param capabilities - The optional members the host offers. Every other optional member must be undefined.
- */
-export function describeExtensionsHostContract(
-  name: string,
-  makeHarness: ExtensionsHostHarnessFactory,
-  capabilities: readonly ExtensionsHostCapability[],
-): void {
-  const has = (c: ExtensionsHostCapability) => capabilities.includes(c);
-
-  describe(`ExtensionsHost contract: ${name}`, () => {
-    const cleanup: (() => void)[] = [];
-    afterEach(() => {
-      for (const done of cleanup.splice(0).reverse()) done();
-    });
-    const setup = async () => {
-      const harness = await makeHarness(backend());
-      cleanup.push(() => harness.dispose?.());
-      return harness;
-    };
-
-    it('offers exactly its capabilities; the members it leaves out are undefined', async () => {
-      const { host } = await setup();
-      for (const token of EXTENSION_TOKENS) expect(typeof host.items[token].get, token).toBe('function');
-      for (const member of MEMBERS) expect(host[member] === undefined, member).toBe(!has(member));
-      if (host.settings) expect(typeof host.settings.set).toBe(has('settings.set') ? 'function' : 'undefined');
-    });
-
-    it('lists the items per token, and follows them as they come, change and go', async () => {
-      const { host, control } = await setup();
-      expect(host.items.slot.get()).toEqual([STATUS]);
-      expect(host.items.panel.get()).toEqual([PANEL]);
-      const heard = vi.fn();
-      cleanup.push(host.items.slot.subscribe(heard));
-      const changed: ExtensionItem<'slot'> = { ...STATUS, item: { ...STATUS.item, text: 'Syncing', loader: true } };
-      control.upsert(changed);
-      await vi.waitFor(() => expect(host.items.slot.get()).toEqual([changed]));
-      expect(heard).toHaveBeenCalled();
-      control.remove(STATUS.key);
-      await vi.waitFor(() => expect(host.items.slot.get()).toEqual([]));
-      expect(host.items.panel.get()).toEqual([PANEL]);
-    });
-
-    it.skipIf(!has('invoke'))('invokes callbacks, and words a failing one as failed', async () => {
-      const { host } = await setup();
-      const content = await host.invoke!('panel.load', { panelId: 'demo/board', cwd: '/repo' });
-      expect(JSON.stringify(content)).toContain('hello from demo/board');
-      const err = await rejection(host.invoke!('panel.action', { panelId: 'demo/board', actionId: 'x', cwd: '/repo' }));
-      expect(err.error).toEqual({ code: 'failed', message: 'the board is read-only' });
-    });
-
-    it.skipIf(!has('dialogs'))('shows a routed dialog until answered, and toasts beside it', async () => {
-      const { host, control } = await setup();
-      expect(host.dialogs!.current.get()).toBeNull();
-      const answer = control.dialog({ kind: 'confirm', title: 'Delete it?' }, { extensionId: 'demo', sessionId: 's1' });
-      await vi.waitFor(() =>
-        expect(host.dialogs!.current.get()?.request).toEqual({ kind: 'confirm', title: 'Delete it?' }),
-      );
-      const toast = control.dialog({ kind: 'toast', text: 'Saved', tone: 'success' }, { extensionId: 'demo' });
-      await vi.waitFor(() =>
-        expect(host.dialogs!.toasts.get().map((d) => d.request)).toEqual([
-          { kind: 'toast', text: 'Saved', tone: 'success' },
-        ]),
-      );
-      const dialog = host.dialogs!.current.get()!;
-      expect(dialog.extensionId).toBe('demo');
-      await host.dialogs!.answer(dialog.id, true);
-      await expect(answer).resolves.toBe(true);
-      await vi.waitFor(() => expect(host.dialogs!.current.get()).toBeNull());
-      await host.dialogs!.answer(host.dialogs!.toasts.get()[0]!.id, undefined);
-      await expect(toast).resolves.toBeUndefined();
-    });
-
-    it.skipIf(!has('dialogs'))('drops a dialog the extension withdraws', async () => {
-      const { host, control } = await setup();
-      const abort = new AbortController();
-      const answer = control.dialog({ kind: 'prompt', title: 'Name?' }, { extensionId: 'demo', signal: abort.signal });
-      await vi.waitFor(() => expect(host.dialogs!.current.get()).not.toBeNull());
-      abort.abort(new Error('timed out'));
-      await expect(answer).rejects.toThrow();
-      await vi.waitFor(() => expect(host.dialogs!.current.get()).toBeNull());
-    });
-
-    it.skipIf(!has('effects'))('hands ctx.ui calls to the app and answers with what it settled', async () => {
-      const { host, control } = await setup();
-      const seen: ExtensionUiEffectRequest[] = [];
-      cleanup.push(
-        host.effects!.subscribe((request) => {
-          seen.push(request);
-          host.effects!.settle(request.id, request.effect.kind === 'panel-state' ? ['demo/board'] : true);
-        }),
-      );
-      await expect(control.effect({ kind: 'panel', action: 'open', panelId: 'demo/board' })).resolves.toBe(true);
-      await expect(control.effect({ kind: 'panel-state' })).resolves.toEqual(['demo/board']);
-      await expect(control.effect({ kind: 'composer', op: { op: 'insert', text: 'hi' } })).resolves.toBe(true);
-      expect(seen.map((r) => r.effect.kind)).toEqual(['panel', 'panel-state', 'composer']);
-    });
-
-    it.skipIf(!has('rpc'))('calls RPC methods and rejects with their typed error', async () => {
-      const { host } = await setup();
-      await expect(host.rpc!('demo.counter', 'add', { n: 1 }, { extensionId: 'demo' })).resolves.toBe(2);
-      const err = await rejection(host.rpc!('demo.counter', 'fail', {}, { extensionId: 'demo' }));
-      expect(err.error).toEqual({ code: 'rpc', type: 'demo.too-big', message: 'too big', data: { max: 3 } });
-    });
-
-    it.skipIf(!has('storage'))('reads, writes and follows a store', async () => {
-      const { host, control } = await setup();
-      const store = host.storage!.store(CONTRACT_STORE);
-      await vi.waitFor(() => expect(store.get()).toEqual({ count: 1 }));
-      await host.storage!.set(CONTRACT_STORE, { count: 2 });
-      await vi.waitFor(() => expect(control.readStore()).toEqual({ count: 2 }));
-      await vi.waitFor(() => expect(store.get()).toEqual({ count: 2 }));
-      const heard = vi.fn();
-      cleanup.push(store.subscribe(heard));
-      control.writeStore({ count: 5 });
-      await vi.waitFor(() => expect(store.get()).toEqual({ count: 5 }));
-      expect(heard).toHaveBeenCalled();
-    });
-
-    it.skipIf(!has('settings'))('lists the settings with their locked keys', async () => {
-      const { host } = await setup();
-      await vi.waitFor(() =>
-        expect(host.settings!.wire.get().schema.items.map((i) => i.key)).toEqual(['enabled', 'token']),
-      );
-      expect(host.settings!.wire.get().locked).toEqual(['demo:token']);
-      expect(host.settings!.wire.get().values.demo?.enabled).toBe(false);
-    });
-
-    it.skipIf(!has('settings.set'))('writes a setting, and refuses a locked one', async () => {
-      const { host } = await setup();
-      await host.settings!.set!('demo', 'enabled', true);
-      await vi.waitFor(() => expect(host.settings!.wire.get().values.demo?.enabled).toBe(true));
-      const err = await rejection(host.settings!.set!('demo', 'token', 'x'));
-      expect(err.error).toMatchObject({ code: 'refused', reason: 'locked' });
-    });
-
-    it.skipIf(!has('integrations'))('connects and disconnects an integration', async () => {
-      const { host } = await setup();
-      const linear = () => host.integrations!.list.get().find((i) => i.id === 'linear');
-      await vi.waitFor(() => expect(linear()).toBeDefined());
-      expect(linear()!.connection).toBeUndefined();
-      const err = await rejection(host.integrations!.connect('linear', { methodId: 'key', key: 'nope' }));
-      expect(err.error).toMatchObject({ code: 'refused', reason: 'invalid' });
-      await host.integrations!.connect('linear', { methodId: 'key', key: CONTRACT_GOOD_KEY });
-      await vi.waitFor(() => expect(linear()!.connection).toMatchObject({ methodId: 'key', account: 'demo' }));
-      expect(linear()!.connections).toEqual([expect.objectContaining({ account: 'demo', isDefault: true })]);
-      await host.integrations!.disconnect('linear');
-      await vi.waitFor(() => expect(linear()!.connection).toBeUndefined());
-      expect(linear()!.connections ?? []).toEqual([]);
-    });
-
-    const accounts = (i: ExtensionIntegrationWire | undefined) =>
-      (i?.connections ?? []).map((c) => [c.account, c.isDefault === true]);
-
-    it.skipIf(!has('integrations'))("lists an integration's connections, the default first", async () => {
-      const { host } = await setup();
-      const github = () => host.integrations!.list.get().find((i) => i.id === 'github');
-      await vi.waitFor(() => expect(github()).toBeDefined());
-      expect(accounts(github())).toEqual([
-        ['work', true],
-        ['home', false],
-      ]);
-      expect(github()!.connection).toMatchObject({ account: 'work', label: 'Work', isDefault: true });
-    });
-
-    it.skipIf(!has('integrations'))('disconnects one account, then the rest', async () => {
-      const { host } = await setup();
-      const github = () => host.integrations!.list.get().find((i) => i.id === 'github');
-      await vi.waitFor(() => expect(github()).toBeDefined());
-      await host.integrations!.disconnect('github', { account: 'home' });
-      await vi.waitFor(() => expect(accounts(github())).toEqual([['work', true]]));
-      await host.integrations!.disconnect('github');
-      await vi.waitFor(() => expect(github()!.connection).toBeUndefined());
-      expect(accounts(github())).toEqual([]);
-    });
-
-    it.skipIf(!has('integrations'))('makes another account the default', async () => {
-      const { host } = await setup();
-      const github = () => host.integrations!.list.get().find((i) => i.id === 'github');
-      await vi.waitFor(() => expect(github()).toBeDefined());
-      await host.integrations!.setDefault('github', 'home');
-      await vi.waitFor(() =>
-        expect(accounts(github())).toEqual([
-          ['home', true],
-          ['work', false],
-        ]),
-      );
-      expect(github()!.connection).toMatchObject({ account: 'home', isDefault: true });
-    });
-
-    it.skipIf(!has('commands'))('lists and runs commands', async () => {
-      const { host, control } = await setup();
-      await vi.waitFor(() => expect(host.commands!.list.get().map((c) => c.id)).toEqual(['demo.sync']));
-      await expect(host.commands!.run('demo.sync', { sessionId: 's1' })).resolves.toBe(true);
-      expect(control.ran()).toEqual([{ id: 'demo.sync', sessionId: 's1' }]);
-      await expect(host.commands!.run('demo.nope')).resolves.toBe(false);
-    });
-  });
-}

package/src/extensions/testing/index.ts

@@ -1,6 +0,0 @@
-/**
- * `zidane-ui/extensions/testing`: an `ExtensionsHost` that runs in memory
- * (`createFixtureExtensionsHost`, `fixtureItem`), for docs, demos,
- * galleries and an app's own tests. Not for production hosts.
- */
-export * from '../headless/fixture-host';

package/src/extensions/useExtensionsLabels.ts

@@ -1,14 +0,0 @@
-/**
- * The extensions components' labels: the defaults, overridable through
- * `<LabelsProvider>` or `ExtensionsProvider`'s `labels`.
- */
-import { useMemo } from 'react';
-
-import { useLabels } from '../labels';
-import { DEFAULT_EXTENSIONS_LABELS, type ExtensionsLabels } from './headless/labels';
-
-/** Returns the extensions components' strings: the defaults merged with any overrides. */
-export function useExtensionsLabels(): ExtensionsLabels {
-  const overrides = useLabels() as Partial<ExtensionsLabels>;
-  return useMemo(() => ({ ...DEFAULT_EXTENSIONS_LABELS, ...overrides }), [overrides]);
-}