@kelpie/ui 0.1.0

package/src/registry/registry.ts

@@ -0,0 +1,204 @@
+import type { ComponentType } from 'react'
+
+import type {
+  DashboardCard,
+  ExtensibleRecordType,
+  IntegrationProvider,
+  NavItem,
+  NavSlot,
+  RecordSidebarCard,
+  RecordTab,
+  RouteContribution,
+} from './contributions.ts'
+import { createOverrideStore } from './overridable.ts'
+import type { Overridable, OverrideStore } from './overridable.ts'
+
+/**
+ * The build-time UI extension registry from `modules.md`.
+ *
+ * Composition is build-time, like the server runtime: an assembly lists its UI
+ * modules and this collects what they contribute. Nothing is loaded at runtime,
+ * so the bundle contains exactly the modules the assembly named.
+ *
+ * There is no `requires` here, unlike the server runtime, because nothing about
+ * a UI contribution depends on another module having registered first. Placement
+ * within a slot is `order`, which is explicit and does not need a topological
+ * sort to reason about.
+ */
+
+export interface UiModuleContext {
+  nav(slot: NavSlot, item: NavItem): void
+  route(route: RouteContribution): void
+  recordTab(objectType: ExtensibleRecordType, tab: RecordTab): void
+  recordSidebarCard(objectType: ExtensibleRecordType, card: RecordSidebarCard): void
+  dashboardCard(card: DashboardCard): void
+  integrationProvider(provider: IntegrationProvider): void
+  /** Replaces a core component. Prefer a slot; see `modules.md`. */
+  override<Props>(token: Overridable<Props>, component: ComponentType<Props>): void
+}
+
+export interface UiModule {
+  readonly id: string
+  register(context: UiModuleContext): void
+}
+
+/** Everything the registered modules contributed, ready for the shell to render. */
+export interface UiExtensions {
+  navItems(slot: NavSlot): readonly NavItem[]
+  routes(): readonly RouteContribution[]
+  recordTabs(objectType: ExtensibleRecordType): readonly RecordTab[]
+  recordSidebarCards(objectType: ExtensibleRecordType): readonly RecordSidebarCard[]
+  dashboardCards(): readonly DashboardCard[]
+  integrationProviders(): readonly IntegrationProvider[]
+  componentFor<Props>(token: Overridable<Props>): ComponentType<Props>
+}
+
+/** Anything unordered sorts after everything ordered, keeping its registration position. */
+const UNORDERED = Number.MAX_SAFE_INTEGER
+
+/**
+ * Sorts slot contributions. Exported because the shell merges its own items into
+ * the same slot and both sides have to agree on what `order` means.
+ *
+ * Stable, so two contributions with the same order keep their registration order
+ * rather than swapping between builds.
+ */
+export function inSlotOrder<T extends { readonly order?: number }>(items: readonly T[]): readonly T[] {
+  return [...items].sort((left, right) => (left.order ?? UNORDERED) - (right.order ?? UNORDERED))
+}
+
+interface Accumulator {
+  readonly nav: Map<NavSlot, NavItem[]>
+  readonly routes: RouteContribution[]
+  readonly recordTabs: Map<ExtensibleRecordType, RecordTab[]>
+  readonly recordSidebarCards: Map<ExtensibleRecordType, RecordSidebarCard[]>
+  readonly dashboardCards: DashboardCard[]
+  readonly integrationProviders: IntegrationProvider[]
+  readonly overrides: OverrideStore
+}
+
+/** A module contributing under a name another module already used. Fails the build, like the server runtime. */
+export class UiModuleError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'UiModuleError'
+  }
+}
+
+function claim(taken: Set<string>, moduleId: string, what: string, id: string): void {
+  const name = `${what}:${id}`
+
+  if (taken.has(name)) {
+    throw new UiModuleError(`module "${moduleId}" contributes ${what} "${id}", which is already taken`)
+  }
+
+  taken.add(name)
+}
+
+function pushInto<Key, Value>(map: Map<Key, Value[]>, key: Key, value: Value): void {
+  const existing = map.get(key)
+
+  if (existing === undefined) {
+    map.set(key, [value])
+
+    return
+  }
+
+  existing.push(value)
+}
+
+function createModuleContext(
+  module: UiModule,
+  accumulator: Accumulator,
+  taken: Set<string>,
+): UiModuleContext {
+  return {
+    nav(slot, item) {
+      claim(taken, module.id, `nav.${slot}`, item.id)
+      pushInto(accumulator.nav, slot, item)
+    },
+
+    route(route) {
+      claim(taken, module.id, 'route', route.path)
+      accumulator.routes.push(route)
+    },
+
+    recordTab(objectType, tab) {
+      claim(taken, module.id, `record.tabs.${objectType}`, tab.id)
+      pushInto(accumulator.recordTabs, objectType, tab)
+    },
+
+    recordSidebarCard(objectType, card) {
+      claim(taken, module.id, `record.sidebar.${objectType}`, card.id)
+      pushInto(accumulator.recordSidebarCards, objectType, card)
+    },
+
+    dashboardCard(card) {
+      claim(taken, module.id, 'dashboard.cards', card.id)
+      accumulator.dashboardCards.push(card)
+    },
+
+    integrationProvider(provider) {
+      claim(taken, module.id, 'admin.integrations.catalog', provider.id)
+      accumulator.integrationProviders.push(provider)
+    },
+
+    override(token, component) {
+      if (accumulator.overrides.has(token.key)) {
+        throw new UiModuleError(
+          `module "${module.id}" overrides "${token.key}", which another module already replaced`,
+        )
+      }
+
+      accumulator.overrides.set(token, component)
+    },
+  }
+}
+
+/**
+ * @throws UiModuleError on a duplicate module id, or two modules claiming the
+ *   same contribution. Both would otherwise surface as a React key collision or
+ *   a silently discarded contribution, at runtime, in the browser.
+ */
+export function registerUiModules(modules: readonly UiModule[]): UiExtensions {
+  const accumulator: Accumulator = {
+    nav: new Map(),
+    routes: [],
+    recordTabs: new Map(),
+    recordSidebarCards: new Map(),
+    dashboardCards: [],
+    integrationProviders: [],
+    overrides: createOverrideStore(),
+  }
+  const taken = new Set<string>()
+  const seenIds = new Set<string>()
+
+  for (const module of modules) {
+    if (seenIds.has(module.id)) {
+      throw new UiModuleError(`two UI modules share the id "${module.id}"`)
+    }
+
+    seenIds.add(module.id)
+    module.register(createModuleContext(module, accumulator, taken))
+  }
+
+  return {
+    navItems: (slot) => inSlotOrder(accumulator.nav.get(slot) ?? []),
+    routes: () => accumulator.routes,
+    recordTabs: (objectType) => inSlotOrder(accumulator.recordTabs.get(objectType) ?? []),
+    recordSidebarCards: (objectType) =>
+      inSlotOrder(accumulator.recordSidebarCards.get(objectType) ?? []),
+    dashboardCards: () => inSlotOrder(accumulator.dashboardCards),
+    integrationProviders: () => accumulator.integrationProviders,
+    componentFor: (token) => accumulator.overrides.get(token),
+  }
+}
+
+/**
+ * The registry an assembly with no UI modules gets, and the default a component
+ * tree without a provider sees.
+ *
+ * Every slot is empty and every overridable renders its core fallback, which is
+ * the state `modules.md` requires core pages to look finished in.
+ */
+export const NO_UI_MODULES: UiExtensions = registerUiModules([])

