@thomasfosterau/components 0.0.0 → 0.1.0

package/dist/seo/og-image.js

@@ -0,0 +1,81 @@
+/**
+ * The content-addressed Open Graph share-image URL builder.
+ *
+ * Shared by `<Head>` (which emits the URL as `og:image`) and whatever renders
+ * the card (an app route or Worker reading the same query params), so the
+ * producer and the consumer of the URL can never disagree on the param names
+ * or the length caps — import the constants below on both sides.
+ *
+ * The URL is **content-addressed**: the title and description ride in the
+ * query, and a `v` token derived from the content's last-modified instant
+ * changes the whole URL whenever the content changes. A new URL is how the
+ * image cache-busts — link-preview scrapers (Facebook, LinkedIn, federated
+ * servers) cache aggressively and only re-fetch a URL they have not seen, so
+ * the version token is load-bearing, not cosmetic.
+ *
+ * @module
+ */
+/** Query param carrying the card title. */
+export const OG_TITLE_PARAM = 't';
+/** Query param carrying the card's second line (the page description). */
+export const OG_SUBTITLE_PARAM = 'd';
+/** Query param carrying the cache-busting version token. */
+export const OG_VERSION_PARAM = 'v';
+/**
+ * Length caps on the title / description carried in the URL. A renderer
+ * should re-apply them defensively; here they keep the emitted URL short.
+ */
+export const OG_TITLE_MAX_LENGTH = 120;
+/** Longest description, in characters, carried in a share-card URL; see `OG_TITLE_MAX_LENGTH`. */
+export const OG_SUBTITLE_MAX_LENGTH = 200;
+/** The rendered card's size — the 1.91:1 Open Graph standard. */
+export const OG_IMAGE_WIDTH = 1200;
+/** Share-card height in pixels; see `OG_IMAGE_WIDTH`. */
+export const OG_IMAGE_HEIGHT = 630;
+/**
+ * Reduce an identity to a short URL-safe slug. Cosmetic — a renderer should
+ * ignore it — so an empty or garbage id collapses to a stable fallback rather
+ * than an invalid path.
+ */
+const toSlug = (id) => {
+    const slug = id
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+    return slug === '' ? 'page' : slug;
+};
+/** Epoch milliseconds of `updatedAt`, or `undefined` when absent or unparseable. */
+const versionToken = (updatedAt) => {
+    if (updatedAt === null || updatedAt === undefined)
+        return undefined;
+    const time = updatedAt instanceof Date
+        ? updatedAt.getTime()
+        : typeof updatedAt === 'number'
+            ? updatedAt
+            : Date.parse(updatedAt);
+    return Number.isFinite(time) ? String(time) : undefined;
+};
+/**
+ * Build the `og:image` URL for a page's share card: `<basePath>/<slug>.png`
+ * resolved through `href`, with the title, description and version token in
+ * the query. Returns `undefined` for a blank title, so the caller falls back
+ * to its default share image.
+ */
+export function ogImageUrl(card, options = {}) {
+    const title = card.title.trim();
+    if (title === '')
+        return undefined;
+    const params = new URLSearchParams();
+    params.set(OG_TITLE_PARAM, title.slice(0, OG_TITLE_MAX_LENGTH));
+    const description = card.description?.trim();
+    if (description !== undefined && description !== '') {
+        params.set(OG_SUBTITLE_PARAM, description.slice(0, OG_SUBTITLE_MAX_LENGTH));
+    }
+    const version = versionToken(card.updatedAt);
+    if (version !== undefined)
+        params.set(OG_VERSION_PARAM, version);
+    const basePath = (options.basePath ?? '/og').replace(/\/+$/, '');
+    const href = options.href ?? ((path) => path);
+    return `${href(`${basePath}/${toSlug(card.id)}.png`)}?${params.toString()}`;
+}

package/dist/seo/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The data shapes `<Head>` takes.
+ *
+ * @module
+ */
+/** The Open Graph `og:type` values `<Head>` emits. */
+export type OpenGraphType = 'website' | 'article' | 'profile';
+/**
+ * The Schema.org page types `<Head>` understands, used only to derive
+ * `og:type` when `openGraphType` is not given (so it is never empty).
+ */
+export type SchemaPageType = 'WebPage' | 'WebSite' | 'CollectionPage' | 'Article' | 'BlogPosting' | 'ProfilePage';
+/** The Twitter / X card variants. */
+export type TwitterCard = 'summary' | 'summary_large_image';
+/** A social preview image. `url` must be absolute. */
+export interface HeadImage {
+    readonly url: string;
+    readonly alt?: string | undefined;
+    readonly width?: number | undefined;
+    readonly height?: number | undefined;
+    /** The MIME type, e.g. `image/png`. */
+    readonly type?: string | undefined;
+}
+/** One `<link rel="alternate" hreflang>`. */
+export interface AlternateLink {
+    readonly href: string;
+    /** A BCP 47 tag, or `x-default`. */
+    readonly lang: string;
+}
+/** The `robots` meta directive. Both default to `true`. */
+export interface Robots {
+    readonly index?: boolean | undefined;
+    readonly follow?: boolean | undefined;
+}
+/** A feed advertised with `<link rel="alternate">`. */
+export interface FeedLink {
+    /** App-relative path, resolved through `canonicalHref` like the canonical URL. */
+    readonly path: string;
+    /** The feed's title. Default `'Latest changes'`. */
+    readonly title?: string | undefined;
+    /** The feed's MIME type. Default `application/feed+json` (JSON Feed 1.1). */
+    readonly type?: string | undefined;
+}

