@marianmeres/stuic 3.167.0 → 3.169.0

package/dist/components/TrendChart/TrendChart.svelte

@@ -0,0 +1,114 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+	import type {
+		TrendChart as TrendChartInstance,
+		TrendChartOptions,
+		TrendData,
+	} from "@marianmeres/trend-chart";
+
+	export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+		/**
+		 * The series: `DataPoint[]` or plain `number[]` shorthand (index becomes x).
+		 * Reactive — the chart updates in place (keeping pan/zoom state) when it changes.
+		 */
+		data: TrendData;
+		/**
+		 * `@marianmeres/trend-chart` options, passed through. Reactive. When `sparkline`
+		 * is set, these are merged OVER the sparkline preset (so any preset key can be
+		 * overridden back).
+		 */
+		options?: TrendChartOptions;
+		/**
+		 * Preset for the axis-less, non-interactive mini chart look:
+		 * no axes/grid/pan/zoom/points. Also switches the default height.
+		 */
+		sparkline?: boolean;
+		/**
+		 * Bindable underlying `TrendChart` instance for the imperative API
+		 * (`setDomainX`, `resetDomain`, `getDomainX`, ...). `undefined` during SSR
+		 * and before mount.
+		 */
+		chart?: TrendChartInstance;
+		/** Skip all default styling (incl. the default height — size it yourself) */
+		unstyled?: boolean;
+		/** Additional CSS classes */
+		class?: string;
+		/** Bindable element reference (the chart's container) */
+		el?: HTMLElement;
+	}
+</script>
+
+<script lang="ts">
+	import { untrack } from "svelte";
+	import { TrendChart as TrendChartClass } from "@marianmeres/trend-chart";
+	import { twMerge } from "../../utils/tw-merge.js";
+	import "./index.css";
+
+	const SPARKLINE_PRESET: Partial<TrendChartOptions> = {
+		xAxis: false,
+		yAxis: false,
+		grid: false,
+		pan: false,
+		zoom: false,
+		points: "none",
+	};
+
+	let {
+		data,
+		options,
+		sparkline = false,
+		chart = $bindable(),
+		unstyled = false,
+		class: classProp,
+		el = $bindable(),
+		...rest
+	}: Props = $props();
+
+	let _class = $derived(unstyled ? classProp : twMerge("stuic-trend-chart", classProp));
+
+	let _options: TrendChartOptions = $derived({
+		...(sparkline ? SPARKLINE_PRESET : {}),
+		...options,
+	});
+
+	// Hand the library plain (non-proxied) data; reading the snapshot also makes
+	// deep mutations of a $state-backed series reactive, not just reassignments.
+	let _data = $derived($state.snapshot(data) as TrendData);
+
+	// The internal wiring must not run through `el`/`chart`: those are write-out
+	// mirrors a parent (or test harness) may overwrite as plain props at any time.
+	let _container = $state<HTMLElement>();
+	let _chart = $state<TrendChartInstance>();
+
+	// Create once per container element; option/data changes below patch the
+	// existing instance in place (preserving pan/zoom state) instead of rebuilding.
+	$effect(() => {
+		if (!_container) return;
+		const instance = untrack(() => new TrendChartClass(_container!, _data, _options));
+		_chart = instance;
+		el = _container;
+		chart = instance;
+		return () => {
+			instance.destroy();
+			_chart = undefined;
+			chart = undefined;
+		};
+	});
+
+	$effect(() => {
+		const d = _data;
+		untrack(() => _chart)?.update(d);
+	});
+
+	$effect(() => {
+		const o = _options;
+		untrack(() => _chart)?.setOptions(o);
+	});
+</script>
+
+<div
+	bind:this={_container}
+	class={_class}
+	data-sparkline={!unstyled && sparkline ? "" : undefined}
+	{...rest}
+></div>

package/dist/components/TrendChart/TrendChart.svelte.d.ts

