@marianmeres/stuic 3.143.0 → 3.145.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 57 component directories
+├── components/     # 63 component directories
 ├── actions/        # 15 Svelte actions (use: directives)
 ├── attachments/    # Svelte attachments ({@attach} — preferred for new DOM helpers)
 ├── utils/          # 44 utility modules
@@ -53,6 +53,9 @@ Theme CSS files are not bundled in this package — they're provided by `@marian
 5. Create components without `unstyled`, `class`, `el` props
 6. Use `dark:` Tailwind prefix when CSS vars handle dark mode
 7. Import CSS inside components — centralize in `src/lib/index.css`
+   (**exception:** subpath-export components with optional peer deps — `MarkdownEditor`,
+   `CommentInput` — import their own `index.css` locally so their styles don't ship to
+   barrel-only consumers. Enforced by `src/lib/barrel-optional-peers.test.ts`.)
 8. Declare component tokens at `:root` that reference shared structural tokens (use fallback pattern instead)
 
 ### CSS Variable Pattern
@@ -125,7 +128,7 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 57 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 63 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [Actions](./docs/domains/actions.md) — 15 Svelte directives
 - [Attachments](./docs/domains/attachments.md) — `{@attach}` DOM helpers (preferred for new ones)

package/API.md

@@ -2178,6 +2178,7 @@ Each component defines customization tokens. Override globally in `:root {}` or
 | ------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Button             | `--stuic-button-*`              | `bg`, `text`, `border`, `ring-color`, `radius`, `padding-x-{size}`                                                                                                                                                            |
 | Switch             | `--stuic-switch-*`              | `accent`                                                                                                                                                                                                                      |
+| Slider             | `--stuic-slider-*`              | `track`, `fill`, `thumb`, `tick`, `tick-on-fill`, `thickness`, `length`, `radius`, `fill-radius`                                                                                                                              |
 | Input              | `--stuic-input-*`               | `accent`, `accent-error`                                                                                                                                                                                                      |
 | Progress           | `--stuic-progress-*`            | `bg`, `accent`                                                                                                                                                                                                                |
 | ListItemButton     | `--stuic-list-item-button-*`    | `bg`, `text`, `border`, `bg-hover`, `text-hover`                                                                                                                                                                              |

package/README.md

@@ -27,6 +27,29 @@ npm install @marianmeres/stuic
 </Modal>
 ```
 
+## Subpath exports
+
+Most of the library is on the main entry. A few things live behind subpaths:
+
+| Subpath                               | Contents                                                      |
+| ------------------------------------- | ------------------------------------------------------------- |
+| `@marianmeres/stuic`                  | Components, actions, icons, utils — everything below excepted |
+| `@marianmeres/stuic/utils`            | Utilities only, without pulling in components                 |
+| `@marianmeres/stuic/phone-validation` | Phone validation helpers                                      |
+| `@marianmeres/stuic/markdown-editor`  | `MarkdownEditor` — requires optional peer deps                |
+| `@marianmeres/stuic/comment-input`    | `CommentInput` — requires optional peer deps                  |
+
+The last two are **not** on the main entry by design: they depend on Milkdown and
+CodeMirror, which are declared as _optional_ peer dependencies. Keeping them off the
+barrel means consumers who don't use them never have to install that stack — and,
+more importantly, their builds don't fail for want of it.
+
+```ts
+import { CommentInput } from "@marianmeres/stuic/comment-input";
+```
+
+See each component's README for the peer set to install.
+
 ## Theming System
 
 STUIC uses a 4-layer CSS variable token system:
@@ -152,7 +175,7 @@ FieldInput, FieldMoney, FieldTextarea, FieldSelect, FieldCheckbox, FieldRadios,
 
 ### Buttons & Controls
 
-Button, ButtonGroupRadio, Switch, TwCheck, ListItemButton, X
+Button, ButtonGroupRadio, Switch, Slider, TwCheck, ListItemButton, X
 
 ### Feedback & Notifications
 

package/dist/components/CommentInput/CommentInput.svelte

@@ -143,6 +143,7 @@
 	import { Button } from "../Button/index.js";
 	import Thc from "../Thc/Thc.svelte";
 	import { MarkdownEditor } from "../MarkdownEditor/index.js";
+	import "./index.css";
 
 	let {
 		value = $bindable(""),

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

@@ -110,6 +110,7 @@ export interface Props extends InputWrapClassProps {
     classFooter?: string;
     style?: string;
 }
+import "./index.css";
 declare const CommentInput: import("svelte").Component<Props, {
     validate: () => ValidationResult | undefined;
     clearValidation: () => void;

package/dist/components/CommentInput/README.md

@@ -12,9 +12,14 @@ lightweight, opinionated wrapper for the common "leave a comment / reply" use
 case: a clean minimal toolbar, an avatar, a submit button, and
 ⌘/Ctrl+Enter-to-send — without you having to wire any of it up.
 
+Because it embeds `MarkdownEditor`, it is shipped as an **optional subpath export**
+(`@marianmeres/stuic/comment-input`), separate from the main barrel — so the heavy
+editor dependencies never reach consumers who don't use it. Importing it from
+`@marianmeres/stuic` will not work.
+
 ```svelte
 <script>
