zabi-components 7.0.2 → 8.1.0

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

@@ -0,0 +1,43 @@
+import { type Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "role"> & {
+    /** Shows the bar. Set it while the form differs from what is saved. */
+    dirty?: boolean;
+    /** Shown in the bar, and announced once when it appears. */
+    message?: string;
+    /** Accessible name of the bar as a landmark. */
+    label?: string;
+    saveLabel?: string;
+    discardLabel?: string;
+    /**
+     * Save shows its loading state and Discard is disabled. Set by the
+     * bar itself while a promise from `onsave` is pending.
+     */
+    saving?: boolean;
+    /**
+     * Called when Save is activated. Return a promise to keep the bar in
+     * its saving state until it settles. The bar does not hide itself:
+     * clear `dirty` once the save has gone through.
+     */
+    onsave?: () => void | Promise<unknown>;
+    /** Called when Discard is activated. */
+    ondiscard?: () => void;
+    /**
+     * Called when the promise from `onsave` rejects; the bar stays.
+     * Without it the error goes to the global error handler.
+     */
+    onerror?: (error: unknown) => void;
+    /**
+     * Which edge of its scroll container the bar sticks to. It is sticky,
+     * not fixed, so it keeps its place in the flow: put it after the
+     * form's last field (`bottom`) or before its first (`top`).
+     */
+    position?: "bottom" | "top";
+    /** Extra buttons, placed before Discard. */
+    actions?: Snippet;
+    /** Extra classes for the bar. */
+    class?: string;
+};
+declare const UnsavedChangesBar: import("svelte").Component<Props, {}, "">;
+type UnsavedChangesBar = ReturnType<typeof UnsavedChangesBar>;
+export default UnsavedChangesBar;

package/dist/molecules/index.d.ts

@@ -2,8 +2,12 @@ export { default as Alert } from './Alert.svelte';
 export { default as ComponentDemo } from './ComponentDemo.svelte';
 export { default as ContactForm } from './ContactForm.svelte';
 export { default as Dropdown } from './Dropdown.svelte';
+export { default as DropdownItem } from './DropdownItem.svelte';
+export type { DropdownItemIcon, DropdownItemTone, DropdownOption, } from '../util/dropdown.js';
 export { default as Form } from './Form.svelte';
 export { default as ImageUpload } from './ImageUpload.svelte';
+export { default as MediaGrid } from './MediaGrid.svelte';
+export type { MediaGridItemType, MediaGridKey, MediaGridSelectDetail, MediaGridStrings, } from '../util/media-grid.js';
 export { default as Modal } from './Modal.svelte';
 export { default as NavigationMenu } from './NavigationMenu.svelte';
 export { default as NavigationMenuList } from './NavigationMenuList.svelte';
@@ -23,4 +27,46 @@ export { default as Header } from './Header.svelte';
 export { default as EmptyState } from './EmptyState.svelte';
 export { default as Toaster } from './Toaster.svelte';
 export { default as RadioGroup } from './RadioGroup.svelte';
+export { default as SegmentedControl } from './SegmentedControl.svelte';
+export type { SegmentedControlIcon, SegmentedControlOption, } from '../util/segmented-control.js';
+export { default as SortableList } from './SortableList.svelte';
+export type { SortableListAnnouncement, SortableListReorderDetail, SortableListRow, SortableListStrings, } from '../util/sortable-list.js';
+export { default as Collapsible } from './Collapsible.svelte';
+export { default as SwipeableListItem } from './SwipeableListItem.svelte';
+export { DEFAULT_SWIPEABLE_LIST_ITEM_STRINGS } from '../util/swipeable-list-item.js';
+export type { SwipeableListItemAction, SwipeableListItemStrings } from '../util/swipeable-list-item.js';
+export { default as PullToRefresh } from './PullToRefresh.svelte';
+export { DEFAULT_PULL_TO_REFRESH_STRINGS } from '../util/pull-to-refresh.js';
+export type { PullToRefreshStrings } from '../util/pull-to-refresh.js';
+export { default as CollapsibleGroup } from './CollapsibleGroup.svelte';
+export type { CollapsibleHeadingLevel, CollapsibleTriggerProps, CollapsibleTriggerState, } from '../util/collapsible.js';
+export { default as ConfirmDialog } from './ConfirmDialog.svelte';
+export type { ConfirmDialogCancelReason, ConfirmDialogResult, ConfirmDialogVariant, } from '../util/confirm-dialog.js';
+export { default as Drawer } from './Drawer.svelte';
+export type { DrawerCloseReason, DrawerSide, DrawerSize, } from '../util/drawer.js';
+export { default as UnsavedChangesBar } from './UnsavedChangesBar.svelte';
+export { default as AppBar } from './AppBar.svelte';
+export { default as BottomTabBar } from './BottomTabBar.svelte';
+export type { BottomTabBarIcon, BottomTabBarItem, } from '../util/bottom-tab-bar.js';
+export { default as BottomSheet } from './BottomSheet.svelte';
+export type { BottomSheetCloseReason, BottomSheetSnap, } from '../util/bottom-sheet.js';
+export { default as StickyActionBar } from './StickyActionBar.svelte';
+export { default as Calendar } from './Calendar.svelte';
+export type { CalendarEvent, CalendarStrings, CalendarTone, } from '../util/calendar.js';
+export { default as PhotoGrid } from './PhotoGrid.svelte';
+export { default as PhotoViewer } from './PhotoViewer.svelte';
+export type { Photo, PhotoGridSelectDetail, PhotoGridStrings, PhotoKey, PhotoViewerAction, PhotoViewerCloseReason, PhotoViewerStrings, } from '../util/photo.js';
+export { default as AvatarGroup } from './AvatarGroup.svelte';
+export { DEFAULT_AVATAR_GROUP_STRINGS } from '../util/avatar.js';
+export type { AvatarGroupStrings, AvatarPerson } from '../util/avatar.js';
+export { default as Stepper } from './Stepper.svelte';
+export type { StepperItem, StepperLayout, StepperStep, StepperStepState, StepperStrings, } from '../util/stepper.js';
 export * from './toast-store.js';
+export { DEFAULT_TOASTER_STRINGS, TOAST_DURATIONS } from '../util/toaster.js';
+export type { ToasterStrings, ToastPauseChange, ToastDuration } from '../util/toaster.js';
+export { DEFAULT_SELECT_STRINGS } from '../util/select.js';
+export type { SelectStrings, SelectPresentation } from '../util/select.js';
+export { DEFAULT_SIDEBAR_BRAND_HEADER_STRINGS, DEFAULT_SIDEBAR_FOOTER_STRINGS, } from '../util/sidebar.js';
+export type { SidebarBrandHeaderStrings, SidebarFooterStrings } from '../util/sidebar.js';
+export { DEFAULT_COMPONENT_DEMO_STRINGS, DEFAULT_CONTACT_FORM_STRINGS, DEFAULT_PROPS_TABLE_STRINGS, } from '../util/ready-made-strings.js';
+export type { ComponentDemoStrings, ContactFormStrings, PropsTableStrings, } from '../util/ready-made-strings.js';

package/dist/molecules/index.js

@@ -2,8 +2,10 @@ export { default as Alert } from './Alert.svelte';
 export { default as ComponentDemo } from './ComponentDemo.svelte';
 export { default as ContactForm } from './ContactForm.svelte';
 export { default as Dropdown } from './Dropdown.svelte';
+export { default as DropdownItem } from './DropdownItem.svelte';
 export { default as Form } from './Form.svelte';
 export { default as ImageUpload } from './ImageUpload.svelte';
+export { default as MediaGrid } from './MediaGrid.svelte';
 export { default as Modal } from './Modal.svelte';
 export { default as NavigationMenu } from './NavigationMenu.svelte';
 export { default as NavigationMenuList } from './NavigationMenuList.svelte';
@@ -23,4 +25,29 @@ export { default as Header } from './Header.svelte';
 export { default as EmptyState } from './EmptyState.svelte';
 export { default as Toaster } from './Toaster.svelte';
 export { default as RadioGroup } from './RadioGroup.svelte';
+export { default as SegmentedControl } from './SegmentedControl.svelte';
+export { default as SortableList } from './SortableList.svelte';
+export { default as Collapsible } from './Collapsible.svelte';
+export { default as SwipeableListItem } from './SwipeableListItem.svelte';
+export { DEFAULT_SWIPEABLE_LIST_ITEM_STRINGS } from '../util/swipeable-list-item.js';
+export { default as PullToRefresh } from './PullToRefresh.svelte';
+export { DEFAULT_PULL_TO_REFRESH_STRINGS } from '../util/pull-to-refresh.js';
+export { default as CollapsibleGroup } from './CollapsibleGroup.svelte';
+export { default as ConfirmDialog } from './ConfirmDialog.svelte';
+export { default as Drawer } from './Drawer.svelte';
+export { default as UnsavedChangesBar } from './UnsavedChangesBar.svelte';
+export { default as AppBar } from './AppBar.svelte';
+export { default as BottomTabBar } from './BottomTabBar.svelte';
+export { default as BottomSheet } from './BottomSheet.svelte';
+export { default as StickyActionBar } from './StickyActionBar.svelte';
+export { default as Calendar } from './Calendar.svelte';
+export { default as PhotoGrid } from './PhotoGrid.svelte';
+export { default as PhotoViewer } from './PhotoViewer.svelte';
+export { default as AvatarGroup } from './AvatarGroup.svelte';
+export { DEFAULT_AVATAR_GROUP_STRINGS } from '../util/avatar.js';
+export { default as Stepper } from './Stepper.svelte';
 export * from './toast-store.js';
+export { DEFAULT_TOASTER_STRINGS, TOAST_DURATIONS } from '../util/toaster.js';
+export { DEFAULT_SELECT_STRINGS } from '../util/select.js';
+export { DEFAULT_SIDEBAR_BRAND_HEADER_STRINGS, DEFAULT_SIDEBAR_FOOTER_STRINGS, } from '../util/sidebar.js';
+export { DEFAULT_COMPONENT_DEMO_STRINGS, DEFAULT_CONTACT_FORM_STRINGS, DEFAULT_PROPS_TABLE_STRINGS, } from '../util/ready-made-strings.js';

package/dist/molecules/toast-store.d.ts

@@ -1,17 +1,52 @@
+import type { ToastDuration } from '../util/toaster.js';
 export type ToastLevel = 'success' | 'error' | 'warning' | 'info';
+/**
+ * One action offered inside a toast, such as Undo.
+ *
+ * A toast with an action stays until it is dismissed, unless you give it a
+ * `duration` (a named length or milliseconds): a keyboard user has to reach the button first, and the toaster
+ * may be far away in the tab order (WCAG 2.2.1). `focusToasts()` moves focus
+ * there. The action must still not be the only way to do the thing: offer it
+ * elsewhere in the page as well.
+ */
+export interface ToastAction {
+    /** Button text, and its accessible name. */
+    label: string;
+    onclick: () => void;
+    /** Close the toast after the handler runs. Defaults to `true`. */
+    dismissOnClick?: boolean;
+}
 export interface ToastItem {
     id: string;
-    /** Primary line (always shown). */
+    /**
+     * What the toast says. Always shown: as its one line, or under `title`
+     * when it has one.
+     */
     message: string;
     type: ToastLevel;
+    /** A heading over the message. Without it the message stands alone. */
     title?: string;
-    /** Expandable body; UI can fall back to `message`. */
+    /**
+     * The long version, kept behind a button that opens it. Only a toast
+     * with `detail` has that button.
+     */
     detail?: string;
     /**
-     * Auto-dismiss duration in milliseconds.
-     * When omitted, the toaster uses 14s. Use `0` to keep the toast until dismissed manually.
+     * How long the toast stays: `"short"` (3 s, a few words that need no
+     * reading time), `"medium"` (7 s), `"long"` (14 s), `"persistent"`
+     * (until it is dismissed: what the user has to act on, and errors), or
+     * a number of milliseconds, where `0` is persistent too. What is given
+     * here always wins.
+     *
+     * When omitted, the toaster decides: an error and a toast with an
+     * `action` stay until dismissed. Everything else goes by its title and
+     * message together: up to 120 characters gets `medium` (or the
+     * Toaster's `defaultDuration`), 121 to 240 gets `long`, and more than
+     * 240 stays until dismissed.
      */
-    duration?: number;
+    duration?: ToastDuration;
+    /** An action button in the toast, such as Undo. */
+    action?: ToastAction;
 }
 export declare const toastStore: {
     subscribe: (this: void, run: import("svelte/store").Subscriber<ToastItem[]>, invalidate?: () => void) => import("svelte/store").Unsubscriber;
@@ -19,10 +54,11 @@ export declare const toastStore: {
         message: string;
         type?: ToastLevel;
         /** Same semantics as {@link ToastItem.duration}. */
-        duration?: number;
+        duration?: ToastDuration;
         id?: string;
         title?: string;
         detail?: string;
+        action?: ToastAction;
     }): string;
     dismiss: (id: string) => void;
     clear(): void;
@@ -31,8 +67,18 @@ export declare function pushToast(options: {
     message: string;
     type?: ToastLevel;
     /** Same semantics as {@link ToastItem.duration}. */
-    duration?: number;
+    duration?: ToastDuration;
     title?: string;
     detail?: string;
+    /** An action button in the toast, such as Undo. See {@link ToastAction}. */
+    action?: ToastAction;
 }): string;
 export declare function dismissToast(id: string): void;
+/**
+ * Moves keyboard focus to the newest toast, so its action can be reached
+ * without tabbing through the page. Bind it to a shortcut of your own; the
+ * library registers none. Returns false when there is no toast to focus.
+ *
+ * Focus returns to where it was when that toast is dismissed.
+ */
+export declare function focusToasts(): boolean;

package/dist/molecules/toast-store.js

@@ -15,6 +15,7 @@ function createToastStore() {
                 duration: options.duration,
                 title: options.title,
                 detail: options.detail,
+                action: options.action,
             };
             update((list) => [...list, item]);
             return id;
@@ -32,3 +33,23 @@ export function pushToast(options) {
 export function dismissToast(id) {
     toastStore.dismiss(id);
 }
+/**
+ * Moves keyboard focus to the newest toast, so its action can be reached
+ * without tabbing through the page. Bind it to a shortcut of your own; the
+ * library registers none. Returns false when there is no toast to focus.
+ *
+ * Focus returns to where it was when that toast is dismissed.
+ */
+export function focusToasts() {
+    if (typeof document === 'undefined')
+        return false;
+    const toasts = document.querySelectorAll('[data-zabi-toaster] [data-toast-id]');
+    const newest = toasts[toasts.length - 1];
+    // The action if the toast has one, else its first control.
+    const target = newest?.querySelector('[data-toast-action]') ??
+        newest?.querySelector('button');
+    if (!target)
+        return false;
+    target.focus();
+    return document.activeElement === target;
+}

package/dist/organisms/AppShell.svelte

@@ -0,0 +1,196 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import { untrack } from "svelte";
+    import { markAppShell, publishAppShellInsets } from "../util/app-shell.js";
+    import { cn } from "../util/cn.js";
+
+    /**
+     * The layout of a phone app: a bar at the top, content that scrolls, a
+     * tab bar at the bottom, and none of it under the notch or the home
+     * indicator.
+     *
+     * The shell is exactly as tall as the visible screen (`100dvh`, so the
+     * browser's own bars are accounted for) and only the middle scrolls. The
+     * header stays at the top of that scrolling area; the footer sits below it.
+     *
+     * ```svelte
+     * <AppShell>
+     *     {#snippet header()}
+     *         <AppBar title="Quizrundan" collapseOnScroll />
+     *     {/snippet}
+     *     <div class="p-4">…</div>
+     *     {#snippet footer()}
+     *         <BottomTabBar {items} active={page.url.pathname} />
+     *     {/snippet}
+     * </AppShell>
+     * ```
+     *
+     * Two custom properties on the host say how much of the screen the bars
+     * take, safe areas included, so anything inside the shell can stay clear
+     * of them:
+     *
+     * - `--app-shell-top-inset`: the height of the header;
+     * - `--app-shell-bottom-inset`: the height of the footer.
+     *
+     * Without a bar the value is the safe-area inset alone. The host is the
+     * containing block for anything positioned inside it, and such an element
+     * does not scroll with the content, so a floating button above the tab bar
+     * is `absolute` with `bottom: calc(var(--app-shell-bottom-inset) + 1rem)`.
+     *
+     * While the shell is mounted the same two properties are also set on
+     * `<html>`, so an overlay that is moved to `document.body` (a sheet, a
+     * toast) can read them too. With more than one shell on the page, the one
+     * mounted last is the one mirrored there.
+     */
+    type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "style"> & {
+        /** The top bar, an `AppBar`. It handles the safe area above it. */
+        header?: Snippet;
+        /** The scrolling content, rendered in the element `contentElement` names. */
+        children?: Snippet;
+        /**
+         * The element around the content. `main` when the shell is the page,
+         * which is what it is for. A page has one `<main>`: use `div` for a
+         * shell that sits inside another one, such as a preview in a page of
+         * its own.
+         */
+        contentElement?: "main" | "div";
+        /** The bottom bar, a `BottomTabBar`. It handles the safe area below it. */
+        footer?: Snippet;
+        class?: string;
+        /** Added after the two custom properties the shell sets. */
+        style?: string;
+    };
+
+    let {
+        header,
+        children,
+        contentElement = "main",
+        footer,
+        class: className = "",
+        style = "",
+        ...restProps
+    }: Props = $props();
+
+    markAppShell();
+
+    let headerRegion: HTMLDivElement | undefined = $state();
+    let footerRegion: HTMLDivElement | undefined = $state();
+    /** Measured heights in px; null on the server and until the first measurement. */
+    let headerHeight = $state<number | null>(null);
+    let footerHeight = $state<number | null>(null);
+
+    /**
+     * What the bars measure before they have been measured: the default
+     * heights of AppBar and BottomTabBar. The real size replaces it once the
+     * shell runs, which matters when the text is enlarged or a label wraps.
+     */
+    // In px: AppBar and BottomTabBar keep their height when the text is enlarged.
+    const HEADER_ESTIMATE = "calc(57px + env(safe-area-inset-top, 0px))";
+    const FOOTER_ESTIMATE = "calc(65px + env(safe-area-inset-bottom, 0px))";
+
+    function track(region: HTMLElement | undefined, set: (height: number | null) => void) {
+        if (!region) {
+            set(null);
+            return;
+        }
+        const measure = () => {
+            const height = region.getBoundingClientRect().height;
+            // No layout (a hidden shell, a test DOM): keep the estimate.
+            set(height > 0 ? height : null);
+        };
+        measure();
+        if (typeof ResizeObserver === "undefined") return;
+        const observer = new ResizeObserver(measure);
+        observer.observe(region);
+        return () => observer.disconnect();
+    }
+
+    $effect(() => track(headerRegion, (height) => (headerHeight = height)));
+    $effect(() => track(footerRegion, (height) => (footerHeight = height)));
+
+    const topInset = $derived(
+        !header
+            ? "env(safe-area-inset-top, 0px)"
+            : headerHeight === null
+              ? HEADER_ESTIMATE
+              : `${headerHeight}px`,
+    );
+    const bottomInset = $derived(
+        !footer
+            ? "env(safe-area-inset-bottom, 0px)"
+            : footerHeight === null
+              ? FOOTER_ESTIMATE
+              : `${footerHeight}px`,
+    );
+
+    // On `<html>` as well, for what is rendered outside the shell.
+    let published: ReturnType<typeof publishAppShellInsets> | undefined;
+    $effect(() => {
+        published = untrack(() => publishAppShellInsets(topInset, bottomInset));
+        return () => {
+            published?.leave();
+            published = undefined;
+        };
+    });
+    $effect(() => {
+        published?.update(topInset, bottomInset);
+    });
+
+    const contentClasses = $derived(
+        cn(
+            "min-w-0 flex-1 pl-[env(safe-area-inset-left)] pr-[env(safe-area-inset-right)]",
+            !header && "pt-[env(safe-area-inset-top)]",
+            !footer && "pb-[env(safe-area-inset-bottom)]",
+        ),
+    );
+</script>
+
+<div
+    data-app-shell
+    class={cn(
+        "relative flex h-dvh w-full flex-col overflow-hidden bg-background text-body",
+        className,
+    )}
+    style="--app-shell-top-inset: {topInset}; --app-shell-bottom-inset: {bottomInset}; {style}"
+    {...restProps}
+>
+    <!--
+      The header is inside the scrolling area and sticks to its top. It keeps
+      its place in the flow, so the content starts below it with nothing to
+      measure, and it can slide away (AppBar's collapseOnScroll) without the
+      content moving. scroll-padding keeps a focused field from landing under it.
+    -->
+    <div
+        data-app-shell-scroller
+        class="flex min-h-0 flex-1 flex-col overflow-x-hidden overflow-y-auto overscroll-y-contain scroll-pt-(--app-shell-top-inset)"
+    >
+        {#if header}
+            <!-- An empty strip is left when the bar slides away; it must not take taps. -->
+            <div
+                bind:this={headerRegion}
+                data-app-shell-header
+                class="pointer-events-none sticky top-0 z-sticky shrink-0 *:pointer-events-auto"
+            >
+                {@render header()}
+            </div>
+        {/if}
+        <!-- Two branches, not `<svelte:element>`: hydration takes a dynamic
+        element out and puts it back, which blurs a control inside it that the
+        user had already tabbed to, and the whole page is inside this one. -->
+        {#if contentElement === "div"}
+            <div data-app-shell-content class={contentClasses}>
+                {@render children?.()}
+            </div>
+        {:else}
+            <main data-app-shell-content class={contentClasses}>
+                {@render children?.()}
+            </main>
+        {/if}
+    </div>
+    {#if footer}
+        <div bind:this={footerRegion} data-app-shell-footer class="shrink-0">
+            {@render footer()}
+        </div>
+    {/if}
+</div>

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

@@ -0,0 +1,61 @@
+import type { Snippet } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * The layout of a phone app: a bar at the top, content that scrolls, a
+ * tab bar at the bottom, and none of it under the notch or the home
+ * indicator.
+ *
+ * The shell is exactly as tall as the visible screen (`100dvh`, so the
+ * browser's own bars are accounted for) and only the middle scrolls. The
+ * header stays at the top of that scrolling area; the footer sits below it.
+ *
+ * ```svelte
+ * <AppShell>
+ *     {#snippet header()}
+ *         <AppBar title="Quizrundan" collapseOnScroll />
+ *     {/snippet}
+ *     <div class="p-4">…</div>
+ *     {#snippet footer()}
+ *         <BottomTabBar {items} active={page.url.pathname} />
+ *     {/snippet}
+ * </AppShell>
+ * ```
+ *
+ * Two custom properties on the host say how much of the screen the bars
+ * take, safe areas included, so anything inside the shell can stay clear
+ * of them:
+ *
+ * - `--app-shell-top-inset`: the height of the header;
+ * - `--app-shell-bottom-inset`: the height of the footer.
+ *
+ * Without a bar the value is the safe-area inset alone. The host is the
+ * containing block for anything positioned inside it, and such an element
+ * does not scroll with the content, so a floating button above the tab bar
+ * is `absolute` with `bottom: calc(var(--app-shell-bottom-inset) + 1rem)`.
+ *
+ * While the shell is mounted the same two properties are also set on
+ * `<html>`, so an overlay that is moved to `document.body` (a sheet, a
+ * toast) can read them too. With more than one shell on the page, the one
+ * mounted last is the one mirrored there.
+ */
+type Props = Omit<HTMLAttributes<HTMLDivElement>, "class" | "style"> & {
+    /** The top bar, an `AppBar`. It handles the safe area above it. */
+    header?: Snippet;
+    /** The scrolling content, rendered in the element `contentElement` names. */
+    children?: Snippet;
+    /**
+     * The element around the content. `main` when the shell is the page,
+     * which is what it is for. A page has one `<main>`: use `div` for a
+     * shell that sits inside another one, such as a preview in a page of
+     * its own.
+     */
+    contentElement?: "main" | "div";
+    /** The bottom bar, a `BottomTabBar`. It handles the safe area below it. */
+    footer?: Snippet;
+    class?: string;
+    /** Added after the two custom properties the shell sets. */
+    style?: string;
+};
+declare const AppShell: import("svelte").Component<Props, {}, "">;
+type AppShell = ReturnType<typeof AppShell>;
+export default AppShell;