@kelpie/ui 0.1.0

package/dist/registry/contributions.js

@@ -0,0 +1,25 @@
+/**
+ * What a UI module may add to the shell, per the slot table in `modules.md`.
+ *
+ * Every slot renders nothing when empty. A core page has to look finished with
+ * no modules loaded at all, because the open-source assembly is exactly that.
+ */
+export const NAV_SLOTS = ['primary', 'admin', 'account'];
+/**
+ * The record types a detail page exists for, and therefore the ones a module can
+ * add a tab or a sidebar card to.
+ *
+ * Now in `@kelpie/schemas`, which is the shared-schema package this file's
+ * previous note was waiting for. Re-exported rather than moved outright: it is
+ * part of the contribution vocabulary, and a module author reading this file
+ * should not have to follow an import to learn what a record type is.
+ */
+export { EXTENSIBLE_RECORD_TYPES } from '@kelpie/schemas';
+export const INTEGRATION_CATEGORIES = [
+    'messaging',
+    'identity',
+    'enrichment',
+    'email',
+    'calendar',
+];
+//# sourceMappingURL=contributions.js.map

package/dist/registry/contributions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contributions.js","sourceRoot":"","sources":["../../src/registry/contributions.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,CAAU,CAAA;AAuBjE;;;;;;;;GAQG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AA4BzD,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,WAAW;IACX,UAAU;IACV,YAAY;IACZ,OAAO;IACP,UAAU;CACF,CAAA"}

package/dist/registry/overridable.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentType } from 'react';
+/**
+ * The override escape hatch from `modules.md`: a module replaces a core
+ * component outright. Prefer a slot; this is for the cases a slot cannot reach.
+ *
+ * A core component is replaceable only if it hands out a token, and the token
+ * carries its props type. So an override that does not accept the props core
+ * passes is a compile error, and a key nothing declared cannot be overridden at
+ * all: there is no token to name it with.
+ */
+export interface Overridable<Props> {
+    readonly key: string;
+    /** What renders when no module overrides it. Core's own component. */
+    readonly fallback: ComponentType<Props>;
+}
+/**
+ * @param key Stable across releases. It is the name a module writes down.
+ */
+export declare function defineOverridable<Props>(key: string, fallback: ComponentType<Props>): Overridable<Props>;
+export interface OverrideStore {
+    set<Props>(token: Overridable<Props>, component: ComponentType<Props>): void;
+    /** @returns The override, or the token's own fallback when no module replaced it. */
+    get<Props>(token: Overridable<Props>): ComponentType<Props>;
+    has(key: string): boolean;
+}
+export declare function createOverrideStore(): OverrideStore;
+//# sourceMappingURL=overridable.d.ts.map

package/dist/registry/overridable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overridable.d.ts","sourceRoot":"","sources":["../../src/registry/overridable.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW,CAAC,KAAK;IAChC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,CAAA;CACxC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,GAC7B,WAAW,CAAC,KAAK,CAAC,CAEpB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;IAC5E,qFAAqF;IACrF,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;IAC3D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAC1B;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CA0BnD"}

package/dist/registry/overridable.js

@@ -0,0 +1,29 @@
+/**
+ * @param key Stable across releases. It is the name a module writes down.
+ */
+export function defineOverridable(key, fallback) {
+    return { key, fallback };
+}
+export function createOverrideStore() {
+    // One map holding components with different props types, so the value type is
+    // the only one they share. `ComponentType<never>` looks like the tighter
+    // choice and is not: `ComponentClass.defaultProps` is covariant in Props, so
+    // nothing is assignable to it.
+    const byKey = new Map();
+    return {
+        set(token, component) {
+            byKey.set(token.key, component);
+        },
+        get(token) {
+            const override = byKey.get(token.key);
+            if (override === undefined) {
+                return token.fallback;
+            }
+            // Sound by construction: the only writer is `set`, which accepts nothing
+            // but a component for this token's own props.
+            return override;
+        },
+        has: (key) => byKey.has(key),
+    };
+}
+//# sourceMappingURL=overridable.js.map

