@kouji-ui/core 0.0.4 → 0.1.1

package/src/skeleton/skeleton.ts

@@ -0,0 +1,56 @@
+import { Directive, input } from '@angular/core';
+
+/**
+ * Visual shape preset for a skeleton placeholder. Reflects to `data-shape`.
+ */
+export type KjSkeletonShape = 'rectangle' | 'circle' | 'text' | 'text-block';
+
+/**
+ * Animation preset for a skeleton placeholder. Reflects to `data-animation`.
+ */
+export type KjSkeletonAnimation = 'shimmer' | 'pulse' | 'none';
+
+/**
+ * Marks an element as a kouji skeleton — a decorative placeholder painted
+ * while real content is loading. Forces `aria-hidden="true"` on the host so
+ * AT skips the placeholder (the *parent region* carries the loading
+ * semantics, see [`skeleton.md`](./skeleton.md) § Accessibility), and
+ * reflects `data-shape` / `data-animation` so theme CSS can pick the
+ * chrome and animation. The directive owns no dimensions, no variant, no
+ * size — sizing is consumer-driven and skeletons are tonally neutral by
+ * design.
+ *
+ * @example
+ * ```html
+ * <span kjSkeleton kjSkeletonShape="text" style="width: 12rem"></span>
+ * <div kjSkeleton kjSkeletonShape="circle" style="width: 40px; height: 40px"></div>
+ * ```
+ * @doc-category Core/Layout
+ * @doc
+ * @doc-name skeleton
+ * @doc-description Marks an element as a decorative loading placeholder hidden from screen readers.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjSkeleton]',
+  standalone: true,
+  exportAs: 'kjSkeleton',
+  host: {
+    '[attr.aria-hidden]': '"true"',
+    '[attr.data-shape]': 'kjSkeletonShape()',
+    '[attr.data-animation]': 'kjSkeletonAnimation()',
+  },
+})
+export class KjSkeleton {
+  /**
+   * The visual shape of the skeleton. Reflects to `data-shape`. Defaults to
+   * `'rectangle'`.
+   */
+  readonly kjSkeletonShape = input<KjSkeletonShape>('rectangle');
+
+  /**
+   * The animation style applied while the skeleton is on screen. Reflects to
+   * `data-animation`. Defaults to `'shimmer'`.
+   */
+  readonly kjSkeletonAnimation = input<KjSkeletonAnimation>('shimmer');
+}

package/src/slider/index.ts

@@ -0,0 +1,10 @@
+export { KjSlider } from './slider';
+export { KjSliderTrack } from './slider-track';
+export { KjSliderRange } from './slider-range';
+export { KjSliderThumb } from './slider-thumb';
+export {
+  KJ_SLIDER,
+  type KjSliderContext,
+  type KjSliderSource,
+  type KjSliderThumbHandle,
+} from './slider.context';

package/src/slider/slider-range.ts

@@ -0,0 +1,49 @@
+import { Directive, computed, inject } from '@angular/core';
+import { KJ_SLIDER } from './slider.context';
+import { fractionForValue } from './slider.geometry';
+
+/**
+ * Highlighted span representing the *selected* portion of the track —
+ * `0..thumb` for a single-thumb slider, or `low..high` for a range slider.
+ *
+ * Pure visual: writes two CSS custom properties (`--kj-slider-start` and
+ * `--kj-slider-end`, both `0..1` fractions) which the wrapper layer maps
+ * to `inset-inline-start` / `inline-size` (or block equivalents for
+ * vertical). `aria-hidden="true"` — decoration only.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name slider
+ */
+@Directive({
+  selector: '[kjSliderRange]',
+  standalone: true,
+  exportAs: 'kjSliderRange',
+  host: {
+    'aria-hidden': 'true',
+    '[attr.data-orientation]': 'ctx.orientation()',
+    '[style.--kj-slider-start]': 'fractions().start',
+    '[style.--kj-slider-end]': 'fractions().end',
+  },
+})
+export class KjSliderRange {
+  /** @internal */
+  readonly ctx = inject(KJ_SLIDER);
+
+  /** @internal — `start` ≤ `end` regardless of inversion (CSS handles flipping). */
+  readonly fractions = computed(() => {
+    const thumbs = this.ctx.thumbs();
+    const args = { min: this.ctx.min(), max: this.ctx.max(), inverted: this.ctx.inverted() };
+    if (thumbs.length === 0) return { start: 0, end: 0 };
+    if (thumbs.length === 1) {
+      const f = fractionForValue(thumbs[0].value(), args);
+      // From the start of the track (post-invert) to the thumb.
+      const start = this.ctx.inverted() ? f : 0;
+      const end = this.ctx.inverted() ? 1 : f;
+      return { start, end };
+    }
+    const lo = fractionForValue(thumbs[0].value(), args);
+    const hi = fractionForValue(thumbs[1].value(), args);
+    return { start: Math.min(lo, hi), end: Math.max(lo, hi) };
+  });
+}

