@marianmeres/stuic 3.172.0 → 3.174.0

package/AGENTS.md

@@ -23,7 +23,7 @@
 
 ```
 src/lib/
-├── components/     # 75 component directories
+├── components/     # 78 component directories
 ├── actions/        # 16 Svelte actions (use: directives)
 ├── attachments/    # Svelte attachments ({@attach} — preferred for new DOM helpers)
 ├── utils/          # 55 utility modules (48 on the barrel)
@@ -101,12 +101,27 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 }
 ```
 
-**Element vs Container classification:**
+**Element vs Button vs Container classification:**
 
 - **Element** (`--stuic-radius`): inputs, badges, list items, checkboxes, tabs — interactive controls
-- **Button** (`--stuic-radius-button`): buttons, button groups — allows rounded buttons even with flat elements
+- **Button** (`--stuic-radius-button`): buttons, split buttons, button groups — allows rounded buttons even with flat elements
 - **Container** (`--stuic-radius-container`): cards, modals, dropdowns, notifications, accordions — content wrappers
 
+**Tier tokens vs component tokens — the mirrored names.** Tier tokens (the table above) are
+`--stuic-{property}-{tier}` and ARE declared in `src/lib/index.css`. Component tokens are the
+transposition, `--stuic-{component}-{property}`, and are NEVER declared — they exist only as
+the first argument of a `var()` fallback:
+
+```css
+border-radius: var(--stuic-button-radius, var(--stuic-radius-button));
+/*                 ^ component token (3)  ^ tier token (2) */
+```
+
+So `--stuic-radius-button` applies to Button, SplitButton and ButtonGroupRadio, while
+`--stuic-button-radius` applies to Button alone. Same for `--stuic-border-width-button` vs
+`--stuic-button-border-width`. `button` is the only tier name that is also a component name,
+so it is the only confusable pair — do not "fix" one into the other.
+
 ---
 
 ## Before Making Changes
@@ -131,7 +146,7 @@ Global tokens that control cross-component visual properties. Defined in `src/li
 
 ### Domain Docs
 
-- [Components](./docs/domains/components.md) — 75 component directories, Props pattern, snippets
+- [Components](./docs/domains/components.md) — 78 component directories, Props pattern, snippets
 - [Theming](./docs/domains/theming.md) — CSS tokens, dark mode, themes
 - [CSS presets](./docs/domains/css-presets.md) — ratio-locked frame (letterbox), safe-area, scrollbar
 - [Actions](./docs/domains/actions.md) — 16 Svelte directives

package/API.md

@@ -114,6 +114,25 @@ Expandable sections with exclusive or multi-open modes.
 
 Responsive two-column layout with collapsible side panel, resizable width, and mobile-aware slide transitions.
 
+#### `SplitPane`
+
+Two panes with a draggable, keyboard-operable separator (ARIA window splitter) — `horizontal` (side by side, a width) or `vertical` (stacked, a height); nestable. Built on the `resizable` attachment.
+
+| Prop            | Type                         | Default        | Description                                                               |
+| --------------- | ---------------------------- | -------------- | ------------------------------------------------------------------------- |
+| `start` / `end` | `Snippet`                    | —              | The two panes' content                                                    |
+| `orientation`   | `"horizontal" \| "vertical"` | `"horizontal"` | Resize a width (side by side) or a height (stacked)                       |
+| `primary`       | `"start" \| "end"`           | `"start"`      | Which pane carries the size; the other one fills the rest                 |
+| `size`          | `number`                     | `50`           | Bindable size of the primary pane in `units`; a stored size wins on mount |
+| `units`         | `"%" \| "px"`                | `"%"`          | Of the container, or px                                                   |
+| `min` / `max`   | `number`                     | `0`            | Bounds in `units` (`0` = none)                                            |
+| `key`           | `string \| number`           | —              | Persist the size (`storage`: `"session"` default, or `"local"`)           |
+| `disabled`      | `boolean`                    | `false`        | Inert separator, layout kept                                              |
+| `label` / `t`   | `string` / `TranslateFn`     | `"Resize"`     | Accessible name of the separator (Slovak catalog bundled)                 |
+| `onResize`      | `(info) => void`             | —              | Every applied size                                                        |
+
+Imperative `reset()` restores the mount size. Class slots `startClass` / `endClass` / `separatorClass`.
+
 #### `Collapsible`
 
 Expandable/collapsible content sections.
@@ -1606,10 +1625,12 @@ Visual feedback (class toggle) on drag-over.
 
 ### `resizableWidth`
 
-Make an element's width draggable.
+Make an element's width draggable. A thin wrapper over the `resizable` attachment (`axis: "x"`, see [Attachments](#attachments)) — the handle is a keyboard-operable `role="separator"`, `min` / `max` clamp, `key` persists.
 
 ```svelte
