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

package/src/plugin-id.tsx

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The plugin-identity context: which plugin's UI a subtree belongs to, AND the
+ * DOM surface that plugin's stylesheet is confined to.
+ *
+ * It lives in the KIT, not in the host, because both ends must share one
+ * instance: the host imports `@kabmo-labs/kabmo-ui` directly while a plugin bundle
+ * gets the same module through `globalThis.__kabmoPluginRuntime.ui`, so a
+ * `Provider` the host renders is the `Provider` a plugin's hook reads.
+ *
+ * A Preact context rather than a module-level value, and that is a correctness
+ * point rather than a style choice: a component's children render AFTER its own
+ * function returns, so a value set and restored around `return <>{children}</>`
+ * is already gone by the time the children run. Measured — `setId('outer')` in
+ * a `try/finally` left the children reading `null`.
+ *
+ * The id is what makes `useRpc('save')` safe: the hook takes the plugin from
+ * here, so a component rendered for plugin A can never address plugin B's
+ * namespace, however the caller names its method.
+ *
+ * The ELEMENT is the other half, and it is why this component renders a node
+ * rather than only a context. A plugin's stylesheet is served wrapped in
+ * `@scope ([data-plugin-surface="<id>"])` (see the server's css route), so a
+ * rule the plugin writes reaches only elements inside a surface carrying its
+ * own id. Without this element a plugin's own CSS would match nothing at all,
+ * and the pattern it replaced — marking `<html>` — matched the HOST's chrome
+ * too, which is the leak this closes.
+ */
+
+import { createContext } from 'preact';
+import { useContext } from 'preact/hooks';
+import type { ComponentChildren } from 'preact';
+import { PLUGIN_SURFACE_ATTR } from '@kabmo-labs/kabmo-sdk';
+
+const PluginIdContext = createContext<string | null>(null);
+
+/**
+ * Wrap a plugin's own UI so its hooks resolve the right plugin and its CSS has
+ * a surface to land on.
+ *
+ * Every host surface that draws a plugin row wraps it — the right panel, the
+ * editor column, a chat row's actions, the composer's slots, a timeline
+ * renderer, a file view, the navbar. A surface that forgot would leave its
+ * plugin's `useRpc` answering `no_plugin` (the loud failure) AND its stylesheet
+ * inert (the silent one).
+ *
+ * `display: contents` is load-bearing: the wrapper must not become a flex item,
+ * a grid item or a block that changes the host's layout. It generates no box,
+ * so the plugin's own root behaves exactly as it did before this element
+ * existed, while the element itself is still a real DOM node for the CSS scope
+ * to root at.
+ *
+ * It is a `<span>` rather than a `<div>` for the same reason it carries
+ * `display: contents`: a host surface may render a plugin row inside a
+ * `<button>` (the navbar trigger), a `<label>` or a `<p>`, where only phrasing
+ * content is valid. Since the element generates no box, the tag name costs
+ * nothing.
+ */
+export function PluginIdProvider({ pluginId, children }: { pluginId: string; children?: ComponentChildren }) {
+  return (
+    <PluginIdContext.Provider value={pluginId}>
+      <span data-plugin-surface={pluginId} style="display: contents">
+        {children}
+      </span>
+    </PluginIdContext.Provider>
+  );
+}
+
+/** The plugin whose subtree this is, or null outside any plugin's UI. */
+export function usePluginId(): string | null {
+  return useContext(PluginIdContext);
+}
+
+/** The attribute a plugin's surface element carries — re-exported for the host. */
+export { PLUGIN_SURFACE_ATTR };

package/src/repo-picker.tsx

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The nested-repo picker, shared by the host's own panels and by plugins.
+ *
+ * It is in the KIT rather than in the host because both ends must draw the same
+ * control: a plugin panel's header and the Files panel's toolbar describe the
+ * same working tree, and a second implementation would drift on the things that
+ * matter — the label for the root itself, the checkmark, what refresh does.
+ *
+ * The kit has no icon dependency (its only dependencies are `preact` and the
+ * SDK), so every glyph here is an inline `<svg>` with `currentColor` paint. That
+ * is also why it carries its own outside-click handling: the host's
+ * `useOnClickOutside` is not reachable from a published package.
+ *
+ * The rows are the discovered repos of the CURRENT root, and `'.'` is always
+ * among them — the root is a legitimate choice even when it is not itself a
+ * repository, because a folder of nested repos is a normal workspace.
+ */
+
+import { useEffect, useMemo, useRef, useState } from 'preact/hooks';
+import type { RepoScopeHandle } from './repo';
+
+export interface RepoPickerProps {
+  /** The scope to draw and write. Pass `useRepoScope()`'s handle. */
+  scope: RepoScopeHandle;
+  /** Extra classes for the trigger, for a host that sizes its own toolbar. */
+  className?: string;
+  /** Hide the picker entirely (no workspace root to describe). */
+  disabled?: boolean;
+  /**
+   * A row under the list that opens a larger surface (the host's repo manager).
+   *
+   * Optional because it is HOST chrome: Kabmo opens a modal with grouping
+   * and per-repo state, which a plugin has no equivalent of. Absent, no row is
+   * drawn — the picker never promises an interaction it does not have, the same
+   * rule the navbar's header slots follow.
+   */
+  onManage?: () => void;
+  /** The manage row's label. Only read when `onManage` is given. */
+  manageLabel?: string;
+}
+
+/** One inline glyph. `currentColor` so it follows the theme with no CSS. */
+function Glyph({ path, size = 12, spin = false }: { path: string; size?: number; spin?: boolean }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      class={spin ? 'animate-spin' : undefined}
+      aria-hidden="true"
+    >
+      <path d={path} />
+    </svg>
+  );
+}
+
+const ICON = {
+  folder: 'M4 20h16a1 1 0 0 0 1-1V8a1 1 0 0 0-1-1h-7l-2-2H4a1 1 0 0 0-1 1v13a1 1 0 0 0 1 1z',
+  chevron: 'M6 9l6 6 6-6',
+  search: 'M11 19a8 8 0 1 0 0-16 8 8 0 0 0 0 16zM21 21l-4.35-4.35',
+  refresh: 'M3 12a9 9 0 0 1 15.5-6.2M21 12a9 9 0 0 1-15.5 6.2M3 4v5h5M21 20v-5h-5',
+  check: 'M20 6L9 17l-5-5',
+  manage: 'M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6zM19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 1 1-4 0v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 1 1 0-4h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 1 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 1 1 0 4h-.09a1.65 1.65 0 0 0-1.51 1z',
+} as const;
+
+export function RepoPicker({ scope, className, disabled = false, onManage, manageLabel = 'Manage repositories…' }: RepoPickerProps) {
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState('');
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Outside click closes. A published package cannot import the host's hook, and
+  // a pointerdown listener is what a browser actually delivers for a click
+  // outside a menu (a click listener misses a drag that ends elsewhere).
+  useEffect(() => {
+    if (!open) return;
+    const onDown = (event: globalThis.MouseEvent) => {
+      if (!ref.current?.contains(event.target as Node)) setOpen(false);
+    };
+    document.addEventListener('pointerdown', onDown);
+    return () => document.removeEventListener('pointerdown', onDown);
+  }, [open]);
+
+  // `'.'` always leads, so the root is the first row whatever order discovery
+  // returned. The rest keep discovery's order.
+  const options = useMemo(() => {
+    const rest = scope.rows.filter((row) => row.repo !== '.');
+    const root = scope.rows.find((row) => row.repo === '.');
+    return root ? [root, ...rest] : rest;
+  }, [scope.rows]);
+
+  const selected = options.find((row) => row.repo === scope.repo) ?? options[0];
+
+  const filtered = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    if (!needle) return options;
+    // The LABEL is what is searched, not the path: a user types what they can
+    // read, and for the root row the two differ ("Workspace" vs ".").
+    return options.filter((row) => row.label.toLowerCase().includes(needle));
+  }, [options, query]);
+
+  // No root: there is no tree to describe, so the control says so rather than
+  // offering a list that cannot be applied.
+  if (disabled || !scope.root) {
+    return (
+      <span class={`inline-flex items-center gap-1.5 px-2 py-1 text-xs text-ink/40 ${className ?? ''}`} title="No workspace folder">
+        <Glyph path={ICON.folder} />
+        no workspace
+      </span>
+    );
+  }
+
+  return (
+    <div class={`relative ${className ?? ''}`} ref={ref}>
+      <button
+        type="button"
+        onClick={() => setOpen((was) => !was)}
+        title="Switch git project"
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        class="flex items-center gap-1.5 px-2 py-1 rounded transition-colors text-xs text-ink/80 font-medium hover:bg-ink/5"
+      >
+        <Glyph path={ICON.folder} />
+        <span class="truncate max-w-[130px]">{selected?.short ?? 'workspace root'}</span>
+        <Glyph path={ICON.chevron} />
+      </button>
+
+      {open && (
+        <div
+          role="listbox"
+          class="absolute top-full left-0 mt-1 w-56 bg-paper border border-ink/20 rounded-md shadow-lg z-50 flex flex-col overflow-hidden text-xs"
+        >
+          <div class="px-2 py-1.5 border-b border-ink/10 flex items-center gap-1.5">
+            <Glyph path={ICON.search} size={11} />
+            <input
+              type="text"
+              value={query}
+              onInput={(event) => setQuery(event.currentTarget.value)}
+              placeholder="Search repos..."
+              title="Search repositories"
+              class="w-full bg-transparent outline-none text-xs text-ink placeholder-ink/40"
+              autoFocus
+            />
+            {query && (
+              <button type="button" onClick={() => setQuery('')} title="Clear search" class="text-ink/40 hover:text-ink">
+                ×
+              </button>
+            )}
+            <button
+              type="button"
+              onClick={() => scope.refresh()}
+              title="Refresh nested repos"
+              disabled={scope.scanning}
+              class="text-ink/40 hover:text-ink transition-colors disabled:opacity-40"
+            >
+              <Glyph path={ICON.refresh} size={11} spin={scope.scanning} />
+            </button>
+          </div>
+          <div class="max-h-48 overflow-y-auto scrollbar-overlay-container py-1">
+            {filtered.length === 0 ? (
+              <div class="px-3 py-2 text-ink/40 italic">No repos found</div>
+            ) : (
+              filtered.map((row) => (
+                <button
+                  key={row.repo}
+                  type="button"
+                  role="option"
+                  aria-selected={scope.repo === row.repo}
+                  onClick={() => {
+                    scope.setRepo(row.repo);
+                    setOpen(false);
+                    setQuery('');
+                  }}
+                  title={row.label}
+                  class="w-full text-left px-3 py-2 hover:bg-ink/5 flex items-center justify-between transition-colors"
+                >
+                  <span class="truncate">{row.label}</span>
+                  {scope.repo === row.repo && <Glyph path={ICON.check} />}
+                </button>
+              ))
+            )}
+          </div>
+          {onManage && (
+            <div class="border-t border-ink/10">
+              <button
+                type="button"
+                onClick={() => {
+                  onManage();
+                  setOpen(false);
+                  setQuery('');
+                }}
+                class="w-full text-left px-3 py-2 hover:bg-ink/5 flex items-center gap-2 transition-colors text-ink/80"
+              >
+                <Glyph path={ICON.manage} size={12} />
+                <span>{manageLabel}</span>
+              </button>
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/repo.test.tsx

@@ -0,0 +1,218 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * `useRepoScope` — the kit's view of the nested-repo scope the host's panels
+ * share.
+ *
+ * The behaviours pinned here are the ones a plugin gets wrong when it reads the
+ * session slot itself:
+ *
+ * - **The scope arrives late and changes from elsewhere.** The stored pick loads
+ *   with the session and the four host panels write the same slot, so a
+ *   component that captured the value once would show the previous repo forever.
+ *   The hook must re-read on a service push.
+ * - **A host that cannot answer is not an error.** An older host provides no
+ *   `repoScope`, and the hook reports an empty scope so a panel draws "no
+ *   workspace" instead of throwing.
+ * - **A write goes through the SERVICE**, never through a private copy — that is
+ *   the whole point of the shared slot, and a plugin that kept its own state
+ *   would leave the host's picker behind.
+ *
+ * Rendered with `h()` (no JSX) against happy-dom.
+ */
+
+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, useRepoScope, type RepoScope, type UiKitServices } from '@kabmo-labs/kabmo-ui';
+
+const DOM_GLOBALS = ['window', 'document', 'navigator', 'Node', 'Element', 'HTMLElement', 'Event'] as const;
+const nativeGlobals: Partial<Record<(typeof DOM_GLOBALS)[number], unknown>> = {};
+
+let container: HTMLElement;
+let scope: RepoScope;
+/** Every repo a test's component wrote, in order. */
+let writes: string[];
+/** Every rescan requested. */
+let rescans: number;
+/** The listeners the hook registered, so a test can push a change. */
+let listeners: Array<() => void>;
+
+const EMPTY: RepoScope = { root: null, repo: '.', rows: [], scanning: false, ready: false };
+
+/** The services a host would inject, with only the repo seam under test. */
+function services(): UiKitServices {
+  return {
+    context: () => ({ sessionId: 's1', workspacePath: '/ws', theme: 'paper' }),
+    subscribe: () => () => {},
+    getSessionValue: () => null,
+    setSessionValue: () => {},
+    readWorkspaceFile: async () => '',
+    repoScope: () => scope,
+    setRepoScope: (repo: string) => {
+      writes.push(repo);
+    },
+    subscribeRepoScope: (listener: () => void) => {
+      listeners.push(listener);
+      return () => {
+        listeners = listeners.filter((entry) => entry !== listener);
+      };
+    },
+    rescanRepoScope: () => {
+      rescans += 1;
+    },
+  };
+}
+
+beforeEach(() => {
+  const win = new Window({ url: 'http://localhost' });
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (!(key in nativeGlobals)) nativeGlobals[key] = target[key];
+    target[key] = (win as unknown as Record<string, unknown>)[key];
+  }
+  container = document.createElement('div') as unknown as HTMLElement;
+  document.body.appendChild(container as never);
+  scope = EMPTY;
+  writes = [];
+  rescans = 0;
+  listeners = [];
+  configureUiKit(services());
+});
+
+afterEach(() => {
+  render(null, container);
+  container.remove();
+  const target = globalThis as unknown as Record<string, unknown>;
+  for (const key of DOM_GLOBALS) {
+    if (key in nativeGlobals) target[key] = nativeGlobals[key];
+    else delete target[key];
+  }
+});
+
+/** Render the hook and expose its value plus its two actions. */
+function Probe() {
+  const handle = useRepoScope();
+  const text = [
+    handle.root ?? 'null',
+    handle.repo,
+    handle.rows.map((row) => `${row.repo}=${row.label}/${row.short}`).join(','),
+    handle.scanning ? 'scanning' : 'idle',
+  ].join('|');
+  return h(
+    'div',
+    { id: 'probe' },
+    h('span', { id: 'value' }, text),
+    h('button', { id: 'pick', onClick: () => handle.setRepo('projects/a/token') }, 'pick'),
+    h('button', { id: 'refresh', onClick: () => handle.refresh() }, 'refresh'),
+  );
+}
+
+const read = () => (container.querySelector('#value') as HTMLElement | null)?.textContent ?? '';
+
+async function settle(): Promise<void> {
+  for (let i = 0; i < 8; i += 1) await act(async () => {});
+}
+
+describe('useRepoScope', () => {
+  test('reports an empty scope against a host with no repo service', async () => {
+    const base = services();
+    delete base.repoScope;
+    delete base.subscribeRepoScope;
+    configureUiKit(base);
+
+    await act(async () => render(h(Probe, {}), container));
+    await settle();
+
+    // "no workspace", never a throw: a plugin panel must still render.
+    expect(read()).toBe('null|.||idle');
+  });
+
+  test('renders the host scope, rows and labels included', async () => {
+    scope = {
+      root: '/ws/Workspace',
+      repo: '.',
+      rows: [
+        { repo: '.', label: 'Workspace', short: 'Workspace' },
+        { repo: 'projects/a/token', label: 'projects/a/token', short: 'token' },
+      ],
+      scanning: false,
+      ready: true,
+    };
+
+    await act(async () => render(h(Probe, {}), container));
+    await settle();
+
+    // The labels travel WITH the rows — the naming rule is the host's, and the
+    // kit must not re-derive it.
+    expect(read()).toBe('/ws/Workspace|.|.=Workspace/Workspace,projects/a/token=projects/a/token/token|idle');
+  });
+
+  test('a scope change pushed by the host re-renders the panel', async () => {
+    scope = { root: '/ws', repo: '.', rows: [{ repo: '.', label: 'ws', short: 'ws' }], scanning: false, ready: true };
+    await act(async () => render(h(Probe, {}), container));
+    await settle();
+    expect(read()).toStartWith('/ws|.');
+
+    // The host's own picker moved the shared slot.
+    scope = {
+      root: '/ws',
+      repo: 'projects/b',
+      rows: [
+        { repo: '.', label: 'ws', short: 'ws' },
+        { repo: 'projects/b', label: 'projects/b', short: 'b' },
+      ],
+      scanning: false,
+      ready: true,
+    };
+    await act(async () => {
+      for (const listener of listeners) listener();
+    });
+    await settle();
+
+    expect(read()).toContain('|projects/b|');
+  });
+
+  test('a write goes through the service, not a private copy', async () => {
+    scope = { root: '/ws', repo: '.', rows: [{ repo: '.', label: 'ws', short: 'ws' }], scanning: false, ready: true };
+    await act(async () => render(h(Probe, {}), container));
+    await settle();
+
+    await act(async () => {
+      (container.querySelector('#pick') as HTMLButtonElement).click();
+    });
+    await settle();
+
+    expect(writes).toEqual(['projects/a/token']);
+  });
+
+  test('refresh asks the service to rescan', async () => {
+    scope = { root: '/ws', repo: '.', rows: [], scanning: false, ready: true };
+    await act(async () => render(h(Probe, {}), container));
+    await settle();
+
+    await act(async () => {
+      (container.querySelector('#refresh') as HTMLButtonElement).click();
+    });
+    await settle();
+
+    expect(rescans).toBe(1);
+  });
+
+  test('unsubscribes on unmount', async () => {
+    scope = { root: '/ws', repo: '.', rows: [], scanning: false, ready: true };
+    await act(async () => render(h(Probe, {}), container));
+    await settle();
+    expect(listeners).toHaveLength(1);
+
+    render(null, container);
+    await settle();
+
+    // A leaked listener would re-render a torn-down panel on every host write.
+    expect(listeners).toHaveLength(0);
+  });
+});

package/src/repo.ts

@@ -0,0 +1,72 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The repo scope, as a plugin reads and writes it.
+ *
+ * A nested repository is a path RELATIVE to the active workspace root
+ * (`projects/api` names a directory under the root), so the choice and the
+ * discovered list are both meaningless without the root they belong to. The host
+ * keeps the pairing; this module is the plugin's view of it.
+ *
+ * Two properties the hooks exist to enforce:
+ *
+ * - **The value arrives late and changes from elsewhere.** The stored pick loads
+ *   with the session, and the four host panels write the same slot. A component
+ *   that captured the scope once would show the previous repo forever, so the
+ *   hook subscribes and re-renders.
+ * - **A pick made under another root is not this root's pick.** The service
+ *   resolves that (it is the host that holds both halves), so a plugin never has
+ *   to compare roots itself.
+ *
+ * Against a host too old to provide the service, the hook reports an empty scope
+ * rather than throwing: a plugin that renders a picker against a host without
+ * one should draw "no workspace", not break the panel.
+ */
+
+import { useCallback, useEffect, useState } from 'preact/hooks';
+import { requireServices, type RepoScope } from './services';
+
+/** The scope with nothing known yet, for a host that cannot answer. */
+const NO_SCOPE: RepoScope = { root: null, repo: '.', rows: [], scanning: false, ready: false };
+
+export interface RepoScopeHandle extends RepoScope {
+  /** Set the shared pick. */
+  setRepo(repo: string): void;
+  /** Force a fresh nested-repo walk for the current root. */
+  refresh(): void;
+}
+
+/**
+ * The nested-repo scope the workspace panels share.
+ *
+ * Takes NO root argument: the service resolves the root from the plugin context
+ * the host already publishes, which is the same value a panel body carries. That
+ * is deliberate — one resolution serves both a panel (which has a component to
+ * call a hook from) and a content script (which does not), so the two cannot
+ * disagree about which tree they are describing.
+ */
+export function useRepoScope(): RepoScopeHandle {
+  const [scope, setScope] = useState<RepoScope>(() => requireServices().repoScope?.() ?? NO_SCOPE);
+
+  useEffect(() => {
+    const api = requireServices();
+    const read = () => setScope(api.repoScope?.() ?? NO_SCOPE);
+    // Re-read once on mount: the first render may have run before the session's
+    // stored state loaded, and the subscription only fires on a CHANGE.
+    read();
+    return api.subscribeRepoScope?.(read);
+  }, []);
+
+  const setRepo = useCallback((repo: string) => {
+    requireServices().setRepoScope?.(repo);
+  }, []);
+
+  const refresh = useCallback(() => {
+    requireServices().rescanRepoScope?.();
+  }, []);
+
+  return { ...scope, setRepo, refresh };
+}