tera-system-ui 0.1.71 → 0.1.73

package/dist/components/side-navigation/SideNavigation.d.ts

@@ -1,20 +1,55 @@
 import { type VariantProps } from "tailwind-variants";
 import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
+/**
+ * App-shell sidebar navigation. Use `SideNavigationLayout` as the outermost wrapper of a page: it renders the fixed sidebar plus a content region for your `Header`, the page body, and optional bottom controls. `SideNavigation` is the bar itself and is normally driven through the layout. Wrap the app in `TeraUiContext` so `sideNavHref` (active route) and `language` are supplied globally, or pass them as props directly.
+ *
+ * The `items` prop is a single flat array that may MIX two shapes in any order: (1) a link item `{ href, title, icon?, exactHref? }` — a single navigable entry, where `exactHref` (falling back to `href`) is compared to the active route to apply the `selected` highlight; and (2) a group `{ id, title, items, defaultExpanded? }` — a collapsible section whose `items` are link items. A group renders a compact, fixed-height header (title + chevron, no icon) that expands/collapses its children; in the compact icon-only rail the header collapses to a thin divider so groups stay separated without large gaps, while keeping a stable height so items don't shift. Group children render with their own icons.
+ *
+ * Group expand/collapse state is PERSISTED to localStorage under the key `side-nav-group-state` (a JSON map of `{ [groupId]: boolean }`), keyed by the group's `id` — so `id` must be stable and unique. `defaultExpanded` only sets the initial state the first time a group `id` is seen (before any saved value exists). A group that contains the active route is always force-expanded on mount, regardless of saved state.
+ *
+ * If `items` is omitted, a built-in default navigation (calculator / converter / docs) is rendered. The sidebar's own expand vs. compact (icon-only) state is toggled by calling the exported `toggleSideNavigation()` (e.g. from a hamburger button) and is persisted at the xl breakpoint under localStorage key `side-nav-xl-state`; on smaller widths the bar is icon-only and temporarily expands on hover.
+ *
+ * Example: `<SideNavigationLayout items={[{ href: '/home', title: 'Home', icon: IconHome }, { id: 'tools', title: 'Tools', defaultExpanded: true, items: [{ href: '/calc', exactHref: '/calc', title: 'Calculator', icon: IconCalc }] }]}> <Header onHamburgerClick={toggleSideNavigation}>...</Header> <div>Page content</div> </SideNavigationLayout>`
+ */
 export declare const styles: import("tailwind-variants").TVReturnType<{}, undefined, "", {}, undefined, import("tailwind-variants").TVReturnType<{}, undefined, "", unknown, unknown, undefined>>;
 type SideNavigationVariants = VariantProps<typeof styles>;
+/** A single navigable link in the sidebar. */
 export type SideNavigationItem = {
+    /** Destination URL for the link. */
     href: string;
+    /** Route used for active-state matching; falls back to `href` when omitted. */
     exactHref?: string;
+    /** Icon component (e.g. a Tabler icon) rendered before the title. */
     icon?: any;
+    /** Visible label. */
     title: string;
 };
+/** A collapsible section grouping several link items under a header. */
+export type SideNavigationGroup = {
+    /** Stable, unique key — used to persist this group's expanded state in localStorage. */
+    id: string;
+    /** Header label (the group header shows title + chevron only, no icon). */
+    title: string;
+    /** Initial expanded state the first time the group is seen (before any saved value). */
+    defaultExpanded?: boolean;
+    /** Child links shown when the group is expanded. */
+    items: SideNavigationItem[];
+};
+/** An entry in the `items` array: either a flat link item or a collapsible group. */
+export type SideNavigationEntry = SideNavigationItem | SideNavigationGroup;
+/** Type guard: true when an entry is a {@link SideNavigationGroup} (has an `items` array). */
+export declare function isSideNavigationGroup(entry: SideNavigationEntry): entry is SideNavigationGroup;
 export interface SideNavigationProps extends HTMLAttributes<HTMLElement>, SideNavigationVariants {
     children?: Snippet;
     class?: string;
+    /** Current active route, used to highlight the matching item. Usually supplied via TeraUiContext. */
     sideNavHref?: string;
+    /** Active language code; localizes the built-in default nav links. Usually supplied via TeraUiContext. */
     language?: string;
-    items?: SideNavigationItem[];
+    /** Navigation entries: a flat array mixing link items ({ href, title, icon?, exactHref? }) and collapsible groups ({ id, title, items, defaultExpanded? }). Omit to render the built-in default nav. */
+    items?: SideNavigationEntry[];
+    /** Snippet rendered pinned at the bottom of the sidebar (e.g. a theme toggle). */
     bottomChildren?: Snippet;
     ref?: HTMLElement | null;
 }
