zabi-components 7.0.1 → 8.0.0

package/dist/organisms/TopNavbar.svelte

@@ -1,6 +1,10 @@
 <script lang="ts">
     import ThemeToggle from "../atoms/ThemeToggle.svelte";
+    import IconButton from "../atoms/IconButton.svelte";
+    import { ExternalLink, Menu, X } from "@lucide/svelte";
     import type { Component, Snippet } from "svelte";
+    import { generateId } from "../util/ssr-safe.js";
+    import { cn } from "../util/cn.js";
 
     export interface TopNavbarNavItem {
         label: string;
@@ -15,6 +19,8 @@
         /** `aria-label` on `<nav>` when multiple nav landmarks exist. */
         ariaLabel?: string;
         showThemeToggle?: boolean;
+        class?: string;
+        /** @deprecated use `class`. */
         className?: string;
         /** Slim mode: only the `nav` region (no full chrome bar). */
         embedded?: boolean;
@@ -30,7 +36,8 @@
         brandHref,
         ariaLabel,
         showThemeToggle = true,
-        className = "",
+        class: classAttr = "",
+        className: legacyClass = "",
         embedded = false,
         items = [],
         navVariant = "header",
@@ -42,12 +49,24 @@
         ...restProps
     }: Props & { nav?: Snippet; actions?: Snippet } = $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 mobileMenuId = generateId("topnavbar-menu");
+
     let isMenuOpen = $state(false);
 
     function toggleMenu() {
         isMenuOpen = !isMenuOpen;
     }
 
+    function handleWindowKeydown(event: KeyboardEvent) {
+        if (event.key === "Escape" && isMenuOpen) {
+            isMenuOpen = false;
+        }
+    }
+
     function handleNavLinkClick(event: MouseEvent) {
         if (preventNavigation) {
             event.preventDefault();
@@ -57,6 +76,11 @@
         }
     }
 
