zabi-components 8.1.0 → 9.0.0

package/dist/atoms/Card.svelte

@@ -1,18 +1,71 @@
 <script lang="ts">
     import type { Snippet } from "svelte";
-    import type { HTMLAttributes } from "svelte/elements";
-    import type { CardVariant, SizeVariant } from "../types/variants.js";
+    import type { HTMLAnchorAttributes, HTMLAttributes } from "svelte/elements";
+    import type { CardVariant, SizeVariant, SurfaceTone } from "../types/variants.js";
 
     import { cn } from "../util/cn.js";
+    import { toneSurface } from "../util/tone-surface.js";
     type Props = Omit<HTMLAttributes<HTMLDivElement>, "class"> & {
         onclick?: (event: MouseEvent) => void | Promise<void>;
         size?: SizeVariant;
+        /** The look of a `neutral` card. With a `tone` or a `fill` the fill is the edge: no border, and a shadow only for `elevated`. */
         variant?: CardVariant;
+        /**
+         * What the card is filled with: `neutral` (the default, the card surface),
+         * `tint` (the brand tint), `brand` or `accent`. On `brand` and `accent`
+         * the text, links, controls and focus rings inside take the fill's label
+         * colour; a Card, field or Alert inside is a surface again.
+         */
+        tone?: SurfaceTone;
+        /**
+         * A fill the app chooses, any CSS colour (`var(--group-colour)`). Wins
+         * over `tone`. Set `onFill`, the label colour on it. The library cannot
+         * check that pair's contrast: the app must hold it to 4.5:1.
+         */
+        fill?: string;
+        /** The label colour on `fill`, any CSS colour. */
+        onFill?: string;
+        /**
+         * With `href` the card itself is an `<a>`: the whole card is the link,
+         * and it works without scripts. A link card must not contain other
+         * interactive elements (a link or a button in a link is invalid and
+         * unreachable); a card with actions inside takes `onclick` or none.
+         * With `onclick` too, it is a link and `onclick` runs on activation.
+         */
+        href?: string;
+        /** With `href`: where the link opens. */
+        target?: HTMLAnchorAttributes["target"];
+        /** With `href`: the link's relationship, such as `noopener`. */
+        rel?: string;
+        /**
+         * The card itself is a `<button>`: the whole card is the control, and
+         * `submit` posts the form around it without scripts. With `href`
+         * the card is a link and this is ignored. Like a link card it must not
+         * contain other interactive elements. `onclick`
+         * runs on a press, as on any button.
+         */
+        type?: "submit" | "button" | "reset";
+        /** With `type`: the name the button submits under. */
+        name?: string;
+        /** With `type`: what the button submits. */
+        value?: string;
+        /** With `type`: the id of the form it belongs to, when it is not inside one. */
+        form?: string;
+        /** With `type`: the card cannot be pressed, is dimmed, and is skipped by the keyboard. */
+        disabled?: boolean;
+        /**
+         * With `type`: the card's action is on its way, as `Button`'s and
+         * `Chip`'s `loading`. `aria-busy` and `aria-disabled` (not `disabled`),
+         * the press swallowed (it submits nothing and does not reach
+         * `onclick`), the pressed look held, the size and the Tab stop kept.
+         * No spinner. Ignored by a link card and a plain card.
+         */
+        loading?: boolean;
         fullWidth?: boolean;
         class?: string;
         /** @deprecated use `class` — kept so 7.x call sites keep working. */
         className?: string;
-        /** Required when `onclick` is set (no visible label). */
+        /** Names the card when it is interactive and its content does not (the content names a link well enough in most cases). */
         ariaLabel?: string;
         children?: Snippet;
     };
@@ -21,10 +74,23 @@
         onclick,
         size = "md",
         variant = "default",
+        tone = "neutral",
+        fill,
+        onFill,
+        href,
+        target,
+        rel,
+        type: buttonType,
+        name,
+        value,
+        form,
+        disabled = false,
+        loading = false,
         fullWidth = true,
         class: classProp = "",
         className = "",
         ariaLabel,
+        style: styleProp,
         children,
         ...restProps
     }: Props = $props();
@@ -35,36 +101,79 @@
         size === "sm" ? "p-4" : size === "lg" ? "p-8" : "p-6",
     );
 
