zabi-components 7.0.2 → 8.1.0

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

@@ -0,0 +1,53 @@
+import type { HTMLInputAttributes } from "svelte/elements";
+import type { SizeVariant } from "../types/variants.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: the date 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 -->
+ * ```
+ *
+ * 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;
+};
+declare const DateField: import("svelte").Component<Props, {}, "value">;
+type DateField = ReturnType<typeof DateField>;
+export default DateField;

package/dist/atoms/Divider.svelte

@@ -1,4 +1,6 @@
 <script lang="ts">
+    import { cn } from "../util/cn.js";
+
     type Orientation = 'horizontal' | 'vertical';
 
     interface Props {
@@ -34,13 +36,11 @@
 </script>
 
 <div
-    class={[
+    class={cn(
         'flex items-center text-description',
         isVertical ? 'h-full min-h-[1rem] flex-col' : 'w-full flex-row',
         className,
-    ]
-        .filter(Boolean)
-        .join(' ')}
+    )}
 >
     <div
         aria-hidden={decorative ? 'true' : undefined}

package/dist/atoms/FeatureCard.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
     import type { Component, Snippet } from "svelte";
+    import { cn } from "../util/cn.js";
 
     interface Props {
         title: string;
@@ -19,18 +20,18 @@
 </script>
 
 <article
-    class="flex flex-col gap-3 p-6 rounded-2xl bg-surface-1 border border-base-200 transition-colors duration-200 hover:border-base-300 {className}"
+    class={cn("flex flex-col gap-3 p-6 rounded-container bg-surface-1 border border-border transition-colors duration-200 hover:border-border-medium", className)}
 >
     {#if Icon}
         <span
-            class="inline-flex items-center justify-center w-10 h-10 rounded-lg bg-brand-50 text-brand-600"
+            class="inline-flex items-center justify-center w-10 h-10 rounded-control bg-brand-50 text-brand-600"
             aria-hidden="true"
         >
             <Icon size={20} />
         </span>
     {/if}
 
-    <div class="flex flex-col gap-1.5">
+    <div class="flex flex-col gap-2">
         <h3 class="text-base font-semibold leading-snug text-headline">
             {title}
         </h3>

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,174 @@
+<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: 65px"
+     * />
+     * ```
+     *
+     * 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 text-action-primary",
+            "transition-[background-color,scale] duration-150 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}
+        {...restProps}
+    >
+        {@render content()}
+    </a>
+{:else}
+    <button
+        bind:this={host}
+        type="button"
+        class={classes}
+        aria-label={extended ? undefined : label}
+        data-position={position}
+        {...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: 65px"
+ * />
+ * ```
+ *
+ * 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

@@ -1,38 +1,99 @@
 <script lang="ts">
-    interface Props {
-        level?: number;
-        text: string;
-    }
-
-    let { level = 1, text }: Props = $props();
-
-    const fontWeight = $derived(level <= 2 ? "700" : "500");
-    const Tag = $derived(`h${level}`);
-
-    const sizeClasses = {
-        1: "text-4xl",
-        2: "text-3xl",
-        3: "text-2xl",
-        4: "text-xl",
-        5: "text-lg",
-        6: "text-base",
+    import type { Snippet } from "svelte";
+    import type { HTMLAttributes } from "svelte/elements";
+    import { cn } from "../util/cn.js";
+    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"> & {
+        level?: HeadingLevel;
+        /**
+         * Visual size, when it should differ from the semantic level — an `h2`
+         * that needs to look like an `h4` keeps the document outline correct
+         * without forcing the wrong tag.
+         */
+        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;
+        class?: string;
+        children?: Snippet;
+    };
+
+    let {
+        level = 1,
+        size,
+        text = "",
+        tone = "headline",
+        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 sizeClass = $derived(
-        sizeClasses[level as keyof typeof sizeClasses] || "text-base",
+    const visualSize = $derived(size ?? level);
+
+    /**
+     * Display sizes tighten as they grow. Untracked 36px type with default
+     * 40px leading is the single clearest "this is stock Tailwind" tell;
+     * negative tracking and a tighter leading is most of what separates
+     * display type from body type set large.
+     */
+    const sizeClasses: Record<HeadingLevel, string> = {
+        1: "text-4xl leading-10 tracking-[-0.02em] font-bold",
+        2: "text-3xl leading-9 tracking-[-0.015em] font-bold",
+        3: "text-2xl leading-8 tracking-[-0.01em] font-semibold",
+        4: "text-xl leading-7 tracking-[-0.005em] font-semibold",
+        5: "text-lg leading-7 font-semibold",
+        6: "text-base leading-6 font-semibold",
+    };
+
+    const headingClasses = $derived(
+        cn(`${toneClasses[tone] ?? toneClasses.headline} ${sizeClasses[visualSize] ?? sizeClasses[6]} ${className}`),
     );
 </script>
 
-<svelte:element
-    this={Tag}
-    class="text-headline font-nunito {sizeClass}"
-    style="font-weight: {fontWeight};"
->
-    {text}
-</svelte:element>
-
-<style>
-    .font-nunito {
-        font-family: "Nunito Sans", ui-sans-serif, system-ui, sans-serif;
-    }
-</style>
+<!--
+  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.
+-->
+{#snippet content()}
+    {#if children}
+        {@render children()}
+    {:else}
+        {text}
+    {/if}
+{/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,7 +1,27 @@
-interface Props {
-    level?: number;
-    text: string;
-}
+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"> & {
+    level?: HeadingLevel;
+    /**
+     * Visual size, when it should differ from the semantic level — an `h2`
+     * that needs to look like an `h4` keeps the document outline correct
+     * without forcing the wrong tag.
+     */
+    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;
+    class?: string;
+    children?: Snippet;
+};
 declare const Heading: import("svelte").Component<Props, {}, "">;
 type Heading = ReturnType<typeof Heading>;
 export default Heading;