@marianmeres/stuic 3.167.0 → 3.169.0

package/docs/domains/components.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-64 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
+73 Svelte 5 component directories with consistent API patterns. All use runes-based reactivity.
 
 ## Component Categories
 
@@ -20,22 +20,27 @@
 | SlidingPanels            | Panel transitions                                  |
 | TabbedMenu               | Tab navigation                                     |
 | Nav                      | Navigation wrapper                                 |
+| Breadcrumbs              | Breadcrumb trail (collapse + JSON-LD helpers)      |
 | WithSidePanel            | Two-column layout with collapsible/resizable panel |
 
 ### Interactive
 
-| Component            | Purpose                                     |
-| -------------------- | ------------------------------------------- |
-| Button               | Actions with intent/variant/size            |
-| ButtonGroupRadio     | Toggle group (single selection)             |
-| Switch               | Boolean toggle                              |
-| Slider               | Fancy range input (fill + optional thumb)   |
-| TwCheck              | Styled checkbox/radio                       |
-| DropdownMenu         | Popover menu                                |
-| CommandMenu          | Command palette (keyboard-driven)           |
-| TypeaheadInput       | Autocomplete input                          |
-| ColorScheme          | Dark/light mode management with persistence |
-| HoverExpandableWidth | Width-expanding container on hover          |
+| Component            | Purpose                                                                                   |
+| -------------------- | ----------------------------------------------------------------------------------------- |
+| Button               | Actions with intent/variant/size                                                          |
+| CopyButton           | Click-to-copy Button with copied/error feedback; `copyToClipboard()` util for code        |
+| ButtonGroupRadio     | Toggle group (single selection)                                                           |
+| Switch               | Boolean toggle                                                                            |
+| Slider               | Fancy range input (fill + optional thumb)                                                 |
+| TwCheck              | Styled checkbox/radio                                                                     |
+| DropdownMenu         | Popover menu                                                                              |
+| ContextMenu          | Right-click / long-press menu at the cursor (the DropdownMenu engine + trigger semantics) |
+| CommandMenu          | Command palette (keyboard-driven)                                                         |
+| Pagination           | Standalone pager: compact prev/next or windowed page numbers; DataTable-compatible        |
+| Stepper              | Numbered step indicator for wizard/checkout flows; optional click navigation              |
+| TypeaheadInput       | Autocomplete input                                                                        |
+| ColorScheme          | Dark/light mode management with persistence                                               |
+| HoverExpandableWidth | Width-expanding container on hover                                                        |
 
 ### Feedback
 
@@ -83,6 +88,7 @@
 | AnimatedElipsis     | Loading dots animation                                                                               |
 | IconSwap            | N-state visibility swap with opacity transitions (e.g. hamburger/X)                                  |
 | DataTable           | Responsive data table with paging, selection, batch actions                                          |
+| EmptyState          | Icon + title + description + CTA placeholder for empty lists/tables/search results                   |
 | ThemePreview        | Theme color swatches                                                                                 |
 | AssetsPreview       | Modal-based asset/file preview with zoom, pan, swipe, area clicking                                  |
 | AssetsPreviewInline | Always-visible (non-modal) asset preview with same feature set                                       |
@@ -93,6 +99,8 @@
 | Separator           | Horizontal/vertical separator line                                                                   |
 | Thc                 | Flexible renderer for text, HTML, components, or snippets                                            |
 | Card                | Flexible card with image, title, footer; vertical/horizontal layout                                  |
+| Stat                | KPI/stat card: label + value + delta with trend arrow and semantic coloring                          |
+| TrendChart          | Svelte wrapper for `@marianmeres/trend-chart` (subpath-only: `@marianmeres/stuic/trend-chart`)       |
 | Tree                | Hierarchical tree view with keyboard nav and drag-and-drop                                           |
 | X                   | Styled close/multiply SVG icon                                                                       |
 | ImageCycler         | Auto-cycling image carousel with fade transitions and preloading                                     |
@@ -788,6 +796,48 @@ Components use private CSS vars (`--_*`) set by intent/variant:
 
 ---
 