@@ -0,0 +1,36 @@
+import type { HTMLAttributes } from "svelte/elements";
+import type { TrendChart as TrendChartInstance, TrendChartOptions, TrendData } from "@marianmeres/trend-chart";
+export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * The series: `DataPoint[]` or plain `number[]` shorthand (index becomes x).
+     * Reactive — the chart updates in place (keeping pan/zoom state) when it changes.
+     */
+    data: TrendData;
+    /**
+     * `@marianmeres/trend-chart` options, passed through. Reactive. When `sparkline`
+     * is set, these are merged OVER the sparkline preset (so any preset key can be
+     * overridden back).
+     */
+    options?: TrendChartOptions;
+    /**
+     * Preset for the axis-less, non-interactive mini chart look:
+     * no axes/grid/pan/zoom/points. Also switches the default height.
+     */
+    sparkline?: boolean;
+    /**
+     * Bindable underlying `TrendChart` instance for the imperative API
+     * (`setDomainX`, `resetDomain`, `getDomainX`, ...). `undefined` during SSR
+     * and before mount.
+     */
+    chart?: TrendChartInstance;
+    /** Skip all default styling (incl. the default height — size it yourself) */
+    unstyled?: boolean;
+    /** Additional CSS classes */
+    class?: string;
+    /** Bindable element reference (the chart's container) */
+    el?: HTMLElement;
+}
+import "./index.css";
+declare const TrendChart: import("svelte").Component<Props, {}, "el" | "chart">;
+type TrendChart = ReturnType<typeof TrendChart>;
+export default TrendChart;

package/dist/components/TrendChart/index.css

@@ -0,0 +1,51 @@
+/******************************************************************************
+  TrendChart
+
+  NOTE — intentional deviation from the usual STUIC CSS convention.
+  Every other component's `index.css` is `@import`-ed into the central
+  `src/lib/index.css`. This component is NOT: it is an OPTIONAL subpath export
+  (`@marianmeres/stuic/trend-chart`) kept off the main barrel so its
+  `@marianmeres/trend-chart` peer dependency stays opt-in. Centralizing its
+  CSS would ship these styles to every consumer, defeating that. Instead
+  `TrendChart.svelte` imports THIS file locally; the package's `sideEffects`
+  glob (all css files) keeps the import for real users.
+
+  Theming: the underlying chart renders its colors wrapped in
+  `var(--trend-chart-*, fallback)` (its `cssVars` option, on by default in the
+  DOM renderer). Mapping those vars to STUIC theme tokens here is what makes
+  the chart follow the active theme — dark mode included — with zero options.
+******************************************************************************/
+
+@layer components {
+	.stuic-trend-chart {
+		/* The chart measures its container — it must have a real size. */
+		width: 100%;
+		height: var(--stuic-trend-chart-height, 8rem);
+
+		/* Map the chart's own CSS hooks to STUIC theme tokens. */
+		--trend-chart-line: var(--stuic-trend-chart-line, var(--stuic-color-primary));
+		--trend-chart-fill: var(--stuic-trend-chart-fill, var(--stuic-color-primary));
+		--trend-chart-grid: var(--stuic-trend-chart-grid, var(--stuic-color-border));
+		--trend-chart-label: var(
+			--stuic-trend-chart-label,
+			var(--stuic-color-muted-foreground)
+		);
+		--trend-chart-font: var(--stuic-trend-chart-font, var(--font-sans));
+		--trend-chart-end-dot-ring: var(
+			--stuic-trend-chart-end-dot-ring,
+			var(--stuic-color-background)
+		);
+		--trend-chart-annotation: var(
+			--stuic-trend-chart-annotation,
+			var(--stuic-color-warning)
+		);
+		--trend-chart-annotation-halo: var(
+			--stuic-trend-chart-annotation-halo,
+			var(--stuic-color-background)
+		);
+	}
+
+	.stuic-trend-chart[data-sparkline] {
+		height: var(--stuic-trend-chart-height-sparkline, 2.5rem);
+	}
+}

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

@@ -0,0 +1 @@
+export { default as TrendChart, type Props as TrendChartProps, } from "./TrendChart.svelte";

package/dist/components/TrendChart/index.js

@@ -0,0 +1 @@
+export { default as TrendChart, } from "./TrendChart.svelte";

package/dist/icons/index.d.ts

@@ -22,10 +22,13 @@ export { iconLucideArrowLeft as iconArrowLeft } from "@marianmeres/icons-fns/luc
 export { iconLucideArrowRight as iconArrowRight } from "@marianmeres/icons-fns/lucide/iconLucideArrowRight.js";
 export { iconLucideArrowUp as iconArrowUp } from "@marianmeres/icons-fns/lucide/iconLucideArrowUp.js";
 export { iconLucideArrowUpToLine as iconArrowUpToLine } from "@marianmeres/icons-fns/lucide/iconLucideArrowUpToLine.js";
