zabi-components 8.0.0 → 9.0.0

package/dist/molecules/SlideUp.svelte

@@ -1,59 +1,121 @@
 <script lang="ts">
+    import { zabiCommonStrings } from "../util/zabi-strings.js";
     import type { Snippet } from 'svelte';
     import {
         focusFirstElement,
-        getFocusableElements,
+        joinOverlayStack,
+        recoverStrayFocus,
         returnFocus,
         saveFocus,
     } from '../util/focus-utils.js';
+    import {
+        followKeyboard,
+        lockBodyScroll,
+        registerOverlayFooter,
+        registerOverlayHeader,
+        trapTabKey,
+    } from '../util/overlay.js';
+    import { TOUCH_HIT_AREA } from '../util/touch-target.js';
     import { generateId } from "../util/ssr-safe.js";
     import { cn } from "../util/cn.js";
+    import {
+        OVERLAY_CHROME,
+        OVERLAY_CLOSE_GLYPH,
+        OVERLAY_TITLE_2XL,
+        OVERLAY_TITLE_HYPHENS,
+        OVERLAY_TITLE_WRAP,
+        textIsEnlarged,
+    } from "../util/overlay-chrome.js";
+    import { attachSheetDrag, FLICK_VELOCITY } from "../util/sheet-drag.js";
 
     interface Props {
         /** Extra classes for the host element. */
         class?: string;
         isOpen?: boolean;
         title?: string;
+        /** Accessible name of the close button. */
+        closeLabel?: string;
+        /**
+         * CSS selector, looked up inside the sheet, of the control that takes
+         * focus when it opens. Without it, or with no match, the first control does.
+         */
+        initialFocus?: string;
+        /**
+         * Adds a grip at the top and lets a swipe down close the sheet. The
+         * grip drags from anywhere; a swipe on the content closes only when
+         * the content is at its top, and scrolls it otherwise. The close
+         * button, the backdrop and Escape stay, so nothing depends on the
+         * gesture.
+         */
+        swipeToClose?: boolean;
+        /**
+         * Runs when the sheet closes itself, with the event that closed it:
+         * the click, the Escape keydown, or the end of a swipe.
+         */
         onclick?: (event: Event) => void;
         onkeydown?: (event: Event) => void;
         children?: Snippet;
+        /**
+         * Pinned to the bottom of the sheet, below the content, which then
+         * scrolls on its own: for the buttons of a form. It stays above the
+         * on-screen keyboard, and toasts keep off it. Without it the sheet is
+         * as it always was: one box that scrolls as a whole.
+         */
+        footer?: Snippet;
     }
 
     let {
         class: className = "",
-        isOpen = $bindable(false),
+        isOpen = $bindable<Exclude<Props["isOpen"], undefined>>(),
         title = '',
+        closeLabel: closeLabelGiven,
+        initialFocus,
+        swipeToClose = false,
         onclick,
         onkeydown,
         children,
+        footer,
         ...restProps
     }: Props = $props();
 
+    /** Words many components share: a `ZabiStringsProvider` above this one may give them; else English. */
+    const common = zabiCommonStrings();
+    const closeLabel = $derived(closeLabelGiven ?? common().close);
+
+    // 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);
+
     const slideTitleId = generateId('slideup-title');
 
     let slideUpContainer = $state<HTMLDivElement>();
-    let focusActive = false;
+    let grip = $state<HTMLDivElement>();
+    let headerElement = $state<HTMLDivElement>();
+    let footerElement = $state<HTMLDivElement>();
 
