@classic-homes/theme-svelte 0.1.56 → 1.0.0

package/dist/__tests__/nav-access.test.js

@@ -0,0 +1,145 @@
+/**
+ * Navigation Access Filtering Tests
+ *
+ * Covers which navigation items a user sees given the roles and permissions
+ * they hold — including the nested case, where a restricted child sits under
+ * an unrestricted parent.
+ */
+import { describe, it, expect } from 'vitest';
+import { filterNavItems, isNavItemVisible, matchesAccess } from '../lib/utils/nav-access.js';
+function item(partial) {
+    return { name: partial.id, ...partial };
+}
+const ids = (items) => items.map((i) => i.id);
+describe('matchesAccess', () => {
+    it('matches when nothing is required', () => {
+        expect(matchesAccess(undefined, [])).toBe(true);
+        expect(matchesAccess([], [])).toBe(true);
+    });
+    it('does not match a requirement when the user holds nothing', () => {
+        expect(matchesAccess(['admin'], undefined)).toBe(false);
+        expect(matchesAccess(['admin'], [])).toBe(false);
+    });
+    it('matches any by default', () => {
+        expect(matchesAccess(['admin', 'manager'], ['manager'])).toBe(true);
+        expect(matchesAccess(['admin', 'manager'], ['agent'])).toBe(false);
+    });
+    it('can require all', () => {
+        expect(matchesAccess(['admin', 'manager'], ['admin'], true)).toBe(false);
+        expect(matchesAccess(['admin', 'manager'], ['admin', 'manager'], true)).toBe(true);
+    });
+});
+describe('isNavItemVisible', () => {
+    it('shows unrestricted items to anyone', () => {
+        expect(isNavItemVisible(item({ id: 'a' }), {})).toBe(true);
+    });
+    it('matches against every role held, not just one', () => {
+        const nav = item({ id: 'a', roles: ['agent'] });
+        expect(isNavItemVisible(nav, { userRoles: ['manager', 'agent'] })).toBe(true);
+    });
+    it('does not imply roles from one another', () => {
+        // Mirrors the auth package: holding admin does not imply agent, so the UI
+        // cannot offer something the server would reject.
+        const nav = item({ id: 'a', roles: ['agent'] });
+        expect(isNavItemVisible(nav, { userRoles: ['admin'] })).toBe(false);
+    });
+    it('combines roles and permissions as AND', () => {
+        const nav = item({ id: 'a', roles: ['manager'], permissions: ['users:write'] });
+        expect(isNavItemVisible(nav, { userRoles: ['manager'], userPermissions: ['users:write'] })).toBe(true);
+        expect(isNavItemVisible(nav, { userRoles: ['manager'], userPermissions: ['users:read'] })).toBe(false);
+        expect(isNavItemVisible(nav, { userRoles: ['agent'], userPermissions: ['users:write'] })).toBe(false);
+    });
+    it('gates on permissions alone', () => {
+        const nav = item({ id: 'a', permissions: ['settings:read'] });
+        expect(isNavItemVisible(nav, { userPermissions: ['settings:read'] })).toBe(true);
+        expect(isNavItemVisible(nav, { userRoles: ['admin'] })).toBe(false);
+    });
+});
+describe('filterNavItems', () => {
+    it('shows the union across a multi-role user', () => {
+        const items = [
+            item({ id: 'dashboard' }),
+            item({ id: 'users', roles: ['manager'] }),
+            item({ id: 'homes', roles: ['agent'] }),
+            item({ id: 'system', roles: ['admin'] }),
+        ];
+        expect(ids(filterNavItems(items, { userRoles: ['manager', 'agent'] }))).toEqual([
+            'dashboard',
+            'users',
+            'homes',
+        ]);
+    });
+    it('filters a restricted child under an unrestricted parent', () => {
+        // The parent passes on its own merits; without recursion nothing would ever
+        // look inside it and the admin-only child would show to everyone.
+        const items = [
+            item({
+                id: 'main',
+                children: [item({ id: 'open' }), item({ id: 'audit', roles: ['admin'] })],
+            }),
+        ];
+        const filtered = filterNavItems(items, { userRoles: ['agent'] });
+        expect(ids(filtered[0].children)).toEqual(['open']);
+    });
+    it('filters arbitrarily deep', () => {
+        const items = [
+            item({
+                id: 'l1',
+                children: [
+                    item({
+                        id: 'l2',
+                        children: [item({ id: 'l3', roles: ['admin'] }), item({ id: 'l3-open' })],
+                    }),
+                ],
+            }),
+        ];
+        const filtered = filterNavItems(items, { userRoles: ['agent'] });
+        expect(ids(filtered[0].children[0].children)).toEqual(['l3-open']);
+    });
+    it('drops a container whose children are all filtered away', () => {
+        const items = [
+            item({ id: 'admin-area', children: [item({ id: 'system', roles: ['admin'] })] }),
+        ];
+        // Keeping it would render an expandable with nothing behind it.
+        expect(ids(filterNavItems(items, { userRoles: ['agent'] }))).toEqual([]);
+    });
+    it('keeps an emptied parent that is a destination in its own right', () => {
+        const items = [
+            item({
+                id: 'reports',
+                href: '/reports',
+                children: [item({ id: 'revenue', roles: ['admin'] })],
+            }),
+        ];
+        const filtered = filterNavItems(items, { userRoles: ['agent'] });
+        expect(ids(filtered)).toEqual(['reports']);
+        expect(filtered[0].children).toEqual([]);
+    });
+    it('hides everything restricted from a user with no roles', () => {
+        const items = [item({ id: 'dashboard' }), item({ id: 'users', roles: ['manager'] })];
+        expect(ids(filterNavItems(items, {}))).toEqual(['dashboard']);
+    });
+    it('honors requireAllRoles', () => {
+        const items = [item({ id: 'both', roles: ['admin', 'manager'] })];
+        expect(ids(filterNavItems(items, { userRoles: ['admin'], requireAllRoles: true }))).toEqual([]);
+        expect(ids(filterNavItems(items, { userRoles: ['admin', 'manager'], requireAllRoles: true }))).toEqual(['both']);
+    });
+    it('honors requireAllPermissions', () => {
+        const items = [item({ id: 'both', permissions: ['a:read', 'b:read'] })];
+        expect(ids(filterNavItems(items, { userPermissions: ['a:read'], requireAllPermissions: true }))).toEqual([]);
+        expect(ids(filterNavItems(items, {
+            userPermissions: ['a:read', 'b:read'],
+            requireAllPermissions: true,
+        }))).toEqual(['both']);
+    });
+    it('leaves childless items without a children key', () => {
+        const filtered = filterNavItems([item({ id: 'a' })], {});
+        expect('children' in filtered[0]).toBe(false);
+    });
+    it('does not mutate the input', () => {
+        const items = [item({ id: 'main', children: [item({ id: 'audit', roles: ['admin'] })] })];
+        const before = JSON.stringify(items);
+        filterNavItems(items, { userRoles: ['agent'] });
+        expect(JSON.stringify(items)).toBe(before);
+    });
+});

