zabi-components 8.0.0 → 8.1.0

package/dist/organisms/SidebarShell.svelte

@@ -1,7 +1,10 @@
 <script lang="ts">
+    import { zabiCommonStrings } from "../util/zabi-strings.js";
     import type { Snippet } from "svelte";
     import type { HTMLAttributes } from "svelte/elements";
+    import Drawer from "../molecules/Drawer.svelte";
     import { cn } from "../util/cn.js";
+    import type { DrawerCloseReason } from "../util/drawer.js";
 
     /**
      * The chrome of a sidebar and nothing else: width, surface, collapse
@@ -28,8 +31,37 @@
      *     {/snippet}
      * </SidebarShell>
      * ```
+     *
+     * A sidebar is 266px wide, which a phone does not have beside its
+     * content. With `mobile="drawer"` the rail is only there from the `lg`
+     * breakpoint (1024px) up; below it the same regions open in a Drawer from
+     * the start edge, with the Drawer's focus trap, Escape and backdrop:
+     *
+     * ```svelte
+     * <SidebarShell mobile="drawer" bind:isOpen drawerTitle="Menu">
+     *     {#snippet trigger({ props, toggle })}
+     *         <IconButton label="Menu" onclick={toggle} {...props}><Menu /></IconButton>
+     *     {/snippet}
+     *     …
+     * </SidebarShell>
+     * ```
+     *
+     * `trigger` is rendered where the rail would be, below `lg` only; leave
+     * it out and open the drawer from a button of your own by setting
+     * `isOpen`. The drawer closes when a link in it is followed.
      */
 
+    /** What the `trigger` snippet gets. */
+    export interface SidebarTriggerContext {
+        isOpen: boolean;
+        toggle: () => void;
+        /** Spread on the button: it says what the button opens, and whether it is open. */
+        props: { "aria-haspopup": "dialog"; "aria-expanded": boolean };
+    }
+
+    /** What closed the drawer: the user, a link that was followed, or the screen reaching `lg`. */
+    export type SidebarDrawerCloseReason = DrawerCloseReason | "navigate" | "resize";
+
     /** Passed to every region so it can match the shell's collapse and inset. */
     export interface SidebarRegionContext {
         collapsed: boolean;
@@ -37,11 +69,34 @@
         insetX: string;
     }
 
-    type Props = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+    // `children` here is a snippet that takes the region context; the one in
+    // `HTMLAttributes` takes nothing, and the two together accepted neither.
+    type Props = Omit<HTMLAttributes<HTMLElement>, "class" | "onclose" | "children"> & {
         mode?: "expanded" | "collapsed";
         /** `rail` attaches to the viewport edge; `card` is a floating panel. */
         layout?: "rail" | "card";
         ariaLabel?: string;
+        /** Accessible name of the scrolling region between header and footer. */
+        label?: string;
+        /**
+         * What the sidebar is below the `lg` breakpoint. `none`: the rail, as
+         * everywhere. `drawer`: the rail is hidden there and its regions open
+         * in a Drawer from the start edge instead.
+         */
+        mobile?: "none" | "drawer";
+        /** Whether the drawer is open. Bindable. Only used with `mobile="drawer"`. */
+        isOpen?: boolean;
+        /** Heading of the drawer, and its accessible name. Without it, `ariaLabel` is. */
+        drawerTitle?: string;
+        /** Accessible name of the drawer's close button. */
+        closeLabel?: string;
+        /** Fired when the drawer closes itself, with why. */
+        onclose?: (detail: { reason: SidebarDrawerCloseReason }) => void;
+        /**
+         * The button that opens the drawer, rendered in the rail's place below
+         * `lg`. Optional: a button anywhere that sets `isOpen` does the same.
+         */
+        trigger?: Snippet<[SidebarTriggerContext]>;
         class?: string;
         /** @deprecated use `class`. */
         className?: string;
@@ -57,6 +112,13 @@
         mode = "expanded",
         layout = "rail",
         ariaLabel = "Sidebar navigation",
+        label = "Navigation links",
+        mobile = "none",
+        isOpen = $bindable<Exclude<Props["isOpen"], undefined>>(),
+        drawerTitle = undefined,
+        closeLabel: closeLabelGiven,
+        onclose,
+        trigger,
         class: classAttr = "",
         className: legacyClass = "",
         header,
@@ -65,6 +127,21 @@
         ...restProps
     }: Props = $props();
 
