@volter/world-ui 0.1.37 → 1.0.0

package/client/kit.tsx

@@ -1,312 +0,0 @@
-// THE TWIN UI KIT — shared pieces for a derived pack's screens (docs/contributing/architecture.md,
-// "Screens"): the shell and navigation, lists and details, references, state pills, the moves a machine
-// allows from a row's state, and create forms, all through the vendor's own API. A pack builds the
-// screens people work in from these under its skin. It is not a vendor's UI on its own: TwinUi's
-// generic resource browser renders any declared resource and so answers what a World holds, which a
-// vendor's screens never pose as.
-import React, { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
-import { createRoot } from 'react-dom/client';
-
-export type Row = Record<string, any>;
-
-export type UiAction = { operation: string; method: string; path: string; field: string; from: string[] | '*'; to?: string };
-export type UiResource = {
-  list?: string;
-  retrieve?: string;
-  create?: { path: string; encoding: string; body: Array<{ name: string; type: string; required: boolean }> };
-  actions: UiAction[];
-  states: Record<string, string[]>;
-  embeds: Record<string, string>;
-};
-export type UiData = { resources: Record<string, UiResource> };
-
-/** One entry of the navigation: a resource's list, titled the vendor's way. */
-export type Section = {
-  resource: string;
-  label: string;
-  /** where it is listed, when not the resource's own list (a sub-collection) */
-  list?: string;
-  title?: (row: Row) => string;
-  subtitle?: (row: Row) => string;
-  /** what the vendor's detail page shows beyond the fields (a balance panel, an error banner) */
-  extras?: (row: Row) => ReactNode;
-};
-
-/** A screen of the vendor's UI that is not a resource view (a chat, a board, a canvas). */
-export type Screen = { key: string; label: string; render: (api: Api) => ReactNode };
-
-export type TwinUiConfig = {
-  skin: { name: string; product?: string };
-  ui: UiData;
-  sections: Section[];
-  screens?: Screen[];
-  /** headers every call carries (the fake credential the vendor's API asks for) */
-  headers?: Record<string, string>;
-  /** how the vendor's lists hold their rows: `data` (Stripe, OpenAI), the whole body (GitHub), or a key */
-  rowsAt?: (body: any, resource: string) => Row[];
-  /** a value's tone for its status pill */
-  tone?: (value: string) => 'ok' | 'warn' | 'bad' | 'muted';
-};
-
-// ── talking to the vendor's API ────────────────────────────────────────────────────────────
-
-const BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
-
-export type Api = {
-  get: (path: string) => Promise<any>;
-  send: (method: string, path: string, body?: Record<string, unknown>, encoding?: string) => Promise<{ status: number; body: any }>;
-};
-
-function formEncode(value: unknown, prefix: string, out: URLSearchParams): void {
-  if (value === undefined || value === '') return;
-  if (value && typeof value === 'object') {
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) formEncode(v, prefix ? `${prefix}[${k}]` : k, out);
-  } else out.append(prefix, String(value));
-}
-
-export function makeApi(headers: Record<string, string> = {}): Api {
-  return {
-    get: (path) => fetch(`${BASE}${path}`, { headers }).then((r) => r.json()),
-    send: async (method, path, body, encoding = 'json') => {
-      const init: RequestInit = { method, headers: { ...headers } };
-      if (body && Object.keys(body).length) {
-        if (encoding === 'form') {
-          const p = new URLSearchParams();
-          formEncode(body, '', p);
-          init.body = p.toString();
-          (init.headers as Record<string, string>)['content-type'] = 'application/x-www-form-urlencoded';
-        } else {
-          init.body = JSON.stringify(body);
-          (init.headers as Record<string, string>)['content-type'] = 'application/json';
-        }
-      }
-      const r = await fetch(`${BASE}${path}`, init);
-      const text = await r.text();
-      let parsed: any = text;
-      try { parsed = text ? JSON.parse(text) : null; } catch { /* a non-JSON answer stays text */ }
-      return { status: r.status, body: parsed };
-    },
-  };
-}
-
-const fill = (path: string, id: string): string => path.replace(/\{[^}]+\}/, encodeURIComponent(id));
-const defaultRows = (body: any): Row[] => (Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : []);
-
-// ── pieces ───────────────────────────────────────────────────────────────────────────────
-
-export function StatusPill({ value, tone }: { value: unknown; tone?: TwinUiConfig['tone'] }) {
-  if (value === undefined || value === null || value === '') return null;
-  const t = tone?.(String(value)) ?? (/(succeeded|paid|active|open|completed|ok|true)/.test(String(value)) ? 'ok' : /(fail|canceled|cancelled|void|closed|expired|error|false)/.test(String(value)) ? 'bad' : 'muted');
-  return <span className={`tw-pill tw-pill-${t}`}>{String(value)}</span>;
-}
-
-export function RefChip({ label, onJump }: { label: string; onJump: () => void }) {
-  return (
-    <button type="button" className="tw-ref" onClick={onJump}>
-      {label}
-    </button>
-  );
-}
-
-/** An object as the vendor's detail page lists it: one line per field, nested objects indented, references as chips. */
-export function Fields({ row, embeds, onJump }: { row: Row; embeds: Record<string, string>; onJump: (resource: string, id: string) => void }) {
-  const lines: Array<{ key: string; depth: number; value: ReactNode }> = [];
-  const walk = (obj: Row, depth: number, prefix: string) => {
-    for (const [k, v] of Object.entries(obj)) {
-      const key = prefix ? `${prefix}.${k}` : k;
-      if (v && typeof v === 'object' && !Array.isArray(v)) {
-        lines.push({ key, depth, value: '' });
-        walk(v, depth + 1, key);
-      } else if (depth === 0 && embeds[k] && typeof v === 'string') {
-        lines.push({ key, depth, value: <RefChip label={v} onJump={() => onJump(embeds[k]!, v)} /> });
-      } else lines.push({ key, depth, value: Array.isArray(v) ? JSON.stringify(v) : String(v) });
-    }
-  };
-  walk(row, 0, '');
-  return (
-    <dl className="tw-fields">
-      {lines.map((l) => (
-        <div key={l.key} className="tw-field" style={{ paddingLeft: `${l.depth * 16}px` }}>
-          <dt>{l.key.split('.').at(-1)}</dt>
-          <dd>{l.value}</dd>
-        </div>
-      ))}
-    </dl>
-  );
-}
-
-/** The moves the resource's machine allows from where this row stands, as buttons. */
-export function Actions({ resource, row, api, onDone }: { resource: UiResource; row: Row; api: Api; onDone: () => void }) {
-  const [error, setError] = useState<string | null>(null);
-  const legal = resource.actions.filter((a) => a.from === '*' || a.from.includes(String(row[a.field])));
-  const seen = new Set<string>();
-  const unique = legal.filter((a) => (seen.has(a.operation) ? false : (seen.add(a.operation), true)));
-  if (!unique.length) return null;
-  return (
-    <div className="tw-actions">
-      {unique.map((a) => (
-        <button
-          key={a.operation}
-          type="button"
-          onClick={async () => {
-            setError(null);
-            const r = await api.send(a.method, fill(a.path, String(row.id)), undefined, resource.create?.encoding);
-            if (r.status >= 400) setError(r.body?.error?.message ?? r.body?.message ?? r.body?.error ?? `HTTP ${r.status}`);
-            onDone();
-          }}
-        >
-          {a.path.split('/').at(-1)!.replace(/[_-]/g, ' ')}
-        </button>
-      ))}
-      {error ? <p className="tw-error">{String(error)}</p> : null}
-    </div>
-  );
-}
-
-/** A form for the resource's create operation: its required parameters, and any others the caller fills. */
-export function CreateForm({ resource, api, onCreated }: { resource: UiResource; api: Api; onCreated: (row: Row) => void }) {
-  const create = resource.create;
-  const [values, setValues] = useState<Record<string, string>>({});
-  const [error, setError] = useState<string | null>(null);
-  if (!create) return null;
-  const fields = create.body.filter((b) => b.required || ['name', 'email', 'description', 'title', 'amount', 'currency'].includes(b.name));
-  return (
-    <form
-      className="tw-create"
-      onSubmit={async (e) => {
-        e.preventDefault();
-        setError(null);
-        const r = await api.send('POST', create.path, values, create.encoding);
-        if (r.status >= 400) setError(r.body?.error?.message ?? r.body?.message ?? `HTTP ${r.status}`);
-        else onCreated(r.body);
-      }}
-    >
-      {fields.map((f) => (
-        <label key={f.name}>
-          {f.name}
-          {f.required ? ' *' : ''}
-          <input value={values[f.name] ?? ''} onChange={(e) => setValues({ ...values, [f.name]: e.target.value })} />
-        </label>
-      ))}
-      <button type="submit">Create</button>
-      {error ? <p className="tw-error">{String(error)}</p> : null}
-    </form>
-  );
-}
-
-// ── the app ──────────────────────────────────────────────────────────────────────────────
-
-type Route = { kind: 'home' } | { kind: 'list'; section: Section } | { kind: 'detail'; section: Section; id: string } | { kind: 'screen'; screen: Screen };
-
-export function TwinUi({ config }: { config: TwinUiConfig }) {
-  const api = useMemo(() => makeApi(config.headers), [config.headers]);
-  const [route, setRoute] = useState<Route>({ kind: 'home' });
-  const [rows, setRows] = useState<Row[]>([]);
-  const [detail, setDetail] = useState<Row | null>(null);
-  const [counts, setCounts] = useState<Record<string, number>>({});
-  const [tick, setTick] = useState(0);
-  const rowsOf = config.rowsAt ?? defaultRows;
-  const listPath = (s: Section) => s.list ?? config.ui.resources[s.resource]?.list;
-  const bySection = (resource: string) => config.sections.find((s) => s.resource === resource);
-
-  useEffect(() => {
-    for (const s of config.sections) {
-      const p = listPath(s);
-      if (p && !p.includes('{')) api.get(p).then((b) => setCounts((c) => ({ ...c, [s.label]: rowsOf(b, s.resource).length }))).catch(() => undefined);
-    }
-  }, [tick]);
-
-  useEffect(() => {
-    if (route.kind === 'list') {
-      const p = listPath(route.section);
-      if (p) api.get(p).then((b) => setRows(rowsOf(b, route.section.resource))).catch(() => setRows([]));
-    }
-    if (route.kind === 'detail') {
-      const r = config.ui.resources[route.section.resource];
-      const fromList = rows.find((x) => String(x.id) === route.id) ?? null;
-      if (r?.retrieve && (r.retrieve.match(/\{/g) ?? []).length === 1) api.get(fill(r.retrieve, route.id)).then(setDetail).catch(() => setDetail(fromList));
-      else setDetail(fromList);
-    }
-  }, [route, tick]);
-
-  const jump = useCallback((resource: string, id: string) => {
-    const s = bySection(resource);
-    if (s) setRoute({ kind: 'detail', section: s, id });
-  }, []);
-
-  return (
-    <div className="tw-app">
-      <nav className="tw-nav">
-        <button type="button" className="tw-brand" onClick={() => setRoute({ kind: 'home' })}>
-          {config.skin.name}
-          {config.skin.product ? <small>{config.skin.product}</small> : null}
-        </button>
-        {(config.screens ?? []).map((s) => (
-          <button key={s.key} type="button" className={route.kind === 'screen' && route.screen.key === s.key ? 'tw-on' : ''} onClick={() => setRoute({ kind: 'screen', screen: s })}>
-            {s.label}
-          </button>
-        ))}
-        {config.sections.map((s) => (
-          <button key={s.label} type="button" className={route.kind !== 'home' && route.kind !== 'screen' && route.section.label === s.label ? 'tw-on' : ''} onClick={() => setRoute({ kind: 'list', section: s })}>
-            {s.label}
-            {counts[s.label] !== undefined ? <span className="tw-count">{counts[s.label]}</span> : null}
-          </button>
-        ))}
-      </nav>
-      <main className="tw-main">
-        {route.kind === 'home' ? (
-          <section className="tw-home">
-            <h1>{config.skin.name}</h1>
-            <ul>
-              {config.sections.map((s) => (
-                <li key={s.label}>
-                  <button type="button" onClick={() => setRoute({ kind: 'list', section: s })}>
-                    {s.label} <span className="tw-count">{counts[s.label] ?? '…'}</span>
-                  </button>
-                </li>
-              ))}
-            </ul>
-          </section>
-        ) : null}
-        {route.kind === 'screen' ? route.screen.render(api) : null}
-        {route.kind === 'list' ? (
-          <section>
-            <h1>{route.section.label}</h1>
-            {config.ui.resources[route.section.resource] ? <CreateForm resource={config.ui.resources[route.section.resource]!} api={api} onCreated={() => setTick((t) => t + 1)} /> : null}
-            <ul className="tw-list">
-              {rows.map((r) => (
-                <li key={String(r.id)}>
-                  <button type="button" onClick={() => setRoute({ kind: 'detail', section: route.section, id: String(r.id) })}>
-                    <strong>{route.section.title?.(r) ?? String(r.name ?? r.title ?? r.id)}</strong>
-                    <span>{route.section.subtitle?.(r) ?? String(r.id)}</span>
-                    <StatusPill value={r.status ?? r.state} tone={config.tone} />
-                  </button>
-                </li>
-              ))}
-              {rows.length === 0 ? <li className="tw-empty">None yet.</li> : null}
-            </ul>
-          </section>
-        ) : null}
-        {route.kind === 'detail' && detail ? (
-          <section>
-            <button type="button" className="tw-back" onClick={() => setRoute({ kind: 'list', section: route.section })}>
-              ← {route.section.label}
-            </button>
-            <h1>
-              {route.section.title?.(detail) ?? String(detail.name ?? detail.title ?? detail.id)} <StatusPill value={detail.status ?? detail.state} tone={config.tone} />
-            </h1>
-            {route.section.extras?.(detail)}
-            {config.ui.resources[route.section.resource] ? <Actions resource={config.ui.resources[route.section.resource]!} row={detail} api={api} onDone={() => setTick((t) => t + 1)} /> : null}
-            <Fields row={detail} embeds={config.ui.resources[route.section.resource]?.embeds ?? {}} onJump={jump} />
-          </section>
-        ) : null}
-      </main>
-    </div>
-  );
-}
-
-/** Mount a pack's UI into the shell's #root. */
-export function mountTwinUi(config: TwinUiConfig): void {
-  if (typeof document === 'undefined') return;
-  createRoot(document.getElementById('root')!).render(<TwinUi config={config} />);
-}