zabi-components 8.0.0 → 9.0.0

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

@@ -1,4 +1,6 @@
-import type { Snippet } from 'svelte';
+import { type Snippet } from 'svelte';
+import { type DropdownOption, type DropdownPresentation } from "../util/dropdown.js";
+import type { BottomSheetSnap } from "../util/bottom-sheet.js";
 export type DropdownTriggerProps = {
     'aria-expanded': boolean;
     'aria-haspopup': 'menu' | 'listbox';
@@ -8,16 +10,55 @@ interface Props {
     /** Extra classes for the host element. */
     class?: string;
     isOpen?: boolean;
+    /**
+     * The side the menu opens on. It is where the menu goes whenever it
+     * fits there; near an edge of the screen it flips to the other side,
+     * and is narrowed or given its own scroll when neither side has room.
+     */
     placement?: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+    /**
+     * How the menu is shown. `popover`: under its trigger, as always.
+     * `sheet`: in a BottomSheet, with the same items, roles and keys; this
+     * is the action sheet ("Edit, Share, Delete" from the bottom of the
+     * screen). `auto`: a sheet on a phone (a touch screen narrower than
+     * 640px), the pop-over everywhere else. Decided each time the menu
+     * opens, in the browser.
+     */
+    presentation?: DropdownPresentation;
+    /**
+     * The host fills its container instead of being as wide as its
+     * trigger's content, and the menu is at least as wide as the host.
+     * For a trigger that is a field (Select); a menu on an icon button
+     * stays as it is.
+     */
+    fullWidth?: boolean;
+    /** Heading of the sheet. Without it, `ariaLabel` is. */
+    sheetTitle?: string;
+    /**
+     * The height the sheet opens at. Without it: half the screen for up
+     * to six `options`, all of it for more. The grip moves it either way.
+     */
+    sheetSnap?: BottomSheetSnap;
+    /** The sheet is as tall as the list, up to half the screen (BottomSheet `fit`); the grip then only drags. Off by default. */
+    sheetFit?: boolean;
+    /** Accessible name of the sheet's close button. */
+    sheetCloseLabel?: string;
+    /** Accessible name of the sheet's grip while its button takes the sheet up a step. */
+    sheetExpandLabel?: string;
+    /** The same, while it takes the sheet down a step. */
+    sheetCollapseLabel?: string;
     ariaLabel?: string;
+    /** Id of an element that names the list; wins over `ariaLabel` for the pop-over list. */
+    ariaLabelledby?: string;
     /** `listbox` for Select-style; `menu` for actions. */
     menuRole?: 'menu' | 'listbox';
     selectedValue?: string | number | null;
-    options?: Array<{
-        value: string | number;
-        label: string;
-        disabled?: boolean;
-    }>;
+    /**
+     * Menu items, when not supplying children. Each takes an optional
+     * `icon`, `tone` (`danger`) and `description`; a disabled item stays
+     * focusable so its description can be read.
+     */
+    options?: DropdownOption[];
     onOptionClick?: (value: string | number) => void;
     trigger: Snippet<[DropdownTriggerProps]>;
     /** Rendered in the popup above the menu/listbox, outside its role (e.g. a search field). */

package/dist/molecules/DropdownItem.svelte

@@ -0,0 +1,122 @@
+<script lang="ts">
+    import Check from "@lucide/svelte/icons/check";
+    import { getContext, type Snippet } from "svelte";
+    import type { HTMLButtonAttributes } from "svelte/elements";
+    import { generateId } from "../util/ssr-safe.js";
+    import { cn } from "../util/cn.js";
+    import {
+        DROPDOWN_CONTEXT_KEY,
+        type DropdownContext,
+        type DropdownItemIcon,
+        type DropdownItemTone,
+    } from "../util/dropdown.js";
+
+    type Props = Omit<HTMLButtonAttributes, "class" | "disabled"> & {
+        /** The text of the item, and its accessible name. Use `children` for custom content instead. */
+        label?: string;
+        /** Second line under the label, e.g. why the item is disabled. */
+        description?: string;
+        /** Rendered before the label, at 16px. Decorative: the label names the item. */
+        icon?: DropdownItemIcon;
+        /** `danger` for a destructive action such as Delete. */
+        tone?: DropdownItemTone;
+        /**
+         * Rendered as `aria-disabled`, not `disabled`: the item stays focusable,
+         * so the arrow keys reach it and its description is read, but a click
+         * does nothing.
+         */
+        disabled?: boolean;
+        /** Marks the chosen option of a listbox (`aria-selected`). */
+        selected?: boolean;
+        /** Extra classes for the item. */
+        class?: string;
+        /** Replaces `label` as the content. */
+        children?: Snippet;
+    };
+
+    let {
+        label = "",
+        description = "",
+        icon: Icon,
+        tone = "default",
+        disabled = false,
+        selected = false,
+        role,
+        class: className = "",
+        onclick,
+        children,
+        ...restProps
+    }: Props = $props();
+
+    const dropdown = getContext<DropdownContext | undefined>(DROPDOWN_CONTEXT_KEY);
+    // The keyboard model of Dropdown finds items by role, so there is always one.
+    const itemRole = $derived(role ?? dropdown?.itemRole ?? "menuitem");
+
+    const labelId = generateId("dropdown-item-label");
+    const descriptionId = generateId("dropdown-item-description");
+
+    function handleClick(
+        event: MouseEvent & { currentTarget: EventTarget & HTMLButtonElement },
+    ) {
+        if (disabled) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        onclick?.(event);
+    }
+
+    const itemClasses = $derived(
+        cn(
+            "focus-ring flex w-full items-start justify-start gap-2 rounded-control px-3 py-2 pointer-coarse:py-3 text-start text-sm transition-colors focus:outline-none",
+            tone === "danger" ? "text-error-text focus-ring--danger" : "text-body",
+            disabled
+                ? "cursor-not-allowed"
+                : tone === "danger"
+                  ? "cursor-pointer hover:bg-action-danger-subtle active:bg-action-danger-subtle-hover"
+                  : "cursor-pointer hover:bg-surface-overlay-hover active:bg-surface-active",
+            // The chosen option has a fill and a check: a mark of its own,
+            // which is neither the focus ring nor colour alone.
+            itemRole === "option" && selected && "bg-surface-overlay-hover text-headline",
+            className,
+        ),
+    );
+    // The description explains a disabled item, so it is never dimmed with it.
+    const dimmed = $derived(disabled ? "opacity-50" : "");
+</script>
+
+<button
+    type="button"
+    role={itemRole}
+    aria-selected={itemRole === "option" ? selected : undefined}
+    aria-disabled={disabled ? "true" : undefined}
+    aria-labelledby={description && (label || children) ? labelId : undefined}
+    aria-describedby={description ? descriptionId : undefined}
+    class={itemClasses}
+    onclick={handleClick}
+    {...restProps}
+>
+    {#if Icon}
+        <span class="mt-0.5 shrink-0 {dimmed}" aria-hidden="true">
+            <Icon size={16} />
+        </span>
+    {/if}
+    <span class="min-w-0 flex-1">
+        {#if children}
+            <!-- The label when there is a description, so the name is the content alone. -->
+            <span id={labelId} class="block {dimmed}">{@render children()}</span>
+        {:else}
+            <span id={labelId} class="block {dimmed}">{label}</span>
+        {/if}
+        {#if description}
+            <span id={descriptionId} class="mt-0.5 block text-xs text-description">
+                {description}
+            </span>
+        {/if}
+    </span>
+    {#if itemRole === "option" && selected}
+        <span class="mt-0.5 shrink-0 text-headline" aria-hidden="true">
+            <Check size={16} />
+        </span>
+    {/if}
+</button>

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

@@ -0,0 +1,28 @@
+import { type Snippet } from "svelte";
+import type { HTMLButtonAttributes } from "svelte/elements";
+import { type DropdownItemIcon, type DropdownItemTone } from "../util/dropdown.js";
+type Props = Omit<HTMLButtonAttributes, "class" | "disabled"> & {
+    /** The text of the item, and its accessible name. Use `children` for custom content instead. */
+    label?: string;
+    /** Second line under the label, e.g. why the item is disabled. */
+    description?: string;
+    /** Rendered before the label, at 16px. Decorative: the label names the item. */
+    icon?: DropdownItemIcon;
+    /** `danger` for a destructive action such as Delete. */
+    tone?: DropdownItemTone;
+    /**
+     * Rendered as `aria-disabled`, not `disabled`: the item stays focusable,
+     * so the arrow keys reach it and its description is read, but a click
+     * does nothing.
+     */
+    disabled?: boolean;
+    /** Marks the chosen option of a listbox (`aria-selected`). */
+    selected?: boolean;
+    /** Extra classes for the item. */
+    class?: string;
+    /** Replaces `label` as the content. */
+    children?: Snippet;
+};
+declare const DropdownItem: import("svelte").Component<Props, {}, "">;
+type DropdownItem = ReturnType<typeof DropdownItem>;
+export default DropdownItem;

package/dist/molecules/EmptyState.svelte

@@ -2,10 +2,18 @@
     import type { Snippet } from "svelte";
     import { generateId } from "../util/ssr-safe.js";
     import { cn } from "../util/cn.js";
+    import type { CollapsibleHeadingLevel } from "../util/collapsible.js";
 
     interface Props {
         title: string;
         description: string;
+        /** Heading element of the title, to fit the outline of the page around it. */
+        headingLevel?: CollapsibleHeadingLevel;
+        /**
+         * `compact` tightens the padding and the title to sit inside a card,
+         * and is a plain `<div>`, not a landmark region like the default.
+         */
+        size?: "default" | "compact";
         class?: string;
         action?: Snippet;
         media?: Snippet;
@@ -14,32 +22,69 @@
     let {
         title,
         description,
+        headingLevel = 2,
+        size = "default",
         class: className = "",
         action,
         media,
     }: Props = $props();
 
     const titleId = generateId("empty-state-title");
+    const compact = $derived(size === "compact");
+    const rootClasses = $derived(
+        cn(
+            "mx-auto flex flex-col items-center justify-center text-center",
+            compact ? "gap-3 px-4 py-6" : "gap-4 px-6 py-12",
+            className,
+        ),
+    );
 </script>
 
-<section
-    class={cn("mx-auto flex flex-col items-center justify-center gap-4 px-6 py-12 text-center", className)}
-    aria-labelledby={titleId}
->
+{#snippet body()}
+    {@const headingClasses = cn("font-semibold text-headline", compact ? "text-base" : "text-lg")}
     {#if media}
         <div class="text-description" aria-hidden="true">
             {@render media()}
         </div>
     {/if}
-    <div class="space-y-2">
-        <h2 id={titleId} class="text-lg font-semibold text-headline">
-            {title}
-        </h2>
+    <div class={compact ? "space-y-1" : "space-y-2"}>
+        {#if headingLevel === 1}
+            <h1 id={titleId} class={headingClasses}>{title}</h1>
+        {:else if headingLevel === 2}
+            <h2 id={titleId} class={headingClasses}>{title}</h2>
+        {:else if headingLevel === 3}
+            <h3 id={titleId} class={headingClasses}>{title}</h3>
+        {:else if headingLevel === 4}
+            <h4 id={titleId} class={headingClasses}>{title}</h4>
+        {:else if headingLevel === 5}
+            <h5 id={titleId} class={headingClasses}>{title}</h5>
+        {:else}
+            <h6 id={titleId} class={headingClasses}>{title}</h6>
+        {/if}
         <p class="text-sm text-description">{description}</p>
     </div>
     {#if action}
-        <div class="mt-2 flex flex-wrap items-center justify-center gap-2">
+        <div
+            class={cn("flex flex-wrap items-center justify-center gap-2", compact ? "mt-1" : "mt-2")}
+        >
             {@render action()}
         </div>
     {/if}
-</section>
+{/snippet}
+
+<!-- A named `<section>` is a landmark. One per page is a help; a compact empty
+     state in every card is a page of landmarks, so that size is a plain `<div>`.
+
+     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. The heading is one branch per level for the same
+     reason. -->
+{#if compact}
+    <div class={rootClasses}>
+        {@render body()}
+    </div>
+{:else}
+    <section class={rootClasses} aria-labelledby={titleId}>
+        {@render body()}
+    </section>
+{/if}

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

@@ -1,7 +1,15 @@
 import type { Snippet } from "svelte";
+import type { CollapsibleHeadingLevel } from "../util/collapsible.js";
 interface Props {
     title: string;
     description: string;
+    /** Heading element of the title, to fit the outline of the page around it. */
+    headingLevel?: CollapsibleHeadingLevel;
+    /**
+     * `compact` tightens the padding and the title to sit inside a card,
+     * and is a plain `<div>`, not a landmark region like the default.
+     */
+    size?: "default" | "compact";
     class?: string;
     action?: Snippet;
     media?: Snippet;

package/dist/molecules/FormField.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+    import { zabiCommonStrings } from "../util/zabi-strings.js";
     import type { Snippet } from 'svelte';
     import { generateId } from "../util/ssr-safe.js";
 
@@ -17,6 +18,8 @@
         description?: string;
         error?: string;
         required?: boolean;
+        /** Read after the label of a required field, where the asterisk is only seen. */
+        requiredLabel?: string;
         disabled?: boolean;
         class?: string;
         labelClass?: string;
@@ -30,6 +33,7 @@
         description,
         error,
         required = false,
+        requiredLabel: requiredLabelGiven,
         disabled = false,
         class: className = '',
         labelClass = '',
@@ -37,6 +41,10 @@
         meta,
     }: Props = $props();
 
+    /** Words many components share: a `ZabiStringsProvider` above this one may give them; else English. */
+    const common = zabiCommonStrings();
+    const requiredLabel = $derived(requiredLabelGiven ?? common().required);
+
     const fallbackId = generateId('field');
     const fieldId = $derived(idProp ?? fallbackId);
     const descriptionId = $derived(
@@ -63,7 +71,7 @@
             {label}
             {#if required}
                 <span class="ml-1 text-error" aria-hidden="true">*</span>
-                <span class="sr-only">(required)</span>
+                <span class="sr-only">{requiredLabel}</span>
             {/if}
         </label>
 

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

@@ -12,6 +12,8 @@ interface Props {
     description?: string;
     error?: string;
     required?: boolean;
+    /** Read after the label of a required field, where the asterisk is only seen. */
+    requiredLabel?: string;
     disabled?: boolean;
     class?: string;
     labelClass?: string;

package/dist/molecules/Header.svelte

@@ -42,7 +42,7 @@
                 Variants / states:
             </span>
             {#each variantsStates as v (v)}
-                <span class="rounded-control bg-base-100 px-2 py-1 text-xs text-headline">
+                <span class="rounded-control bg-neutral-subtle px-2 py-1 text-xs text-headline">
                     {v}
                 </span>
             {/each}