@poodle64/ui 2026.9.6 → 2026.9.7

package/README.md

@@ -33,11 +33,15 @@ src/lib/
   utils.ts              cn() (clsx + tailwind-merge) and the shared TS helper types
   format.ts             the Australian value formatters: money, dates, percentages,
                           numbers — en-AU, AUD, Australia/Brisbane
+  telemetry.ts          browser telemetry: one initBrowserTelemetry() call, one Faro
+                          instance, one session id (see below)
   styles.css            the component stylesheet: scale keys, .ds-edge, .ds-chip/.ds-dot,
                           the dialogue-section divider rule
   components/ui/         one directory per component: the shadcn-svelte primitives
                           (bits-ui behaviour + shadcn markup/variants) and the composed
                           page-chrome components built on top of them
+  components/feedback/  ReportWidget: the fixed bottom-right "report a problem"
+                          trigger and dialogue every app mounts (see below)
 dist/                    generated by `pnpm build` (@sveltejs/package); never edit
 ```
 
@@ -1089,6 +1093,67 @@ one is bound to Xero tax codes besides. Relative time ("2 hours ago") is out
 too — it rides on `date-fns` in the one app that has it, and a display formatter
 is not worth making that a dependency of every consumer.
 
+## Browser telemetry and the feedback widget
+
+Two exports are app machinery rather than page chrome: `@poodle64/ui/telemetry`
+(Faro) and `@poodle64/ui/feedback` (`ReportWidget`). A household app mounts both
+once, in its client entry and root layout, and every app mounts the same pair.
+
+```ts
+// +layout.ts or the client entry — the browser leg only
+import { initBrowserTelemetry } from '@poodle64/ui/telemetry';
+
+initBrowserTelemetry({
+	app: 'cadmus',
+	version: APP_VERSION,
+	url: PUBLIC_FARO_URL
+});
+```
+
+`initBrowserTelemetry` is inert without a `url` — a private or unconfigured
+deployment ships no beacons and gets null from `getSessionId()`, with no branch
+at the call site. It is idempotent: a second call returns the first instance,
+so an HMR leg or a remounted layout cannot produce a second Faro global. The
+configuration is the house decision, not an app decision: session tracking on,
+the console captured nowhere (the console stays local by rule), and the
+tracing instrumentation on so every same-origin `fetch`/XHR carries a
+`traceparent` — the feedback POST and the page's server-side traces share one
+trace id. The faro packages are `dependencies`, not peers, for the same reason
+`bits-ui` is a peer: a duplicated Faro global would strand the session id the
+feedback widget reports against.
+
+`ReportWidget` is the user-facing other half: a fixed bottom-right trigger
+opening the one report dialogue — a labelled "What happened?" textarea, and a
+screenshot checkbox (on by default) that captures `document.body` with
+`html-to-image`. A capture the page cannot produce is tolerated silently: the
+report sends with a null image rather than not at all. Submitting POSTs one
+JSON body to the `endpoint` prop (default `/api/feedback`):
+
+```json
+{
+	"message": "string — the textarea, required",
+	"route": "string — location.pathname at send time",
+	"user_agent": "string — navigator.userAgent",
+	"viewport": { "width": 1024, "height": 768 },
+	"session_id": "string | null — Faro's session id",
+	"screenshot": "string | null — a PNG data URL, or null"
+}
+```
+
+That body is the interface the app's own route is written against, and
+`src/test/report-widget.test.ts` asserts it field for field. The endpoint
+answers `{ "id": "…" }`; the dialogue shows the id with a thank-you (quote it
+to follow up) and fires `onSubmitted(id)` so the app can log or route on it.
+A failure keeps the draft and offers Retry — the message the user typed is
+the hard half to reproduce, and losing it to a flaky connection would make
+the retry cost more than the first attempt.
+
+The widget lives under `components/feedback/`, not `components/ui/`: it is
+mounted by the layout, once, alongside the telemetry init — not composed into
+routes by situation, so it stands outside the situation→component registry
+for the same reason. `getSessionId()` reading null when telemetry is off is
+ordinary, not an error: the report sends with a null `session_id`.
+
 ## The gate: `ds-check-colour-surface`
 
 The package ships the gate that proves its own surface actually resolves in the

package/dist/components/feedback/index.d.ts

@@ -0,0 +1,2 @@
+import ReportWidget from './report-widget.svelte';
+export { ReportWidget, ReportWidget as default };

package/dist/components/feedback/index.js

@@ -0,0 +1,2 @@
+import ReportWidget from './report-widget.svelte';
+export { ReportWidget, ReportWidget as default };

package/dist/components/feedback/report-widget.svelte

@@ -0,0 +1,174 @@
+<script lang="ts" module>
+	// In the module script so the instance script's typed state can reference
+	// it: svelte2tsx emits a component's instance-script type declarations
+	// below its `let`s, so a type both declared and referenced there turns
+	// into "used before its declaration".
+	type WidgetState = 'idle' | 'submitting' | 'done' | 'error';
+</script>
+
+<script lang="ts">
+	import { toPng } from 'html-to-image';
+	import Check from '@lucide/svelte/icons/check';
+	import CircleAlert from '@lucide/svelte/icons/circle-alert';
+	import LoaderCircle from '@lucide/svelte/icons/loader-circle';
+	import MessageSquarePlus from '@lucide/svelte/icons/message-square-plus';
+	import AppDialog from '../ui/app-dialog/app-dialog.svelte';
+	import { Button } from '../ui/button/index.js';
+	import { Checkbox } from '../ui/checkbox/index.js';
+	import { Label } from '../ui/label/index.js';
+	import Textarea from '../ui/textarea/textarea.svelte';
+	import { getSessionId } from '../../telemetry';
+
+	// The feedback widget every household app mounts: a fixed bottom-right
+	// trigger opening the one report dialogue. It is deliberately NOT under
+	// components/ui — it is app machinery the layout mounts once (alongside
+	// initBrowserTelemetry), not page chrome a route composes from, so it does
+	// not sit in the situation→component registry either.
+
+	let {
+		/** Where the report POSTs. The app's own route, defaulting to the one every household app serves. */
+		endpoint = '/api/feedback',
+		/** Fired with the id the endpoint returned, once, on the success leg. */
+		onSubmitted
+	}: {
+		endpoint?: string;
+		onSubmitted?: (id: string) => void;
+	} = $props();
+
+	let open = $state(false);
+	let message = $state('');
+	let includeScreenshot = $state(true);
+	let phase: WidgetState = $state('idle');
+	let submittedId: string | null = $state(null);
+
+	// Instance-scoped element ids: a label's `for` has to reach its control,
+	// and a page that mounts two widgets must not cross-wire their fields.
+	const uid = Math.random().toString(36).slice(2, 10);
+	const formId = `feedback-form-${uid}`;
+	const messageId = `feedback-message-${uid}`;
+	const screenshotId = `feedback-screenshot-${uid}`;
+
+	async function submit() {
+		phase = 'submitting';
+
+		// A screenshot the page cannot produce (canvas-tainted content, a
+		// browser without the API) is tolerated silently: the report still
+		// sends, with a null image rather than no report at all.
+		let screenshot: string | null = null;
+		if (includeScreenshot) {
+			screenshot = await toPng(document.body).catch(() => null);
+		}
+
+		try {
+			const response = await fetch(endpoint, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({
+					message,
+					route: location.pathname,
+					user_agent: navigator.userAgent,
+					viewport: { width: window.innerWidth, height: window.innerHeight },
+					session_id: getSessionId(),
+					screenshot
+				})
+			});
+
+			if (!response.ok) throw new Error(`the feedback endpoint answered ${response.status}`);
+
+			const { id } = (await response.json()) as { id: string };
+			submittedId = id;
+			phase = 'done';
+			onSubmitted?.(id);
+		} catch {
+			// The draft survives the failure — the message the user typed is
+			// the hard half to reproduce, and losing it on a flaky connection
+			// would make the retry cost more than the first attempt.
+			phase = 'error';
+		}
+	}
+
+	function reset() {
+		// A sent report clears the dialogue for the next one; an abandoned
+		// draft is kept, so an accidental close is not lost work.
+		if (phase === 'done') {
+			message = '';
+			submittedId = null;
+		}
+		phase = 'idle';
+	}
+</script>
+
+<!-- The floating trigger is the same shape the context column's is: a raw
+     button in the house chrome rather than the Button primitive, because a
+     Button's padding and text rhythm are for a row of actions, not a
+     44px disc pinned over the page. -->
+<button
+	type="button"
+	onclick={() => (open = true)}
+	class="border-border bg-card text-muted-foreground hover:text-foreground ds-edge fixed right-4 bottom-[calc(1rem+env(safe-area-inset-bottom))] z-50 grid size-11 flex-none place-items-center rounded-full border transition-colors"
+	aria-label="Report a problem"
+>
+	<MessageSquarePlus class="size-4.5" />
+	<span class="sr-only">Report a problem</span>
+</button>
+
+<AppDialog
+	bind:open
+	title="Report a problem"
+	subtitle="Describe what happened and the household team will take a look."
+	size="sm"
+	onOpenChange={(next) => !next && reset()}
+>
+	{#if phase === 'done'}
+		<div class="flex flex-col items-start gap-3" data-testid="feedback-done">
+			<span class="bg-primary/15 text-primary grid size-8 place-items-center rounded-md">
+				<Check class="size-4" />
+			</span>
+			<p class="font-medium">Thank you — your report was received.</p>
+			<p class="text-muted-foreground text-sm">
+				Its reference is <span class="text-foreground font-medium" data-testid="feedback-id">{submittedId}</span
+				>. Quote it if you follow it up.
+			</p>
+		</div>
+	{:else}
+		<form id={formId} onsubmit={(e) => { e.preventDefault(); submit(); }}>
+			<div class="space-y-2">
+				<Label for={messageId}>What happened?</Label>
+				<Textarea
+					id={messageId}
+					bind:value={message}
+					placeholder="What did you see, and what did you expect?"
+				/>
+			</div>
+			<div class="mt-4 flex items-center gap-2">
+				<Checkbox id={screenshotId} bind:checked={includeScreenshot} />
+				<Label for={screenshotId}>Include a screenshot of this page</Label>
+			</div>
+			{#if phase === 'error'}
+				<p class="text-destructive mt-4 flex items-center gap-2 text-sm" role="alert" data-testid="feedback-error">
+					<CircleAlert class="size-4 flex-none" />
+					Your report could not be sent. Check your connection and try again.
+				</p>
+			{/if}
+		</form>
+	{/if}
+
+	{#snippet footer()}
+		{#if phase === 'done'}
+			<Button variant="outline" onclick={() => (open = false)}>Close</Button>
+		{:else if phase === 'error'}
+			<Button variant="outline" onclick={() => (open = false)}>Cancel</Button>
+			<Button type="submit" form={formId} disabled={!message.trim()}>Retry</Button>
+		{:else}
+			<Button variant="outline" disabled={phase === 'submitting'} onclick={() => (open = false)}>
+				Cancel
+			</Button>
+			<Button type="submit" form={formId} disabled={phase === 'submitting' || !message.trim()}>
+				{#if phase === 'submitting'}
+					<LoaderCircle class="size-4 animate-spin" />
+				{/if}
+				{phase === 'submitting' ? 'Sending…' : 'Send report'}
+			</Button>
+		{/if}
+	{/snippet}
+</AppDialog>

package/dist/components/feedback/report-widget.svelte.d.ts

@@ -0,0 +1,7 @@
+type $$ComponentProps = {
+    endpoint?: string;
+    onSubmitted?: (id: string) => void;
+};
+declare const ReportWidget: import("svelte").Component<$$ComponentProps, {}, "">;
+type ReportWidget = ReturnType<typeof ReportWidget>;
+export default ReportWidget;

package/dist/components/ui/command/command-dialog.svelte.d.ts

@@ -9,6 +9,6 @@ type $$ComponentProps = WithoutChildrenOrChild<DialogPrimitive.RootProps> & With
     showCloseButton?: boolean;
     class?: string;
 };
-declare const CommandDialog: import("svelte").Component<$$ComponentProps, {}, "ref" | "value" | "open">;
+declare const CommandDialog: import("svelte").Component<$$ComponentProps, {}, "open" | "ref" | "value">;
 type CommandDialog = ReturnType<typeof CommandDialog>;
 export default CommandDialog;

package/dist/components/ui/input-group/input-group-input.svelte.d.ts

@@ -2,7 +2,7 @@ declare const InputGroupInput: import("svelte").Component<(Omit<import("svelte/e
     type: "file";
     files?: FileList;
 } | {
-    type?: "number" | "month" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "url" | "email" | "date" | "time" | "image" | "datetime-local" | "password" | "range" | "week";
+    type?: "number" | "month" | "url" | "hidden" | "color" | "submit" | "reset" | "button" | "search" | "checkbox" | "radio" | (string & {}) | "text" | "tel" | "email" | "date" | "time" | "image" | "datetime-local" | "password" | "range" | "week";
     files?: undefined;
 })) & {
     ref?: HTMLElement | null | undefined;

package/dist/components/ui/select/select.svelte.d.ts

@@ -1,3 +1,3 @@
-declare const Select: import("svelte").Component<import("bits-ui").SelectRootPropsWithoutHTML, {}, "value" | "open">;
+declare const Select: import("svelte").Component<import("bits-ui").SelectRootPropsWithoutHTML, {}, "open" | "value">;
 type Select = ReturnType<typeof Select>;
 export default Select;

package/dist/telemetry.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Browser telemetry for a household frontend: one `initBrowserTelemetry()`
+ * call in the client entry, one Faro instance for the app's lifetime.
+ *
+ * Both faro packages are ordinary `dependencies`, not peers: telemetry is not
+ * an optional flavour a consumer chooses per route, it is part of what every
+ * household app mounts, and a duplicated faro global would strand the session
+ * id the feedback widget reports against.
+ */
+import { type Faro } from '@grafana/faro-web-sdk';
+/** What an app supplies to switch telemetry on. */
+export interface BrowserTelemetryOptions {
+    /** The app's name, as it should appear in Faro's app metadata. */
+    app: string;
+    /** The app's version — the package's own CalVer, ordinarily. */
+    version: string;
+    /**
+     * The Faro collector endpoint. Empty means "no collector configured" and
+     * the whole module stays inert rather than shipping beacons that error.
+     */
+    url: string;
+}
+/**
+ * Start browser telemetry. Returns the Faro instance, or null when there is
+ * no collector to send to — the caller has nothing to clean up in that case,
+ * because nothing was created.
+ *
+ * Idempotent: a second call returns the first instance and initialises
+ * nothing. A layout remount, a dev-mode HMR leg or two init calls racing in
+ * different modules must not produce a second Faro global (faro-core refuses
+ * a second registration outright, and the session id a second instance would
+ * hand out would not be the one the first instance's events carry).
+ */
+export declare function initBrowserTelemetry({ app, version, url }: BrowserTelemetryOptions): Faro | null;
+/**
+ * Faro's current session id, or null when telemetry is not running (no URL, or
+ * init not yet called). The null leg is ordinary, not an error: the feedback
+ * widget's `session_id` field carries it as null and the report still sends.
+ */
+export declare function getSessionId(): string | null;

package/dist/telemetry.js

@@ -0,0 +1,63 @@
+/**
+ * Browser telemetry for a household frontend: one `initBrowserTelemetry()`
+ * call in the client entry, one Faro instance for the app's lifetime.
+ *
+ * Both faro packages are ordinary `dependencies`, not peers: telemetry is not
+ * an optional flavour a consumer chooses per route, it is part of what every
+ * household app mounts, and a duplicated faro global would strand the session
+ * id the feedback widget reports against.
+ */
+import { initializeFaro, getWebInstrumentations } from '@grafana/faro-web-sdk';
+import { TracingInstrumentation } from '@grafana/faro-web-tracing';
+/** The one Faro instance this browser tab holds, once initialised. */
+let faro = null;
+/**
+ * Start browser telemetry. Returns the Faro instance, or null when there is
+ * no collector to send to — the caller has nothing to clean up in that case,
+ * because nothing was created.
+ *
+ * Idempotent: a second call returns the first instance and initialises
+ * nothing. A layout remount, a dev-mode HMR leg or two init calls racing in
+ * different modules must not produce a second Faro global (faro-core refuses
+ * a second registration outright, and the session id a second instance would
+ * hand out would not be the one the first instance's events carry).
+ */
+export function initBrowserTelemetry({ app, version, url }) {
+    // No URL, no telemetry. An app that was never told where the collector
+    // lives ships a silent no-op rather than a transport that fails on every
+    // send — the call sites never branch on this; `getSessionId()` reads the
+    // same null either way.
+    if (!url)
+        return null;
+    if (faro)
+        return faro;
+    faro = initializeFaro({
+        url,
+        app: { name: app, version },
+        // Session tracking is Faro's default too, but the feedback widget's
+        // payload carries the session id, so the guarantee is stated here
+        // rather than inherited from a default that could change upstream.
+        sessionTracking: { enabled: true },
+        instrumentations: [
+            ...getWebInstrumentations({
+                // The console stays local by rule: a household app's logs are not
+                // shipped to the collector, only errors, events and measurements.
+                captureConsole: false
+            }),
+            // W3C trace context on same-origin fetch and XHR: every request the
+            // app's own backend serves carries a `traceparent`, so a feedback
+            // report can be correlated with the server-side trace of the page
+            // it was sent from.
+            new TracingInstrumentation()
+        ]
+    });
+    return faro;
+}
+/**
+ * Faro's current session id, or null when telemetry is not running (no URL, or
+ * init not yet called). The null leg is ordinary, not an error: the feedback
+ * widget's `session_id` field carries it as null and the report still sends.
+ */
+export function getSessionId() {
+    return faro?.api.getSession()?.id ?? null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@poodle64/ui",
-	"version": "2026.9.6",
+	"version": "2026.9.7",
 	"description": "Household shared component layer: shadcn-svelte primitives (bits-ui) plus the composed page chrome every app builds its routes from, restyled by each app's @poodle64/design-tokens alias layer. One fix reaches every app.",
 	"type": "module",
 	"license": "MIT",
@@ -29,6 +29,14 @@
 			"types": "./dist/format.d.ts",
 			"svelte": "./dist/format.js"
 		},
+		"./telemetry": {
+			"types": "./dist/telemetry.d.ts",
+			"svelte": "./dist/telemetry.js"
+		},
+		"./feedback": {
+			"types": "./dist/components/feedback/index.d.ts",
+			"svelte": "./dist/components/feedback/index.js"
+		},
 		"./*": {
 			"types": "./dist/components/ui/*/index.d.ts",
 			"svelte": "./dist/components/ui/*/index.js"
@@ -60,10 +68,13 @@
 		}
 	},
 	"dependencies": {
+		"@grafana/faro-web-sdk": "^2.11.0",
+		"@grafana/faro-web-tracing": "^2.11.0",
 		"@jsonforms/core": "^3.8.0",
 		"@lucide/svelte": "^1.25.0",
 		"@tanstack/table-core": "^8.21.3",
 		"clsx": "^2.1.1",
+		"html-to-image": "^1.11.13",
 		"tailwind-merge": "^3.6.0",
 		"tailwind-variants": "^3.2.2",
 		"tw-animate-css": "^1.4.0"

package/registry/component-map.json

@@ -1,7 +1,7 @@
 {
 	"meta": {
 		"package": "@poodle64/ui",
-		"version": "2026.9.6",
+		"version": "2026.9.7",
 		"generatedBy": "scripts/generate-registry.mjs",
 		"source": "scripts/situations.json + package source (DO NOT EDIT the outputs by hand)",
 		"componentCount": 56,

package/registry/component-map.md

@@ -1,7 +1,7 @@
 # @poodle64/ui — situation → component map
 
 <!-- GENERATED by scripts/generate-registry.mjs from scripts/situations.json + package source. DO NOT EDIT. -->
-Generated from `@poodle64/ui@2026.9.6`. 56 components, 15 situations.
+Generated from `@poodle64/ui@2026.9.7`. 56 components, 15 situations.
 
 **Read this before writing a `<div>`.** Find the SITUATION you are in below, then compose the component named for it — do not hand-build it from raw `Card` or utility classes. Import is `import { Name } from '<import path>'`. Props marked `?` are optional. This map is the retrieval step the [`frontend-design` skill] makes mandatory; the [CHI 2026 study] measured composing-from-a-registry at 95% design-system compliance against 71% for writing the CSS from a prose style guide.