tera-system-ui 0.1.70 → 0.1.72

package/dist/components/dialog/Dialog.d.ts

@@ -21,6 +21,8 @@ export type DialogProps = {
     padding?: 'none' | undefined;
     /** Whether clicking the backdrop closes the dialog. */
     closeOnClickOutside?: boolean;
+    /** Whether pressing the browser Back button closes the dialog. Default true. */
+    closeOnNavigateBack?: boolean;
     /** Whether to render a close (×) button in the header. */
     closeButton?: boolean;
     /**

package/dist/components/dialog/Dialog.svelte

@@ -1,7 +1,8 @@
 <script lang="ts">import { Dialog as DialogPrimitive } from 'bits-ui';
 import IconX from '../icons/IconX.svelte';
 import { cn } from '../../utils/index.js';
-let { children, open = $bindable(false), ref = $bindable(null), closeOnClickOutside = true, closeButton = true, size = 'sm', header, footer, class: className, position = 'center', padding, staticRender = false, preventScroll, onOpenChangeComplete, triggerRef, focusTriggerAfterClose = true, containerClass, headerClass, bodyClass, footerClass, ...props } = $props();
+import { closeOnBackNavigation } from '../../hooks';
+let { children, open = $bindable(false), ref = $bindable(null), closeOnClickOutside = true, closeOnNavigateBack = true, closeButton = true, size = 'sm', header, footer, class: className, position = 'center', padding, staticRender = false, preventScroll, onOpenChangeComplete, triggerRef, focusTriggerAfterClose = true, containerClass, headerClass, bodyClass, footerClass, ...props } = $props();
 const sizeClass = {
     xs: 'max-w-[min(24rem,calc(100vw-2rem))]',
     sm: 'max-w-[min(30rem,calc(100vw-2rem))]',
@@ -20,6 +21,11 @@ function handleCloseAutoFocus(e) {
         triggerRef.focus();
     }
 }
+closeOnBackNavigation({
+    enabled: () => closeOnNavigateBack,
+    isOpen: () => open,
+    close: () => { open = false; },
+});
 </script>
 
 <DialogPrimitive.Root bind:open onOpenChangeComplete={onOpenChangeComplete}>

package/dist/components/dialog/dialog.scss

@@ -1,184 +0,0 @@
-@reference "tailwindcss/theme";
-
-
-.dialog-box {
-    max-height: min(calc(100svh - 1rem), 55rem);
-    overflow-y: auto;
-    overscroll-behavior: contain;
-    display: grid;
-    grid-template-rows: auto 1fr auto;
-    width: 100%;
-    background: var(--color-surface);
-    border-radius: var(--border-radius-container);
-    position: relative;
-    top: 0;
-    left: 0;
-    bottom: 0;
-    main {
-        overflow: auto;
-    }
-}
-
-dialog, dialog:modal {
-    max-height: 100svh;
-    width: 100%;
-    height: fit-content;
-}
-
-dialog {
-    &[size="xs"] {
-        width: 24rem;
-        max-width: min(calc(100vw - 1rem), 24rem);
-    }
-
-    &[size="sm"] {
-        width: 30rem;
-        max-width: min(calc(100vw - 1rem), 30rem);
-    }
-
-    &[size="md"] {
-        width: 40rem;
-        max-width: min(calc(100vw - 1rem), 40rem);
-    }
-
-    &[size="lg"] {
-        width: 50rem;
-        max-width: min(calc(100vw - 1rem), 50rem);
-    }
-
-    &[size="full"] {
-        width: 100vw;
-        max-width: 100vw;
-        border-radius: 0;
-    }
-    &[size="auto"] {
-        width: fit-content;
-        max-width: 100vw;
-    }
-
-}
-
-dialog[open] {
-    display: inline-flex;
-}
-
-dialog {
-    --transition-duration: 0.25s;
-    --transition-easing: var(--ease-spring);
-    transform: translateY(0px);
-    margin: auto;
-    box-shadow: var(--shadow-lg);
-    border-radius: var(--border-radius-container);
-
-    &[data-position="top"] {
-        position: fixed;
-        top: 0;
-        left: 50%;
-        transform: translateX(-50%) translateY(0.5rem);
-        margin: 0;
-    }
-
-    &, &::backdrop {
-        transition: opacity var(--transition-duration) var(--transition-easing),
-        transform var(--transition-duration) var(--transition-easing),
-        display var(--transition-duration) allow-discrete,
-        overlay var(--transition-duration) allow-discrete,
-        box-shadow var(--transition-duration) var(--transition-easing);
-
-        opacity: 0;
-
-        will-change: transform, opacity, box-shadow;
-        backface-visibility: hidden;
-        -webkit-backface-visibility: hidden;
-    }
-
-
-    &[open] {
-        animation: dialog-enter var(--transition-duration) var(--transition-easing);
-        opacity: 1;
-        box-shadow: var(--shadow-lg);
-        &::backdrop {
-            opacity: 1;
-        }
-
-        &[data-position="top"] {
-            animation: slide-in-top var(--transition-duration) var(--transition-easing);
-        }
-    }
-
-    &:not([open]) {
-        animation: dialog-exit var(--transition-duration) var(--ease-ui);
-        opacity: 0;
-        box-shadow: var(--shadow-sm);
-        &::backdrop {
-            opacity: 0;
-        }
-
-        &[data-position="top"] {
-            animation: slide-out-top var(--transition-duration) var(--ease-ui);
-        }
-    }
-
-}
-
-@keyframes dialog-enter {
-    from {
-        transform: scale(0.95);
-        opacity: 0;
-    }
-    to {
-        transform: scale(1);
-        opacity: 1;
-    }
-}
-
-@keyframes dialog-exit {
-    from {
-        transform: scale(1);
-        opacity: 1;
-    }
-    to {
-        transform: scale(0.95);
-        opacity: 0;
-    }
-}
-
-@keyframes slide-in-top {
-    from {
-        top: 0;
-        left: 50%;
-        transform: translateX(-50%) translateY(-40px);
-        opacity: 0;
-        box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
-    }
-    to {
-        top: 0;
-        left: 50%;
-        transform: translateX(-50%) translateY(0.5rem);
-        opacity: 1;
-        box-shadow: 0 16px 48px rgba(0, 0, 0, 0.24), 0 8px 16px rgba(0, 0, 0, 0.12);
-    }
-}
-
-@keyframes slide-out-top {
-    from {
-        top: 0;
-        left: 50%;
-        transform: translateX(-50%) translateY(0.5rem);
-        opacity: 1;
-        box-shadow: 0 16px 48px rgba(0, 0, 0, 0.24), 0 8px 16px rgba(0, 0, 0, 0.12);
-    }
-    to {
-        top: 0;
-        left: 50%;
-        transform: translateX(-50%) translateY(-40px);
-        opacity: 0;
-        box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2);
-    }
-}
-
-dialog::backdrop {
-    backdrop-filter: blur(0.2rem);
-    background: --alpha(var(--color-neutral-token-13) / 20%);
-    transition: opacity var(--transition-duration) ease-out;
-}

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';
+export type { SideNavigationItem, SideNavigationGroup as SideNavigationGroupItem, SideNavigationEntry, SideNavigationProps } from "./SideNavigation";

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';

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/hooks/closeOnBackNavigation.svelte.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Closes an overlay (Dialog, Drawer, …) when the browser Back button is pressed,
+ * without ever navigating the real page away.
+ *
+ * While the overlay is open a *dummy* history entry (same URL) is pushed. Pressing
+ * Back pops that entry and closes the overlay; any other close path (Esc, click-outside,
+ * close button, programmatic `open = false`) silently removes the dummy entry again.
+ *
+ * Must live in a `.svelte.ts` module so it can use `$effect`, and must be called from a
+ * component init scope.
+ */
+export declare function closeOnBackNavigation(opts: {
+    /** Whether the behavior is enabled. */
+    enabled: () => boolean;
+    /** Current open state of the overlay. */
+    isOpen: () => boolean;
+    /** Close the overlay (e.g. set `open = false`). */
+    close: () => void;
+}): void;

package/dist/hooks/closeOnBackNavigation.svelte.js

@@ -0,0 +1,40 @@
+/**
+ * Closes an overlay (Dialog, Drawer, …) when the browser Back button is pressed,
+ * without ever navigating the real page away.
+ *
+ * While the overlay is open a *dummy* history entry (same URL) is pushed. Pressing
+ * Back pops that entry and closes the overlay; any other close path (Esc, click-outside,
+ * close button, programmatic `open = false`) silently removes the dummy entry again.
+ *
+ * Must live in a `.svelte.ts` module so it can use `$effect`, and must be called from a
+ * component init scope.
+ */
+let counter = 0; // module scope, monotonic per page load
+export function closeOnBackNavigation(opts) {
+    const id = `tera-overlay-${++counter}`;
+    let poppedByBack = false; // non-reactive guard
+    function handlePopState() {
+        // Our entry was popped only if the current top state is no longer ours.
+        if (opts.isOpen() && history.state?.__teraOverlayId !== id) {
+            poppedByBack = true;
+            opts.close();
+        }
+    }
+    $effect(() => {
+        if (!opts.enabled() || !opts.isOpen())
+            return;
+        // Opened → push a dummy entry (same URL); preserve any existing state keys
+        // (e.g. SvelteKit's own routing state).
+        history.pushState({ ...history.state, __teraOverlayId: id }, '');
+        window.addEventListener('popstate', handlePopState);
+        return () => {
+            window.removeEventListener('popstate', handlePopState);
+            if (poppedByBack) {
+                poppedByBack = false; // Back already removed the entry
+            }
+            else if (history.state?.__teraOverlayId === id) {
+                history.back(); // Esc / click-outside / × / programmatic → drop our entry
+            }
+        };
+    });
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1 @@
+export { closeOnBackNavigation } from './closeOnBackNavigation.svelte';

package/dist/hooks/index.js

@@ -0,0 +1 @@
+export { closeOnBackNavigation } from './closeOnBackNavigation.svelte';

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, SideNavigationGroup, 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/colors.md

@@ -23,11 +23,11 @@ Always use semantic tokens in components — never primitive shades.
 
   Tailwind utility      CSS variable               Primitive     Role
   ─────────────────────────────────────────────────────────────────────────
-  bg-surface            --color-surface            #FFFFFF   Page / app background
-  bg-surface-raised     --color-surface-raised     #FCFCFC   Cards, panels
-  bg-surface-sunken     --color-surface-sunken     #F5F5F5   Inputs (filled), disabled areas
-  bg-surface-hover      --color-surface-hover      #F0F0F0   Hover / pressed neutral bg
-  bg-surface-control    --color-surface-control    #FFFFFF   Interactive controls (button, input outlined, checkbox, select, slider)
+  bg-surface            --color-surface            #090909   Page / app background
+  bg-surface-raised     --color-surface-raised     #141414   Cards, panels
+  bg-surface-sunken     --color-surface-sunken     #202020   Inputs (filled), disabled areas
+  bg-surface-hover      --color-surface-hover      #303030   Hover / pressed neutral bg
+  bg-surface-control    --color-surface-control    #090909   Interactive controls (button, input outlined, checkbox, select, slider)
                                                              Light: same as page (white). Dark: elevated gray — sits above both page and dialogs.
                                                              Use this instead of bg-surface for any interactive control background.
 
@@ -35,17 +35,17 @@ Always use semantic tokens in components — never primitive shades.
 
   Tailwind utility      CSS variable               Primitive     Role
   ─────────────────────────────────────────────────────────────────────────
-  border-border-default --color-border-default     #D9D9D9   Default border
-  border-border-strong  --color-border-strong      #BFBFBF   Focus ring, separator
+  border-border-default --color-border-default     #464646   Default border
+  border-border-strong  --color-border-strong      #5F5F5F   Focus ring, separator
 
 ## Semantic Tokens — Text
 
   Tailwind utility      CSS variable               Primitive     Role
   ─────────────────────────────────────────────────────────────────────────
-  text-text-primary     --color-text-primary       #000000   Body text, headings
-  text-text-secondary   --color-text-secondary     #595959   Supporting / label text
+  text-text-primary     --color-text-primary       #FFFFFF   Body text, headings
+  text-text-secondary   --color-text-secondary     #BFBFBF   Supporting / label text
   text-text-tertiary    --color-text-tertiary      #8C8C8C   Placeholders, hints
-  text-text-disabled    --color-text-disabled      #BFBFBF   Disabled labels
+  text-text-disabled    --color-text-disabled      #5F5F5F   Disabled labels
 
 ## Semantic Tokens — Interactive (primary action)
 
@@ -102,15 +102,15 @@ Always use semantic tokens in components — never primitive shades.
 
   ### Neutral scale (inverts in dark mode)
 
-  neutral-token-1  = #FFFFFF  (white — page background)
-  neutral-token-2  = #FCFCFC
-  neutral-token-3  = #F5F5F5  (input / disabled bg)
-  neutral-token-4  = #F0F0F0  (hover state bg)
-  neutral-token-5  = #D9D9D9  (default border)
-  neutral-token-6  = #BFBFBF  (focus border / disabled text)
+  neutral-token-1  = #090909  (white — page background)
+  neutral-token-2  = #141414
+  neutral-token-3  = #202020  (input / disabled bg)
+  neutral-token-4  = #303030  (hover state bg)
+  neutral-token-5  = #464646  (default border)
+  neutral-token-6  = #5F5F5F  (focus border / disabled text)
   neutral-token-7  = #8C8C8C  (placeholder / hint)
-  neutral-token-8  = #595959  (secondary text)
-  neutral-token-13 = #000000  (primary text)
+  neutral-token-8  = #BFBFBF  (secondary text)
+  neutral-token-13 = #FFFFFF  (primary text)
 
   ### Primary (brand blue — changes per theme)
 

package/dist/llms/dialog.md

@@ -24,6 +24,7 @@ Built on BitsUI Dialog primitive.
   position                  'top' | 'center'                        optional  Vertical alignment of the dialog on screen.
   padding                   'none'                                  optional  Set to 'none' to remove internal padding.
   closeOnClickOutside       boolean                                 optional  Whether clicking the backdrop closes the dialog.
+  closeOnNavigateBack       boolean                                 optional  Whether pressing the browser Back button closes the dialog. Default true.
   closeButton               boolean                                 optional  Whether to render a close (×) button in the header.
   staticRender              boolean                                 optional  When true the dialog DOM is kept alive after close — children preserve internal state between open/close cycles.
   preventScroll             boolean                                 optional  Prevent the page from scrolling while the dialog is open.

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.70",
+  "version": "0.1.72",
   "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",