@marianmeres/stuic 3.167.0 → 3.168.0

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) |