+    /** Absolute URLs leave the site, so they are marked and open in a new tab. */
+    function isExternal(href: string): boolean {
+        return href.startsWith("http://") || href.startsWith("https://");
+    }
+
     /** App routes: prefix match except `/` and absolute URLs (exact match). */
     function isNavItemActive(href: string): boolean {
         if (href.startsWith("http://") || href.startsWith("https://")) {
@@ -78,8 +102,30 @@
         return "flex flex-col gap-1 grow h-full items-center justify-center min-h-0 min-w-0 relative shrink-0 cursor-pointer w-full md:w-auto";
     }
 
-    function getIconContainerClasses(): string {
-        return "focus-ring focus-ring--nav group/nav-item flex flex-col items-center justify-center overflow-clip relative rounded-[20px] shrink-0 text-nav-menu-item transition-colors duration-200 outline-none hover:bg-nav-menu-hover hover:text-nav-menu-item-hover aria-[current=page]:bg-nav-menu-active aria-[current=page]:text-nav-menu-item-active";
+    /**
+     * The active state is resolved here rather than with
+     * `aria-[current=page]:text-nav-menu-item-active`.
+     *
+     * That variant was dead: the semantic utilities are hand-written in
+     * app.css and sit outside Tailwind's cascade layer, so an unlayered
+     * `.text-nav-menu-item` beats anything Tailwind generates for a variant of
+     * the same property. The fill happened to survive only because no plain
+     * `bg-*` class competed with it — so the selected tab painted its pill but
+     * kept the idle label colour (#27272a where #3c52ba was intended), which
+     * is exactly the "active state does almost nothing" failure the sidebar
+     * had.
+     *
+     * Plain classes chosen in JS cannot lose that way.
+     */
+    function getIconContainerClasses(isActive: boolean): string {
+        const base =
+            "focus-ring focus-ring--nav group/nav-item flex flex-col items-center justify-center overflow-clip relative rounded-pill shrink-0 transition-colors duration-200 outline-none";
+        return isActive
+            ? cn(base, "bg-nav-menu-active text-nav-menu-item-active")
+            : cn(
+                  base,
+                  "text-nav-menu-item hover:bg-nav-menu-hover hover:text-nav-menu-item-hover",
+              );
     }
 
     function getStateLayerClasses(): string {
@@ -87,7 +133,9 @@
     }
 
     function getLabelClasses(): string {
-        return "font-medium leading-4 relative shrink-0 text-center text-nowrap tracking-[0.5px] whitespace-pre text-xs text-inherit";
+        // `whitespace-pre` used to sit beside `text-nowrap` — same property,
+        // and it preserved literal whitespace as a side effect.
+        return "font-medium leading-4 relative shrink-0 text-center text-nowrap tracking-wide text-xs text-inherit";
     }
 
     function getIconWrapperClasses(): string {
@@ -99,12 +147,15 @@
     <ul class="{ulClasses} list-none m-0 p-0">
         {#each items as item (item.href)}
             {@const isActive = isNavItemActive(item.href)}
+            {@const external = isExternal(item.href)}
             <li class={getNavItemClasses()}>
                 <a
                     href={item.href}
-                    class={getIconContainerClasses()}
+                    class={getIconContainerClasses(isActive)}
                     onclick={handleNavLinkClick}
                     aria-current={isActive ? "page" : undefined}
+                    target={external ? "_blank" : undefined}
+                    rel={external ? "noopener noreferrer" : undefined}
                 >
                     <div class={getStateLayerClasses()}>
                         {#if item.iconFilled && isActive}
@@ -118,9 +169,17 @@
                                 <Icon size={16} class="w-4 h-4" />
                             </div>
                         {/if}
-                        <p class={getLabelClasses()}>
+                        <span class={getLabelClasses()}>
                             {item.label}
-                        </p>
+                        </span>
+                        {#if external}
+                            <ExternalLink
+                                size={12}
+                                class="shrink-0 text-current opacity-70"
+                                aria-hidden="true"
+                            />
+                            <span class="sr-only">(opens in a new tab)</span>
+                        {/if}
                     </div>
                 </a>
             </li>
@@ -128,6 +187,8 @@
     </ul>
 {/snippet}
 
+<svelte:window onkeydown={handleWindowKeydown} />
+
 {#if embedded}
     <nav class={className} aria-label={ariaLabel} {...restProps}>
         {#if nav}
@@ -138,7 +199,7 @@
     </nav>
 {:else}
     <nav
-        class="border-b border-border bg-background sticky top-0 z-50 {className}"
+        class={cn("border-b border-border bg-background sticky top-0 z-sticky", className)}
         aria-label={ariaLabel}
         {...restProps}
     >
@@ -148,7 +209,7 @@
                     {#if brandHref}
                         <a
                             href={brandHref}
-                            class="focus-ring text-xl font-bold text-headline hover:opacity-90"
+                            class="focus-ring text-xl font-bold text-headline transition-colors hover:text-link"
                         >
                             {brand}
                         </a>
@@ -158,7 +219,7 @@
                 </div>
 
                 <div class="hidden md:block">
-                    <div class="ml-10 flex items-baseline space-x-4">
+                    <div class="ml-10 flex items-center space-x-4">
                         {#if nav}
                             {@render nav()}
                         {:else if items.length > 0}
@@ -177,19 +238,29 @@
                 </div>
 
                 <div class="md:hidden">
-                    <button
-                        type="button"
-                        class="cursor-pointer text-description hover:text-body"
+                    <!--
+                      Was a bare ☰ glyph in a text-2xl span: font-dependent,
+                      off the icon scale, and with no disclosure semantics, so
+                      a screen reader could not tell the menu was open.
+                    -->
+                    <IconButton
+                        variant="ghost"
+                        label={isMenuOpen ? "Close menu" : "Open menu"}
                         onclick={toggleMenu}
-                        aria-label="Toggle menu"
+                        aria-expanded={isMenuOpen}
+                        aria-controls={mobileMenuId}
                     >
-                        <span class="text-2xl">☰</span>
-                    </button>
+                        {#if isMenuOpen}
+                            <X size={20} />
+                        {:else}
+                            <Menu size={20} />
+                        {/if}
+                    </IconButton>
                 </div>
             </div>
 
             {#if isMenuOpen}
-                <div class="md:hidden">
+                <div class="md:hidden" id={mobileMenuId}>
                     <div
                         class="px-2 pt-2 pb-3 space-y-1 sm:px-3 border-t border-border"
                     >

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

@@ -17,6 +17,8 @@ interface Props {
     /** `aria-label` on `<nav>` when multiple nav landmarks exist. */
     ariaLabel?: string;
     showThemeToggle?: boolean;
+    class?: string;
+    /** @deprecated use `class`. */
     className?: string;
     /** Slim mode: only the `nav` region (no full chrome bar). */
     embedded?: boolean;

package/dist/organisms/index.d.ts

@@ -1,4 +1,5 @@
 export { default as TopNavbar } from './TopNavbar.svelte';
 export { default as SidebarNavigation } from './SidebarNavigation.svelte';
+export { default as SidebarShell } from './SidebarShell.svelte';
 export { default as SidebarAccountPanel } from './SidebarAccountPanel.svelte';
 export { default as SidebarPanel } from './SidebarPanel.svelte';

package/dist/organisms/index.js

@@ -1,4 +1,5 @@
 export { default as TopNavbar } from './TopNavbar.svelte';
 export { default as SidebarNavigation } from './SidebarNavigation.svelte';
+export { default as SidebarShell } from './SidebarShell.svelte';
 export { default as SidebarAccountPanel } from './SidebarAccountPanel.svelte';
 export { default as SidebarPanel } from './SidebarPanel.svelte';

package/dist/routes/lib/variant-utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Variant class helpers — semantic design tokens only (see src/app.css).
+ */
+import type { SemanticVariant } from '../../types/variants.js';
+export type Variant = SemanticVariant;
+/**
+ * Border + focus ring classes for text inputs (Input, Textarea).
+ */
+export declare function getInputVariantClasses(variant: Variant): string;
+/**
+ * Card surfaces — border + background using semantic tokens.
+ */
+export declare function getCardVariantClasses(variant: Variant): string;
+/**
+ * Generic variant classes for borders, text, or backgrounds.
+ */
+export declare function getVariantClasses(variant: Variant, type: 'border' | 'text' | 'bg'): string;
+export declare function getAllVariantClasses(variant: Variant): {
+    border: string;
+    text: string;
+    bg: string;
+};
+/**
+ * Create a variant class map for use in reactive statements
+ */
+export declare function createVariantClassMap<T extends string>(variants: T[], prefix: string): Record<T, string>;

package/dist/routes/lib/{variant-utils.ts → variant-utils.js}

@@ -1,55 +1,37 @@
 /**
  * Variant class helpers — semantic design tokens only (see src/app.css).
  */
-
-import type { SemanticVariant } from '../../types/variants.js';
-
-export type Variant = SemanticVariant;
-
 /**
  * Border + focus ring classes for text inputs (Input, Textarea).
  */
-export function getInputVariantClasses(variant: Variant): string {
-    const variantMap: Record<Variant, string> = {
-        default:
-            'focus-ring border-input-border focus-visible:border-input-border',
-        success:
-            'focus-ring border-success focus-visible:border-success',
-        warning:
-            'focus-ring border-warning focus-visible:border-warning',
+export function getInputVariantClasses(variant) {
+    const variantMap = {
+        default: 'focus-ring border-input-border focus-visible:border-input-border',
+        success: 'focus-ring border-success focus-visible:border-success',
+        warning: 'focus-ring border-warning focus-visible:border-warning',
         error: 'focus-ring border-error focus-visible:border-error',
         info: 'focus-ring border-info focus-visible:border-info',
     };
-
     return variantMap[variant] || variantMap.default;
 }
-
 /**
  * Card surfaces — border + background using semantic tokens.
  */
-export function getCardVariantClasses(variant: Variant): string {
-    const variantMap: Record<Variant, string> = {
+export function getCardVariantClasses(variant) {
+    const variantMap = {
         default: 'border-border bg-card',
         success: 'border-success bg-card',
         warning: 'border-warning bg-card',
         error: 'border-error bg-card',
         info: 'border-info bg-card',
     };
-
     return variantMap[variant] || variantMap.default;
 }
-
 /**
  * Generic variant classes for borders, text, or backgrounds.
  */
-export function getVariantClasses(
-    variant: Variant,
-    type: 'border' | 'text' | 'bg',
-): string {
-    const variantMap: Record<
-        Variant,
-        Record<'border' | 'text' | 'bg', string>
-    > = {
+export function getVariantClasses(variant, type) {
+    const variantMap = {
         default: {
             border: 'border-border',
             text: 'text-body',
@@ -76,34 +58,21 @@ export function getVariantClasses(
             bg: 'bg-card',
         },
     };
-
     return variantMap[variant]?.[type] || variantMap.default[type];
 }
-
-export function getAllVariantClasses(variant: Variant): {
-    border: string;
-    text: string;
-    bg: string;
-} {
+export function getAllVariantClasses(variant) {
     return {
         border: getVariantClasses(variant, 'border'),
         text: getVariantClasses(variant, 'text'),
         bg: getVariantClasses(variant, 'bg'),
     };
 }
-
 /**
  * Create a variant class map for use in reactive statements
  */
-export function createVariantClassMap<T extends string>(
-    variants: T[],
-    prefix: string,
-): Record<T, string> {
-    return variants.reduce(
-        (acc, variant) => {
-            acc[variant] = `${prefix}-${variant}`;
-            return acc;
-        },
-        {} as Record<T, string>,
-    );
+export function createVariantClassMap(variants, prefix) {
+    return variants.reduce((acc, variant) => {
+        acc[variant] = `${prefix}-${variant}`;
+        return acc;
+    }, {});
 }

package/dist/types/events.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.js

@@ -0,0 +1,3 @@
+export * from './events.js';
+export * from './variants.js';
+export * from './page.types.js';

package/dist/util/cn.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Merge class values, last conflicting utility wins.
+ *
+ * Falsy entries are dropped, so `cn(base, isActive && activeClasses, className)`
+ * is safe.
+ */
+export declare function cn(...classes: (string | false | null | undefined)[]): string;

package/dist/util/cn.js

@@ -0,0 +1,48 @@
+import { extendTailwindMerge } from "tailwind-merge";
+/**
+ * Class merger for every component's final `class` value.
+ *
+ * The library promises that a call-site utility wins over the component's own.
+ * Plain concatenation does not deliver that: `rounded-control` and
+ * `rounded-container` are equal-specificity utilities, so the winner is
+ * whichever Tailwind emits later in the stylesheet, not whichever the caller
+ * passed. The sidebar's search field asked for `rounded-container` and rendered
+ * at 8px, because `rounded-control` happened to come later.
+ *
+ * tailwind-merge resolves conflicts by class group and keeps the last one, so
+ * the promise holds for real.
+ *
+ * Almost all of this repo's semantic utilities already work with the stock
+ * config — `bg-card` vs `bg-surface-overlay`, `text-headline` vs
+ * `text-description`, `border-border` vs `border-input-border` all resolve,
+ * because tailwind-merge treats an unrecognised colour-ish value as a colour.
+ * The radii are the exception: `control`, `container`, `overlay` and `pill` are
+ * role names, not scale values, so they have to be declared or tailwind-merge
+ * keeps both and we are back to stylesheet order deciding.
+ */
+const RADIUS_ROLES = ["control", "container", "overlay", "pill"];
+/**
+ * Every corner group tailwind-merge knows about, so `rounded-t-overlay` on a
+ * sheet is still beaten by a call-site `rounded-t-control`. Declaring only the
+ * base `rounded` group silently leaves the per-side ones unmerged.
+ */
+const RADIUS_GROUPS = [
+    "rounded",
+    "rounded-s", "rounded-e", "rounded-t", "rounded-r", "rounded-b", "rounded-l",
+    "rounded-ss", "rounded-se", "rounded-ee", "rounded-es",
+    "rounded-tl", "rounded-tr", "rounded-br", "rounded-bl",
+];
+const twMerge = extendTailwindMerge({
+    extend: {
+        classGroups: Object.fromEntries(RADIUS_GROUPS.map((group) => [group, [{ [group]: RADIUS_ROLES }]])),
+    },
+});
+/**
+ * Merge class values, last conflicting utility wins.
+ *
+ * Falsy entries are dropped, so `cn(base, isActive && activeClasses, className)`
+ * is safe.
+ */
+export function cn(...classes) {
+    return twMerge(classes.filter(Boolean).join(" "));
+}

package/dist/util/ssr-safe.d.ts

@@ -9,8 +9,8 @@ export declare function safeDocument(): Document | undefined;
 export declare function safeLocalStorage(): Storage | undefined;
 export declare function safeSessionStorage(): Storage | undefined;
 export declare function safeRequestAnimationFrame(callback: FrameRequestCallback): number | undefined;
-export declare function safeSetTimeout(callback: () => void, delay: number): NodeJS.Timeout | undefined;
-export declare function safeClearTimeout(id: NodeJS.Timeout | undefined): void;
-export declare function safeSetInterval(callback: () => void, delay: number): NodeJS.Timeout | undefined;
-export declare function safeClearInterval(id: NodeJS.Timeout | undefined): void;
+export declare function safeSetTimeout(callback: () => void, delay: number): ReturnType<typeof setTimeout> | undefined;
+export declare function safeClearTimeout(id: ReturnType<typeof setTimeout> | undefined): void;
+export declare function safeSetInterval(callback: () => void, delay: number): ReturnType<typeof setInterval> | undefined;
+export declare function safeClearInterval(id: ReturnType<typeof setInterval> | undefined): void;
 export declare function generateId(prefix?: string): string;