@thomasfosterau/components 0.0.0-stage → 0.1.0

package/dist/tips/tip-store.svelte.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The tip store: which tips exist, which have been seen, and whether one may
+ * show right now.
+ *
+ * This is a plain object with `$state` inside it, so a tip re-renders when
+ * its state changes rather than when a promise resolves. Rules are
+ * synchronous for the same reason a network round-trip would show a tip a
+ * beat after the page did, while the reader is already doing something else:
+ * await first, then declare the tip.
+ *
+ * Storage is optional and every access is guarded: a private window can have
+ * `localStorage` present and throwing, and a tip system that breaks the page
+ * it is meant to explain is worse than one that forgets.
+ *
+ * @module
+ */
+import type { TipConfig, TipState } from './types.ts';
+/**
+ * The subset of `Storage` this needs, so a test can pass a plain object.
+ *
+ * The signatures are the DOM `Storage` interface's own, `null` included: this
+ * type exists so `globalThis.localStorage` satisfies it structurally.
+ */
+export interface TipStorage {
+    getItem: (key: string) => string | null;
+    setItem: (key: string, value: string) => void;
+    removeItem: (key: string) => void;
+}
+/** What `createTipStore` returns: registers tips, decides whether each may show, and records what the reader did with it. */
+export interface TipStore {
+    /** Declare a tip. Re-registering the same id replaces its configuration. */
+    register: (config: TipConfig) => void;
+    /** Whether this tip may show right now. */
+    shouldDisplay: (id: string) => boolean;
+    /** What is remembered about this tip. */
+    getState: (id: string) => TipState;
+    /** Record that it has just been shown. */
+    markShown: (id: string) => void;
+    /** The reader closed it: never show it again. */
+    dismiss: (id: string) => void;
+    /** The reader took its action: never show it again. */
+    complete: (id: string) => void;
+    /** Forget every tip's state — the "show me the tour again" button. */
+    resetAll: () => void;
+}
+/**
+ * Storage that forgets when the page does.
+ *
+ * The fallback for a browser that refuses persistence, and the right storage
+ * for a test or a Storybook story — a tip dismissed while reviewing one story
+ * must not be invisible in the next reviewer's session.
+ */
+export declare const memoryTipStorage: () => TipStorage;
+/**
+ * `globalThis.localStorage` where it exists and is usable, and
+ * {@link memoryTipStorage} where it does not — the server, and a browser that
+ * refuses storage.
+ */
+export declare const browserTipStorage: () => TipStorage;
+/** Options for {@link createTipStore}. */
+export interface TipStoreOptions {
+    /** Defaults to {@link browserTipStorage}. */
+    readonly storage?: TipStorage | undefined;
+    /** The storage key prefix each tip's entry is written under. */
+    readonly prefix?: string | undefined;
+}
+/**
+ * Build a tip store over the given storage.
+ *
+ * Call once, high in the tree, and hand it to the tips (or put it in a context
+ * of the app's own). The in-memory state is what drives re-rendering; storage
+ * is where it survives a reload.
+ */
+export declare const createTipStore: (options?: TipStoreOptions) => TipStore;

package/dist/tips/tip-store.svelte.js

