@happyvertical/smrt-svelte 0.30.0

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

@@ -0,0 +1,88 @@
+/**
+ * Pure helpers for breadcrumb derivation.
+ *
+ * Extracted so the path-walking logic can be unit-tested without rendering
+ * a Svelte component.
+ */
+/**
+ * Walk a nav tree depth-first and return the label of the item whose
+ * `href` matches exactly, or `null` if not found.
+ */
+export function findLabelInNav(items, href) {
+    for (const item of items) {
+        if (item.href === href)
+            return item.label;
+        if (item.children?.length) {
+            const label = findLabelInNav(item.children, href);
+            if (label)
+                return label;
+        }
+    }
+    return null;
+}
+/**
+ * Default label fallback for unknown segments: capitalize the first letter
+ * and turn dashes/underscores into spaces.
+ */
+export function capitalizeSegment(segment) {
+    if (!segment)
+        return segment;
+    const cleaned = segment.replace(/[-_]/g, ' ');
+    return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+/**
+ * Derive a breadcrumb trail from a pathname + nav tree.
+ *
+ * Strategy:
+ *  1. Optionally prepend `rootCrumb`.
+ *  2. Split the pathname into segments.
+ *  3. If `startAfter` is set, locate its trailing segment in the
+ *     pathname and skip everything before/including it. The
+ *     `startAfter` value may include a leading slash or none and
+ *     may be a multi-segment path (e.g. `sites/foo`).
+ *  4. Walk the remaining segments, building cumulative paths; for
+ *     each, try to find a matching nav label, otherwise capitalize.
+ */
+export function deriveCrumbsFromNav(pathname, nav, options = {}) {
+    const { rootCrumb, startAfter, capitalize = true } = options;
+    const result = [];
+    if (rootCrumb) {
+        result.push(rootCrumb);
+    }
+    const segments = (pathname || '').split('/').filter(Boolean);
+    // Resolve which segment index we start emitting crumbs after.
+    let startIndex = 0;
+    let basePath = '';
+    if (startAfter) {
+        const startSegments = startAfter.split('/').filter(Boolean);
+        if (startSegments.length > 0) {
+            // Match the full contiguous `startSegments` sequence in `segments`,
+            // not just the last token — otherwise an ambiguous pathname like
+            // `/sites/sites/content` with `startAfter: 'sites/sites'` would
+            // anchor on the first `sites` and build the wrong base path.
+            let matched = false;
+            outer: for (let i = 0; i <= segments.length - startSegments.length; i++) {
+                for (let j = 0; j < startSegments.length; j++) {
+                    if (segments[i + j] !== startSegments[j])
+                        continue outer;
+                }
+                startIndex = i + startSegments.length;
+                basePath = `/${segments.slice(0, startIndex).join('/')}`;
+                matched = true;
+                break;
+            }
+            if (!matched) {
+                // startAfter not in path → nothing to walk.
+                return result;
+            }
+        }
+    }
+    let currentPath = basePath;
+    for (const segment of segments.slice(startIndex)) {
+        currentPath += `/${segment}`;
+        const label = findLabelInNav(nav, currentPath) ??
+            (capitalize ? capitalizeSegment(segment) : segment);
+        result.push({ label, href: currentPath });
+    }
+    return result;
+}

package/dist/components/workspace/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @happyvertical/smrt-svelte/workspace
+ *
+ * Workspace shell primitives for admin UIs. See packages/smrt-svelte/CLAUDE.md
+ * for layering principles. Implementations land via #1227, #1228, #1229.
+ */
+export { default as Breadcrumbs } from './Breadcrumbs.svelte';
+export { type NavSection, type NavTreeFromManifestOptions, navTreeFromManifest, pluralizeClassName, type SmrtManifestEntryLike, type SmrtManifestLike, } from './manifest-nav.js';
+export { default as NavTree } from './NavTree.svelte';
+export { default as RoleShell } from './RoleShell.svelte';
+export { type DefineToolsDockOptions, defineToolsDock, TOOLS_DOCK_KEY, type ToolsDockInstance, } from './tools-dock/define-tools-dock.svelte.js';
+export { default as ToolsDock } from './tools-dock/ToolsDock.svelte';
+export { tryUseToolsDock, useToolsDock } from './tools-dock/use-tools-dock.js';
+export type { AvailableTool, BreadcrumbItem, NavItem, RoleConfig, ToolDef, ToolsDockApi, ToolsDockContext, ToolsDockEvents, } from './types.js';
+export { default as WorkspaceShell } from './WorkspaceShell.svelte';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/workspace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/workspace/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EACL,KAAK,UAAU,EACf,KAAK,0BAA0B,EAC/B,mBAAmB,EACnB,kBAAkB,EAClB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,0CAA0C,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAC/E,YAAY,EACV,aAAa,EACb,cAAc,EACd,OAAO,EACP,UAAU,EACV,OAAO,EACP,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/components/workspace/index.js

@@ -0,0 +1,14 @@
+/**
+ * @happyvertical/smrt-svelte/workspace
+ *
+ * Workspace shell primitives for admin UIs. See packages/smrt-svelte/CLAUDE.md
+ * for layering principles. Implementations land via #1227, #1228, #1229.
+ */
+export { default as Breadcrumbs } from './Breadcrumbs.svelte';
+export { navTreeFromManifest, pluralizeClassName, } from './manifest-nav.js';
+export { default as NavTree } from './NavTree.svelte';
+export { default as RoleShell } from './RoleShell.svelte';
+export { defineToolsDock, TOOLS_DOCK_KEY, } from './tools-dock/define-tools-dock.svelte.js';
+export { default as ToolsDock } from './tools-dock/ToolsDock.svelte';
+export { tryUseToolsDock, useToolsDock } from './tools-dock/use-tools-dock.js';
+export { default as WorkspaceShell } from './WorkspaceShell.svelte';

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

@@ -0,0 +1,200 @@
+/**
+ * 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.
+ */
+/**
+ * Visibility flavours emitted by `@smrt({ visibility })`. Mirrors
+ * `SmrtVisibility` in `@happyvertical/smrt-core` without importing it
+ * (see the file-top note on why we avoid a core peer dep).
+ */
+type ManifestVisibility = 'public' | 'internal' | 'test';
+/** Subset of `SmartObjectDefinition` the nav helper reads from. */
+export interface SmrtManifestEntryLike {
+    /** Qualified name in `@package/name:ClassName` form. Primary key. */
+    qualifiedName?: string;
+    /** Simple class name (PascalCase). */
+    className: string;
+    /** Package name where the class is defined. */
+    packageName?: string;
+    /** Pluralized resource name (used by the REST generator for the URL path). */
+    collection?: string;
+    /** Base class name as written in source. */
+    extends?: string;
+    /**
+     * Top-level visibility flag — `SmartObjectDefinition` hoists this out of
+     * `decoratorConfig` so it can be read without parsing the raw config. The
+     * helper reads here first, then falls back to `decoratorConfig.visibility`
+     * for older / hand-built manifests.
+     */
+    visibility?: ManifestVisibility;
+    /**
+     * The `@smrt({...})` config object captured by the AST scanner. Fields
+     * are optional in the structural type so partial manifests still satisfy
+     * it. The helper specifically looks at `ui?: { icon?, label? }`.
+     */
+    decoratorConfig?: {
+        ui?: {
+            icon?: string;
+            label?: string;
+        };
+        /**
+         * Subset of the `@smrt({ api })` shape we care about for nav filtering —
+         * entries with `api: false` (or an `include` that drops `list` / an
+         * `exclude` that drops `list`) don't get a REST list route and so
+         * can't anchor a nav link.
+         */
+        api?: boolean | {
+            include?: string[];
+            exclude?: string[];
+            [key: string]: unknown;
+        };
+        /**
+         * Raw visibility flag as written in source. Read as a fallback when
+         * the top-level `visibility` field is absent.
+         */
+        visibility?: ManifestVisibility;
+        [key: string]: unknown;
+    };
+}
+/** Subset of `SmartObjectManifest`. */
+export interface SmrtManifestLike {
+    objects: Record<string, SmrtManifestEntryLike>;
+}
+import type { NavItem } from './types.js';
+/**
+ * A nav section emitted by `navTreeFromManifest`. Structurally identical to
+ * `NavItem` — a top-level entry whose `children` are the resources grouped
+ * under it. Aliased for documentation clarity.
+ */
+export type NavSection = NavItem;
+/** Options consumed by {@link navTreeFromManifest}. */
+export interface NavTreeFromManifestOptions {
+    /**
+     * Qualified class names a role is allowed to see (e.g.
+     * `'@happyvertical/smrt-content:Article'`). Entries outside this list are
+     * dropped. Omit to include every visible resource.
+     *
+     * Plain string array on purpose — this helper must not depend on
+     * `smrt-users` or any concrete role / permission package. Wire your
+     * resolver (`PermissionResolver` from smrt-users etc.) at the
+     * `+layout.server.ts` level and pass the resulting allow-list in.
+     */
+    permittedResources?: string[];
+    /**
+     * Map of qualifier substring → section title. A class's qualified name
+     * is checked against each key with `String.includes()`; the first match
+     * wins. When no hint matches, the section title defaults to the package
+     * suffix after the last `/` and before the `:` —
+     * `@happyvertical/smrt-content:Article` → "smrt-content".
+     *
+     * @example
+     * ```ts
+     * sectionHints: {
+     *   '@happyvertical/smrt-content': 'Content',
+     *   '@happyvertical/smrt-commerce': 'Commerce',
+     *   '@acme/apparel': 'Catalog',
+     * }
+     * ```
+     */
+    sectionHints?: Record<string, string>;
+    /**
+     * Base path for generated hrefs. Defaults to `/api/v1` so the emitted
+     * URLs match SMRT's REST generator (`/api/v1/{collection}`). Pass an
+     * empty string to emit unprefixed paths like `/articles`.
+     */
+    basePath?: string;
+}
+/**
+ * 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 declare function pluralizeClassName(name: string): string;
+/**
+ * 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 declare function navTreeFromManifest(manifest: SmrtManifestLike, options?: NavTreeFromManifestOptions): NavSection[];
+export {};
+//# sourceMappingURL=manifest-nav.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-nav.d.ts","sourceRoot":"","sources":["../../../src/components/workspace/manifest-nav.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH;;;;GAIG;AACH,KAAK,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,MAAM,CAAC;AAEzD,mEAAmE;AACnE,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC;;;;OAIG;IACH,eAAe,CAAC,EAAE;QAChB,EAAE,CAAC,EAAE;YACH,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,KAAK,CAAC,EAAE,MAAM,CAAC;SAChB,CAAC;QACF;;;;;WAKG;QACH,GAAG,CAAC,EACA,OAAO,GACP;YAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;YAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC;QACvE;;;WAGG;QACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;QAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;CACH;AAED,uCAAuC;AACvC,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;CAChD;AAWD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC;AAEjC,uDAAuD;AACvD,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;OASG;IACH,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAWD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAevD;AA6OD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,GAAE,0BAA+B,GACvC,UAAU,EAAE,CAkEd"}