@urbicon-ui/blocks 6.34.0 → 6.36.0

package/dist/primitives/SplitPane/SplitPane.svelte

@@ -0,0 +1,293 @@
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { mintRegistry } from '../../mint';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
+  import type { SplitPaneProps } from './index';
+  import { clampRatio, parseLimit, ratioFromPointer, resolveDragRatio } from './split-pane.utils';
+  import { splitPaneVariants, type SplitPaneVariants } from './split-pane.variants';
+
+  let {
+    start,
+    end,
+    handle,
+    orientation = 'horizontal',
+    defaultRatio = 0.5,
+    ratio = $bindable(defaultRatio),
+    min = '10%',
+    max = '90%',
+    collapsible = false,
+    collapseThreshold = 48,
+    disabled = false,
+    onRatioChange,
+    onCollapsedChange,
+    handleLabel = 'Resize panes',
+    mint = 'none',
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: SplitPaneProps = $props();
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+
+  // aria-controls needs a stable id for the first pane. `$props.id()` must be a
+  // top-level initializer (compiler rule) — SplitPane has no `id` prop, so the
+  // single-step form is enough.
+  const propsId = $props.id();
+  const startPaneId = `splitpane-${propsId}-start`;
+
+  // Slider performs NO right-to-left inversion in its pointer/keyboard handling
+  // (physical coordinates, ArrowRight = increase). SplitPane mirrors that role
+  // model exactly, so `rtl` stays false here. The geometry util still accepts an
+  // `rtl` flag (and is unit-tested for it) so a future house-wide RTL pass has
+  // one seam to wire — see the primitive's open issues.
+  const rtl = false;
+
+  let rootRef = $state<HTMLDivElement>();
+  let handleRef = $state<HTMLDivElement>();
+  let dragging = $state(false);
+  // Collapsed is DERIVED from the bindable ratio, never tracked separately —
+  // an external `bind:ratio` write must move this flag too, or the Enter
+  // toggle acts on stale state (review finding, P1 wave).
+  const collapsed = $derived(collapsible && ratio <= 0);
+  // Remembers the ratio to restore when re-expanding via Enter. Seeded once
+  // from the initial defaultRatio — `untrack` marks the one-time snapshot so it
+  // does not read as a missed reactive dependency.
+  let lastExpandedRatio = $state(untrack(() => defaultRatio));
+
+  // Keep the restore target fresh from every expanded ratio (interactive or
+  // consumer-driven), and fire onCollapsedChange on actual transitions of the
+  // derived flag — regardless of which side caused them.
+  let lastCollapsed = untrack(() => collapsed);
+  $effect(() => {
+    if (ratio > 0) lastExpandedRatio = ratio;
+  });
+  $effect(() => {
+    if (collapsed !== lastCollapsed) {
+      lastCollapsed = collapsed;
+      onCollapsedChange?.(collapsed);
+    }
+  });
+  // Last measured container size on the active axis — feeds px-limit resolution
+  // and the aria-value* bounds. Kept fresh via a ResizeObserver (no-op in jsdom).
+  let measuredPx = $state(0);
+
+  $effect(() => {
+    const el = rootRef;
+    if (!el) return;
+    const measure = () => {
+      const rect = el.getBoundingClientRect();
+      measuredPx = orientation === 'horizontal' ? rect.width : rect.height;
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const ro = new ResizeObserver(measure);
+    ro.observe(el);
+    return () => ro.disconnect();
+  });
+
+  // mint is wired on the interactive element — the divider — exactly as Slider
+  // applies it to its track ref.
+  $effect(() => {
+    if (handleRef && mint && mint !== 'none' && !disabled) {
+      return mintRegistry.apply(handleRef, mint);
+    }
+  });
+
+  function containerSize(): number {
+    if (!rootRef) return measuredPx;
+    const rect = rootRef.getBoundingClientRect();
+    const px = orientation === 'horizontal' ? rect.width : rect.height;
+    if (px > 0) measuredPx = px;
+    return px > 0 ? px : measuredPx;
+  }
+
+  function emitRatio(next: number) {
+    if (next !== ratio) {
+      ratio = next;
+      onRatioChange?.(next);
+    }
+  }
+
+  // ─── Pointer drag ────────────────────────────────────────────────────────
+  // setPointerCapture routes every subsequent pointer event to the divider, so
+  // move/up listeners live on the divider itself — no window listeners, nothing
+  // to leak. Cancel restores the resting state.
+  function onHandlePointerDown(event: PointerEvent) {
+    if (disabled) return;
+    event.preventDefault();
+    handleRef?.focus();
+    handleRef?.setPointerCapture?.(event.pointerId);
+    dragging = true;
+  }
+
+  function onHandlePointerMove(event: PointerEvent) {
+    if (!dragging || disabled || !rootRef) return;
+    const rect = rootRef.getBoundingClientRect();
+    const px = orientation === 'horizontal' ? rect.width : rect.height;
+    if (px > 0) measuredPx = px;
+    const clientPos = orientation === 'horizontal' ? event.clientX : event.clientY;
+    const raw = ratioFromPointer(clientPos, rect, orientation, rtl);
+    const resolved = resolveDragRatio(
+      raw,
+      px,
+      { min, max, collapsible, collapseThreshold },
+      collapsed
+    );
+    emitRatio(resolved.ratio);
+  }
+
+  function endDrag(event: PointerEvent) {
+    if (!dragging) return;
+    handleRef?.releasePointerCapture?.(event.pointerId);
+    dragging = false;
+  }
+
+  function onHandleDblClick() {
+    if (disabled) return;
+    emitRatio(clampRatio(defaultRatio, min, max, containerSize()));
+  }
+
+  // ─── Keyboard ────────────────────────────────────────────────────────────
+  // Arrow keys map to the layout axis (horizontal → Left/Right, vertical →
+  // Up/Down): the "increase" key grows the first pane. ±2% default, ±10% with
+  // Shift; Home/End jump to the min/max limits. Enter follows the APG window
+  // splitter: with `collapsible` it toggles collapse, otherwise it restores
+  // defaultRatio — which also gives keyboard users the reset that double-click
+  // provides for pointers.
+  function onHandleKeydown(event: KeyboardEvent) {
+    if (disabled) return;
+
+    const px = containerSize();
+    const stepAmount = event.shiftKey ? 0.1 : 0.02;
+    const incKey = orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown';
+    const decKey = orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp';
+
+    switch (event.key) {
+      case incKey: {
+        event.preventDefault();
+        emitRatio(clampRatio(ratio + stepAmount, min, max, px));
+        return;
+      }
+      case decKey: {
+        event.preventDefault();
+        emitRatio(clampRatio(ratio - stepAmount, min, max, px));
+        return;
+      }
+      case 'Home': {
+        event.preventDefault();
+        emitRatio(parseLimit(min, px) ?? 0);
+        return;
+      }
+      case 'End': {
+        event.preventDefault();
+        emitRatio(parseLimit(max, px) ?? 1);
+        return;
+      }
+      case 'Enter': {
+        event.preventDefault();
+        if (!collapsible) {
+          emitRatio(clampRatio(defaultRatio, min, max, px));
+        } else if (collapsed) {
+          const restore = lastExpandedRatio > 0 ? lastExpandedRatio : defaultRatio;
+          emitRatio(clampRatio(restore, min, max, px));
+        } else {
+          emitRatio(0);
+        }
+        return;
+      }
+      default:
+        return;
+    }
+  }
+
+  const separatorOrientation = $derived(orientation === 'horizontal' ? 'vertical' : 'horizontal');
+
+  // The DISPLAYED ratio is always clamped into [min, max] (collapse being the
+  // one legitimate exception), so an out-of-window initial/controlled value or
+  // a container resize can never render the pane — or report aria-valuenow —
+  // outside the configured bounds. The bound `ratio` itself is left untouched
+  // (no write-backs from render state).
+  const effectiveRatio = $derived.by(() => {
+    const bounded = Math.max(0, Math.min(1, ratio));
+    if (collapsed) return 0;
+    return clampRatio(bounded, min, max, measuredPx);
+  });
+  const startBasisPct = $derived(effectiveRatio * 100);
+
+  const valueNow = $derived(Math.round(effectiveRatio * 100));
+  // With `collapsible`, 0 is a legitimate value of the separator's range —
+  // otherwise a collapsed pane would report valuenow below valuemin.
+  const valueMin = $derived(collapsible ? 0 : Math.round((parseLimit(min, measuredPx) ?? 0) * 100));
+  const valueMax = $derived(Math.round((parseLimit(max, measuredPx) ?? 1) * 100));
+
+  const variantProps: SplitPaneVariants = $derived({
+    orientation,
+    dragging: dragging || undefined,
+    disabled: disabled || undefined
+  });
+
+  const styles = $derived(splitPaneVariants(variantProps));
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'SplitPane', preset, variantProps, slotClassesProp)
+  );
+</script>
+
+<div
+  {...restProps}
+  bind:this={rootRef}
+  class={unstyled
+    ? [slotClasses?.root, className].filter(Boolean).join(' ')
+    : styles.root({ class: [slotClasses?.root, className] })}
+  data-orientation={orientation}
+  data-dragging={dragging || undefined}
+  data-collapsed={collapsed || undefined}
+>
+  <div
+    id={startPaneId}
+    class={unstyled
+      ? (slotClasses?.startPane ?? '')
+      : styles.startPane({ class: slotClasses?.startPane })}
+    style="flex: 0 0 {startBasisPct}%"
+  >
+    {@render start()}
+  </div>
+
+  <!-- The divider is the ARIA "window splitter": role="separator" made focusable
+       (tabindex) with aria-value* + keyboard resize. Svelte's a11y rules treat
+       any separator as non-interactive; this pattern is the sanctioned exception. -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex, a11y_no_noninteractive_element_interactions -->
+  <div
+    bind:this={handleRef}
+    role="separator"
+    tabindex={disabled ? -1 : 0}
+    aria-label={handleLabel}
+    aria-controls={startPaneId}
+    aria-orientation={separatorOrientation}
+    aria-valuenow={valueNow}
+    aria-valuemin={valueMin}
+    aria-valuemax={valueMax}
+    aria-disabled={disabled || undefined}
+    data-dragging={dragging || undefined}
+    class={unstyled ? (slotClasses?.handle ?? '') : styles.handle({ class: slotClasses?.handle })}
+    onpointerdown={onHandlePointerDown}
+    onpointermove={onHandlePointerMove}
+    onpointerup={endDrag}
+    onpointercancel={endDrag}
+    ondblclick={onHandleDblClick}
+    onkeydown={onHandleKeydown}
+  >
+    {@render handle?.()}
+  </div>
+
+  <div
+    class={unstyled
+      ? (slotClasses?.endPane ?? '')
+      : styles.endPane({ class: slotClasses?.endPane })}
+    style="flex: 1 1 0%"
+  >
+    {@render end()}
+  </div>
+</div>

