@classic-homes/theme-svelte 0.1.55 → 1.0.0

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/dist/lib/utils.d.ts

@@ -4,13 +4,3 @@ import { type ClassValue } from 'clsx';
  * Uses clsx for conditional classes and tailwind-merge to handle conflicts
  */
 export declare function cn(...inputs: ClassValue[]): string;
-/**
- * Generate a unique ID with an optional prefix.
- * Uses crypto.randomUUID() to avoid SSR hydration mismatches caused by
- * sequential counters (where server and client counts can diverge).
- * The short suffix is derived from the UUID for compact, readable IDs.
- *
- * @param prefix - Optional prefix for the ID (e.g., 'checkbox', 'tabs')
- * @returns A unique ID string like 'checkbox-a1b2c3d4' or 'ct-a1b2c3d4'
- */
-export declare function useId(prefix?: string): string;

package/dist/lib/utils.js

@@ -7,16 +7,3 @@ import { twMerge } from 'tailwind-merge';
 export function cn(...inputs) {
     return twMerge(clsx(inputs));
 }
-/**
- * Generate a unique ID with an optional prefix.
- * Uses crypto.randomUUID() to avoid SSR hydration mismatches caused by
- * sequential counters (where server and client counts can diverge).
- * The short suffix is derived from the UUID for compact, readable IDs.
- *
- * @param prefix - Optional prefix for the ID (e.g., 'checkbox', 'tabs')
- * @returns A unique ID string like 'checkbox-a1b2c3d4' or 'ct-a1b2c3d4'
- */
-export function useId(prefix) {
-    const id = crypto.randomUUID().slice(0, 8);
-    return prefix ? `${prefix}-${id}` : `ct-${id}`;
-}

package/package.json

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