@classic-homes/theme-svelte 0.1.56 → 1.0.1

package/dist/lib/stores/sidebar.svelte.js

@@ -17,6 +17,7 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
 };
 var _SidebarStore_instances, _SidebarStore_initialized, _SidebarStore_loadedFromStorage, _SidebarStore_loadedExpansionFromStorage, _SidebarStore_loadedPinnedFromStorage, _SidebarStore_onPinnedChange, _SidebarStore_appId, _SidebarStore_getStorageKey, _SidebarStore_persist, _SidebarStore_persistExpansion, _SidebarStore_persistPinned;
+import { matchesAccess } from '../utils/nav-access.js';
 const STORAGE_PREFIX = 'classic-theme-sidebar';
 class SidebarStore {
     constructor() {
@@ -281,15 +282,20 @@ class SidebarStore {
     // ============================================
     /**
      * Compute which sections should be initially expanded based on user roles.
-     * Sections with expandForRoles that match user roles will be auto-expanded.
-     * Falls back to section.expanded or default behavior.
+     *
+     * A section listing `expandForRoles` expands for a user holding ANY of them.
+     * Sections without it fall back to the default: expanded unless explicitly
+     * collapsed.
+     *
+     * This is a UX affordance, not access control — it decides what starts open,
+     * not what is visible. Filtering is `filterNavItems`.
      */
     computeInitialExpansions(sections, userRoles) {
         return sections
             .filter((section) => {
             // Check role-based expansion first
             if (section.expandForRoles?.length) {
-                return section.expandForRoles.some((role) => userRoles?.includes(role));
+                return matchesAccess(section.expandForRoles, userRoles);
             }
             // Fall back to default behavior: expand unless explicitly collapsed
             return !section.collapsible || section.expanded !== false;

package/dist/lib/types/layout.d.ts

@@ -78,8 +78,19 @@ export interface NavItem {
     icon?: string;
     /** Optional badge (notification count, etc.) */
     badge?: string | number;
-    /** Role-based visibility */
+    /**
+     * Roles that can see this item. The user needs ANY of them by default; set
+     * `requireAllRoles` on the Sidebar for ALL. Omit to show the item to everyone.
+     */
     roles?: string[];
+    /**
+     * Permissions that can see this item. The user needs ANY of them by default;
+     * set `requireAllPermissions` on the Sidebar for ALL.
+     *
+     * Combined with `roles` as AND: an item listing both is shown only to a user
+     * who satisfies each.
+     */
+    permissions?: string[];
     /** Opens in new tab */
     external?: boolean;
     /** Whether this item is currently active */
@@ -125,7 +136,27 @@ export interface SidebarPreferences {
     expandedItems: string[];
 }
 /**
- * User data for layout components
+ * User data for layout components.
+ *
+ * A display view-model, deliberately not an identity: the layout only needs
+ * enough to render an avatar and decide what navigation to show, so this stays
+ * independent of any auth package. Apps map their own user into it.
+ *
+ * With `@classic-homes/auth`, derive the display fields rather than reaching for
+ * a matching shape — its `User` has no `name` or `initials`:
+ *
+ * ```typescript
+ * import { getDisplayName, getUserInitials } from '@classic-homes/auth/core';
+ *
+ * const layoutUser = {
+ *   id: user.id,
+ *   name: getDisplayName(user),
+ *   initials: getUserInitials(user),
+ *   email: user.email,
+ *   roles: user.roles,
+ *   permissions: user.permissions,
+ * };
+ * ```
  */
 export interface User {
     /** Unique identifier */
@@ -136,8 +167,16 @@ export interface User {
     email?: string;
     /** Avatar URL */
     avatar?: string;
-    /** User roles for authorization */
+    /**
+     * Every role the user holds, used to filter navigation.
+     *
+     * A user may hold several; items are matched against the whole set, so a
+     * manager who is also an agent sees both. Not an access control boundary —
+     * this only decides what is rendered.
+     */
     roles?: string[];
+    /** Every permission the user holds, used to filter navigation. */
+    permissions?: string[];
     /** User initials (fallback for avatar) */
     initials?: string;
 }
@@ -286,8 +325,17 @@ export interface PublicLayoutProps {
 export interface SidebarProps {
     /** Navigation sections */
     navigation: NavSection[];
-    /** User roles for filtering navigation items */
+    /**
+     * Every role the current user holds. Items are matched against the whole set,
+     * so a user with several roles sees the union of what they allow.
+     */
     userRoles?: string[];
+    /** Every permission the current user holds, for permission-gated items. */
+    userPermissions?: string[];
+    /** Require ALL of an item's `roles` rather than any (default: any). */
+    requireAllRoles?: boolean;
+    /** Require ALL of an item's `permissions` rather than any (default: any). */
+    requireAllPermissions?: boolean;
     /** Visual variant - light (default) or dark */
     variant?: 'light' | 'dark';
     /** Whether sidebar is collapsed */

package/dist/lib/utils/nav-access.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Navigation Access Filtering
+ *
+ * Decides which navigation items a user should see, based on the roles and
+ * permissions they hold.
+ *
+ * A user holds a *set* of roles and a *set* of permissions, and an item is
+ * matched against the whole set — someone who is both a manager and an agent
+ * sees the union of what each allows.
+ *
+ * This decides what is **rendered**. It is not an access control boundary:
+ * the server enforces access, and hiding a link is a courtesy to the user, not
+ * a security measure.
+ */
+import type { NavItem } from '../types/layout.js';
+/**
+ * Who is looking, and how strictly to match.
+ */
+export interface NavAccessContext {
+    /** Every role the user holds. */
+    userRoles?: string[];
+    /** Every permission the user holds. */
+    userPermissions?: string[];
+    /** Require ALL of an item's `roles` rather than any (default: any). */
+    requireAllRoles?: boolean;
+    /** Require ALL of an item's `permissions` rather than any (default: any). */
+    requireAllPermissions?: boolean;
+}
+/**
+ * Whether `held` satisfies `required`.
+ *
+ * An empty or absent `required` is no restriction at all, so it matches. An
+ * empty `held` against a real restriction never matches — a user with no roles
+ * cannot satisfy a role requirement.
+ */
+export declare function matchesAccess(required: string[] | undefined, held: string[] | undefined, requireAll?: boolean): boolean;
+/**
+ * Whether a single item should be shown.
+ *
+ * `roles` and `permissions` combine as AND: an item declaring both is shown
+ * only to a user who satisfies each.
+ */
+export declare function isNavItemVisible(item: NavItem, context?: NavAccessContext): boolean;
+/**
+ * Filter a navigation tree.
+ *
+ * Recurses into `children`: a restricted child under an unrestricted parent is
+ * still checked, rather than inheriting the parent's visibility.
+ *
+ * A parent left with no children is dropped, since it would render as an empty
+ * expandable — unless it has its own `href`, which makes it a destination in
+ * its own right.
+ *
+ * Does not mutate `items`.
+ *
+ * @example
+ * ```typescript
+ * filterNavItems(items, { userRoles: ['manager', 'agent'] });
+ * ```
+ */
+export declare function filterNavItems(items: NavItem[], context?: NavAccessContext): NavItem[];

package/dist/lib/utils/nav-access.js

@@ -0,0 +1,74 @@
+/**
+ * Navigation Access Filtering
+ *
+ * Decides which navigation items a user should see, based on the roles and
+ * permissions they hold.
+ *
+ * A user holds a *set* of roles and a *set* of permissions, and an item is
+ * matched against the whole set — someone who is both a manager and an agent
+ * sees the union of what each allows.
+ *
+ * This decides what is **rendered**. It is not an access control boundary:
+ * the server enforces access, and hiding a link is a courtesy to the user, not
+ * a security measure.
+ */
+/**
+ * Whether `held` satisfies `required`.
+ *
+ * An empty or absent `required` is no restriction at all, so it matches. An
+ * empty `held` against a real restriction never matches — a user with no roles
+ * cannot satisfy a role requirement.
+ */
+export function matchesAccess(required, held, requireAll = false) {
+    if (!required || required.length === 0)
+        return true;
+    if (!held || held.length === 0)
+        return false;
+    return requireAll
+        ? required.every((value) => held.includes(value))
+        : required.some((value) => held.includes(value));
+}
+/**
+ * Whether a single item should be shown.
+ *
+ * `roles` and `permissions` combine as AND: an item declaring both is shown
+ * only to a user who satisfies each.
+ */
+export function isNavItemVisible(item, context = {}) {
+    return (matchesAccess(item.roles, context.userRoles, context.requireAllRoles) &&
+        matchesAccess(item.permissions, context.userPermissions, context.requireAllPermissions));
+}
+/**
+ * Filter a navigation tree.
+ *
+ * Recurses into `children`: a restricted child under an unrestricted parent is
+ * still checked, rather than inheriting the parent's visibility.
+ *
+ * A parent left with no children is dropped, since it would render as an empty
+ * expandable — unless it has its own `href`, which makes it a destination in
+ * its own right.
+ *
+ * Does not mutate `items`.
+ *
+ * @example
+ * ```typescript
+ * filterNavItems(items, { userRoles: ['manager', 'agent'] });
+ * ```
+ */
+export function filterNavItems(items, context = {}) {
+    const result = [];
+    for (const item of items) {
+        if (!isNavItemVisible(item, context))
+            continue;
+        if (!item.children) {
+            result.push(item);
+            continue;
+        }
+        const children = filterNavItems(item.children, context);
+        if (item.children.length > 0 && children.length === 0 && !item.href) {
+            continue;
+        }
+        result.push({ ...item, children });
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classic-homes/theme-svelte",
-  "version": "0.1.56",
+  "version": "1.0.1",
   "description": "Svelte components for the Classic theme system",
   "type": "module",
   "svelte": "./dist/lib/index.js",