@swimmesberger/elarion-contributions 0.0.0

package/README.md

@@ -0,0 +1,111 @@
+# @swimmesberger/elarion-contributions
+
+The [Elarion](https://github.com/swimmesberger/Elarion) **frontend contribution model**
+([ADR-0032](https://github.com/swimmesberger/Elarion/blob/main/docs/decisions/0032-frontend-contribution-model.md)):
+typed extension-point tokens, declarative module manifests, and capability-gated, deterministic resolution.
+It extends the backend's review-isolation rule — *a module only touches its own code* — to the frontend:
+adding a sidebar item or a cross-module action edits one file in the owning module, never the shell.
+
+- **Framework-free core** (`@swimmesberger/elarion-contributions`) — no dependencies, no React.
+- **React bindings** (`@swimmesberger/elarion-contributions/react`) — `ContributionProvider`,
+  `useContributions`, `<ExtensionSlot>`. React is an optional peer dependency; other view frameworks
+  can port the bindings in a page of code.
+- **TanStack Router guard** (`@swimmesberger/elarion-contributions/tanstack-router`) —
+  `redirectUnless(when, to)` + the vocabulary-bound `createRouteGuards<V>()`: a `beforeLoad` guard
+  evaluating the same `when` clause as a contribution, so a route and its nav entry can never gate
+  differently. `@tanstack/react-router` is an optional peer; everything else routing-related stays
+  the router's own API.
+
+```bash
+npm install @swimmesberger/elarion-contributions
+```
+
+## What you import vs. what you own
+
+This package ships the *machinery* with fixed semantics; your application owns the *points* and the shell
+(Elarion deliberately ships no UI kit and no router integration):
+
+| You import (fixed semantics) | You own (copy from the sample) |
+| --- | --- |
+| `defineExtensionPoint`, `defineModule`, `contribute` | Your extension points (`sidebarItems`, …) and their payload types |
+| `evaluateWhen` + the `when` AND semantics | The kit instantiation binding your generated vocabulary |
+| `createContributionRegistry` (filter + deterministic order) | The app shell that renders each slot |
+| `ContributionProvider` / `useContributions` / `<ExtensionSlot>` | Route composition and module discovery (e.g. `import.meta.glob`) |
+| `redirectUnless` route guard (`/tanstack-router`) | Everything else routing — the router's own API |
+
+## Quick start
+
+Bind the kernel once to your generated capability vocabulary (from the Elarion client generator's
+`session-client.ts`), so `when` clauses are compile-checked against the catalog the backend enforces:
+
+```ts
+// platform/contributions.ts — the app's one kit
+import { createContributionKit, type ModuleManifest } from "@swimmesberger/elarion-contributions"
+import type { FlagName, ModuleName, PermissionName, RoleName } from "./generated/session-client"
+
+export interface AppVocabulary {
+  module: ModuleName
+  permission: PermissionName
+  flag: FlagName
+  role: RoleName
+}
+export type AppManifest = ModuleManifest<AppVocabulary>
+export const { defineModule, defineExtensionPoint, contribute } = createContributionKit<AppVocabulary>()
+```
+
+Declare a point where the *owner* of the slot lives (the shell for a sidebar, a module for its own
+extension surface), and export the token from the owner's public entry. The payload shape is yours —
+whatever your shell needs to render:
+
+```ts
+// platform/points.ts
+export interface SidebarItem { readonly label: string; readonly icon: LucideIcon; readonly to: string }
+export const sidebarItems = defineExtensionPoint<SidebarItem>("platform.sidebar")
+```
+
+Modules contribute through their manifest — plain data plus lazy component references, never import-time
+registration:
+
+```ts
+// modules/invoicing/module.tsx
+export const invoicingManifest = defineModule({
+  name: Modules.Invoicing,
+  when: { module: Modules.Invoicing },   // module-level gate, ANDed into every contribution
+  contributes: [
+    contribute(sidebarItems, [{
+      id: "invoices", label: "Invoices", to: "/invoices", order: 20,
+      when: { permission: Permissions.invoices.read },
+    }]),
+  ],
+})
+```
+
+The composition root resolves once per capability snapshot and hands the registry to React:
+
+```tsx
+import { createContributionRegistry } from "@swimmesberger/elarion-contributions"
+import { ContributionProvider, useContributions } from "@swimmesberger/elarion-contributions/react"
+
+const registry = createContributionRegistry(appModules.map((m) => m.manifest), capabilities)
+// <ContributionProvider registry={registry}> … </ContributionProvider>
+
+// anywhere in the shell:
+const items = useContributions(sidebarItems)
+```
+
+## Semantics (the part that must not drift)
+
+- **`when` is AND** across its fields (`module`, `permission`, `flag`, `role`), mirroring
+  `[RequirePermission]`/`[RequireRole]`/`[FeatureGate]`; a manifest-level `when` is ANDed into every
+  contribution. Absent capabilities fail closed.
+- **Resolution is pure and deterministic**: contributions sort by `order` (default 0), then `id`, then
+  contributing module name, using code-unit comparison — the same input renders the same UI on server
+  and client. Refreshing the snapshot means building a new registry.
+- **UX projection, never security.** A hidden contribution is not a secured operation — the backend
+  handler's own gates are the enforcement on every call.
+
+## Reference usage
+
+The [Billing sample](https://github.com/swimmesberger/Elarion/tree/main/samples/Billing/web) is the
+living reference: module folders, a shell-owned sidebar point, a cross-module row-action point with a
+lazily-chunked contributed dialog, and TanStack Router route subtrees composed per module.

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The capability vocabulary a contribution kit is typed against — supplied by the application from the
+ * generated literal unions in `session-client.ts` (ModuleName/PermissionName/FlagName/RoleName).
+ */
+export interface Vocabulary {
+    module: string;
+    permission: string;
+    flag: string;
+    role: string;
+}
+/** Keeps literal-union autocomplete while accepting out-of-vocabulary names (the generated accessors' shape). */
+type Hint<T extends string> = T | (string & {});
+/**
+ * The declarative visibility condition of a contribution — the frontend mirror of
+ * `[RequirePermission]`/`[RequireRole]`/`[FeatureGate]`: every present field must hold (AND).
+ */
+export interface WhenClause<V extends Vocabulary = Vocabulary> {
+    readonly module?: Hint<V["module"]>;
+    readonly permission?: Hint<V["permission"]>;
+    readonly flag?: Hint<V["flag"]>;
+    readonly role?: Hint<V["role"]>;
+}
+/**
+ * The snapshot surface resolution reads — structurally satisfied by the `SessionCapabilities` class the
+ * Elarion client generator emits, so this package never depends on generated code.
+ */
+export interface CapabilityReader {
+    isModuleEnabled(name: string): boolean;
+    hasPermission(permission: string): boolean;
+    hasRole(role: string): boolean;
+    isFlagEnabled(name: string): boolean;
+}
+export declare function evaluateWhen(when: WhenClause | undefined, capabilities: CapabilityReader): boolean;
+declare const CONTRIBUTION: unique symbol;
+declare const SLOT_CONTEXT: unique symbol;
+/**
+ * A typed extension-point token. Exporting one from a module's public entry is the frontend
+ * [ModuleContract]: contributors import the token — an explicit, compile-checked, correctly-directed
+ * dependency — without pulling the owning module's components into their chunk, because the token is data.
+ *
+ * `TItem` is the payload the point accepts; `TContext` documents what a slot site supplies to the payload's
+ * callbacks or components (`void` for context-free slots like a sidebar).
+ */
+export interface ExtensionPoint<TItem, TContext = void> {
+    /** Globally unique, stable id — convention `{owner}.{point}`, e.g. `"clients.rowActions"`. */
+    readonly id: string;
+    /** Phantom type markers only — nothing is ever stored under these keys. */
+    readonly [CONTRIBUTION]?: TItem;
+    readonly [SLOT_CONTEXT]?: TContext;
+}
+export declare function defineExtensionPoint<TItem, TContext = void>(id: string): ExtensionPoint<TItem, TContext>;
+/** A single contribution: the point's payload plus identity, ordering, and visibility. */
+export type Contribution<TItem, V extends Vocabulary = Vocabulary> = TItem & {
+    /** Unique within the point across all modules; part of the deterministic sort key. */
+    readonly id: string;
+    /** Ascending sort rank (default 0); ties break by id, then by contributing module name. */
+    readonly order?: number;
+    /** Visibility condition, ANDed with the contributing module's manifest-level `when`. */
+    readonly when?: WhenClause<V>;
+};
+/** One manifest entry: a point token and the items contributed to it. Built with {@link contribute}. */
+export interface ContributionBatch<V extends Vocabulary = Vocabulary> {
+    readonly point: ExtensionPoint<unknown, unknown>;
+    readonly items: ReadonlyArray<Contribution<unknown, V>>;
+}
+/** Types a batch against its point: the items must match the point's declared payload. */
+export declare function contribute<TItem, TContext, V extends Vocabulary = Vocabulary>(point: ExtensionPoint<TItem, TContext>, items: ReadonlyArray<Contribution<TItem, V>>): ContributionBatch<V>;
+/**
+ * A frontend module's manifest: plain data plus lazy references — the whole surface the composition root
+ * sees. Manifests are inspectable without executing module code and testable as plain arrays (the reason
+ * VS Code moved contributions into static `package.json` data).
+ */
+export interface ModuleManifest<V extends Vocabulary = Vocabulary> {
+    /** The module's name — its backend [AppModule] name when it mirrors one, any unique name when UI-only. */
+    readonly name: Hint<V["module"]>;
+    /**
+     * Module-level visibility, ANDed into every contribution. A backend-paired module gates itself here once
+     * — `when: { module: Modules.X }` — so disabling the backend module removes the whole frontend module;
+     * a UI-only module omits it.
+     */
+    readonly when?: WhenClause<V>;
+    readonly contributes: ReadonlyArray<ContributionBatch<V>>;
+}
+export declare function defineModule<V extends Vocabulary = Vocabulary>(manifest: ModuleManifest<V>): ModuleManifest<V>;
+/** The resolved, filtered, deterministically ordered view of every manifest against one snapshot. */
+export interface ContributionRegistry {
+    get<TItem, TContext>(point: ExtensionPoint<TItem, TContext>): ReadonlyArray<Contribution<TItem>>;
+}
+/**
+ * Resolves manifests against a capability snapshot. Resolution is eager and pure — the same
+ * (manifests, capabilities) input yields the same registry, so a server render and the client hydration
+ * produce identical trees. Refreshing the snapshot (login, context change) means building a new registry,
+ * the same contract as the generated session provider.
+ */
+export declare function createContributionRegistry(manifests: ReadonlyArray<ModuleManifest>, capabilities: CapabilityReader): ContributionRegistry;
+/** The vocabulary-bound facade of the kernel — created once by the application, imported by every module. */
+export interface ContributionKit<V extends Vocabulary> {
+    defineModule(manifest: ModuleManifest<V>): ModuleManifest<V>;
+    defineExtensionPoint<TItem, TContext = void>(id: string): ExtensionPoint<TItem, TContext>;
+    contribute<TItem, TContext>(point: ExtensionPoint<TItem, TContext>, items: ReadonlyArray<Contribution<TItem, V>>): ContributionBatch<V>;
+}
+/**
+ * Binds the kernel to an application's capability vocabulary (the generated literal unions), so every
+ * `when` clause is compile-checked against the same catalog the backend enforces — a typo'd permission is
+ * a type error, not a silently hidden item. Purely a typing layer with zero runtime cost.
+ */
+export declare function createContributionKit<V extends Vocabulary>(): ContributionKit<V>;
+export {};

package/dist/index.js

@@ -0,0 +1,89 @@
+// The contribution kernel of the Elarion frontend module system (ADR-0032): typed extension-point tokens,
+// declarative module manifests, and a snapshot-pure resolution step. Framework-free — the React bindings
+// live in the `/react` sub-export, and porting them to another view framework is a page of code.
+//
+// Semantics in one paragraph: a module ships a manifest (plain data plus lazy component references — never
+// import-time `register()` calls, which are import-order-dependent, side-effectful, and invisible to
+// tree-shaking); an extension point is a typed token whose export from a module's public entry is the
+// frontend [ModuleContract]; resolution filters every contribution by its `when` clause (ANDed with the
+// owning manifest's module-level `when`) against the capability snapshot and sorts deterministically, so
+// the same input always renders the same UI on server and client. `when` is a UX projection, never
+// security — the backend's [RequirePermission]/[FeatureGate] remain the enforcement on every call.
+export function evaluateWhen(when, capabilities) {
+    if (when === undefined)
+        return true;
+    if (when.module !== undefined && !capabilities.isModuleEnabled(when.module))
+        return false;
+    if (when.permission !== undefined && !capabilities.hasPermission(when.permission))
+        return false;
+    if (when.role !== undefined && !capabilities.hasRole(when.role))
+        return false;
+    if (when.flag !== undefined && !capabilities.isFlagEnabled(when.flag))
+        return false;
+    return true;
+}
+export function defineExtensionPoint(id) {
+    return { id };
+}
+/** Types a batch against its point: the items must match the point's declared payload. */
+export function contribute(point, items) {
+    return { point, items };
+}
+export function defineModule(manifest) {
+    return manifest;
+}
+// Code-unit string comparison — localeCompare would make the resolved order environment-dependent.
+function compareStrings(a, b) {
+    if (a < b)
+        return -1;
+    if (a > b)
+        return 1;
+    return 0;
+}
+const EMPTY = [];
+/**
+ * Resolves manifests against a capability snapshot. Resolution is eager and pure — the same
+ * (manifests, capabilities) input yields the same registry, so a server render and the client hydration
+ * produce identical trees. Refreshing the snapshot (login, context change) means building a new registry,
+ * the same contract as the generated session provider.
+ */
+export function createContributionRegistry(manifests, capabilities) {
+    const byPoint = new Map();
+    for (const manifest of manifests) {
+        if (!evaluateWhen(manifest.when, capabilities))
+            continue;
+        for (const batch of manifest.contributes) {
+            for (const item of batch.items) {
+                if (!evaluateWhen(item.when, capabilities))
+                    continue;
+                const entries = byPoint.get(batch.point.id);
+                if (entries === undefined) {
+                    byPoint.set(batch.point.id, [{ item, module: manifest.name }]);
+                }
+                else {
+                    entries.push({ item, module: manifest.name });
+                }
+            }
+        }
+    }
+    const resolved = new Map();
+    for (const [pointId, entries] of byPoint) {
+        entries.sort((a, b) => (a.item.order ?? 0) - (b.item.order ?? 0) ||
+            compareStrings(a.item.id, b.item.id) ||
+            compareStrings(a.module, b.module));
+        resolved.set(pointId, entries.map((entry) => entry.item));
+    }
+    return {
+        get(point) {
+            return (resolved.get(point.id) ?? EMPTY);
+        },
+    };
+}
+/**
+ * Binds the kernel to an application's capability vocabulary (the generated literal unions), so every
+ * `when` clause is compile-checked against the same catalog the backend enforces — a typo'd permission is
+ * a type error, not a silently hidden item. Purely a typing layer with zero runtime cost.
+ */
+export function createContributionKit() {
+    return { defineModule, defineExtensionPoint, contribute };
+}

package/dist/react.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from "react";
+import type { Contribution, ContributionRegistry, ExtensionPoint } from "./index.js";
+export declare function ContributionProvider({ registry, children, }: {
+    registry: ContributionRegistry;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The resolved contributions for a point — already filtered by `when` and deterministically ordered. */
+export declare function useContributions<TItem, TContext>(point: ExtensionPoint<TItem, TContext>): ReadonlyArray<Contribution<TItem>>;
+/** Renders a point's contributions through a render prop — sugar over {@link useContributions} for inline slots. */
+export declare function ExtensionSlot<TItem, TContext>({ point, render, }: {
+    point: ExtensionPoint<TItem, TContext>;
+    render: (item: Contribution<TItem>) => ReactNode;
+}): import("react").JSX.Element;

package/dist/react.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+// React bindings over the contribution kernel — the thin `/react` adapter of ADR-0032 (the same split as
+// Elarion.Abstractions ↔ Elarion.AspNetCore): one provider, one hook, one slot component. Everything
+// interesting happens in the framework-free core; this file only surfaces the resolved registry through
+// React context, so porting it to another view framework is a page of code, not a redesign.
+import { createContext, Fragment, useContext } from "react";
+const RegistryContext = createContext(null);
+export function ContributionProvider({ registry, children, }) {
+    return _jsx(RegistryContext.Provider, { value: registry, children: children });
+}
+/** The resolved contributions for a point — already filtered by `when` and deterministically ordered. */
+export function useContributions(point) {
+    const registry = useContext(RegistryContext);
+    if (registry === null)
+        throw new Error("useContributions requires a <ContributionProvider> above it.");
+    return registry.get(point);
+}
+/** Renders a point's contributions through a render prop — sugar over {@link useContributions} for inline slots. */
+export function ExtensionSlot({ point, render, }) {
+    const items = useContributions(point);
+    return (_jsx(_Fragment, { children: items.map((item) => (_jsx(Fragment, { children: render(item) }, item.id))) }));
+}

package/dist/tanstack-router.d.ts

@@ -0,0 +1,28 @@
+import { type CapabilityReader, type Vocabulary, type WhenClause } from "./index.js";
+/** The router-context shape the guard reads — the app's router context carries the capability snapshot. */
+export interface GuardContext {
+    readonly context: {
+        readonly caps: CapabilityReader;
+    };
+}
+/**
+ * A `beforeLoad` guard: redirects to `to` unless the `when` clause holds against the capability snapshot
+ * in the router context — the route-level mirror of a contribution's `when`, so a deep link into a hidden
+ * module bounces instead of rendering. UX only: the handlers behind the route still enforce their own
+ * `[RequirePermission]`/`[FeatureGate]` on every call.
+ *
+ * @example
+ * ```ts
+ * createRoute({ path: "/invoices", beforeLoad: redirectUnless({ module: "Invoicing" }, "/"), … })
+ * ```
+ */
+export declare function redirectUnless<V extends Vocabulary = Vocabulary>(when: WhenClause<V>, to: string): (opts: GuardContext) => void;
+/** The vocabulary-bound guard factory — the router-side sibling of `createContributionKit`. */
+export interface RouteGuards<V extends Vocabulary> {
+    redirectUnless(when: WhenClause<V>, to: string): (opts: GuardContext) => void;
+}
+/**
+ * Binds the route guards to an application's capability vocabulary, so a route's `when` clause is
+ * compile-checked against the same generated literal unions as a manifest's. Purely a typing layer.
+ */
+export declare function createRouteGuards<V extends Vocabulary>(): RouteGuards<V>;

package/dist/tanstack-router.js

@@ -0,0 +1,32 @@
+// TanStack Router adapter — deliberately a single semantic helper, not routing machinery (an ADR-0032
+// non-goal): routes stay module-owned TanStack subtrees composed with the router's own API. What the
+// framework owns is the `when` clause, and a route guard must evaluate it with exactly the slot-filter
+// semantics (AND, fail-closed) — this sub-export exists so that never drifts. The guard takes the same
+// `when` object a sidebar item declares, so "this page and its nav entry gate identically" is one literal.
+import { redirect } from "@tanstack/react-router";
+import { evaluateWhen } from "./index.js";
+/**
+ * A `beforeLoad` guard: redirects to `to` unless the `when` clause holds against the capability snapshot
+ * in the router context — the route-level mirror of a contribution's `when`, so a deep link into a hidden
+ * module bounces instead of rendering. UX only: the handlers behind the route still enforce their own
+ * `[RequirePermission]`/`[FeatureGate]` on every call.
+ *
+ * @example
+ * ```ts
+ * createRoute({ path: "/invoices", beforeLoad: redirectUnless({ module: "Invoicing" }, "/"), … })
+ * ```
+ */
+export function redirectUnless(when, to) {
+    return ({ context }) => {
+        if (!evaluateWhen(when, context.caps)) {
+            throw redirect({ to });
+        }
+    };
+}
+/**
+ * Binds the route guards to an application's capability vocabulary, so a route's `when` clause is
+ * compile-checked against the same generated literal unions as a manifest's. Purely a typing layer.
+ */
+export function createRouteGuards() {
+    return { redirectUnless };
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@swimmesberger/elarion-contributions",
+  "version": "0.0.0",
+  "description": "The Elarion frontend contribution model: typed extension points, declarative module manifests, and capability-gated resolution — framework-free core with React bindings under /react.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./tanstack-router": {
+      "types": "./dist/tanstack-router.d.ts",
+      "import": "./dist/tanstack-router.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build",
+    "prepare": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/swimmesberger/Elarion.git",
+    "directory": "src/elarion-contributions"
+  },
+  "bugs": {
+    "url": "https://github.com/swimmesberger/Elarion/issues"
+  },
+  "homepage": "https://github.com/swimmesberger/Elarion#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.11"
+  },
+  "peerDependencies": {
+    "@tanstack/react-router": ">=1",
+    "react": ">=18"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "@tanstack/react-router": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-router": "^1.170.17",
+    "@types/react": "^19.2.17",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}