@thomasfosterau/components 0.0.0 → 0.2.0

package/dist/tips/PopoverTip.svelte

@@ -0,0 +1,80 @@
+<!-- @component
+A `Tip` anchored beside the trigger it is about, which renders inside it.
+-->
+<!--
+  PopoverTip — a `Tip` anchored to the thing it is talking about: the
+  caller's own trigger renders inside, and the bubble floats beside it.
+
+  Built on bits-ui's `Popover` rather than the hand-measured `position: fixed`
+  span the old copy used (a layout read per scroll frame, page-wide, for a
+  bubble that never moves relative to what it points at) — bits-ui's
+  `Popover.Content` computes and keeps that position via Floating UI, and
+  handles focus containment and outside-click dismissal for free.
+
+  `open` is NOT bound: it is a pure function of the tip's own state
+  (`available` and not yet dismissed/completed), read back from the store. A
+  tip shows because the store's rules say it may, never because the reader
+  clicked the trigger — so the trigger element has its bits-ui click/keydown
+  toggle handlers stripped (the `onclick`/`onkeydown` overrides below); it
+  keeps only the id/ref wiring `Popover.Content` needs to float against it.
+  Otherwise a click on an ordinary anchor button could pop open an EMPTY
+  bubble for a tip the store has not decided to show yet (`Tip`'s own
+  `{#if visible}` gate would render nothing inside).
+
+  Escape closing is arbitrated by the shared `TipStack`, not by bits-ui's own
+  (unrelated) escape-layer stacking order: `onEscapeKeydown` blocks the
+  default close unless this tip is the page's topmost, so two tips opened
+  from two different `PopoverTip`s still resolve "which one does Escape
+  close" the same way two `Tip`s do. Whatever closes the popover — Escape
+  when topmost, or a click outside it — is treated as a dismissal and fed
+  back into the store via `onOpenChange`, so the store and the floating
+  layer never disagree about whether the tip is showing.
+
+  `Popover.Content` is `forceMount`ed: it stays in the DOM whether or not
+  `open` is true, with bits-ui only toggling its floating position/listeners.
+  That is what lets `Tip` — mounted unconditionally inside it — run its own
+  `shouldDisplay`/`markShown` effect and flip the store to `available` in the
+  first place. Without `forceMount`, `Content` would itself wait for `open`
+  before rendering `Tip` at all, and `open` here is derived FROM what `Tip`
+  decides — a deadlock neither side could break.
+-->
+<script lang="ts">import { Popover } from "bits-ui";
+import Tip from "./Tip.svelte";
+import { soloTipStack } from "./tip-stack.js";
+let { config, store, stack = soloTipStack, placement = "top", children, dismissLabel = "Dismiss", class: className } = $props();
+const placementSide = {
+	top: "top",
+	bottom: "bottom",
+	left: "left",
+	right: "right"
+};
+/** True exactly when `Tip` would render itself, read back from the store. */
+const open = $derived(store.getState(config.id).status === "available");
+const handleOpenChange = (next) => {
+	if (!next) store.dismiss(config.id);
+};
+const handleEscapeKeydown = (event) => {
+	if (!stack.isTopmost(config.id)) event.preventDefault();
+};
+</script>
+
+<Popover.Root {open} onOpenChange={handleOpenChange}>
+  <Popover.Trigger>
+    {#snippet child({ props })}
+      <span {...props} onclick={undefined} onkeydown={undefined} class="contents">
+        {@render children()}
+      </span>
+    {/snippet}
+  </Popover.Trigger>
+  <Popover.Portal>
+    <Popover.Content
+      forceMount
+      side={placementSide[placement]}
+      sideOffset={8}
+      onEscapeKeydown={handleEscapeKeydown}
+      class={['z-50 w-64', className]}
+    >
+      <Tip {config} {store} {stack} {dismissLabel} />
+    </Popover.Content>
+  </Popover.Portal>
+</Popover.Root>

package/dist/tips/PopoverTip.svelte.d.ts

@@ -0,0 +1,33 @@
+import type { Snippet } from 'svelte';
+import { type TipStack } from './tip-stack.ts';
+import type { TipStore } from './tip-store.svelte.ts';
+import type { TipConfig, TipPlacement } from './types.ts';
+interface Props {
+    /** The tip’s id, copy and actions. */
+    config: TipConfig;
+    /** The store that decides whether this shows and remembers that it did. */
+    store: TipStore;
+    /**
+     * Shared with the page’s other tips so Escape closes only the top one.
+     * @defaultValue `soloTipStack` (shares Escape with no other tip)
+     */
+    stack?: TipStack | undefined;
+    /**
+     * Which side of the trigger the bubble sits on.
+     * @defaultValue `'top'`
+     */
+    placement?: TipPlacement | undefined;
+    /** The trigger — a button, a field, whatever the tip is about. */
+    children: Snippet<[]>;
+    /**
+     * Accessible name of the tip's dismiss button.
+     * @defaultValue `'Dismiss'`
+     */
+    dismissLabel?: string | undefined;
+    /** Extra classes, merged last. */
+    class?: string | undefined;
+}
+/** A `Tip` anchored beside the trigger it is about, which renders inside it. */
+declare const PopoverTip: import("svelte").Component<Props, {}, "">;
+type PopoverTip = ReturnType<typeof PopoverTip>;
+export default PopoverTip;

package/dist/tips/Tip.svelte

@@ -0,0 +1,91 @@
+<!-- @component
+One piece of inline guidance that shows only when its store allows and closes for good once dismissed or acted on.
+-->
+<!--
+  Tip — one piece of inline guidance: a title, an optional sentence, and the
+  actions it offers. Shows itself only if the store says it may, records that
+  it did, and closes for good when the reader dismisses it or takes an
+  action.
+
+  A daisyUI `alert` rather than a hand-rolled card — no hard-coded colours, no
+  hand-drawn arrow (that belongs to `PopoverTip`, where a tip is actually
+  anchored to something an arrow can point at; an inline tip sits in the flow
+  and has nothing to point at).
+
+  `role="status"` with `aria-live="polite"`: a tip is an offer, not an
+  interruption, so it is announced at the next pause rather than immediately.
+
+  The Escape-to-dismiss listener is hand-rolled rather than left to bits-ui:
+  this component has no bits-ui primitive backing it (it is a plain `alert`,
+  not a dialog or popover), and the key has to be scoped to "only the topmost
+  tip on the page" via the shared `TipStack` — a concern bits-ui's own
+  Escape handling knows nothing about. `PopoverTip` wires the same stack into
+  its bits-ui `Popover` instead, once there is a floating layer to hand it to.
+-->
+<script lang="ts">import { soloTipStack } from "./tip-stack.js";
+let { config, store, stack = soloTipStack, dismissLabel = "Dismiss", class: className } = $props();
+let visible = $state(false);
+// The decision is made on mount, not during render: `markShown` writes, and a
+// write inside a derivation would run again on every re-render.
+$effect(() => {
+	if (!store.shouldDisplay(config.id)) return;
+	visible = true;
+	store.markShown(config.id);
+});
+$effect(() => {
+	if (!visible) return;
+	stack.push(config.id);
+	const onKey = (event) => {
+		if (event.key !== "Escape" || !stack.isTopmost(config.id)) return;
+		event.preventDefault();
+		dismiss();
+	};
+	globalThis.addEventListener("keydown", onKey);
+	return () => {
+		stack.pop(config.id);
+		globalThis.removeEventListener("keydown", onKey);
+	};
+});
+const dismiss = () => {
+	store.dismiss(config.id);
+	visible = false;
+};
+/**
+* Taking an action COMPLETES the tip rather than dismissing it. The two are
+* different facts — "they did the thing" and "they made it go away" — and
+* the store keeps them apart so a later "show me what I skipped" can tell.
+*/
+const act = async (action) => {
+	await action.handler();
+	store.complete(config.id);
+	visible = false;
+};
+</script>
+
+{#if visible}
+  <div class={['alert alert-info alert-soft items-start', className]} role="status" aria-live="polite">
+    <div class="flex-1 space-y-2">
+      <p class="font-semibold">{config.title}</p>
+      {#if config.message !== undefined && config.message !== ''}
+        <p class="text-sm">{config.message}</p>
+      {/if}
+      {#if config.actions !== undefined && config.actions.length > 0}
+        <div class="flex flex-wrap gap-2">
+          {#each config.actions as action (action.id)}
+            <button type="button" class="btn btn-sm" onclick={() => act(action)}>
+              {action.title}
+            </button>
+          {/each}
+        </div>
+      {/if}
+    </div>
+    <button
+      type="button"
+      class="btn btn-ghost btn-sm btn-circle"
+      onclick={dismiss}
+      aria-label={dismissLabel}
+    >
+      ✕
+    </button>
+  </div>
+{/if}

package/dist/tips/Tip.svelte.d.ts

@@ -0,0 +1,25 @@
+import { type TipStack } from './tip-stack.ts';
+import type { TipStore } from './tip-store.svelte.ts';
+import type { TipConfig } from './types.ts';
+interface Props {
+    /** The tip’s id, copy and actions. */
+    config: TipConfig;
+    /** The store that decides whether this shows and remembers that it did. */
+    store: TipStore;
+    /**
+     * Shared with the page's other tips so Escape closes only the top one.
+     * @defaultValue `soloTipStack` (shares Escape with no other tip)
+     */
+    stack?: TipStack | undefined;
+    /**
+     * Accessible name of the dismiss button.
+     * @defaultValue `'Dismiss'`
+     */
+    dismissLabel?: string | undefined;
+    /** Extra classes, merged last. */
+    class?: string | undefined;
+}
+/** One piece of inline guidance that shows only when its store allows and closes for good once dismissed or acted on. */
+declare const Tip: import("svelte").Component<Props, {}, "">;
+type Tip = ReturnType<typeof Tip>;
+export default Tip;

package/dist/tips/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@thomasfosterau/components/tips` — a separate entry point so it never sits on
+ * the always-loaded path of a consumer that does not use it.
+ *
+ * TipKit — contextual, dismissible guidance: an inline tip, a tip anchored to
+ * its trigger, the store that decides when either may show, and the stack
+ * that decides which one Escape closes.
+ *
+ * @module
+ */
+export { default as PopoverTip } from './PopoverTip.svelte';
+export { default as Tip } from './Tip.svelte';
+export { createTipStack, soloTipStack, type TipStack } from './tip-stack.ts';
+export { browserTipStorage, createTipStore, memoryTipStorage, type TipStorage, type TipStoreOptions, type TipStore, } from './tip-store.svelte.ts';
+export type { TipAction, TipConfig, TipFrequency, TipPlacement, TipRule, TipState, TipStatus, } from './types.ts';

package/dist/tips/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@thomasfosterau/components/tips` — a separate entry point so it never sits on
+ * the always-loaded path of a consumer that does not use it.
+ *
+ * TipKit — contextual, dismissible guidance: an inline tip, a tip anchored to
+ * its trigger, the store that decides when either may show, and the stack
+ * that decides which one Escape closes.
+ *
+ * @module
+ */
+export { default as PopoverTip } from './PopoverTip.svelte';
+export { default as Tip } from './Tip.svelte';
+export { createTipStack, soloTipStack } from "./tip-stack.js";
+export { browserTipStorage, createTipStore, memoryTipStorage, } from "./tip-store.svelte.js";

package/dist/tips/tip-stack.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The tip stack: which tips are on screen, most recent last.
+ *
+ * It exists for one keystroke. Escape must close the tip the reader is looking
+ * at — the last one to appear — and not every tip on the page at once. Each
+ * visible tip asks the stack whether it is on top before acting on the key.
+ *
+ * @module
+ */
+/** Which tips are on screen, most recent last, so Escape closes only the topmost one. */
+export interface TipStack {
+    /** Mark a tip visible, moving it to the top if it was already there. */
+    push: (id: string) => void;
+    /** Mark a tip no longer visible. */
+    pop: (id: string) => void;
+    /** Whether this tip is the one Escape should close. */
+    isTopmost: (id: string) => boolean;
+}
+/**
+ * A fresh stack. Create one per app (or per test) and hand it to the tips; a
+ * module-level singleton would make two mounted apps — or two tests — share a
+ * stack, which is exactly the bug this is meant to prevent.
+ */
+export declare const createTipStack: () => TipStack;
+/** A stack that always says yes — for a tip mounted without one. */
+export declare const soloTipStack: TipStack;

package/dist/tips/tip-stack.js

@@ -0,0 +1,37 @@
+/**
+ * The tip stack: which tips are on screen, most recent last.
+ *
+ * It exists for one keystroke. Escape must close the tip the reader is looking
+ * at — the last one to appear — and not every tip on the page at once. Each
+ * visible tip asks the stack whether it is on top before acting on the key.
+ *
+ * @module
+ */
+/**
+ * A fresh stack. Create one per app (or per test) and hand it to the tips; a
+ * module-level singleton would make two mounted apps — or two tests — share a
+ * stack, which is exactly the bug this is meant to prevent.
+ */
+export const createTipStack = () => {
+    const stack = [];
+    return {
+        push: (id) => {
+            const index = stack.indexOf(id);
+            if (index !== -1)
+                stack.splice(index, 1);
+            stack.push(id);
+        },
+        pop: (id) => {
+            const index = stack.indexOf(id);
+            if (index !== -1)
+                stack.splice(index, 1);
+        },
+        isTopmost: (id) => stack.length > 0 && stack[stack.length - 1] === id,
+    };
+};
+/** A stack that always says yes — for a tip mounted without one. */
+export const soloTipStack = {
+    push: () => { },
+    pop: () => { },
+    isTopmost: () => true,
+};

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

@@ -0,0 +1,75 @@
+/**
+ * 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 the DOM `Storage` interface a tip store reads and writes, 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 {};