@cosmicdrift/kumiko-renderer 0.374.0 → 0.377.0

package/dist/headless/locale-routing/index.d.ts

@@ -0,0 +1,41 @@
+import type { LocaleResolver } from "../contracts/index.ts";
+export type LocaleRouterConfig<TPage extends string> = {
+    /** Canonical default, usually "de". No URL prefix. */
+    readonly defaultLocale: string;
+    /** Locales that get a URL prefix, e.g. ["en"] → /en/... */
+    readonly prefixedLocales: readonly string[];
+    /** Prefix segment per locale, default: locale code ("en" → "/en"). */
+    readonly prefixFor?: (locale: string) => string;
+    /** Logical page → path per locale. Every page must define defaultLocale path. */
+    readonly routes: Record<TPage, Record<string, string>>;
+    /** Legacy slug-only paths for detectLang/resolvePage, e.g. { en: ["/features"] }. */
+    readonly localeHints?: Readonly<Record<string, readonly string[]>>;
+    /** Fallback page when altLocalePath cannot resolve pathname. Default: "home". */
+    readonly homePage?: TPage;
+};
+export type LocaleRouter<TPage extends string> = {
+    detectLang(pathname: string): string;
+    publicPath(page: TPage, locale: string): string;
+    resolvePage(pathname: string): TPage | undefined;
+    altLocalePath(pathname: string, targetLocale?: string): string;
+    sectionAnchor(page: TPage, locale: string, fragment: string): string;
+};
+export declare function createLocaleRouter<TPage extends string>(config: LocaleRouterConfig<TPage>): LocaleRouter<TPage>;
+export type WrapUrlLocaleResolverOptions = {
+    resolvePage: (pathname: string) => string | undefined;
+    detectLang: (pathname: string) => string;
+    pathname?: () => string | undefined;
+    /** Optional pathname-change subscription. Browser default listens to `popstate` only,
+     *  which does not fire on `history.pushState`/`replaceState`: apps with a client-side
+     *  router must supply this themselves. */
+    subscribePathname?: (listener: () => void) => () => void;
+    /** When set, translate against the URL-resolved locale instead of base.translate
+     *  (needed for fixed-T / cloneInstance resolvers that are not locale-live). */
+    translateFor?: (locale: string, key: string, params?: Readonly<Record<string, unknown>>) => string;
+};
+/**
+ * Prefer URL-derived locale when `resolvePage` matches the current path;
+ * otherwise defer to `base.locale()`. Passes through setLocale and the rest of LocaleResolver.
+ * Without `translateFor`, `base.translate` must already be locale-live.
+ */
+export declare function wrapUrlLocaleResolver(base: LocaleResolver, options: WrapUrlLocaleResolverOptions): LocaleResolver;

package/dist/headless/locale-routing/index.js