package/dist/registry/overridable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overridable.js","sourceRoot":"","sources":["../../src/registry/overridable.ts"],"names":[],"mappings":"AAkBA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAC/B,GAAW,EACX,QAA8B;IAE9B,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAA;AAC1B,CAAC;AASD,MAAM,UAAU,mBAAmB;IACjC,8EAA8E;IAC9E,yEAAyE;IACzE,6EAA6E;IAC7E,+BAA+B;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmB,CAAA;IAExC,OAAO;QACL,GAAG,CAAQ,KAAyB,EAAE,SAA+B;YACnE,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;QACjC,CAAC;QAED,GAAG,CAAQ,KAAyB;YAClC,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;YAErC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAC3B,OAAO,KAAK,CAAC,QAAQ,CAAA;YACvB,CAAC;YAED,yEAAyE;YACzE,8CAA8C;YAC9C,OAAO,QAAgC,CAAA;QACzC,CAAC;QAED,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;KAC7B,CAAA;AACH,CAAC"}

package/dist/registry/registry.d.ts

@@ -0,0 +1,68 @@
+import type { ComponentType } from 'react';
+import type { DashboardCard, ExtensibleRecordType, IntegrationProvider, NavItem, NavSlot, RecordSidebarCard, RecordTab, RouteContribution } from './contributions.ts';
+import type { Overridable } 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>;
+}
+/**
+ * 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 declare function inSlotOrder<T extends {
+    readonly order?: number;
+}>(items: readonly T[]): readonly T[];
+/** A module contributing under a name another module already used. Fails the build, like the server runtime. */
+export declare class UiModuleError extends Error {
+    constructor(message: string);
+}
+/**
+ * @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 declare function registerUiModules(modules: readonly UiModule[]): UiExtensions;
+/**
+ * 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 declare const NO_UI_MODULES: UiExtensions;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAE1C,OAAO,KAAK,EACV,aAAa,EACb,oBAAoB,EACpB,mBAAmB,EACnB,OAAO,EACP,OAAO,EACP,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EAClB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,KAAK,EAAE,WAAW,EAAiB,MAAM,kBAAkB,CAAA;AAElE;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAA;IACvC,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACrC,SAAS,CAAC,UAAU,EAAE,oBAAoB,EAAE,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;IACjE,iBAAiB,CAAC,UAAU,EAAE,oBAAoB,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAClF,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI,CAAA;IACxC,mBAAmB,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAA;IACxD,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,IAAI,CAAA;CAClF;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAAA;CACzC;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAA;IAC3C,MAAM,IAAI,SAAS,iBAAiB,EAAE,CAAA;IACtC,UAAU,CAAC,UAAU,EAAE,oBAAoB,GAAG,SAAS,SAAS,EAAE,CAAA;IAClE,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,GAAG,SAAS,iBAAiB,EAAE,CAAA;IAClF,cAAc,IAAI,SAAS,aAAa,EAAE,CAAA;IAC1C,oBAAoB,IAAI,SAAS,mBAAmB,EAAE,CAAA;IACtD,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;CACrE;AAKD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,SAAS,CAAC,EAAE,CAEpG;AAYD,gHAAgH;AAChH,qBAAa,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAwED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,YAAY,CAgC5E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,YAAoC,CAAA"}

package/dist/registry/registry.js

@@ -0,0 +1,112 @@
+import { createOverrideStore } from './overridable.js';
+/** 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(items) {
+    return [...items].sort((left, right) => (left.order ?? UNORDERED) - (right.order ?? UNORDERED));
+}
+/** A module contributing under a name another module already used. Fails the build, like the server runtime. */
+export class UiModuleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'UiModuleError';
+    }
+}
+function claim(taken, moduleId, what, id) {
+    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(map, key, value) {
+    const existing = map.get(key);
+    if (existing === undefined) {
+        map.set(key, [value]);
+        return;
+    }
+    existing.push(value);
+}
+function createModuleContext(module, accumulator, taken) {
+    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) {
+    const accumulator = {
+        nav: new Map(),
+        routes: [],
+        recordTabs: new Map(),
+        recordSidebarCards: new Map(),
+        dashboardCards: [],
+        integrationProviders: [],
+        overrides: createOverrideStore(),
+    };
+    const taken = new Set();
+    const seenIds = new Set();
+    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 = registerUiModules([]);
+//# sourceMappingURL=registry.js.map

package/dist/registry/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/registry/registry.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AA2CtD,4FAA4F;AAC5F,MAAM,SAAS,GAAG,MAAM,CAAC,gBAAgB,CAAA;AAEzC;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAwC,KAAmB;IACpF,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,IAAI,SAAS,CAAC,CAAC,CAAA;AACjG,CAAC;AAYD,gHAAgH;AAChH,MAAM,OAAO,aAAc,SAAQ,KAAK;IACtC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,eAAe,CAAA;IAC7B,CAAC;CACF;AAED,SAAS,KAAK,CAAC,KAAkB,EAAE,QAAgB,EAAE,IAAY,EAAE,EAAU;IAC3E,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,CAAA;IAE5B,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,aAAa,CAAC,WAAW,QAAQ,iBAAiB,IAAI,KAAK,EAAE,2BAA2B,CAAC,CAAA;IACrG,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACjB,CAAC;AAED,SAAS,QAAQ,CAAa,GAAsB,EAAE,GAAQ,EAAE,KAAY;IAC1E,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAE7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC,CAAA;QAErB,OAAM;IACR,CAAC;IAED,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACtB,CAAC;AAED,SAAS,mBAAmB,CAC1B,MAAgB,EAChB,WAAwB,EACxB,KAAkB;IAElB,OAAO;QACL,GAAG,CAAC,IAAI,EAAE,IAAI;YACZ,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,IAAI,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;YAC/C,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAA;QACvC,CAAC;QAED,KAAK,CAAC,KAAK;YACT,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,CAAA;YAC5C,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC;QAED,SAAS,CAAC,UAAU,EAAE,GAAG;YACvB,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,eAAe,UAAU,EAAE,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;YAC5D,QAAQ,CAAC,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,GAAG,CAAC,CAAA;QACnD,CAAC;QAED,iBAAiB,CAAC,UAAU,EAAE,IAAI;YAChC,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,kBAAkB,UAAU,EAAE,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;YAChE,QAAQ,CAAC,WAAW,CAAC,kBAAkB,EAAE,UAAU,EAAE,IAAI,CAAC,CAAA;QAC5D,CAAC;QAED,aAAa,CAAC,IAAI;YAChB,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,CAAC,CAAA;YACnD,WAAW,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QACvC,CAAC;QAED,mBAAmB,CAAC,QAAQ;YAC1B,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,EAAE,EAAE,4BAA4B,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAA;YAClE,WAAW,CAAC,oBAAoB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACjD,CAAC;QAED,QAAQ,CAAC,KAAK,EAAE,SAAS;YACvB,IAAI,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,MAAM,IAAI,aAAa,CACrB,WAAW,MAAM,CAAC,EAAE,gBAAgB,KAAK,CAAC,GAAG,0CAA0C,CACxF,CAAA;YACH,CAAC;YAED,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QAC7C,CAAC;KACF,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA4B;IAC5D,MAAM,WAAW,GAAgB;QAC/B,GAAG,EAAE,IAAI,GAAG,EAAE;QACd,MAAM,EAAE,EAAE;QACV,UAAU,EAAE,IAAI,GAAG,EAAE;QACrB,kBAAkB,EAAE,IAAI,GAAG,EAAE;QAC7B,cAAc,EAAE,EAAE;QAClB,oBAAoB,EAAE,EAAE;QACxB,SAAS,EAAE,mBAAmB,EAAE;KACjC,CAAA;IACD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAA;IAC/B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAA;IAEjC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,aAAa,CAAC,gCAAgC,MAAM,CAAC,EAAE,GAAG,CAAC,CAAA;QACvE,CAAC;QAED,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,CAAA;QACtB,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,KAAK,CAAC,CAAC,CAAA;IAClE,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QAChE,MAAM,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,MAAM;QAChC,UAAU,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACrF,kBAAkB,EAAE,CAAC,UAAU,EAAE,EAAE,CACjC,WAAW,CAAC,WAAW,CAAC,kBAAkB,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QACnE,cAAc,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,WAAW,CAAC,cAAc,CAAC;QAC7D,oBAAoB,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,oBAAoB;QAC5D,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC;KAC1D,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAiB,iBAAiB,CAAC,EAAE,CAAC,CAAA"}

package/dist/testing/inputs.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function setInputValue(input: HTMLElement, value: string): void;
+//# sourceMappingURL=inputs.d.ts.map

package/dist/testing/inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.d.ts","sourceRoot":"","sources":["../../src/testing/inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAMrE"}

package/dist/testing/inputs.js

@@ -0,0 +1,16 @@
+/**
+ * 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, value) {
+    Object.getOwnPropertyDescriptor(globalThis.HTMLInputElement.prototype, 'value')?.set?.call(input, value);
+    input.dispatchEvent(new Event('input', { bubbles: true }));
+}
+//# sourceMappingURL=inputs.js.map

package/dist/testing/inputs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inputs.js","sourceRoot":"","sources":["../../src/testing/inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,KAAkB,EAAE,KAAa;IAC7D,MAAM,CAAC,wBAAwB,CAAC,UAAU,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,IAAI,CACxF,KAAK,EACL,KAAK,CACN,CAAA;IACD,KAAK,CAAC,aAAa,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;AAC5D,CAAC"}

package/dist/testing/stubClient.d.ts

@@ -0,0 +1,42 @@
+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;
+}
+export declare function stubClient(stubs: ClientStubs): ApiClient;
+//# sourceMappingURL=stubClient.d.ts.map

package/dist/testing/stubClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubClient.d.ts","sourceRoot":"","sources":["../../src/testing/stubClient.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAElE;;;;;;;;;;;;;;;GAeG;AAEH,uEAAuE;AACvE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAC/F,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IAC7D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,CAAA;IAClG,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAC3E,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAChF,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAA;IAC5E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;CAC7F;AAUD,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,SAAS,CAyBxD"}

package/dist/testing/stubClient.js

@@ -0,0 +1,29 @@
+function required(stub, verb, path) {
+    if (stub === undefined) {
+        throw new Error(`Unexpected ${verb} ${path}`);
+    }
+    return stub;
+}
+export function stubClient(stubs) {
+    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);
+        },
+    };
+}
+//# sourceMappingURL=stubClient.js.map

package/dist/testing/stubClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stubClient.js","sourceRoot":"","sources":["../../src/testing/stubClient.ts"],"names":[],"mappings":"AA4CA,SAAS,QAAQ,CAAQ,IAAuB,EAAE,IAAY,EAAE,IAAY;IAC1E,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,IAAI,IAAI,EAAE,CAAC,CAAA;IAC/C,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAkB;IAC3C,OAAO;QACL,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,CACjC,MAAM,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC;QACvE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,EAAE;YACtC,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;YAElE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CAAA;QAC3E,CAAC;QACD,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChG,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CACrC,MAAM,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,UAAU,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACtE,SAAS,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC9B,MAAM,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAChE,CAAC;QACD,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAClC,MAAM,CAAC,MAAM,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;YAC/B,MAAM,QAAQ,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QAClE,CAAC;QACD,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE;YAC5B,MAAM,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAC3D,CAAC;KACF,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@kelpie/ui",
+  "version": "0.1.0",
+  "description": "React UI for Kelpie: components, pages, API client, and the extension registry an assembly composes modules through.",
+  "keywords": [
+    "kelpie",
+    "crm",
+    "react",
+    "ui",
+    "components"
+  ],
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velvet-tiger/kelpie.git",
+    "directory": "packages/ui"
+  },
+  "homepage": "https://github.com/velvet-tiger/kelpie/tree/main/packages/ui#readme",
+  "bugs": "https://github.com/velvet-tiger/kelpie/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx"
+  ],
+  "exports": {
+    ".": {
+      "kelpie-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./styles.css": "./src/styles.css"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@kelpie/schemas": "^0.1.0",
+    "@tanstack/react-query": "^5.101.4",
+    "react-markdown": "^10.1.0",
+    "react-router": "^8.3.0",
+    "remark-gfm": "^4.0.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "happy-dom": "^20.11.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.2.0",
+    "vitest": "^4.1.10"
+  }
+}

package/src/ServiceStatus.tsx

@@ -0,0 +1,61 @@
+import { useEffect, useState } from 'react'
+
+import { fetchServiceHealth } from './api/health.ts'
+import type { ServiceHealth } from './api/health.ts'
+
+/**
+ * Placeholder root view. It exists so the UI build and the API wiring are both
+ * exercised end to end; the mockup pages replace it during the Phase 1 port.
+ */
+
+type HealthState =
+  | { readonly kind: 'loading' }
+  | { readonly kind: 'loaded'; readonly health: ServiceHealth }
+  | { readonly kind: 'unreachable'; readonly reason: string }
+
+export interface ServiceStatusProps {
+  /** Path or URL of the service health endpoint. */
+  readonly healthUrl: string
+}
+
+export function ServiceStatus({ healthUrl }: ServiceStatusProps): React.JSX.Element {
+  const [state, setState] = useState<HealthState>({ kind: 'loading' })
+
+  useEffect(() => {
+    let active = true
+
+    fetchServiceHealth({ url: healthUrl })
+      .then((health) => {
+        if (active) {
+          setState({ kind: 'loaded', health })
+        }
+      })
+      .catch((error: unknown) => {
+        if (active) {
+          setState({ kind: 'unreachable', reason: error instanceof Error ? error.message : String(error) })
+        }
+      })
+
+    return () => {
+      active = false
+    }
+  }, [healthUrl])
+
+  return (
+    <main className="mx-auto flex min-h-screen max-w-xl flex-col justify-center gap-3 px-6">
+      <h1 className="text-2xl font-semibold">Kelpie</h1>
+      <p className="text-sm text-gray-600">{describe(state)}</p>
+    </main>
+  )
+}
+
+function describe(state: HealthState): string {
+  switch (state.kind) {
+    case 'loading':
+      return 'Checking the service…'
+    case 'loaded':
+      return `Service ${state.health.status}, database ${state.health.database}.`
+    case 'unreachable':
+      return `Service unreachable: ${state.reason}`
+  }
+}

package/src/api/ApiProvider.tsx

@@ -0,0 +1,40 @@
+import { QueryClientProvider } from '@tanstack/react-query'
+import type { QueryClient } from '@tanstack/react-query'
+import { useState } from 'react'
+import type { ReactNode } from 'react'
+
+import { createApiClient } from './client.ts'
+import type { ApiClient } from './client.ts'
+import { ApiClientContext } from './context.ts'
+import { createQueryClient } from './queryClient.ts'
+
+export interface ApiProviderProps {
+  /** Origin plus base path, e.g. `/v1` in the browser. */
+  readonly baseUrl?: string
+  /** A prepared client, for tests and for assemblies that construct their own. */
+  readonly client?: ApiClient
+  readonly queryClient?: QueryClient
+  readonly children: ReactNode
+}
+
+/**
+ * Puts an API client and a query cache in reach of the tree below it.
+ *
+ * Both are held in state rather than built inline, because a fresh
+ * `QueryClient` on every render throws the cache away on every render.
+ */
+export function ApiProvider({
+  baseUrl = '/v1',
+  client,
+  queryClient,
+  children,
+}: ApiProviderProps): React.JSX.Element {
+  const [resolvedClient] = useState<ApiClient>(() => client ?? createApiClient({ baseUrl }))
+  const [resolvedQueryClient] = useState<QueryClient>(() => queryClient ?? createQueryClient())
+
+  return (
+    <QueryClientProvider client={resolvedQueryClient}>
+      <ApiClientContext value={resolvedClient}>{children}</ApiClientContext>
+    </QueryClientProvider>
+  )
+}