+    const surface = $derived(toneSurface({ tone, fill, onFill }));
+
+    const isLink = $derived(href !== undefined && href !== null);
+    const isButton = $derived(!isLink && buttonType !== undefined);
+
     const variantClasses = $derived(
-        variant === "elevated"
-            ? "bg-card-elevated shadow-lg"
-            : variant === "outlined"
-              ? "bg-card border border-border shadow-none"
+        surface.filled
+            ? // The fill is the edge: no border, flat unless the variant lifts it.
+              `${surface.classes} ${variant === "elevated" ? "shadow-lg" : "shadow-none"}`
+            : variant === "elevated"
+              ? "bg-card-elevated shadow-lg"
               : variant === "flat"
-                ? "bg-card shadow-none border-none"
-                : "bg-card shadow-sm",
+                ? "bg-card-flat shadow-none border-none"
+                : "bg-card border border-border shadow-none",
     );
 
+    /**
+     * Hover and pressed on a fill the card does not know: a veil of the card's
+     * own text colour (`bg-current`), so it reads on a tint, the brand, the
+     * accent and any colour an app passes. The card is `relative` for it.
+     */
+    const STATE_LAYER =
+        "relative after:absolute after:inset-0 after:rounded-[inherit] after:bg-current after:opacity-0 after:pointer-events-none after:transition-opacity after:duration-(--duration-base) motion-reduce:after:transition-none hover:after:opacity-8 active:after:opacity-12";
+
+    /** Loading without `disabled`: unavailable, and still where focus is (see Button). */
+    const isBusy = $derived(isButton && loading && !disabled);
+
+    const interactive = $derived(!!onclick || isLink || isButton);
+
     const interactiveClasses = $derived.by(() => {
-        if (!onclick) return "";
+        if (!interactive) return "";
+        if (isBusy) {
+            // The pressed look, held: no hover or pressed rule is left to change it.
+            // Forced colours drop the fills the held look is made of: GrayText text and a dashed inset edge say it there.
+            const held =
+                "cursor-progress focus-ring forced-colors:text-[color:GrayText] forced-colors:outline-1 forced-colors:outline-dashed forced-colors:-outline-offset-1 forced-colors:outline-[color:GrayText]";
+            if (surface.filled) return `${held} relative after:absolute after:inset-0 after:rounded-[inherit] after:bg-current after:opacity-12 after:pointer-events-none`;
+            switch (variant) {
+                case "elevated":
+                    return `${held} bg-card-active`;
+                case "flat":
+                    return `${held} bg-card-flat-active`;
+                default:
+                    return `${held} border-border-medium bg-card-active`;
+            }
+        }
         const shared = "cursor-pointer focus-ring";
+        if (surface.filled) return `${shared} ${STATE_LAYER}`;
         switch (variant) {
             case "elevated":
                 return `${shared} hover:bg-card-hover active:bg-card-active`;
-            case "outlined":
-                return `${shared} hover:border-border-medium hover:bg-card-hover active:bg-card-active`;
             case "flat":
-                return `${shared} hover:bg-card-hover active:bg-card-active`;
+                return `${shared} hover:bg-card-flat-hover active:bg-card-flat-active`;
             default:
-                return `${shared} hover:shadow-lg hover:bg-card-hover active:bg-card-active`;
+                return `${shared} hover:border-border-medium hover:bg-card-hover active:bg-card-active`;
         }
     });
 
+    /** A link card keeps the body colour (its whole content is not link-coloured); a scoped fill sets its own. */
+    const linkClasses = $derived(
+        isLink
+            ? `block no-underline min-h-11 ${surface.scoped ? "" : "text-body"}`
+            : isButton
+              ? `block text-start min-h-11 ${surface.scoped ? "" : "text-body"} ${disabled ? "cursor-not-allowed opacity-50 pointer-events-none" : ""}`
+              : "",
+    );
+
     const cardClasses = $derived(
         cn(
             "rounded-container transition-all duration-150",
             variantClasses,
             interactiveClasses,
+            linkClasses,
             fullWidth ? "w-full" : "",
             sizeClass,
             classProp,
@@ -72,6 +181,20 @@
         ),
     );
 