-<div use:resizableWidth={() => ({ minWidth: 200, maxWidth: 600 })}>Resizable</div>
+<div use:resizableWidth={() => ({ initial: 300, min: 200, max: 600, key: "sidebar" })}>
+	Resizable
+</div>
 ```
 
 ### `trim`
@@ -1802,6 +1823,37 @@ When a step has `selector`, the tour uses `document.querySelector(selector)` to
 
 ---
 
+## Attachments
+
+Svelte `{@attach}` helpers — the preferred form for new DOM behavior (reactive, composable, forwardable through components). Imported from the package root like everything else.
+
+### `autoHeight`
+
+Animates the host's height to its single child's natural height (pair it with a CSS `height` transition).
+
+```svelte
+<div class="viewport" {@attach autoHeight}>
+	<div>…variable-height content…</div>
+</div>
+```
+
+### `longPress`
+
+Factory: calls `onLongPress` when a touch / pen pointer stays down for `duration` ms (default 500) without moving beyond `moveTolerance` px.
+
+```svelte
+<div {@attach longPress({ onLongPress: (e) => openAt(e.clientX, e.clientY) })}>…</div>
+```
+
+### `resizable`
+
+Factory: drag-resizable width (`axis: "x"`) or height (`axis: "y"`) with an ARIA window-splitter handle (arrows / Home / End / Enter), `min` / `max`, `px` or `%` of the parent, persisted under `key`; `handle` drives an element of your own, `onInit` hands out `set()` / `reset()`.
+
+```svelte
+<aside {@attach resizable({ initial: 300, min: 200, max: 600, key: "sidebar" })}>…</aside>
+<div {@attach resizable({ axis: "y", units: "%", initial: 40 })}>…</div>
+```
+
 ## Utilities
 
 Import from `@marianmeres/stuic`.
@@ -2327,6 +2379,8 @@ 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`                                                                                                                              |
+| RangeSlider        | `--stuic-range-slider-*`        | `track`, `fill`, `thumb`, `tick`, `tick-on-fill`, `thickness`, `length`, `radius`, `fill-radius`, `ring-width`, `ring-color`                                                                                                  |
+| SplitPane          | `--stuic-split-pane-*`          | `separator-color`, `separator-color-hover`, `separator-thickness`, `separator-hit-area`, `grip-color`, `grip-color-hover`, `grip-border-color`, `grip-length`, `grip-thickness`, `grip-radius`, `ring-color`, `transition`    |
 | 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

@@ -57,7 +57,7 @@ STUIC uses a 4-layer CSS variable token system:
 ```
 Layer 1: Theme Tokens (--stuic-color-*)
     ↓
-Layer 2: Structural Tokens (--stuic-radius, --stuic-shadow, --stuic-border-width, --stuic-transition)
+Layer 2: Structural Tokens (--stuic-radius, --stuic-radius-button, --stuic-shadow, ...)
     ↓ (used as fallback defaults)
 Layer 3: Component Tokens (--stuic-button-radius, --stuic-input-accent, etc.)
     ↓ (Tailwind utility class references)
@@ -87,16 +87,20 @@ Override shared structural tokens to change the entire library's visual characte
 /* Brutalist — sharp, flat, borderless */
 :root {
 	--stuic-radius: 0;
+	--stuic-radius-button: 0;
 	--stuic-radius-container: 0;
 	--stuic-shadow: none;
 	--stuic-shadow-hover: none;
 	--stuic-shadow-overlay: none;
 	--stuic-shadow-dialog: none;
 	--stuic-border-width: 0;
+	--stuic-border-width-button: 0;
 }
 ```
 
