@classic-homes/theme-svelte 0.1.26 → 0.1.28

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

@@ -79,12 +79,24 @@
     searchable?: boolean;
     /** Placeholder text for search input */
     searchPlaceholder?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Title for the pinned items section (default: "Pinned") */
+    pinnedSectionTitle?: string;
+    /** Initial pinned item IDs for server hydration */
+    initialPinnedItems?: string[];
+    /** Callback when pinned items change (for external persistence) */
+    onPinnedChange?: (pinnedIds: string[]) => void;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{ isPinned: boolean }]>;
     /** Header search configuration */
     headerSearch?: HeaderSearchConfig;
     /** Breakpoint at which to switch between mobile and desktop layouts */
     mobileBreakpoint?: Breakpoint;
     /** Content area padding: 'default' (p-4 lg:p-6), 'compact' (p-2 lg:p-4), 'none' (no padding) */
     contentPadding?: 'default' | 'compact' | 'none';
+    /** App identifier for per-app sidebar preferences storage */
+    appId?: string;
     /** Main content */
     children: Snippet;
   }
@@ -112,9 +124,15 @@
     collapsedWidth = 64,
     searchable = false,
     searchPlaceholder = 'Search...',
+    enablePinning = false,
+    pinnedSectionTitle = 'Pinned',
+    initialPinnedItems,
+    onPinnedChange,
+    pinIcon,
     headerSearch,
     mobileBreakpoint = 'lg',
     contentPadding = 'default',
+    appId,
     children,
   }: Props = $props();
 
@@ -159,7 +177,7 @@
 
   // Load persisted sidebar state and apply prop-based defaults
   $effect(() => {
-    sidebarStore.initialize();
+    sidebarStore.initialize(appId);
 
     // Only apply prop-based initial state if no persisted state exists
     if (!sidebarStore.hasPersistedState && !isMobile) {
@@ -221,12 +239,18 @@
     {icon}
     {quickLinks}
     {quickLinksDisplay}
-    {quickLinkIcon}
+    quickLinkIcon={quickLinkIcon ?? (icon as Snippet<[QuickLink]> | undefined)}
     footer={sidebarFooter}
     {expandedWidth}
     {collapsedWidth}
     {searchable}
     {searchPlaceholder}
+    {enablePinning}
+    {pinnedSectionTitle}
+    {initialPinnedItems}
+    {onPinnedChange}
+    {pinIcon}
+    {appId}
   />
 
   <!-- Main Content Area -->

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

@@ -57,12 +57,26 @@ interface Props {
     searchable?: boolean;
     /** Placeholder text for search input */
     searchPlaceholder?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Title for the pinned items section (default: "Pinned") */
+    pinnedSectionTitle?: string;
+    /** Initial pinned item IDs for server hydration */
+    initialPinnedItems?: string[];
+    /** Callback when pinned items change (for external persistence) */
+    onPinnedChange?: (pinnedIds: string[]) => void;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{
+        isPinned: boolean;
+    }]>;
     /** Header search configuration */
     headerSearch?: HeaderSearchConfig;
     /** Breakpoint at which to switch between mobile and desktop layouts */
     mobileBreakpoint?: Breakpoint;
     /** Content area padding: 'default' (p-4 lg:p-6), 'compact' (p-2 lg:p-4), 'none' (no padding) */
     contentPadding?: 'default' | 'compact' | 'none';
+    /** App identifier for per-app sidebar preferences storage */
+    appId?: string;
     /** Main content */
     children: Snippet;
 }

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

@@ -61,6 +61,18 @@
     searchable?: boolean;
     /** Placeholder text for search input */
     searchPlaceholder?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Title for the pinned items section (default: "Pinned") */
+    pinnedSectionTitle?: string;
+    /** Initial pinned item IDs for server hydration */
+    initialPinnedItems?: string[];
+    /** Callback when pinned items change (for external persistence) */
+    onPinnedChange?: (pinnedIds: string[]) => void;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{ isPinned: boolean }]>;
+    /** App identifier for per-app preferences storage */
+    appId?: string;
     /** Additional classes */
     class?: string;
   }
@@ -85,6 +97,12 @@
     collapsedWidth = 64,
     searchable = false,
     searchPlaceholder = 'Search...',
+    enablePinning = false,
+    pinnedSectionTitle = 'Pinned',
+    initialPinnedItems,
+    onPinnedChange,
+    pinIcon,
+    appId,
     class: className,
   }: Props = $props();
 
@@ -113,6 +131,66 @@
       .filter((section) => section.items.length > 0)
   );
 
