Zayin/Ekklesia
3
0
Fork 0
Code Issues 1 Pull Requests 3 Actions Packages Projects Releases 8 Wiki Activity

feat: add Dashboard navigation as presentation configuration
CI / verify (pull_request) Successful in 34s
Details
CI / infrastructure-smoke (pull_request) Successful in 12s
Details
CI / migration-smoke (pull_request) Successful in 44s
Details

Browse Source 
Phase 6D pass 1. The shell's navigation was a flat list of module ids, which
is not a usable experience — and the obvious fix carries an obvious trap.
Letting a module declare its folder, or modelling "Media" as something
Livestream and Video belong to, turns a rendering preference into
architecture: a folder becomes an owner, membership starts to look like a
dependency, and the flat module graph acquires a hierarchy nobody decided on.

So the rule comes first: a Dashboard group is a label on a rendering bucket.
No manifest, no version, no artifact, no API, no lifecycle; nothing depends on
it. Livestream depends on Video because it calls Video's functionality, and
that orders startup. Livestream is shown under Media, and that orders nothing.
No parent module, child module, owning module, or group-derived dependency
appears anywhere in the contracts.

No manifest change and no version 5. `manifest.name` has been required since
version 1 and already is the module's product identity, so the shell renders
"Livestream" instead of `livestream` with nothing added. `suggestedGroup` is
deliberately deferred rather than shipped: it would force a hard
manifest-version cutover for a hint, and its only correct semantics needs
initialization logic that risks a suggestion overwriting an administrator's
decision. Defaulting and ownership are different things.

Two Core tables (migration 0003) hold groups and placements — server-side,
because a church configures its Dashboard rather than one browser;
platform-global, because no organization model exists to scope them to.
`group_id` is `on delete set null`, so deleting a group ungroups its modules
and a dangling reference is impossible. `module_id` carries no foreign key,
because modules are packages rather than rows, so a placement for an
uninstalled module is retained and restores its position on reinstall.

`resolveDashboardNavigation` is a pure function of configuration plus the
mountable set: an unplaced module is ungrouped and visible with no
initialization write, an absent module renders nothing, empty groups are kept,
and ordering is total with the module id as final tie-break.

`GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of
the host-neutral module UI inventory rather than merged into it — each generic
descriptor is embedded untouched, so a standalone host never inherits Dashboard
semantics. Reading needs the permission the inventory already needs; organizing
needs the new platform permission `core.dashboard.navigation.manage` through a
narrow, idempotent, closed-validation mutation contract. No editor UI.

The flatness rule is executable: a test discovers real fixtures with a genuine
dependency, arranges them four ways including both in one folder and the
dependency inverted in presentation, and asserts discovery order, dependency
declarations, and the module set stay byte-identical. The end-to-end test
organizes a real installation through the real API, mounts a module from inside
a group, moves it, and asserts the navigation entry is byte-identical across the
move and still mounts the same artifact.

The shell's client for the generic inventory became dead code and was removed
rather than kept speculatively; the endpoint itself is unchanged.

Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
2026-08-22 12:44:40 -05:00
co-authored by Claude Opus 5
parent ac5b2b7f6c
commit bd34c9c714
49 changed files with 4866 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files
surfaces/shell/src/browser/HostApp.tsx
+111 -50
View File
@@ -2,6 +2,7 @@ import type { ModuleUiImporter } from "@ekklesia/module-ui-host";
import { type ReactElement, useEffect, useState } from "react";
import {
bootstrapHost,
type DashboardNavigationEntry,
type EkklesiaHostConfig,
type HostBootstrap,
HostProtocolError,
@@ -24,7 +25,14 @@ export interface HostAppProps {
}
const shellStyles = {
aside: { borderRight: "1px solid #e7e5e4", minWidth: "12rem", padding: "1rem" },
aside: { borderRight: "1px solid #e7e5e4", minWidth: "13rem", padding: "1rem" },
groupLabel: {
color: "#78716c",
fontSize: "0.75rem",
letterSpacing: "0.05em",
margin: "0 0 0.25rem",
textTransform: "uppercase",
},
header: {
borderBottom: "1px solid #e7e5e4",
fontWeight: 600,
@@ -42,24 +50,66 @@ const shellStyles = {
message: { color: "#57534e", padding: "1rem" },
} as const;
function moduleKey(id: string, version: string): string {
return `${id}@${version}`;
/** Identity, not placement: a module keeps the same selection key wherever it is arranged, so moving
* it between groups never resets what is open or remounts what is showing. */
function moduleKey(entry: DashboardNavigationEntry): string {
return `${entry.descriptor.id}@${entry.descriptor.version}`;
}
function allEntries(bootstrap: HostBootstrap): readonly DashboardNavigationEntry[] {
return [
...bootstrap.navigation.groups.flatMap((group) => group.modules),
...bootstrap.navigation.ungrouped,
];
}
function ModuleButton(props: {
readonly entry: DashboardNavigationEntry;
readonly selected: boolean;
readonly onSelect: () => void;
}): ReactElement {
return (
<button
aria-current={props.selected ? "page" : undefined}
data-testid={`select-${props.entry.descriptor.id}`}
onClick={props.onSelect}
style={{
background: props.selected ? "#e7e5e4" : "transparent",
border: "none",
borderRadius: "0.25rem",
cursor: "pointer",
font: "inherit",
padding: "0.375rem 0.5rem",
textAlign: "left",
width: "100%",
}}
type="button"
>
{props.entry.name}
</button>
);
}
/**
* The minimal Ekklesia browser shell: sign-in awareness, a module list, and one mount target.
* The Ekklesia browser shell: sign-in awareness, the Dashboard's configured navigation, and one
* mount target.
*
* **This is not the Dashboard.** There is no navigation model, no grouping or folders, no icons, no
* ordering, no home screen, no design system, and no routing — a selected-module state is the whole
* of it, and the selector renders module ids because the inventory deliberately carries no display
* metadata yet (ADR 0021 keeps that an administrator's presentation configuration, not a module
* declaration). What this proves is the architecture underneath: that a module discovered on the
* server, published as an artifact, and described by the inventory can be mounted here without the
* shell knowing anything about it in advance.
* ## The shell renders the arrangement; it never computes one
*
* Nothing about any specific module appears in this file, or anywhere in this package. There is no
* import of a module, no module id, no registry, no allowlist, and no fallback bundle. Every module
* the shell can mount arrives at run time from the inventory the server returned.
* Groups, their order, their labels, which module sits where, and the order within each group all
* arrive already resolved from the server (ADR 0027). This component reads no manifest, performs no
* sorting, and knows nothing about how a placement is decided — so changing the Dashboard's ordering
* rules, or eventually where configuration is scoped, needs no change here at all. The module id is
* never displayed: the module's own manifest name is.
*
* ## Still not the finished Dashboard
*
* There is one level of grouping and no nesting, no icons, no drag and drop, no editor, no home
* screen or widgets, no theme, and no client routing — selection is state. What this proves is the
* layer beneath a Dashboard: persistent, platform-owned presentation configuration driving a real
* host that mounts flat, independent modules.
*
* Nothing about any specific module appears in this file, or anywhere in this package.
*/
export function HostApp(props: HostAppProps): ReactElement {
const [state, setState] = useState<BootstrapState>({ status: "loading" });
@@ -79,11 +129,8 @@ export function HostApp(props: HostAppProps): ReactElement {
? { status: "signed-out" }
: { bootstrap, status: "ready" },
);
setSelectedKey(
bootstrap.modules[0]
? moduleKey(bootstrap.modules[0].id, bootstrap.modules[0].version)
: undefined,
);
const first = allEntries(bootstrap)[0];
setSelectedKey(first ? moduleKey(first) : undefined);
})
.catch((error: unknown) => {
if (abort.signal.aborted) {
@@ -118,54 +165,68 @@ export function HostApp(props: HostAppProps): ReactElement {
}
const { bootstrap } = state;
const selected = bootstrap.modules.find(
(module) => moduleKey(module.id, module.version) === selectedKey,
);
const entries = allEntries(bootstrap);
const selected = entries.find((entry) => moduleKey(entry) === selectedKey);
const { groups, ungrouped } = bootstrap.navigation;
return (
<div style={shellStyles.layout}>
<header style={shellStyles.header}>Ekklesia</header>
<aside style={shellStyles.aside}>
{bootstrap.modules.length === 0 ? (
{entries.length === 0 && groups.length === 0 ? (
<p data-testid="host-empty" style={{ color: "#57534e", margin: 0 }}>
No installed module provides a user interface.
</p>
) : (
<nav style={{ display: "grid", gap: "0.25rem" }}>
{bootstrap.modules.map((module) => {
const key = moduleKey(module.id, module.version);
return (
<button
data-testid={`select-${module.id}`}
key={key}
onClick={() => setSelectedKey(key)}
style={{
background: key === selectedKey ? "#e7e5e4" : "transparent",
border: "none",
cursor: "pointer",
font: "inherit",
padding: "0.375rem 0.5rem",
textAlign: "left",
}}
type="button"
>
{module.id}
</button>
);
})}
<nav aria-label="Modules" style={{ display: "grid", gap: "1rem" }}>
{groups.map((group) => (
// An empty group still renders: an administrator created it, and hiding it would look
// like it had been deleted.
<section data-testid={`group-${group.id}`} key={group.id}>
<h2 style={shellStyles.groupLabel}>{group.label}</h2>
<div style={{ display: "grid", gap: "0.125rem" }}>
{group.modules.map((entry) => (
<ModuleButton
entry={entry}
key={moduleKey(entry)}
onSelect={() => setSelectedKey(moduleKey(entry))}
selected={moduleKey(entry) === selectedKey}
/>
))}
</div>
</section>
))}
{ungrouped.length > 0 ? (
// Where a module lives until someone decides otherwise — including one installed five
// minutes ago. The heading is omitted when nothing is grouped, so an unconfigured
// installation reads as a plain module list rather than a mysterious "Other" bucket.
<section data-testid="group-ungrouped">
{groups.length > 0 ? <h2 style={shellStyles.groupLabel}>Other</h2> : undefined}
<div style={{ display: "grid", gap: "0.125rem" }}>
{ungrouped.map((entry) => (
<ModuleButton
entry={entry}
key={moduleKey(entry)}
onSelect={() => setSelectedKey(moduleKey(entry))}
selected={moduleKey(entry) === selectedKey}
/>
))}
</div>
</section>
) : undefined}
</nav>
)}
</aside>
<main style={shellStyles.main}>
{selected ? (
// Keyed by module identity, so switching selection discards this frame — and its container
// element — entirely rather than reusing one across two modules. See `ModuleUiFrame` for
// why that is what makes a slow, stale load harmless.
// Keyed by module identity — not by group — so switching selection discards this frame and
// its container entirely, while re-grouping a module never remounts it. See
// `ModuleUiFrame` for why that is what makes a slow, stale load harmless.
<ModuleUiFrame
config={config}
descriptor={selected}
descriptor={selected.descriptor}
{...(importModule ? { importModule } : {})}
key={moduleKey(selected.id, selected.version)}
key={moduleKey(selected)}
principal={bootstrap.principal}
/>
) : undefined}