@kabmo-labs/kabmo-ui 0.0.0-stage → 0.0.1

package/src/panels.ts

@@ -0,0 +1,206 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Panel-facing hooks: what a view is rendered with, and how it reads the
+ * Kabmo's own state.
+ *
+ * These are the pieces a built-in panel and a plugin panel both need, and the
+ * reason they live in the published kit is that the alternative — each panel
+ * re-deriving them — is how Kabmo's eleven views drifted apart in the
+ * first place.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { requireServices, type PanelContext } from './services';
+
+/**
+ * The live panel context, re-rendering on every change.
+ *
+ * `useState` is seeded from the service and updated by its subscription, which
+ * is what makes a workspace that arrives after the first paint show up.
+ */
+export function usePanelInfo(): PanelContext {
+  const [context, setContext] = useState<PanelContext>(() => requireServices().context());
+
+  useEffect(() => {
+    const api = requireServices();
+    setContext(api.context());
+    return api.subscribe(setContext);
+  }, []);
+
+  return context;
+}
+
+/** The live palette id. */
+export function useTheme(): string {
+  return usePanelInfo().theme;
+}
+
+export interface SessionValue {
+  /** `null` until the read answers — the field should be disabled, not empty. */
+  value: string | null;
+  status: 'loading' | 'idle' | 'saving' | 'saved' | 'error';
+  error: string | null;
+  update: (next: string) => void;
+}
+
+/**
+ * Per-session state, as a `useState` that persists.
+ *
+ * The write is debounced: `onInput` fires per keystroke, and each one would
+ * otherwise be a store write and a request.
+ */
+export function useSessionValue(key: string, delayMs = 400): SessionValue {
+  const { sessionId } = usePanelInfo();
+  const [value, setValue] = useState<string | null>(null);
+  const [status, setStatus] = useState<SessionValue['status']>('loading');
+  const [error, setError] = useState<string | null>(null);
+  // Distinguishes "this component's own edit" from "someone else wrote the
+  // slot". Only the former may set `saving`, or an unrelated write would mark a
+  // field dirty and write it straight back.
+  const editing = useRef(false);
+
+  const read = useCallback((): string => {
+    try {
+      const stored = requireServices().getSessionValue(sessionId, key) ?? '';
+      setError(null);
+      return stored;
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+      setStatus('error');
+      return '';
+    }
+  }, [sessionId, key]);
+
+  useEffect(() => {
+    editing.current = false;
+    setStatus('loading');
+    setValue(read());
+    setStatus((current) => (current === 'error' ? current : 'idle'));
+  }, [read]);
+
+  // Follow writes from anywhere else — the header readout showing a note's
+  // length, a second view of the same value. Skipped while THIS component is
+  // mid-edit, because its own state is the newer truth until the debounce lands.
+  useEffect(() => {
+    const api = requireServices();
+    if (!api.subscribeSessionValue) return;
+    return api.subscribeSessionValue(sessionId, key, () => {
+      if (editing.current) return;
+      setValue(read());
+    });
+  }, [sessionId, key, read]);
+
+  useEffect(() => {
+    if (value === null || status !== 'saving') return;
+    const timer = setTimeout(() => {
+      try {
+        requireServices().setSessionValue(sessionId, key, value);
+        editing.current = false;
+        setStatus('saved');
+      } catch (cause) {
+        setError(cause instanceof Error ? cause.message : String(cause));
+        setStatus('error');
+      }
+    }, delayMs);
+    return () => clearTimeout(timer);
+  }, [sessionId, key, value, status, delayMs]);
+
+  const update = useCallback((next: string) => {
+    editing.current = true;
+    setValue(next);
+    setStatus('saving');
+  }, []);
+
+  return { value, status, error, update };
+}
+
+export interface WorkspaceFile {
+  content: string | null;
+  loading: boolean;
+  error: string | null;
+}
+
+/**
+ * Per-session state of any JSON shape, persisted by Kabmo's store.
+ *
+ * The `useState`-with-persistence contract, for a value that is not a string: a
+ * collapsed-phase map, a picked file. `ready` is false until the session's blob
+ * has loaded, so a view can hold its first render rather than paint a fallback
+ * over a value that is on its way.
+ */
+export function useSessionState<T>(
+  key: string,
+  fallback: T,
+): [T, (value: T | ((prev: T) => T)) => void, boolean] {
+  const { sessionId } = usePanelInfo();
+  const [ready, setReady] = useState(false);
+  const [local, setLocal] = useState<T>(() => requireServices().getSessionJson?.<T>(sessionId, key) ?? fallback);
+
+  const read = useCallback(() => {
+    const stored = requireServices().getSessionJson?.<T>(sessionId, key);
+    setLocal(stored === undefined ? fallback : stored);
+  }, [sessionId, key, fallback]);
+
+  useEffect(() => {
+    setReady(true);
+    read();
+  }, [read]);
+
+  // Follow writes from anywhere else, the same reason `useSessionValue` does:
+  // two readers of one key must not hold two private copies of the same fact.
+  useEffect(() => {
+    const api = requireServices();
+    if (!api.subscribeSessionJson) return;
+    return api.subscribeSessionJson(sessionId, key, read);
+  }, [sessionId, key, read]);
+
+  const setValue = useCallback(
+    (value: T | ((prev: T) => T)) => {
+      const api = requireServices();
+      const current = api.getSessionJson?.<T>(sessionId, key) ?? fallback;
+      const resolved = typeof value === 'function' ? (value as (prev: T) => T)(current) : value;
+      setLocal(resolved);
+      api.setSessionJson?.(sessionId, key, resolved);
+    },
+    [sessionId, key, fallback],
+  );
+
+  return [local, setValue, ready];
+}
+
+/** Read one text file inside the active workspace. */
+export function useWorkspaceFile(relativePath: string): WorkspaceFile {
+  const { workspacePath } = usePanelInfo();
+  const [content, setContent] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    requireServices()
+      .readWorkspaceFile(workspacePath, relativePath)
+      .then(
+        (text) => {
+          if (cancelled) return;
+          setContent(text);
+          setLoading(false);
+        },
+        (cause: unknown) => {
+          if (cancelled) return;
+          setError(cause instanceof Error ? cause.message : String(cause));
+          setLoading(false);
+        },
+      );
+    return () => {
+      cancelled = true;
+    };
+  }, [workspacePath, relativePath]);
+
+  return { content, loading, error };
+}