package/src/slider/slider-thumb.ts

@@ -0,0 +1,335 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  afterNextRender,
+  booleanAttribute,
+  computed,
+  effect,
+  inject,
+  input,
+  model,
+  signal,
+} from '@angular/core';
+import { KjDisabled } from '../primitives/interaction/disabled';
+import { KjFocusRing } from '../primitives/interaction/focus-ring';
+import { KjFormControl } from '../primitives/forms/form-control';
+import { KJ_SLIDER, KjSliderSource, KjSliderThumbHandle } from './slider.context';
+import { fractionForValue } from './slider.geometry';
+
+let nextId = 0;
+
+/**
+ * Per-thumb directive. Owns `role="slider"`, `aria-valuemin/max/now/text`,
+ * `aria-orientation`, the keyboard contract (Arrow / Page / Home / End),
+ * pointer-drag with capture, and one `KjFormControl` per thumb so each
+ * thumb is independently bindable through Angular Forms.
+ *
+ * Range mode is just two `[kjSliderThumb]`s as siblings inside one
+ * `[kjSliderTrack]`. The root resolves DOM order to `index` (0 = low,
+ * 1 = high) and narrows each thumb's `aria-valuemin/max` to the partner
+ * thumb's position when `kjMinDistance` would otherwise place a value
+ * out of reach.
+ *
+ * Composes `KjDisabled`, `KjFocusRing`, and `KjFormControl` via
+ * `hostDirectives`. Effective disabled is the OR of root + per-thumb.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name slider
+ */
+@Directive({
+  selector: '[kjSliderThumb]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjDisabled, inputs: ['kjDisabled'] },
+    KjFocusRing,
+    KjFormControl,
+  ],
+  exportAs: 'kjSliderThumb',
+  host: {
+    '[attr.role]': '"slider"',
+    '[attr.id]': 'thumbId()',
+    '[attr.tabindex]': 'effectiveDisabled() ? -1 : 0',
+    '[attr.aria-orientation]': 'ctx.orientation()',
+    '[attr.aria-valuemin]': 'effectiveValueMin()',
+    '[attr.aria-valuemax]': 'effectiveValueMax()',
+    '[attr.aria-valuenow]': 'kjValue()',
+    '[attr.aria-valuetext]': 'ariaValueText()',
+    '[attr.aria-disabled]': 'effectiveDisabled() ? "true" : null',
+    '[attr.aria-readonly]': 'ctx.readonly() ? "true" : null',
+    '[attr.aria-label]': 'kjAriaLabel()',
+    '[attr.aria-labelledby]': 'kjAriaLabelledBy()',
+    '[attr.data-orientation]': 'ctx.orientation()',
+    '[attr.data-dragging]': 'dragging() ? "" : null',
+    '[style.--kj-slider-thumb-fraction]': 'fraction()',
+    '[style.touch-action]': '"none"',
+    '(keydown)': 'onKeydown($event)',
+    '(pointerdown)': 'onPointerDown($event)',
+    '(focus)': 'onFocus()',
+    '(blur)': 'onBlur()',
+  },
+})
+export class KjSliderThumb implements KjSliderThumbHandle {
+  /** @internal */
+  readonly ctx = inject(KJ_SLIDER);
+  /** @internal */
+  readonly formCtrl = inject(KjFormControl);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly destroyRef = inject(DestroyRef);
+
+  // ── Inputs ───────────────────────────────────────────────────────────────
+
+  /** Per-thumb value. Two-way bindable. CVA-bridged via `KjFormControl`. */
+  readonly kjValue = model<number>(0);
+
+  /** Required when there is no `aria-labelledby` ancestor. */
+  readonly kjAriaLabel = input<string | null>(null);
+
+  /** Alternative to `kjAriaLabel`. */
+  readonly kjAriaLabelledBy = input<string | null>(null);
+
+  /** Per-thumb override of the root's `kjDisplayWith`. */
+  readonly kjAriaValueText = input<string | null>(null);
+
+  /** Per-thumb disable. ORed with the root's `kjDisabled`. */
+  readonly kjDisabled = input<boolean, unknown>(false, { transform: booleanAttribute });
+
+  // ── Internal state ───────────────────────────────────────────────────────
+
+  /** @internal — DOM-order index assigned by the root on register. Mutable for re-indexing. */
+  index = 0;
+
+  private readonly _dragging = signal(false);
+  private readonly _id = `kj-slider-thumb-${++nextId}`;
+  private dragStartValue: number | null = null;
+
+  // ── KjSliderThumbHandle interface ────────────────────────────────────────
+
+  /** @internal */
+  readonly value = this.kjValue.asReadonly();
+
+  /** @internal */
+  get element(): HTMLElement {
+    return this.el.nativeElement;
+  }
+
+  /** @internal */
+  setValue(value: number, _source: KjSliderSource): void {
+    if (this.kjValue() !== value) {
+      this.kjValue.set(value);
+      this.formCtrl.notifyChange(value);
+    }
+  }
+
+  /** @internal */
+  focus(): void {
+    this.el.nativeElement.focus();
+  }
+
+  // ── Computed ─────────────────────────────────────────────────────────────
+
+  protected readonly thumbId = computed(() => this.el.nativeElement.id || this._id);
+
+  /** OR of root + per-thumb disabled. */
+  readonly effectiveDisabled = computed(
+    () => this.ctx.disabled() || this.kjDisabled() || this.formCtrl.disabled(),
+  );
+
+  /** @internal */
+  readonly disabled = this.effectiveDisabled;
+
+  /** Effective `aria-valuemin` — narrowed to partner-thumb position in range mode. */
+  protected readonly effectiveValueMin = computed(() => {
+    const thumbs = this.ctx.thumbs();
+    if (thumbs.length === 2 && this.index === 1) {
+      return thumbs[0].value() + this.ctx.minDistance();
+    }
+    return this.ctx.min();
+  });
+
+  /** Effective `aria-valuemax` — narrowed to partner-thumb position in range mode. */
+  protected readonly effectiveValueMax = computed(() => {
+    const thumbs = this.ctx.thumbs();
+    if (thumbs.length === 2 && this.index === 0) {
+      return thumbs[1].value() - this.ctx.minDistance();
+    }
+    return this.ctx.max();
+  });
+
+  protected readonly ariaValueText = computed<string | null>(() => {
+    const override = this.kjAriaValueText();
+    if (override) return override;
+    const formatter = this.ctx.displayWith();
+    if (formatter) return formatter(this.kjValue(), this.index);
+    // Continuous mode (step <= 0): truncate FP noise.
+    if (this.ctx.step() <= 0) {
+      try {
+        return new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }).format(this.kjValue());
+      } catch {
+        return String(this.kjValue());
+      }
+    }
+    return null;
+  });
+
+  /** @internal — used by the wrapper layer to position the thumb visually. */
+  readonly fraction = computed(() =>
+    fractionForValue(this.kjValue(), {
+      min: this.ctx.min(),
+      max: this.ctx.max(),
+      inverted: this.ctx.inverted(),
+    }),
+  );
+
+  /** @internal */
+  readonly dragging = this._dragging.asReadonly();
+
+  constructor() {
+    // Register with the root after construction so the host element exists.
+    this.ctx.registerThumb(this);
+    this.destroyRef.onDestroy(() => this.ctx.unregisterThumb(this));
+
+    // Default the value to `min` if uninitialised. afterNextRender so the
+    // host element is in DOM and the root has registered us first.
+    afterNextRender(() => {
+      const v = this.kjValue();
+      if (!Number.isFinite(v)) {
+        this.kjValue.set(this.ctx.min());
+      }
+    });
+
+    // Bridge KjFormControl ↔ kjValue.
+    effect(() => {
+      const cvaValue = this.formCtrl.value();
+      if (cvaValue == null || cvaValue === undefined) return;
+      const num = typeof cvaValue === 'number' ? cvaValue : Number(cvaValue);
+      if (Number.isFinite(num) && num !== this.kjValue()) {
+        this.kjValue.set(num);
+      }
+    });
+  }
+
+  // ── Event handlers ───────────────────────────────────────────────────────
+
+  /** @internal */
+  onKeydown(event: KeyboardEvent): void {
+    if (this.effectiveDisabled() || this.ctx.readonly()) return;
+    const step = this.ctx.step() > 0 ? this.ctx.step() : 1;
+    const pageStep = this.ctx.pageStep();
+    const orientation = this.ctx.orientation();
+    const rtl = this.ctx.direction() === 'rtl';
+
+    switch (event.key) {
+      case 'ArrowUp':
+        event.preventDefault();
+        this.stepBy(step);
+        return;
+      case 'ArrowDown':
+        event.preventDefault();
+        this.stepBy(-step);
+        return;
+      case 'ArrowRight': {
+        event.preventDefault();
+        // Visual semantics: LTR right = increase; RTL right = decrease.
+        // Vertical: right = increase too (APG: visual axis collapses to value axis).
+        const sign = orientation === 'horizontal' && rtl ? -1 : 1;
+        this.stepBy(sign * step);
+        return;
+      }
+      case 'ArrowLeft': {
+        event.preventDefault();
+        const sign = orientation === 'horizontal' && rtl ? 1 : -1;
+        this.stepBy(sign * step);
+        return;
+      }
+      case 'PageUp':
+        event.preventDefault();
+        this.stepBy(pageStep);
+        return;
+      case 'PageDown':
+        event.preventDefault();
+        this.stepBy(-pageStep);
+        return;
+      case 'Home':
+        event.preventDefault();
+        this.ctx.setThumbValue(this.index, this.effectiveValueMin(), 'keyboard');
+        return;
+      case 'End':
+        event.preventDefault();
+        this.ctx.setThumbValue(this.index, this.effectiveValueMax(), 'keyboard');
+        return;
+      case 'Escape':
+        if (this._dragging() && this.dragStartValue != null) {
+          event.preventDefault();
+          this.ctx.setThumbValue(this.index, this.dragStartValue, 'keyboard');
+          this.endDrag(true);
+        }
+        return;
+      default:
+        return;
+    }
+  }
+
+  /** @internal */
+  onPointerDown(event: PointerEvent): void {
+    if (this.effectiveDisabled() || this.ctx.readonly()) return;
+    if (event.button !== undefined && event.button !== 0) return;
+    event.preventDefault();
+    this.dragStartValue = this.kjValue();
+    this._dragging.set(true);
+    this.ctx.beginDrag(this.index);
+
+    const target = this.el.nativeElement;
+    target.setPointerCapture?.(event.pointerId);
+    target.focus();
+
+    const onMove = (e: PointerEvent) => {
+      if (!this._dragging()) return;
+      const value = this.ctx.valueFromClientPosition(e.clientX, e.clientY);
+      this.ctx.setThumbValue(this.index, value, 'pointer');
+    };
+    const onUp = () => {
+      cleanup();
+      this.endDrag(false);
+    };
+    const onCancel = () => {
+      cleanup();
+      this.endDrag(true);
+    };
+    const cleanup = () => {
+      target.removeEventListener('pointermove', onMove);
+      target.removeEventListener('pointerup', onUp);
+      target.removeEventListener('pointercancel', onCancel);
+      target.removeEventListener('lostpointercapture', onCancel);
+    };
+
+    target.addEventListener('pointermove', onMove);
+    target.addEventListener('pointerup', onUp);
+    target.addEventListener('pointercancel', onCancel);
+    target.addEventListener('lostpointercapture', onCancel);
+  }
+
+  /** @internal */
+  onFocus(): void {
+    /* hook for KjFocusRing */
+  }
+
+  /** @internal */
+  onBlur(): void {
+    this.formCtrl.notifyTouched();
+  }
+
+  // ── Internals ────────────────────────────────────────────────────────────
+
+  private stepBy(delta: number): void {
+    const next = this.kjValue() + delta;
+    this.ctx.setThumbValue(this.index, next, 'keyboard');
+  }
+
+  private endDrag(cancelled: boolean): void {
+    this._dragging.set(false);
+    this.dragStartValue = null;
+    this.ctx.endDrag(cancelled);
+  }
+}