@@ -0,0 +1,145 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+function normalizePath(pathname) {
+    if (pathname === "" || pathname === "/")
+        return "/";
+    return pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+}
+function defaultPrefixFor(locale) {
+    return `/${locale}`;
+}
+function stripLocalePrefix(path, locale, prefixFor) {
+    const prefix = prefixFor(locale);
+    if (path === prefix)
+        return "/";
+    if (path.startsWith(`${prefix}/`))
+        return path.slice(prefix.length);
+    return path;
+}
+export function createLocaleRouter(config) {
+    const { defaultLocale, prefixedLocales, routes, localeHints = {}, prefixFor = defaultPrefixFor, homePage = "home", } = config;
+    if (routes[homePage] === undefined) {
+        throw new Error(`locale-routing: homePage "${String(homePage)}" has no entry in routes — altLocalePath's fallback would throw at request time`);
+    }
+    const pathIndex = new Map();
+    for (const [page, localePaths] of Object.entries(routes)) {
+        for (const [locale, routePath] of Object.entries(localePaths)) {
+            pathIndex.set(normalizePath(routePath), { page, locale });
+        }
+    }
+    for (const [hintLocale, hints] of Object.entries(localeHints)) {
+        for (const hint of hints) {
+            const normalizedHint = normalizePath(hint);
+            if (pathIndex.has(normalizedHint))
+                continue;
+            for (const [page, localePaths] of Object.entries(routes)) {
+                const canonical = localePaths[hintLocale];
+                if (canonical === undefined)
+                    continue;
+                const canonicalNorm = normalizePath(canonical);
+                const hintSlug = stripLocalePrefix(normalizedHint, hintLocale, prefixFor);
+                const canonicalSlug = stripLocalePrefix(canonicalNorm, hintLocale, prefixFor);
+                if (hintSlug === canonicalSlug) {
+                    pathIndex.set(normalizedHint, { page, locale: hintLocale });
+                    break;
+                }
+            }
+        }
+    }
+    function detectLang(pathname) {
+        const path = normalizePath(pathname);
+        for (const locale of prefixedLocales) {
+            const prefix = prefixFor(locale);
+            if (path === prefix || path.startsWith(`${prefix}/`))
+                return locale;
+        }
+        const resolved = pathIndex.get(path);
+        if (resolved !== undefined)
+            return resolved.locale;
+        for (const [locale, hints] of Object.entries(localeHints)) {
+            if (hints.some((hint) => normalizePath(hint) === path))
+                return locale;
+        }
+        return defaultLocale;
+    }
+    function resolvePage(pathname) {
+        return pathIndex.get(normalizePath(pathname))?.page;
+    }
+    function publicPath(page, locale) {
+        const localePaths = routes[page];
+        const routePath = localePaths?.[locale];
+        if (localePaths === undefined ||
+            !Object.hasOwn(localePaths, locale) ||
+            routePath === undefined) {
+            throw new Error(`locale-routing: no path for page "${String(page)}" locale "${locale}"`);
+        }
+        return routePath;
+    }
+    function otherLocale(currentLocale) {
+        if (currentLocale === defaultLocale) {
+            return prefixedLocales[0] ?? defaultLocale;
+        }
+        return defaultLocale;
+    }
+    function altLocalePath(pathname, targetLocale) {
+        const path = normalizePath(pathname);
+        const resolved = pathIndex.get(path);
+        const locale = targetLocale ?? otherLocale(detectLang(pathname));
+        if (resolved !== undefined) {
+            return publicPath(resolved.page, locale);
+        }
+        return publicPath(homePage, locale);
+    }
+    function sectionAnchor(page, locale, fragment) {
+        return `${publicPath(page, locale)}#${fragment}`;
+    }
+    return { detectLang, publicPath, resolvePage, altLocalePath, sectionAnchor };
+}
+function defaultBrowserPathname() {
+    const pathname = propertyOf(propertyOf(globalThis, "location"), "pathname");
+    return typeof pathname === "string" ? pathname : undefined;
+}
+function defaultSubscribePathname(listener) {
+    const add = propertyOf(globalThis, "addEventListener");
+    const remove = propertyOf(globalThis, "removeEventListener");
+    if (typeof add !== "function" || typeof remove !== "function") {
+        return () => { };
+    }
+    Reflect.apply(add, globalThis, ["popstate", listener]);
+    return () => {
+        Reflect.apply(remove, globalThis, ["popstate", listener]);
+    };
+}
+/**
+ * Prefer URL-derived locale when `resolvePage` matches the current path;
+ * otherwise defer to `base.locale()`. Passes through setLocale and the rest of LocaleResolver.
+ * Without `translateFor`, `base.translate` must already be locale-live.
+ */
+export function wrapUrlLocaleResolver(base, options) {
+    const getPathname = options.pathname ?? defaultBrowserPathname;
+    const subscribePathname = options.subscribePathname ?? defaultSubscribePathname;
+    const resolveLocale = () => {
+        const path = getPathname();
+        if (path === undefined)
+            return base.locale();
+        if (options.resolvePage(path) != null) {
+            return options.detectLang(path);
+        }
+        return base.locale();
+    };
+    return {
+        translate: (key, params) => options.translateFor
+            ? options.translateFor(resolveLocale(), key, params)
+            : base.translate(key, params),
+        timeZone: () => base.timeZone(),
+        subscribe: (listener) => {
+            const unsubBase = base.subscribe(listener);
+            const unsubPath = subscribePathname(listener);
+            return () => {
+                unsubBase();
+                unsubPath();
+            };
+        },
+        setLocale: base.setLocale !== undefined ? (locale) => base.setLocale?.(locale) : undefined,
+        locale: resolveLocale,
+    };
+}

package/dist/headless/nav/index.d.ts

@@ -0,0 +1,2 @@
+export { resolveNavigation } from "./resolve.ts";
+export type { NavDefinition, NavNode, NavRegistrySlice, NavTree, ResolveNavigationOptions, } from "./types.ts";

package/dist/headless/nav/index.js

@@ -0,0 +1 @@
+export { resolveNavigation } from "./resolve.js";

package/dist/headless/nav/resolve.d.ts

@@ -0,0 +1,2 @@
+import type { NavTree, ResolveNavigationOptions } from "./types.ts";
+export declare function resolveNavigation(options: ResolveNavigationOptions): NavTree;

package/dist/headless/nav/resolve.js

