@happyvertical/smrt-svelte 0.30.0

package/dist/components/workspace/manifest-nav.js

@@ -0,0 +1,408 @@
+/**
+ * Pure helper that turns a SMRT manifest into the `NavItem[]` shape the
+ * existing `NavTree` / `RoleShell` primitives expect.
+ *
+ * This is the "manifest → admin UI" adapter called out as a friction gap in
+ * happyvertical/smrt#1235 / #1226 / #1248: every consumer hand-writes its nav
+ * config today, with dozens of `@smrt()` classes that boilerplate drifts.
+ * Opt in here to manifest-driven nav while keeping the primitives themselves
+ * SmrtObject-agnostic.
+ *
+ * Design constraints (see #1248 for the full brief):
+ *  - Pure function. No SvelteKit imports, no SSR coupling, no module side
+ *    effects. Data in → data out.
+ *  - Cross-industry-safe. Never assumes apparel / furniture / automotive
+ *    vocabulary; consumers supply their own `sectionHints`.
+ *  - Deterministic output. Sections and items both sort alphabetically by
+ *    title so manifest-order churn doesn't shuffle the rendered nav.
+ *  - Decoupled from any concrete role/permission package. `permittedResources`
+ *    is just a plain string array of qualified class names.
+ *
+ * The structural `SmrtManifestLike` / `SmrtManifestEntryLike` shapes here
+ * intentionally subset the real `SmartObjectManifest` from `@happyvertical/smrt-core`.
+ * Adding a peer dependency on core would create a circular reference (core
+ * pulls in svelte primitives downstream), so the helper accepts anything
+ * that matches the documented shape. Pass a `SmartObjectManifest` directly
+ * and TypeScript is happy.
+ */
+// ────────────────────────────────────────────────────────────────────────
+// Pluralization
+//
+// The brief explicitly says "use a tiny pluralization helper, don't pull
+// in pluralize". This covers the common English suffix rules and is
+// deterministic. Consumers who need exotic plurals override via
+// `decoratorConfig.ui.label`.
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * Minimal English pluralizer. Handles the common suffix rules sufficient
+ * for class-name → label conversion (Article → Articles, Category →
+ * Categories, Box → Boxes, etc.). For irregulars or exotic plurals,
+ * override with `@smrt({ ui: { label: 'Foo bars' } })`.
+ *
+ * Exported only for tests / advanced callers; most code should let
+ * `navTreeFromManifest` apply it.
+ */
+export function pluralizeClassName(name) {
+    if (!name)
+        return name;
+    // Already plural-ish (very rough — "Categories" passes through).
+    if (/(?:[^aeiouy]|qu)ies$/i.test(name))
+        return name;
+    if (/s$/i.test(name) && !/(?:ss|us|is)$/i.test(name))
+        return name;
+    // Words ending in consonant + 'y' → 'ies' (Category → Categories).
+    if (/[^aeiouy]y$/i.test(name)) {
+        return `${name.slice(0, -1)}ies`;
+    }
+    // Words ending in s, x, z, ch, sh → 'es' (Box → Boxes, Dish → Dishes).
+    if (/(?:s|x|z|ch|sh)$/i.test(name)) {
+        return `${name}es`;
+    }
+    return `${name}s`;
+}
+/** Convert a PascalCase class name to a kebab-case URL slug. */
+function classNameToKebab(name) {
+    return name
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1-$2')
+        .toLowerCase();
+}
+// ────────────────────────────────────────────────────────────────────────
+// Filtering — drop collection classes, internal/test visibility, etc.
+// ────────────────────────────────────────────────────────────────────────
+/**
+ * True when an entry represents a `SmrtCollection` subclass rather than a
+ * `SmrtObject`. The manifest captures both — collections appear with
+ * `extends: 'SmrtCollection'` (or any ancestor whose own `extends` chain
+ * eventually hits one), but the nav helper only cares about the SmrtObject
+ * side. Heuristic: `className` ending in `Collection`. This matches the
+ * SMRT convention (`ProductCollection`, `CategoryCollection`) and avoids
+ * needing the full inheritance walk.
+ */
+function looksLikeCollectionClass(entry) {
+    if (entry.className.endsWith('Collection'))
+        return true;
+    if (entry.extends === 'SmrtCollection')
+        return true;
+    return false;
+}
+/**
+ * Whether an entry is publicly visible in the manifest. Classes marked
+ * `@smrt({ visibility: 'internal' })` are package-only and should never
+ * surface in admin nav — they're typically join tables, sync helpers, or
+ * cross-package plumbing. `'test'` fixtures should obviously never leak
+ * either. Default (`undefined` / `'public'`) keeps the entry visible.
+ *
+ * Reads the top-level `visibility` field first (the shape published by
+ * `SmartObjectDefinition`) and falls back to `decoratorConfig.visibility`
+ * for older / hand-built manifests.
+ */
+function isPublicEntry(entry) {
+    const visibility = entry.visibility ?? entry.decoratorConfig?.visibility ?? 'public';
+    return visibility === 'public';
+}
+/**
+ * True when an entry is an STI subtype whose REST route would be the
+ * same as some ancestor's. The SMRT scanner copies the STI parent's
+ * `collection` field onto every child entry — `Material`, `Style`,
+ * `Cart`, `Order`, `ProductionOrder` etc. all carry the parent's
+ * `collection` value (`products`, `contracts`). If we emitted a nav
+ * item per entry, the user would see "Materials" and "Products" both
+ * linking to `/api/v1/products`, with no way to tell which list they
+ * landed on. Suppressing the child entries keeps the base class's
+ * single nav link — the REST endpoint already exposes the full
+ * polymorphic list, which is the conventional shape for STI tables.
+ *
+ * **Walks the ancestor chain.** A two-level hierarchy like
+ * `Product → Material → FabricMaterial` may have its intermediate
+ * `Material` entry stripped from a partial manifest while `Product`
+ * remains. A one-level check would let `FabricMaterial` through
+ * (parent absent → return false → keep) and duplicate the `Product`
+ * link. Walking the chain handles this case: as long as any ancestor
+ * with a matching `collection` is reachable through the chain, the
+ * subtype is suppressed. Fully-orphaned entries (no resolvable
+ * ancestor in the manifest) stay visible — better to show one link
+ * than none.
+ *
+ * Detection: starting at `entry.extends`, look up that className in
+ * the manifest. If found and `collection` matches, suppress this
+ * entry. Otherwise recurse into THAT entry's `extends` and try again.
+ * Stop at `SmrtObject`/`SmrtClass`, when no manifest entry resolves,
+ * or when a cycle is detected.
+ */
+function looksLikeStiSubtypeOfParentRoute(entry, manifest) {
+    const byClassName = entryIndexByClassName(manifest);
+    const visited = new Set();
+    let cursor = entry.extends;
+    while (cursor && cursor !== 'SmrtObject' && cursor !== 'SmrtClass') {
+        if (visited.has(cursor))
+            return false; // pathological cycle
+        visited.add(cursor);
+        const ancestor = byClassName.get(cursor);
+        if (!ancestor)
+            return false; // chain broken, keep this entry visible
+        if (ancestor.collection && ancestor.collection === entry.collection) {
+            return true;
+        }
+        cursor = ancestor.extends;
+    }
+    return false;
+}
+/**
+ * Build a className → entry lookup over the manifest. Memoised per
+ * manifest via WeakMap so a typical `navTreeFromManifest` call only
+ * walks `Object.values(manifest.objects)` once even when many entries
+ * trigger `looksLikeStiSubtypeOfParentRoute`. When two entries share
+ * a className (shouldn't happen in a well-formed manifest), the first
+ * one wins — duplicates would still produce the same dedup answer
+ * because both would carry the same parent chain.
+ */
+const manifestClassNameIndex = new WeakMap();
+function entryIndexByClassName(manifest) {
+    const cached = manifestClassNameIndex.get(manifest);
+    if (cached)
+        return cached;
+    const idx = new Map();
+    for (const e of Object.values(manifest.objects)) {
+        if (!idx.has(e.className))
+            idx.set(e.className, e);
+    }
+    manifestClassNameIndex.set(manifest, idx);
+    return idx;
+}
+/**
+ * Whether an entry exposes a `list` route through the REST generator.
+ *
+ * Join-table / link / asset models commonly declare `@smrt({ api: false })`
+ * because they're plumbing, not catalog. Linking a nav item to them would
+ * 404 — the route literally isn't generated. Conservatively skip those.
+ *
+ * Handles the three shapes `@smrt({ api })` can take:
+ *
+ *   - `undefined` / `true` → default routes (list included)
+ *   - `false` → no routes
+ *   - `{ include: [...] }` → only listed routes
+ *   - `{ exclude: [...] }` → all except listed routes
+ */
+function hasListRoute(entry) {
+    const api = entry.decoratorConfig?.api;
+    if (api === undefined || api === true)
+        return true;
+    if (api === false)
+        return false;
+    if (typeof api !== 'object' || api === null)
+        return true;
+    const obj = api;
+    if (Array.isArray(obj.include)) {
+        return obj.include.includes('list');
+    }
+    if (Array.isArray(obj.exclude)) {
+        return !obj.exclude.includes('list');
+    }
+    return true;
+}
+/**
+ * Derive a section title for an entry. Order of preference:
+ *  1. First `sectionHints` key whose substring appears in the qualified name.
+ *  2. The package suffix between the last `/` and the `:` of the qualified
+ *     name (e.g. `@happyvertical/smrt-content:Article` → `smrt-content`).
+ *  3. The `packageName` field as-is, or `'Resources'` as a final fallback.
+ */
+function deriveSectionTitle(entry, qualifier, sectionHints) {
+    if (sectionHints) {
+        for (const [needle, title] of Object.entries(sectionHints)) {
+            if (qualifier.includes(needle))
+                return title;
+        }
+    }
+    // `@happyvertical/smrt-content:Article` → after last `/`, before `:`.
+    const colonIndex = qualifier.indexOf(':');
+    const beforeColon = colonIndex >= 0 ? qualifier.slice(0, colonIndex) : qualifier;
+    const lastSlash = beforeColon.lastIndexOf('/');
+    if (lastSlash >= 0 && lastSlash < beforeColon.length - 1) {
+        return beforeColon.slice(lastSlash + 1);
+    }
+    return entry.packageName || beforeColon || 'Resources';
+}
+/**
+ * Pick the qualifier string for an entry. Prefers the explicit
+ * `qualifiedName`; falls back to a synthesised `packageName:className`
+ * pair so partial / hand-built manifests still work in tests.
+ */
+function entryQualifier(entry) {
+    if (entry.qualifiedName)
+        return entry.qualifiedName;
+    if (entry.packageName)
+        return `${entry.packageName}:${entry.className}`;
+    return entry.className;
+}
+/**
+ * Expand a permitted-qualifiers set so it includes the parent
+ * qualifier of every STI subtype that shares its parent's `collection`
+ * value. Without this expansion, a role permitted to access an STI
+ * subtype (e.g. `Cart`) would lose its nav link, because the dedup
+ * step suppresses subtypes that share the parent's REST route and
+ * the permission filter would then drop the parent. The expansion
+ * threads through the inheritance chain (handles multi-level STI)
+ * with a visited-set cycle guard.
+ *
+ * Pure: returns a new Set; never mutates the caller's set. The
+ * className index is the same memoised one used by
+ * `looksLikeStiSubtypeOfParentRoute`.
+ */
+function expandPermittedThroughStiParents(permitted, manifest) {
+    const byClassName = entryIndexByClassName(manifest);
+    // Also need to resolve qualifier → entry, because permitted set
+    // entries are qualified names (`@pkg/x:Class`), not raw classNames.
+    const byQualifier = new Map();
+    for (const entry of Object.values(manifest.objects)) {
+        byQualifier.set(entryQualifier(entry), entry);
+    }
+    const expanded = new Set(permitted);
+    for (const qualifier of permitted) {
+        const entry = byQualifier.get(qualifier);
+        if (!entry)
+            continue;
+        const visited = new Set();
+        let cursor = entry.extends;
+        let lastSeenCollection = entry.collection;
+        while (cursor && cursor !== 'SmrtObject' && cursor !== 'SmrtClass') {
+            if (visited.has(cursor))
+                break;
+            visited.add(cursor);
+            const ancestor = byClassName.get(cursor);
+            if (!ancestor)
+                break;
+            if (ancestor.collection && ancestor.collection === lastSeenCollection) {
+                expanded.add(entryQualifier(ancestor));
+            }
+            lastSeenCollection = ancestor.collection ?? lastSeenCollection;
+            cursor = ancestor.extends;
+        }
+    }
+    return expanded;
+}
+/**
+ * Walk a SMRT manifest and emit the `NavSection[]` shape that
+ * `<NavTree items={...}>` and `RoleConfig.sections` consume.
+ *
+ * Algorithm:
+ *   1. Drop collection classes (`*Collection` / `extends: 'SmrtCollection'`).
+ *   2. Drop entries marked `@smrt({ visibility: 'internal' | 'test' })` —
+ *      they're plumbing / fixtures and never belong in admin nav.
+ *   3. Drop entries that don't expose a REST `list` route (`@smrt({ api: false })`,
+ *      `include` without `list`, or `exclude` containing `list`).
+ *   4. Drop STI subtypes that share their parent's `collection` value —
+ *      the REST endpoint at the shared collection URL is polymorphic and
+ *      shows all subtypes through one link.
+ *   5. If `permittedResources` is provided, drop entries whose qualified
+ *      name isn't in the list. Otherwise keep all remaining entries.
+ *   6. Group remaining entries by their resolved section title.
+ *   4. For each entry, emit a `NavItem` with:
+ *       - `label` = `decoratorConfig.ui.label` ?? `pluralizeClassName(className)`
+ *       - `href`  = `${basePath}/${collection}` (defaults to `/api/v1/{collection}`)
+ *                   falling back to `${basePath}/{kebab-case-class}` if the
+ *                   manifest entry omits `collection`.
+ *       - `icon`  = `decoratorConfig.ui.icon` if present.
+ *   5. Sort items inside each section by label, then sort sections by title.
+ *      The result is fully deterministic given a manifest input.
+ *
+ * @example Plug into RoleShell
+ * ```ts
+ * import { manifest } from '@my-app/manifest';
+ * import { navTreeFromManifest } from '@happyvertical/smrt-svelte/workspace';
+ *
+ * const sections = navTreeFromManifest(manifest, {
+ *   sectionHints: {
+ *     '@happyvertical/smrt-content': 'Content',
+ *     '@happyvertical/smrt-commerce': 'Commerce',
+ *   },
+ * });
+ * const roles: RoleConfig[] = [
+ *   { id: 'admin', label: 'Admin', sections },
+ * ];
+ * ```
+ *
+ * @example Per-role filtering
+ * ```ts
+ * const editor = navTreeFromManifest(manifest, {
+ *   permittedResources: [
+ *     '@happyvertical/smrt-content:Article',
+ *     '@happyvertical/smrt-content:Document',
+ *   ],
+ * });
+ * // editor: [{ label: 'Content', children: [Articles, Documents] }]
+ * ```
+ *
+ * @example Unprefixed hrefs
+ * ```ts
+ * const sections = navTreeFromManifest(manifest, { basePath: '' });
+ * // items[0].href === '/articles' (not '/api/v1/articles')
+ * ```
+ */
+export function navTreeFromManifest(manifest, options = {}) {
+    const { permittedResources, sectionHints, basePath = '/api/v1' } = options;
+    // Build the *effective* permitted set. When the caller permits a
+    // role to access an STI subtype (e.g. `@acme/shop:Cart`) but not
+    // its base (`Contract`), the role still needs the base's nav link
+    // because every STI subtype routes through the parent's shared
+    // collection URL. Walk each permitted qualifier up the inheritance
+    // chain — if any ancestor in the same manifest carries the same
+    // `collection` value, that ancestor is the actual link target, so
+    // add its qualifier to the permitted set. Without this remap the
+    // dedup step below would drop the subtype, the original permission
+    // check would drop the base, and the role would lose every link to
+    // the shared route.
+    const permitted = permittedResources
+        ? expandPermittedThroughStiParents(new Set(permittedResources), manifest)
+        : undefined;
+    // Group items by their resolved section title. Map preserves insertion
+    // order, but we sort the final output anyway so callers don't have to
+    // care about it.
+    const sectionMap = new Map();
+    for (const entry of Object.values(manifest.objects)) {
+        if (looksLikeCollectionClass(entry))
+            continue;
+        if (!isPublicEntry(entry))
+            continue;
+        if (!hasListRoute(entry))
+            continue;
+        if (looksLikeStiSubtypeOfParentRoute(entry, manifest))
+            continue;
+        const qualifier = entryQualifier(entry);
+        if (permitted && !permitted.has(qualifier))
+            continue;
+        const ui = entry.decoratorConfig?.ui;
+        const label = ui?.label ?? pluralizeClassName(entry.className);
+        const slug = entry.collection ?? classNameToKebab(entry.className);
+        const href = `${basePath}/${slug}`;
+        const item = {
+            href,
+            label,
+        };
+        if (ui?.icon)
+            item.icon = ui.icon;
+        const sectionTitle = deriveSectionTitle(entry, qualifier, sectionHints);
+        const bucket = sectionMap.get(sectionTitle);
+        if (bucket) {
+            bucket.push(item);
+        }
+        else {
+            sectionMap.set(sectionTitle, [item]);
+        }
+    }
+    // Deterministic ordering: sort items inside each section by label, then
+    // sort sections by title. Using `localeCompare` for predictable
+    // cross-locale behaviour without surprises around case.
+    const sections = [];
+    for (const [title, items] of sectionMap) {
+        items.sort((a, b) => a.label.localeCompare(b.label));
+        sections.push({
+            href: `#${title.toLowerCase().replace(/\s+/g, '-')}`,
+            label: title,
+            children: items,
+        });
+    }
+    sections.sort((a, b) => a.label.localeCompare(b.label));
+    return sections;
+}