+export { iconLucideCopy as iconCopy } from "@marianmeres/icons-fns/lucide/iconLucideCopy.js";
 export { iconLucideDownload as iconDownload } from "@marianmeres/icons-fns/lucide/iconLucideDownload.js";
 export { iconLucideMinus as iconMinus } from "@marianmeres/icons-fns/lucide/iconLucideMinus.js";
 export { iconLucidePlus as iconPlus } from "@marianmeres/icons-fns/lucide/iconLucidePlus.js";
 export { iconLucideTrash2 as iconTrash } from "@marianmeres/icons-fns/lucide/iconLucideTrash2.js";
+export { iconLucideTrendingDown as iconTrendingDown } from "@marianmeres/icons-fns/lucide/iconLucideTrendingDown.js";
+export { iconLucideTrendingUp as iconTrendingUp } from "@marianmeres/icons-fns/lucide/iconLucideTrendingUp.js";
 export { iconLucideZoomIn as iconZoomIn } from "@marianmeres/icons-fns/lucide/iconLucideZoomIn.js";
 export { iconLucideZoomOut as iconZoomOut } from "@marianmeres/icons-fns/lucide/iconLucideZoomOut.js";
 export { iconLucideCheck as iconCheck } from "@marianmeres/icons-fns/lucide/iconLucideCheck.js";
@@ -40,6 +43,7 @@ export { iconLucideEllipsisVertical as iconEllipsisVertical } from "@marianmeres
 export { iconLucideGrip as iconGrip } from "@marianmeres/icons-fns/lucide/iconLucideGrip.js";
 export { iconLucideGripHorizontal as iconGripHorizontal } from "@marianmeres/icons-fns/lucide/iconLucideGripHorizontal.js";
 export { iconLucideGripVertical as iconGripVertical } from "@marianmeres/icons-fns/lucide/iconLucideGripVertical.js";
+export { iconLucideInbox as iconInbox } from "@marianmeres/icons-fns/lucide/iconLucideInbox.js";
 export { iconLucideLanguages as iconLanguages } from "@marianmeres/icons-fns/lucide/iconLucideLanguages.js";
 export { iconLucideList as iconList } from "@marianmeres/icons-fns/lucide/iconLucideList.js";
 export { iconLucideLogOut as iconLogOut } from "@marianmeres/icons-fns/lucide/iconLucideLogOut.js";

package/dist/icons/index.js

@@ -26,10 +26,13 @@ export { iconLucideArrowLeft as iconArrowLeft } from "@marianmeres/icons-fns/luc
 export { iconLucideArrowRight as iconArrowRight } from "@marianmeres/icons-fns/lucide/iconLucideArrowRight.js";
 export { iconLucideArrowUp as iconArrowUp } from "@marianmeres/icons-fns/lucide/iconLucideArrowUp.js";
 export { iconLucideArrowUpToLine as iconArrowUpToLine } from "@marianmeres/icons-fns/lucide/iconLucideArrowUpToLine.js";
+export { iconLucideCopy as iconCopy } from "@marianmeres/icons-fns/lucide/iconLucideCopy.js";
 export { iconLucideDownload as iconDownload } from "@marianmeres/icons-fns/lucide/iconLucideDownload.js";
 export { iconLucideMinus as iconMinus } from "@marianmeres/icons-fns/lucide/iconLucideMinus.js";
 export { iconLucidePlus as iconPlus } from "@marianmeres/icons-fns/lucide/iconLucidePlus.js";
 export { iconLucideTrash2 as iconTrash } from "@marianmeres/icons-fns/lucide/iconLucideTrash2.js";
+export { iconLucideTrendingDown as iconTrendingDown } from "@marianmeres/icons-fns/lucide/iconLucideTrendingDown.js";
+export { iconLucideTrendingUp as iconTrendingUp } from "@marianmeres/icons-fns/lucide/iconLucideTrendingUp.js";
 export { iconLucideZoomIn as iconZoomIn } from "@marianmeres/icons-fns/lucide/iconLucideZoomIn.js";
 export { iconLucideZoomOut as iconZoomOut } from "@marianmeres/icons-fns/lucide/iconLucideZoomOut.js";
 // UI Control Icons (Lucide)
