zabi-components 7.0.1 → 8.0.0

package/dist/organisms/SidebarNavigation.svelte

@@ -6,6 +6,8 @@
     import SidebarBrandHeader from "../molecules/SidebarBrandHeader.svelte";
     import SidebarFooter from "../molecules/SidebarFooter.svelte";
     import SidebarNavSection from "../molecules/SidebarNavSection.svelte";
+    import Tooltip from "../atoms/Tooltip.svelte";
+    import SidebarShell from "./SidebarShell.svelte";
     import { Command, Search } from "@lucide/svelte";
     import type { Snippet } from "svelte";
     import type { Component } from "svelte";
@@ -34,6 +36,8 @@
         items?: SidebarNavigationItem[];
         currentPath?: string;
         ariaLabel?: string;
+        class?: string;
+        /** @deprecated use `class`. */
         className?: string;
         logoSrc?: string;
         logoAlt?: string;
@@ -78,7 +82,8 @@
         currentPath = "",
         activePrimaryHref = "",
         ariaLabel = "Sidebar navigation",
-        className = "",
+        class: classAttr = "",
+        className: legacyClass = "",
         logoSrc = "",
         logoAlt = "",
         brandName = "",
@@ -113,8 +118,10 @@
         ...restProps
     }: Props = $props();
 
+    /** `class` is the public prop; `className` is a deprecated alias.
+     * Both are merged here so existing call sites keep working. */
+
     const isCollapsed = $derived(mode === "collapsed");
-    const isCard = $derived(layout === "card");
     const showBrandRow = $derived(
         Boolean(logoSrc.trim() || brandName.trim()),
     );
@@ -178,24 +185,6 @@
         partitionBySection(filteredPrimaryItems),
     );
 
-    const insetX = $derived(isCollapsed ? "px-2.5" : "px-4");
-
-    const containerClasses = $derived.by(() => {
-        const widthClass = isCollapsed ? "w-[104px]" : "w-[266px]";
-        const railSurface = "border-r border-border bg-background text-headline";
-        const cardSurface =
-            "border-r border-border bg-background text-headline shadow-sm";
-        const surfaceClasses = isCard ? cardSurface : railSurface;
-        const verticalPad = isCard ? "py-4" : "py-5";
-        const baseClasses = `flex h-full min-h-0 max-h-full flex-col overflow-visible ${verticalPad}`;
-
-        return `${baseClasses} ${widthClass} ${surfaceClasses} ${className}`.trim();
-    });
-
-    const headerStackClasses = $derived(
-        `flex w-full shrink-0 flex-col gap-5 ${insetX}`,
-    );
-
     const iconContainerClasses = $derived(
         "flex size-6 shrink-0 items-center justify-center leading-none text-current",
     );
@@ -210,21 +199,43 @@
         return isMuted ? "text-description" : "text-headline";
     }
 