-    /** Ref-counted on `<body>`; shares the counter with Modal so nested overlays unlock once. */
-    function lockBodyScroll(): () => void {
-        const body = document.body;
-        const count = Number(body.dataset.zabiScrollLock ?? '0');
-        if (count === 0) {
-            body.dataset.zabiScrollLockOverflow = body.style.overflow;
-            body.style.overflow = 'hidden';
-        }
-        body.dataset.zabiScrollLock = String(count + 1);
-        return () => {
-            const next = Number(body.dataset.zabiScrollLock ?? '1') - 1;
-            if (next <= 0) {
-                body.style.overflow = body.dataset.zabiScrollLockOverflow ?? '';
-                delete body.dataset.zabiScrollLock;
-                delete body.dataset.zabiScrollLockOverflow;
-            } else {
-                body.dataset.zabiScrollLock = String(next);
-            }
-        };
-    }
+    /**
+     * Read as the overlay opens: with the text enlarged, a long word in the
+     * title is hyphenated before it is cut (util/overlay-chrome.ts).
+     */
+    let enlargedText = $state(false);
+    $effect(() => {
+        if (isOpen) enlargedText = textIsEnlarged();
+    });
+    /** With a footer: the content, which is then what scrolls. */
+    let scroller = $state<HTMLDivElement>();
+    /** How far a swipe has pulled the sheet down, in px. */
+    let dragOffset = $state(0);
+    let dragging = $state(false);
+    let focusActive = false;
+    /** Position among the open overlays; lifts a sheet opened later above the earlier ones. */
+    let depth = $state(0);
 
     function closeSlideUp(event?: Event) {
         isOpen = false;
@@ -72,11 +134,32 @@
             saveFocus();
             focusActive = true;
             const unlockScroll = lockBodyScroll();
+            const overlay = joinOverlayStack(container);
+            depth = overlay.depth;
             const t = setTimeout(() => {
-                focusFirstElement(container);
+                // Something inside has taken focus already (a field that
+                // focuses itself as it mounts): leave it there. `initialFocus`
+                // is the consumer saying where focus goes, so it still decides.
+                const active = document.activeElement;
+                const inside = !!active && active !== container && container.contains(active);
+                if (inside && !(initialFocus && container.querySelector(initialFocus))) return;
+                focusFirstElement(container, initialFocus);
             }, 0);
+            // If the focused control is disabled or removed, focus lands on
+            // `<body>`; take Tab and Escape back from there.
+            const stopRecovery = recoverStrayFocus(container, {
+                onEscape: (event) => closeSlideUp(event),
+            });
+            // Where the on-screen keyboard covers the page, the overlay
+            // keeps to what is left above it.
+            const stopKeyboard = container.parentElement
+                ? followKeyboard(container.parentElement)
+                : undefined;
             return () => {
                 clearTimeout(t);
+                stopRecovery();
+                stopKeyboard?.();
+                overlay.leave();
                 unlockScroll();
                 if (focusActive) {
                     focusActive = false;
@@ -86,34 +169,49 @@
         }
     });
 