@@ -45,6 +48,7 @@ export { iconLucideEllipsisVertical as iconEllipsisVertical } from "@marianmeres
 export { iconLucideGrip as iconGrip } from "@marianmeres/icons-fns/lucide/iconLucideGrip.js";
 export { iconLucideGripHorizontal as iconGripHorizontal } from "@marianmeres/icons-fns/lucide/iconLucideGripHorizontal.js";
 export { iconLucideGripVertical as iconGripVertical } from "@marianmeres/icons-fns/lucide/iconLucideGripVertical.js";
+export { iconLucideInbox as iconInbox } from "@marianmeres/icons-fns/lucide/iconLucideInbox.js";
 export { iconLucideLanguages as iconLanguages } from "@marianmeres/icons-fns/lucide/iconLucideLanguages.js";
 export { iconLucideList as iconList } from "@marianmeres/icons-fns/lucide/iconLucideList.js";
 export { iconLucideLogOut as iconLogOut } from "@marianmeres/icons-fns/lucide/iconLucideLogOut.js";

package/dist/index.css

@@ -60,6 +60,7 @@ In practice:
 @import "./components/Avatar/index.css";
 @import "./components/Backdrop/index.css";
 @import "./components/Book/index.css";
+@import "./components/Breadcrumbs/index.css";
 @import "./components/Button/index.css";
 @import "./components/ButtonGroupRadio/index.css";
 @import "./components/Collapsible/index.css";
@@ -75,11 +76,14 @@ In practice:
    MarkdownEditor's. It is a subpath-export component and imports its own CSS
    locally (see components/CommentInput/index.css). Do not re-add. */
 @import "./components/ContactUsForm/index.css";
+@import "./components/ContextMenu/index.css";
+@import "./components/CopyButton/index.css";
 @import "./components/CronInput/index.css";
 @import "./components/DataTable/index.css";
 @import "./components/DismissibleMessage/index.css";
 @import "./components/DropdownMenu/index.css";
 @import "./components/EmailVerifyForm/index.css";
+@import "./components/EmptyState/index.css";
 @import "./components/FieldsBuilder/index.css";
 @import "./components/Float/index.css";
 @import "./components/H/index.css";
@@ -94,6 +98,7 @@ In practice:
 @import "./components/Nav/index.css";
 @import "./components/Notifications/index.css";
 @import "./components/OtpInput/index.css";
+@import "./components/Pagination/index.css";
 @import "./components/Pill/index.css";
 @import "./components/PricingTable/index.css";
 @import "./components/Progress/index.css";
@@ -102,6 +107,8 @@ In practice:
 @import "./components/Slider/index.css";
 @import "./components/Spinner/index.css";
 @import "./components/SplitButton/index.css";
+@import "./components/Stat/index.css";
+@import "./components/Stepper/index.css";
 @import "./components/Switch/index.css";
 @import "./components/TabbedMenu/index.css";
 @import "./components/ThemePreview/index.css";

package/dist/index.d.ts

@@ -29,6 +29,7 @@ export * from "./components/AssetsPreview/index.js";
 export * from "./components/Avatar/index.js";
 export * from "./components/Backdrop/index.js";
 export * from "./components/Book/index.js";
+export * from "./components/Breadcrumbs/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";
 export * from "./components/Cart/index.js";
@@ -40,12 +41,15 @@ export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
 export * from "./components/ContactUsForm/index.js";
+export * from "./components/ContextMenu/index.js";
+export * from "./components/CopyButton/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";
 export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/EmailVerifyForm/index.js";
+export * from "./components/EmptyState/index.js";
 export * from "./components/FieldsBuilder/index.js";
 export * from "./components/Float/index.js";
 export * from "./components/H/index.js";
@@ -64,6 +68,7 @@ export * from "./components/ModalDialog/index.js";
 export * from "./components/Nav/index.js";
 export * from "./components/Notifications/index.js";
 export * from "./components/OtpInput/index.js";