+    // No fallback on a bindable prop: Svelte refuses `bind:…={undefined}` on
+    // one that has a fallback (`props_invalid_value`), and a page that throws
+    // while it hydrates never becomes interactive. The default is applied
+    // here instead: at once, for the server and the first render, and again
+    // whenever a parent hands back `undefined`.
+    const applyDefaults = () => {
+        if (isOpen === undefined) isOpen = false;
+    };
+    applyDefaults();
+    $effect.pre(applyDefaults);
+
+    /** Words many components share: a `ZabiStringsProvider` above this one may give them; else English. */
+    const common = zabiCommonStrings();
+    const closeLabel = $derived(closeLabelGiven ?? common().close);
+
     const className = $derived(cn(classAttr, legacyClass));
     const isCollapsed = $derived(mode === "collapsed");
     const isCard = $derived(layout === "card");
@@ -78,35 +155,109 @@
             "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}`;
+        // `flex` and `max-lg:hidden` must not both apply below `lg`: with
+        // the drawer mode the rail is a flex box from `lg` up only.
+        const display = asDrawer ? "hidden lg:flex" : "flex";
+        const baseClasses = `${display} 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 });
+
+    const asDrawer = $derived(mobile === "drawer");
+    /** In the drawer the sidebar is always spelled out, and the drawer's own padding is the inset. */
+    const drawerRegion: SidebarRegionContext = { collapsed: false, insetX: "px-0" };
+
+    function closeDrawer(reason: SidebarDrawerCloseReason) {
+        if (!isOpen) return;
+        isOpen = false;
+        onclose?.({ reason });
+    }
+
+    // From `lg` up the rail is there: a drawer left open would cover it.
+    $effect(() => {
+        if (!asDrawer || typeof window.matchMedia !== "function") return;
+        const wide = window.matchMedia("(min-width: 1024px)");
+        const onChange = () => {
+            if (wide.matches) closeDrawer("resize");
+        };
+        onChange();
+        wide.addEventListener("change", onChange);
+        return () => wide.removeEventListener("change", onChange);
+    });
+
+    /** A link in the drawer was followed: the page it leads to is behind the drawer. */
+    function handleDrawerClick(event: MouseEvent) {
+        if (!(event.target instanceof Element)) return;
+        if (event.target.closest("a[href]")) closeDrawer("navigate");
+    }
+
+    const triggerContext = $derived<SidebarTriggerContext>({
+        isOpen,
+        toggle: () => (isOpen ? closeDrawer("close-button") : (isOpen = true)),
+        props: { "aria-haspopup": "dialog", "aria-expanded": isOpen },
+    });
 </script>
 
-<nav class={containerClasses} aria-label={ariaLabel} {...restProps}>
-    <div class="flex min-h-0 w-full min-w-0 flex-1 flex-col">
+{#snippet regions(context: SidebarRegionContext, inDrawer: boolean)}
+    <div class={cn("flex w-full min-w-0 flex-col", !inDrawer && "min-h-0 flex-1")}>
         {#if header}
-            <div class={cn("flex w-full shrink-0 flex-col gap-5 pb-3", insetX)}>
-                {@render header(region)}
+            <div class={cn("flex w-full shrink-0 flex-col gap-5 pb-3", context.insetX)}>
+                {@render header(context)}
             </div>
         {/if}
 
+        <!-- In the drawer the drawer's body scrolls, so this region does not. -->
         <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,
+                "flex min-w-0 flex-col gap-3 pt-4 pb-2",
+                !inDrawer &&
+                    "min-h-0 flex-1 overflow-y-auto overflow-x-hidden overscroll-y-contain",
+                context.insetX,
             )}
             role="region"
-            aria-label="Navigation links"
+            aria-label={label}
         >
-            {@render children?.(region)}
+            {@render children?.(context)}
         </div>
     </div>
 
     {#if footer}
-        {@render footer(region)}
+        {@render footer(context)}
     {/if}
+{/snippet}
+
+<nav class={containerClasses} aria-label={ariaLabel} {...restProps}>
+    {@render regions(region, false)}
 </nav>
+
+{#if asDrawer}
+    {#if trigger}
+        <div class="lg:hidden" data-sidebar-trigger>
+            {@render trigger(triggerContext)}
+        </div>
+    {/if}
+    <!-- The same regions, in a Drawer. Rendered only while it is open, so
+    nothing of the sidebar is in the page twice until then, and the server
+    renders the rail alone. -->
+    <Drawer
+        bind:isOpen
+        side="start"
+        size="sm"
+        title={drawerTitle || ariaLabel}
+        {closeLabel}
+        onclose={(detail) => onclose?.(detail)}
+        class="lg:hidden"
+    >
+        <!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions -->
+        <nav
+            class="flex w-full min-w-0 flex-col text-headline"
+            aria-label={ariaLabel}
+            data-sidebar-drawer
+            onclick={handleDrawerClick}
+        >
+            {@render regions(drawerRegion, true)}
+        </nav>
+    </Drawer>
+{/if}

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

@@ -1,5 +1,6 @@
 import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
+import type { DrawerCloseReason } from "../util/drawer.js";
 /**
  * The chrome of a sidebar and nothing else: width, surface, collapse
  * behaviour, the inset its regions share, and a scroll container for the
@@ -25,18 +26,71 @@ import type { HTMLAttributes } from "svelte/elements";
  *     {/snippet}
  * </SidebarShell>
  * ```