-	import { CommentInput } from "@marianmeres/stuic";
+	import { CommentInput } from "@marianmeres/stuic/comment-input";
 
 	let value = $state("");
 
@@ -49,6 +54,11 @@ This is the same peer set as `MarkdownEditor` — see its README for the
 authoritative list. If they aren't installed, the surface stays empty and a
 console error explains why.
 
+> **CSS is imported locally** by this component, not via the central
+> `src/lib/index.css`. Deliberate deviation from the usual STUIC convention,
+> required so these styles ship only to subpath users. Same as `MarkdownEditor`;
+> see `index.css` for the rationale.
+
 ## Toolbar
 
 `toolbar` accepts `true` (the default), `false` (hidden), or an ordered

package/dist/components/CommentInput/index.css

@@ -1,6 +1,19 @@
 /******************************************************************************
   CommentInput
 
+  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: because it embeds `MarkdownEditor`
+  it is an OPTIONAL subpath export (`@marianmeres/stuic/comment-input`) kept off
+  the main barrel, so the heavy Milkdown/CodeMirror peers never reach consumers
+  who don't use it. Centralizing its CSS would ship these styles to every
+  consumer anyway. Instead `CommentInput.svelte` imports THIS file locally; the
+  package's `sideEffects` glob (all css files) keeps the import for real users.
+
+  `MarkdownEditor/index.css` arrives on its own — `MarkdownEditor.svelte`
+  imports it locally too — so do NOT `@import` it here (it would double-inject
+  for anyone using both components).
+
   A GitHub-style comment composer built on top of `MarkdownEditor` (a rich
   WYSIWYG / source surface) with an avatar gutter and a submit/cancel footer.
 

package/dist/components/Slider/README.md

@@ -0,0 +1,205 @@
+# Slider
+
+A fancy `input[type="range"]` wrap — a pill-shaped track that fills with the value, with
+an optional icon-capable thumb riding the fill edge (think iOS volume control). Supports
+horizontal and vertical orientation, pointer dragging with step snapping, native keyboard
+interaction, tick marks, a floating value label, form participation, and validation.
+
+Not a replacement for `FieldInput type="range"` — this is the special-case "fancy"
+variant for custom UI (volume/brightness controls, dashboards, media players).
+
+## Props
+
+| Prop            | Type                                                               | Default        | Description                                                                                                                                      |
+| --------------- | ------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `value`         | `number`                                                           | `min`          | Current value (bindable; non-finite / out-of-range / off-grid writes are normalized back)                                                        |
+| `min`           | `number`                                                           | `0`            | Minimum value                                                                                                                                    |
+| `max`           | `number`                                                           | `100`          | Maximum value                                                                                                                                    |
+| `step`          | `number \| "any"`                                                  | `1`            | Snap increment (`"any"` or non-positive = continuous)                                                                                            |
+| `orientation`   | `"horizontal" \| "vertical"`                                       | `"horizontal"` | Slider direction (vertical fills bottom-up)                                                                                                      |
+| `size`          | `"sm" \| "md" \| "lg" \| string`                                   | `"md"`         | Cross-axis thickness preset                                                                                                                      |
+| `intent`        | `"primary" \| "accent" \| "success" \| "warning" \| "destructive"` | -              | Semantic fill color                                                                                                                              |
+| `thumb`         | `boolean \| Snippet<[SliderRenderCtx]>`                            | `true`         | `false` hides the thumb (fill-only look), snippet renders inside thumb                                                                           |
+| `thumbPosition` | `"value" \| "start"`                                               | `"value"`      | `"value"` rides the fill edge; `"start"` pins it to the left/bottom so only the bar moves (true iOS volume look)                                 |
+| `fillRounded`   | `boolean`                                                          | `false`        | Round the fill's leading edge ("pill inside a pill")                                                                                             |
+| `ticks`         | `boolean \| number[]`                                              | -              | `true` = tick at every `step` (positive numeric step only; skipped above 101 auto ticks — pass an array), array = ticks at given in-range values |
+| `valueLabel`    | `Snippet<[SliderRenderCtx]>`                                       | -              | Floating label at the current value along the track                                                                                              |
+| `disabled`      | `boolean`                                                          | `false`        | Disable interaction                                                                                                                              |
+| `label`         | `string`                                                           | -              | Screen reader label for the underlying input                                                                                                     |
+| `id`            | `string`                                                           | -              | Id for the underlying input (enables `<label for>` association)                                                                                  |
+| `name`          | `string`                                                           | -              | Form field name for the hidden range input                                                                                                       |
+| `required`      | `boolean`                                                          | `false`        | Forwarded to the input; per HTML spec inert on range inputs (use `validate.customValidator` for custom rules)                                    |
+| `oninput`       | `(value: number) => void`                                          | -              | Fires on every value change (drag, keyboard)                                                                                                     |
+| `onchange`      | `(value: number) => void`                                          | -              | Fires when a change is committed (drag release, keyboard)                                                                                        |
+| `validate`      | `boolean \| ValidateOptions`                                       | -              | Enable validation (stuic validate action)                                                                                                        |
+| `unstyled`      | `boolean`                                                          | `false`        | Skip all default styling                                                                                                                         |
+| `class`         | `string`                                                           | -              | Classes for the root element                                                                                                                     |
+| `trackClass`    | `string`                                                           | -              | Classes for the track (pill background)                                                                                                          |
+| `fillClass`     | `string`                                                           | -              | Classes for the fill (value indicator)                                                                                                           |
+| `thumbClass`    | `string`                                                           | -              | Classes for the thumb                                                                                                                            |
+| `tickClass`     | `string`                                                           | -              | Classes for each tick mark                                                                                                                       |
+| `valueClass`    | `string`                                                           | -              | Classes for the value label wrapper                                                                                                              |
+| `el`            | `HTMLDivElement`                                                   | -              | Root element reference (bindable)                                                                                                                |
+| `inputEl`       | `HTMLInputElement`                                                 | -              | Hidden range input reference (bindable)                                                                                                          |
+
+`SliderRenderCtx` (passed to the `thumb` and `valueLabel` snippets):
+`{ value: number; ratio: number /* 0..1 */; percent: number /* 0..100 */; dragging: boolean }`
+
+Remaining props are spread onto the root `<div>`.
+
+### Exported methods (via component instance binding)
+
+| Method                  | Description                         |
+| ----------------------- | ----------------------------------- |
+| `validate()`            | Trigger validation now              |
+| `clearValidation()`     | Clear the current validation result |
+| `getValidation()`       | Read the current validation result  |
+| `focus()`               | Focus the underlying range input    |
+| `scrollIntoView(opts?)` | Scroll the slider into view         |
+
+## Usage
+
+### Basic
+
+```svelte
+<script lang="ts">
+	import { Slider } from "@marianmeres/stuic";
+
+	let volume = $state(30);
+</script>
+
+<Slider bind:value={volume} />
+```
+
+### Vertical volume control (thumb rides the fill edge)
+
+```svelte
+<Slider
+	orientation="vertical"
+	size="lg"
+	bind:value={volume}
+	style="--stuic-slider-length: 10rem; --stuic-slider-fill: white; --stuic-slider-track: rgb(255 255 255 / .25);"
+>
+	{#snippet thumb()}
+		{@html iconVolume({ size: 16 })}
+	{/snippet}
+</Slider>
+```
+
+### Fill-only (no thumb)
+
+```svelte
+<Slider thumb={false} bind:value={brightness} />
+```
+
+### True iOS volume: fixed icon at the start, only the bar moves
+
+```svelte
+<!-- bare icon (no knob): drop the thumb's own background/shadow -->
+<Slider
+	orientation="vertical"
+	thumbPosition="start"
+	fillRounded
+	thumbClass="bg-transparent shadow-none"
+	bind:value={volume}
+>
+	{#snippet thumb()}
+		{@html iconVolume({ size: 18 })}
+	{/snippet}
+</Slider>
+
+<!-- or keep the white knob pinned at the bottom -->
+<Slider orientation="vertical" thumbPosition="start" bind:value={volume}>
+	{#snippet thumb()}
+		{@html iconVolume({ size: 16 })}
+	{/snippet}
+</Slider>
+```
+
+With `thumbPosition="start"` the thumb is decorative (`pointer-events: none`) and the
+value maps linearly across the full track — there is no thumb-travel inset.
+
+### Steps and ticks
+
+```svelte
+<Slider min={0} max={10} step={1} ticks bind:value={rating} />
+<Slider min={0} max={100} step={0.5} ticks={[0, 25, 50, 75, 100]} />
+```
+
+### Value label
+
+```svelte
+<Slider bind:value={percent}>
+	{#snippet valueLabel({ value })}
+		{value}%
+	{/snippet}
+</Slider>
+```
+
+### Continuous (no snapping)
+
+```svelte
+<Slider step="any" bind:value={gain} />
+```
+
+### In a form
+
+```svelte
+<form onsubmit={...}>
+	<Slider name="volume" bind:value={volume} />
+</form>
+```
+
+## Interaction
+
+- **Pointer**: press anywhere on the track to jump the value there, then drag. Grabbing
+  the thumb itself does not jump (drag continues from the grab point).
+- **Keyboard**: focus and use Arrow keys / PageUp / PageDown / Home / End — native
+  `input[type=range]` behavior (the real input is visually hidden but focusable).
+- **Vertical**: bottom is `min`, top is `max`; ArrowUp increases.
+- **RTL**: horizontal sliders flip automatically (logical CSS properties + pointer math).
+- **Commit semantics**: `oninput` fires only on actual value changes; `onchange` only
+  when a drag/keypress committed a _different_ value (native-faithful — a no-move tap
+  fires neither).
+- **Off-grid max**: when `max` is not on the step grid (e.g. `min=0 max=95 step=10`),
+  the largest reachable value is the last grid point (`90`), matching native range
+  sanitization.
+
+## Caveats
+
+- **Cross-axis sizing**: size the thickness via `size` presets or
+  `--stuic-slider-thickness` — not via `h-*`/`w-*` utility classes. The pointer math
+  and the CSS thumb positioning both derive from the thickness; a utility class
+  resizes the box without updating `--_thickness`, misaligning them. (Main-axis
+  length via a class — e.g. `class="h-40"` on a vertical slider — is fine.)
+- **Root pointer handlers are reserved**: `onpointerdown/move/up/cancel` are excluded
+  from `Props` (the drag machinery owns them). Wrap the slider if you need them.
+- **Touch**: the slider claims the whole touch gesture (`touch-action: none`) —
+  a touch starting on it adjusts the value and never scrolls the page.
+- **The wrapper is not the control**: props spread onto the root `<div>` — including
+  `aria-*` and `onfocus`/`onblur` — never reach the underlying `<input type="range">`
+  and are inert for assistive tech. Use `label` (→ `aria-label`) and `id` (→ `<label for>`);
+  for anything else, bind `inputEl` and wire it imperatively.
+
+## CSS Variables
+
+| Variable                          | Default                    | Description                       |
+| --------------------------------- | -------------------------- | --------------------------------- |
+| `--stuic-slider-track`            | `--stuic-color-muted`      | Track (pill background) color     |
+| `--stuic-slider-fill`             | `--stuic-color-primary`    | Fill color                        |
+| `--stuic-slider-thumb`            | `--color-white`            | Thumb background                  |
+| `--stuic-slider-thumb-foreground` | `--stuic-color-foreground` | Thumb content color               |
+| `--stuic-slider-tick`             | foreground 25% mix         | Tick mark color (over the track)  |
+| `--stuic-slider-tick-on-fill`     | background 55% mix         | Tick mark color (over the fill)   |
+| `--stuic-slider-ring-width`       | `4px`                      | Focus ring width                  |
+| `--stuic-slider-ring-color`       | `--stuic-color-ring`       | Focus ring color                  |
+| `--stuic-slider-thickness`        | `2rem` (`sm` 1.25, `lg` 3) | Cross-axis size                   |
+| `--stuic-slider-length`           | `10rem`                    | Main-axis size                    |
+| `--stuic-slider-thumb-inset`      | `3px`                      | Gap between thumb and track edge  |
+| `--stuic-slider-radius`           | `9999px`                   | Track corner radius               |
+| `--stuic-slider-fill-radius`      | `--stuic-slider-radius`    | Fill radius (when `fillRounded`)  |
+| `--stuic-slider-thumb-radius`     | `9999px`                   | Thumb corner radius               |
+| `--stuic-slider-thumb-shadow`     | `--stuic-shadow`           | Thumb shadow                      |
+| `--stuic-slider-tick-size`        | `4px`                      | Tick mark diameter                |
+| `--stuic-slider-value-gap`        | `0.375rem`                 | Gap between track and value label |
+| `--stuic-slider-transition`       | `--stuic-transition`       | Fill/thumb movement transition    |