@@ -0,0 +1,71 @@
+import { isUiAccessGranted } from "@cosmicdrift/kumiko-framework/ui-types";
+// Assembles the renderable nav tree from the registry's pre-grouped
+// indexes (topLevel + byParent). Walks top-down: each node is
+// access-checked; a hidden parent drops its entire subtree implicitly
+// because we never recurse into it. Siblings sort by `order` (ascending,
+// default 0), tie-broken by qualified name so renders stay deterministic
+// across registry iteration orders. A pure group (no screen, target,
+// provider or createAction) whose children are all hidden or absent is
+// dropped too.
+//
+// Pure — same inputs produce the same tree. The renderer memoizes the
+// result and only recomputes when the registry changes (rare — boot
+// only) or the user's roles change (logout/login, tenant-switch).
+export function resolveNavigation(options) {
+    const { source, user } = options;
+    function build(entry) {
+        // Shared default-visible UI predicate, not hasAccess from the engine:
+        // that module pulls server-side deps and would break bundle purity.
+        if (!isUiAccessGranted(entry.access, user?.roles))
+            return null;
+        // `entry.id` is already the qualified name — the registry stores
+        // it that way. No reverse-index lookup needed.
+        const children = [];
+        for (const child of source.byParent(entry.id)) {
+            const node = build(child);
+            if (node !== null)
+                children.push(node);
+        }
+        // A pure group (nothing to open itself) with nothing visible below it
+        // would render as an empty, unclickable heading.
+        if (children.length === 0 && isPureGroup(entry))
+            return null;
+        children.sort(bySortKey);
+        return {
+            qualifiedName: entry.id,
+            label: entry.label,
+            order: entry.order ?? 0,
+            children,
+            ...(entry.icon !== undefined && { icon: entry.icon }),
+            ...(entry.screen !== undefined && { screen: entry.screen }),
+            ...(entry.target !== undefined && { target: entry.target }),
+            ...(entry.actions !== undefined && { actions: entry.actions }),
+            ...(entry.createAction !== undefined && { createAction: entry.createAction }),
+            ...(entry.provider !== undefined && { provider: entry.provider }),
+        };
+    }
+    const roots = [];
+    for (const entry of source.topLevel) {
+        const node = build(entry);
+        if (node !== null)
+            roots.push(node);
+    }
+    roots.sort(bySortKey);
+    return roots;
+}
+function isPureGroup(entry) {
+    return (entry.screen === undefined &&
+        entry.target === undefined &&
+        entry.provider === undefined &&
+        entry.actions === undefined &&
+        entry.createAction === undefined);
+}
+function bySortKey(a, b) {
+    // Primary key: `order` ascending. Secondary: qualifiedName alphabetic,
+    // which is a stable fallback — the registry-iteration order isn't
+    // guaranteed across boots, so tied-order entries would otherwise
+    // shuffle between renders.
+    if (a.order !== b.order)
+        return a.order - b.order;
+    return a.qualifiedName.localeCompare(b.qualifiedName);
+}

package/dist/headless/nav/types.d.ts

@@ -0,0 +1,26 @@
+import type { NavDefinition, TargetRef, TreeAction } from "@cosmicdrift/kumiko-framework/ui-types";
+export type NavNode = {
+    readonly qualifiedName: string;
+    readonly label: string;
+    readonly icon?: string;
+    readonly screen?: string;
+    readonly target?: TargetRef;
+    readonly actions?: readonly TreeAction[];
+    readonly createAction?: TreeAction;
+    readonly provider?: boolean;
+    readonly order: number;
+    readonly children: readonly NavNode[];
+};
+export type NavTree = readonly NavNode[];
+export type NavRegistrySlice = {
+    readonly topLevel: readonly NavDefinition[];
+    readonly byParent: (parentQualifiedName: string) => readonly NavDefinition[];
+};
+export type ResolveNavigationOptions = {
+    readonly source: NavRegistrySlice;
+    readonly user?: {
+        readonly id: string;
+        readonly roles: readonly string[];
+    };
+};
+export type { NavDefinition };

package/dist/headless/nav/types.js

@@ -0,0 +1 @@
+export {};

package/dist/headless/store/create-store.d.ts

@@ -0,0 +1,2 @@
+import type { WritableStore } from "./types.ts";
+export declare function createStore<T>(initial: T): WritableStore<T>;

package/dist/headless/store/create-store.js