+    const cardStyle = $derived(
+        [surface.style, typeof styleProp === "string" ? styleProp : undefined].filter(Boolean).join("; ") || undefined,
+    );
+
+    /** A busy card is not `disabled`, so the press reaches it: it ends here, and submits nothing. */
+    function handleButtonClick(event: MouseEvent) {
+        if (isBusy) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        onclick?.(event);
+    }
+
     function handleKeydown(event: KeyboardEvent) {
         if (onclick && (event.key === "Enter" || event.key === " ")) {
             event.preventDefault();
@@ -82,14 +205,47 @@
     const cardRole = $derived(onclick ? "button" : undefined);
 </script>
 
-<div
-    class={cardClasses}
-    {onclick}
-    role={cardRole}
-    {...onclick ? { tabindex: 0 } : {}}
-    aria-label={ariaLabel}
-    onkeydown={onclick ? handleKeydown : undefined}
-    {...restProps}
->
-    {@render children?.()}
-</div>
+{#if isLink}
+    <a
+        class={cardClasses}
+        style={cardStyle}
+        {href}
+        {target}
+        {rel}
+        {onclick}
+        aria-label={ariaLabel}
+        {...restProps as HTMLAnchorAttributes}
+    >
+        {@render children?.()}
+    </a>
+{:else if isButton}
+    <button
+        type={buttonType}
+        {name}
+        {value}
+        {form}
+        {disabled}
+        class={cardClasses}
+        style={cardStyle}
+        aria-label={ariaLabel}
+        aria-busy={isBusy ? "true" : undefined}
+        aria-disabled={isBusy ? "true" : undefined}
+        {...restProps as HTMLAttributes<HTMLButtonElement>}
+        onclick={handleButtonClick}
+    >
+        {@render children?.()}
+    </button>
+{:else}
+    <div
+        class={cardClasses}
+        style={cardStyle}
+        {onclick}
+        role={cardRole}
+        {...onclick ? { tabindex: 0 } : {}}
+        aria-label={ariaLabel}
+        onkeydown={onclick ? handleKeydown : undefined}
+        {...restProps}
+    >
+        {@render children?.()}
+    </div>
+{/if}

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

@@ -1,15 +1,67 @@
 import type { Snippet } from "svelte";
-import type { HTMLAttributes } from "svelte/elements";
-import type { CardVariant, SizeVariant } from "../types/variants.js";
+import type { HTMLAnchorAttributes, HTMLAttributes } from "svelte/elements";
+import type { CardVariant, SizeVariant, SurfaceTone } from "../types/variants.js";
 type Props = Omit<HTMLAttributes<HTMLDivElement>, "class"> & {
     onclick?: (event: MouseEvent) => void | Promise<void>;
     size?: SizeVariant;
+    /** The look of a `neutral` card. With a `tone` or a `fill` the fill is the edge: no border, and a shadow only for `elevated`. */
     variant?: CardVariant;
+    /**
+     * What the card is filled with: `neutral` (the default, the card surface),
+     * `tint` (the brand tint), `brand` or `accent`. On `brand` and `accent`
+     * the text, links, controls and focus rings inside take the fill's label
+     * colour; a Card, field or Alert inside is a surface again.
+     */
+    tone?: SurfaceTone;
+    /**
+     * A fill the app chooses, any CSS colour (`var(--group-colour)`). Wins
+     * over `tone`. Set `onFill`, the label colour on it. The library cannot
+     * check that pair's contrast: the app must hold it to 4.5:1.
+     */
+    fill?: string;
+    /** The label colour on `fill`, any CSS colour. */
+    onFill?: string;
+    /**
+     * With `href` the card itself is an `<a>`: the whole card is the link,
+     * and it works without scripts. A link card must not contain other
+     * interactive elements (a link or a button in a link is invalid and
+     * unreachable); a card with actions inside takes `onclick` or none.
+     * With `onclick` too, it is a link and `onclick` runs on activation.
+     */
+    href?: string;
+    /** With `href`: where the link opens. */
+    target?: HTMLAnchorAttributes["target"];
+    /** With `href`: the link's relationship, such as `noopener`. */
+    rel?: string;
+    /**
+     * The card itself is a `<button>`: the whole card is the control, and
+     * `submit` posts the form around it without scripts. With `href`
+     * the card is a link and this is ignored. Like a link card it must not
+     * contain other interactive elements. `onclick`
+     * runs on a press, as on any button.
+     */
+    type?: "submit" | "button" | "reset";
+    /** With `type`: the name the button submits under. */
+    name?: string;
+    /** With `type`: what the button submits. */
+    value?: string;
+    /** With `type`: the id of the form it belongs to, when it is not inside one. */
+    form?: string;
+    /** With `type`: the card cannot be pressed, is dimmed, and is skipped by the keyboard. */
+    disabled?: boolean;
+    /**
+     * With `type`: the card's action is on its way, as `Button`'s and
+     * `Chip`'s `loading`. `aria-busy` and `aria-disabled` (not `disabled`),
+     * the press swallowed (it submits nothing and does not reach
+     * `onclick`), the pressed look held, the size and the Tab stop kept.
+     * No spinner. Ignored by a link card and a plain card.
+     */
+    loading?: boolean;
     fullWidth?: boolean;
     class?: string;
     /** @deprecated use `class` — kept so 7.x call sites keep working. */
     className?: string;
-    /** Required when `onclick` is set (no visible label). */
+    /** Names the card when it is interactive and its content does not (the content names a link well enough in most cases). */
     ariaLabel?: string;
     children?: Snippet;
 };

package/dist/atoms/Checkbox.svelte

@@ -1,5 +1,7 @@
 <script lang="ts">
+    import type { Snippet } from "svelte";
     import type { HTMLInputAttributes } from "svelte/elements";
+    import type { SemanticVariant } from "../types/variants.js";
     import SelectionControl from "./SelectionControl.svelte";
     import type { SelectionControlMarkProps } from "./SelectionControl.svelte";
 
@@ -20,6 +22,31 @@
         checked?: boolean;
         onChange?: (event: Event) => void;
         onchange?: (event: Event) => void;
+        /**
+         * Drawn inside the one label, between the box and the label text, as
+         * decoration for the name `label` already gives. A leading image
+         * should have an empty alt: the label names the row.
+         */
+        leading?: Snippet;
+        /**
+         * A line under the label, tied to the box with `aria-describedby`.
+         * It is inside the label, so a tap on it ticks the box; it does not
+         * join the name.
+         */
+        description?: string;
+        /**
+         * Where the box sits in the row. `end` puts it after the leading, the
+         * label and the description, at the far edge; the row is still one
+         * label and fills the width it is given.
+         */
+        controlPosition?: "start" | "end";
+        variant?: SemanticVariant;
+        /** Status text under the control. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+        message?: string;
+        /** Help text under the control, read out with it. */
+        hint?: string;
+        /** An error under the control. It marks the input invalid and is announced; it wins over `variant` and `message`. */
+        error?: string;
     };
 
     let {
@@ -34,6 +61,9 @@
         checked = $bindable<Exclude<Props["checked"], undefined>>(),
         onChange,
         onchange,
+        leading,
+        description,
+        controlPosition = "start",
         ...restProps
     }: Props = $props();
 
@@ -95,6 +125,9 @@
     {onChange}
     {onchange}
     {mark}
+    {leading}
+    {description}
+    {controlPosition}
     class={className}
     {...restProps}
 />

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

@@ -1,4 +1,6 @@
+import type { Snippet } from "svelte";
 import type { HTMLInputAttributes } from "svelte/elements";
+import type { SemanticVariant } from "../types/variants.js";
 /** Other attributes (`required`, `data-*`, `aria-*`, ...) land on the `<input>`. */
 type Props = Omit<HTMLInputAttributes, "class" | "id" | "name" | "value" | "disabled" | "checked" | "type" | "onchange"> & {
     /** Extra classes for the host element. */
@@ -13,6 +15,31 @@ type Props = Omit<HTMLInputAttributes, "class" | "id" | "name" | "value" | "disa
     checked?: boolean;
     onChange?: (event: Event) => void;
     onchange?: (event: Event) => void;
+    /**
+     * Drawn inside the one label, between the box and the label text, as
+     * decoration for the name `label` already gives. A leading image
+     * should have an empty alt: the label names the row.
+     */
+    leading?: Snippet;
+    /**
+     * A line under the label, tied to the box with `aria-describedby`.
+     * It is inside the label, so a tap on it ticks the box; it does not
+     * join the name.
+     */
+    description?: string;
+    /**
+     * Where the box sits in the row. `end` puts it after the leading, the
+     * label and the description, at the far edge; the row is still one
+     * label and fills the width it is given.
+     */
+    controlPosition?: "start" | "end";
+    variant?: SemanticVariant;
+    /** Status text under the control. Shown with a `success`, `warning` or `error` variant; for neutral help, use `hint`. */
+    message?: string;
+    /** Help text under the control, read out with it. */
+    hint?: string;
+    /** An error under the control. It marks the input invalid and is announced; it wins over `variant` and `message`. */
+    error?: string;
 };
 declare const Checkbox: import("svelte").Component<Props, {}, "checked">;
 type Checkbox = ReturnType<typeof Checkbox>;