package/src/styles.css

@@ -0,0 +1,175 @@
+@import "tailwindcss";
+
+/*
+ * The components beside this file, which is why the package ships `src` as well
+ * as `dist` and why `exports` points `./styles.css` here rather than at a copy
+ * under `dist`. Tailwind skips node_modules when it detects sources by itself,
+ * so a consumer's build finds these classes only through this line. Nothing
+ * warns when it stops working: the build still succeeds and every page ships
+ * unstyled. `npm run verify:packaging` asserts a few of the utilities survive an
+ * out-of-tree install.
+ */
+@source ".";
+
+/*
+ * Theme tokens, ported from mockups/src/index.css. Every colour a component
+ * names is a token, never a literal, so light and dark are the same markup with
+ * a different :root block. A module replacing a component inherits the palette
+ * for free.
+ */
+
+@theme {
+  --font-sans: "IBM Plex Sans", ui-sans-serif, system-ui, sans-serif;
+  --font-mono: "IBM Plex Mono", ui-monospace, monospace;
+
+  --color-surface: var(--surface);
+  --color-surface-raised: var(--surface-raised);
+  --color-surface-sunken: var(--surface-sunken);
+  --color-ink: var(--ink);
+  --color-ink-muted: var(--ink-muted);
+  --color-ink-faint: var(--ink-faint);
+  --color-border: var(--border);
+  --color-border-strong: var(--border-strong);
+  --color-accent: var(--accent);
+  --color-accent-hover: var(--accent-hover);
+  --color-accent-soft: var(--accent-soft);
+  --color-accent-fg: var(--accent-fg);
+  --color-danger: var(--danger);
+  --color-danger-soft: var(--danger-soft);
+  --color-danger-fg: var(--danger-fg);
+  --color-success: var(--success);
+  --color-success-soft: var(--success-soft);
+  --color-warning: var(--warning);
+  --color-warning-soft: var(--warning-soft);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-ink: var(--sidebar-ink);
+  --color-sidebar-muted: var(--sidebar-muted);
+  --color-sidebar-hover: var(--sidebar-hover);
+  --color-sidebar-active: var(--sidebar-active);
+  --color-code-bg: var(--code-bg);
+  --color-code-fg: var(--code-fg);
+  --color-sidebar-border: var(--sidebar-border);
+}
+
+:root {
+  color-scheme: light;
+
+  --surface: #fafafa;
+  --surface-raised: #ffffff;
+  --surface-sunken: #f4f4f5;
+  --ink: #18181b;
+  --ink-muted: #71717a;
+  --ink-faint: #a1a1aa;
+  --border: #e4e4e7;
+  --border-strong: #d4d4d8;
+  --accent: #0f766e;
+  --accent-hover: #0d9488;
+  --accent-soft: #f0fdfa;
+  --accent-fg: #ffffff;
+  --danger: #dc2626;
+  --danger-soft: #fef2f2;
+  --danger-fg: #ffffff;
+  --success: #059669;
+  --success-soft: #ecfdf5;
+  --warning: #d97706;
+  --warning-soft: #fffbeb;
+  --sidebar: #fafafa;
+  --sidebar-ink: #18181b;
+  --sidebar-muted: #71717a;
+  --sidebar-hover: #f4f4f5;
+  --sidebar-active: #ececef;
+  --sidebar-border: #e4e4e7;
+  --code-bg: #18181b;
+  --code-fg: #99f6e4;
+}
+
+[data-theme="dark"] {
+  color-scheme: dark;
+
+  --surface: #0c0c0d;
+  --surface-raised: #141416;
+  --surface-sunken: #09090b;
+  --ink: #fafafa;
+  --ink-muted: #a1a1aa;
+  --ink-faint: #71717a;
+  --border: #27272a;
+  --border-strong: #3f3f46;
+  --accent: #2dd4bf;
+  --accent-hover: #5eead4;
+  --accent-soft: #134e4a;
+  --accent-fg: #042f2e;
+  --danger: #f87171;
+  --danger-soft: #450a0a;
+  --danger-fg: #450a0a;
+  --success: #34d399;
+  --success-soft: #064e3b;
+  --warning: #fbbf24;
+  --warning-soft: #451a03;
+  --sidebar: #0c0c0d;
+  --sidebar-ink: #fafafa;
+  --sidebar-muted: #a1a1aa;
+  --sidebar-hover: #18181b;
+  --sidebar-active: #1f1f23;
+  --sidebar-border: #27272a;
+  --code-bg: #09090b;
+  --code-fg: #99f6e4;
+}
+
+@layer base {
+  * {
+    box-sizing: border-box;
+  }
+
+  html {
+    font-family: var(--font-sans);
+    color: var(--ink);
+    background: var(--surface);
+    -webkit-font-smoothing: antialiased;
+  }
+
+  body {
+    margin: 0;
+    min-height: 100vh;
+  }
+
+  button,
+  input,
+  select,
+  textarea {
+    font: inherit;
+  }
+
+  ::selection {
+    background: color-mix(in srgb, var(--accent) 28%, transparent);
+  }
+}
+
+@layer utilities {
+  .animate-fade-in {
+    animation: fade-in 160ms ease-out;
+  }
+
+  .animate-slide-in {
+    animation: slide-in 200ms ease-out;
+  }
+}
+
+@keyframes fade-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes slide-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}