package/dist/primitives/SplitPane/SplitPane.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { SplitPaneProps } from './index.js';
+declare const SplitPane: import("svelte").Component<SplitPaneProps, {}, "ratio">;
+type SplitPane = ReturnType<typeof SplitPane>;
+export default SplitPane;

package/dist/primitives/SplitPane/index.d.ts

@@ -0,0 +1,88 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import type { MintProp } from '../../mint/index.js';
+import type { SplitPaneLimit } from './split-pane.utils.js';
+import type { SplitPaneSlots, SplitPaneVariants } from './split-pane.variants.js';
+/**
+ * @description Resizable two-pane layout. A draggable divider (ARIA "window
+ * splitter", role="separator") splits the container into a `start` and an `end`
+ * pane; the first pane's share is controlled by `ratio` (0–1) and supports
+ * `bind:ratio`. Resize by pointer drag or keyboard (Arrow / Home / End), with
+ * optional collapse-to-zero. Panes clip their own overflow so their content
+ * scrolls independently. For an application shell with a permanent nav rail
+ * prefer SidebarLayout / Sidebar; reach for SplitPane when both regions are
+ * primary content the user should be able to rebalance.
+ *
+ * @tag layout
+ * @related SidebarLayout
+ * @related Sidebar
+ * @stability experimental
+ *
+ * @example
+ * ```svelte
+ * <SplitPane bind:ratio={split} min="20%" max="80%">
+ *   {#snippet start()}<nav class="p-4">…</nav>{/snippet}
+ *   {#snippet end()}<main class="p-4">…</main>{/snippet}
+ * </SplitPane>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <SplitPane orientation="vertical" collapsible defaultRatio={0.3}>
+ *   {#snippet start()}<section class="overflow-auto">Editor</section>{/snippet}
+ *   {#snippet end()}<section class="overflow-auto">Preview</section>{/snippet}
+ * </SplitPane>
+ * ```
+ */
+export interface SplitPaneProps extends Omit<SplitPaneVariants, 'dragging' | 'orientation' | 'disabled'>, Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'class'> {
+    /** First pane. In `horizontal` orientation it is the leading (left) pane; in `vertical` the top pane. Required. */
+    start: Snippet;
+    /** Second pane — fills the space the first pane leaves. Required. */
+    end: Snippet;
+    /** Custom content rendered inside the divider (e.g. a grip icon). Replaces the default line; the divider stays the focusable separator. */
+    handle?: Snippet;
+    /** Layout axis. `horizontal` places panes side by side (vertical divider); `vertical` stacks them (horizontal divider). @default 'horizontal' */
+    orientation?: 'horizontal' | 'vertical';
+    /** First pane's share of the container, `0`–`1`. Supports `bind:ratio`. When omitted, starts at `defaultRatio` and is managed internally. */
+    ratio?: number;
+    /** Initial ratio for uncontrolled use; also the target of a double-click reset. @default 0.5 */
+    defaultRatio?: number;
+    /** Lower bound for the first pane — px (`number`) or percentage string (`'20%'`). @default '10%' */
+    min?: SplitPaneLimit;
+    /** Upper bound for the first pane — px (`number`) or percentage string (`'90%'`). @default '90%' */
+    max?: SplitPaneLimit;
+    /** Allow the first pane to collapse to zero: dragging below `collapseThreshold`, or pressing Enter on the divider, snaps it shut. @default false */
+    collapsible?: boolean;
+    /** Pixel width/height of the first pane below which a drag snaps it collapsed. Only used when `collapsible`. @default 48 */
+    collapseThreshold?: number;
+    /** Disable resizing — the divider becomes inert (not focusable, no pointer/keyboard response). Panes stay visible. @default false */
+    disabled?: boolean;
+    /** Fires after a drag/keyboard interaction changes the ratio. Receives the new ratio (`0`–`1`). Does not fire for consumer-driven `bind:ratio` writes. */
+    onRatioChange?: (ratio: number) => void;
+    /** Fires when the first pane collapses (`true`) or re-expands (`false`) via drag or Enter. */
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** Accessible name for the divider (its `aria-label`). @default 'Resize panes' */
+    handleLabel?: string;
+    /** Micro-interaction preset applied to the divider. @default 'none' */
+    mint?: MintProp;
+    /** Extra classes merged onto the root container (the flex box). */
+    class?: string;
+    /** Remove all default tv() classes; combine with `slotClasses` to rebuild the look. */
+    unstyled?: boolean;
+    /**
+     * Per-slot class overrides merged with tv() styles. Slots: root (the flex
+     * container — what `class` also targets) | startPane | endPane | handle (the
+     * draggable divider / separator).
+     */
+    slotClasses?: Partial<Record<SplitPaneSlots, string>>;
+    /**
+     * Apply a named preset registered via `<BlocksProvider presets={{ SplitPane: {...} }}>`.
+     * Prefer this over `class` overrides when the requested look falls outside the
+     * semantic intent palette — presets keep hover/active/dark-mode logic coherent
+     * and make the custom look reusable across the project.
+     */
+    preset?: string;
+}
+export { default as SplitPane } from './SplitPane.svelte';
+export type { SplitPaneLimit, SplitPaneOrientation } from './split-pane.utils.js';
+export { type SplitPaneVariants, splitPaneVariants } from './split-pane.variants.js';