+ *
+ * A sidebar is 266px wide, which a phone does not have beside its
+ * content. With `mobile="drawer"` the rail is only there from the `lg`
+ * breakpoint (1024px) up; below it the same regions open in a Drawer from
+ * the start edge, with the Drawer's focus trap, Escape and backdrop:
+ *
+ * ```svelte
+ * <SidebarShell mobile="drawer" bind:isOpen drawerTitle="Menu">
+ *     {#snippet trigger({ props, toggle })}
+ *         <IconButton label="Menu" onclick={toggle} {...props}><Menu /></IconButton>
+ *     {/snippet}
+ *     …
+ * </SidebarShell>
+ * ```
+ *
+ * `trigger` is rendered where the rail would be, below `lg` only; leave
+ * it out and open the drawer from a button of your own by setting
+ * `isOpen`. The drawer closes when a link in it is followed.
  */
+/** What the `trigger` snippet gets. */
+export interface SidebarTriggerContext {
+    isOpen: boolean;
+    toggle: () => void;
+    /** Spread on the button: it says what the button opens, and whether it is open. */
+    props: {
+        "aria-haspopup": "dialog";
+        "aria-expanded": boolean;
+    };
+}
+/** What closed the drawer: the user, a link that was followed, or the screen reaching `lg`. */
+export type SidebarDrawerCloseReason = DrawerCloseReason | "navigate" | "resize";
 /** 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"> & {
+type Props = Omit<HTMLAttributes<HTMLElement>, "class" | "onclose" | "children"> & {
     mode?: "expanded" | "collapsed";
     /** `rail` attaches to the viewport edge; `card` is a floating panel. */
     layout?: "rail" | "card";
     ariaLabel?: string;
+    /** Accessible name of the scrolling region between header and footer. */
+    label?: string;
+    /**
+     * What the sidebar is below the `lg` breakpoint. `none`: the rail, as
+     * everywhere. `drawer`: the rail is hidden there and its regions open
+     * in a Drawer from the start edge instead.
+     */
+    mobile?: "none" | "drawer";
+    /** Whether the drawer is open. Bindable. Only used with `mobile="drawer"`. */
+    isOpen?: boolean;
+    /** Heading of the drawer, and its accessible name. Without it, `ariaLabel` is. */
+    drawerTitle?: string;
+    /** Accessible name of the drawer's close button. */
+    closeLabel?: string;
+    /** Fired when the drawer closes itself, with why. */
+    onclose?: (detail: {
+        reason: SidebarDrawerCloseReason;
+    }) => void;
+    /**
+     * The button that opens the drawer, rendered in the rail's place below
+     * `lg`. Optional: a button anywhere that sets `isOpen` does the same.
+     */
+    trigger?: Snippet<[SidebarTriggerContext]>;
     class?: string;
     /** @deprecated use `class`. */
     className?: string;
@@ -47,6 +101,6 @@ type Props = Omit<HTMLAttributes<HTMLElement>, "class"> & {
     /** Account row, logout, theme toggle. Outside the scroll container. */
     footer?: Snippet<[SidebarRegionContext]>;
 };
-declare const SidebarShell: import("svelte").Component<Props, {}, "">;
+declare const SidebarShell: import("svelte").Component<Props, {}, "isOpen">;
 type SidebarShell = ReturnType<typeof SidebarShell>;
 export default SidebarShell;