zabi-components 8.0.0 → 9.0.0

package/dist/atoms/DateField.svelte.d.ts

@@ -0,0 +1,81 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { SizeVariant } from "../types/variants.js";
+import type { DateFieldStrings } from "../util/temporal-field.js";
+/**
+ * A date, picked with the device's own date picker and styled like Input.
+ *
+ * It is a native `<input type="date">`: an iPhone shows its wheels or
+ * calendar, Android its calendar, a desktop browser its own. `value` is
+ * always `YYYY-MM-DD`, or `""` while empty, whatever the field shows.
+ *
+ * What the field shows is the browser's decision, unless it has a
+ * `locale`: without one, the date is in the format of the browser or
+ * device, not of the page, and no attribute changes that. To show a date
+ * as text in the page's language, use `formatDate`:
+ *
+ * ```svelte
+ * <DateField label="Date" bind:value={date} min="2026-01-01" />
+ * <p>{formatDate(date, "sv")}</p>  <!-- 6 okt. 2026 -->
+ * ```
+ *
+ * With `locale`, the field shows the value in that language and its own
+ * picker opens: a Calendar in a BottomSheet (at every width), with Clear
+ * unless the field is `required`. Until the page has run, and without
+ * scripts, it is the native input as above and submits as before; once
+ * it has, the native input stays as the form control, out of sight, and a
+ * button in its place shows the date. `picker="native"` opens the
+ * platform's own picker instead.
+ *
+ * ```svelte
+ * <DateField label="Datum" locale="sv" bind:value format={{ weekday: "short", day: "numeric", month: "short" }} />
+ * ```
+ *
+ * Other attributes (`autocomplete`, `data-*`, `onchange`, ...) land on the
+ * `<input>`.
+ */
+type Props = Omit<HTMLInputAttributes, "class" | "type" | "value" | "size" | "min" | "max" | "step" | "required" | "disabled" | "readonly" | "id" | "name"> & {
+    /** Omit to auto-generate; pair with FormField's `id` when used inside FormField. */
+    id?: string;
+    /** The date as `YYYY-MM-DD`, or `""` while empty. Supports `bind:value`. */
+    value?: string;
+    /** Name the value is submitted under in a form. */
+    name?: string;
+    label?: string;
+    /** True when FormField supplies the visible `<label>`. */
+    hideLabel?: boolean;
+    /** Help text under the field, read out with it. */
+    hint?: string;
+    /** An error under the field. It marks the field invalid and is announced. */
+    error?: string;
+    /** Earliest date that can be picked, as `YYYY-MM-DD`. */
+    min?: string;
+    /** Latest date that can be picked, as `YYYY-MM-DD`. */
+    max?: string;
+    /** Steps between dates that can be picked, in days. */
+    step?: number | "any";
+    required?: boolean;
+    disabled?: boolean;
+    /** Shows the value without letting it be changed; it is still submitted. */
+    readonly?: boolean;
+    /** Height, on the scale Input and Button use. At least 44px on a touch screen. */
+    size?: SizeVariant;
+    /** Extra classes for the `<input>`. */
+    class?: string;
+    /**
+     * Language of the field, as a BCP 47 tag (`sv`, `en-GB`) or a list of them. With it the
+     * field shows the value in that language, whatever the browser's is, and opens the
+     * library's own picker; see above. Left out, the field is the native input.
+     */
+    locale?: string | string[];
+    /** With `locale`: how the value is shown, as options of `Intl.DateTimeFormat`. Default: what formatDate gives for the locale. */
+    format?: Intl.DateTimeFormatOptions;
+    /** With `locale`: shown in the placeholder colour while the field is empty. */
+    placeholder?: string;
+    /** With `locale`: `library` (default) opens the library's calendar in a sheet; `native` opens the platform's own picker. */
+    picker?: "library" | "native";
+    /** With `locale`: the words the field says; replace any of them to translate. */
+    strings?: Partial<DateFieldStrings>;
+};
+declare const DateField: import("svelte").Component<Props, {}, "value">;
+type DateField = ReturnType<typeof DateField>;
+export default DateField;