+  // Initialize store with appId for per-app preferences
+  $effect(() => {
+    sidebarStore.initialize(appId);
+  });
+
+  // Initialize pinning from props
+  $effect(() => {
+    // Set up the callback for pinned changes
+    sidebarStore.setOnPinnedChange(onPinnedChange);
+
+    // Initialize from props if provided (server hydration)
+    if (initialPinnedItems?.length) {
+      sidebarStore.initializePinnedItems(initialPinnedItems);
+    }
+  });
+
+  // Helper to find a nav item by ID (including nested children)
+  function findNavItemById(sections: NavSection[], itemId: string): NavItem | undefined {
+    for (const section of sections) {
+      for (const item of section.items) {
+        if (item.id === itemId) return item;
+        if (item.children) {
+          const found = item.children.find((child) => child.id === itemId);
+          if (found) return found;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  // Build pinned items section (only pinnable items that still exist in navigation)
+  const pinnedSection = $derived.by(() => {
+    if (!enablePinning) return null;
+
+    const pinnedIds = sidebarStore.getPinnedIds();
+    if (pinnedIds.length === 0) return null;
+
+    const pinnedItems: NavItem[] = [];
+    for (const id of pinnedIds) {
+      const item = findNavItemById(roleFilteredNavigation, id);
+      // Only include if item exists, is visible, and is pinnable
+      if (item && item.pinnable !== false) {
+        // Create a flattened copy (no children in pinned section)
+        pinnedItems.push({
+          ...item,
+          children: undefined, // Flatten nested items
+        });
+      }
+    }
+
+    if (pinnedItems.length === 0) return null;
+
+    return {
+      id: '__pinned__',
+      title: pinnedSectionTitle,
+      items: pinnedItems,
+      collapsible: false,
+    } satisfies NavSection;
+  });
+
   // Search state
   let searchQuery = $state('');
 
@@ -155,19 +233,16 @@
   // Track previous search to avoid redundant updates
   let prevSearchQuery = '';
 
-  // Initialize expanded sections based on navigation data (only if no persisted state)
+  // Initialize expanded sections based on navigation data and user roles (only if no persisted state)
   $effect(() => {
     // Only run on initial mount (no search)
     if (searchQuery.trim()) return;
 
-    // Set default expansions if no persisted state
-    const defaultExpanded: string[] = [];
-    roleFilteredNavigation.forEach((section) => {
-      // Expand by default unless explicitly set to collapsed
-      if (!section.collapsible || section.expanded !== false) {
-        defaultExpanded.push(section.id);
-      }
-    });
+    // Use computeInitialExpansions for role-based section expansion
+    const defaultExpanded = sidebarStore.computeInitialExpansions(
+      roleFilteredNavigation,
+      userRoles
+    );
     sidebarStore.setDefaultSections(defaultExpanded);
   });
 
@@ -419,6 +494,24 @@
   <!-- Navigation - keydown for arrow key navigation is intentional for a11y -->
   <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
   <nav bind:this={navElement} class="flex-1 overflow-y-auto py-4" onkeydown={handleNavKeydown}>
+    <!-- Pinned Section (always at top, not affected by search) -->
+    {#if pinnedSection && !searchQuery.trim()}
+      <SidebarSection
+        section={pinnedSection}
+        {isLight}
+        {collapsed}
+        {isMobile}
+        {icon}
+        searchQuery=""
+        {enablePinning}
+        {pinIcon}
+        isPinnedSection={true}
+        onNavigate={handleNavigate}
+        onItemMouseEnter={handleItemMouseEnter}
+        onItemMouseLeave={handleItemMouseLeave}
+      />
+    {/if}
+
     {#each filteredNavigation as section}
       <SidebarSection
         {section}
@@ -427,6 +520,9 @@
         {isMobile}
         {icon}
         {searchQuery}
+        {enablePinning}
+        {pinIcon}
+        isPinnedSection={false}
         onNavigate={handleNavigate}
         onItemMouseEnter={handleItemMouseEnter}
         onItemMouseLeave={handleItemMouseLeave}
@@ -464,7 +560,7 @@
         links={quickLinks}
         display={collapsed && !isMobile ? 'icons' : quickLinksDisplay}
         {variant}
-        icon={quickLinkIcon}
+        icon={quickLinkIcon ?? (icon as Snippet<[QuickLink]> | undefined)}
       />
     </div>
   {/if}

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

@@ -52,6 +52,20 @@ interface Props {
     searchable?: boolean;
     /** Placeholder text for search input */
     searchPlaceholder?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Title for the pinned items section (default: "Pinned") */
+    pinnedSectionTitle?: string;
+    /** Initial pinned item IDs for server hydration */
+    initialPinnedItems?: string[];
+    /** Callback when pinned items change (for external persistence) */
+    onPinnedChange?: (pinnedIds: string[]) => void;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{
+        isPinned: boolean;
+    }]>;
+    /** App identifier for per-app preferences storage */
+    appId?: string;
     /** Additional classes */
     class?: string;
 }

package/dist/lib/components/layout/sidebar/SidebarNavItem.svelte

@@ -27,6 +27,12 @@
     icon?: Snippet<[NavItem]>;
     /** Search query for text highlighting */
     searchQuery?: string;
+    /** Enable pinning feature */
+    enablePinning?: boolean;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{ isPinned: boolean }]>;
+    /** Whether this item is rendered in the pinned section */
+    isPinnedSection?: boolean;
     /** Callback when item is clicked */
     onNavigate?: (item: NavItem) => void;
     /** Callback when mouse enters item (for flyout) */
@@ -42,6 +48,9 @@
     isMobile = false,
     icon,
     searchQuery = '',
+    enablePinning = false,
+    pinIcon,
+    isPinnedSection = false,
     onNavigate,
     onMouseEnter,
     onMouseLeave,
@@ -96,6 +105,21 @@
   function handleMouseEnter(e: MouseEvent) {
     onMouseEnter?.(item, e);
   }
+
+  // Pinning logic
+  const canBePinned = $derived(
+    enablePinning && item.pinnable !== false && !isPinnedSection && !collapsed
+  );
+  const isPinned = $derived(sidebarStore.isPinned(item.id));
+
+  // In pinned section, show unpin button
+  const showUnpinButton = $derived(enablePinning && isPinnedSection && !collapsed);
+
+  function handlePinToggle(e: MouseEvent | KeyboardEvent) {
+    e.preventDefault();
+    e.stopPropagation();
+    sidebarStore.togglePin(item.id);
+  }
 </script>
 
 <!-- Reusable snippets -->
@@ -158,6 +182,66 @@
   {/if}
 {/snippet}
 
+{#snippet pinButton(pinned: boolean, isUnpin: boolean = false)}
+  <button
+    type="button"
+    class={cn(
+      'flex items-center justify-center p-1 rounded transition-all shrink-0',
+      'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1',
+      // Show on hover for regular items, always show in pinned section
+      isUnpin ? 'opacity-100' : 'opacity-0 group-hover:opacity-100',
+      // Light variant: white text when row is hovered (teal bg), red/primary text when active
+      isLight && !item.active && 'text-muted-foreground group-hover:text-white hover:bg-white/20',
+      isLight && item.active && 'text-primary hover:bg-primary/20',
+      // Dark variant: white text when row is hovered
+      !isLight &&
+        !item.active &&
+        'text-sidebar-foreground/60 group-hover:text-white hover:bg-white/20',
+      !isLight && item.active && 'text-sidebar-primary-foreground hover:bg-white/20'
+    )}
+    onclick={handlePinToggle}
+    onkeydown={(e) => e.key === 'Enter' && handlePinToggle(e)}
+    aria-label={pinned ? `Unpin ${item.name}` : `Pin ${item.name}`}
+    title={pinned ? `Unpin ${item.name}` : `Pin ${item.name}`}
+  >
+    {#if pinIcon}
+      {@render pinIcon({ isPinned: pinned })}
+    {:else if pinned}
+      <!-- Filled pin icon (pinned) -->
+      <svg
+        class="h-4 w-4"
+        viewBox="0 0 24 24"
+        fill="currentColor"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
+        <line x1="12" x2="12" y1="17" y2="22" />
+        <path
+          d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24Z"
+        />
+      </svg>
+    {:else}
+      <!-- Outline pin icon (not pinned) -->
+      <svg
+        class="h-4 w-4"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+      >
+        <line x1="12" x2="12" y1="17" y2="22" />
+        <path
+          d="M5 17h14v-1.76a2 2 0 0 0-1.11-1.79l-1.78-.9A2 2 0 0 1 15 10.76V6h1a2 2 0 0 0 0-4H8a2 2 0 0 0 0 4h1v4.76a2 2 0 0 1-1.11 1.79l-1.78.9A2 2 0 0 0 5 15.24Z"
+        />
+      </svg>
+    {/if}
+  </button>
+{/snippet}
+
 {#if hasChildren && !collapsed}
   <!-- Item with children - expandable submenu -->
   <div>
@@ -259,6 +343,13 @@
           />
         </svg>
       </button>
+
+      <!-- Pin button for items with children -->
+      {#if canBePinned}
+        {@render pinButton(isPinned, false)}
+      {:else if showUnpinButton}
+        {@render pinButton(true, true)}
+      {/if}
     </div>
 
     {#if isExpanded}
@@ -300,80 +391,110 @@
   </div>
 {:else}
   <!-- Regular item or collapsed item -->
-  {#if item.href}
-    <!-- Item with href - render as link -->
-    <a
-      href={item.disabled ? undefined : item.href}
-      class={cn(
-        'flex items-center gap-3 rounded-md px-3 py-2 text-sm font-medium transition-colors overflow-hidden relative',
-        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1',
-        getItemStateClasses(item.active, item.disabled),
-        collapsed && !isMobile && 'justify-center px-2'
-      )}
-      target={item.external ? '_blank' : undefined}
-      rel={item.external ? 'noopener noreferrer' : undefined}
-      aria-current={item.active ? 'page' : undefined}
-      aria-disabled={item.disabled || undefined}
-      tabindex={item.disabled ? -1 : undefined}
-      title={collapsed && !isMobile
-        ? item.external
-          ? `${item.name} (opens in new tab)`
-          : item.name
-        : undefined}
-      onclick={handleClick}
-      onmouseenter={handleMouseEnter}
-      onmouseleave={onMouseLeave}
-    >
-      {@render navIcon(item)}
+  <!-- Wrap in group div for pin button hover behavior -->
+  <div
+    class={cn(
+      'group flex w-full items-center rounded-md transition-colors overflow-hidden',
+      isLight && !item.active && 'hover:bg-accent',
+      isLight && item.active && 'bg-primary/10',
+      !isLight && !item.active && 'hover:bg-sidebar-accent',
+      !isLight && item.active && 'bg-sidebar-primary'
+    )}
+  >
+    {#if item.href}
+      <!-- Item with href - render as link -->
+      <a
+        href={item.disabled ? undefined : item.href}
+        class={cn(
+          'flex flex-1 items-center gap-3 px-3 py-2 text-sm font-medium transition-colors overflow-hidden relative',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1',
+          isLight && !item.active && 'text-foreground group-hover:text-accent-foreground',
+          isLight && item.active && 'text-primary',
+          !isLight &&
+            !item.active &&
+            'text-sidebar-foreground group-hover:text-sidebar-accent-foreground',
+          !isLight && item.active && 'text-sidebar-primary-foreground',
+          item.disabled && 'opacity-50 pointer-events-none cursor-not-allowed',
+          collapsed && !isMobile && 'justify-center px-2'
+        )}
+        target={item.external ? '_blank' : undefined}
+        rel={item.external ? 'noopener noreferrer' : undefined}
+        aria-current={item.active ? 'page' : undefined}
+        aria-disabled={item.disabled || undefined}
+        tabindex={item.disabled ? -1 : undefined}
+        title={collapsed && !isMobile
+          ? item.external
+            ? `${item.name} (opens in new tab)`
+            : item.name
+          : undefined}
+        onclick={handleClick}
+        onmouseenter={handleMouseEnter}
+        onmouseleave={onMouseLeave}
+      >
+        {@render navIcon(item)}
 
-      {#if !collapsed || isMobile}
-        {@render highlightedName(item.name, itemHighlight)}
-        {@render navBadge(item.badge)}
-        {#if item.external}{@render externalIndicator()}{/if}
-      {/if}
+        {#if !collapsed || isMobile}
+          {@render highlightedName(item.name, itemHighlight)}
+          {@render navBadge(item.badge)}
+          {#if item.external}{@render externalIndicator()}{/if}
+        {/if}
 
-      <!-- Visual indicator for collapsed items with children -->
-      {#if collapsed && !isMobile && hasChildren}
-        <span class="absolute bottom-0.5 right-0.5">
-          <svg class="h-2 w-2 opacity-50" fill="currentColor" viewBox="0 0 8 8">
-            <path d="M0 0 L8 4 L0 8 Z" />
-          </svg>
-        </span>
-      {/if}
-    </a>
-  {:else}
-    <!-- Item without href (parent with children only, or action button) - render as button -->
-    <button
-      type="button"
-      class={cn(
-        'flex items-center gap-3 rounded-md px-3 py-2 text-sm font-medium transition-colors overflow-hidden w-full text-left relative',
-        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1',
-        getItemStateClasses(item.active, item.disabled),
-        collapsed && !isMobile && 'justify-center px-2'
-      )}
-      title={collapsed && !isMobile ? item.name : undefined}
-      aria-haspopup={hasChildren ? 'menu' : undefined}
-      aria-disabled={item.disabled || undefined}
-      disabled={item.disabled}
-      onclick={handleClick}
-      onmouseenter={handleMouseEnter}
-      onmouseleave={onMouseLeave}
-    >
-      {@render navIcon(item)}
+        <!-- Visual indicator for collapsed items with children -->
+        {#if collapsed && !isMobile && hasChildren}
+          <span class="absolute bottom-0.5 right-0.5">
+            <svg class="h-2 w-2 opacity-50" fill="currentColor" viewBox="0 0 8 8">
+              <path d="M0 0 L8 4 L0 8 Z" />
+            </svg>
+          </span>
+        {/if}
+      </a>
+    {:else}
+      <!-- Item without href (parent with children only, or action button) - render as button -->
+      <button
+        type="button"
+        class={cn(
+          'flex flex-1 items-center gap-3 px-3 py-2 text-sm font-medium transition-colors overflow-hidden text-left relative',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-1',
+          isLight && !item.active && 'text-foreground group-hover:text-accent-foreground',
+          isLight && item.active && 'text-primary',
+          !isLight &&
+            !item.active &&
+            'text-sidebar-foreground group-hover:text-sidebar-accent-foreground',
+          !isLight && item.active && 'text-sidebar-primary-foreground',
+          item.disabled && 'opacity-50 pointer-events-none cursor-not-allowed',
+          collapsed && !isMobile && 'justify-center px-2'
+        )}
+        title={collapsed && !isMobile ? item.name : undefined}
+        aria-haspopup={hasChildren ? 'menu' : undefined}
+        aria-disabled={item.disabled || undefined}
+        disabled={item.disabled}
+        onclick={handleClick}
+        onmouseenter={handleMouseEnter}
+        onmouseleave={onMouseLeave}
+      >
+        {@render navIcon(item)}
 
-      {#if !collapsed || isMobile}
-        {@render highlightedName(item.name, itemHighlight)}
-        {@render navBadge(item.badge)}
-      {/if}
+        {#if !collapsed || isMobile}
+          {@render highlightedName(item.name, itemHighlight)}
+          {@render navBadge(item.badge)}
+        {/if}
 
-      <!-- Visual indicator for collapsed items with children -->
-      {#if collapsed && !isMobile && hasChildren}
-        <span class="absolute bottom-0.5 right-0.5">
-          <svg class="h-2 w-2 opacity-50" fill="currentColor" viewBox="0 0 8 8">
-            <path d="M0 0 L8 4 L0 8 Z" />
-          </svg>
-        </span>
-      {/if}
-    </button>
-  {/if}
+        <!-- Visual indicator for collapsed items with children -->
+        {#if collapsed && !isMobile && hasChildren}
+          <span class="absolute bottom-0.5 right-0.5">
+            <svg class="h-2 w-2 opacity-50" fill="currentColor" viewBox="0 0 8 8">
+              <path d="M0 0 L8 4 L0 8 Z" />
+            </svg>
+          </span>
+        {/if}
+      </button>
+    {/if}
+
+    <!-- Pin button for regular items -->
+    {#if canBePinned}
+      {@render pinButton(isPinned, false)}
+    {:else if showUnpinButton}
+      {@render pinButton(true, true)}
+    {/if}
+  </div>
 {/if}

package/dist/lib/components/layout/sidebar/SidebarNavItem.svelte.d.ts

@@ -13,6 +13,14 @@ interface Props {
     icon?: Snippet<[NavItem]>;
     /** Search query for text highlighting */
     searchQuery?: string;
+    /** Enable pinning feature */
+    enablePinning?: boolean;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{
+        isPinned: boolean;
+    }]>;
+    /** Whether this item is rendered in the pinned section */
+    isPinnedSection?: boolean;
     /** Callback when item is clicked */
     onNavigate?: (item: NavItem) => void;
     /** Callback when mouse enters item (for flyout) */

package/dist/lib/components/layout/sidebar/SidebarSection.svelte

@@ -24,6 +24,12 @@
     icon?: Snippet<[NavItem]>;
     /** Search query for text highlighting */
     searchQuery?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{ isPinned: boolean }]>;
+    /** Whether this is the special pinned section */
+    isPinnedSection?: boolean;
     /** Callback when a navigation item is clicked */
     onNavigate?: (item: NavItem) => void;
     /** Callback when mouse enters an item (for flyout) */
@@ -39,6 +45,9 @@
     isMobile = false,
     icon,
     searchQuery = '',
+    enablePinning = false,
+    pinIcon,
+    isPinnedSection = false,
     onNavigate,
     onItemMouseEnter,
     onItemMouseLeave,
@@ -110,6 +119,9 @@
             {isMobile}
             {icon}
             {searchQuery}
+            {enablePinning}
+            {pinIcon}
+            {isPinnedSection}
             {onNavigate}
             onMouseEnter={onItemMouseEnter}
             onMouseLeave={onItemMouseLeave}
@@ -133,6 +145,9 @@
             {isMobile}
             {icon}
             {searchQuery}
+            {enablePinning}
+            {pinIcon}
+            {isPinnedSection}
             {onNavigate}
             onMouseEnter={onItemMouseEnter}
             onMouseLeave={onItemMouseLeave}

package/dist/lib/components/layout/sidebar/SidebarSection.svelte.d.ts

@@ -13,6 +13,14 @@ interface Props {
     icon?: Snippet<[NavItem]>;
     /** Search query for text highlighting */
     searchQuery?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{
+        isPinned: boolean;
+    }]>;
+    /** Whether this is the special pinned section */
+    isPinnedSection?: boolean;
     /** Callback when a navigation item is clicked */
     onNavigate?: (item: NavItem) => void;
     /** Callback when mouse enters an item (for flyout) */

package/dist/lib/index.d.ts

@@ -66,7 +66,7 @@ export { default as Header } from './components/layout/Header.svelte';
 export { default as Footer } from './components/layout/Footer.svelte';
 export { default as QuickLinks } from './components/layout/QuickLinks.svelte';
 export { default as HeaderSearch } from './components/HeaderSearch.svelte';
-export type { NavItem, NavSection, User, BackLink, QuickLink, QuickLinksProps, DashboardLayoutProps, PublicLayoutProps, AuthLayoutProps, AuthFooterLink, ErrorLayoutProps, FormPageLayoutProps, SidebarProps, HeaderProps, FooterProps, AppShellProps, SearchResultItem, SearchResultGroup, HeaderSearchConfig, } from './types/layout.js';
+export type { NavItem, NavSection, User, BackLink, QuickLink, QuickLinksProps, DashboardLayoutProps, PublicLayoutProps, AuthLayoutProps, AuthFooterLink, ErrorLayoutProps, FormPageLayoutProps, SidebarProps, SidebarPreferences, HeaderProps, FooterProps, AppShellProps, SearchResultItem, SearchResultGroup, HeaderSearchConfig, } from './types/layout.js';
 export { toastStore, type Toast as ToastType, type ToastInput } from './stores/toast.svelte.js';
 export { sidebarStore } from './stores/sidebar.svelte.js';
 export { themeStore, type ThemeMode } from './stores/theme.svelte.js';

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

@@ -1,12 +1,18 @@
 /**
  * Sidebar Store - Svelte 5 runes-based state management for sidebar
+ *
+ * Supports per-app preferences via appId parameter. When an appId is set,
+ * all localStorage keys are namespaced to that app, allowing different
+ * apps to have independent sidebar preferences for the same user.
  */
+import type { NavSection, SidebarPreferences } from '../types/layout.js';
 declare class SidebarStore {
     #private;
     isOpen: boolean;
     isMobile: boolean;
     expandedSections: Set<string>;
     expandedItems: Set<string>;
+    pinnedItems: Set<string>;
     /**
      * Whether the store has been initialized
      */
@@ -19,11 +25,22 @@ declare class SidebarStore {
      * Whether expansion state was loaded from localStorage
      */
     get hasPersistedExpansionState(): boolean;
+    /**
+     * Whether pinned state was loaded from localStorage
+     */
+    get hasPersistedPinnedState(): boolean;
     /**
      * Initialize store with persisted state.
      * Call this from a component's $effect to load saved state.
+     *
+     * @param appId - Optional app identifier for per-app preferences.
+     *                When provided, localStorage keys are namespaced to this app.
+     */
+    initialize(appId?: string): void;
+    /**
+     * Get the current app ID
      */
-    initialize(): void;
+    get appId(): string | undefined;
     /**
      * Toggle the sidebar open/closed state
      */
@@ -74,6 +91,45 @@ declare class SidebarStore {
      * This bypasses the persisted state check but doesn't persist the changes
      */
     forceExpandSections(sectionIds: string[]): void;
+    /**
+     * Set callback for when pinned items change (for external persistence)
+     */
+    setOnPinnedChange(callback: ((pinnedIds: string[]) => void) | undefined): void;
+    /**
+     * Initialize pinned items from external source (server hydration)
+     * This takes precedence over localStorage
+     */
+    initializePinnedItems(pinnedIds: string[]): void;
+    /**
+     * Pin a navigation item
+     */
+    pinItem(itemId: string): void;
+    /**
+     * Unpin a navigation item
+     */
+    unpinItem(itemId: string): void;
+    /**
+     * Toggle pin state of a navigation item
+     */
+    togglePin(itemId: string): void;
+    /**
+     * Check if an item is pinned
+     */
+    isPinned(itemId: string): boolean;
+    /**
+     * Get all pinned item IDs
+     */
+    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.
+     */
+    computeInitialExpansions(sections: NavSection[], userRoles?: string[]): string[];
+    /**
+     * Get current sidebar preferences for external persistence
+     */
+    getPreferences(): SidebarPreferences;
 }
 export declare const sidebarStore: SidebarStore;
 export {};

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

@@ -1,5 +1,9 @@
 /**
  * Sidebar Store - Svelte 5 runes-based state management for sidebar
+ *
+ * Supports per-app preferences via appId parameter. When an appId is set,
+ * all localStorage keys are namespaced to that app, allowing different
+ * apps to have independent sidebar preferences for the same user.
  */
 var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
     if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
@@ -12,10 +16,8 @@ var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (
     if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
     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_persist, _SidebarStore_persistExpansion;
-const STORAGE_KEY = 'classic-theme-sidebar-open';
-const SECTIONS_STORAGE_KEY = 'classic-theme-sidebar-sections';
-const ITEMS_STORAGE_KEY = 'classic-theme-sidebar-items';
+var _SidebarStore_instances, _SidebarStore_initialized, _SidebarStore_loadedFromStorage, _SidebarStore_loadedExpansionFromStorage, _SidebarStore_loadedPinnedFromStorage, _SidebarStore_onPinnedChange, _SidebarStore_appId, _SidebarStore_getStorageKey, _SidebarStore_persist, _SidebarStore_persistExpansion, _SidebarStore_persistPinned;
+const STORAGE_PREFIX = 'classic-theme-sidebar';
 class SidebarStore {
     constructor() {
         _SidebarStore_instances.add(this);
@@ -23,9 +25,13 @@ class SidebarStore {
         this.isMobile = $state(false);
         this.expandedSections = $state(new Set());
         this.expandedItems = $state(new Set());
+        this.pinnedItems = $state(new Set());
         _SidebarStore_initialized.set(this, false);
         _SidebarStore_loadedFromStorage.set(this, false);
         _SidebarStore_loadedExpansionFromStorage.set(this, false);
+        _SidebarStore_loadedPinnedFromStorage.set(this, false);
+        _SidebarStore_onPinnedChange.set(this, void 0);
+        _SidebarStore_appId.set(this, void 0);
     }
     /**
      * Whether the store has been initialized
@@ -45,38 +51,66 @@ class SidebarStore {
     get hasPersistedExpansionState() {
         return __classPrivateFieldGet(this, _SidebarStore_loadedExpansionFromStorage, "f");
     }
+    /**
+     * Whether pinned state was loaded from localStorage
+     */
+    get hasPersistedPinnedState() {
+        return __classPrivateFieldGet(this, _SidebarStore_loadedPinnedFromStorage, "f");
+    }
     /**
      * Initialize store with persisted state.
      * Call this from a component's $effect to load saved state.
+     *
+     * @param appId - Optional app identifier for per-app preferences.
+     *                When provided, localStorage keys are namespaced to this app.
      */
-    initialize() {
-        if (__classPrivateFieldGet(this, _SidebarStore_initialized, "f") || typeof window === 'undefined')
+    initialize(appId) {
+        // If appId changed, reset and reinitialize
+        if (__classPrivateFieldGet(this, _SidebarStore_initialized, "f") && __classPrivateFieldGet(this, _SidebarStore_appId, "f") === appId)
             return;
+        if (typeof window === 'undefined')
+            return;
+        __classPrivateFieldSet(this, _SidebarStore_appId, appId, "f");
         __classPrivateFieldSet(this, _SidebarStore_initialized, true, "f");
+        __classPrivateFieldSet(this, _SidebarStore_loadedFromStorage, false, "f");
+        __classPrivateFieldSet(this, _SidebarStore_loadedExpansionFromStorage, false, "f");
+        __classPrivateFieldSet(this, _SidebarStore_loadedPinnedFromStorage, false, "f");
         try {
             // Load sidebar open state
-            const stored = localStorage.getItem(STORAGE_KEY);
+            const stored = localStorage.getItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'open'));
             if (stored !== null) {
                 this.isOpen = stored === 'true';
                 __classPrivateFieldSet(this, _SidebarStore_loadedFromStorage, true, "f");
             }
             // Load expanded sections
-            const sections = localStorage.getItem(SECTIONS_STORAGE_KEY);
+            const sections = localStorage.getItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'sections'));
             if (sections) {
                 this.expandedSections = new Set(JSON.parse(sections));
                 __classPrivateFieldSet(this, _SidebarStore_loadedExpansionFromStorage, true, "f");
             }
             // Load expanded items
-            const items = localStorage.getItem(ITEMS_STORAGE_KEY);
+            const items = localStorage.getItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'items'));
             if (items) {
                 this.expandedItems = new Set(JSON.parse(items));
                 __classPrivateFieldSet(this, _SidebarStore_loadedExpansionFromStorage, true, "f");
             }
+            // Load pinned items
+            const pinned = localStorage.getItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'pinned'));
+            if (pinned) {
+                this.pinnedItems = new Set(JSON.parse(pinned));
+                __classPrivateFieldSet(this, _SidebarStore_loadedPinnedFromStorage, true, "f");
+            }
         }
         catch {
             // localStorage not available
         }
     }
+    /**
+     * Get the current app ID
+     */
+    get appId() {
+        return __classPrivateFieldGet(this, _SidebarStore_appId, "f");
+    }
     /**
      * Toggle the sidebar open/closed state
      */
@@ -184,12 +218,107 @@ class SidebarStore {
         this.expandedSections = newSet;
         // Don't persist - this is temporary for search
     }
+    // ============================================
+    // Pinning Methods
+    // ============================================
+    /**
+     * Set callback for when pinned items change (for external persistence)
+     */
+    setOnPinnedChange(callback) {
+        __classPrivateFieldSet(this, _SidebarStore_onPinnedChange, callback, "f");
+    }
+    /**
+     * Initialize pinned items from external source (server hydration)
+     * This takes precedence over localStorage
+     */
+    initializePinnedItems(pinnedIds) {
+        this.pinnedItems = new Set(pinnedIds);
+        __classPrivateFieldSet(this, _SidebarStore_loadedPinnedFromStorage, true, "f"); // Prevent localStorage override
+    }
+    /**
+     * Pin a navigation item
+     */
+    pinItem(itemId) {
+        const newSet = new Set(this.pinnedItems);
+        newSet.add(itemId);
+        this.pinnedItems = newSet;
+        __classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_persistPinned).call(this);
+    }
+    /**
+     * Unpin a navigation item
+     */
+    unpinItem(itemId) {
+        const newSet = new Set(this.pinnedItems);
+        newSet.delete(itemId);
+        this.pinnedItems = newSet;
+        __classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_persistPinned).call(this);
+    }
+    /**
+     * Toggle pin state of a navigation item
+     */
+    togglePin(itemId) {
+        if (this.pinnedItems.has(itemId)) {
+            this.unpinItem(itemId);
+        }
+        else {
+            this.pinItem(itemId);
+        }
+    }
+    /**
+     * Check if an item is pinned
+     */
+    isPinned(itemId) {
+        return this.pinnedItems.has(itemId);
+    }
+    /**
+     * Get all pinned item IDs
+     */
+    getPinnedIds() {
+        return [...this.pinnedItems];
+    }
+    // ============================================
+    // Role-based Section Expansion
+    // ============================================
+    /**
+     * 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.
+     */
+    computeInitialExpansions(sections, userRoles) {
+        return sections
+            .filter((section) => {
+            // Check role-based expansion first
+            if (section.expandForRoles?.length) {
+                return section.expandForRoles.some((role) => userRoles?.includes(role));
+            }
+            // Fall back to default behavior: expand unless explicitly collapsed
+            return !section.collapsible || section.expanded !== false;
+        })
+            .map((section) => section.id);
+    }
+    // ============================================
+    // Preferences Export
+    // ============================================
+    /**
+     * Get current sidebar preferences for external persistence
+     */
+    getPreferences() {
+        return {
+            pinnedItems: [...this.pinnedItems],
+            expandedSections: [...this.expandedSections],
+            expandedItems: [...this.expandedItems],
+        };
+    }
 }
-_SidebarStore_initialized = new WeakMap(), _SidebarStore_loadedFromStorage = new WeakMap(), _SidebarStore_loadedExpansionFromStorage = new WeakMap(), _SidebarStore_instances = new WeakSet(), _SidebarStore_persist = function _SidebarStore_persist() {
+_SidebarStore_initialized = new WeakMap(), _SidebarStore_loadedFromStorage = new WeakMap(), _SidebarStore_loadedExpansionFromStorage = new WeakMap(), _SidebarStore_loadedPinnedFromStorage = new WeakMap(), _SidebarStore_onPinnedChange = new WeakMap(), _SidebarStore_appId = new WeakMap(), _SidebarStore_instances = new WeakSet(), _SidebarStore_getStorageKey = function _SidebarStore_getStorageKey(suffix) {
+    return __classPrivateFieldGet(this, _SidebarStore_appId, "f")
+        ? `${STORAGE_PREFIX}-${__classPrivateFieldGet(this, _SidebarStore_appId, "f")}-${suffix}`
+        : `${STORAGE_PREFIX}-${suffix}`;
+}, _SidebarStore_persist = function _SidebarStore_persist() {
     if (typeof window === 'undefined')
         return;
     try {
-        localStorage.setItem(STORAGE_KEY, String(this.isOpen));
+        localStorage.setItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'open'), String(this.isOpen));
     }
     catch {
         // localStorage not available
@@ -198,11 +327,22 @@ _SidebarStore_initialized = new WeakMap(), _SidebarStore_loadedFromStorage = new
     if (typeof window === 'undefined')
         return;
     try {
-        localStorage.setItem(SECTIONS_STORAGE_KEY, JSON.stringify([...this.expandedSections]));
-        localStorage.setItem(ITEMS_STORAGE_KEY, JSON.stringify([...this.expandedItems]));
+        localStorage.setItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'sections'), JSON.stringify([...this.expandedSections]));
+        localStorage.setItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'items'), JSON.stringify([...this.expandedItems]));
+    }
+    catch {
+        // localStorage not available
+    }
+}, _SidebarStore_persistPinned = function _SidebarStore_persistPinned() {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        localStorage.setItem(__classPrivateFieldGet(this, _SidebarStore_instances, "m", _SidebarStore_getStorageKey).call(this, 'pinned'), JSON.stringify([...this.pinnedItems]));
     }
     catch {
         // localStorage not available
     }
+    // Notify external callback for server persistence
+    __classPrivateFieldGet(this, _SidebarStore_onPinnedChange, "f")?.call(this, [...this.pinnedItems]);
 };
 export const sidebarStore = new SidebarStore();

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

@@ -92,6 +92,8 @@ export interface NavItem {
     disabled?: boolean;
     /** Whether the item is in a loading state */
     loading?: boolean;
+    /** Whether this item can be pinned by users */
+    pinnable?: boolean;
 }
 /**
  * Navigation section for grouping nav items
@@ -107,6 +109,20 @@ export interface NavSection {
     collapsible?: boolean;
     /** Is section currently expanded (for collapsible sections) */
     expanded?: boolean;
+    /** Auto-expand this section for users with these roles */
+    expandForRoles?: string[];
+}
+/**
+ * Sidebar preferences for external persistence
+ * Used to save/restore user customizations like pinned items
+ */
+export interface SidebarPreferences {
+    /** IDs of pinned navigation items */
+    pinnedItems: string[];
+    /** IDs of expanded sections */
+    expandedSections: string[];
+    /** IDs of expanded items (items with children that are expanded) */
+    expandedItems: string[];
 }
 /**
  * User data for layout components
@@ -216,8 +232,22 @@ export interface DashboardLayoutProps {
     expandedWidth?: number;
     /** Sidebar width when collapsed in pixels (default: 64) */
     collapsedWidth?: number;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Title for the pinned items section (default: "Pinned") */
+    pinnedSectionTitle?: string;
+    /** Initial pinned item IDs for server hydration */
+    initialPinnedItems?: string[];
+    /** Callback when pinned items change (for external persistence) */
+    onPinnedChange?: (pinnedIds: string[]) => void;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{
+        isPinned: boolean;
+    }]>;
     /** Header search configuration */
     headerSearch?: HeaderSearchConfig;
+    /** App identifier for per-app sidebar preferences storage */
+    appId?: string;
     /** Main content */
     children: Snippet;
 }
@@ -292,6 +322,20 @@ export interface SidebarProps {
     searchable?: boolean;
     /** Placeholder text for search input */
     searchPlaceholder?: string;
+    /** Enable pinning feature for navigation items */
+    enablePinning?: boolean;
+    /** Title for the pinned items section (default: "Pinned") */
+    pinnedSectionTitle?: string;
+    /** Initial pinned item IDs for server hydration */
+    initialPinnedItems?: string[];
+    /** Callback when pinned items change (for external persistence) */
+    onPinnedChange?: (pinnedIds: string[]) => void;
+    /** Custom pin icon renderer */
+    pinIcon?: Snippet<[{
+        isPinned: boolean;
+    }]>;
+    /** App identifier for per-app sidebar preferences storage */
+    appId?: string;
     /** Additional classes */
     class?: string;
 }

package/package.json

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