package/dist/components/workspace/nav-helpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure helpers for nav state derivation.
+ *
+ * Extracted so the recursive active/expanded logic can be unit-tested
+ * without needing to mount Svelte components.
+ *
+ * No DOM, no Svelte runes, no SvelteKit imports — these are SSR-safe and
+ * deterministic given their inputs.
+ */
+import type { NavItem } from './types.js';
+/**
+ * Default activeness check for a nav item against a current path.
+ *
+ * - Exact match → active
+ * - `item.exact === true` → only exact match counts
+ * - `item.href === '/'` → only matches `currentPath === '/'`; otherwise
+ *   the descendant-path fallback would degrade to `startsWith('//')`
+ *   and never fire (and we don't want every path counting the root as
+ *   active by ancestry).
+ * - Otherwise, active when `currentPath` starts with `item.href + '/'`
+ *   (the trailing slash avoids `/foo` matching `/foobar`).
+ */
+export declare function defaultIsActive(item: NavItem, currentPath: string): boolean;
+/**
+ * True if the item or any descendant is active under `isActive`.
+ */
+export declare function isItemOrChildActive(item: NavItem, currentPath: string, isActive?: (item: NavItem, currentPath: string) => boolean): boolean;
+/**
+ * True when an item's children container should render as expanded.
+ *
+ * Children are expanded when:
+ *  - the item has children, AND
+ *  - one of its descendants is active, OR `item.defaultExpanded` is set.
+ */
+export declare function isExpanded(item: NavItem, currentPath: string, isActive?: (item: NavItem, currentPath: string) => boolean): boolean;
+//# sourceMappingURL=nav-helpers.d.ts.map

