# Feature: Slider Runtime

## Intent

Problem: `@seventh-ui/css` styles native range inputs, but the filled track and two-handle range segment need JavaScript synchronization.
Users or stakeholders: maintainers, app teams, QA, and future runtime package authors.
Desired outcome: provide a dependency-free helper that enhances existing DS Slider markup, syncs CSS custom properties, updates value text, coordinates simple ranges, and cleans up listeners.
Non-goals: replace native range inputs, implement a full custom drag engine, render arbitrary scale math, or own server-side validation.

## Scope

In scope: existing Slider markup, one-handle sliders, two-input range sliders, fill/range CSS variables, simple range pointer targeting, optional value formatting, active marks, focus/hover/pressed state classes, events, public methods, and cleanup.
Out of scope: generated layout for every visual variant, non-linear scales, tick snapping beyond native `step`, custom thumbs, remote persistence, and advanced collision rules.
Assumptions: visual styling comes from `@seventh-ui/css@1.0.2`; the CSS docs define Slider as CSS-first with native range behavior and helper-owned synchronization.
Dependencies: none beyond the local runtime core and `@seventh-ui/css` classes.

## Behavior

1. The controller must register on `[data-sui-slider]` and `[data-sui-component="slider"]`.
2. The controller must enhance existing `.sui-slider__control` range inputs instead of replacing native input behavior.
3. A single slider must sync `--sui-slider-fill-size` from `min`, `max`, and current `value`.
4. A range slider using `.sui-slider__range-control` with lower and upper inputs must sync `--sui-slider-range-start` and `--sui-slider-range-end`.
5. Range pointer interaction must choose the nearest lower or upper handle from pointer position so the lower handle remains reachable when inputs overlap.
6. When `clampRange` is not `false`, lower and upper values must not cross.
7. The controller must update `.sui-slider__value` with default, unit, template, or formatter output.
8. Numeric `.sui-slider__mark` or `[data-sui-slider-mark]` items must receive `.sui-slider__mark--active` and `aria-current` based on current value or range.
9. Focus, hover, and pressed interactions may synchronize `.sui-slider--focus`, `.sui-slider--hover`, and `.sui-slider--pressed` for DS state parity.
10. The runtime must emit `sui:slider:input`, `sui:slider:change`, and `sui:slider:render`.
11. Cleanup must remove listeners attached to inputs and document-level pointer handlers.

## Acceptance Examples

Scenario: sync single fill
Given a Slider has one range input with value `56`
When the runtime initializes
Then the input style contains `--sui-slider-fill-size: 56%` and the value label updates.

Scenario: react to input
Given the user moves a native range input
When the input event fires
Then fill size, value text, active marks, and `sui:slider:input` update.

Scenario: clamp range handles
Given a range slider has lower `20` and upper `80`
When the lower handle moves to `90`
Then lower is clamped to `80` and the selected range variables both read `80%`.

Scenario: target lower range handle
Given a range slider has lower `10` and upper `60`
When the user drags near the lower value on the range track
Then the lower input updates even when the upper input is visually stacked above it.

Scenario: keep native semantics
Given an application needs keyboard support
When it uses this runtime
Then the native input remains the interactive control.

## Data and Contracts

Inputs: a Slider root, existing DS markup, native range input values, runtime options, and optional per-instance options keyed by element id.
Outputs: synchronized inline CSS custom properties, updated value text, active marks, public controller methods, `data-sui-state`, and `sui:slider:*` events.
API/schema/event changes: exports `createSliderController`, Slider selectors, and `registerSlider`.
Persistence changes: none.

## Quality Attributes

Pragmatism: provide the synchronization CSS cannot do without turning Slider into a custom widget.
Accessibility: preserve native range input semantics and keyboard behavior.
Compatibility: avoid CSS source paths and preserve `.sui-*` visual classes.
Maintainability: keep range coordination simple and explicit.