-    function getNavItemClasses(item: SidebarNavigationItem): string {
-        const isActive =
+    /**
+     * The selected row used to be carried by its fill alone, and the fill was
+     * 1.05:1 against the sidebar in light mode — not a fill, a rumour. Active
+     * and idle labels were #18181b and #27272a at the same weight, a 15-unit
+     * difference in one channel that nobody can see. So in light mode there
+     * was effectively no indication of where you were.
+     *
+     * Three cues now, only one of which is colour-discrimination dependent:
+     * the label takes --color-nav-menu-item-active (defined all along and
+     * never referenced — the row said `text-inherit`), a 3px bar marks the
+     * leading edge, and the tint stays as reinforcement rather than as the
+     * whole message.
+     */
+    function isItemActive(item: SidebarNavigationItem): boolean {
+        return (
             currentPath === item.href ||
-            (Boolean(activePrimaryHref) && item.href === activePrimaryHref);
+            (Boolean(activePrimaryHref) && item.href === activePrimaryHref)
+        );
+    }
+
+    function getNavItemClasses(item: SidebarNavigationItem): string {
+        const isActive = isItemActive(item);
         const layoutClasses = isCollapsed
             ? "flex min-h-10 items-center justify-center px-0 py-2"
-            : "flex min-h-10 items-center gap-2.5 px-2.5 py-2";
+            : "flex min-h-10 items-center gap-3 px-2 py-2";
         const structural =
-            "focus-ring focus-ring--nav w-full cursor-pointer rounded-lg no-underline transition-colors duration-150 outline-none";
+            "focus-ring focus-ring--nav relative w-full cursor-pointer rounded-control no-underline transition-colors duration-150 outline-none";
 
         if (isActive) {
-            return `${structural} ${layoutClasses} bg-nav-menu-active text-inherit hover:bg-nav-menu-active hover:text-inherit active:opacity-90`;
+            return (
+                `${structural} ${layoutClasses} bg-nav-menu-active ` +
+                "text-nav-menu-item-active hover:bg-nav-menu-active " +
+                "active:bg-nav-menu-active-hover"
+            );
         }
 
-        return `${structural} ${layoutClasses} text-nav-menu-item hover:bg-nav-menu-hover hover:text-nav-menu-item-hover active:bg-base-200`;
+        return `${structural} ${layoutClasses} text-nav-menu-item hover:bg-nav-menu-hover hover:text-nav-menu-item-hover active:bg-surface-active`;
     }
 
     function handleNavigate(item: SidebarNavigationItem, event: MouseEvent) {
@@ -268,11 +279,15 @@
     }
 </script>
 
-<nav class={containerClasses} aria-label={ariaLabel} {...restProps}>
-    <div
-        class="flex min-h-0 w-full min-w-0 flex-1 flex-col"
-    >
-        <div class={`${headerStackClasses} pb-3`.trim()}>
+<SidebarShell
+    {mode}
+    {layout}
+    {ariaLabel}
+    class={classAttr}
+    className={legacyClass}
+    {...restProps}
+>
+    {#snippet header()}
             {#if showBrandRow}
                 <SidebarBrandHeader
                     collapsed={isCollapsed}
@@ -307,10 +322,10 @@
                             <Button
                                 variant={searchTriggerVariant}
                                 size={searchTriggerSize}
-                                isFullWidth
+                                fullWidth
                                 onclick={handleSearchClick}
                             >
-                                <span class="flex w-full items-center justify-start gap-2.5">
+                                <span class="flex w-full items-center justify-start gap-3">
                                     <span class={iconContainerClasses} aria-hidden="true">
                                         <TriggerIcon size={17} />
                                     </span>
@@ -334,18 +349,13 @@
                             bind:value={searchValue}
                             placeholder={searchPlaceholder}
                             aria-label={searchPlaceholder}
-                            class="focus-ring focus-ring--nav w-full min-w-0 min-h-10 rounded-xl border-transparent !bg-transparent py-2 pl-10 text-sm ring-1 ring-border/60 hover:!bg-nav-menu-hover focus:!bg-transparent"
+                            class="focus-ring focus-ring--nav w-full min-w-0 min-h-10 rounded-container border-transparent !bg-transparent py-2 pl-10 text-sm ring-1 ring-border/60 hover:!bg-nav-menu-hover focus:!bg-transparent"
                         />
                     </div>
                 {/if}
             {/if}
-        </div>
+    {/snippet}
 
-        <div
-            class={`flex min-h-0 min-w-0 flex-1 flex-col gap-3 overflow-y-auto overflow-x-hidden overscroll-y-contain pt-4 pb-1.5 ${insetX}`}
-            role="region"
-            aria-label="Navigation links"
-        >
         {#if hasFilteredItems}
             <div
                 class="flex w-full min-w-0 flex-col divide-y divide-border"
@@ -363,6 +373,19 @@
                             {#each group.items as item (item.id)}
                                 {@const Icon = item.icon}
                                 <li>
+                                    <!--
+                                      Collapsed rows are icon-only. aria-label
+                                      covers screen readers, but a sighted user
+                                      got an unlabelled glyph with no hover
+                                      affordance at all.
+                                    -->
+                                    <Tooltip
+                                        content={item.label}
+                                        placement="right"
+                                        disabled={!isCollapsed}
+                                        block
+                                        fixed
+                                    >
                                     <a
                                         href={item.href}
                                         class={getNavItemClasses(item)}
@@ -370,6 +393,12 @@
                                         aria-current={getAriaCurrent(item)}
                                         aria-label={isCollapsed ? item.label : undefined}
                                     >
+                                        {#if isItemActive(item)}
+                                            <span
+                                                class="absolute left-0 top-1/2 h-5 w-[3px] -translate-y-1/2 rounded-pill bg-nav-menu-item-active"
+                                                aria-hidden="true"
+                                            ></span>
+                                        {/if}
                                         {#if Icon}
                                             <span
                                                 class={iconContainerClasses}
@@ -384,16 +413,31 @@
                                                 >{item.label}</span
                                             >
                                         {/if}
-                                        {#if !isCollapsed && getItemBadgeText(item) !== null}
-                                            <span class="ml-auto">
-                                                <Badge
-                                                    variant="default"
-                                                    size="sm"
-                                                    text={getItemBadgeText(item) ?? ""}
-                                                />
-                                            </span>
+                                        {#if getItemBadgeText(item) !== null}
+                                            {#if isCollapsed}
+                                                <!--
+                                                  A notification count that
+                                                  disappears when you collapse
+                                                  the rail is a real loss; the
+                                                  count becomes a dot rather
+                                                  than nothing.
+                                                -->
+                                                <span
+                                                    class="absolute right-2 top-2 size-2 rounded-pill bg-error"
+                                                    aria-hidden="true"
+                                                ></span>
+                                            {:else}
+                                                <span class="ml-auto">
+                                                    <Badge
+                                                        variant="default"
+                                                        size="sm"
+                                                        text={getItemBadgeText(item) ?? ""}
+                                                    />
+                                                </span>
+                                            {/if}
                                         {/if}
                                     </a>
+                                    </Tooltip>
                                 </li>
                             {/each}
                         </SidebarNavSection>
@@ -446,7 +490,7 @@
             {/if}
         {:else}
             <div
-                class="rounded-xl border border-border border-dashed bg-transparent px-3.5 py-4 ring-1 ring-border/60"
+                class="rounded-container border border-border border-dashed bg-transparent px-4 py-4 ring-1 ring-border/60"
             >
                 <h3 class="text-sm font-semibold {getTextToneClass()}">
                     {normalizedSearchTerm && searchMode === "input"
@@ -461,7 +505,7 @@
                 {#if !(normalizedSearchTerm && searchMode === "input")}
                     <button
                         type="button"
-                        class="focus-ring focus-ring--nav mt-3 inline-flex min-h-10 cursor-pointer items-center rounded-lg bg-action-primary px-3 py-2 text-sm font-medium text-action-primary outline-none transition-colors hover:bg-action-primary-hover"
+                        class="focus-ring focus-ring--nav mt-3 inline-flex min-h-10 cursor-pointer items-center rounded-control bg-action-primary px-3 py-2 text-sm font-medium text-action-primary outline-none transition-colors hover:bg-action-primary-hover"
                         onclick={handleEmptyStateAction}
                     >
                         {emptyStateActionLabel}
@@ -469,11 +513,9 @@
                 {/if}
             </div>
         {/if}
-        </div>
-    </div>
-
-    <SidebarFooter
-        collapsed={isCollapsed}
+    {#snippet footer({ insetX })}
+        <SidebarFooter
+            collapsed={isCollapsed}
         {showProfile}
         {profileName}
         {profileEmail}
@@ -489,6 +531,7 @@
         {profilePanelOpen}
         {profilePanelControlsId}
         {profilePanel}
-        className={insetX}
-    />
-</nav>
+            className={insetX}
+        />
+    {/snippet}
+</SidebarShell>

package/dist/organisms/SidebarNavigation.svelte.d.ts

@@ -21,6 +21,8 @@ interface Props {
     items?: SidebarNavigationItem[];
     currentPath?: string;
     ariaLabel?: string;
+    class?: string;
+    /** @deprecated use `class`. */
     className?: string;
     logoSrc?: string;
     logoAlt?: string;

package/dist/organisms/SidebarPanel.svelte

@@ -3,6 +3,7 @@
     import Badge from "../atoms/Badge.svelte";
     import { Search, X } from "@lucide/svelte";
     import type { Component } from "svelte";
+    import { cn } from "../util/cn.js";
 
     export interface SidebarPanelItem {
         id: string;
@@ -13,6 +14,8 @@
     }
 
     interface Props {
+        class?: string;
+        /** @deprecated use `class`. */
         className?: string;
         widthClass?: string;
         variant?: "plain" | "elevated";
@@ -35,7 +38,8 @@
     }
 
     let {
-        className = "",
+        class: classAttr = "",
+        className: legacyClass = "",
         widthClass = "w-80",
         variant = "elevated",
         ariaLabel = "Picker panel",
@@ -57,6 +61,10 @@
         ...restProps
     }: Props = $props();
 
+    /** `class` is the public prop; `className` is a deprecated alias.
+     * Both are merged here so existing call sites keep working. */
+    const className = $derived(cn(`${classAttr} ${legacyClass}`));
+
     const normalizedSearchTerm = $derived(searchValue.trim().toLowerCase());
     const filteredItems = $derived(
         normalizedSearchTerm
@@ -71,19 +79,19 @@
     const containerClasses = $derived.by(() => {
         const resolvedWidthClass = widthClass.trim() || "w-80";
         const shell = isElevated
-            ? "rounded-3xl border border-border bg-card text-headline shadow-md ring-1 ring-border/50"
-            : "rounded-3xl border border-border bg-card text-headline shadow-sm";
-        return `${resolvedWidthClass} shrink-0 p-5 ${shell} ${className}`.trim();
+            ? "rounded-container border border-border bg-card text-headline shadow-sm ring-1 ring-border/50"
+            : "rounded-container border border-border bg-card text-headline shadow-sm";
+        return cn(`${resolvedWidthClass} shrink-0 p-5 ${shell} ${className}`);
     });
 
     function getItemClasses(itemId: string): string {
         const isActive = selectedItemId === itemId;
         const baseClasses =
-            "focus-ring focus-ring--nav w-full cursor-pointer rounded-lg px-3 py-2.5 text-left transition-colors duration-150";
+            "focus-ring focus-ring--nav w-full cursor-pointer rounded-control px-3 py-2 text-left transition-colors duration-150";
         if (isActive) {
             return `${baseClasses} bg-nav-menu-active text-inherit shadow-sm ring-1 ring-border/80`;
         }
-        return `${baseClasses} text-nav-menu-item hover:bg-nav-menu-hover hover:text-nav-menu-item-hover active:bg-base-200`;
+        return `${baseClasses} text-nav-menu-item hover:bg-nav-menu-hover hover:text-nav-menu-item-hover active:bg-surface-active`;
     }
 
     function handleSelect(item: SidebarPanelItem): void {
@@ -116,7 +124,7 @@
         </div>
         <button
             type="button"
-            class="-mr-0.5 -mt-0.5 inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-lg text-nav-menu-item transition-colors hover:bg-nav-menu-hover hover:text-nav-menu-item-hover focus-ring focus-ring--nav"
+            class="-mr-0.5 -mt-0.5 inline-flex size-9 shrink-0 cursor-pointer items-center justify-center rounded-control text-nav-menu-item transition-colors hover:bg-nav-menu-hover hover:text-nav-menu-item-hover focus-ring focus-ring--nav"
             aria-label={closeLabel}
             onclick={handleClose}
         >
@@ -137,7 +145,7 @@
                 bind:value={searchValue}
                 placeholder={searchPlaceholder}
                 aria-label={searchPlaceholder}
-                class="w-full min-w-0 min-h-10 rounded-xl border-transparent !bg-transparent py-2 pl-10 text-sm ring-1 ring-border/60 hover:!bg-nav-menu-hover focus:!bg-transparent focus-ring focus-ring--nav"
+                class="w-full min-w-0 min-h-10 rounded-container border-transparent !bg-transparent py-2 pl-10 text-sm ring-1 ring-border/60 hover:!bg-nav-menu-hover focus:!bg-transparent focus-ring focus-ring--nav"
             />
         </div>
     {/if}
@@ -154,7 +162,7 @@
                         aria-selected={selectedItemId === item.id}
                     >
                         <span class="flex items-center justify-between gap-3">
-                            <span class="flex min-w-0 items-start gap-2.5">
+                            <span class="flex min-w-0 items-start gap-3">
                                 {#if item.icon}
                                     {@const Icon = item.icon}
                                     <span
@@ -189,14 +197,14 @@
         </ul>
     {:else}
         <div
-            class="rounded-xl border border-dashed border-border bg-transparent px-3.5 py-4 ring-1 ring-border/40"
+            class="rounded-container border border-dashed border-border bg-transparent px-4 py-4 ring-1 ring-border/40"
         >
             <h4 class="text-sm font-semibold text-headline">{emptyStateTitle}</h4>
             <p class="mt-1 text-sm leading-relaxed text-description">{emptyStateDescription}</p>
             {#if emptyStateActionLabel.trim() && onEmptyStateAction}
                 <button
                     type="button"
-                    class="mt-3 inline-flex min-h-10 cursor-pointer items-center rounded-lg bg-action-primary px-3 py-2 text-sm font-medium text-action-primary transition-colors hover:bg-action-primary-hover focus-ring focus-ring--nav"
+                    class="mt-3 inline-flex min-h-10 cursor-pointer items-center rounded-control bg-action-primary px-3 py-2 text-sm font-medium text-action-primary transition-colors hover:bg-action-primary-hover focus-ring focus-ring--nav"
                     onclick={handleEmptyStateAction}
                 >
                     {emptyStateActionLabel.trim()}

package/dist/organisms/SidebarPanel.svelte.d.ts

@@ -10,6 +10,8 @@ export interface SidebarPanelItem {
     badgeText?: string;
 }
 interface Props {
+    class?: string;
+    /** @deprecated use `class`. */
     className?: string;
     widthClass?: string;
     variant?: "plain" | "elevated";

package/dist/organisms/SidebarShell.svelte

@@ -0,0 +1,112 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import { cn } from "../util/cn.js";
+
+    /**
+     * The chrome of a sidebar and nothing else: width, surface, collapse
+     * behaviour, the inset its regions share, and a scroll container for the
+     * middle.
+     *
+     * `SidebarNavigation` is a fully-specified sidebar driven by ~44 props —
+     * excellent when your sidebar looks like that one, useless when it does
+     * not, because the parts are not reachable. This is the same shell with
+     * the regions left open, so you can drop in `SidebarBrandHeader`,
+     * `SidebarNavSection` and `SidebarFooter` (or your own markup) and skip
+     * the props you would never set.
+     *
+     * `SidebarNavigation` is built on it, so the two cannot drift apart.
+     *
+     * ```svelte
+     * <SidebarShell mode="collapsed">
+     *     {#snippet header({ collapsed })}
+     *         <SidebarBrandHeader {collapsed} brandName="Zabi" />
+     *     {/snippet}
+     *     <SidebarNavSection title="Main" sectionKey="main">…</SidebarNavSection>
+     *     {#snippet footer({ collapsed, insetX })}
+     *         <SidebarFooter {collapsed} className={insetX} />
+     *     {/snippet}
+     * </SidebarShell>
+     * ```
+     */
+
+    /** Passed to every region so it can match the shell's collapse and inset. */
+    export interface SidebarRegionContext {
+        collapsed: boolean;
+        /** Horizontal padding utility the shell's own regions use. */
+        insetX: string;
+    }
+
+    type Props = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+        mode?: "expanded" | "collapsed";
+        /** `rail` attaches to the viewport edge; `card` is a floating panel. */
+        layout?: "rail" | "card";
+        ariaLabel?: string;
+        class?: string;
+        /** @deprecated use `class`. */
+        className?: string;
+        /** Brand row, search — anything above the scrolling nav area. */
+        header?: Snippet<[SidebarRegionContext]>;
+        /** The scrolling middle. */
+        children?: Snippet<[SidebarRegionContext]>;
+        /** Account row, logout, theme toggle. Outside the scroll container. */
+        footer?: Snippet<[SidebarRegionContext]>;
+    };
+
+    let {
+        mode = "expanded",
+        layout = "rail",
+        ariaLabel = "Sidebar navigation",
+        class: classAttr = "",
+        className: legacyClass = "",
+        header,
+        children,
+        footer,
+        ...restProps
+    }: Props = $props();
+
+    const className = $derived(cn(classAttr, legacyClass));
+    const isCollapsed = $derived(mode === "collapsed");
+    const isCard = $derived(layout === "card");
+
+    const insetX = $derived(isCollapsed ? "px-2" : "px-4");
+
+    const containerClasses = $derived.by(() => {
+        const widthClass = isCollapsed ? "w-[72px]" : "w-[266px]";
+        const railSurface = "border-r border-border bg-background text-headline";
+        const cardSurface =
+            "border-r border-border bg-background text-headline shadow-sm";
+        const surfaceClasses = isCard ? cardSurface : railSurface;
+        const verticalPad = isCard ? "py-4" : "py-5";
+        const baseClasses = `flex h-full min-h-0 max-h-full flex-col overflow-visible ${verticalPad}`;
+
+        return cn(`${baseClasses} ${widthClass} ${surfaceClasses} ${className}`);
+    });
+
+    const region = $derived({ collapsed: isCollapsed, insetX });
+</script>
+
+<nav class={containerClasses} aria-label={ariaLabel} {...restProps}>
+    <div class="flex min-h-0 w-full min-w-0 flex-1 flex-col">
+        {#if header}
+            <div class={cn("flex w-full shrink-0 flex-col gap-5 pb-3", insetX)}>
+                {@render header(region)}
+            </div>
+        {/if}
+
+        <div
+            class={cn(
+                "flex min-h-0 min-w-0 flex-1 flex-col gap-3 overflow-y-auto overflow-x-hidden overscroll-y-contain pt-4 pb-2",
+                insetX,
+            )}
+            role="region"
+            aria-label="Navigation links"
+        >
+            {@render children?.(region)}
+        </div>
+    </div>
+
+    {#if footer}
+        {@render footer(region)}
+    {/if}
+</nav>

package/dist/organisms/SidebarShell.svelte.d.ts

@@ -0,0 +1,52 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * The chrome of a sidebar and nothing else: width, surface, collapse
+ * behaviour, the inset its regions share, and a scroll container for the
+ * middle.
+ *
+ * `SidebarNavigation` is a fully-specified sidebar driven by ~44 props —
+ * excellent when your sidebar looks like that one, useless when it does
+ * not, because the parts are not reachable. This is the same shell with
+ * the regions left open, so you can drop in `SidebarBrandHeader`,
+ * `SidebarNavSection` and `SidebarFooter` (or your own markup) and skip
+ * the props you would never set.
+ *
+ * `SidebarNavigation` is built on it, so the two cannot drift apart.
+ *
+ * ```svelte
+ * <SidebarShell mode="collapsed">
+ *     {#snippet header({ collapsed })}
+ *         <SidebarBrandHeader {collapsed} brandName="Zabi" />
+ *     {/snippet}
+ *     <SidebarNavSection title="Main" sectionKey="main">…</SidebarNavSection>
+ *     {#snippet footer({ collapsed, insetX })}
+ *         <SidebarFooter {collapsed} className={insetX} />
+ *     {/snippet}
+ * </SidebarShell>
+ * ```
+ */
+/** Passed to every region so it can match the shell's collapse and inset. */
+export interface SidebarRegionContext {
+    collapsed: boolean;
+    /** Horizontal padding utility the shell's own regions use. */
+    insetX: string;
+}
+type Props = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+    mode?: "expanded" | "collapsed";
+    /** `rail` attaches to the viewport edge; `card` is a floating panel. */
+    layout?: "rail" | "card";
+    ariaLabel?: string;
+    class?: string;
+    /** @deprecated use `class`. */
+    className?: string;
+    /** Brand row, search — anything above the scrolling nav area. */
+    header?: Snippet<[SidebarRegionContext]>;
+    /** The scrolling middle. */
+    children?: Snippet<[SidebarRegionContext]>;
+    /** Account row, logout, theme toggle. Outside the scroll container. */
+    footer?: Snippet<[SidebarRegionContext]>;
+};
+declare const SidebarShell: import("svelte").Component<Props, {}, "">;
+type SidebarShell = ReturnType<typeof SidebarShell>;
+export default SidebarShell;