package/dist/seo/types.js

@@ -0,0 +1,6 @@
+/**
+ * The data shapes `<Head>` takes.
+ *
+ * @module
+ */
+export {};

package/dist/theme.css

@@ -0,0 +1,161 @@
+/*
+ * The library's design tokens: two daisyUI themes, `light` and `dark`, that
+ * every component in this package renders on.
+ *
+ * Shipped as the package's `./theme.css` export and imported by BOTH
+ * consumers — an application's CSS entry, and Storybook's
+ * `.storybook/preview.css` relatively — so there is exactly one copy of every
+ * token.
+ *
+ * **This is the whole styling vocabulary.** A component here reaches for a
+ * semantic name — `bg-base-200`, `text-error`, `btn-primary` — and never for
+ * a raw palette class (`bg-green-700`), a hex, or an `oklch()` of its own. Two
+ * vocabularies for one palette is how a design system drifts.
+ *
+ * The values below are DELIBERATELY NEUTRAL: an achromatic surface ramp and a
+ * single mid-slate brand hue, so the library looks like nothing in particular
+ * out of the box. They are a starting point, not a brand. An application
+ * overrides them by declaring its own `light` / `dark` themes after importing
+ * this file, or by naming its own themes entirely and never importing it.
+ */
+@plugin "daisyui/theme" {
+  name: 'light';
+  default: true;
+  color-scheme: light;
+  /* Surfaces: a neutral off-white ramp. */
+  --color-base-100: oklch(100% 0 0);
+  --color-base-200: oklch(96% 0 0);
+  --color-base-300: oklch(91% 0 0);
+  --color-base-content: oklch(22% 0 0);
+  /* Brand: slate. Replace these four pairs, not the surface ramp. */
+  --color-primary: oklch(45% 0.03 260);
+  --color-primary-content: oklch(98% 0 0);
+  --color-secondary: oklch(55% 0.02 260);
+  --color-secondary-content: oklch(98% 0 0);
+  --color-accent: oklch(60% 0.02 260);
+  --color-accent-content: oklch(98% 0 0);
+  --color-neutral: oklch(30% 0 0);
+  --color-neutral-content: oklch(96% 0 0);
+  /* Status: blue / green / amber / red, at their conventional roles. */
+  --color-info: oklch(62.3% 0.214 259.815);
+  --color-info-content: oklch(97% 0.01 260);
+  --color-success: oklch(59.6% 0.145 163.225);
+  --color-success-content: oklch(97% 0.02 163);
+  --color-warning: oklch(76.9% 0.188 70.08);
+  --color-warning-content: oklch(28% 0.07 70);
+  --color-error: oklch(57.7% 0.245 27.325);
+  --color-error-content: oklch(97% 0.01 27);
+  --radius-selector: 1rem;
+  --radius-field: 0.375rem;
+  --radius-box: 0.75rem;
+  --size-selector: 0.25rem;
+  --size-field: 0.25rem;
+  --border: 1px;
+  --depth: 1;
+  --noise: 0;
+}
+
+@plugin "daisyui/theme" {
+  name: 'dark';
+  prefersdark: true;
+  color-scheme: dark;
+  /* Surfaces: the same ramp inverted — not a different ramp. */
+  --color-base-100: oklch(18% 0 0);
+  --color-base-200: oklch(22% 0 0);
+  --color-base-300: oklch(28% 0 0);
+  --color-base-content: oklch(95% 0 0);
+  /* Brand: the light theme's hue, stepped for a dark surface rather than
+     flipped — a colour that clears contrast on white rarely clears it on
+     near-black. */
+  --color-primary: oklch(72% 0.04 260);
+  --color-primary-content: oklch(20% 0.01 260);
+  --color-secondary: oklch(66% 0.03 260);
+  --color-secondary-content: oklch(20% 0.01 260);
+  --color-accent: oklch(70% 0.03 260);
+  --color-accent-content: oklch(20% 0.01 260);
+  --color-neutral: oklch(26% 0 0);
+  --color-neutral-content: oklch(92% 0 0);
+  --color-info: oklch(70.7% 0.165 254.624);
+  --color-info-content: oklch(20% 0.05 255);
+  --color-success: oklch(76.5% 0.177 163.223);
+  --color-success-content: oklch(20% 0.05 163);
+  --color-warning: oklch(82.8% 0.189 84.429);
+  --color-warning-content: oklch(25% 0.07 84);
+  --color-error: oklch(70.4% 0.191 22.216);
+  --color-error-content: oklch(20% 0.05 22);
+  --radius-selector: 1rem;
+  --radius-field: 0.375rem;
+  --radius-box: 0.75rem;
+  --size-selector: 0.25rem;
+  --size-field: 0.25rem;
+  --border: 1px;
+  --depth: 1;
+  --noise: 0;
+}
+
+/* ────────────────────────────────────────────────────────────────────────────
+ * Categorical chart slots — appended block, owned by `charts/`.
+ *
+ * The one part of the palette a component reads as a raw custom property
+ * rather than through a Tailwind class, because a series colour is chosen by
+ * INDEX at runtime and Tailwind only emits classes it can see spelled out.
+ *
+ * Four slots, and **validated rather than chosen by eye**: the figures below
+ * were measured against the two themes above (`--color-base-100` is
+ * `oklch(100% 0 0)` → #ffffff in light, `oklch(18% 0 0)` → #121212 in dark),
+ * with dichromacy simulated by the Machado (2009) severity-1.0 matrices on
+ * linear sRGB and separation as Euclidean ΔE in OKLab ×100.
+ *
+ *   light — #008236 #4f39f6 #e17100 #155dfc
+ *     contrast on the surface 4.94 / 6.44 / 3.19 / 5.26 : 1
+ *     worst ADJACENT pair: normal ΔE 37.6, simulated-dichromat ΔE 8.3
+ *   dark — #00a63e #615fff #e17100 #155dfc
+ *     contrast on the surface 5.85 / 4.11 / 5.89 / 3.58 : 1
+ *     worst ADJACENT pair: normal ΔE 38.6, simulated-dichromat ΔE 9.8
+ *
+ * Every slot clears 3:1 against its own surface; every adjacent pair clears the
+ * ΔE ≥ 15 normal-vision floor and the ΔE ≥ 8 dichromat floor in both modes.
+ * The dark set is STEPPED for the dark surface, not flipped: slots 1 and 2 move
+ * one step lighter, slots 3 and 4 already sit inside both modes' bands.
+ *
+ * Three rules the slots exist to make keepable:
+ *
+ * - **Order is the safety mechanism.** The gates above are measured on ADJACENT
+ *   pairs, which is what a line, bar or stack puts side by side. Re-ordering
+ *   the slots invalidates the measurement — slots 2 and 4 (indigo and blue) are
+ *   ΔE 2.7 apart in light and 0.4 in dark under simulated dichromacy, so a
+ *   chart that puts them side by side has no colour difference for that reader
+ *   at all.
+ * - **Four is the cap, and three is the cap for a form that compares EVERY
+ *   pair at once** (a scatter, a choropleth, a pie). A fifth series is a design
+ *   problem — fold it into an "other" series, or facet — never a generated hue.
+ *   `Chart` draws a fifth in `--color-neutral` and names it in the legend
+ *   rather than inventing one. Even at three, the 1↔3 pair falls to ΔE 4.9
+ *   under protanopia, which is the reason `Chart`'s `sr-only` data table is
+ *   always in the DOM: colour is the fast path, never the only one.
+ * - **Status colours are not series colours.** `--color-success` / `-warning` /
+ *   `-error` mean a STATE, and slot 3 is deliberately amber-600 rather than the
+ *   amber-500 that IS `--color-warning`, so a series can never impersonate one.
+ *
+ * A consumer replacing the two themes above should replace these four with
+ * their own measured set, in the same order.
+ * ──────────────────────────────────────────────────────────────────────────── */
+:root {
+  /*
+   * One declaration per slot, not one per mode: `light-dark()` resolves against
+   * the `color-scheme` each daisyUI theme already sets — `light` on the `light`
+   * theme, `dark` on the `dark` one, and on whichever the OS asks for by
+   * default. Writing the dark set out a second time under `[data-theme]` and a
+   * third under `prefers-color-scheme` is how two of the three drift apart.
+   */
+  --color-chart-1: light-dark(
+    oklch(52.7% 0.154 150.069),
+    oklch(62.7% 0.194 149.214)
+  ); /* green-700 / -600 */
+  --color-chart-2: light-dark(
+    oklch(51.1% 0.262 276.966),
+    oklch(58.5% 0.233 277.117)
+  ); /* indigo-600 / -500 */
+  --color-chart-3: oklch(66.6% 0.179 58.318); /* amber-600, inside both bands */
+  --color-chart-4: oklch(54.6% 0.245 262.881); /* blue-600, inside both bands */
+}

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,25 @@
+/**
+ * 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
+ */
+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,
+};