@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/feedback/Toaster.svelte

@@ -0,0 +1,78 @@
+<!-- @component
+The notification region, plus the context that lets any descendant push a toast into it (`getToaster().add({ title: 'Saved' })`).
+-->
+<!--
+  Toaster — the notification region, plus the context that lets any descendant
+  push into it (`getToaster().add({ title: 'Saved' })`).
+
+  Hand-rolled rather than on a bits-ui primitive, deliberately: there is no
+  interaction to get right. A toast takes no focus, traps nothing and has no
+  keyboard contract of its own — it is a live region with a queue and a timer,
+  and the queue is a plain rune.
+
+  ARIA contract: ONE `aria-live="polite"` region, named by `regionLabel`, and
+  nothing live inside it. The tempting `role="status"` on each toast is the
+  bug this replaces: a status inside a live region makes assistive technology
+  announce the same text twice, and a region that is only created when the
+  first toast arrives is often not announced at all — so the region is in the
+  document from mount, empty, and only its contents change. Dismiss is a
+  labelled text button, not a bare glyph.
+
+  Timers are held in a map and cleared on destroy: a toast that outlives its
+  page would otherwise write to a component that is gone.
+-->
+<script lang="ts">import { alertTone } from "../ui/tones.js";
+import Button from "../ui/Button.svelte";
+import { toastPosition } from "./sizes.js";
+import { setToaster } from "./toaster.js";
+let { position = "bottom-end", regionLabel = "Notifications", dismissLabel = "Dismiss", durationMs = 6e3, class: className, children } = $props();
+let toasts = $state([]);
+let nextId = 1;
+const timers = new Map();
+const dismiss = (id) => {
+	const timer = timers.get(id);
+	if (timer !== undefined) {
+		clearTimeout(timer);
+		timers.delete(id);
+	}
+	toasts = toasts.filter((toast) => toast.id !== id);
+};
+const api = {
+	add(toast, duration = durationMs) {
+		const id = nextId++;
+		toasts = [...toasts, {
+			...toast,
+			tone: toast.tone ?? "info",
+			id
+		}];
+		if (duration > 0) timers.set(id, setTimeout(() => dismiss(id), duration));
+		return id;
+	},
+	dismiss
+};
+setToaster(api);
+$effect(() => () => {
+	for (const timer of timers.values()) clearTimeout(timer);
+	timers.clear();
+});
+</script>
+
+{@render children()}
+
+<div
+  class={['toast z-50', toastPosition[position], className]}
+  aria-live="polite"
+  aria-label={regionLabel}
+>
+  {#each toasts as toast (toast.id)}
+    <div class={['alert items-start shadow-lg', alertTone[toast.tone]]}>
+      <div>
+        <p class="font-semibold">{toast.title}</p>
+        {#if toast.description !== undefined}
+          <p class="text-sm">{toast.description}</p>
+        {/if}
+      </div>
+      <Button variant="ghost" size="sm" onclick={() => dismiss(toast.id)}>{dismissLabel}</Button>
+    </div>
+  {/each}
+</div>

package/dist/feedback/Toaster.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { Snippet } from 'svelte';
+import { type ToastPosition } from './sizes.ts';
+interface Props {
+    /**
+     * Which corner the stack grows from.
+     * @defaultValue `'bottom-end'`
+     */
+    position?: ToastPosition | undefined;
+    /**
+     * Accessible name of the live region.
+     * @defaultValue `'Notifications'`
+     */
+    regionLabel?: string | undefined;
+    /**
+     * Accessible name of every toast's dismiss button.
+     * @defaultValue `'Dismiss'`
+     */
+    dismissLabel?: string | undefined;
+    /**
+     * How long a toast lives when `add` is given no duration. `0` = sticky.
+     * @defaultValue `6_000`
+     */
+    durationMs?: number | undefined;
+    /** Extra classes on the region. */
+    class?: string | undefined;
+    /** The application. Rendered above the region. */
+    children: Snippet<[]>;
+}
+/** The notification region, plus the context that lets any descendant push a toast into it (`getToaster().add({ title: 'Saved' })`). */
+declare const Toaster: import("svelte").Component<Props, {}, "">;
+type Toaster = ReturnType<typeof Toaster>;
+export default Toaster;

package/dist/feedback/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * feedback — dialogs, toasts, progress and the chrome around a pending read.
+ *
+ * What these have in common is that they speak to the reader about something
+ * that just happened, or is happening now: a confirmation to give, a result
+ * to notice, a number to compare, a wait to explain. That makes the live
+ * regions and the announcement order the contract — see each component's
+ * header comment — rather than the markup.
+ *
+ * As in `ui/`, every optional prop is declared `T | undefined`: the workspace
+ * compiles with `exactOptionalPropertyTypes`, under which `prop?: T` rejects
+ * an explicitly passed `undefined`, and these components are composed by
+ * callers forwarding their own optional props straight through.
+ *
+ * @module
+ */
+export { default as ConfirmDialog } from './ConfirmDialog.svelte';
+export { default as Dialog } from './Dialog.svelte';
+export { default as LoadingBoundary } from './LoadingBoundary.svelte';
+export { default as ProgressBar } from './ProgressBar.svelte';
+export { default as SegmentBar } from './SegmentBar.svelte';
+export { default as StatTile } from './StatTile.svelte';
+export { default as Stats } from './Stats.svelte';
+export { default as Timeline } from './Timeline.svelte';
+export { default as Toaster } from './Toaster.svelte';
+export type { ConfirmForm } from './ConfirmDialog.svelte';
+export type { BarSegment } from './SegmentBar.svelte';
+export type { StatDelta } from './StatTile.svelte';
+export type { TimelineDate, TimelineEntry } from './Timeline.svelte';
+export * from './sizes.ts';
+export * from './toaster.ts';

package/dist/feedback/index.js

@@ -0,0 +1,27 @@
+/**
+ * feedback — dialogs, toasts, progress and the chrome around a pending read.
+ *
+ * What these have in common is that they speak to the reader about something
+ * that just happened, or is happening now: a confirmation to give, a result
+ * to notice, a number to compare, a wait to explain. That makes the live
+ * regions and the announcement order the contract — see each component's
+ * header comment — rather than the markup.
+ *
+ * As in `ui/`, every optional prop is declared `T | undefined`: the workspace
+ * compiles with `exactOptionalPropertyTypes`, under which `prop?: T` rejects
+ * an explicitly passed `undefined`, and these components are composed by
+ * callers forwarding their own optional props straight through.
+ *
+ * @module
+ */
+export { default as ConfirmDialog } from './ConfirmDialog.svelte';
+export { default as Dialog } from './Dialog.svelte';
+export { default as LoadingBoundary } from './LoadingBoundary.svelte';
+export { default as ProgressBar } from './ProgressBar.svelte';
+export { default as SegmentBar } from './SegmentBar.svelte';
+export { default as StatTile } from './StatTile.svelte';
+export { default as Stats } from './Stats.svelte';
+export { default as Timeline } from './Timeline.svelte';
+export { default as Toaster } from './Toaster.svelte';
+export * from "./sizes.js";
+export * from "./toaster.js";

package/dist/feedback/sizes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The literal class tables this family looks its variants up in.
+ *
+ * Tailwind only generates classes it can see verbatim in source, so a
+ * template string (`max-w-${size}`, `toast-${position}`) emits nothing at
+ * build time. Every step is spelled out once here as a `Record<K, string>`
+ * and looked up — the same discipline as `ui/tones.ts`, kept local because
+ * these steps are this family's, not the whole library's.
+ *
+ * @module
+ */
+/** Width steps of a `Dialog`'s `modal-box`. */
+export type DialogSize = 'sm' | 'md' | 'lg' | 'xl';
+/** Literal `max-w-*` class per `DialogSize`; a lookup table so Tailwind's scanner sees every class. */
+export declare const dialogSize: Record<DialogSize, string>;
+/** Where a `Toaster` stacks its notifications. */
+export type ToastPosition = 'top-start' | 'top-center' | 'top-end' | 'bottom-start' | 'bottom-center' | 'bottom-end';
+/** Literal daisyUI class per `ToastPosition` for `Toaster`; a lookup table so Tailwind's scanner sees every class. */
+export declare const toastPosition: Record<ToastPosition, string>;
+/** Height steps of a `SegmentBar`. */
+export type BarSize = 'sm' | 'md' | 'lg';
+/** Literal height class per `BarSize`; a lookup table so Tailwind's scanner sees every class. */
+export declare const barSize: Record<BarSize, string>;
+/** How a `Stats` row lays its tiles out. */
+export type StatsOrientation = 'horizontal' | 'vertical' | 'responsive';
+/** Literal daisyUI class per `StatsOrientation` for `Stats`; a lookup table so Tailwind's scanner sees every class. */
+export declare const statsOrientation: Record<StatsOrientation, string>;

package/dist/feedback/sizes.js

@@ -0,0 +1,41 @@
+/**
+ * The literal class tables this family looks its variants up in.
+ *
+ * Tailwind only generates classes it can see verbatim in source, so a
+ * template string (`max-w-${size}`, `toast-${position}`) emits nothing at
+ * build time. Every step is spelled out once here as a `Record<K, string>`
+ * and looked up — the same discipline as `ui/tones.ts`, kept local because
+ * these steps are this family's, not the whole library's.
+ *
+ * @module
+ */
+/** Literal `max-w-*` class per `DialogSize`; a lookup table so Tailwind's scanner sees every class. */
+export const dialogSize = {
+    sm: 'max-w-sm',
+    md: 'max-w-lg',
+    lg: 'max-w-2xl',
+    xl: 'max-w-4xl',
+};
+/** Literal daisyUI class per `ToastPosition` for `Toaster`; a lookup table so Tailwind's scanner sees every class. */
+export const toastPosition = {
+    'top-start': 'toast-top toast-start',
+    'top-center': 'toast-top toast-center',
+    'top-end': 'toast-top toast-end',
+    'bottom-start': 'toast-bottom toast-start',
+    'bottom-center': 'toast-bottom toast-center',
+    'bottom-end': 'toast-bottom toast-end',
+};
+/** Literal height class per `BarSize`; a lookup table so Tailwind's scanner sees every class. */
+export const barSize = {
+    sm: 'h-2',
+    md: 'h-4',
+    lg: 'h-6',
+};
+/** Literal daisyUI class per `StatsOrientation` for `Stats`; a lookup table so Tailwind's scanner sees every class. */
+export const statsOrientation = {
+    horizontal: 'stats-horizontal',
+    vertical: 'stats-vertical',
+    // Stacked on a phone, in a row from `sm` up — the shape every app's
+    // dashboard reached for by hand.
+    responsive: 'stats-vertical sm:stats-horizontal',
+};

package/dist/feedback/toaster.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The toaster seam: what a toast is, and how anything below a `<Toaster>`
+ * reaches the one region on the page.
+ *
+ * Kept out of `Toaster.svelte` so a module that only wants to *push* a toast
+ * — a store, a form helper, another component — imports a `.ts` file rather
+ * than pulling a component (and its icons) onto its own path.
+ *
+ * @module
+ */
+import type { StatusTone } from '../ui/tones.ts';
+/** The colour a toast is drawn in; the same four states an `Alert` has. */
+export type ToastTone = StatusTone;
+/** One notification as the `Toaster` holds it, after it has been given an id. */
+export interface Toast {
+    /** Assigned by the toaster; unique for the life of the page. */
+    readonly id: number;
+    /** The line that carries the message. */
+    readonly title: string;
+    /** Optional second line. */
+    readonly description?: string | undefined;
+    readonly tone: ToastTone;
+}
+/** What a toast looks like before the toaster has given it an id. */
+export type NewToast = Omit<Toast, 'id' | 'tone'> & {
+    readonly tone?: ToastTone | undefined;
+};
+/** What `getToaster()` returns: push a toast or dismiss one. */
+export interface ToasterApi {
+    /**
+     * Push a toast and return its id. It dismisses itself after `durationMs`
+     * (the `<Toaster>`'s own default when omitted); `0` makes it sticky, for a
+     * message the reader must act on.
+     */
+    add(toast: NewToast, durationMs?: number): number;
+    /** Remove a toast early — the dismiss button, or the app itself. */
+    dismiss(id: number): void;
+}
+/** Publish the region's API to its descendants. Called by `Toaster`. */
+export declare function setToaster(api: ToasterApi): void;
+/**
+ * The nearest `<Toaster>`'s API.
+ *
+ * Throws when there is no provider: a silently dropped notification is worse
+ * than a loud failure in development, and every call site is inside the app's
+ * own layout where the provider is mounted once.
+ */
+export declare function getToaster(): ToasterApi;

package/dist/feedback/toaster.js

@@ -0,0 +1,29 @@
+/**
+ * The toaster seam: what a toast is, and how anything below a `<Toaster>`
+ * reaches the one region on the page.
+ *
+ * Kept out of `Toaster.svelte` so a module that only wants to *push* a toast
+ * — a store, a form helper, another component — imports a `.ts` file rather
+ * than pulling a component (and its icons) onto its own path.
+ *
+ * @module
+ */
+import { getContext, setContext } from 'svelte';
+const TOASTER_KEY = Symbol('@thomasfosterau/components:toaster');
+/** Publish the region's API to its descendants. Called by `Toaster`. */
+export function setToaster(api) {
+    setContext(TOASTER_KEY, api);
+}
+/**
+ * The nearest `<Toaster>`'s API.
+ *
+ * Throws when there is no provider: a silently dropped notification is worse
+ * than a loud failure in development, and every call site is inside the app's
+ * own layout where the provider is mounted once.
+ */
+export function getToaster() {
+    const api = getContext(TOASTER_KEY);
+    if (api === undefined)
+        throw new Error('getToaster() was called outside a <Toaster>');
+    return api;
+}

package/dist/fields/Checkbox.svelte

@@ -0,0 +1,33 @@
+<!-- @component
+A daisyUI `checkbox` with its label in the same `<label>`, so the whole row is the hit target.
+-->
+<!--
+  Checkbox — daisyUI `checkbox` with its label in the same `<label>`, so the
+  whole row is the hit target and the input is named without an `id`/`for`
+  pair at all.
+
+  Unlike the text fields this one carries its OWN label: a checkbox's label
+  sits beside it rather than above it, and a `FormField` wrapped around a
+  single checkbox would put the question in two places. Use `CheckboxGroup`
+  (or `Fieldset`) when several checkboxes answer one question.
+
+  ARIA contract: a native `<input type="checkbox">` wrapped in its `<label>`,
+  so `checked` is the state assistive technology reads and Space toggles it
+  with no script. `describedBy` and `invalid` tie it to an enclosing group's
+  hint and errors when there is one.
+-->
+<script lang="ts">import { checkboxSize } from "./field-types.js";
+let { label, checked = $bindable(false), size = "md", invalid = false, describedBy = "", class: className, ...rest } = $props();
+</script>
+
+<label class={['label cursor-pointer justify-start gap-3', className]}>
+  <input
+    {...rest}
+    type="checkbox"
+    bind:checked
+    aria-invalid={invalid ? 'true' : undefined}
+    aria-describedby={describedBy === '' ? undefined : describedBy}
+    class={['checkbox', checkboxSize[size], invalid && 'checkbox-error']}
+  />
+  <span>{label}</span>
+</label>

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

@@ -0,0 +1,24 @@
+import type { HTMLInputAttributes } from 'svelte/elements';
+import { type FieldSize } from './field-types.ts';
+interface Props extends Omit<HTMLInputAttributes, 'type' | 'checked' | 'size'> {
+    /** Text beside the box; becomes the input's accessible name. */
+    label: string;
+    /** Whether the box is ticked. Bindable. */
+    checked?: boolean | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: FieldSize | undefined;
+    /** `FieldControl`: the field is in error — sets `aria-invalid` and the error style. */
+    invalid?: boolean | undefined;
+    /**
+     * `FieldControl`: space-separated ids for `aria-describedby`.
+     * @defaultValue `''`
+     */
+    describedBy?: string | undefined;
+}
+/** A daisyUI `checkbox` with its label in the same `<label>`, so the whole row is the hit target. */
+declare const Checkbox: import("svelte").Component<Props, {}, "checked">;
+type Checkbox = ReturnType<typeof Checkbox>;
+export default Checkbox;

package/dist/fields/CheckboxGroup.svelte

@@ -0,0 +1,41 @@
+<!-- @component
+Several checkboxes answering one question, inside one `Fieldset`.
+-->
+<!--
+  CheckboxGroup — several checkboxes answering one question, inside one
+  `Fieldset`.
+
+  ARIA contract: the `<legend>` names the group and is repeated as focus moves
+  between the boxes; each box is named by its own inline label; the group's
+  hint and errors are on the `<fieldset>`, so they are read once for the group
+  rather than once per box.
+
+  `values` is the list of TICKED values, bindable. It is a plain array rather
+  than a `Set` because that is what a form's decoded body and a JSON payload
+  both look like, and because Svelte's deep reactivity tracks it.
+-->
+<script lang="ts">import Checkbox from "./Checkbox.svelte";
+import Fieldset from "./Fieldset.svelte";
+import { toFieldOptions } from "./field-types.js";
+let { legend, options, values = $bindable([]), name, hint, errors = [], required = false, requiredLabel = "(required)", disabled = false, size = "md", ...rest } = $props();
+const entries = $derived(toFieldOptions(options));
+const invalid = $derived(errors.length > 0);
+const toggle = (value, ticked) => {
+	values = ticked ? [...values, value] : values.filter((entry) => entry !== value);
+};
+</script>
+
+<Fieldset {...rest} {legend} {hint} {errors} {required} {requiredLabel}>
+  {#each entries as option (option.value)}
+    <Checkbox
+      label={option.label}
+      {name}
+      {size}
+      {invalid}
+      value={option.value}
+      disabled={disabled || option.disabled === true}
+      checked={values.includes(option.value)}
+      onchange={(event) => toggle(option.value, event.currentTarget.checked)}
+    />
+  {/each}
+</Fieldset>

package/dist/fields/CheckboxGroup.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { HTMLAttributes } from 'svelte/elements';
+import { type FieldOptionInput, type FieldSize } from './field-types.ts';
+interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, 'children'> {
+    /** The question the boxes answer. */
+    legend: string;
+    /** Full options, or bare strings when value and label are the same. */
+    options: readonly FieldOptionInput[];
+    /**
+     * The ticked values.
+     * @defaultValue `[]`
+     */
+    values?: string[] | undefined;
+    /** Posted field name; every box shares it, as a multi-value field. */
+    name?: string | undefined;
+    /** Guidance rendered under the legend. */
+    hint?: string | undefined;
+    /**
+     * Validation messages; any at all marks the group invalid.
+     * @defaultValue `[]`
+     */
+    errors?: readonly string[] | undefined;
+    /** Marks the group required and reads `requiredLabel` after the legend. */
+    required?: boolean | undefined;
+    /**
+     * Read out after the legend when `required`.
+     * @defaultValue `'(required)'`
+     */
+    requiredLabel?: string | undefined;
+    /** Disables every option. */
+    disabled?: boolean | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: FieldSize | undefined;
+}
+/** Several checkboxes answering one question, inside one `Fieldset`. */
+declare const CheckboxGroup: import("svelte").Component<Props, {}, "values">;
+type CheckboxGroup = ReturnType<typeof CheckboxGroup>;
+export default CheckboxGroup;