-    /** Re-queries focusables on every Tab so late-rendered content stays inside the trap. */
-    function handleTrapKeydown(event: KeyboardEvent) {
-        const container = slideUpContainer;
-        if (event.key !== 'Tab' || !container) return;
-        const owner = (event.target as Element | null)?.closest?.('[role="dialog"]');
-        if (owner && owner !== container) return;
-
-        const focusable = getFocusableElements(container);
-        if (focusable.length === 0) {
-            event.preventDefault();
-            container.focus();
-            return;
-        }
-        const first = focusable[0];
-        const last = focusable[focusable.length - 1];
-        const active = document.activeElement as HTMLElement | null;
+    // For the toast stack: it starts below the header, which holds the close
+    // button, and stays off a pinned footer.
+    $effect(() => {
+        const top = headerElement;
+        if (!isOpen || !top) return;
+        return registerOverlayHeader(top);
+    });
+    $effect(() => {
+        const pinned = footerElement;
+        if (!isOpen || !pinned) return;
+        return registerOverlayFooter(pinned);
+    });
 
-        if (!active || !focusable.includes(active)) {
-            event.preventDefault();
-            first.focus();
-        } else if (event.shiftKey && active === first) {
-            event.preventDefault();
-            last.focus();
-        } else if (!event.shiftKey && active === last) {
-            event.preventDefault();
-            first.focus();
-        }
-    }
+    $effect(() => {
+        const container = slideUpContainer;
+        const zone = grip;
+        // With a footer the content scrolls, not the panel.
+        const scrolls = footer ? scroller : container;
+        if (!isOpen || !swipeToClose || !container || !zone || !scrolls) return;
+        const settle = () => {
+            dragging = false;
+            dragOffset = 0;
+        };
+        const stop = attachSheetDrag(
+            // Without a footer the panel is its own scrolling box.
+            { handleZone: zone, scroller: scrolls },
+            {
+                onStart: () => (dragging = true),
+                // Down only: there is nowhere for it to go upwards.
+                onMove: (distance) => (dragOffset = Math.max(0, distance)),
+                onEnd(distance, velocity, event) {
+                    const far = distance > container.getBoundingClientRect().height * 0.3;
+                    settle();
+                    if (distance > 0 && (far || velocity >= FLICK_VELOCITY)) closeSlideUp(event);
+                },
+                onCancel: settle,
+            },
+        );
+        return () => {
+            stop();
+            settle();
+        };
+    });
 
     function handleBackdropClick(event: Event) {
         if (event.target === event.currentTarget) {
@@ -134,43 +232,104 @@
 {#if isOpen}
     <!-- svelte-ignore a11y_click_events_have_key_events -->
     <div
-        class="fixed inset-0 z-modal cursor-pointer bg-overlay"
+        class="group/overlay fixed inset-0 z-modal cursor-pointer bg-overlay"
+        style:z-index={depth > 0 ? `calc(var(--z-modal) + ${depth})` : undefined}
+        data-overlay-depth={depth}
         onclick={handleBackdropClick}
         onkeydown={handleKeydown}
         role="presentation"
     >
         <div
             bind:this={slideUpContainer}
-            class={cn("fixed bottom-0 left-0 right-0 z-modal flex max-h-[90vh] cursor-default flex-col overflow-y-auto rounded-t-overlay border-t border-border-overlay bg-surface-overlay shadow-lg animate-[slideUp_0.3s_ease-out]", className)}
+            class={cn(
+                "group-data-keyboard-open/overlay:max-h-full",
+                "absolute bottom-0 left-0 right-0 z-modal flex max-h-[90dvh] cursor-default flex-col overflow-y-auto rounded-t-overlay border-t border-border-overlay bg-surface-overlay shadow-lg animate-[slideUp_0.3s_ease-out] motion-reduce:animate-none",
+                // With a footer the content scrolls between the header and it.
+                footer && "overflow-y-hidden",
+                // Back to rest after a swipe that did not close it.
+                swipeToClose &&
+                    "overscroll-contain transition-transform duration-200 ease-out motion-reduce:transition-none",
+                className,
+            )}
+            style:transform={dragOffset > 0 ? `translateY(${dragOffset}px)` : undefined}
+            style:transition={dragging ? "none" : undefined}
+            data-dragging={dragging ? "true" : undefined}
             role="dialog"
             aria-modal="true"
             aria-labelledby={title ? slideTitleId : undefined}
             tabindex="-1"
-            onkeydown={handleTrapKeydown}
+            onkeydown={(event) => trapTabKey(slideUpContainer, event)}
             {...restProps}
         >
+            {#if swipeToClose}
+                <!-- Decorative: it adds a gesture, and the close button is the
+                control. It stays at the top while the content scrolls.
+                `touch-none`: otherwise the browser takes a touch here for
+                itself. The bar is drawn in the text colour where colours are
+                forced, since a background is dropped there. -->
+                <div
+                    bind:this={grip}
+                    data-sheet-grip
+                    aria-hidden="true"
+                    class="sticky top-0 z-10 flex h-[28px] shrink-0 cursor-grab touch-none items-start justify-center bg-surface-overlay pt-[10px] active:cursor-grabbing {OVERLAY_CHROME}"
+                >
+                    <span
+                        class="block h-1 w-9 rounded-pill bg-current text-description forced-colors:bg-[CanvasText]"
+                    ></span>
+                </div>
+            {/if}
             {#if title}
-                <div class="flex items-center justify-between px-6 pb-4 pt-6">
+                <!-- Chrome: laid out in px, with a title that stops at 1.3
+                times its size (util/overlay-chrome.ts). 12px between a long
+                title and the button: the title wraps, the button keeps its size. -->
+                <div
+                    bind:this={headerElement}
+                    class="flex shrink-0 items-center justify-between gap-[12px] px-6 pb-4 {OVERLAY_CHROME} {swipeToClose
+                        ? 'pt-2'
+                        : 'pt-6'}"
+                >
                     <h2
                         id={slideTitleId}
-                        class="text-2xl font-normal leading-8 tracking-normal text-headline"
+                        class="min-w-0 {OVERLAY_TITLE_2XL} font-normal tracking-normal text-headline {OVERLAY_TITLE_WRAP} {enlargedText ? OVERLAY_TITLE_HYPHENS : ''}"
                     >
                         {title}
                     </h2>
                     <button
                         type="button"
                         onclick={closeSlideUp}
-                        class="focus-ring flex h-8 w-8 cursor-pointer items-center justify-center rounded-full text-2xl text-description transition-colors hover:bg-surface-overlay-hover hover:text-headline"
-                        aria-label="Close"
+                        class="focus-ring pointer-coarse:relative flex h-8 w-8 shrink-0 cursor-pointer items-center justify-center rounded-full {OVERLAY_CLOSE_GLYPH} text-description transition-colors hover:bg-surface-overlay-hover hover:text-headline active:bg-surface-active {TOUCH_HIT_AREA}"
+                        aria-label={closeLabel}
                     >
                         ×
                     </button>
                 </div>
             {/if}
 
-            <div class="flex-1 px-6 pb-6">
-                {@render children?.()}
-            </div>
+            {#if footer}
+                <!-- `pt-1`: a scroll container clips, and the focus ring of a
+                first control needs the room. -->
+                <div
+                    bind:this={scroller}
+                    data-slide-up-content
+                    class="min-h-0 flex-1 overflow-y-auto overscroll-contain px-[24px] pt-[4px] pb-[16px]"
+                >
+                    {@render children?.()}
+                </div>
+                <!-- Clear of the home indicator on a phone; over the keyboard
+                that is under the keyboard, and 16px is enough. -->
+                <div
+                    bind:this={footerElement}
+                    data-slide-up-footer
+                    class="flex shrink-0 flex-wrap justify-end gap-[8px] border-t border-border-overlay px-[24px] pt-[16px] pb-[calc(16px+env(safe-area-inset-bottom,0px))] group-data-keyboard-open/overlay:pb-[16px]"
+                >
+                    {@render footer()}
+                </div>
+            {:else}
+                <!-- Clear of the home indicator on a phone. -->
+                <div class="flex-1 px-[24px] pb-[calc(1.5rem+env(safe-area-inset-bottom,0px))]">
+                    {@render children?.()}
+                </div>
+            {/if}
         </div>
     </div>
 {/if}

package/dist/molecules/SlideUp.svelte.d.ts

@@ -4,9 +4,35 @@ interface Props {
     class?: string;
     isOpen?: boolean;
     title?: string;
+    /** Accessible name of the close button. */
+    closeLabel?: string;
+    /**
+     * CSS selector, looked up inside the sheet, of the control that takes
+     * focus when it opens. Without it, or with no match, the first control does.
+     */
+    initialFocus?: string;
+    /**
+     * Adds a grip at the top and lets a swipe down close the sheet. The
+     * grip drags from anywhere; a swipe on the content closes only when
+     * the content is at its top, and scrolls it otherwise. The close
+     * button, the backdrop and Escape stay, so nothing depends on the
+     * gesture.
+     */
+    swipeToClose?: boolean;
+    /**
+     * Runs when the sheet closes itself, with the event that closed it:
+     * the click, the Escape keydown, or the end of a swipe.
+     */
     onclick?: (event: Event) => void;
     onkeydown?: (event: Event) => void;
     children?: Snippet;
+    /**
+     * Pinned to the bottom of the sheet, below the content, which then
+     * scrolls on its own: for the buttons of a form. It stays above the
+     * on-screen keyboard, and toasts keep off it. Without it the sheet is
+     * as it always was: one box that scrolls as a whole.
+     */
+    footer?: Snippet;
 }
 declare const SlideUp: import("svelte").Component<Props, {}, "isOpen">;
 type SlideUp = ReturnType<typeof SlideUp>;