package/dist/__tests__/sidebar-expansion.test.js

@@ -0,0 +1,59 @@
+/**
+ * Sidebar Role-based Expansion Tests
+ *
+ * Covers which sections start expanded for a given user. This is a UX
+ * affordance, not access control — it decides what starts open, not what is
+ * visible (that's nav-access).
+ */
+import { describe, it, expect } from 'vitest';
+import { sidebarStore } from '../lib/stores/sidebar.svelte.js';
+function section(partial) {
+    return { title: partial.id, items: [], ...partial };
+}
+describe('computeInitialExpansions', () => {
+    it('expands a section for any matching role', () => {
+        const sections = [section({ id: 'admin', expandForRoles: ['admin', 'superuser'] })];
+        expect(sidebarStore.computeInitialExpansions(sections, ['admin'])).toEqual(['admin']);
+        expect(sidebarStore.computeInitialExpansions(sections, ['superuser'])).toEqual(['admin']);
+    });
+    it('expands on a secondary role, not just the first held', () => {
+        const sections = [section({ id: 'ops', expandForRoles: ['agent'] })];
+        expect(sidebarStore.computeInitialExpansions(sections, ['manager', 'agent'])).toEqual(['ops']);
+    });
+    it('leaves a section collapsed when no role matches', () => {
+        const sections = [section({ id: 'admin', expandForRoles: ['admin'] })];
+        expect(sidebarStore.computeInitialExpansions(sections, ['agent'])).toEqual([]);
+    });
+    it('leaves a role-gated section collapsed for a user with no roles', () => {
+        const sections = [section({ id: 'admin', expandForRoles: ['admin'] })];
+        expect(sidebarStore.computeInitialExpansions(sections, [])).toEqual([]);
+        expect(sidebarStore.computeInitialExpansions(sections, undefined)).toEqual([]);
+    });
+    it('expands non-collapsible sections regardless of roles', () => {
+        const sections = [section({ id: 'main', collapsible: false })];
+        expect(sidebarStore.computeInitialExpansions(sections, [])).toEqual(['main']);
+    });
+    it('respects an explicitly collapsed section', () => {
+        const sections = [section({ id: 'main', collapsible: true, expanded: false })];
+        expect(sidebarStore.computeInitialExpansions(sections, ['admin'])).toEqual([]);
+    });
+    it('expands a collapsible section that is not explicitly collapsed', () => {
+        const sections = [section({ id: 'main', collapsible: true })];
+        expect(sidebarStore.computeInitialExpansions(sections, [])).toEqual(['main']);
+    });
+    it('prefers expandForRoles over the collapsed default', () => {
+        // expandForRoles is checked first, so it wins over `expanded: false`.
+        const sections = [
+            section({ id: 'admin', collapsible: true, expanded: false, expandForRoles: ['admin'] }),
+        ];
+        expect(sidebarStore.computeInitialExpansions(sections, ['admin'])).toEqual(['admin']);
+    });
+    it('handles a mixed navigation', () => {
+        const sections = [
+            section({ id: 'main', collapsible: false }),
+            section({ id: 'admin', expandForRoles: ['admin'] }),
+            section({ id: 'ops', expandForRoles: ['agent'] }),
+        ];
+        expect(sidebarStore.computeInitialExpansions(sections, ['agent'])).toEqual(['main', 'ops']);
+    });
+});