package/src/testing/inputs.ts

@@ -0,0 +1,18 @@
+/**
+ * Driving a controlled input the way a person does.
+ *
+ * React installs its own `value` setter on the node and tracks the last value it
+ * wrote, so a plain `input.value = 'x'` is invisible to it: the change event
+ * fires, React compares against what it thinks is there, and drops the update.
+ * Calling the prototype's setter is what makes the assignment visible.
+ *
+ * Here rather than in each suite because this is the third file that needed it,
+ * which is the point at which `stubClient` moved too.
+ */
+export function setInputValue(input: HTMLElement, value: string): void {
+  Object.getOwnPropertyDescriptor(globalThis.HTMLInputElement.prototype, 'value')?.set?.call(
+    input,
+    value,
+  )
+  input.dispatchEvent(new Event('input', { bubbles: true }))
+}

package/src/testing/stubClient.ts

@@ -0,0 +1,78 @@
+import type { ApiClient, QueryParameters } from '../api/client.ts'
+
+/**
+ * One `ApiClient` stand-in for every UI test.
+ *
+ * Three test files used to hand-write their own, so a method added to
+ * `ApiClient` broke all three at once and each had to be fixed separately. It
+ * happened for `patchEmpty`, then again for `getText` and `postForm`. This is
+ * the one file that now has to change.
+ *
+ * A method a test did not stub throws, naming the verb and the path. An
+ * unexpected request is then a readable failure rather than a hang or a
+ * confusing decode error somewhere downstream.
+ *
+ * Stubs answer with **wire** shapes, not records: the decoder each hook passes
+ * runs the way it does in the browser, so a schema that stops matching the API
+ * fails a test rather than being bypassed.
+ */
+
+/** A list response before decoding, as `client.list` assembles one. */
+export interface WirePage {
+  readonly items: readonly unknown[]
+  readonly nextCursor: string | null
+}
+
+/**
+ * What a test chooses to answer. Everything is optional; anything left out
+ * throws when it is called.
+ *
+ * Each may return a value or a promise, so a test that does not care about
+ * timing can return a literal.
+ */
+export interface ClientStubs {
+  readonly get?: (path: string, query: QueryParameters | undefined) => Promise<unknown> | unknown
+  readonly getText?: (path: string) => Promise<string> | string
+  readonly list?: (path: string, query: QueryParameters | undefined) => Promise<WirePage> | WirePage
+  readonly post?: (path: string, body: unknown) => Promise<unknown> | unknown
+  readonly postForm?: (path: string, form: FormData) => Promise<unknown> | unknown
+  readonly postEmpty?: (path: string, body: unknown) => Promise<void> | void
+  readonly patch?: (path: string, body: unknown) => Promise<unknown> | unknown
+  readonly patchEmpty?: (path: string, body: unknown) => Promise<void> | void
+  readonly delete?: (path: string, query: QueryParameters | undefined) => Promise<void> | void
+}
+
+function required<TStub>(stub: TStub | undefined, verb: string, path: string): TStub {
+  if (stub === undefined) {
+    throw new Error(`Unexpected ${verb} ${path}`)
+  }
+
+  return stub
+}
+
+export function stubClient(stubs: ClientStubs): ApiClient {
+  return {
+    get: async (path, decode, query) =>
+      decode(await required(stubs.get, 'get', path)(path, query)),
+    getText: async (path) => required(stubs.getText, 'getText', path)(path),
+    list: async (path, decodeItem, query) => {
+      const wire = await required(stubs.list, 'list', path)(path, query)
+
+      return { items: wire.items.map(decodeItem), nextCursor: wire.nextCursor }
+    },
+    post: async (path, body, decode) => decode(await required(stubs.post, 'post', path)(path, body)),
+    postForm: async (path, form, decode) =>
+      decode(await required(stubs.postForm, 'postForm', path)(path, form)),
+    postEmpty: async (path, body) => {
+      await required(stubs.postEmpty, 'postEmpty', path)(path, body)
+    },
+    patch: async (path, body, decode) =>
+      decode(await required(stubs.patch, 'patch', path)(path, body)),
+    patchEmpty: async (path, body) => {
+      await required(stubs.patchEmpty, 'patchEmpty', path)(path, body)
+    },
+    delete: async (path, query) => {
+      await required(stubs.delete, 'delete', path)(path, query)
+    },
+  }
+}