@ompchamber/ui 1.0.0 → 2.0.0

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@ompchamber/ui",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Preact hooks and components for OMPChamber panel plugins.",
   "exports": {
     ".": "./src/index.tsx",
-    "./components": "./src/components.tsx",
-    "./styles.css": "./src/styles.css"
+    "./components": "./src/components.tsx"
   },
   "files": [
     "src"

package/src/components.tsx

@@ -6,17 +6,19 @@
 /**
  * The panel UI kit.
  *
- * Components a panel draws with, styled by the CSS variables the host's palette
- * drives. They exist so panels look like the chamber and like each other without
- * each one re-deriving the same markup — a second copy of a labelled field is
- * the first place two panels drift apart.
+ * These are ordinary host components, not a sandboxed mini-app's widgets: a
+ * plugin renders inside the chamber's own tree, so the kit uses the chamber's
+ * theme variables and Tailwind utilities directly and looks native in every
+ * palette with no CSS bridge.
  *
- * Class names are prefixed `oc-` and the stylesheet ships from the same package
- * (`@ompchamber/ui/styles.css`), so a plugin imports one thing and gets both.
- * Colours come from `var(--oc-*)`, which the host does NOT set: the frame has an
- * opaque origin, so the palette arrives as `data-theme` on `<html>` and the
- * stylesheet maps it. That is why this package carries CSS rather than reading
- * the app's.
+ * The kit exists so a plugin does not re-invent the same six shapes — a titled
+ * panel, a label/value row, a text field, a button, an empty state, a note —
+ * and so those shapes stay consistent across plugins the way they are within
+ * the chamber itself.
+ *
+ * Every component takes its colours from the theme variables (`bg-paper`,
+ * `text-ink`, `border-ink/10`), never a literal, which is what keeps a plugin
+ * legible in the light and dark palettes without knowing they exist.
  */
 
 import type { ComponentChildren } from 'preact';
@@ -29,11 +31,11 @@ interface PanelProps {
 /** A panel's outer chrome: a title bar over a scrolling body. */
 export function Panel({ title, children }: PanelProps) {
   return (
-    <div class="oc-panel">
-      <header class="oc-panel-header">
-        <h1 class="oc-panel-title">{title}</h1>
-      </header>
-      <div class="oc-panel-body">{children}</div>
+    <div class="flex flex-col h-full w-full bg-paper text-ink">
+      <div class="flex-shrink-0 border-b border-ink/10 px-3 py-2">
+        <span class="text-xs font-semibold text-ink">{title}</span>
+      </div>
+      <div class="flex-1 min-h-0 overflow-auto p-3">{children}</div>
     </div>
   );
 }
@@ -41,60 +43,55 @@ export function Panel({ title, children }: PanelProps) {
 interface FieldProps {
   label: string;
   value: string;
-  /** Shown under the value, for a path or an id that would otherwise wrap badly. */
   hint?: string;
 }
 
 /** One labelled fact. The label is a micro-header, the value is machine text. */
 export function Field({ label, value, hint }: FieldProps) {
   return (
-    <div class="oc-field">
-      <span class="oc-label">{label}</span>
-      <span class="oc-value" title={value}>
-        {value}
-      </span>
-      {hint ? <span class="oc-hint">{hint}</span> : null}
+    <div class="flex flex-col gap-0.5">
+      <span class="text-[10px] uppercase font-mono text-ink/40">{label}</span>
+      <span class="text-xs font-mono text-ink break-all">{value}</span>
+      {hint ? <span class="text-[11px] text-ink/50">{hint}</span> : null}
     </div>
   );
 }
 
 /** A stack of `Field`s. */
 export function FieldList({ children }: { children: ComponentChildren }) {
-  return <div class="oc-fields">{children}</div>;
+  return <div class="flex flex-col gap-3">{children}</div>;
 }
 
 interface TextAreaFieldProps {
-  id?: string;
+  id: string;
   label: string;
+  value: string;
   placeholder?: string;
-  /** `null` while the stored value has not been read yet. */
-  value: string | null;
   hint?: string;
-  onInput: (next: string) => void;
+  onInput: (value: string) => void;
 }
 
 /**
  * A labelled textarea.
  *
- * Disabled while `value` is null — that is "the read has not answered yet", and
- * an editable box there would let the user type into a field whose contents are
- * about to be replaced by the stored value.
+ * Controlled through `onInput` rather than owning its own state, so the caller
+ * decides what a keystroke means — the session-persisting hook debounces the
+ * write, while a purely local field can keep the value in the caller.
  */
-export function TextAreaField({ id, label, placeholder, value, hint, onInput }: TextAreaFieldProps) {
+export function TextAreaField({ id, label, value, placeholder, hint, onInput }: TextAreaFieldProps) {
   return (
-    <div class="oc-textarea-field">
-      <label class="oc-label" for={id}>
+    <div class="flex flex-col gap-1">
+      <label for={id} class="text-[10px] uppercase font-mono text-ink/40">
         {label}
       </label>
       <textarea
         id={id}
-        class="oc-textarea"
+        value={value}
         placeholder={placeholder}
-        value={value ?? ''}
-        disabled={value === null}
-        onInput={(event) => onInput(event.currentTarget.value)}
+        onInput={(event) => onInput((event.currentTarget as HTMLTextAreaElement).value)}
+        class="w-full min-h-20 resize-y bg-canvas border border-ink/15 rounded px-2.5 py-1.5 text-xs font-mono text-ink placeholder-ink/35 focus:outline-none focus:border-ink/40"
       />
-      {hint ? <span class="oc-hint">{hint}</span> : null}
+      {hint ? <span class="text-[11px] text-ink/50">{hint}</span> : null}
     </div>
   );
 }
@@ -103,13 +100,23 @@ interface ButtonProps {
   children: ComponentChildren;
   onClick: () => void;
   disabled?: boolean;
+  /** The one action a panel wants the user to take. */
   variant?: 'default' | 'primary';
 }
 
-/** A button. `primary` is the one action a panel wants the user to take. */
+/** A button. */
 export function Button({ children, onClick, disabled, variant = 'default' }: ButtonProps) {
+  const tone =
+    variant === 'primary'
+      ? 'bg-ink text-canvas border-ink hover:opacity-90'
+      : 'border-ink/15 hover:bg-ink/5 text-ink';
   return (
-    <button type="button" class={`oc-button oc-button-${variant}`} disabled={disabled} onClick={onClick}>
+    <button
+      type="button"
+      onClick={onClick}
+      disabled={disabled}
+      class={`inline-flex items-center gap-1.5 px-2.5 py-1.5 text-xs rounded border transition-colors disabled:opacity-40 disabled:cursor-default ${tone}`}
+    >
       {children}
     </button>
   );
@@ -117,10 +124,15 @@ export function Button({ children, onClick, disabled, variant = 'default' }: But
 
 /** Centred placeholder for a panel with nothing to show. */
 export function Empty({ children }: { children: ComponentChildren }) {
-  return <p class="oc-empty">{children}</p>;
+  return (
+    <div class="h-full flex items-center justify-center px-6 text-center">
+      <p class="text-xs text-ink/45 font-mono">{children}</p>
+    </div>
+  );
 }
 
 /** A message. `error` is the only chroma a panel should use. */
 export function Note({ children, tone = 'default' }: { children: ComponentChildren; tone?: 'default' | 'error' }) {
-  return <p class={`oc-note oc-note-${tone}`}>{children}</p>;
+  const colour = tone === 'error' ? 'text-error' : 'text-ink/60';
+  return <p class={`text-[11px] ${colour}`}>{children}</p>;
 }

package/src/index.tsx

@@ -4,54 +4,85 @@
  */
 
 /**
- * The Preact integration for a panel plugin: one provider, four hooks.
+ * The UI kit a plugin renders with, and the host services it reads through.
  *
- * A plugin used to hand-roll this — a context, a `ready` await, a theme handler,
- * a debounced session write — which meant every plugin re-derived the same two
- * behaviours that are easy to get wrong:
+ * Everything here runs IN THE HOST'S TREE — same Preact instance, same
+ * document, same theme — so the kit is plain Preact components, not a
+ * message-passing client. What it still must not do is reach into the host's
+ * own source: this is a published package, so the host INJECTS its services
+ * once at boot via `configureUiKit`, and the hooks read them.
  *
- * - **The provider owns BOTH bridge subscriptions.** Registering `onTheme` from
- *   a component only fires if that component mounts; a panel whose components
- *   never called `useTheme()` silently stopped following the palette.
- * - **The context arrives late.** `workspacePath` and `sessionId` are resolved
- *   asynchronously by the chamber, so they are usually empty when `ready`
- *   settles. A component that captured `info` once would show "none" over a real
- *   workspace.
+ * Two rules the hooks exist to enforce, because a plugin gets them wrong:
  *
- * Both are handled here so a plugin cannot get them wrong.
+ * - **Context arrives late.** The active session and workspace are resolved
+ *   asynchronously, so a component that captured them once would show "none"
+ *   over a real workspace. Every hook subscribes and re-renders.
+ * - **Session state is not component state.** The component is unmounted when
+ *   its panel is hidden, so a value kept in `useState` alone would be lost on
+ *   every tab switch. `useSessionValue` reads the chamber's store.
  */
 
-import { createContext } from 'preact';
-import { useContext, useEffect, useState } from 'preact/hooks';
-import type { ComponentChildren } from 'preact';
-import { acquirePanel, type ChamberPanelApi, type PanelInfo } from '@ompchamber/plugin-sdk';
+import { useCallback, useEffect, useState } from 'preact/hooks';
 
-interface PanelContextValue {
-  api: ChamberPanelApi;
-  info: PanelInfo;
+/** What the host seeds every plugin component with. */
+export interface PanelContext {
+  sessionId: string | null;
+  workspacePath: string | null;
+  theme: string;
 }
 
-const PanelContext = createContext<PanelContextValue | null>(null);
+/**
+ * The host's own services, injected once.
+ *
+ * Deliberately narrow: each field is something a plugin genuinely cannot do
+ * itself (read the chamber's per-session store, know the live palette, resolve
+ * the active workspace). Anything a plugin could read from the DOM it should.
+ */
+export interface UiKitServices {
+  /** The current panel context. */
+  context(): PanelContext;
+  /** Subscribe to context changes (a new session, a palette switch). */
+  subscribe(listener: (context: PanelContext) => void): () => void;
+  /** Read one per-session value. */
+  getSessionValue(sessionId: string | null, key: string): string | null;
+  /** Write one per-session value. */
+  setSessionValue(sessionId: string | null, key: string, value: string): void;
+  /** Read a text file inside the active workspace. Rejects with the reason. */
+  readWorkspaceFile(workspacePath: string | null, relativePath: string): Promise<string>;
+}
+
+let services: UiKitServices | null = null;
 
-function usePanelContext(): PanelContextValue {
-  const value = useContext(PanelContext);
-  if (!value) throw new Error('Panel hooks must be used inside <PanelProvider>');
-  return value;
+/** Called ONCE by the host at boot. A plugin must never call this. */
+export function configureUiKit(next: UiKitServices): void {
+  services = next;
+}
+
+function requireServices(): UiKitServices {
+  if (!services) {
+    throw new Error(
+      'The OMPChamber UI kit has no host services — this component must be rendered by the OMPChamber app.',
+    );
+  }
+  return services;
 }
 
 /**
- * The live panel info.
+ * The live panel context, re-rendering on every change.
  *
- * Read through a hook rather than off the context directly so a component
- * re-renders when the workspace arrives.
+ * `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(): PanelInfo {
-  return usePanelContext().info;
-}
+export function usePanelInfo(): PanelContext {
+  const [context, setContext] = useState<PanelContext>(() => requireServices().context());
+
+  useEffect(() => {
+    const api = requireServices();
+    setContext(api.context());
+    return api.subscribe(setContext);
+  }, []);
 
-/** The bridge itself, for `api.call(...)`. */
-export function usePanelApi(): ChamberPanelApi {
-  return usePanelContext().api;
+  return context;
 }
 
 /** The live palette id. */
@@ -70,42 +101,31 @@ export interface SessionValue {
 /**
  * Per-session state, as a `useState` that persists.
  *
- * The value lives in the session store, not in the frame: the frame is destroyed
- * whenever the panel is hidden, so local state would be lost on every tab
- * switch. Reads once on mount, writes debounced — `input` fires per keystroke,
- * and each one would otherwise be a postMessage round trip.
+ * 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 api = usePanelApi();
+  const { sessionId } = usePanelInfo();
   const [value, setValue] = useState<string | null>(null);
   const [status, setStatus] = useState<SessionValue['status']>('loading');
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
-    let cancelled = false;
     setStatus('loading');
-    api.call<string | null>('sessionState.get', { key }).then(
-      (stored) => {
-        if (cancelled) return;
-        setValue(stored ?? '');
-        setStatus('idle');
-      },
-      (cause: unknown) => {
-        if (cancelled) return;
-        setError(cause instanceof Error ? cause.message : String(cause));
-        setStatus('error');
-      },
-    );
-    return () => {
-      cancelled = true;
-    };
-  }, [api, key]);
+    try {
+      setValue(requireServices().getSessionValue(sessionId, key) ?? '');
+      setStatus('idle');
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+      setStatus('error');
+    }
+  }, [sessionId, key]);
 
   useEffect(() => {
     if (value === null || status !== 'saving') return;
-    const timer = setTimeout(async () => {
+    const timer = setTimeout(() => {
       try {
-        await api.call('sessionState.set', { key, value });
+        requireServices().setSessionValue(sessionId, key, value);
         setStatus('saved');
       } catch (cause) {
         setError(cause instanceof Error ? cause.message : String(cause));
@@ -113,69 +133,51 @@ export function useSessionValue(key: string, delayMs = 400): SessionValue {
       }
     }, delayMs);
     return () => clearTimeout(timer);
-  }, [api, key, value, status, delayMs]);
-
-  return {
-    value,
-    status,
-    error,
-    update: (next: string) => {
-      setValue(next);
-      setStatus('saving');
-    },
-  };
+  }, [sessionId, key, value, status, delayMs]);
+
+  const update = useCallback((next: string) => {
+    setValue(next);
+    setStatus('saving');
+  }, []);
+
+  return { value, status, error, update };
 }
 
-/**
- * Mount a panel, rendering `children` once the host has answered.
- *
- * Renders nothing until `ready` resolves: the panel has no data to draw before
- * then, and a half-drawn first frame is worse than none.
- */
-export function PanelProvider({ children }: { children: ComponentChildren }) {
-  const [value, setValue] = useState<PanelContextValue | null>(null);
+export interface WorkspaceFile {
+  content: string | null;
+  loading: boolean;
+  error: string | null;
+}
+
+/** 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;
-    let api: ChamberPanelApi;
-    try {
-      api = acquirePanel();
-    } catch (cause) {
-      setError(cause instanceof Error ? cause.message : String(cause));
-      return;
-    }
-
-    /** Apply a palette id to the document, which is what `:root[data-theme]` keys off. */
-    const applyTheme = (theme: string) => document.documentElement.setAttribute('data-theme', theme);
-
-    api.ready.then(
-      (info) => {
-        if (cancelled) return;
-        applyTheme(info.theme);
-        api.onTheme = (theme) => {
-          applyTheme(theme);
-          setValue((current) => (current ? { ...current, info: { ...current.info, theme } } : current));
-        };
-        api.onContext = (next) => {
-          if (next.theme) applyTheme(next.theme);
-          setValue((current) => (current ? { ...current, info: { ...current.info, ...next } } : current));
-        };
-        setValue({ api, info });
-      },
-      (cause: unknown) => {
-        if (!cancelled) setError(cause instanceof Error ? cause.message : String(cause));
-      },
-    );
-
+    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;
-      api.onTheme = undefined;
-      api.onContext = undefined;
     };
-  }, []);
+  }, [workspacePath, relativePath]);
 
-  if (error) return <p class="oc-note oc-note-error">Could not attach to the chamber: {error}</p>;
-  if (!value) return null;
-  return <PanelContext.Provider value={value}>{children}</PanelContext.Provider>;
+  return { content, loading, error };
 }

package/src/styles.css

@@ -1,187 +0,0 @@
-/**
- * The UI kit's stylesheet.
- *
- * The frame has an opaque origin, so it cannot reach the chamber's stylesheet —
- * the palette arrives as `data-theme` on `<html>` (set by `PanelProvider`) and
- * this file maps it. That is the whole reason a kit ships CSS: without it, every
- * panel would invent its own colours and drift from the app.
- *
- * The palette ids are the two the chamber ships most often. A plugin may add a
- * block for a theme it wants to support; an unknown id leaves the defaults,
- * which is a readable fallback rather than a broken one.
- */
-
-:root {
-  --oc-bg: #faf8f3;
-  --oc-paper: #ffffff;
-  --oc-ink: #141310;
-  --oc-muted: rgba(20, 19, 16, 0.55);
-  --oc-faint: rgba(20, 19, 16, 0.38);
-  --oc-line: rgba(20, 19, 16, 0.14);
-  --oc-error: #b3261e;
-}
-
-:root[data-theme='one-dark-pro-soft'] {
-  --oc-bg: #21252b;
-  --oc-paper: #282c34;
-  --oc-ink: #d7dae0;
-  --oc-muted: rgba(215, 218, 224, 0.6);
-  --oc-faint: rgba(215, 218, 224, 0.42);
-  --oc-line: rgba(215, 218, 224, 0.16);
-  --oc-error: #e06c75;
-}
-
-html,
-body {
-  margin: 0;
-  height: 100%;
-}
-
-body {
-  background: var(--oc-bg);
-  color: var(--oc-ink);
-  font-family: system-ui, -apple-system, sans-serif;
-  font-size: 13px;
-}
-
-/* Panel chrome ------------------------------------------------------------ */
-
-.oc-panel {
-  display: flex;
-  flex-direction: column;
-  height: 100%;
-}
-
-.oc-panel-header {
-  padding: 12px 14px;
-  border-bottom: 1px solid var(--oc-line);
-  flex-shrink: 0;
-}
-
-.oc-panel-title {
-  margin: 0;
-  font-size: 13px;
-  font-weight: 600;
-}
-
-.oc-panel-body {
-  flex: 1;
-  min-height: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  padding: 12px 14px 14px;
-  overflow: auto;
-}
-
-/* Fields ------------------------------------------------------------------ */
-
-.oc-fields {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-}
-
-.oc-field {
-  display: flex;
-  flex-direction: column;
-  gap: 2px;
-}
-
-.oc-label {
-  font-size: 10px;
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
-  color: var(--oc-muted);
-  font-family: ui-monospace, monospace;
-}
-
-.oc-value {
-  font-family: ui-monospace, monospace;
-  font-size: 12px;
-  word-break: break-all;
-}
-
-.oc-hint {
-  font-size: 11px;
-  color: var(--oc-muted);
-}
-
-/* Text field -------------------------------------------------------------- */
-
-.oc-textarea-field {
-  flex: 1;
-  min-height: 0;
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-}
-
-.oc-textarea {
-  flex: 1;
-  min-height: 80px;
-  resize: none;
-  border: 1px solid var(--oc-line);
-  border-radius: 6px;
-  padding: 8px;
-  font: 12px/1.6 ui-monospace, monospace;
-  background: transparent;
-  color: inherit;
-  outline: none;
-}
-
-.oc-textarea:focus {
-  border-color: var(--oc-ink);
-}
-
-.oc-textarea:disabled {
-  opacity: 0.5;
-}
-
-/* Button ------------------------------------------------------------------ */
-
-.oc-button {
-  font: inherit;
-  font-size: 12px;
-  padding: 5px 10px;
-  border-radius: 6px;
-  border: 1px solid var(--oc-line);
-  background: transparent;
-  color: inherit;
-  cursor: pointer;
-}
-
-.oc-button:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--oc-ink) 6%, transparent);
-}
-
-.oc-button:disabled {
-  opacity: 0.45;
-  cursor: default;
-}
-
-.oc-button-primary {
-  background: var(--oc-ink);
-  color: var(--oc-bg);
-  border-color: var(--oc-ink);
-}
-
-/* Messages ---------------------------------------------------------------- */
-
-.oc-empty {
-  margin: 0;
-  padding: 24px 8px;
-  text-align: center;
-  font-size: 12px;
-  color: var(--oc-faint);
-}
-
-.oc-note {
-  margin: 0;
-  font-size: 11px;
-  color: var(--oc-muted);
-}
-
-.oc-note-error {
-  color: var(--oc-error);
-}

package/src/styles.d.css.ts

@@ -1,16 +0,0 @@
-/**
- * Type declaration for `@ompchamber/ui/styles.css`.
- *
- * TypeScript will not accept a side-effect import of a `.css` file without a
- * declaration beside it, and the error (`TS2882: Cannot find module or type
- * declarations for side-effect import`) is the first thing a plugin author would
- * hit. This is the shape TypeScript looks for — `styles.css` resolves to
- * `styles.d.css.ts` — and it requires `allowArbitraryExtensions: true` in the
- * consumer's tsconfig, which the plugin tsconfig in the docs sets.
- *
- * It is exported rather than ambient so the file is a module, which is what
- * `allowArbitraryExtensions` expects; the stylesheet itself is the payload, and
- * nothing is imported from here at runtime.
- */
-
-export {};