+export * from "./components/Pagination/index.js";
 export * from "./components/Pill/index.js";
 export * from "./components/PricingTable/index.js";
 export * from "./components/Progress/index.js";
@@ -73,6 +78,8 @@ export * from "./components/Slider/index.js";
 export * from "./components/SlidingPanels/index.js";
 export * from "./components/Spinner/index.js";
 export * from "./components/SplitButton/index.js";
+export * from "./components/Stat/index.js";
+export * from "./components/Stepper/index.js";
 export * from "./components/Switch/index.js";
 export * from "./components/TabbedMenu/index.js";
 export * from "./components/Thc/index.js";

package/dist/index.js

@@ -30,6 +30,7 @@ export * from "./components/AssetsPreview/index.js";
 export * from "./components/Avatar/index.js";
 export * from "./components/Backdrop/index.js";
 export * from "./components/Book/index.js";
+export * from "./components/Breadcrumbs/index.js";
 export * from "./components/Button/index.js";
 export * from "./components/ButtonGroupRadio/index.js";
 export * from "./components/Cart/index.js";
@@ -46,12 +47,15 @@ export * from "./components/CommandMenu/index.js";
 // subpath export instead, mirroring `@marianmeres/stuic/markdown-editor`.
 // Guarded by src/lib/barrel-optional-peers.test.ts — do not re-add.
 export * from "./components/ContactUsForm/index.js";
+export * from "./components/ContextMenu/index.js";
+export * from "./components/CopyButton/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";
 export * from "./components/DismissibleMessage/index.js";
 export * from "./components/Drawer/index.js";
 export * from "./components/DropdownMenu/index.js";
 export * from "./components/EmailVerifyForm/index.js";
+export * from "./components/EmptyState/index.js";
 export * from "./components/FieldsBuilder/index.js";
 export * from "./components/Float/index.js";
 export * from "./components/H/index.js";
@@ -70,6 +74,7 @@ export * from "./components/ModalDialog/index.js";
 export * from "./components/Nav/index.js";
 export * from "./components/Notifications/index.js";
 export * from "./components/OtpInput/index.js";
+export * from "./components/Pagination/index.js";
 export * from "./components/Pill/index.js";
 export * from "./components/PricingTable/index.js";
 export * from "./components/Progress/index.js";
@@ -79,10 +84,17 @@ export * from "./components/Slider/index.js";
 export * from "./components/SlidingPanels/index.js";
 export * from "./components/Spinner/index.js";
 export * from "./components/SplitButton/index.js";
+export * from "./components/Stat/index.js";
+export * from "./components/Stepper/index.js";
 export * from "./components/Switch/index.js";
 export * from "./components/TabbedMenu/index.js";
 export * from "./components/Thc/index.js";
 export * from "./components/ThemePreview/index.js";
+// NOTE: TrendChart is deliberately NOT exported here. It statically imports the
+// optional @marianmeres/trend-chart peer, which would then be pulled into the
+// root entry graph of every consumer. It ships as the `@marianmeres/stuic/trend-chart`
+// subpath export instead, mirroring `@marianmeres/stuic/markdown-editor`.
+// Guarded by src/lib/barrel-optional-peers.test.ts — do not re-add.
 export * from "./components/Tree/index.js";
 export * from "./components/TwCheck/index.js";
 export * from "./components/TypeaheadInput/index.js";

package/dist/utils/copy-to-clipboard.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Copies `text` to the system clipboard.
+ *
+ * Uses the async Clipboard API (`navigator.clipboard.writeText`) and, when that is
+ * unavailable (insecure context, older browser) or rejects (permission policy,
+ * unfocused document), falls back to the legacy `document.execCommand("copy")` path
+ * via an off-screen textarea. Rejects only when both paths fail — with the async
+ * API's own error when it was the one that failed.
+ *
+ * Call it from a user gesture (a click handler): browsers gate clipboard writes on
+ * transient user activation, and Safari in particular expects the write to happen
+ * promptly after the gesture. Any async work (resolving the text) should be kept
+ * short.
+ *
+ * @param text - The text to place on the clipboard
+ * @returns Resolves once the text is on the clipboard
+ *
+ * @example
+ * ```ts
+ * import { copyToClipboard } from "@marianmeres/stuic";
+ *
+ * try {
+ *   await copyToClipboard(apiKey);
+ *   notifications.success("Copied");
+ * } catch (e) {
+ *   notifications.error("Copy failed");
+ * }
+ * ```
+ */
+export declare function copyToClipboard(text: string): Promise<void>;
+/**
+ * Whether any clipboard write path is available in the current environment:
+ * the async Clipboard API or the legacy `execCommand("copy")`. Always `false` outside
+ * a browser (SSR). Useful to decide whether to render a copy control at all.
+ *
+ * @example
+ * ```svelte
+ * {#if isCopyToClipboardSupported()}
+ *   <CopyButton text={url} />
+ * {/if}
+ * ```
+ */
+export declare function isCopyToClipboardSupported(): boolean;