@@ -0,0 +1,158 @@
+/**
+ * The tip store: which tips exist, which have been seen, and whether one may
+ * show right now.
+ *
+ * This is a plain object with `$state` inside it, so a tip re-renders when
+ * its state changes rather than when a promise resolves. Rules are
+ * synchronous for the same reason a network round-trip would show a tip a
+ * beat after the page did, while the reader is already doing something else:
+ * await first, then declare the tip.
+ *
+ * Storage is optional and every access is guarded: a private window can have
+ * `localStorage` present and throwing, and a tip system that breaks the page
+ * it is meant to explain is worse than one that forgets.
+ *
+ * @module
+ */
+const DEFAULT_PREFIX = 'tips:';
+/** Milliseconds a frequency has to elapse before a tip may reappear. */
+const INTERVALS = {
+    hourly: 60 * 60 * 1000,
+    daily: 24 * 60 * 60 * 1000,
+    weekly: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * Storage that forgets when the page does.
+ *
+ * The fallback for a browser that refuses persistence, and the right storage
+ * for a test or a Storybook story — a tip dismissed while reviewing one story
+ * must not be invisible in the next reviewer's session.
+ */
+export const memoryTipStorage = () => {
+    const memory = new Map();
+    return {
+        getItem: (key) => memory.get(key) ?? null,
+        setItem: (key, value) => {
+            memory.set(key, value);
+        },
+        removeItem: (key) => {
+            memory.delete(key);
+        },
+    };
+};
+/**
+ * `globalThis.localStorage` where it exists and is usable, and
+ * {@link memoryTipStorage} where it does not — the server, and a browser that
+ * refuses storage.
+ */
+export const browserTipStorage = () => {
+    try {
+        const storage = globalThis.localStorage;
+        // Presence is not permission: Safari's private mode throws on write.
+        storage.setItem('tips:probe', '1');
+        storage.removeItem('tips:probe');
+        return storage;
+    }
+    catch {
+        return memoryTipStorage();
+    }
+};
+/**
+ * Build a tip store over the given storage.
+ *
+ * Call once, high in the tree, and hand it to the tips (or put it in a context
+ * of the app's own). The in-memory state is what drives re-rendering; storage
+ * is where it survives a reload.
+ */
+export const createTipStore = (options = {}) => {
+    const storage = options.storage ?? browserTipStorage();
+    const prefix = options.prefix ?? DEFAULT_PREFIX;
+    const configs = new Map();
+    const states = $state(new Map());
+    const read = (id) => {
+        const live = states.get(id);
+        if (live !== undefined)
+            return live;
+        let stored = { id, status: 'pending', displayCount: 0 };
+        try {
+            const raw = storage.getItem(`${prefix}${id}`);
+            // Trusted only for its shape: it is this app's own write, and a corrupt
+            // entry falls back to "never seen" rather than throwing at the reader.
+            if (raw !== null)
+                stored = JSON.parse(raw);
+        }
+        catch {
+            /* unreadable or malformed — treat the tip as unseen */
+        }
+        states.set(id, stored);
+        return stored;
+    };
+    const write = (next) => {
+        states.set(next.id, next);
+        try {
+            storage.setItem(`${prefix}${next.id}`, JSON.stringify(next));
+        }
+        catch {
+            /* storage refused; the in-memory state still drives this session */
+        }
+    };
+    const frequencyAllows = (config, state) => {
+        if (state.lastShown === undefined)
+            return true;
+        const frequency = config.frequency ?? 'immediate';
+        if (frequency === 'immediate')
+            return true;
+        if (frequency === 'once')
+            return false;
+        const since = Date.now() - new Date(state.lastShown).getTime();
+        return since >= (INTERVALS[frequency] ?? 0);
+    };
+    return {
+        register: (config) => {
+            configs.set(config.id, config);
+        },
+        getState: read,
+        shouldDisplay: (id) => {
+            const config = configs.get(id);
+            // An unregistered tip shows nothing: a typo in an id should be an absent
+            // tip, not a tip with no rules.
+            if (config === undefined)
+                return false;
+            const state = read(id);
+            if (state.status === 'dismissed' || state.status === 'completed')
+                return false;
+            if (config.maxDisplayCount !== undefined && state.displayCount >= config.maxDisplayCount) {
+                return false;
+            }
+            if (!frequencyAllows(config, state))
+                return false;
+            return (config.rules ?? []).every((rule) => rule.evaluate());
+        },
+        markShown: (id) => {
+            const state = read(id);
+            write({
+                ...state,
+                status: 'available',
+                displayCount: state.displayCount + 1,
+                lastShown: new Date().toISOString(),
+            });
+        },
+        dismiss: (id) => {
+            write({ ...read(id), status: 'dismissed', dismissedAt: new Date().toISOString() });
+        },
+        complete: (id) => {
+            write({ ...read(id), status: 'completed', completedAt: new Date().toISOString() });
+        },
+        resetAll: () => {
+            for (const id of [...states.keys(), ...configs.keys()]) {
+                states.delete(id);
+                try {
+                    storage.removeItem(`${prefix}${id}`);
+                }
+                catch {
+                    /* storage refused; the in-memory reset still stands */
+                }
+            }
+        },
+    };
+};

package/dist/tips/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * TipKit types — contextual, dismissible guidance, after Apple's TipKit.
+ *
+ * @module
+ */
+/** How often a tip may reappear once it has been shown. */
+export type TipFrequency = 'immediate' | 'hourly' | 'daily' | 'weekly' | 'once';
+/** Where a tip has got to in its life. */
+export type TipStatus = 'pending' | 'available' | 'dismissed' | 'completed';
+/** Which side of its anchor a popover tip sits on. */
+export type TipPlacement = 'top' | 'bottom' | 'left' | 'right';
+/** A condition that must hold for a tip to show. */
+export interface TipRule {
+    readonly id: string;
+    /** Synchronous on purpose — see the note in `tip-store.svelte.ts`. */
+    readonly evaluate: () => boolean;
+}
+/** Something the reader can do from the tip. */
+export interface TipAction {
+    readonly id: string;
+    readonly title: string;
+    readonly handler: () => void | Promise<void>;
+}
+/** A tip, as declared by the page that owns it. */
+export interface TipConfig {
+    readonly id: string;
+    readonly title: string;
+    readonly message?: string | undefined;
+    readonly actions?: readonly TipAction[] | undefined;
+    /** Every rule must hold. */
+    readonly rules?: readonly TipRule[] | undefined;
+    /** Defaults to `immediate` — shown every time the page is visited. */
+    readonly frequency?: TipFrequency | undefined;
+    /** Never shown more than this many times, whatever the frequency says. */
+    readonly maxDisplayCount?: number | undefined;
+}
+/** What is remembered about a tip between visits. */
+export interface TipState {
+    readonly id: string;
+    readonly status: TipStatus;
+    readonly displayCount: number;
+    /** ISO 8601; absent until the tip has been shown once. */
+    readonly lastShown?: string | undefined;
+    readonly dismissedAt?: string | undefined;
+    readonly completedAt?: string | undefined;
+}

package/dist/tips/types.js

@@ -0,0 +1,6 @@
+/**
+ * TipKit types — contextual, dismissible guidance, after Apple's TipKit.
+ *
+ * @module
+ */
+export {};

package/dist/ui/Alert.svelte

@@ -0,0 +1,61 @@
+<!-- @component
+The daisyUI `alert`: a tone-coloured notice with an icon, an optional lead-in and an optional dismiss button.
+-->
+<!--
+  Alert — the daisyUI `alert`: a tone-coloured notice with an icon, an
+  optional bold lead-in and an optional dismiss button.
+
+  ARIA contract, and the reason `live` is a prop rather than a constant: an
+  alert that is on the page when it loads must NOT be announced, an alert
+  that appears in response to something the reader did must be, and the
+  urgency depends on what happened. `live` picks between `role="alert"`
+  (assertive — interrupt, the default for `error`), `role="status"` (polite —
+  wait for a pause, the default for everything else) and `off`, which renders
+  no role at all. Static page furniture wants `off`; a form failure wants
+  `assertive`.
+
+  A live region must be IN the document before its content changes, so an app
+  that swaps an alert's text keeps the component mounted; one that mounts the
+  alert on failure gets the announcement from the insertion.
+
+  The tone icon is `aria-hidden` — it restates the tone, which the text
+  already carries — and the dismiss button is a labelled `Button`, not a
+  bare glyph.
+-->
+<script lang="ts">import { CircleCheck, CircleX, Info, TriangleAlert, X } from "@lucide/svelte";
+import Button from "./Button.svelte";
+import { alertTone, alertVariant } from "./tones.js";
+import VisuallyHidden from "./VisuallyHidden.svelte";
+let { tone = "info", variant = "soft", title, live, icon, onDismiss, dismissLabel = "Dismiss", children, class: className, ...rest } = $props();
+const liveness = $derived(live ?? (tone === "error" ? "assertive" : "polite"));
+// `role="alert"` already implies `aria-live="assertive"` and `role="status"`
+// implies `polite`; spelling the second one out as well is how a region ends
+// up announced twice.
+const role = $derived(liveness === "assertive" ? "alert" : liveness === "polite" ? "status" : undefined);
+</script>
+
+<div {...rest} {role} class={['alert', alertTone[tone], alertVariant[variant], className]}>
+  {#if icon}
+    {@render icon()}
+  {:else if tone === 'success'}
+    <CircleCheck class="size-5 shrink-0" aria-hidden="true" />
+  {:else if tone === 'warning'}
+    <TriangleAlert class="size-5 shrink-0" aria-hidden="true" />
+  {:else if tone === 'error'}
+    <CircleX class="size-5 shrink-0" aria-hidden="true" />
+  {:else}
+    <Info class="size-5 shrink-0" aria-hidden="true" />
+  {/if}
+  <div>
+    {#if title !== undefined}
+      <p class="font-semibold">{title}</p>
+    {/if}
+    {@render children()}
+  </div>
+  {#if onDismiss}
+    <Button variant="ghost" size="sm" class="btn-square" onclick={onDismiss}>
+      <X class="size-4" aria-hidden="true" />
+      <VisuallyHidden>{dismissLabel}</VisuallyHidden>
+    </Button>
+  {/if}
+</div>

package/dist/ui/Alert.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type AlertVariant, type StatusTone } from './tones.ts';
+interface Props extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Status colour and icon.
+     * @defaultValue `'info'`
+     */
+    tone?: StatusTone | undefined;
+    /**
+     * daisyUI alert style.
+     * @defaultValue `'soft'`
+     */
+    variant?: AlertVariant | undefined;
+    /** Bold lead-in rendered above the body. */
+    title?: string | undefined;
+    /**
+     * How — and whether — assistive technology announces this alert.
+     * Defaults to `assertive` for `error` and `polite` for every other tone.
+     */
+    live?: 'assertive' | 'polite' | 'off' | undefined;
+    /** Replace the tone's default icon. */
+    icon?: Snippet<[]> | undefined;
+    /** When set, renders a dismiss button that calls it. */
+    onDismiss?: (() => void) | undefined;
+    /**
+     * Accessible name of the dismiss button.
+     * @defaultValue `'Dismiss'`
+     */
+    dismissLabel?: string | undefined;
+    /** The message, after the optional bold lead-in. */
+    children: Snippet<[]>;
+}
+/** The daisyUI `alert`: a tone-coloured notice with an icon, an optional lead-in and an optional dismiss button. */
+declare const Alert: import("svelte").Component<Props, {}, "">;
+type Alert = ReturnType<typeof Alert>;
+export default Alert;

package/dist/ui/Badge.svelte

@@ -0,0 +1,39 @@
+<!-- @component
+The daisyUI `badge`: a short inline label for a status, a count or a category.
+-->
+<!--
+  Badge — the daisyUI `badge`: a short, inline label for a status, a count or
+  a category.
+
+  Two colour paths. A semantic `tone` picks the badge's daisyUI colour, which
+  is what a status ("Draft", "Overdue") wants. A `colourToken` instead names a
+  custom property the consuming app's theme declares, which is what a
+  subject-coloured label (a party, a rank, a project) wants: the badge then
+  tints its border and a translucent fill from that one variable and keeps
+  `base-content` text, so it stays legible on either theme whatever the hue.
+  `colourToken` wins over `tone` — a subject's colour is not a tone.
+
+  ARIA contract: none, deliberately. A badge is a decorative frame around
+  text, so the text has to carry the meaning: a status badge showing only a
+  colour is a status nobody can read. If the badge's own text is not enough
+  in context, label the thing it sits on, not the badge.
+-->
+<script lang="ts">import { BADGE_COLOUR_PROPERTY, colourTokenStyle } from "./colour-token.js";
+import { badgeSize, badgeTone, badgeVariant } from "./tones.js";
+let { tone = "neutral", variant = "soft", size = "md", colourToken, children, class: className, ...rest } = $props();
+const classes = $derived(colourToken === undefined ? [
+	"badge",
+	badgeTone[tone],
+	badgeVariant[variant],
+	badgeSize[size],
+	className
+] : [
+	"badge border-(--badge-colour) bg-(--badge-colour)/15 text-base-content",
+	badgeSize[size],
+	className
+]);
+</script>
+
+<span {...rest} class={classes} style={colourTokenStyle(BADGE_COLOUR_PROPERTY, colourToken)}>
+  {@render children()}
+</span>

package/dist/ui/Badge.svelte.d.ts

@@ -0,0 +1,32 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type BadgeVariant, type Size, type Tone } from './tones.ts';
+interface Props extends HTMLAttributes<HTMLSpanElement> {
+    /**
+     * Semantic colour.
+     * @defaultValue `'neutral'`
+     */
+    tone?: Tone | undefined;
+    /**
+     * daisyUI badge style.
+     * @defaultValue `'soft'`
+     */
+    variant?: BadgeVariant | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: Size | undefined;
+    /**
+     * A CSS custom-property name the app's theme declares (`--party-alp`).
+     * Overrides `tone` and `variant`; falls back to the theme's neutral
+     * colour when the token is undeclared.
+     */
+    colourToken?: string | undefined;
+    /** The badge text; keep it to a word or a count. */
+    children: Snippet<[]>;
+}
+/** The daisyUI `badge`: a short inline label for a status, a count or a category. */
+declare const Badge: import("svelte").Component<Props, {}, "">;
+type Badge = ReturnType<typeof Badge>;
+export default Badge;

package/dist/ui/Button.svelte

@@ -0,0 +1,43 @@
+<!-- @component
+The daisyUI `btn` with tone, variant and size; `loading` disables it and sets `aria-busy` without changing its name. `type` defaults to `button`, not the native `submit`.
+-->
+<!--
+  Button — the daisyUI `btn`, with tone / variant / size chosen from literal
+  lookup tables and a `loading` state that is a real busy state rather than a
+  spinner drawn over a live control.
+
+  ARIA contract: a native `<button>`, so role and keyboard (Enter and Space)
+  come from the platform and nothing is hand-rolled. While `loading` the
+  button is `disabled` AND `aria-busy="true"` — disabled alone says "you may
+  not", busy says "it is already happening" — and the spinner that replaces
+  the leading icon is `aria-hidden`, because the accessible name must not
+  change when the state does.
+
+  `type` defaults to `button`: a button inside a form that does not say what
+  it is submits it, which is almost never what a call site means.
+-->
+<script lang="ts">import { buttonSize, buttonTone, buttonVariant } from "./tones.js";
+let { tone, variant = "solid", size = "md", loading = false, block = false, icon, children, type = "button", disabled = false, class: className, ...rest } = $props();
+</script>
+
+<button
+  {...rest}
+  {type}
+  disabled={disabled || loading}
+  aria-busy={loading ? 'true' : undefined}
+  class={[
+    'btn',
+    tone !== undefined && buttonTone[tone],
+    buttonVariant[variant],
+    buttonSize[size],
+    block && 'btn-block',
+    className,
+  ]}
+>
+  {#if loading}
+    <span class="loading loading-spinner loading-sm" aria-hidden="true"></span>
+  {:else if icon}
+    {@render icon()}
+  {/if}
+  {@render children()}
+</button>

package/dist/ui/Button.svelte.d.ts

@@ -0,0 +1,29 @@
+import type { Snippet } from 'svelte';
+import type { HTMLButtonAttributes } from 'svelte/elements';
+import { type ButtonVariant, type Size, type Tone } from './tones.ts';
+interface Props extends HTMLButtonAttributes {
+    /** Semantic colour. Omitted, the button is daisyUI's neutral `btn`. */
+    tone?: Tone | undefined;
+    /**
+     * daisyUI button style.
+     * @defaultValue `'solid'`
+     */
+    variant?: ButtonVariant | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: Size | undefined;
+    /** Disables the button, marks it busy and shows a spinner. */
+    loading?: boolean | undefined;
+    /** Full-width. */
+    block?: boolean | undefined;
+    /** Leading icon, replaced by the spinner while `loading`. */
+    icon?: Snippet<[]> | undefined;
+    /** The button text; its accessible name. */
+    children: Snippet<[]>;
+}
+/** The daisyUI `btn` with tone, variant and size; `loading` disables it and sets `aria-busy` without changing its name. `type` defaults to `button`, not the native `submit`. */
+declare const Button: import("svelte").Component<Props, {}, "">;
+type Button = ReturnType<typeof Button>;
+export default Button;

package/dist/ui/Card.svelte

@@ -0,0 +1,49 @@
+<!-- @component
+The bordered `base-100` surface: a padded body with an optional heading, a figure above and an actions row below.
+-->
+<!--
+  Card — the surface. One bordered box on `base-100` with a padded body, an
+  optional heading, an optional figure above it and an optional actions row
+  under it.
+
+  This component exists to END the hand-written
+  `card card-border bg-base-100 p-6 shadow-sm`, of which the four apps carried
+  56 copies. A bare `<Card>` renders exactly that look, so adopting it is a
+  substitution and never a redesign; every knob below is an opt-in for a site
+  that wanted something slightly different and previously got it by editing
+  the class list in place.
+
+  ARIA contract: `title` is a REAL heading at `headingLevel`, not a styled
+  `<p>`, so a card in a list is reachable by heading navigation and the
+  document outline stays true. The default is `h2` — a card under the page's
+  `<h1>`. `as` picks the element that carries the semantics: `article` for a
+  self-contained item (the default), `section` for a labelled region of the
+  page, `div` for pure grouping.
+-->
+<script lang="ts">import { cardSize, cardVariant } from "./tones.js";
+let { as = "article", title, headingLevel = 2, variant = "border", size = "md", padded = true, bodyClass, figure, actions, children, class: className, ...rest } = $props();
+</script>
+
+<svelte:element
+  this={as}
+  {...rest}
+  class={[
+    'card bg-base-100 shadow-sm',
+    cardVariant[variant],
+    cardSize[size],
+    className,
+  ]}
+>
+  {#if figure}
+    <figure>{@render figure()}</figure>
+  {/if}
+  <div class={['card-body', !padded && 'p-0', bodyClass]}>
+    {#if title !== undefined}
+      <svelte:element this={`h${headingLevel}`} class="card-title">{title}</svelte:element>
+    {/if}
+    {@render children()}
+    {#if actions}
+      <div class="card-actions justify-end">{@render actions()}</div>
+    {/if}
+  </div>
+</svelte:element>

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

@@ -0,0 +1,44 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type CardVariant, type HeadingLevel, type Size } from './tones.ts';
+interface Props extends HTMLAttributes<HTMLElement> {
+    /**
+     * The element that carries the semantics.
+     * @defaultValue `'article'`
+     */
+    as?: 'article' | 'section' | 'div' | undefined;
+    /** Heading rendered as `card-title` at the top of the body. */
+    title?: string | undefined;
+    /**
+     * Heading level for `title`.
+     * @defaultValue `2`
+     */
+    headingLevel?: HeadingLevel | undefined;
+    /**
+     * daisyUI card style.
+     * @defaultValue `'border'`
+     */
+    variant?: CardVariant | undefined;
+    /**
+     * daisyUI size step.
+     * @defaultValue `'md'`
+     */
+    size?: Size | undefined;
+    /**
+     * Drop the body padding — for a card whose content is edge to edge.
+     * @defaultValue `true`
+     */
+    padded?: boolean | undefined;
+    /** Extra classes on the `card-body`, for layout the caller owns. */
+    bodyClass?: string | undefined;
+    /** Media block rendered above the body. */
+    figure?: Snippet<[]> | undefined;
+    /** Buttons or links rendered in the `card-actions` row. */
+    actions?: Snippet<[]> | undefined;
+    /** The body, inside the padded `card-body`, under the heading. */
+    children: Snippet<[]>;
+}
+/** The bordered `base-100` surface: a padded body with an optional heading, a figure above and an actions row below. */
+declare const Card: import("svelte").Component<Props, {}, "">;
+type Card = ReturnType<typeof Card>;
+export default Card;