package/src/participant.test.tsx

@@ -0,0 +1,238 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The participant hooks: `useRpc`, `useRealtime`, `useComposer`.
+ *
+ * Each one is a behaviour a plugin would otherwise hand-roll, and each of those
+ * behaviours is a bug when it is missing:
+ *
+ * - `useRpc` must return a plugin's REFUSAL as a result rather than throwing.
+ *   The route answers `{ ok: false, error }` at HTTP 200, because the call
+ *   reached the plugin and the plugin said no — flattening that into a rejected
+ *   promise turns "the plugin refused this argument" into "the network broke".
+ * - `useRpc` must drop a superseded call's answer, or a slow first call repaints
+ *   the panel a faster second one already moved.
+ * - `useRealtime` must seed from the value on hand before subscribing: a
+ *   component that mounted between two pushes would otherwise render blank.
+ * - `useComposer` must WRITE through the host's state. A DOM write is reverted
+ *   by the next keystroke, so the plugin's edit vanishes with no error.
+ *
+ * Rendered with `h()` against happy-dom, driven by the harness's own fake kit —
+ * the same seam a plugin's tests use.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Window } from 'happy-dom';
+import { h, render } from 'preact';
+import { act } from 'preact/test-utils';
+import { configureUiKit, PluginIdProvider, useComposer, useRealtime, useRpc } from '@kabmo-labs/kabmo-ui';
+import { makeUiKitServices, type FakeUiKit } from '@kabmo-labs/kabmo-sdk/testing';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event'] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+let window_: Window | null = null;
+
+function installDom(): void {
+  window_ = new Window();
+  const target = globalThis as unknown as Record<string, unknown>;
+  const source = window_ as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = target[key];
+    target[key] = source[key];
+  }
+}
+
+function restoreDom(): void {
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    const value = nativeGlobals[key];
+    if (value === undefined) delete target[key];
+    else target[key] = value;
+  }
+  window_ = null;
+}
+
+let host: FakeUiKit;
+let container: HTMLDivElement;
+
+beforeEach(() => {
+  installDom();
+  host = makeUiKitServices();
+  configureUiKit(host);
+  container = document.createElement('div');
+  document.body.appendChild(container);
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+  restoreDom();
+});
+
+/**
+ * Render one hook INSIDE a plugin's scope, which is what a host surface does —
+ * the id the participant hooks address comes from that context, so a test that
+ * rendered outside it would only exercise the no-plugin path.
+ */
+function mount<T>(use: () => T, pluginId = 'demo'): { get: () => T } {
+  let latest: T;
+  function Probe() {
+    latest = use();
+    return null;
+  }
+  act(() => render(h(PluginIdProvider, { pluginId }, h(Probe, {})), container));
+  return { get: () => latest! };
+}
+
+describe('useRpc', () => {
+  test('a successful call answers the value and clears the error', async () => {
+    host.rpc.stub('list', [1, 2]);
+    const rpc = mount(() => useRpc<{ q: string }, number[]>('list'));
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await rpc.get().call({ q: 'today' });
+    });
+
+    expect(outcome).toEqual({ ok: true, value: [1, 2] });
+    expect(rpc.get().value).toEqual([1, 2]);
+    expect(rpc.get().error).toBeNull();
+    expect(rpc.get().pending).toBe(false);
+    expect(host.rpc.calls).toEqual([{ pluginId: 'demo', method: 'list', input: { q: 'today' } }]);
+  });
+
+  test('a plugin refusal is a RESULT, not a thrown error', async () => {
+    host.rpc.stubError('save', { code: 'invalid_input', message: 'note must be a string' });
+    const rpc = mount(() => useRpc('save'));
+
+    let outcome: unknown;
+    await act(async () => {
+      outcome = await rpc.get().call({ note: 42 });
+    });
+
+    // The call did not throw, and the plugin's own reason survived.
+    expect(outcome).toEqual({ ok: false, error: { code: 'invalid_input', message: 'note must be a string' } });
+    expect(rpc.get().error).toEqual({ code: 'invalid_input', message: 'note must be a string' });
+    expect(rpc.get().value).toBeNull();
+  });
+
+  test('an unstubbed method is unknown_method, exactly as the route answers', async () => {
+    const rpc = mount(() => useRpc('typo'));
+    let outcome: { ok: boolean } = { ok: true };
+    await act(async () => {
+      outcome = (await rpc.get().call(null)) as { ok: boolean };
+    });
+    expect(outcome.ok).toBe(false);
+    expect(rpc.get().error?.code).toBe('unknown_method');
+  });
+
+  test('a superseded call does not overwrite the newer one', async () => {
+    // The first call answers LATE; the second, immediately.
+    let releaseFirst: (() => void) | null = null;
+    const first = new Promise<void>((resolve) => {
+      releaseFirst = resolve;
+    });
+    let call = 0;
+    configureUiKit({
+      ...host,
+      callRpc: async () => {
+        call += 1;
+        if (call === 1) {
+          await first;
+          return { ok: true, value: 'stale' };
+        }
+        return { ok: true, value: 'fresh' };
+      },
+    });
+
+    const rpc = mount(() => useRpc('list'));
+    await act(async () => {
+      void rpc.get().call(null);
+      await rpc.get().call(null);
+    });
+    expect(rpc.get().value).toBe('fresh');
+
+    await act(async () => {
+      releaseFirst?.();
+      await first;
+    });
+    // The late answer for the superseded call was dropped.
+    expect(rpc.get().value).toBe('fresh');
+  });
+});
+
+describe('useRealtime', () => {
+  test('seeds from the value on hand, then follows pushes', () => {
+    host.publishTopic({ count: 1 });
+    const realtime = mount(() => useRealtime<{ count: number }>());
+
+    // Seeded without waiting for the next push.
+    expect(realtime.get().value).toEqual({ count: 1 });
+    expect(realtime.get().isLoading).toBe(false);
+
+    act(() => host.publishTopic({ count: 2 }));
+    expect(realtime.get().value).toEqual({ count: 2 });
+  });
+
+  test('reports stale rather than hiding it', () => {
+    const realtime = mount(() => useRealtime());
+    expect(realtime.get().stale).toBe(false);
+  });
+
+  test('a refresh re-announces the value on hand', () => {
+    host.publishTopic('a');
+    const realtime = mount(() => useRealtime<string>());
+    act(() => realtime.get().refresh());
+    expect(realtime.get().value).toBe('a');
+  });
+
+  test('a subscriber that arrives before any value renders loading, not blank data', () => {
+    const realtime = mount(() => useRealtime());
+    expect(realtime.get().value).toBeNull();
+    expect(realtime.get().isLoading).toBe(true);
+  });
+});
+
+describe('useComposer', () => {
+  test('reads the live draft and re-renders on a change', () => {
+    host.composerControl.setState({ text: 'hello', isEmpty: false });
+    const composer = mount(() => useComposer());
+    expect(composer.get().text).toBe('hello');
+    expect(composer.get().isEmpty).toBe(false);
+
+    act(() => host.composerControl.setState({ text: 'hello world', isEmpty: false }));
+    expect(composer.get().text).toBe('hello world');
+  });
+
+  test('set writes THROUGH the host, so the draft the user sees changes', () => {
+    const composer = mount(() => useComposer());
+    act(() => composer.get().set('from the plugin'));
+    expect(host.composerControl.sets).toEqual(['from the plugin']);
+    expect(host.composerControl.state.text).toBe('from the plugin');
+  });
+
+  test('insert appends and focus is delegated', () => {
+    host.composerControl.setState({ text: 'a', isEmpty: false });
+    const composer = mount(() => useComposer());
+    act(() => {
+      composer.get().insert('b');
+      composer.get().focus();
+    });
+    expect(host.composerControl.inserts).toEqual(['b']);
+    expect(host.composerControl.state.text).toBe('ab');
+    expect(host.composerControl.focusCount()).toBe(1);
+  });
+
+  test('reports the run state and the scope', () => {
+    host.composerControl.setState({
+      isSubmitting: true,
+      scope: { kind: 'session', sessionId: 's1' },
+    });
+    const composer = mount(() => useComposer());
+    expect(composer.get().isSubmitting).toBe(true);
+    expect(composer.get().scope).toEqual({ kind: 'session', sessionId: 's1' });
+  });
+});