+## Breadcrumbs
+
+Breadcrumb navigation trail — `<nav aria-label>` + ordered list (the WAI-ARIA APG pattern) with the last crumb marked `aria-current="page"`. Long trails optionally collapse their middle into an expandable ellipsis button (`maxItems` + `itemsBeforeCollapse`/`itemsAfterCollapse`; a new `items` array re-collapses). Ships schema.org `BreadcrumbList` JSON-LD helpers for SEO — usable standalone in `<svelte:head>` or rendered inline by the component via the `jsonLd` prop.
+
+### Exports
+
+| Export                     | Kind      | Description                                                       |
+| -------------------------- | --------- | ----------------------------------------------------------------- |
+| `Breadcrumbs`              | component | Main component                                                    |
+| `BreadcrumbsProps`         | type      | Props type                                                        |
+| `BreadcrumbItem`           | type      | `{ label: string; href?: string }`                                |
+| `breadcrumbsJsonLd`        | function  | Builds the schema.org `BreadcrumbList` object                     |
+| `breadcrumbsJsonLdScript`  | function  | Full `<script type="application/ld+json">` string, `{@html}`-safe |
+| `BreadcrumbsJsonLdOptions` | type      | `{ baseUrl? }` — resolves relative hrefs to absolute URLs         |
+| `BreadcrumbListJsonLd`     | type      | The JSON-LD output shape (+ `BreadcrumbListItemJsonLd`)           |
+| `createBreadcrumbsT`       | function  | Builds the `t` prop from a (partial) message catalog              |
+| `BREADCRUMBS_MESSAGES_EN`  | constant  | Built-in English catalog (also the fallback)                      |
+| `BREADCRUMBS_MESSAGES_SK`  | constant  | Bundled Slovak catalog (opt-in)                                   |
+| `BreadcrumbsMessageKey`    | type      | Message key union                                                 |
+| `BreadcrumbsMessages`      | type      | One locale's catalog                                              |
+
+### Key Props
+
+| Prop                                       | Type                     | Default | Description                                           |
+| ------------------------------------------ | ------------------------ | ------- | ----------------------------------------------------- |
+| `items`                                    | `BreadcrumbItem[]`       | —       | The trail, first-to-current; last item = current page |
+| `separator`                                | `string`                 | `"/"`   | Separator text (or the `renderSeparator` snippet)     |
+| `maxItems`                                 | `number`                 | `0`     | Collapse when longer than this; `0` never collapses   |
+| `itemsBeforeCollapse`/`itemsAfterCollapse` | `number`                 | `1`/`1` | Crumbs kept visible around the ellipsis               |
+| `jsonLd`                                   | `boolean \| { baseUrl }` | `false` | Render `BreadcrumbList` JSON-LD along with the trail  |
+| `t`                                        | `TranslateFn`            | English | i18n (`createBreadcrumbsT`)                           |
+
+Snippets: `renderItem` (`(item, index, isLast)`), `renderSeparator`. Class slots: `class`, `classItem`, `classLink`, `classCurrent`, `classSeparator`. Data attributes: `data-current` on the current `<li>`.
+
+### CSS Tokens
+
+Prefix: `--stuic-breadcrumbs-*`
+
+`gap`, `font-size`, `text`, `text-hover`, `text-current`, `font-weight-current`, `separator-text`, `transition` (falls back to `--stuic-transition`)
+
+---
+
 ## Card
 
 Flexible, responsive card for displaying content in a contained box. Supports images (top or side), titles, descriptions, footers, and interactive states.
@@ -824,6 +874,223 @@ Prefix: `--stuic-card-*`
 
 ---
 