package/src/slider/slider-track.ts

@@ -0,0 +1,70 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  afterNextRender,
+  inject,
+  output,
+} from '@angular/core';
+import { KJ_SLIDER } from './slider.context';
+
+/**
+ * Pointer-event owner for the slider. Captures `pointerdown` on the track,
+ * resolves the target value via the root's geometry helper, picks the
+ * nearest thumb (by absolute value distance), and forwards the value.
+ *
+ * Pointer interactions on a *thumb* are handled by `[kjSliderThumb]` —
+ * the track only handles the click-on-empty-track-jump case.
+ *
+ * Sets `touch-action` to allow page scroll on the cross axis (e.g. vertical
+ * page scroll on a horizontal slider) while blocking the on-axis drag.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name slider
+ */
+@Directive({
+  selector: '[kjSliderTrack]',
+  standalone: true,
+  exportAs: 'kjSliderTrack',
+  host: {
+    '[attr.aria-orientation]': 'ctx.orientation()',
+    '[attr.data-orientation]': 'ctx.orientation()',
+    '[style.touch-action]': 'ctx.orientation() === "vertical" ? "pan-x" : "pan-y"',
+    '(pointerdown)': 'onPointerDown($event)',
+  },
+})
+export class KjSliderTrack {
+  /** @internal */
+  readonly ctx = inject(KJ_SLIDER);
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly destroyRef = inject(DestroyRef);
+
+  /** Diagnostics: emitted when click-to-jump moves a thumb. */
+  readonly kjTrackClick = output<{ value: number; thumbIndex: number }>();
+
+  constructor() {
+    afterNextRender(() => {
+      this.ctx.setTrackElement(this.el.nativeElement);
+      this.destroyRef.onDestroy(() => this.ctx.setTrackElement(null));
+    });
+  }
+
+  /** @internal */
+  onPointerDown(event: PointerEvent): void {
+    if (this.ctx.disabled() || this.ctx.readonly()) {
+      event.preventDefault();
+      return;
+    }
+    const target = event.target as Element | null;
+    // If the press landed on a thumb, let the thumb directive handle it.
+    if (target && target.closest('[kjSliderThumb]')) return;
+
+    event.preventDefault();
+    const value = this.ctx.valueFromClientPosition(event.clientX, event.clientY);
+    const thumbIndex = this.ctx.nearestThumbIndex(value);
+    this.ctx.setThumbValue(thumbIndex, value, 'pointer');
+    this.ctx.thumbs()[thumbIndex]?.focus();
+    this.kjTrackClick.emit({ value, thumbIndex });
+  }
+}