@@ -24,6 +59,8 @@ export declare const SCREEN_BREAK_POINTS: {
     lg: number;
     xl: number;
 };
+export declare function loadGroupStates(): Record<string, boolean>;
+export declare function saveGroupStates(states: Record<string, boolean>): void;
 export declare function saveXlSideNavState(state: string | undefined): void;
 export declare function loadXlSideNavState(): string | undefined;
 export declare function restoreSideNavStateForXl(): void;

package/dist/components/side-navigation/SideNavigation.js

@@ -1,10 +1,25 @@
 import { tv } from "tailwind-variants";
+/**
+ * App-shell sidebar navigation. Use `SideNavigationLayout` as the outermost wrapper of a page: it renders the fixed sidebar plus a content region for your `Header`, the page body, and optional bottom controls. `SideNavigation` is the bar itself and is normally driven through the layout. Wrap the app in `TeraUiContext` so `sideNavHref` (active route) and `language` are supplied globally, or pass them as props directly.
+ *
+ * The `items` prop is a single flat array that may MIX two shapes in any order: (1) a link item `{ href, title, icon?, exactHref? }` — a single navigable entry, where `exactHref` (falling back to `href`) is compared to the active route to apply the `selected` highlight; and (2) a group `{ id, title, items, defaultExpanded? }` — a collapsible section whose `items` are link items. A group renders a compact, fixed-height header (title + chevron, no icon) that expands/collapses its children; in the compact icon-only rail the header collapses to a thin divider so groups stay separated without large gaps, while keeping a stable height so items don't shift. Group children render with their own icons.
+ *
+ * Group expand/collapse state is PERSISTED to localStorage under the key `side-nav-group-state` (a JSON map of `{ [groupId]: boolean }`), keyed by the group's `id` — so `id` must be stable and unique. `defaultExpanded` only sets the initial state the first time a group `id` is seen (before any saved value exists). A group that contains the active route is always force-expanded on mount, regardless of saved state.
+ *
+ * If `items` is omitted, a built-in default navigation (calculator / converter / docs) is rendered. The sidebar's own expand vs. compact (icon-only) state is toggled by calling the exported `toggleSideNavigation()` (e.g. from a hamburger button) and is persisted at the xl breakpoint under localStorage key `side-nav-xl-state`; on smaller widths the bar is icon-only and temporarily expands on hover.
+ *
+ * Example: `<SideNavigationLayout items={[{ href: '/home', title: 'Home', icon: IconHome }, { id: 'tools', title: 'Tools', defaultExpanded: true, items: [{ href: '/calc', exactHref: '/calc', title: 'Calculator', icon: IconCalc }] }]}> <Header onHamburgerClick={toggleSideNavigation}>...</Header> <div>Page content</div> </SideNavigationLayout>`
+ */
 export const styles = tv({
     base: '',
     variants: {},
     compoundVariants: [],
     defaultVariants: {},
 });