@@ -0,0 +1,43 @@
+// Subscribe/Emit primitive matching React's useSyncExternalStore.
+// Single canonical implementation — every stateful controller in
+// ui-core/renderer land composes on top of this instead of rolling
+// its own listener-set + notify-loop.
+//
+// Reentrancy semantics use the Set's documented iteration behavior:
+// listeners deleted DURING the notify-loop but BEFORE their turn are
+// skipped; listeners deleting themselves AFTER firing don't break the
+// loop (Set iteration tolerates concurrent mutation of already-visited
+// entries). MDN: "callbackFn is not invoked for values deleted before
+// being visited." This is exactly the contract callers expect.
+//
+// Caveat — Function-valued stores: setState detects the reducer-form via
+// `typeof next === "function"`. If T itself is a function type
+// (`createStore<() => string>(...)`), there is no way to tell a "new
+// value that happens to be a function" apart from a "reducer producing a
+// new function". Same trap React's useState has. Workaround: wrap the
+// new function in a reducer that ignores prev:
+//   store.setState(() => myNewFn);
+// In practice, function-valued stores are rare — feature controllers
+// hold values, not callbacks.
+export function createStore(initial) {
+    let snapshot = initial;
+    const listeners = new Set();
+    return {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setState: (next) => {
+            const nextValue = typeof next === "function" ? next(snapshot) : next;
+            // skip: next value identical to snapshot, avoid notifying listeners
+            if (Object.is(nextValue, snapshot))
+                return;
+            snapshot = nextValue;
+            for (const listener of listeners)
+                listener();
+        },
+    };
+}

package/dist/headless/store/equality.d.ts

@@ -0,0 +1 @@
+export declare function shallowEqual(a: unknown, b: unknown): boolean;

package/dist/headless/store/equality.js

@@ -0,0 +1,34 @@
+// Shallow equality — Object.is on each own enumerable key. The
+// recommended Equality-Arg for useStoreSelector when the selector
+// returns a plain object/array literal (`s => ({ a: s.a, b: s.b })`),
+// which would otherwise produce a fresh reference each render and
+// trip useSyncExternalStore's identity check.
+//
+// Mirrors Zustand's `shallow` and react-redux's `shallowEqual` — same
+//8-line shape, no recursion. Apps that need deep equality reach for
+// their own helper.
+// Signature is `(a: unknown, b: unknown)` not `<T>(a: T, b: T)` because the
+// function legitimately compares cross-type values (primitive vs. object,
+// null vs. {}, etc.) and returns false for mismatches. A generic `<T>`
+// would force callers into type-gymnastics for those cases. Contra-variance
+// ensures this still satisfies `(a: S, b: S) => boolean` slots like
+// useStoreSelector's `equals` arg.
+export function shallowEqual(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (typeof a !== "object" || a === null)
+        return false;
+    if (typeof b !== "object" || b === null)
+        return false;
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (!Object.hasOwn(b, key))
+            return false;
+        if (!Object.is(Reflect.get(a, key), Reflect.get(b, key)))
+            return false;
+    }
+    return true;
+}

package/dist/headless/store/index.d.ts

@@ -0,0 +1,3 @@
+export { createStore } from "./create-store.ts";
+export { shallowEqual } from "./equality.ts";
+export type { Store, WritableStore } from "./types.ts";

package/dist/headless/store/index.js

@@ -0,0 +1,2 @@
+export { createStore } from "./create-store.js";
+export { shallowEqual } from "./equality.js";

package/dist/headless/store/types.d.ts

@@ -0,0 +1,7 @@
+export type Store<T> = {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+};
+export type WritableStore<T> = Store<T> & {
+    setState(next: T | ((prev: T) => T)): void;
+};

package/dist/headless/store/types.js

@@ -0,0 +1,10 @@
+// Store contract — Pull-Style Subscribe/Emit matching React's
+// useSyncExternalStore signature. The single canonical shape for
+// every stateful controller in ui-core/renderer land (form,
+// dispatcher-status, locale, token, nav, lifecycle).
+//
+// Rationale in docs/plans/ui-store.md. Not a new state-management
+// decision — ui-decisions.md already picked Subscribe/Emit; this
+// module just materializes the pattern instead of rolling a new
+// Set<() => void> per controller.
+export {};

package/dist/headless/view-model/edit.d.ts

@@ -0,0 +1,18 @@
+import type { EditRelatedListSection, EntityDefinition, EntityEditScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { EditRelatedListSectionViewModel, EditViewModel, Translate } from "./types.ts";
+export type ComputeEditViewModelInput<TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>> = {
+    readonly screen: EntityEditScreenDefinition;
+    readonly entity: EntityDefinition;
+    readonly values: TValues;
+    readonly translate: Translate;
+    readonly featureName: string;
+    /** Which write the form drives. Applies the screen's `writeExcludedFields`
+     *  for that verb (create hides them, update shows them read-only); omitted
+     *  means no exclusion applies. */
+    readonly mode?: EditFormMode;
+    /** The record being edited; omitted on create. */
+    readonly entityId?: string;
+};
+export type EditFormMode = "create" | "update";
+export declare function computeRelatedListSectionViewModel(sectionSpec: EditRelatedListSection, translate: Translate): EditRelatedListSectionViewModel;
+export declare function computeEditViewModel<TValues extends Readonly<Record<string, unknown>> = Readonly<Record<string, unknown>>>(input: ComputeEditViewModelInput<TValues>): EditViewModel;