package/dist/components/workspace/nav-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nav-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/workspace/nav-helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAO3E;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,OAAyB,GAC1E,OAAO,CAQT;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,OAAO,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,GAAE,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,KAAK,OAAyB,GAC1E,OAAO,CAIT"}

package/dist/components/workspace/nav-helpers.js

@@ -0,0 +1,60 @@
+/**
+ * Pure helpers for nav state derivation.
+ *
+ * Extracted so the recursive active/expanded logic can be unit-tested
+ * without needing to mount Svelte components.
+ *
+ * No DOM, no Svelte runes, no SvelteKit imports — these are SSR-safe and
+ * deterministic given their inputs.
+ */
+/**
+ * Default activeness check for a nav item against a current path.
+ *
+ * - Exact match → active
+ * - `item.exact === true` → only exact match counts
+ * - `item.href === '/'` → only matches `currentPath === '/'`; otherwise
+ *   the descendant-path fallback would degrade to `startsWith('//')`
+ *   and never fire (and we don't want every path counting the root as
+ *   active by ancestry).
+ * - Otherwise, active when `currentPath` starts with `item.href + '/'`
+ *   (the trailing slash avoids `/foo` matching `/foobar`).
+ */
+export function defaultIsActive(item, currentPath) {
+    if (item.href === currentPath)
+        return true;
+    if (item.exact)
+        return false;
+    // The root href would produce `startsWith('//')`, which never matches a
+    // real path. Treat root as exact-only when not flagged with `exact`.
+    if (item.href === '/')
+        return false;
+    return currentPath.startsWith(`${item.href}/`);
+}
+/**
+ * True if the item or any descendant is active under `isActive`.
+ */
+export function isItemOrChildActive(item, currentPath, isActive = defaultIsActive) {
+    if (isActive(item, currentPath))
+        return true;
+    if (item.children) {
+        for (const child of item.children) {
+            if (isItemOrChildActive(child, currentPath, isActive))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * True when an item's children container should render as expanded.
+ *
+ * Children are expanded when:
+ *  - the item has children, AND
+ *  - one of its descendants is active, OR `item.defaultExpanded` is set.
+ */
+export function isExpanded(item, currentPath, isActive = defaultIsActive) {
+    if (!item.children?.length)
+        return false;
+    if (item.defaultExpanded)
+        return true;
+    return isItemOrChildActive(item, currentPath, isActive);
+}