package/dist/primitives/SplitPane/index.js

@@ -0,0 +1,2 @@
+export { default as SplitPane } from './SplitPane.svelte';
+export { splitPaneVariants } from './split-pane.variants.js';

package/dist/primitives/SplitPane/split-pane.utils.d.ts

@@ -0,0 +1,73 @@
+/** Layout axis. `horizontal` = panes side by side; `vertical` = stacked. */
+export type SplitPaneOrientation = 'horizontal' | 'vertical';
+/**
+ * A min/max boundary for the first pane. A raw `number` is pixels; a string
+ * ending in `%` (e.g. `'20%'`) is a percentage of the container. A bare numeric
+ * string (`'200'`) is also treated as pixels.
+ */
+export type SplitPaneLimit = number | string;
+/** The four rect fields the pointer math reads — a structural subset of DOMRect. */
+export interface RectLike {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Resolve a min/max limit to a ratio in `[0, 1]`.
+ *
+ * - Percentage strings (`'20%'`) convert directly and need no measurement.
+ * - Pixel values (number or bare numeric string) are divided by `containerPx`.
+ *
+ * Returns `null` when a pixel limit cannot be resolved because the container has
+ * not been measured yet (`containerPx <= 0`). Callers treat a `null` minimum as
+ * `0` and a `null` maximum as `1`, so an unmeasured px limit degrades to "no
+ * constraint" until the first layout pass, then clamps at runtime.
+ */
+export declare function parseLimit(limit: SplitPaneLimit, containerPx: number): number | null;
+/**
+ * Clamp a ratio into the `[min, max]` window, resolving px/percent limits
+ * against `containerPx`. Unresolved px limits fall back to `0` (min) / `1`
+ * (max). A reversed window (`min > max`) is tolerated by swapping the bounds so
+ * the result is always well-defined. A non-finite input ratio snaps to the
+ * lower bound.
+ */
+export declare function clampRatio(ratio: number, min: SplitPaneLimit, max: SplitPaneLimit, containerPx: number): number;
+/**
+ * Convert a pointer coordinate to the first-pane ratio (`[0, 1]`), before
+ * min/max clamping.
+ *
+ * - `horizontal`: uses `clientX` against `rect.left` / `rect.width`. When `rtl`
+ *   is true the axis is mirrored (the first pane grows from the right edge).
+ * - `vertical`: uses `clientY` against `rect.top` / `rect.height`; `rtl` has no
+ *   effect on the vertical axis.
+ *
+ * A zero-sized container yields `0` rather than dividing by zero.
+ */
+export declare function ratioFromPointer(clientPos: number, rect: RectLike, orientation: SplitPaneOrientation, rtl?: boolean): number;
+/** Limits + collapse config consumed by {@link resolveDragRatio}. */
+export interface DragResolveOptions {
+    min: SplitPaneLimit;
+    max: SplitPaneLimit;
+    collapsible: boolean;
+    collapseThreshold: number;
+}
+/**
+ * Dead-band added on top of `collapseThreshold` before a collapsed pane
+ * re-expands during a drag. Without it, pointer jitter around the threshold
+ * flip-flops ratio between `0` and `min` and bursts the change callbacks.
+ */
+export declare const COLLAPSE_HYSTERESIS_PX = 12;
+/**
+ * Decide the resting ratio and collapsed flag for a raw pointer ratio.
+ *
+ * Collapse wins over the min clamp: while `collapsible`, dragging the first pane
+ * below `collapseThreshold` px snaps it fully shut (`ratio: 0`, `collapsed:
+ * true`). While `currentlyCollapsed`, re-expanding requires clearing the
+ * threshold plus {@link COLLAPSE_HYSTERESIS_PX} (drag hysteresis). Otherwise the
+ * ratio is clamped into the `[min, max]` window and `collapsed` is `false`.
+ */
+export declare function resolveDragRatio(raw: number, containerPx: number, { min, max, collapsible, collapseThreshold }: DragResolveOptions, currentlyCollapsed?: boolean): {
+    ratio: number;
+    collapsed: boolean;
+};

package/dist/primitives/SplitPane/split-pane.utils.js

@@ -0,0 +1,94 @@
+// Pure geometry for the SplitPane primitive. Every function here is
+// side-effect-free and DOM-free so the resize math can be unit-tested in the
+// node environment (no jsdom) and the `.svelte` file can stay a thin shell over
+// it — exactly the split Slider draws between its keyboard math and its markup.
+const clamp01 = (n) => Math.min(1, Math.max(0, n));
+/**
+ * Resolve a min/max limit to a ratio in `[0, 1]`.
+ *
+ * - Percentage strings (`'20%'`) convert directly and need no measurement.
+ * - Pixel values (number or bare numeric string) are divided by `containerPx`.
+ *
+ * Returns `null` when a pixel limit cannot be resolved because the container has
+ * not been measured yet (`containerPx <= 0`). Callers treat a `null` minimum as
+ * `0` and a `null` maximum as `1`, so an unmeasured px limit degrades to "no
+ * constraint" until the first layout pass, then clamps at runtime.
+ */
+export function parseLimit(limit, containerPx) {
+    if (typeof limit === 'string') {
+        const trimmed = limit.trim();
+        if (trimmed.endsWith('%')) {
+            const pct = Number.parseFloat(trimmed.slice(0, -1));
+            return Number.isFinite(pct) ? clamp01(pct / 100) : null;
+        }
+        const px = Number.parseFloat(trimmed);
+        if (!Number.isFinite(px))
+            return null;
+        return containerPx > 0 ? clamp01(px / containerPx) : null;
+    }
+    if (!Number.isFinite(limit))
+        return null;
+    return containerPx > 0 ? clamp01(limit / containerPx) : null;
+}
+/**
+ * Clamp a ratio into the `[min, max]` window, resolving px/percent limits
+ * against `containerPx`. Unresolved px limits fall back to `0` (min) / `1`
+ * (max). A reversed window (`min > max`) is tolerated by swapping the bounds so
+ * the result is always well-defined. A non-finite input ratio snaps to the
+ * lower bound.
+ */
+export function clampRatio(ratio, min, max, containerPx) {
+    const lo = parseLimit(min, containerPx) ?? 0;
+    const hi = parseLimit(max, containerPx) ?? 1;
+    const low = Math.min(lo, hi);
+    const high = Math.max(lo, hi);
+    const r = Number.isFinite(ratio) ? ratio : low;
+    return Math.min(high, Math.max(low, r));
+}
+/**
+ * Convert a pointer coordinate to the first-pane ratio (`[0, 1]`), before
+ * min/max clamping.
+ *
+ * - `horizontal`: uses `clientX` against `rect.left` / `rect.width`. When `rtl`
+ *   is true the axis is mirrored (the first pane grows from the right edge).
+ * - `vertical`: uses `clientY` against `rect.top` / `rect.height`; `rtl` has no
+ *   effect on the vertical axis.
+ *
+ * A zero-sized container yields `0` rather than dividing by zero.
+ */
+export function ratioFromPointer(clientPos, rect, orientation, rtl = false) {
+    if (orientation === 'vertical') {
+        if (!(rect.height > 0))
+            return 0;
+        return clamp01((clientPos - rect.top) / rect.height);
+    }
+    if (!(rect.width > 0))
+        return 0;
+    const raw = (clientPos - rect.left) / rect.width;
+    return clamp01(rtl ? 1 - raw : raw);
+}
+/**
+ * Dead-band added on top of `collapseThreshold` before a collapsed pane
+ * re-expands during a drag. Without it, pointer jitter around the threshold
+ * flip-flops ratio between `0` and `min` and bursts the change callbacks.
+ */
+export const COLLAPSE_HYSTERESIS_PX = 12;
+/**
+ * Decide the resting ratio and collapsed flag for a raw pointer ratio.
+ *
+ * Collapse wins over the min clamp: while `collapsible`, dragging the first pane
+ * below `collapseThreshold` px snaps it fully shut (`ratio: 0`, `collapsed:
+ * true`). While `currentlyCollapsed`, re-expanding requires clearing the
+ * threshold plus {@link COLLAPSE_HYSTERESIS_PX} (drag hysteresis). Otherwise the
+ * ratio is clamped into the `[min, max]` window and `collapsed` is `false`.
+ */
+export function resolveDragRatio(raw, containerPx, { min, max, collapsible, collapseThreshold }, currentlyCollapsed = false) {
+    if (collapsible && containerPx > 0) {
+        const releasePx = currentlyCollapsed
+            ? collapseThreshold + COLLAPSE_HYSTERESIS_PX
+            : collapseThreshold;
+        if (raw * containerPx < releasePx)
+            return { ratio: 0, collapsed: true };
+    }
+    return { ratio: clampRatio(raw, min, max, containerPx), collapsed: false };
+}

package/dist/primitives/SplitPane/split-pane.variants.d.ts

@@ -0,0 +1,40 @@
+import { type SlotNames, type VariantProps } from '../../utils/variants.js';
+export declare const splitPaneVariants: ((props?: {
+    orientation?: "horizontal" | "vertical" | undefined;
+    dragging?: boolean | undefined;
+    disabled?: boolean | undefined;
+} | undefined) => {
+    root: (props?: ({
+        orientation?: "horizontal" | "vertical" | undefined;
+        dragging?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    startPane: (props?: ({
+        orientation?: "horizontal" | "vertical" | undefined;
+        dragging?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    endPane: (props?: ({
+        orientation?: "horizontal" | "vertical" | undefined;
+        dragging?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+    handle: (props?: ({
+        orientation?: "horizontal" | "vertical" | undefined;
+        dragging?: boolean | undefined;
+        disabled?: boolean | undefined;
+    } & {
+        class?: string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | (string | number | false | /*elided*/ any | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined)[] | Record<string, boolean | null | undefined> | null | undefined;
+    }) | undefined) => string;
+}) & {
+    readonly config: import("../../utils/variants.js").TVConfig;
+};
+export type SplitPaneVariants = VariantProps<typeof splitPaneVariants>;
+/** Slot names derived from the `tv()` config above — single source of truth for `slotClasses`. */
+export type SplitPaneSlots = SlotNames<typeof splitPaneVariants>;

package/dist/primitives/SplitPane/split-pane.variants.js

@@ -0,0 +1,56 @@
+import { tv } from '../../utils/variants.js';
+export const splitPaneVariants = tv({
+    slots: {
+        // Flex container. `h-full`/`w-full` inherit the consumer's box; the panes
+        // size via flex-basis so the divider can sit at any ratio.
+        root: ['relative flex w-full h-full min-w-0 min-h-0'],
+        // Panes clip their own overflow and let long content scroll internally —
+        // min-w-0/min-h-0 defeats flexbox's default min-content floor so a pane can
+        // actually shrink below its content size.
+        startPane: ['overflow-hidden min-w-0 min-h-0'],
+        endPane: ['overflow-hidden min-w-0 min-h-0'],
+        // The divider is a thin visible line (bg-border-default) that is itself the
+        // role="separator". It is positioned (`relative`) with no z-index, so — like
+        // Slider's rail thumb — it and its transparent `::before` hit-expander paint
+        // above the statically-flowed panes. The `::before` swells the grab target
+        // to ≥24px (WCAG 2.5.8 AA) without widening the visible gutter.
+        handle: [
+            'relative shrink-0 touch-none select-none',
+            'bg-border-default',
+            'transition-[background-color] duration-[var(--blocks-duration-fast)]',
+            'hover:bg-primary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary/50 focus-visible:ring-offset-1 focus-visible:ring-offset-surface-base',
+            "before:content-[''] before:absolute"
+        ]
+    },
+    variants: {
+        orientation: {
+            horizontal: {
+                root: 'flex-row',
+                // Vertical rule between side-by-side panes. Hit area: 4px + 2×10px = 24px.
+                handle: 'self-stretch w-1 cursor-col-resize before:inset-y-0 before:-inset-x-2.5'
+            },
+            vertical: {
+                root: 'flex-col',
+                // Horizontal rule between stacked panes.
+                handle: 'w-full h-1 cursor-row-resize before:inset-x-0 before:-inset-y-2.5'
+            }
+        },
+        // State axes last (house order): a state must dominate the resting look.
+        dragging: {
+            true: { handle: 'bg-primary' }
+        },
+        // Declared after `dragging` so its hover-neutralising override wins the
+        // `hover:bg` bucket even if a stale `dragging` were ever set together.
+        disabled: {
+            true: {
+                handle: 'cursor-default pointer-events-none hover:bg-border-default'
+            }
+        }
+    },
+    defaultVariants: {
+        orientation: 'horizontal',
+        dragging: false,
+        disabled: false
+    }
+});