-Available tokens: `--stuic-radius`, `--stuic-radius-container`, `--stuic-shadow`, `--stuic-shadow-hover`, `--stuic-shadow-overlay`, `--stuic-shadow-dialog`, `--stuic-border-width`, `--stuic-transition`.
+Available tokens: `--stuic-radius`, `--stuic-radius-button`, `--stuic-radius-container`, `--stuic-shadow`, `--stuic-shadow-hover`, `--stuic-shadow-overlay`, `--stuic-shadow-dialog`, `--stuic-border-width`, `--stuic-border-width-button`, `--stuic-transition`.
+
+Radius and border-width come in three tiers — elements, **buttons**, containers — so you can flatten inputs while keeping pill buttons, or the reverse.
 
 ### Per-Component Customization
 
@@ -104,7 +108,7 @@ Override specific component tokens:
 
 ```css
 :root {
-	--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared --stuic-radius */
+	--stuic-button-radius: 9999px; /* Pill buttons — overrides the shared --stuic-radius-button */
 	--stuic-switch-accent: #10b981; /* Green switches */
 }
 ```
@@ -167,7 +171,7 @@ See [API.md](API.md) for the full list of exported theme types (`ThemeSchema`, `
 
 ### Layout & Overlays
 
-AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, Header, SlidingPanels, Nav, WithSidePanel
+AppShell, Accordion, Backdrop, Modal, ModalDialog, Drawer, Collapsible, Header, SlidingPanels, Nav, WithSidePanel, SplitPane
 
 ### Forms & Inputs
 
@@ -175,7 +179,7 @@ FieldInput, FieldMoney, FieldDate, FieldDateRange, Calendar, FieldTextarea, Fiel
 
 ### Buttons & Controls
 
-Button, ButtonGroupRadio, Switch, Slider, TwCheck, ListItemButton, X
+Button, ButtonGroupRadio, Switch, Slider, RangeSlider, TwCheck, ListItemButton, X
 
 ### Feedback & Notifications
 
@@ -206,6 +210,18 @@ Cart, Checkout (CheckoutProgress, CheckoutOrderSummary, CheckoutCartReview, Chec
 
 `autogrow` · `validate` · `focusTrap` · `autoscroll` · `dimBehind` · `fileDropzone` · `highlightDragover` · `resizableWidth` · `spotlight` · `trim` · `typeahead` · `onSubmitValidityCheck` · `popover` · `tooltip` · `createTour` / `tourStep` (onboarding)
 
+## Attachments
+
+Svelte `{@attach}` helpers — preferred over new actions (reactive, composable, forwardable).
+
+```svelte
+<div {@attach autoHeight}>…</div>
+<aside {@attach resizable({ initial: 300, min: 200, max: 600, key: "sidebar" })}>…</aside>
+<div {@attach longPress({ onLongPress: (e) => openAt(e.clientX, e.clientY) })}>…</div>
+```
+
+`autoHeight` · `longPress` · `resizable`
+
 ## PWA safe-area insets
 
 When a stuic app is installed and launched standalone (iOS Home Screen, Android/desktop PWA), the web view fills the entire screen, so edge-anchored chrome can render under the status bar / notch / home indicator. stuic ships an **opt-in** safe-area layer that is **inert in a normal browser tab** (`env()` → `0`) and only engages under `@media (display-mode: standalone), (display-mode: fullscreen)`.

package/dist/actions/resizable-width.svelte.d.ts

@@ -1,42 +1,28 @@
+import { type ResizableOptions } from "../attachments/resizable.js";
 /**
- * Options for the resizable width action.
+ * Options for the {@link resizableWidth} action — the `x`-axis
+ * {@link ResizableOptions} of the `resizable` attachment with the legacy
+ * `onResize` payload shape (`width` instead of `size`).
  */
-export interface ResizableWidthOptions {
-    enabled?: boolean;
-    initial?: number;
-    min?: number;
-    max?: number;
-    units?: "px" | "%";
-    /** Reverses handle position (left instead of right) and drag direction */
-    reverse?: boolean;
-    key?: string | number | null | undefined;
-    storage?: "local" | "session";
-    handleClass?: string;
-    handleDragClass?: string;
+export interface ResizableWidthOptions extends Omit<ResizableOptions, "axis" | "onResize"> {
     onResize?: (info: {
         width: number;
         units: "px" | "%";
         container: number;
     }) => void;
-    debug?: (...args: unknown[]) => void;
 }
 /**
- * A Svelte action that makes an element's width resizable via drag handle.
+ * A Svelte action that makes an element's width resizable via a drag handle on its
+ * right (or, with `reverse`, left) edge.
  *
- * Adds a draggable handle to the right (or left with `reverse`) edge of the element.
- * Supports mouse and touch input.
- * Optionally persists the width to localStorage/sessionStorage.
- *
- * Features:
- * - Drag handle with visual feedback
- * - Min/max width constraints
- * - Support for px or % units
- * - Optional storage persistence with custom key
- * - Double-click handle to reset to initial width
- * - Touch device support
+ * Kept for back-compat: it is a thin wrapper over the `resizable` attachment
+ * (`axis: "x"`), so it has everything the attachment has — the handle is a focusable
+ * `role="separator"` with arrow / Home / End / Enter keyboard resizing, Pointer Events
+ * cover mouse, touch and pen, `min` / `max` clamp, `key` persists, double-click resets.
+ * For new code (and for heights) use `{@attach resizable(...)}` directly.
  *
  * @param el - The element to make resizable
- * @param fn - Function returning configuration options
+ * @param fn - Function returning configuration options (re-runs the action on reactive change)
  *
  * @remarks
  * The `units` option should not be changed dynamically after initialization.
@@ -63,4 +49,4 @@ export interface ResizableWidthOptions {
  * </div>
  * ```
  */
-export declare function resizableWidth(el: HTMLDivElement, fn?: () => ResizableWidthOptions): void;
+export declare function resizableWidth(el: HTMLElement, fn?: () => ResizableWidthOptions): void;

package/dist/actions/resizable-width.svelte.js

@@ -1,22 +1,16 @@
-import { localStorageState, sessionStorageState, } from "../utils/persistent-state.svelte.js";
-import { twMerge } from "../utils/tw-merge.js";
+import { resizable } from "../attachments/resizable.js";
 /**
- * A Svelte action that makes an element's width resizable via drag handle.
+ * A Svelte action that makes an element's width resizable via a drag handle on its
+ * right (or, with `reverse`, left) edge.
  *
- * Adds a draggable handle to the right (or left with `reverse`) edge of the element.
- * Supports mouse and touch input.
- * Optionally persists the width to localStorage/sessionStorage.
- *
- * Features:
- * - Drag handle with visual feedback
- * - Min/max width constraints
- * - Support for px or % units
- * - Optional storage persistence with custom key
- * - Double-click handle to reset to initial width
- * - Touch device support
+ * Kept for back-compat: it is a thin wrapper over the `resizable` attachment
+ * (`axis: "x"`), so it has everything the attachment has — the handle is a focusable
+ * `role="separator"` with arrow / Home / End / Enter keyboard resizing, Pointer Events
+ * cover mouse, touch and pen, `min` / `max` clamp, `key` persists, double-click resets.
+ * For new code (and for heights) use `{@attach resizable(...)}` directly.
  *
  * @param el - The element to make resizable
- * @param fn - Function returning configuration options
+ * @param fn - Function returning configuration options (re-runs the action on reactive change)
  *
  * @remarks
  * The `units` option should not be changed dynamically after initialization.
@@ -44,162 +38,13 @@ import { twMerge } from "../utils/tw-merge.js";
  * ```
  */
 export function resizableWidth(el, fn) {
-    const HANDLE_CLS_BASE = [
-        "group",
-        "absolute top-0 bottom-0",
-        "w-[1px]",
-        "bg-black/20 hover:bg-black/30",
-        "dark:bg-white/10 dark:hover:bg-white/20",
-        "transition-colors duration-200",
-        "touch-none cursor-ew-resize",
-    ].join(" ");
-    const DEFAULT_DRAG_HANDLE_CLS = [
-        "absolute h-[20px] w-[9px]",
-        "-translate-x-[4px] top-1/2 -translate-y-1/2",
-        "rounded border border-black/20 dark:border-white/20",
-        "bg-gray-300 group-hover:bg-gray-400",
-        "dark:bg-gray-600 dark:group-hover:bg-gray-500",
-        "transition-colors duration-200",
-        "touch-none cursor-ew-resize",
-    ].join(" ");
-    function create_handle(el, handleClass, handleDragClass, reverse) {
-        const handle = document.createElement("div");
-        handle.setAttribute("data-handle", "true");
-        const dragHandle = document.createElement("div");
-        dragHandle.classList.add(...twMerge(DEFAULT_DRAG_HANDLE_CLS, handleDragClass).split(" "));
-        handle.appendChild(dragHandle);
-        el.appendChild(handle);
-        //
-        const positionCls = reverse ? "left-0" : "right-0";
-        handle.classList.add(...twMerge(HANDLE_CLS_BASE, positionCls, handleClass).split(" "));
-        return handle;
-    }
     $effect(() => {
-        const { enabled = true, initial: initialValue = 0, min = 0, max = 0, units = "px", reverse = false, key, storage = "session", handleClass = "", handleDragClass = "", onResize, debug, } = fn?.() || {};
-        let initial = initialValue;
-        const _debug = (...args) => debug?.("[resizable-width]", ...args);
-        _debug("$effect");
-        if (!enabled)
-            return;
-        // initialize ////////////////////////////////////////////////////////////////////
-        //
-        let isResizing = false;
-        let startX = 0;
-        let startWidth = 0;
-        let containerW = undefined;
-        //
-        const handle = create_handle(el, handleClass, handleDragClass, reverse);
-        const container = el.parentElement;
-        // do we have a storage? if so, adjust the initial value...
-        const initialBackup = initial;
-        const _storage = get_storage(storage, key, initial);
-        if (_storage)
-            initial = _storage.current ?? initial;
-        // handlers/workers/helpers //////////////////////////////////////////////////////
-        function set_width(pxOrPercent) {
-            if (pxOrPercent) {
-                _debug(`set_width(${pxOrPercent})`);
-                set_width_px(units === "%" ? container.offsetWidth * (pxOrPercent / 100) : pxOrPercent);
-            }
-        }
-        function set_width_px(widthPx) {
-            _debug(`set_width_px(${widthPx})`);
-            containerW ??= container.offsetWidth;
-            const clamp = (value) => {
-                const _initial = value;
-                if (min)
-                    value = Math.max(min, value);
-                if (max)
-                    value = Math.min(max, value);
-                if (_initial !== value)
-                    _debug("clamped", value, units);
-                return value;
-            };
-            let width;
-            if (units === "%") {
-                const widthPercent = Math.min(100, (widthPx / containerW) * 100); // convert to % (with 100 max)
-                width = clamp(widthPercent);
-            }
-            else {
-                width = clamp(widthPx);
-            }
-            el.style.width = `${width}${units}`;
-            _debug("new width", width, units);
-            const info = { width, units, container: containerW };
-            onResize?.(info);
-            // maybe save to storage
-            if (_storage)
-                _storage.current = width;
-            return info;
-        }
-        function resize_start(e) {
-            e.preventDefault(); // prevent scrolling on touch devices
-            isResizing = true;
-            //
-            const clientX = "touches" in e ? e.touches[0].clientX : e.clientX;
-            startX = clientX;
-            startWidth = parseInt(getComputedStyle(el).width, 10);
-            containerW = container.offsetWidth;
-            //
-            document.body.style.cursor = "ew-resize";
-            document.body.style.userSelect = "none";
-        }
-        function resize(e) {
-            if (!isResizing)
-                return;
-            e.preventDefault(); // prevent scrolling on touch devices
-            //
-            const clientX = "touches" in e ? e.touches[0].clientX : e.clientX;
-            const deltaX = clientX - startX;
-            const width = reverse ? startWidth - deltaX : startWidth + deltaX;
-            set_width_px(width);
-        }
-        function resize_stop() {
-            if (isResizing) {
-                isResizing = false;
-                containerW = undefined;
-                //
-                document.body.style.cursor = "";
-                document.body.style.userSelect = "";
-            }
-        }
-        function on_dblclick() {
-            set_width(initialBackup);
-        }
-        // initial styles ////////////////////////////////////////////////////////////////
-        el.style.position = "relative"; // so the handle will work
-        set_width(initial);
-        // listeners /////////////////////////////////////////////////////////////////////
-        // handle
-        handle.addEventListener("dblclick", on_dblclick);
-        handle.addEventListener("selectstart", (e) => e.preventDefault()); // prevent text selection during resize
-        // mouse
-        handle.addEventListener("mousedown", resize_start);
-        document.addEventListener("mousemove", resize);
-        document.addEventListener("mouseup", resize_stop);
-        // touch
-        handle.addEventListener("touchstart", resize_start, { passive: false });
-        document.addEventListener("touchmove", resize, { passive: false });
-        document.addEventListener("touchend", resize_stop);
-        document.addEventListener("touchcancel", resize_stop);
-        // cleanup ///////////////////////////////////////////////////////////////////////
-        return () => {
-            // mouse
-            document.removeEventListener("mousemove", resize);
-            document.removeEventListener("mouseup", resize_stop);
-            // touch
-            document.removeEventListener("touchmove", resize);
-            document.removeEventListener("touchend", resize_stop);
-            document.removeEventListener("touchcancel", resize_stop);
-            // will also remove it's own event listeners
-            handle.remove();
-        };
+        const { onResize, ...rest } = fn?.() || {};
+        return resizable({
+            ...rest,
+            axis: "x",
+            onResize: onResize &&
+                (({ size, units, container }) => onResize({ width: size, units, container })),
+        })(el);
     });
 }
-// helpers ///////////////////////////////////////////////////////////////////////////////
-function get_storage(type, key, initialValue) {
-    if (key) {
-        return (type === "session" ? sessionStorageState : localStorageState)(`resizable-width-${key}`, initialValue);
-    }
-    return null;
-}

package/dist/attachments/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./auto-height.js";
 export * from "./long-press.js";
+export * from "./resizable.js";

package/dist/attachments/index.js

@@ -1,2 +1,3 @@
 export * from "./auto-height.js";
 export * from "./long-press.js";
+export * from "./resizable.js";

package/dist/attachments/resizable.d.ts

@@ -0,0 +1,113 @@
+import type { Attachment } from "svelte/attachments";
+/** Which box dimension is resized: `x` = width, `y` = height. */
+export type ResizableAxis = "x" | "y";
+/** `px`, or `%` of the parent element's size along the axis. */
+export type ResizableUnits = "px" | "%";
+/** Payload of {@link ResizableOptions.onResize}. */
+export interface ResizableInfo {
+    /** The applied (clamped) size, in `units` */
+    size: number;
+    units: ResizableUnits;
+    axis: ResizableAxis;
+    /** The parent element's size along the axis in px, as measured for this resize */
+    container: number;
+}
+/** Imperative handle, delivered through {@link ResizableOptions.onInit}. */
+export interface ResizableApi {
+    /** The last applied size, in `units` */
+    readonly current: number;
+    /** Applies a size (in `units`): clamped to `min` / `max`, persisted, announced, reported via `onResize` */
+    set(size: number): void;
+    /** Restores `resetTo` (defaults to `initial`) — what double-click / Enter on the handle do */
+    reset(): void;
+}
+/**
+ * Options for the {@link resizable} attachment.
+ */
+export interface ResizableOptions {
+    /** Master switch. When `false` nothing is set up: no handle, no size applied. Default `true`. */
+    enabled?: boolean;
+    /**
+     * `x` resizes the width (the handle sits on a vertical edge), `y` resizes the height
+     * (horizontal edge). Default `x`.
+     */
+    axis?: ResizableAxis;
+    /**
+     * Size applied on setup when nothing is stored under `key`. `0` (default) leaves the
+     * element's own CSS size alone until the first resize.
+     */
+    initial?: number;
+    /** Lower bound in `units`. `0` = none. */
+    min?: number;
+    /** Upper bound in `units`. `0` = none (`%` is still capped at 100). */
+    max?: number;
+    /** `px` (default) or `%` of the parent element. Not meant to change after setup. */
+    units?: ResizableUnits;
+    /**
+     * Puts the handle on the start edge (left / top) and inverts the drag direction — for
+     * an element sitting at the end (right / bottom) of its container.
+     */
+    reverse?: boolean;
+    /** Persist the size under this key (as `resizable-width-<key>` / `resizable-height-<key>`). */
+    key?: string | number | null | undefined;
+    /** Where `key` persists to. Default `session`. */
+    storage?: "local" | "session";
+    /** Keyboard step in `units`; Shift multiplies it by 10. Default `10` for px, `1` for %. */
+    step?: number;
+    /** Accessible name of the handle (it is a `separator`). Default `"Resize"`. */
+    label?: string;
+    /** The size restored by double-click / Enter / `api.reset()`. Defaults to `initial`. */
+    resetTo?: number;
+    /**
+     * Use this element as the handle instead of creating one inside the resized element.
+     * It receives the separator semantics, the keyboard and the pointer handling (and
+     * `touch-action: none`), but no visual styling — that stays with the consumer.
+     */
+    handle?: HTMLElement;
+    /** Extra classes of the created handle (the full-edge strip). Ignored with `handle`. */
+    handleClass?: string;
+    /** Extra classes of the created handle's grip. Ignored with `handle`. */
+    handleDragClass?: string;
+    /** Fires whenever a size is applied: on setup, while dragging, per key press, on reset and `api.set()` */
+    onResize?: (info: ResizableInfo) => void;
+    /** Receives the imperative api, once per setup */
+    onInit?: (api: ResizableApi) => void;
+    debug?: (...args: unknown[]) => void;
+}
+/**
+ * Makes an element's width (`axis: "x"`) or height (`axis: "y"`) resizable by dragging
+ * its edge. The handle is a keyboard-operable ARIA window splitter (`role="separator"`,
+ * focusable, `aria-valuenow` in `units`): arrow keys along the axis move it by `step`
+ * (×10 with Shift), Home / End go to `min` / `max`, Enter (like double-click) resets.
+ * Pointer Events with capture cover mouse, touch and pen in one code path.
+ *
+ * By default a thin handle strip with a grip is appended inside the element on the
+ * resized edge (the element becomes `position: relative`); pass `handle` to drive an
+ * element of your own (a sibling separator, say) instead. The size can be persisted
+ * under `key`. `min` / `max` clamp every path (drag, keys, `api.set()`).
+ *
+ * A factory: call it with the options (or a function returning them — reactive reads
+ * inside re-run the attachment) and attach the result.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { resizable } from "@marianmeres/stuic";
+ * </script>
+ *
+ * <!-- side by side: the first flex child gets a draggable width -->
+ * <div class="flex">
+ *   <aside {@attach resizable({ initial: 300, min: 200, max: 600, key: "sidebar" })}>…</aside>
+ *   <main class="flex-1">…</main>
+ * </div>
+ *
+ * <!-- stacked: a draggable height, in % of the (definite-height) parent -->
+ * <div class="flex flex-col h-96">
+ *   <div {@attach resizable({ axis: "y", units: "%", initial: 40, max: 80 })}>…</div>
+ *   <div class="flex-1">…</div>
+ * </div>
+ * ```
+ *
+ * @param options - {@link ResizableOptions}, or a function returning them
+ */
+export declare function resizable(options?: ResizableOptions | (() => ResizableOptions)): Attachment<HTMLElement>;

package/dist/attachments/resizable.fixture.svelte

@@ -0,0 +1,53 @@
+<!--
+	TEST-ONLY fixture for the `resizable` attachment (and the `resizableWidth` action
+	wrapper). A 400x300 flex container, the resized element first, a flexing sibling
+	after it; `external` adds a sibling to serve as the provided handle; `unmount`
+	tears the whole thing down so cleanup can be observed on the detached nodes.
+-->
+<script lang="ts">
+	import { resizable, type ResizableOptions } from "./resizable.js";
+	import {
+		resizableWidth,
+		type ResizableWidthOptions,
+	} from "../actions/resizable-width.svelte.js";
+
+	let {
+		options = {} as ResizableOptions,
+		action = undefined as ResizableWidthOptions | undefined,
+		external = false,
+		vertical = false,
+	} = $props();
+
+	let handleEl = $state<HTMLDivElement>();
+	let mounted = $state(true);
+</script>
+
+<div
+	data-testid="container"
+	style="width:400px;height:300px;display:flex;flex-direction:{vertical
+		? 'column'
+		: 'row'}"
+>
+	{#if mounted}
+		{#if action}
+			<div data-testid="el" style="width:100px" use:resizableWidth={() => action}>el</div>
+		{:else}
+			<div
+				data-testid="el"
+				style={vertical ? "height:100px" : "width:100px"}
+				{@attach external
+					? handleEl && resizable({ ...options, handle: handleEl })
+					: resizable(options)}
+			>
+				el
+			</div>
+		{/if}
+		{#if external}
+			<div data-testid="handle" data-foo="bar" bind:this={handleEl}></div>
+		{/if}
+	{/if}
+	<div style="flex:1">rest</div>
+</div>
+<button type="button" data-testid="unmount" onclick={() => (mounted = false)}
+	>unmount</button
+>