@ompchamber/ui 1.0.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ompchamber/ui",
+  "version": "1.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"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "preact": "^10.29.8",
+    "@ompchamber/plugin-sdk": "1.0.0"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rajebdev/ompchamber.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/rajebdev/ompchamber#readme",
+  "bugs": {
+    "url": "https://github.com/rajebdev/ompchamber/issues"
+  },
+  "keywords": [
+    "ompchamber",
+    "panel",
+    "plugin",
+    "preact",
+    "ui"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  }
+}

package/src/components.tsx

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+
+import type { ComponentChildren } from 'preact';
+
+interface PanelProps {
+  title: string;
+  children: ComponentChildren;
+}
+
+/** 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>
+  );
+}
+
+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>
+  );
+}
+
+/** A stack of `Field`s. */
+export function FieldList({ children }: { children: ComponentChildren }) {
+  return <div class="oc-fields">{children}</div>;
+}
+
+interface TextAreaFieldProps {
+  id?: string;
+  label: string;
+  placeholder?: string;
+  /** `null` while the stored value has not been read yet. */
+  value: string | null;
+  hint?: string;
+  onInput: (next: 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.
+ */
+export function TextAreaField({ id, label, placeholder, value, hint, onInput }: TextAreaFieldProps) {
+  return (
+    <div class="oc-textarea-field">
+      <label class="oc-label" for={id}>
+        {label}
+      </label>
+      <textarea
+        id={id}
+        class="oc-textarea"
+        placeholder={placeholder}
+        value={value ?? ''}
+        disabled={value === null}
+        onInput={(event) => onInput(event.currentTarget.value)}
+      />
+      {hint ? <span class="oc-hint">{hint}</span> : null}
+    </div>
+  );
+}
+
+interface ButtonProps {
+  children: ComponentChildren;
+  onClick: () => void;
+  disabled?: boolean;
+  variant?: 'default' | 'primary';
+}
+
+/** A button. `primary` is the one action a panel wants the user to take. */
+export function Button({ children, onClick, disabled, variant = 'default' }: ButtonProps) {
+  return (
+    <button type="button" class={`oc-button oc-button-${variant}`} disabled={disabled} onClick={onClick}>
+      {children}
+    </button>
+  );
+}
+
+/** Centred placeholder for a panel with nothing to show. */
+export function Empty({ children }: { children: ComponentChildren }) {
+  return <p class="oc-empty">{children}</p>;
+}
+
+/** 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>;
+}

package/src/index.tsx

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Preact integration for a panel plugin: one provider, four hooks.
+ *
+ * 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:
+ *
+ * - **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.
+ *
+ * Both are handled here so a plugin cannot get them wrong.
+ */
+
+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';
+
+interface PanelContextValue {
+  api: ChamberPanelApi;
+  info: PanelInfo;
+}
+
+const PanelContext = createContext<PanelContextValue | null>(null);
+
+function usePanelContext(): PanelContextValue {
+  const value = useContext(PanelContext);
+  if (!value) throw new Error('Panel hooks must be used inside <PanelProvider>');
+  return value;
+}
+
+/**
+ * The live panel info.
+ *
+ * Read through a hook rather than off the context directly so a component
+ * re-renders when the workspace arrives.
+ */
+export function usePanelInfo(): PanelInfo {
+  return usePanelContext().info;
+}
+
+/** The bridge itself, for `api.call(...)`. */
+export function usePanelApi(): ChamberPanelApi {
+  return usePanelContext().api;
+}
+
+/** 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 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.
+ */
+export function useSessionValue(key: string, delayMs = 400): SessionValue {
+  const api = usePanelApi();
+  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]);
+
+  useEffect(() => {
+    if (value === null || status !== 'saving') return;
+    const timer = setTimeout(async () => {
+      try {
+        await api.call('sessionState.set', { key, value });
+        setStatus('saved');
+      } catch (cause) {
+        setError(cause instanceof Error ? cause.message : String(cause));
+        setStatus('error');
+      }
+    }, delayMs);
+    return () => clearTimeout(timer);
+  }, [api, key, value, status, delayMs]);
+
+  return {
+    value,
+    status,
+    error,
+    update: (next: string) => {
+      setValue(next);
+      setStatus('saving');
+    },
+  };
+}
+
+/**
+ * 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);
+  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));
+      },
+    );
+
+    return () => {
+      cancelled = true;
+      api.onTheme = undefined;
+      api.onContext = undefined;
+    };
+  }, []);
+
+  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>;
+}

package/src/styles.css

@@ -0,0 +1,187 @@
+/**
+ * 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

@@ -0,0 +1,16 @@
+/**
+ * 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 {};