package/dist/lib/components/layout/DashboardLayout.svelte

@@ -229,6 +229,7 @@
   <Sidebar
     navigation={effectiveNavigation}
     userRoles={user?.roles}
+    userPermissions={user?.permissions}
     variant={sidebarVariant}
     collapsed={!sidebarStore.isOpen && !isMobile}
     {isMobile}

package/dist/lib/components/layout/Sidebar.svelte

@@ -15,6 +15,7 @@
   import type { Snippet } from 'svelte';
   import type { NavSection, NavItem, QuickLink } from '../../types/layout.js';
   import { cn } from '../../utils.js';
+  import { filterNavItems } from '../../utils/nav-access.js';
   import { sidebarStore } from '../../stores/sidebar.svelte.js';
   import LogoMain from '../LogoMain.svelte';
   import QuickLinks from './QuickLinks.svelte';
@@ -25,8 +26,17 @@
   interface Props {
     /** 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;
     /** Whether sidebar is collapsed (desktop) */
     collapsed?: boolean;
     /** Whether currently on mobile */
@@ -80,6 +90,9 @@
   let {
     navigation,
     userRoles,
+    userPermissions,
+    requireAllRoles = false,
+    requireAllPermissions = false,
     collapsed = false,
     isMobile = false,
     mobileOpen = false,
@@ -106,27 +119,19 @@
     class: className,
   }: Props = $props();
 
-  // Helper to check if item is visible based on roles
-  function isItemVisible(item: NavItem): boolean {
-    if (!item.roles || item.roles.length === 0) return true;
-    if (!userRoles || userRoles.length === 0) return false;
-    return item.roles.some((role) => userRoles.includes(role));
-  }
-
-  // Recursively filter items based on roles
-  function filterItems(items: NavItem[]): NavItem[] {
-    return items.filter(isItemVisible).map((item) => ({
-      ...item,
-      children: item.children ? filterItems(item.children) : undefined,
-    }));
-  }
+  const accessContext = $derived({
+    userRoles,
+    userPermissions,
+    requireAllRoles,
+    requireAllPermissions,
+  });
 
-  // Filter navigation based on user roles
+  // Filter navigation by what the user holds, dropping sections left empty.
   const roleFilteredNavigation = $derived(
     navigation
       .map((section) => ({
         ...section,
-        items: filterItems(section.items),
+        items: filterNavItems(section.items, accessContext),
       }))
       .filter((section) => section.items.length > 0)
   );

package/dist/lib/components/layout/Sidebar.svelte.d.ts

@@ -16,8 +16,17 @@ import type { NavSection, NavItem, QuickLink } from '../../types/layout.js';
 interface Props {
     /** 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;
     /** Whether sidebar is collapsed (desktop) */
     collapsed?: boolean;
     /** Whether currently on mobile */

package/dist/lib/schemas/auth.d.ts

@@ -243,7 +243,10 @@ export declare const emailChangeSchema: z.ZodObject<{
 }>;
 export type EmailChangeFormData = z.infer<typeof emailChangeSchema>;
 /**
- * User schema
+ * User schema — for validating a user payload from an API.
+ *
+ * Distinct from the layout `User` in `types/layout.ts`, which is a display
+ * view-model for the sidebar and avatar. This one describes data on the wire.
  */
 export declare const userSchema: z.ZodObject<{
     id: z.ZodString;
@@ -262,9 +265,9 @@ export declare const userSchema: z.ZodObject<{
     email: string;
     username?: string | undefined;
     roles?: string[] | undefined;
+    permissions?: string[] | undefined;
     fullName?: string | undefined;
     avatarUrl?: string | null | undefined;
-    permissions?: string[] | undefined;
     mfaEnabled?: boolean | undefined;
     emailVerified?: boolean | undefined;
     createdAt?: string | undefined;
@@ -274,15 +277,22 @@ export declare const userSchema: z.ZodObject<{
     email: string;
     username?: string | undefined;
     roles?: string[] | undefined;
+    permissions?: string[] | undefined;
     fullName?: string | undefined;
     avatarUrl?: string | null | undefined;
-    permissions?: string[] | undefined;
     mfaEnabled?: boolean | undefined;
     emailVerified?: boolean | undefined;
     createdAt?: string | undefined;
     updatedAt?: string | undefined;
 }>;
-export type User = z.infer<typeof userSchema>;
+/**
+ * A user payload as validated by {@link userSchema}.
+ *
+ * Named `AuthUser` to keep the package's `User` unambiguous — that name belongs
+ * to the layout view-model. Previously exported as `User`, where it collided
+ * with the layout type and lost, making it unreachable from the package root.
+ */
+export type AuthUser = z.infer<typeof userSchema>;
 /**
  * Auth tokens schema
  */
@@ -324,9 +334,9 @@ export declare const loginResponseSchema: z.ZodObject<{
         email: string;
         username?: string | undefined;
         roles?: string[] | undefined;
+        permissions?: string[] | undefined;
         fullName?: string | undefined;
         avatarUrl?: string | null | undefined;
-        permissions?: string[] | undefined;
         mfaEnabled?: boolean | undefined;
         emailVerified?: boolean | undefined;
         createdAt?: string | undefined;
@@ -336,9 +346,9 @@ export declare const loginResponseSchema: z.ZodObject<{
         email: string;
         username?: string | undefined;
         roles?: string[] | undefined;
+        permissions?: string[] | undefined;
         fullName?: string | undefined;
         avatarUrl?: string | null | undefined;
-        permissions?: string[] | undefined;
         mfaEnabled?: boolean | undefined;
         emailVerified?: boolean | undefined;
         createdAt?: string | undefined;
@@ -368,9 +378,9 @@ export declare const loginResponseSchema: z.ZodObject<{
         email: string;
         username?: string | undefined;
         roles?: string[] | undefined;
+        permissions?: string[] | undefined;
         fullName?: string | undefined;
         avatarUrl?: string | null | undefined;
-        permissions?: string[] | undefined;
         mfaEnabled?: boolean | undefined;
         emailVerified?: boolean | undefined;
         createdAt?: string | undefined;
@@ -390,9 +400,9 @@ export declare const loginResponseSchema: z.ZodObject<{
         email: string;
         username?: string | undefined;
         roles?: string[] | undefined;
+        permissions?: string[] | undefined;
         fullName?: string | undefined;
         avatarUrl?: string | null | undefined;
-        permissions?: string[] | undefined;
         mfaEnabled?: boolean | undefined;
         emailVerified?: boolean | undefined;
         createdAt?: string | undefined;

package/dist/lib/schemas/auth.js

@@ -181,7 +181,10 @@ export const emailChangeSchema = z.object({
 // API Response Schemas (for validating API responses)
 // ============================================================================
 /**
- * User schema
+ * User schema — for validating a user payload from an API.
+ *
+ * Distinct from the layout `User` in `types/layout.ts`, which is a display
+ * view-model for the sidebar and avatar. This one describes data on the wire.
  */
 export const userSchema = z.object({
     id: z.string(),

package/dist/lib/schemas/index.d.ts

@@ -9,7 +9,7 @@ export { emailSchema, passwordSchema, loginPasswordSchema, usernameSchema, fullN
 export { loginSchema, registerSchema, forgotPasswordSchema, resetPasswordSchema, changePasswordSchema, mfaVerifySchema, mfaSetupSchema, profileUpdateSchema, emailChangeSchema, } from './auth.js';
 export type { LoginFormData, RegisterFormData, ForgotPasswordFormData, ResetPasswordFormData, ChangePasswordFormData, MfaVerifyFormData, MfaSetupFormData, ProfileUpdateFormData, EmailChangeFormData, } from './auth.js';
 export { userSchema, authTokensSchema, loginResponseSchema } from './auth.js';
-export type { User, AuthTokens, LoginResponse } from './auth.js';
+export type { AuthUser, AuthTokens, LoginResponse } from './auth.js';
 export { nonEmptyString, trimmedString, optionalString, urlSchema, optionalUrlSchema, slugSchema, } from './common.js';
 export { positiveInt, nonNegativeInt, percentageSchema, priceSchema, numericString, } from './common.js';
 export { isoDateSchema, dateStringSchema, timeStringSchema, futureDateSchema, pastDateSchema, } from './common.js';

package/dist/lib/stores/sidebar.svelte.d.ts

@@ -122,8 +122,13 @@ declare class SidebarStore {
     getPinnedIds(): string[];
     /**
      * 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: NavSection[], userRoles?: string[]): string[];
     /**

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.0",
   "description": "Svelte components for the Classic theme system",
   "type": "module",
   "svelte": "./dist/lib/index.js",