package/src/participant.ts

@@ -0,0 +1,186 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The participant hooks: what lets a plugin ACT on the conversation.
+ *
+ * `usePanelInfo` and friends make a plugin a view — it draws into a slot and
+ * reads per-session state. These three make it a participant, and each reads
+ * the host's own machinery rather than a second copy of it:
+ *
+ * - `useRpc` calls the plugin's OWN server method, through the route the server
+ *   half already answers on.
+ * - `useRealtime` subscribes to the plugin's own `plugin:<id>` topic, on the
+ *   same hub every built-in panel reads.
+ * - `useComposer` reads and writes the composer's draft.
+ *
+ * Every one of them goes through `requireServices()`, so a plugin outside the
+ * app throws naming the real problem instead of failing obscurely, and the test
+ * harness answers them with fakes — a plugin's own tests never need a host.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'preact/hooks';
+import { requireServices, type ComposerState, type PluginRpcError, type PluginRpcOutcome } from './services';
+import { usePluginId } from './plugin-id';
+
+/**
+ * Call one of this plugin's server methods.
+ *
+ * The plugin id comes from the HOST, never from the caller: a plugin that built
+ * its own URL would call another plugin's method the day the two disagreed
+ * about the id, and the host is the one party that cannot be wrong about which
+ * plugin it is running.
+ *
+ * Three behaviours, each of which is a bug if missed:
+ *
+ * - **A plugin's refusal is a RESULT, not a thrown error.** The route answers
+ *   `{ ok: false, error }` at HTTP 200, because the call reached the plugin and
+ *   the plugin said no. Flattening that into a rejected promise would turn "the
+ *   plugin refused this argument" into "the network broke", which is the one
+ *   distinction the route exists to preserve.
+ * - **A superseded call is dropped.** Two calls in flight must not leave the
+ *   first one's value on screen, so each call carries a sequence number and a
+ *   late answer for an older one is discarded.
+ * - **`pending` is per-hook, not per-call.** A panel wants one spinner, not one
+ *   per in-flight request.
+ */
+export interface RpcState<In, Out> {
+  /** Invoke the method. Resolves with the outcome; never throws for a refusal. */
+  call: (input: In) => Promise<PluginRpcOutcome>;
+  /** The last successful value, kept while a newer call is in flight. */
+  value: Out | null;
+  /** The last refusal, or null. Cleared by a successful call. */
+  error: PluginRpcError | null;
+  /** A call is in flight. */
+  pending: boolean;
+}
+
+export function useRpc<In = unknown, Out = unknown>(method: string): RpcState<In, Out> {
+  const [value, setValue] = useState<Out | null>(null);
+  const [error, setError] = useState<PluginRpcError | null>(null);
+  const [pending, setPending] = useState(false);
+  // The plugin this component belongs to, from the host's context — which is
+  // what makes `method` the only thing a plugin names.
+  const pluginId = usePluginId();
+  // The newest call's sequence. An answer for anything older is dropped, so a
+  // slow first call cannot repaint the panel a faster second one already moved.
+  const sequence = useRef(0);
+
+  const call = useCallback(
+    async (input: In): Promise<PluginRpcOutcome> => {
+      const services = requireServices();
+      const mine = ++sequence.current;
+      setPending(true);
+      const outcome: PluginRpcOutcome =
+        services.callRpc && pluginId
+          ? await services.callRpc(pluginId, method, input)
+          : { ok: false, error: { code: 'no_plugin', message: 'This component is not inside a plugin.' } };
+      if (mine !== sequence.current) return outcome;
+      setPending(false);
+      if (outcome.ok) {
+        setValue(outcome.value as Out);
+        setError(null);
+      } else {
+        setError(outcome.error);
+      }
+      return outcome;
+    },
+    [method, pluginId],
+  );
+
+  return { call, value, error, pending };
+}
+
+/**
+ * The plugin's own realtime topic, as a value that re-renders on each push.
+ *
+ * `stale` is surfaced rather than hidden: it means the socket is down, and a
+ * panel showing a value of unknown age as if it were current is worse than one
+ * that says so.
+ */
+export interface PluginRealtimeState<T> {
+  value: T | null;
+  /** No value has arrived yet. */
+  isLoading: boolean;
+  /** The value on hand is not known to be current. */
+  stale: boolean;
+  /** Ask the server for a fresh snapshot. */
+  refresh: () => void;
+}
+
+export function useRealtime<T = unknown>(): PluginRealtimeState<T> {
+  const [value, setValue] = useState<T | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [stale, setStale] = useState(false);
+  const pluginId = usePluginId();
+
+  useEffect(() => {
+    const services = requireServices();
+    if (!pluginId || !services.subscribePluginTopic) return;
+    // Seed from the host's current value BEFORE subscribing: a component that
+    // mounted between two pushes would otherwise render empty until the next
+    // one, which for a slow-publishing plugin is a visible blank.
+    const seeded = services.readPluginTopic?.(pluginId);
+    if (seeded !== undefined) {
+      setValue(seeded as T);
+      setIsLoading(false);
+    }
+    setStale(services.pluginTopicStale?.(pluginId) ?? false);
+    const unsubscribe = services.subscribePluginTopic(pluginId, (next) => {
+      setValue(next as T);
+      setIsLoading(false);
+      setStale(services.pluginTopicStale?.(pluginId) ?? false);
+    });
+    return unsubscribe;
+  }, [pluginId]);
+
+  const refresh = useCallback(() => {
+    if (pluginId) requireServices().refreshPluginTopic?.(pluginId);
+  }, [pluginId]);
+
+  return { value, isLoading, stale, refresh };
+}
+
+/**
+ * The composer: its live state, and its writes.
+ *
+ * A write goes through the host's own composer state, NOT the DOM. The composer
+ * is a controlled textarea owned by the chat, so a DOM write is reverted by the
+ * next keystroke and the plugin's edit vanishes with no error — the failure
+ * this hook exists to prevent.
+ *
+ * The read is reactive and the write is immediate, which is what makes
+ * `insert('@')` a one-step operation rather than an await.
+ */
+export interface ComposerHandle extends ComposerState {
+  set(text: string): void;
+  insert(text: string): void;
+  focus(): void;
+}
+
+export function useComposer(): ComposerHandle {
+  const [state, setState] = useState<ComposerState>(() => {
+    const composer = requireServices().composer?.();
+    return composer ?? { text: '', isEmpty: true, isSubmitting: false, scope: { kind: 'new', sessionId: null } };
+  });
+
+  useEffect(() => {
+    const services = requireServices();
+    if (!services.subscribeComposer) return;
+    return services.subscribeComposer(setState);
+  }, []);
+
+  const set = useCallback((text: string) => {
+    requireServices().composer?.().set(text);
+  }, []);
+  const insert = useCallback((text: string) => {
+    requireServices().composer?.().insert(text);
+  }, []);
+  const focus = useCallback(() => {
+    requireServices().composer?.().focus();
+  }, []);
+
+  return { ...state, set, insert, focus };
+}