package/dist/atoms/FieldMessages.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+    import CheckCircle from "@lucide/svelte/icons/circle-check-big";
+    import AlertCircle from "@lucide/svelte/icons/circle-alert";
+    import AlertTriangle from "@lucide/svelte/icons/triangle-alert";
+    import { cn } from "../util/cn.js";
+    import { fieldHintId, fieldMessageId, type FieldMessageState } from "../util/field.js";
+
+    /**
+     * The text under a field: its status message and its hint. Internal: it is
+     * not exported from the package. Input, Textarea and Select render it, and
+     * DateField and TimeField through Input, so the markup, the ids and the
+     * way a message is announced are the same in all of them.
+     *
+     * The ids are the ones `fieldDescribedBy` lists on the control.
+     */
+    interface Props {
+        /** Id of the control the text belongs to. */
+        fieldId: string;
+        /** From `fieldMessageState`. */
+        status: FieldMessageState;
+        hint?: string;
+        /** Distance from the control, and between the two: Textarea and Select sit 4px closer. */
+        gap?: "mt-1" | "mt-2";
+        /** Extra classes for the status message. */
+        messageClass?: string;
+    }
+
+    let { fieldId, status, hint = "", gap = "mt-2", messageClass = "" }: Props = $props();
+
+    // Message text uses the `-text` step (700), which clears 4.5:1 on a page
+    // surface; the solid fill step (600) is for fills, not for small text.
+    const toneClass = $derived(
+        status.variant === "error"
+            ? "text-error-text"
+            : status.variant === "success"
+              ? "text-success-text"
+              : status.variant === "warning"
+                ? "text-warning-text"
+                : "text-description",
+    );
+
+    const Icon = $derived(
+        status.variant === "error"
+            ? AlertCircle
+            : status.variant === "success"
+              ? CheckCircle
+              : status.variant === "warning"
+                ? AlertTriangle
+                : null,
+    );
+</script>
+
+{#if status.showMessage}
+    <p
+        id={fieldMessageId(fieldId)}
+        class={cn("flex items-center gap-2 text-sm", gap, toneClass, messageClass)}
+        role={status.variant === "error" ? "alert" : "status"}
+        aria-live={status.variant === "error" ? "assertive" : "polite"}
+    >
+        {#if Icon}
+            <Icon size={14} class="shrink-0" />
+        {/if}
+        <span>{status.message}</span>
+    </p>
+{/if}
+{#if status.showHint}
+    <!-- Not a live region: a hint is there from the start and is read with the field. -->
+    <p id={fieldHintId(fieldId)} class={cn("text-sm text-description", gap)}>{hint}</p>
+{/if}

package/dist/atoms/FieldMessages.svelte.d.ts

@@ -0,0 +1,23 @@
+import { type FieldMessageState } from "../util/field.js";
+/**
+ * The text under a field: its status message and its hint. Internal: it is
+ * not exported from the package. Input, Textarea and Select render it, and
+ * DateField and TimeField through Input, so the markup, the ids and the
+ * way a message is announced are the same in all of them.
+ *
+ * The ids are the ones `fieldDescribedBy` lists on the control.
+ */
+interface Props {
+    /** Id of the control the text belongs to. */
+    fieldId: string;
+    /** From `fieldMessageState`. */
+    status: FieldMessageState;
+    hint?: string;
+    /** Distance from the control, and between the two: Textarea and Select sit 4px closer. */
+    gap?: "mt-1" | "mt-2";
+    /** Extra classes for the status message. */
+    messageClass?: string;
+}
+declare const FieldMessages: import("svelte").Component<Props, {}, "">;
+type FieldMessages = ReturnType<typeof FieldMessages>;
+export default FieldMessages;

package/dist/atoms/FloatingActionButton.svelte

@@ -0,0 +1,176 @@
+<script lang="ts">
+    import type { Component } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import Plus from "@lucide/svelte/icons/plus";
+    import { findScrollParent, isInsideAppShell } from "../util/app-shell.js";
+    import { cn } from "../util/cn.js";
+    import { reserveScrollPaddingBottom } from "../util/scroll-padding.js";
+
+    /**
+     * The one main thing to do on a screen, as a round button that floats over
+     * the content: new quiz, compose, add.
+     *
+     * Inside an `AppShell` it is placed against the shell, 16px above the tab
+     * bar. On its own it is fixed to the screen, 16px above the home
+     * indicator; if something else is fixed to the bottom there (a
+     * `BottomTabBar` on its own), say how tall it is with
+     * `--fab-bottom-offset` on the button or any ancestor:
+     *
+     * ```svelte
+     * <FloatingActionButton
+     *     label="New quiz"
+     *     onclick={create}
+     *     style="--fab-bottom-offset: 64px"
+     * />
+     * ```
+     *
+     * It lies over the content, so the last row would stay under it at the
+     * end of the page. Give the content room to scroll clear: `pb-24` (96px)
+     * on the list covers the button and its margins.
+     *
+     * While it is mounted it sets `scroll-padding-bottom` on what scrolls
+     * under it (the shell's content, or the page) to the height it takes
+     * from the bottom, so a row that takes keyboard focus is scrolled clear
+     * of the button and not left half under it.
+     */
+    type Props = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+        /** What the button does. Its accessible name, and its text when `extended`. */
+        label: string;
+        /** An icon component, as `@lucide/svelte` icons are. A plus sign by default. */
+        icon?: Component<{ size?: number; class?: string }>;
+        /** Shows the label as text beside the icon. */
+        extended?: boolean;
+        /** Makes it a link to this address. Without it, it is a button. */
+        href?: string;
+        /**
+         * The bottom corner it sits in. `bottom-end` is the right in a
+         * left-to-right page and the left in a right-to-left one.
+         */
+        position?: "bottom-end" | "bottom-start" | "bottom-center";
+        class?: string;
+    };
+
+    let {
+        label,
+        icon,
+        extended = false,
+        href,
+        position = "bottom-end",
+        class: className = "",
+        ...restProps
+    }: Props = $props();
+
+    const inShell = isInsideAppShell();
+    const Icon = $derived(icon ?? Plus);
+
+    let host = $state<HTMLElement>();
+
+    /**
+     * The browser scrolls a focused control into view, to the edge of the
+     * scroll container: under this button, which lies over that edge. The
+     * room it takes, from its top edge to the bottom of the container, is
+     * reserved through the helper the bars use, so the largest request wins.
+     */
+    $effect(() => {
+        const button = host;
+        if (!button) return;
+        const scroller = findScrollParent(button);
+        const reservation = reserveScrollPaddingBottom(scroller ?? document.documentElement);
+        const reserve = () => {
+            const top = button.getBoundingClientRect().top;
+            const bottom = scroller
+                ? scroller.getBoundingClientRect().bottom
+                : document.documentElement.clientHeight;
+            // No layout (a test DOM, a hidden button): nothing to keep clear of.
+            reservation.set(button.offsetHeight > 0 ? Math.max(0, Math.ceil(bottom - top)) : 0);
+        };
+        reserve();
+        const observer =
+            typeof ResizeObserver === "function" ? new ResizeObserver(reserve) : undefined;
+        observer?.observe(button);
+        if (scroller) observer?.observe(scroller);
+        window.addEventListener("resize", reserve);
+        return () => {
+            observer?.disconnect();
+            window.removeEventListener("resize", reserve);
+            reservation.release();
+        };
+    });
+
+    /**
+     * 16px from the edges, in px: a margin that grew with the text size would
+     * push the button into the content it floats over. The side clears a
+     * notch in landscape, whichever side that is on.
+     */
+    const positionClasses = $derived(
+        {
+            "bottom-end":
+                "end-[calc(16px+max(env(safe-area-inset-left,0px),env(safe-area-inset-right,0px)))]",
+            "bottom-start":
+                "start-[calc(16px+max(env(safe-area-inset-left,0px),env(safe-area-inset-right,0px)))]",
+            // Not `left-1/2` with a shift back: that leaves the button half
+            // the width to lay its label out in.
+            "bottom-center": "inset-x-0 mx-auto w-fit",
+        }[position] ??
+            "end-[calc(16px+max(env(safe-area-inset-left,0px),env(safe-area-inset-right,0px)))]",
+    );
+
+    const classes = $derived(
+        cn(
+            "focus-ring z-sticky inline-flex cursor-pointer items-center justify-center gap-2 rounded-pill no-underline shadow-lg select-none",
+            // Round: 56px in px, like the 24px icon in it, so it does not
+            // double with the text size and cover twice the content.
+            // Extended: it holds text, so its height follows the text; it
+            // grows sideways, and downwards if the label wraps.
+            extended ? "min-h-14 min-w-14" : "size-[56px]",
+            // Transparent until forced-colors mode draws it: the fill is gone there.
+            "border border-transparent",
+            "bg-action-primary bg-control-gradient text-action-primary",
+            "transition-[background-color,scale] duration-(--duration-base) active:scale-[0.96] motion-reduce:transition-none motion-reduce:active:scale-100",
+            extended ? "px-5 py-2 text-sm font-medium" : "p-0",
+            // Never wider than the screen it floats on, margins included.
+            "[max-inline-size:calc(100%_-_32px)]",
+            inShell
+                ? "absolute bottom-[calc(var(--app-shell-bottom-inset,0px)+var(--fab-bottom-offset,0px)+16px)]"
+                : "fixed bottom-[calc(env(safe-area-inset-bottom,0px)+var(--fab-bottom-offset,0px)+16px)]",
+            positionClasses,
+            className,
+        ),
+    );
+</script>
+
+{#snippet content()}
+    <!-- Decorative: the label names the button, shown or not. -->
+    <span class="flex size-[24px] shrink-0" aria-hidden="true">
+        <Icon size={24} />
+    </span>
+    {#if extended}
+        <span class="min-w-0 [overflow-wrap:anywhere]">{label}</span>
+    {/if}
+{/snippet}
+
+{#if href !== undefined}
+    <a
+        bind:this={host}
+        {href}
+        class={classes}
+        aria-label={extended ? undefined : label}
+        data-position={position}
+        data-toast-clear
+        {...restProps}
+    >
+        {@render content()}
+    </a>
+{:else}
+    <button
+        bind:this={host}
+        type="button"
+        class={classes}
+        aria-label={extended ? undefined : label}
+        data-position={position}
+        data-toast-clear
+        {...restProps}
+    >
+        {@render content()}
+    </button>
+{/if}

package/dist/atoms/FloatingActionButton.svelte.d.ts

@@ -0,0 +1,51 @@
+import type { Component } from "svelte";
+import type { HTMLAttributes } from "svelte/elements";
+/**
+ * The one main thing to do on a screen, as a round button that floats over
+ * the content: new quiz, compose, add.
+ *
+ * Inside an `AppShell` it is placed against the shell, 16px above the tab
+ * bar. On its own it is fixed to the screen, 16px above the home
+ * indicator; if something else is fixed to the bottom there (a
+ * `BottomTabBar` on its own), say how tall it is with
+ * `--fab-bottom-offset` on the button or any ancestor:
+ *
+ * ```svelte
+ * <FloatingActionButton
+ *     label="New quiz"
+ *     onclick={create}
+ *     style="--fab-bottom-offset: 64px"
+ * />
+ * ```
+ *
+ * It lies over the content, so the last row would stay under it at the
+ * end of the page. Give the content room to scroll clear: `pb-24` (96px)
+ * on the list covers the button and its margins.
+ *
+ * While it is mounted it sets `scroll-padding-bottom` on what scrolls
+ * under it (the shell's content, or the page) to the height it takes
+ * from the bottom, so a row that takes keyboard focus is scrolled clear
+ * of the button and not left half under it.
+ */
+type Props = Omit<HTMLAttributes<HTMLElement>, "class"> & {
+    /** What the button does. Its accessible name, and its text when `extended`. */
+    label: string;
+    /** An icon component, as `@lucide/svelte` icons are. A plus sign by default. */
+    icon?: Component<{
+        size?: number;
+        class?: string;
+    }>;
+    /** Shows the label as text beside the icon. */
+    extended?: boolean;
+    /** Makes it a link to this address. Without it, it is a button. */
+    href?: string;
+    /**
+     * The bottom corner it sits in. `bottom-end` is the right in a
+     * left-to-right page and the left in a right-to-left one.
+     */
+    position?: "bottom-end" | "bottom-start" | "bottom-center";
+    class?: string;
+};
+declare const FloatingActionButton: Component<Props, {}, "">;
+type FloatingActionButton = ReturnType<typeof FloatingActionButton>;
+export default FloatingActionButton;

package/dist/atoms/Heading.svelte

@@ -2,6 +2,8 @@
     import type { Snippet } from "svelte";
     import type { HTMLAttributes } from "svelte/elements";
     import { cn } from "../util/cn.js";
+    import type { OnFillTone } from "../types/variants.js";
+    import { displayVoice } from "../util/display-voice.js";
 
     /** Semantic heading level — also the default visual size. */
     type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
@@ -16,6 +18,19 @@
         size?: HeadingLevel;
         /** Heading text. Ignored when `children` is provided. */
         text?: string;
+        /**
+         * Text colour. `headline` (the default) is for a page or a card. On a
+         * filled block use `inherit` (the block's own colour), `on-brand` or
+         * `on-accent`.
+         */
+        tone?: "headline" | OnFillTone;
+        /**
+         * `heading` is the document heading voice. `display` is the second
+         * face (`--font-family-display`) with larger steps, for a hero, a
+         * score or a big number; its weight and tracking are the custom
+         * properties `--zabi-display-weight` and `--zabi-display-tracking`.
+         */
+        variant?: "heading" | "display";
         class?: string;
         children?: Snippet;
     };
@@ -24,13 +39,21 @@
         level = 1,
         size,
         text = "",
+        tone = "headline",
+        variant = "heading",
         class: className = "",
         children,
         ...restProps
     }: Props = $props();
 
+    const toneClasses: Record<"headline" | OnFillTone, string> = {
+        headline: "text-headline",
+        inherit: "text-inherit",
+        "on-brand": "text-on-brand",
+        "on-accent": "text-on-accent",
+    };
+
     const visualSize = $derived(size ?? level);
-    const Tag = $derived(`h${level}`);
 
     /**
      * Display sizes tighten as they grow. Untracked 36px type with default
@@ -47,21 +70,56 @@
         6: "text-base leading-6 font-semibold",
     };
 
+    /**
+     * Display steps: 60px (48 on a phone), 48 (36), 36 (30), 30, 24, 20. Weight and tracking come from
+     * `displayVoice`, so no size carries its own.
+     */
+    const displaySizeClasses: Record<HeadingLevel, string> = {
+        1: "text-5xl sm:text-6xl leading-[1.0]",
+        2: "text-4xl sm:text-5xl leading-[1.05]",
+        3: "text-3xl sm:text-4xl leading-[1.1]",
+        4: "text-3xl leading-[1.2]",
+        5: "text-2xl leading-[1.2]",
+        6: "text-xl leading-[1.2]",
+    };
+
     const headingClasses = $derived(
-        cn(`text-headline ${sizeClasses[visualSize] ?? sizeClasses[6]} ${className}`),
+        variant === "display"
+            ? cn(
+                  `${toneClasses[tone] ?? toneClasses.headline} font-display text-balance ${displayVoice} ${displaySizeClasses[visualSize] ?? displaySizeClasses[6]} ${className}`,
+              )
+            : cn(`${toneClasses[tone] ?? toneClasses.headline} ${sizeClasses[visualSize] ?? sizeClasses[6]} ${className}`),
     );
 </script>
 
 <!--
-  The font family comes from `--font-family-sans`, applied on `body`. This
+  The font family comes from `--font-family-heading`, which the theme applies
+  to h1–h6 in its base layer and which defaults to `--font-family-sans`. This
   component used to carry its own `font-family: "Nunito Sans"` in a local
   <style> block, which meant a consumer who rebranded the font token got a
   rebranded body and Nunito Sans headings.
 -->
-<svelte:element this={Tag} class={headingClasses} {...restProps}>
+{#snippet content()}
     {#if children}
         {@render children()}
     {:else}
         {text}
     {/if}
-</svelte:element>
+{/snippet}
+
+<!-- One branch per level, not a dynamic element: hydration takes a dynamic
+element out and puts it back, which blurs a control inside it that the user
+had already tabbed to. -->
+{#if level === 1}
+    <h1 class={headingClasses} {...restProps}>{@render content()}</h1>
+{:else if level === 2}
+    <h2 class={headingClasses} {...restProps}>{@render content()}</h2>
+{:else if level === 3}
+    <h3 class={headingClasses} {...restProps}>{@render content()}</h3>
+{:else if level === 4}
+    <h4 class={headingClasses} {...restProps}>{@render content()}</h4>
+{:else if level === 5}
+    <h5 class={headingClasses} {...restProps}>{@render content()}</h5>
+{:else}
+    <h6 class={headingClasses} {...restProps}>{@render content()}</h6>
+{/if}

package/dist/atoms/Heading.svelte.d.ts

@@ -1,5 +1,6 @@
 import type { Snippet } from "svelte";
 import type { HTMLAttributes } from "svelte/elements";
+import type { OnFillTone } from "../types/variants.js";
 /** Semantic heading level — also the default visual size. */
 type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 type Props = Omit<HTMLAttributes<HTMLHeadingElement>, "class"> & {
@@ -12,6 +13,19 @@ type Props = Omit<HTMLAttributes<HTMLHeadingElement>, "class"> & {
     size?: HeadingLevel;
     /** Heading text. Ignored when `children` is provided. */
     text?: string;
+    /**
+     * Text colour. `headline` (the default) is for a page or a card. On a
+     * filled block use `inherit` (the block's own colour), `on-brand` or
+     * `on-accent`.
+     */
+    tone?: "headline" | OnFillTone;
+    /**
+     * `heading` is the document heading voice. `display` is the second
+     * face (`--font-family-display`) with larger steps, for a hero, a
+     * score or a big number; its weight and tracking are the custom
+     * properties `--zabi-display-weight` and `--zabi-display-tracking`.
+     */
+    variant?: "heading" | "display";
     class?: string;
     children?: Snippet;
 };