package/src/slider/slider.context.ts

@@ -0,0 +1,79 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/** Source of a value mutation, used by analytics / wrapper announcements. */
+export type KjSliderSource = 'pointer' | 'keyboard' | 'programmatic';
+
+/**
+ * Public handle each `[kjSliderThumb]` registers with the root.
+ * Used by the root for cross-thumb coordination (min-distance, swap),
+ * and by the track for click-to-jump nearest-thumb resolution.
+ */
+export interface KjSliderThumbHandle {
+  /** DOM-order index. `0` for single mode, `0` (low) and `1` (high) for range. */
+  readonly index: number;
+  /** Current per-thumb value. */
+  readonly value: Signal<number>;
+  /** Underlying focusable host element. */
+  readonly element: HTMLElement;
+  /** Per-thumb effective disabled (root-OR-thumb). */
+  readonly disabled: Signal<boolean>;
+  /** Set the thumb's value. Performs clamp + snap and invokes the per-thumb CVA. */
+  setValue(value: number, source: KjSliderSource): void;
+  /** Move keyboard focus to the thumb. */
+  focus(): void;
+}
+
+/**
+ * Shared context published by `[kjSlider]` and consumed by
+ * `[kjSliderTrack]`, `[kjSliderRange]`, `[kjSliderThumb]`, and
+ * `[kjSliderTick]`.
+ */
+export interface KjSliderContext {
+  // Bounds
+  readonly min: Signal<number>;
+  readonly max: Signal<number>;
+  readonly step: Signal<number>;
+  readonly pageStep: Signal<number>;
+  readonly stepBase: Signal<number>;
+
+  // Layout
+  readonly orientation: Signal<'horizontal' | 'vertical'>;
+  readonly direction: Signal<'ltr' | 'rtl'>;
+  readonly inverted: Signal<boolean>;
+
+  // Range coordination
+  readonly minDistance: Signal<number>;
+  readonly allowThumbCross: Signal<boolean>;
+
+  // State
+  readonly disabled: Signal<boolean>;
+  readonly readonly: Signal<boolean>;
+  readonly dragging: Signal<boolean>;
+  readonly activeThumbIndex: Signal<number | null>;
+
+  // Registry
+  readonly thumbs: Signal<readonly KjSliderThumbHandle[]>;
+
+  // Geometry (set by KjSliderTrack)
+  readonly trackElement: Signal<HTMLElement | null>;
+
+  // Tick definition
+  readonly ticks: Signal<readonly number[]>;
+
+  // Display / formatting
+  readonly displayWith: Signal<((value: number, thumbIndex: number) => string) | undefined>;
+
+  // Mutations
+  registerThumb(handle: KjSliderThumbHandle): void;
+  unregisterThumb(handle: KjSliderThumbHandle): void;
+  setTrackElement(el: HTMLElement | null): void;
+  setThumbValue(thumbIndex: number, value: number, source: KjSliderSource): void;
+  beginDrag(thumbIndex: number): void;
+  endDrag(cancelled?: boolean): void;
+  /** Returns the index of the thumb closest to `value`, ties resolved by side (`px` half). */
+  nearestThumbIndex(value: number): number;
+  /** Convert client coordinates (px) to a slider value, respecting orientation/RTL/inverted. */
+  valueFromClientPosition(clientX: number, clientY: number): number;
+}
+
+export const KJ_SLIDER = new InjectionToken<KjSliderContext>('KjSlider');