package/dist/utils/copy-to-clipboard.js

@@ -0,0 +1,102 @@
+/**
+ * Copies `text` to the system clipboard.
+ *
+ * Uses the async Clipboard API (`navigator.clipboard.writeText`) and, when that is
+ * unavailable (insecure context, older browser) or rejects (permission policy,
+ * unfocused document), falls back to the legacy `document.execCommand("copy")` path
+ * via an off-screen textarea. Rejects only when both paths fail — with the async
+ * API's own error when it was the one that failed.
+ *
+ * Call it from a user gesture (a click handler): browsers gate clipboard writes on
+ * transient user activation, and Safari in particular expects the write to happen
+ * promptly after the gesture. Any async work (resolving the text) should be kept
+ * short.
+ *
+ * @param text - The text to place on the clipboard
+ * @returns Resolves once the text is on the clipboard
+ *
+ * @example
+ * ```ts
+ * import { copyToClipboard } from "@marianmeres/stuic";
+ *
+ * try {
+ *   await copyToClipboard(apiKey);
+ *   notifications.success("Copied");
+ * } catch (e) {
+ *   notifications.error("Copy failed");
+ * }
+ * ```
+ */
+export async function copyToClipboard(text) {
+    let asyncError;
+    if (typeof navigator !== "undefined" &&
+        typeof navigator.clipboard?.writeText === "function") {
+        try {
+            await navigator.clipboard.writeText(text);
+            return;
+        }
+        catch (e) {
+            asyncError = e;
+        }
+    }
+    if (!legacyCopy(text)) {
+        throw asyncError ?? new Error("Clipboard is not available");
+    }
+}
+/**
+ * Whether any clipboard write path is available in the current environment:
+ * the async Clipboard API or the legacy `execCommand("copy")`. Always `false` outside
+ * a browser (SSR). Useful to decide whether to render a copy control at all.
+ *
+ * @example
+ * ```svelte
+ * {#if isCopyToClipboardSupported()}
+ *   <CopyButton text={url} />
+ * {/if}
+ * ```
+ */
+export function isCopyToClipboardSupported() {
+    if (typeof navigator !== "undefined" &&
+        typeof navigator.clipboard?.writeText === "function") {
+        return true;
+    }
+    return (typeof document !== "undefined" &&
+        typeof document.queryCommandSupported === "function" &&
+        document.queryCommandSupported("copy"));
+}
+/** The pre-Clipboard-API path: select the text in an off-screen textarea and `copy`. */
+function legacyCopy(text) {
+    if (typeof document === "undefined" || typeof document.execCommand !== "function") {
+        return false;
+    }
+    const active = document.activeElement;
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.setAttribute("readonly", "");
+    ta.setAttribute("aria-hidden", "true");
+    ta.tabIndex = -1;
+    // off-screen and out of the way, but NOT display:none — hidden elements can't be selected
+    ta.style.position = "fixed";
+    ta.style.top = "0";
+    ta.style.left = "0";
+    ta.style.width = "1px";
+    ta.style.height = "1px";
+    ta.style.opacity = "0";
+    ta.style.pointerEvents = "none";
+    document.body.appendChild(ta);
+    ta.focus({ preventScroll: true });
+    ta.select();
+    ta.setSelectionRange(0, text.length);
+    let ok = false;
+    try {
+        ok = document.execCommand("copy");
+    }
+    catch (_e) {
+        ok = false;
+    }
+    ta.remove();
+    // the textarea stole focus — hand it back
+    if (active && typeof active.focus === "function")
+        active.focus({ preventScroll: true });
+    return ok;
+}