+## ContextMenu
+
+Right-click / long-press triggered menu positioned at the pointer. Wraps content into a context target area: `contextmenu` (right-click), long-press (touch/pen, via the `longPress` attachment), or Shift+F10 / the menu key open the menu anchored at the interaction point (an invisible 0×0 fixed anchor the underlying DropdownMenu positions against). The menu panel **is** a `DropdownMenu` — item model, keyboard navigation, search, overflow handling, and theming (`--stuic-dropdown-menu-*`) all come from there.
+
+### Exports
+
+| Export                     | Kind      | Description                                          |
+| -------------------------- | --------- | ---------------------------------------------------- |
+| `ContextMenu`              | component | Main component                                       |
+| `ContextMenuProps`         | type      | Props type                                           |
+| `ContextMenuItem`          | type      | Alias of `DropdownMenuItem` (full item model)        |
+| `ContextMenuActionItem`    | type      | Alias of `DropdownMenuActionItem`                    |
+| `ContextMenuPosition`      | type      | Alias of `DropdownMenuPosition`                      |
+| `ContextMenuSearchConfig`  | type      | Alias of `DropdownMenuSearchConfig`                  |
+| `createContextMenuT`       | function  | Builds the `t` prop from a (partial) message catalog |
+| `CONTEXT_MENU_MESSAGES_EN` | constant  | Built-in English catalog (also the fallback)         |
+| `CONTEXT_MENU_MESSAGES_SK` | constant  | Bundled Slovak catalog (opt-in)                      |
+| `ContextMenuMessageKey`    | type      | Message key union                                    |
+| `ContextMenuMessages`      | type      | One locale's catalog                                 |
+
+### Key Props
+
+| Prop        | Type                  | Default               | Description                                                                             |
+| ----------- | --------------------- | --------------------- | --------------------------------------------------------------------------------------- |
+| `items`     | `ContextMenuItem[]`   | —                     | Menu items (the DropdownMenu item model)                                                |
+| `children`  | `Snippet`             | —                     | The right-clickable / long-pressable target area content                                |
+| `isOpen`    | `boolean`             | `false`               | Bindable; programmatic `true` anchors at the target area                                |
+| `disabled`  | `boolean`             | `false`               | Triggers inert — the native context menu works again                                    |
+| `longPress` | `number \| false`     | `500`                 | Long-press duration ms (touch/pen); `false` disables                                    |
+| `position`  | `ContextMenuPosition` | `"bottom-span-right"` | Placement relative to the pointer (below-right = native convention); flips at the edges |
+| `t`         | `TranslateFn`         | English               | Localizes the sr-only menu label (`createContextMenuT`)                                 |
+
+Pass-throughs to the underlying DropdownMenu: `offset` (default `"0px"`), `maxHeight`, `closeOnSelect`, `closeOnClickOutside`, `closeOnEscape`, `search`, `showBackdrop`, `scrollbarGutter`, `noScrollLock`, `forceFallback`, `onOpen`/`onClose`/`onSelect`, and the menu part classes (`classDropdown`, `classItem`, …). Class slots on the wrapper: `class`. Bindables: `el` (target wrapper), `dropdownEl` (open menu). Data attributes on the wrapper: `data-open` (while open), `data-longpress` (long-press enabled — drives the CSS suppressing the platform's own long-press behaviors).
+
+### CSS Tokens
+
+None of its own — theme the menu via `--stuic-dropdown-menu-*`. `.stuic-context-menu` is the target area hook; `[data-open]` styles it while the menu is open.
+
+---
+
+## CopyButton
+
+Click-to-copy button with built-in feedback. It IS a `Button` (same intent/variant/size/theming) that writes `text` to the clipboard on click, flips to a "copied" state for `feedbackDuration` ms (check icon, `success` intent, localized label / accessible name, visually hidden `role="status"` announcement) and reports the outcome via `onCopied` / `onError`. A failed write (clipboard unavailable, denied, getter threw) is the "error" state (× icon, `destructive` intent). Icon-only by default; `label` (THC or `true`) adds a visible label. The write itself is the `copyToClipboard()` util (async Clipboard API + `execCommand("copy")` fallback), usable without the button.
+
+### Exports
+
+| Export                       | Kind      | Description                                                   |
+| ---------------------------- | --------- | ------------------------------------------------------------- |
+| `CopyButton`                 | component | Main component                                                |
+| `CopyButtonProps`            | type      | Props type                                                    |
+| `CopyButtonState`            | type      | `"idle" \| "copied" \| "error"`                               |
+| `CopyButtonText`             | type      | `string \| (() => string \| Promise<string>)`                 |
+| `createCopyButtonT`          | function  | Builds the `t` prop from a (partial) message catalog          |
+| `COPY_BUTTON_MESSAGES_EN`    | constant  | Built-in English catalog (also the fallback)                  |
+| `COPY_BUTTON_MESSAGES_SK`    | constant  | Bundled Slovak catalog (opt-in)                               |
+| `CopyButtonMessageKey`       | type      | Message key union (`copy`, `copied`, `copy_failed`)           |
+| `CopyButtonMessages`         | type      | One locale's catalog                                          |
+| `copyToClipboard`            | function  | (utils) `(text) => Promise<void>` — the write the button does |
+| `isCopyToClipboardSupported` | function  | (utils) any clipboard write path available? (false in SSR)    |
+
+### Key Props
+
+| Prop                                | Type                                        | Default            | Description                                                              |
+| ----------------------------------- | ------------------------------------------- | ------------------ | ------------------------------------------------------------------------ |
+| `text`                              | `string \| () => string \| Promise<string>` | required           | What to copy; a getter is resolved on click                              |
+| `label`                             | `THC \| true`                               | —                  | Visible label; omit for icon-only (aria-label from `t`), `true` = "Copy" |
+| `labelCopied`                       | `THC`                                       | `t("copied")`      | Label while copied                                                       |
+| `labelError`                        | `THC`                                       | `t("copy_failed")` | Label while in error                                                     |
+| `icon` / `iconCopied` / `iconError` | `string \| false`                           | copy / check / ×   | Icons per state; `icon={false}` = no icons                               |
+| `feedbackDuration`                  | `number`                                    | `2000`             | ms the feedback stays; `0` = until the next click                        |
+| `intentCopied`                      | `IntentColorKey \| false`                   | `"success"`        | Intent while copied; `false` keeps `intent`                              |
+| `intentError`                       | `IntentColorKey \| false`                   | `"destructive"`    | Intent while in error; `false` keeps `intent`                            |
+| `onCopied`                          | `(text) => void`                            | —                  | After a successful copy                                                  |
+| `onError`                           | `(error) => void`                           | —                  | After a failed copy                                                      |
+| `onclick`                           | `(e) => void`                               | —                  | Runs first; `preventDefault()` skips the copy                            |
+| `tooltip`                           | `boolean \| string \| TooltipConfig`        | icon-only: `true`  | State-aware tooltip ("Copy" → "Copied"), live while showing              |
+| `variant` / `size`                  | Button's                                    | `"ghost"` / `"sm"` | Defaults differ from Button                                              |
+| `t`                                 | `TranslateFn`                               | English            | i18n                                                                     |
+
+Snippets: `children` (full content override, receives `{ state, copied }`). Class slots: `class`, `classIcon`, `classLabel`. `data-state` is kept even when `unstyled` (it is behavior, not styling).
+
+### CSS Tokens
+
+Prefix: `--stuic-copy-button-*` (the surface themes via `--stuic-button-*`)
+
+`icon-size`, `icon-pop-duration`, `icon-pop-scale`
+
+---
+
+## EmptyState
+
+Icon + title + description + CTA placeholder for empty lists, tables, and search results. Centered, non-interactive; the CTA area is a snippet filled with consumer `Button`s/links. Pairs naturally with `DataTable` ("no rows") and search UIs ("no results").
+
+### Exports
+
+| Export              | Kind      | Description                        |
+| ------------------- | --------- | ---------------------------------- |
+| `EmptyState`        | component | Main component                     |
+| `EmptyStateProps`   | type      | Props type                         |
+| `EmptyStateVariant` | type      | `"plain" \| "outline" \| "dashed"` |
+| `EmptyStateSize`    | type      | `"sm" \| "md" \| "lg"`             |
+
+### Key Props
+
+| Prop          | Type                               | Default   | Description                                       |
+| ------------- | ---------------------------------- | --------- | ------------------------------------------------- |
+| `icon`        | `THC`                              | —         | Icon area content (e.g. `{ html: iconSearch() }`) |
+| `title`       | `THC`                              | —         | Title headline                                    |
+| `description` | `THC`                              | —         | Supporting text below the title                   |
+| `variant`     | `"plain" \| "outline" \| "dashed"` | `"plain"` | Container treatment (bordered box or none)        |
+| `size`        | `"sm" \| "md" \| "lg"`             | `"md"`    | Padding, icon and typography scale                |
+
+Snippets: `actions` (CTA area), `renderIcon` (icon override), `children` (full layout override). Class slots: `class`, `classIcon`, `classTitle`, `classDescription`, `classActions`. No implicit ARIA role — pass `role="status"` when the empty state replaces content dynamically.
+
+### CSS Tokens
+
+Prefix: `--stuic-empty-state-*`
+
+`gap`, `padding-{sm,md,lg}`, `icon-size-{sm,md,lg}`, `icon-text`, `icon-opacity`, `icon-margin-bottom`, `title-font-size-{sm,md,lg}`, `title-font-weight`, `title-text`, `description-font-size-{sm,md,lg}`, `description-text`, `description-max-width`, `actions-gap`, `actions-margin-top`, `bg`, `border`, `border-width`, `radius`
+
+Falls back to shared structural tokens `--stuic-border-width` and `--stuic-radius-container` (outline/dashed variants).
+
+---
+
+## Pagination
+
+Standalone pagination for lists, search results, and custom views. Two variants: `compact` (prev / "Page X of Y" / next — the pager `DataTable` renders internally) and `numbers` (windowed page-number buttons with ellipsis gaps). Consumes the same `PagingCalcResult` from `@marianmeres/paging-store` that `DataTable` does, so one paging store can feed both (`<DataTable showPager={false} />` + standalone `Pagination`); `total`/`limit`/`offset` convenience props compute paging internally for quick standalone use.
+
+### Exports
+
+| Export                   | Kind      | Description                                          |
+| ------------------------ | --------- | ---------------------------------------------------- |
+| `Pagination`             | component | Main component                                       |
+| `PaginationProps`        | type      | Props type                                           |
+| `PaginationVariant`      | type      | `"compact" \| "numbers"`                             |
+| `paginationRange`        | function  | Pure windowing helper behind the numbers variant     |
+| `PaginationRangeItem`    | type      | `number \| "ellipsis"`                               |
+| `PaginationRangeOptions` | type      | `{ siblingCount?, boundaryCount? }`                  |
+| `createPaginationT`      | function  | Builds the `t` prop from a (partial) message catalog |
+| `PAGINATION_MESSAGES_EN` | constant  | Built-in English catalog (also the fallback)         |
+| `PAGINATION_MESSAGES_SK` | constant  | Bundled Slovak catalog (opt-in)                      |
+| `PaginationMessageKey`   | type      | Message key union                                    |
+| `PaginationMessages`     | type      | One locale's catalog                                 |
+
+### Key Props
+
+| Prop                     | Type                     | Default     | Description                                                                  |
+| ------------------------ | ------------------------ | ----------- | ---------------------------------------------------------------------------- |
+| `paging`                 | `PagingCalcResult`       | —           | Paging metadata (`DataTable`-compatible); wins over `total`/`limit`/`offset` |
+| `total`/`limit`/`offset` | `number`                 | —/`10`/`0`  | Convenience alternative to `paging` (computed via `calculatePaging`)         |
+| `onPageChange`           | `(offset, page) => void` | —           | New offset (`DataTable`'s signature as first arg) + 1-based target page      |
+| `variant`                | `"compact" \| "numbers"` | `"compact"` | Prev/info/next, or windowed page-number buttons                              |
+| `siblingCount`           | `number`                 | `1`         | Numbers: pages always shown around the current page                          |
+| `boundaryCount`          | `number`                 | `1`         | Numbers: pages always shown at the start and end                             |
+| `showFirstLast`          | `boolean`                | `false`     | First/last jump buttons (« »)                                                |
+| `showInfo`               | `boolean`                | per variant | "Page X of Y" info (`true` for compact, `false` for numbers)                 |
+| `hideSinglePage`         | `boolean`                | `true`      | Render nothing when there is at most one page (the `DataTable` rule)         |
+| `disabled`               | `boolean`                | `false`     | Disable all controls (e.g. while loading)                                    |
+| `size`                   | `ButtonSize`             | `"sm"`      | Size preset of the inner Buttons                                             |
+| `t`                      | `TranslateFn`            | English     | i18n; `previous_page`/`next_page`/`page_x_of_y` keys match `DataTable`'s     |
+
+Snippets: `renderInfo` (info override, receives `PagingCalcResult`). Class slots: `class`, `classButton`, `classButtonCurrent`, `classInfo`. Renders a `<nav aria-label>` landmark; the current page button carries `aria-current="page"`.
+
+### CSS Tokens
+
+Prefix: `--stuic-pagination-*`
+
+`gap`, `button-min-width`, `info-font-size`, `info-text`, `ellipsis-text`
+
+`button-min-width` defaults to `--stuic-button-min-height-sm` so single-character buttons stay square-ish.
+
+---
+
+## Stepper
+
+Numbered multi-step progress header for wizard/checkout flows. Accessible `<nav>` landmark with an ordered list: completed steps get a check mark and filled connector, the current step is highlighted (`aria-current="step"`), upcoming steps stay muted; per-step `error` renders a destructive "×". Display-only by default; `onSelect` makes steps clickable (completed-only by default, `clickable="all"` for free navigation). `current` is a zero-based index — exactly `@marianmeres/wizard`'s `step.index` (`steps.length` = all done).
+
+### Exports
+
+| Export                 | Kind      | Description                                          |
+| ---------------------- | --------- | ---------------------------------------------------- |
+| `Stepper`              | component | Main component                                       |
+| `StepperProps`         | type      | Props type                                           |
+| `StepperStep`          | type      | `{ label, description?, icon?, error?, disabled? }`  |
+| `StepperStepState`     | type      | `"completed" \| "current" \| "upcoming"`             |
+| `StepperOrientation`   | type      | `"horizontal" \| "vertical"`                         |
+| `StepperLabelPosition` | type      | `"end" \| "below"`                                   |
+| `StepperClickable`     | type      | `"none" \| "completed" \| "all"`                     |
+| `createStepperT`       | function  | Builds the `t` prop from a (partial) message catalog |
+| `STEPPER_MESSAGES_EN`  | constant  | Built-in English catalog (also the fallback)         |
+| `STEPPER_MESSAGES_SK`  | constant  | Bundled Slovak catalog (opt-in)                      |
+| `StepperMessageKey`    | type      | Message key union                                    |
+| `StepperMessages`      | type      | One locale's catalog                                 |
+
+### Key Props
+
+| Prop            | Type                             | Default        | Description                                                                          |
+| --------------- | -------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
+| `steps`         | `(StepperStep \| string)[]`      | required       | The steps; plain strings are shorthand for `{ label }` (labels/descriptions are THC) |
+| `current`       | `number`                         | `0`            | Zero-based current step index; `steps.length` = all completed; clamped               |
+| `onSelect`      | `(index, step) => void`          | —              | Navigation callback; when present, steps render as buttons                           |
+| `clickable`     | `"none" \| "completed" \| "all"` | `"completed"`  | Click policy (the current step never fires)                                          |
+| `orientation`   | `"horizontal" \| "vertical"`     | `"horizontal"` | Layout direction                                                                     |
+| `labelPosition` | `"end" \| "below"`               | `"end"`        | Horizontal only: labels beside the indicator or centered below it                    |
+| `disabled`      | `boolean`                        | `false`        | Disable all interaction                                                              |
+| `t`             | `TranslateFn`                    | English        | i18n: landmark label + sr-only step announcements ("Step X of Y", Completed/Failed)  |
+
+Snippets: `renderIndicator` (bubble override, receives `{ index, step, state }`). Class slots: `class`, `classStep`, `classIndicator`, `classLabel`, `classDescription`, `classConnector`. Indicator bubbles are `aria-hidden` — visually hidden text announces position + state instead.
+
+### CSS Tokens
+
+Prefix: `--stuic-stepper-*`
+
+`gap`, `gap-vertical`, `connector-min-length`, `indicator-size`, `indicator-border-width`, `indicator-radius`, `indicator-font-size`, `indicator-font-weight`, `indicator-{bg,text,border}{,-current,-completed,-error}`, `label-font-size`, `label-font-weight`, `label-text{,-current,-completed,-error}`, `description-font-size`, `description-text`, `connector-thickness`, `connector-bg{,-completed}`, `ring-width`, `ring-color`, `opacity-disabled`
+
+---
+
 ## CronInput
 
 Cron expression editor with preset selector, manual 5-field editor, raw expression input, human-readable descriptions, and next-run calculation.

package/docs/domains/utils.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-44 utility modules for common tasks. Organized by category.
+45 utility modules for common tasks. Organized by category.
 
 ---
 
@@ -35,11 +35,13 @@ theme.value = "dark";
 
 ## DOM Utilities
 
-| Util               | Purpose                  |
-| ------------------ | ------------------------ |
-| `qsa`              | querySelectorAll wrapper |
-| `bodyScrollLocker` | Lock/unlock body scroll  |
-| `getId`            | Generate unique IDs      |
+| Util                         | Purpose                                                          |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `qsa`                        | querySelectorAll wrapper                                         |
+| `bodyScrollLocker`           | Lock/unlock body scroll                                          |
+| `getId`                      | Generate unique IDs                                              |
+| `copyToClipboard`            | Write text to the clipboard (async API + `execCommand` fallback) |
+| `isCopyToClipboardSupported` | Whether any clipboard write path exists (false during SSR)       |
 
 ---
 

package/docs/maybe-todo.md

@@ -0,0 +1,132 @@
+# Maybe-todo: missing component candidates
+
+An analysis of typical (widely used) UI/UX components that stuic does not yet ship,
+compared against the usual baseline of comparable libraries (shadcn, Bits UI, Melt,
+Skeleton, Flowbite, DaisyUI). Snapshot as of 2026-09. Nothing here is committed work —
+it is a menu to pick from.
+
+## Already covered under non-obvious names (not gaps)
+
+Checked first, to avoid false positives:
+
+- **Tooltip / Popover** — actions (`actions/tooltip`, `actions/popover`), not components
+- **Toast** — `Notifications` (notifications stack)
+- **Badge** — `Pill`
+- **Toggle group** — `ButtonGroupRadio`
+- **Sheet** — `Drawer`
+- **Alert / callout** — `DismissibleMessage`
+- **Table pagination** — built into `DataTable` (`showpager`)
+- **Multi-select / tags input** — `FieldOptions` (async `getOptions` search, typeahead,
+  `cardinality`, option groups, `allowUnknown` for ad-hoc values, `ordered` for manual
+  arrangement, `chips` for the inline tag form factor). See the note at the bottom on
+  the inline-chip presentation.
+- **File dropzone** — `actions/file-dropzone` + `FieldFile` / `FieldAssets`
+
+## Tier 1 — staples nearly every comparable library ships
+
+1. **Date picker / Calendar** — the single biggest gap. No calendar grid, no date-range
+   picker anywhere in the lib (only native `type="date"` via `FieldInput`).
+   `@marianmeres/calendar-utils` already does the date math, so this is mostly UI work.
+   A `FieldDate` / `FieldDateRange` would slot naturally next to `FieldMoney` /
+   `FieldPhoneNumber`. Most work of anything on this list, but also the absence
+   consumers will actually notice.
+2. ~~**Breadcrumbs**~~ — ✅ shipped (see `src/lib/components/Breadcrumbs/`):
+   APG nav/ol trail, collapsible long trails, schema.org `BreadcrumbList` JSON-LD
+   helpers (`breadcrumbsJsonLd` / `breadcrumbsJsonLdScript` + inline `jsonLd` prop).
+3. ~~**Pagination (standalone)**~~ — ✅ shipped (see `src/lib/components/Pagination/`):
+   compact (the `DataTable` pager) + windowed page-numbers variants, consumes the same
+   `PagingCalcResult` as `DataTable` so one paging store can feed both.
+
+## Tier 2 — very common, clear use cases
+
+4. ~~**Stepper / step indicator**~~ — ✅ shipped (see `src/lib/components/Stepper/`):
+   numbered step indicator with completed/current/upcoming/error states, optional
+   click navigation, horizontal (labels end/below) + vertical orientations; `current`
+   is a zero-based index matching `@marianmeres/wizard`'s `step.index`.
+5. ~~**ContextMenu**~~ — ✅ shipped (see `src/lib/components/ContextMenu/`): wraps the
+   `DropdownMenu` engine behind context-menu trigger semantics — positions at the
+   cursor via a 0×0 fixed anchor, `contextmenu` event, long-press on touch/pen (new
+   reusable `longPress` attachment), Shift+F10 / menu key.
+6. ~~**EmptyState**~~ — ✅ shipped (see `src/lib/components/EmptyState/`): icon +
+   title + description + CTA placeholder for empty lists/tables/search results.
+7. **Rating (stars)** — display + input variants. `FieldLikeButton` is adjacent but not
+   this.
+
+## Tier 3 — common, but judge by actual app needs
+
+8. **SplitPane / resizable panels** — general two-pane draggable splitter
+   (horizontal/vertical, min/max, persisted size). `actions/resizable-width`,
+   `WithSidePanel`, and `persistent-state` already provide the pieces.
+9. **Range slider (dual-thumb)** — `Slider` is deliberately single-value; a min/max
+   range variant (price filters etc.) is a recurring ask.
+10. **Timeline / activity feed** — vertical event list with markers; common in
+    admin/audit views.
+11. ~~**Stat / KPI card**~~ — ✅ shipped (see `src/lib/components/Stat/`): label +
+    value + delta with trend arrow and semantic coloring (`trendIntent` for
+    down-is-good metrics), hint, corner icon, footer/sparkline area.
+12. ~~**CopyButton**~~ — ✅ shipped (see `src/lib/components/CopyButton/`): a
+    `Button` that copies `text` (string or sync/async getter) with copied/error
+    feedback (icon + intent swap, localized label/name, sr live announcement),
+    `onCopied` / `onError` callbacks; the write is the reusable `copyToClipboard()`
+    util (async Clipboard API + `execCommand` fallback) in `utils/`.
+13. **ColorPicker** — beyond native `type="color"`: swatch palette + custom input.
+    Given stuic's theming/design-tokens focus, a swatch picker would be on-brand.
+
+## Deliberately out of scope (or close enough to covered)
+
+- scroll-area (native is fine)
+- virtual list / infinite scroll (belongs closer to `@marianmeres/paging-store`)
+- lightbox (`AssetsPreview` territory)
+- menubar / mega-menu (`Nav` + `DropdownMenu` compose it)
+- password strength meter, toolbar
+
+## Note: inline-chip presentation of FieldOptions
+
+Initially listed as a Tier-1 "tags input" gap; retracted — `FieldOptions` covers the
+capability. What stuic lacked was the _inline chip form factor_. That splits into two
+separable halves, and only the second one has a mobile problem:
+
+1. ~~**Chips as the field's display**~~ — ✅ shipped (`FieldOptions` `chips` prop, see
+   `Input/README.md`): the closed field shows the selection as removable `Pill` chips
+   (per-chip ×, focus kept in the field, `change` dispatched so validation re-runs) plus a
+   trailing button that opens the existing modal; the empty part of the row opens it too.
+   Internally a `FieldLikeButton` sibling (`Input/_internal/FieldLikeChips.svelte`) — the
+   chips carry their own buttons, so they cannot live inside the `<button>` trigger. Works
+   on every device; the one touch concern (× target size) is handled with a padded hit
+   area on `pointer: coarse`.
+2. **Inline adding** (type into the field, suggestions, Enter commits) — not built. This is
+   where every mobile hazard lives (see the reality check below). The design to argue for,
+   if ever built:
+   - a presentation mode of `FieldOptions`, not a new component — the selection model
+     (`ItemCollection`, `cardinality`, `allowUnknown`, `ordered`) is already there. But the
+     engine is currently bound to the modal lifecycle (hydrate on open, fetch while
+     visible, clear on submit) and would need extracting into a shared `.svelte.ts` class
+     rather than more branches in the 1250-line file; that is the real cost
+   - no floating listbox popover: reuse the existing `typeahead` action (ghost text, Tab
+     accepts, Enter commits, Backspace at position 0 removes the last chip via
+     `onDeleteRequest`). No anchored dropdown means the soft-keyboard hazard disappears by
+     construction; the modal stays the browse path via the trailing button. A real list
+     popover can be added later behind the same prop if ghost text proves insufficient
+   - gate it on the `md` breakpoint (`breakpoint.svelte.ts`), not on `DevicePointer` —
+     that util uses `any-pointer`, so a touchscreen laptop counts as coarse and an iPad
+     with a trackpad as fine; the breakpoint is deterministic and testable in the browser
+     suite. If pointer detection is wanted as well, it should be the primary
+     `pointer: coarse`
+   - below the breakpoint, delegate to the modal — i.e. exactly the shipped `chips` mode
+
+Mobile reality check for the inline variant, if it were ever made touch-capable
+instead of delegating:
+
+- a floating anchor-positioned dropdown is the first casualty of the on-screen
+  keyboard (clipped/covered/scrolled); the mobile-viable idiom is a full-width
+  suggestion list in document flow under the field (cf. Gmail's To: field), sized via
+  the `visualViewport` API
+- chip removal: tiny × falls below ~44px touch targets, and backspace-to-delete is
+  unreliable (Android IMEs report `keyCode 229`); workable patterns are
+  tap-to-select-then-delete or generously padded delete zones, detected via
+  `beforeinput`/`input` rather than `keydown`
+- committing unknown values: on separator via `input` event or on blur, not keydown
+
+Once all three adaptations are made, the small-screen result is behaviorally ~90% of
+what the `FieldOptions` modal already does — which is why delegating below a
+breakpoint is the pragmatic answer.

package/docs/upgrading.md

@@ -99,6 +99,12 @@ interface InputWrapClassProps {
 
 Previously most fields only accepted 5–7 of these. You can now pass any of them to **FieldInput, FieldTextarea, FieldSelect, FieldSwitch, FieldFile, FieldLikeButton, FieldObject, FieldOptions, FieldAssets, FieldPhoneNumber, FieldInputLocalized, FieldKeyValues** uniformly. `FieldCheckbox` and `FieldRadios` use bespoke layouts and keep their own narrower class-prop surface.
 
+### FieldOptions
+
+`chips` prop (opt-in): the closed field shows the selection as inline, removable `Pill` chips plus a trailing button that opens the usual modal. Removing a chip writes `value` and fires `onChange` without the modal. Companion props `classChip` / `chipIntent`; `renderValue` is ignored in this mode. The default rendering is unchanged.
+
+`Pill` gained `dismissLabel` — the accessible name of its × button (default `"Dismiss"`).
+
 ### Checkout
 
 New util:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.167.0",
+	"version": "3.169.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -60,6 +60,11 @@
 			"types": "./dist/components/CommentInput/index.d.ts",
 			"svelte": "./dist/components/CommentInput/index.js",
 			"default": "./dist/components/CommentInput/index.js"
+		},
+		"./trend-chart": {
+			"types": "./dist/components/TrendChart/index.d.ts",
+			"svelte": "./dist/components/TrendChart/index.js",
+			"default": "./dist/components/TrendChart/index.js"
 		}
 	},
 	"peerDependencies": {
@@ -69,6 +74,7 @@
 		"@codemirror/language-data": "^6.0.0",
 		"@codemirror/state": "^6.0.0",
 		"@codemirror/view": "^6.0.0",
+		"@marianmeres/trend-chart": "^0.5.0",
 		"@milkdown/core": "^7.0.0",
 		"@milkdown/ctx": "^7.0.0",
 		"@milkdown/plugin-history": "^7.0.0",
@@ -99,6 +105,9 @@
 		"@codemirror/view": {
 			"optional": true
 		},
+		"@marianmeres/trend-chart": {
+			"optional": true
+		},
 		"@milkdown/core": {
 			"optional": true
 		},
@@ -136,6 +145,7 @@
 		"@codemirror/view": "^6.43.9",
 		"@eslint/js": "^9.39.5",
 		"@marianmeres/random-human-readable": "^1.10.2",
+		"@marianmeres/trend-chart": "^0.5.0",
 		"@milkdown/core": "^7.22.1",
 		"@milkdown/ctx": "^7.22.1",
 		"@milkdown/plugin-history": "^7.22.1",