package/src/slider/slider.geometry.ts

@@ -0,0 +1,73 @@
+/**
+ * Pointer-to-value math for `[kjSlider]`. Pure functions kept outside the
+ * directive so they can be unit-tested without an Angular `TestBed`.
+ *
+ * Rules:
+ * - Horizontal LTR: `value = min + (px - left) / width * range`.
+ * - Horizontal RTL: invert the X axis before mapping.
+ * - Vertical: top of the track = `max`, bottom = `min`.
+ * - `inverted` flips the visual axis after the orientation/RTL transform.
+ * - Output is clamped to `[min, max]` but **not** snapped — snapping is the
+ *   directive's responsibility (it owns `kjStep` / `kjStepBase`).
+ */
+
+export interface KjSliderGeometryArgs {
+  readonly min: number;
+  readonly max: number;
+  readonly orientation: 'horizontal' | 'vertical';
+  readonly direction: 'ltr' | 'rtl';
+  readonly inverted: boolean;
+  readonly trackRect: DOMRect | DOMRectReadOnly;
+}
+
+/** Map client coordinates to a value in `[min, max]` (no snapping). */
+export function valueFromClientPosition(
+  clientX: number,
+  clientY: number,
+  args: KjSliderGeometryArgs,
+): number {
+  const { min, max, orientation, direction, inverted, trackRect } = args;
+  const range = max - min;
+  if (range <= 0) return min;
+
+  let fraction: number;
+  if (orientation === 'vertical') {
+    // top = max, bottom = min
+    const denom = trackRect.height || 1;
+    fraction = (trackRect.bottom - clientY) / denom;
+  } else {
+    const denom = trackRect.width || 1;
+    if (direction === 'rtl') {
+      fraction = (trackRect.right - clientX) / denom;
+    } else {
+      fraction = (clientX - trackRect.left) / denom;
+    }
+  }
+
+  if (inverted) fraction = 1 - fraction;
+
+  // Clamp the fraction first, then map. Avoids tiny FP drift past bounds.
+  if (fraction <= 0) return min;
+  if (fraction >= 1) return max;
+  const value = min + fraction * range;
+
+  // Coerce values within EPSILON*range of the bounds to the exact bound.
+  const eps = Number.EPSILON * range;
+  if (Math.abs(value - min) <= eps) return min;
+  if (Math.abs(value - max) <= eps) return max;
+  return value;
+}
+
+/** Position fraction `[0..1]` for a value, post-orientation/RTL/inverted. */
+export function fractionForValue(
+  value: number,
+  args: Pick<KjSliderGeometryArgs, 'min' | 'max' | 'inverted'>,
+): number {
+  const range = args.max - args.min;
+  if (range <= 0) return 0;
+  let f = (value - args.min) / range;
+  if (f < 0) f = 0;
+  else if (f > 1) f = 1;
+  if (args.inverted) f = 1 - f;
+  return f;
+}