package/dist/utils/index.d.ts

@@ -2,6 +2,7 @@ export * from "./avatar-colors.js";
 export * from "./body-scroll-locker.js";
 export * from "./breakpoint.svelte.js";
 export * from "./colors.js";
+export * from "./copy-to-clipboard.js";
 export * from "./debounce.js";
 export * from "./design-tokens.js";
 export * from "./device-pointer.svelte.js";

package/dist/utils/index.js

@@ -2,6 +2,7 @@ export * from "./avatar-colors.js";
 export * from "./body-scroll-locker.js";
 export * from "./breakpoint.svelte.js";
 export * from "./colors.js";
+export * from "./copy-to-clipboard.js";
 export * from "./debounce.js";
 export * from "./design-tokens.js";
 export * from "./device-pointer.svelte.js";

package/docs/architecture.md

@@ -48,7 +48,7 @@ src/lib/
 │   ├── *.ts                  # Traditional actions
 │   └── index.ts              # Barrel export
 │
-├── utils/                # 44 utility modules
+├── utils/                # 45 utility modules
 │   ├── *.svelte.ts           # Reactive utilities
 │   ├── *.ts                  # Pure functions
 │   └── index.ts              # Barrel export

package/docs/domains/attachments.md

@@ -18,6 +18,7 @@ re-exported from the package root (`src/lib/index.ts`).
 | Attachment   | Purpose                                                      | File             |
 | ------------ | ------------------------------------------------------------ | ---------------- |
 | `autoHeight` | Animate a host's height to its single child's natural height | `auto-height.ts` |
+| `longPress`  | Detect a touch/pen long-press on the host (factory)          | `long-press.ts`  |
 
 ---
 
@@ -105,6 +106,41 @@ inline `height` and `overflow`):
 
 ---
 
+## `longPress`
+
+Factory returning an attachment that calls `onLongPress(pointerdownEvent)` when a primary
+touch/pen pointer stays down for `duration` ms (default 500) without moving beyond
+`moveTolerance` px (default 10). Used by `ContextMenu` for its touch trigger; reusable for
+any press-and-hold interaction.
+
+```svelte
+<script>
+	import { longPress } from "@marianmeres/stuic";
+</script>
+
+<div {@attach longPress({ onLongPress: (e) => openAt(e.clientX, e.clientY) })}>...</div>
+```
+
+Semantics worth knowing:
+
+- **Disarms itself** on pointer up/cancel, movement beyond the tolerance (a scroll), and on
+  a native `contextmenu` event on the host — Android synthesizes one on long-press by
+  itself, so a host handling `contextmenu` never gets both paths for one gesture.
+- **Swallows the follow-up click** some platforms fire when the finger lifts after a fired
+  long-press (`suppressClick: false` opts out), so it can't activate whatever sits under
+  it. The suppress window closes right after the gesture ends — a later genuine click is
+  never eaten.
+- **Does not prevent the platform's own long-press UI** — that's CSS the consumer owns on
+  the host: `-webkit-touch-callout: none` (iOS link/image callout) and `user-select: none`
+  (text-selection long-press; scope it to `@media (pointer: coarse)` to keep desktop text
+  selection working — see `ContextMenu/index.css` for the pattern).
+- `pointerTypes` defaults to `["touch", "pen"]` — mouse users have right-click.
+
+Options: `onLongPress` (required), `duration`, `moveTolerance`, `pointerTypes`,
+`suppressClick`.
+
+---
+
 ## Attachment File Pattern
 
 An attachment is a function `(node) => cleanup?`, typed `Attachment<T>` from `svelte/attachments`.
@@ -135,7 +171,8 @@ it needs `$state` / `$derived` / a nested `$effect`.
 
 ## Key Files
 
-| File                               | Purpose                     |
-| ---------------------------------- | --------------------------- |
-| src/lib/attachments/index.ts       | All attachment exports      |
-| src/lib/attachments/auto-height.ts | Height-animation attachment |
+| File                               | Purpose                        |
+| ---------------------------------- | ------------------------------ |
+| src/lib/attachments/index.ts       | All attachment exports         |
+| src/lib/attachments/auto-height.ts | Height-animation attachment    |
+| src/lib/attachments/long-press.ts  | Long-press detection (factory) |