+/** Type guard: true when an entry is a {@link SideNavigationGroup} (has an `items` array). */
+export function isSideNavigationGroup(entry) {
+    return Array.isArray(entry.items);
+}
 export const SCREEN_BREAK_POINTS = {
     sm: 640,
     md: 768,
@@ -12,6 +27,19 @@ export const SCREEN_BREAK_POINTS = {
     xl: 1280,
 };
 const SIDE_NAV_XL_STATE_KEY = 'side-nav-xl-state';
+const SIDE_NAV_GROUP_STATE_KEY = 'side-nav-group-state';
+export function loadGroupStates() {
+    try {
+        const raw = localStorage.getItem(SIDE_NAV_GROUP_STATE_KEY);
+        return raw ? JSON.parse(raw) : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveGroupStates(states) {
+    localStorage.setItem(SIDE_NAV_GROUP_STATE_KEY, JSON.stringify(states));
+}
 export function saveXlSideNavState(state) {
     if (state === undefined) {
         localStorage.removeItem(SIDE_NAV_XL_STATE_KEY);

package/dist/components/side-navigation/SideNavigation.svelte

@@ -1,10 +1,11 @@
 <script lang="ts">import { onMount } from "svelte";
-import { mainLayout, SCREEN_BREAK_POINTS, setSideNavState, restoreSideNavStateForXl, toggleSideNavigation } from "./SideNavigation";
+import { mainLayout, SCREEN_BREAK_POINTS, setSideNavState, restoreSideNavStateForXl, isSideNavigationGroup, loadGroupStates, saveGroupStates, toggleSideNavigation } from "./SideNavigation";
 import { clickOutside } from "../../actions/clickOutside";
 import { Button } from "../button";
 import { IconCoinConvert, IconHamburger } from "../icons";
 import { BrandLogo } from "../brand-logo";
 import SideNavItem from "./SideNavigationItem.svelte";
+import SideNavGroup from "./SideNavigationGroup.svelte";
 import IconBook from "../icons/IconBook.svelte";
 import IconTransform from "../icons/IconTransform.svelte";
 import IconCalculator from "../icons/IconCalculator.svelte";
@@ -66,13 +67,32 @@ const NAV_ITEM = $derived(items ?? [
         title: m.text_calces_documentation(),
     },
 ]);
-let selectedIndex = (() => {
-    return NAV_ITEM.findIndex((item) => {
-        return (item.exactHref ?? item.href) === resolvedSideNavHref;
-    });
-})();
+function isSelected(item) {
+    return (item.exactHref ?? item.href) === resolvedSideNavHref;
+}
+let groupStates = $state({});
+function toggleGroup(id) {
+    groupStates[id] = !groupStates[id];
+    saveGroupStates(groupStates);
+}
 onMount(() => {
     restoreSideNavStateForXl();
+    const saved = loadGroupStates();
+    for (const entry of NAV_ITEM) {
+        if (!isSideNavigationGroup(entry))
+            continue;
+        const hasActiveChild = entry.items.some(isSelected);
+        if (entry.id in saved) {
+            groupStates[entry.id] = saved[entry.id];
+        }
+        else {
+            groupStates[entry.id] = entry.defaultExpanded ?? false;
+        }
+        // Force-expand the group containing the active route.
+        if (hasActiveChild) {
+            groupStates[entry.id] = true;
+        }
+    }
 });
 </script>
 
@@ -99,13 +119,24 @@ onMount(() => {
                 handleHover(false)
              }}
     >
-        {#each NAV_ITEM as item, index (item.href)}
-            <SideNavItem href={item.href} class={selectedIndex === index ? 'selected' : ''}>
-                {#snippet icon()}
-                    <item.icon/>
-                {/snippet}
-                {item.title}
-            </SideNavItem>
+        {#each NAV_ITEM as entry (isSideNavigationGroup(entry) ? entry.id : entry.href)}
+            {#if isSideNavigationGroup(entry)}
+                <SideNavGroup
+                        group={entry}
+                        expanded={groupStates[entry.id]}
+                        onToggle={() => toggleGroup(entry.id)}
+                        {isSelected}
+                />
+            {:else}
+                <SideNavItem href={entry.href} class={isSelected(entry) ? 'selected' : ''}>
+                    {#snippet icon()}
+                        {#if entry.icon}
+                            <entry.icon/>
+                        {/if}
+                    {/snippet}
+                    {entry.title}
+                </SideNavItem>
+            {/if}
         {/each}
     </ul>
     {@render bottomChildren?.()}

package/dist/components/side-navigation/SideNavigationGroup.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">import { slide } from "svelte/transition";
+import { IconChevronDown } from "../icons";
+import SideNavItem from "./SideNavigationItem.svelte";
+let { group, expanded = false, onToggle, isSelected, } = $props();
+</script>
+
+<li class="side-nav_group">
+    <button
+            type="button"
+            class="side-nav_item side-nav_group-header"
+            aria-expanded={expanded}
+            onclick={onToggle}
+    >
+        <span class="side-nav_group-divider" aria-hidden="true"></span>
+        <div class="sm-hidden z-10 truncate side-nav_group-title">
+            {group.title}
+        </div>
+        <div class="sm-hidden z-10 side-nav_group-chevron" data-expanded={expanded}>
+            <IconChevronDown/>
+        </div>
+    </button>
+
+    {#if expanded}
+        <ul class="side-nav_group-items" transition:slide={{duration: 200}}>
+            {#each group.items as item (item.href)}
+                <SideNavItem
+                        href={item.href}
+                        class={`side-nav_group-item ${isSelected(item) ? 'selected' : ''}`}
+                >
+                    {#snippet icon()}
+                        {#if item.icon}
+                            <item.icon/>
+                        {/if}
+                    {/snippet}
+                    {item.title}
+                </SideNavItem>
+            {/each}
+        </ul>
+    {/if}
+</li>

package/dist/components/side-navigation/SideNavigationGroup.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { SideNavigationGroup, SideNavigationItem } from "./SideNavigation";
+type $$ComponentProps = {
+    group: SideNavigationGroup;
+    expanded?: boolean;
+    onToggle: () => void;
+    isSelected: (item: SideNavigationItem) => boolean;
+};
+declare const SideNavigationGroup: import("svelte").Component<$$ComponentProps, {}, "">;
+type SideNavigationGroup = ReturnType<typeof SideNavigationGroup>;
+export default SideNavigationGroup;

package/dist/components/side-navigation/index.d.ts

@@ -1,4 +1,5 @@
 export { default as SideNavigation } from './SideNavigation.svelte';
 export { default as SideNavigationLayout } from './SideNavigationLayout.svelte';
-export { toggleSideNavigation } from './SideNavigation';
-export type { SideNavigationItem, SideNavigationProps } from "./SideNavigation";
+export { default as SideNavigationGroup } from './SideNavigationGroup.svelte';
+export { toggleSideNavigation, isSideNavigationGroup } from './SideNavigation.js';
+export type { SideNavigationItem, SideNavigationGroup as SideNavigationGroupItem, SideNavigationEntry, SideNavigationProps } from "./SideNavigation.js";

package/dist/components/side-navigation/index.js

@@ -1,3 +1,4 @@
 export { default as SideNavigation } from './SideNavigation.svelte';
 export { default as SideNavigationLayout } from './SideNavigationLayout.svelte';
-export { toggleSideNavigation } from './SideNavigation';
+export { default as SideNavigationGroup } from './SideNavigationGroup.svelte';
+export { toggleSideNavigation, isSideNavigationGroup } from './SideNavigation.js';

package/dist/components/side-navigation/sidenav.scss

@@ -163,3 +163,64 @@
         background-color: var(--color-surface-hover);
     }
 }
+
+.side-nav_group {
+    .side-nav_group-header {
+        position: relative;
+        display: flex;
+        gap: 0.5rem;
+        align-items: center;
+        width: 100%;
+        /* Fixed compact height: keeps child items from shifting up/down when the
+           panel collapses/expands, and tightens the gap between groups in the rail. */
+        height: 2rem;
+        white-space: nowrap;
+        padding-block: 0;
+        padding-inline: --spacing(3);
+        font-weight: var(--font-weight-normal);
+        color: var(--color-text-secondary);
+        cursor: pointer;
+        background: transparent;
+        border: none;
+        text-align: start;
+
+        &:hover {
+            background-color: var(--color-surface-hover);
+        }
+    }
+
+    /* In the compact (icon-only) panel the title + chevron fade out and this line
+       fades in — so a group header reads as a thin divider between item clusters.
+       It is the exact inverse of `.sm-hidden`, sharing the same container-query
+       threshold so the two always cross-fade. */
+    .side-nav_group-divider {
+        position: absolute;
+        left: --spacing(2);
+        right: --spacing(2);
+        top: 50%;
+        transform: translateY(-50%);
+        height: 1px;
+        background: var(--color-border-default);
+        opacity: 1;
+        transition: opacity var(--sidebar-transition-duration);
+        pointer-events: none;
+
+        @container (min-width: 3rem) {
+            opacity: 0;
+        }
+    }
+
+    .side-nav_group-title {
+        flex: 1;
+    }
+
+    .side-nav_group-chevron {
+        display: flex;
+        align-items: center;
+        transition: rotate var(--sidebar-transition-duration) var(--ease-ui);
+
+        &[data-expanded="true"] {
+            rotate: 180deg;
+        }
+    }
+}

package/dist/index.d.ts

@@ -23,7 +23,7 @@ export { FeatureCard, StatBlock, PricingCard, TestimonialCard } from './componen
 export { Popover } from './components/popover/index.js';
 export { PopoverResponsive } from './components/popover-responsive/index.js';
 export { Select } from './components/select/index.js';
-export { SideNavigation, SideNavigationLayout, toggleSideNavigation } from './components/side-navigation/index.js';
+export { SideNavigation, SideNavigationLayout, SideNavigationGroup } from './components/side-navigation/index.js';
 export { Skeleton } from './components/skeleton/index.js';
 export { Slider } from './components/slider/index.js';
 export { Spinner } from './components/spinner/index.js';
@@ -55,7 +55,7 @@ export type { LightDarkToggleProps } from './components/light-dark-toggle/index.
 export type { PopoverProps } from './components/popover/index.js';
 export type { PopoverResponsiveProps } from './components/popover-responsive/index.js';
 export type { SelectProps, SelectOption } from './components/select/index.js';
-export type { SideNavigationItem, SideNavigationProps } from './components/side-navigation/index.js';
+export type { SideNavigationItem, SideNavigationGroupItem, SideNavigationEntry, SideNavigationProps } from './components/side-navigation/index.js';
 export type { SliderProps } from './components/slider/index.js';
 export type { StarRatingProps } from './components/star-rating/index.js';
 export type { SwitchProps } from './components/switch/index.js';

package/dist/index.js

@@ -23,7 +23,7 @@ export { FeatureCard, StatBlock, PricingCard, TestimonialCard } from './componen
 export { Popover } from './components/popover/index.js';
 export { PopoverResponsive } from './components/popover-responsive/index.js';
 export { Select } from './components/select/index.js';
-export { SideNavigation, SideNavigationLayout, toggleSideNavigation } from './components/side-navigation/index.js';
+export { SideNavigation, SideNavigationLayout, SideNavigationGroup } from './components/side-navigation/index.js';
 export { Skeleton } from './components/skeleton/index.js';
 export { Slider } from './components/slider/index.js';
 export { Spinner } from './components/spinner/index.js';

package/dist/llms/side-navigation.md

@@ -1,10 +1,12 @@
 # SideNavigation
 
-Sidebar navigation. Parts: SideNavigation, SideNavigationItem, SideNavigationLayout.
+App-shell sidebar navigation with collapsible item groups (state persisted to localStorage). Parts: SideNavigationLayout (wrapper), SideNavigation (the bar), SideNavigationGroup, SideNavigationItem. Pass an `items` array mixing link items and groups.
+
+App-shell sidebar navigation. Use `SideNavigationLayout` as the outermost wrapper of a page: it renders the fixed sidebar plus a content region for your `Header`, the page body, and optional bottom controls. `SideNavigation` is the bar itself and is normally driven through the layout. Wrap the app in `TeraUiContext` so `sideNavHref` (active route) and `language` are supplied globally, or pass them as props directly. The `items` prop is a single flat array that may MIX two shapes in any order: (1) a link item `{ href, title, icon?, exactHref? }` — a single navigable entry, where `exactHref` (falling back to `href`) is compared to the active route to apply the `selected` highlight; and (2) a group `{ id, title, items, defaultExpanded? }` — a collapsible section whose `items` are link items. A group renders a compact, fixed-height header (title + chevron, no icon) that expands/collapses its children; in the compact icon-only rail the header collapses to a thin divider so groups stay separated without large gaps, while keeping a stable height so items don't shift. Group children render with their own icons. Group expand/collapse state is PERSISTED to localStorage under the key `side-nav-group-state` (a JSON map of `{ [groupId]: boolean }`), keyed by the group's `id` — so `id` must be stable and unique. `defaultExpanded` only sets the initial state the first time a group `id` is seen (before any saved value exists). A group that contains the active route is always force-expanded on mount, regardless of saved state. If `items` is omitted, a built-in default navigation (calculator / converter / docs) is rendered. The sidebar's own expand vs. compact (icon-only) state is toggled by calling the exported `toggleSideNavigation()` (e.g. from a hamburger button) and is persisted at the xl breakpoint under localStorage key `side-nav-xl-state`; on smaller widths the bar is icon-only and temporarily expands on hover. Example: `<SideNavigationLayout items={[{ href: '/home', title: 'Home', icon: IconHome }, { id: 'tools', title: 'Tools', defaultExpanded: true, items: [{ href: '/calc', exactHref: '/calc', title: 'Calculator', icon: IconCalc }] }]}> <Header onHamburgerClick={toggleSideNavigation}>...</Header> <div>Page content</div> </SideNavigationLayout>`
 
 ## Import
 
-  import { SideNavigation } from 'tera-system-ui';
+  import { SideNavigation, SideNavigationGroup } from 'tera-system-ui';
   import { SideNavigation } from 'tera-system-ui/side-navigation';  // subpath
 
 ## SideNavigation
@@ -15,10 +17,10 @@ Sidebar navigation. Parts: SideNavigation, SideNavigationItem, SideNavigationLay
   ──────────────────────────────────────────────────────────────────────────
   children                  Snippet                                 optional  
   class                     string                                  optional  
-  sideNavHref               string                                  optional  
-  language                  string                                  optional  
-  items                     SideNavigationItem[]                    optional  
-  bottomChildren            Snippet                                 optional  
+  sideNavHref               string                                  optional  Current active route, used to highlight the matching item. Usually supplied via TeraUiContext.
+  language                  string                                  optional  Active language code; localizes the built-in default nav links. Usually supplied via TeraUiContext.
+  items                     SideNavigationEntry[]                   optional  Navigation entries: a flat array mixing link items ({ href, title, icon?, exactHref? }) and collapsible groups ({ id, title, items, defaultExpanded? }). Omit to render the built-in default nav.
+  bottomChildren            Snippet                                 optional  Snippet rendered pinned at the bottom of the sidebar (e.g. a theme toggle).
   ref                       HTMLElement                             optional  (bindable)
 
 ### Usage
@@ -28,3 +30,22 @@ Sidebar navigation. Parts: SideNavigation, SideNavigationItem, SideNavigationLay
   </script>
 
   <SideNavigation>Content</SideNavigation>
+
+## SideNavigationGroup
+
+### Props
+
+  Name                      Type                                    Required
+  ──────────────────────────────────────────────────────────────────────────
+  group                     SideNavigationGroup                     required  
+  expanded                  boolean                                 optional  
+  onToggle                  () => void                              required  
+  isSelected                (item: SideNavigationItem) => boolean   required  
+
+### Usage
+
+  <script>
+    import { SideNavigationGroup } from 'tera-system-ui';
+  </script>
+
+  <SideNavigationGroup />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tera-system-ui",
-  "version": "0.1.71",
+  "version": "0.1.73",
   "scripts": {
     "dev": "vite dev",
     "build": "npm run customPrepublish && npm run generate-index && npm run generate-llms && vite build && npm run package && npm run copy-docs && npm run copy-llms && npm run postpublish",

package/scripts/generate-ts-index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import fs from "fs";
 
 import path from "path";
@@ -65,7 +65,10 @@ function extractExportNames(filePath) {
 
     // Find all matches for `export type { ... }`
     while ((match = typeExportRegex.exec(fileContent)) !== null) {
-        const typeNames = match[1].split(',').map(t => t.trim().split(/\s+as\s+/)[0].trim()).filter(t => t);
+        const typeNames = match[1].split(',').map(t => {
+            const parts = t.trim().split(/\s+as\s+/);
+            return (parts[1] || parts[0]).trim();
+        }).filter(t => t);
         types.push(...typeNames);
     }