@symbiote-native/slider 0.1.0

package/src/core/slider-state.ts

@@ -0,0 +1,112 @@
+// Slider: the logic half (framework-agnostic, zero render). Unlike Switch, the slider is NOT
+// controlled during a drag — the native view owns the thumb position and reports values up, so
+// there is no snap-back reducer. The shared logic is the pure prop folding the library's React
+// wrapper does before handing props to the native view: value sanitation, disabled/accessibility
+// resolution, limit defaulting, and the step-indicator option layout. Every adapter reuses these.
+
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import { SLIDER_LIMIT_MAX_VALUE, SLIDER_LIMIT_MIN_VALUE } from './constants';
+
+// The accessibilityState slice the disabled fold reads/writes. Only `disabled` is typed (the only
+// field the fold inspects) and NO index signature — so RN's IAccessibilityStateValue (which has no
+// index signature) assigns cleanly. Other state fields (selected/checked/…) are preserved at
+// RUNTIME by the resolve spread; the static type just doesn't track them.
+export type ISliderAccessibilityState = {
+  disabled?: boolean;
+};
+
+// Mirror the library's `passedValue`: NaN or a falsy value (incl. 0) becomes undefined, so the
+// native view falls back to its own default initial value rather than receiving NaN/0 as a
+// write. Entered once it still acts as the initial value (the slider is uncontrolled after).
+export function sanitizeSliderValue(value: number | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  return Number.isNaN(value) || !value ? undefined : value;
+}
+
+// Resolve the effective disabled flag exactly as the wrapper does: an explicit boolean wins,
+// else it falls back to accessibilityState.disabled.
+export function resolveSliderDisabled(
+  disabled: boolean | undefined,
+  accessibilityState: ISliderAccessibilityState | undefined,
+): boolean {
+  if (typeof disabled === 'boolean') return disabled;
+  return accessibilityState?.disabled === true;
+}
+
+// When `disabled` is given explicitly, fold it into accessibilityState so the native view and
+// the a11y tree agree; otherwise pass the caller's accessibilityState through untouched.
+export function resolveSliderAccessibilityState(
+  disabled: boolean | undefined,
+  accessibilityState: ISliderAccessibilityState | undefined,
+): ISliderAccessibilityState | undefined {
+  if (typeof disabled === 'boolean') return { ...accessibilityState, disabled };
+  return accessibilityState;
+}
+
+// Default the slide limits to the unbounded sentinels when unset (the native, non-web case).
+export function resolveSliderLowerLimit(lowerLimit: number | undefined): number {
+  return lowerLimit ?? SLIDER_LIMIT_MIN_VALUE;
+}
+
+export function resolveSliderUpperLimit(upperLimit: number | undefined): number {
+  return upperLimit ?? SLIDER_LIMIT_MAX_VALUE;
+}
+
+// The value the native value/sliding events carry as nativeEvent.value. nativeEvent is an
+// untyped Record, so narrow; a non-number payload yields undefined (no callback fired upstream).
+export function valueFromSliderEvent(event: ISymbioteEvent): number | undefined {
+  const value = event.nativeEvent.value;
+  return typeof value === 'number' ? value : undefined;
+}
+
+// A step overlay is rendered when the caller supplies a custom StepMarker OR opts into step
+// numbers, mirroring `props.StepMarker || !!props.renderStepNumber`.
+export function shouldRenderStepsIndicator(
+  hasStepMarker: boolean,
+  renderStepNumber: boolean | undefined,
+): boolean {
+  return hasStepMarker || renderStepNumber === true;
+}
+
+// With a thumbImage AND a custom StepMarker, the native thumb tint goes transparent so the
+// custom mark shows through; otherwise the caller's thumbTintColor stands. Kept `unknown` (not
+// IColorValue) since a color is an opaque value the engine's derived processor handles — the
+// fold only chooses between the input and the 'transparent' sentinel, never inspects the color.
+export function resolveThumbTintColor(
+  thumbTintColor: unknown,
+  hasStepMarker: boolean,
+  hasThumbImage: boolean,
+): unknown {
+  return hasThumbImage && hasStepMarker ? 'transparent' : thumbTintColor;
+}
+
+// The native view gets a thumbImage only when there is one AND no custom StepMarker (the marker
+// draws its own thumb); matches `props.StepMarker || !props.thumbImage ? undefined : <image>`.
+// The adapter still resolves the asset source (RN's Image.resolveAssetSource) when this is true.
+export function shouldPassNativeThumbImage(
+  hasStepMarker: boolean,
+  hasThumbImage: boolean,
+): boolean {
+  return hasThumbImage && !hasStepMarker;
+}
+
+// The library warns when the limits cross; surfaced as a pure predicate so the adapter logs it.
+export function isInvalidLimitConfig(lowerLimit: number, upperLimit: number): boolean {
+  return lowerLimit >= upperLimit;
+}
+
+// Lay out the step-indicator option values, mirroring the library's options array. With an
+// explicit step the points run min→max by step; with step 0 they spread `resolution`+1 points
+// evenly across the range. `resolution` is the platform-resolved fallback the adapter supplies
+// (ios 1000 / android 128), keeping this fn platform-invariant. Array.from floors a fractional
+// length, matching the library.
+export function computeStepOptions(
+  min: number,
+  max: number,
+  step: number,
+  resolution: number,
+): number[] {
+  const stepLength = step !== 0 ? step : (max - min) / resolution;
+  const count = (step !== 0 ? (max - min) / step : resolution) + 1;
+  return Array.from({ length: count }, (_, index) => min + index * stepLength);
+}

package/src/react/index.ts

@@ -0,0 +1,11 @@
+// @symbiote-native/slider/react: the React wrapper over the @react-native-community/slider native view.
+// Importing this barrel first registers the native view's ViewConfig (../register, a side-effect
+// import of the codegen spec — never the library's React Slider component), then exposes the
+// platform-split Slider. The public prop type is the agnostic base plus React's StepMarker render
+// component (Vue takes the same marker as a scoped slot). See ADR 0027.
+
+import '../register';
+
+export { Slider } from './slider';
+export type { ISliderProps } from './slider/shared';
+export type { IStepMarkerProps } from '../core';

package/src/react/slider/index.android.ts

@@ -0,0 +1,13 @@
+// Slider on Android: the native view sizes itself (no default height), lays out implicit steps at
+// 128-point resolution, and keeps the step row at the top. Mirrors the library's Android branches.
+
+import { createSlider } from './shared';
+import { SLIDER_STEP_RESOLUTION_ANDROID } from '../../core';
+
+const ANDROID_STEPS_CONTAINER_TOP = 0;
+
+export const Slider = createSlider({
+  defaultStyle: {},
+  stepResolution: SLIDER_STEP_RESOLUTION_ANDROID,
+  stepsContainerTop: ANDROID_STEPS_CONTAINER_TOP,
+});

package/src/react/slider/index.ios.ts

@@ -0,0 +1,14 @@
+// Slider on iOS: the native view has an intrinsic 40pt height (the wrapper applies it as the
+// default), lays out implicit steps at 1000-point resolution, and nudges the step row down 10pt.
+// Also the base (./index re-exports it) for headless. Mirrors the library's iOS branches.
+
+import { createSlider } from './shared';
+import { SLIDER_IOS_DEFAULT_HEIGHT, SLIDER_STEP_RESOLUTION_IOS } from '../../core';
+
+const IOS_STEPS_CONTAINER_TOP = 10;
+
+export const Slider = createSlider({
+  defaultStyle: { height: SLIDER_IOS_DEFAULT_HEIGHT },
+  stepResolution: SLIDER_STEP_RESOLUTION_IOS,
+  stepsContainerTop: IOS_STEPS_CONTAINER_TOP,
+});

package/src/react/slider/index.ts

@@ -0,0 +1,4 @@
+// Base entry for headless / tsc: re-exports the iOS variant (Metro picks index.ios / index.android
+// per platform via filename selection; this no-suffix file is what tsx/vitest resolve). ADR 0026.
+
+export { Slider } from './index.ios';

package/src/react/slider/shared.ts

@@ -0,0 +1,332 @@
+// Slider, the React lifecycle half. The logic (value/limit/disabled folds, the step-option layout)
+// and the native render live in @symbiote-native/slider core, shared verbatim with the Vue adapter; here
+// React supplies the lifecycle — useState for the last-reported value (to mark the active step)
+// and the measured width (for the step indicator), useEffect for the limit warning — plus the
+// descriptor bridge and forwardRef to the native view (matching the library's forwardRef). The
+// native RNCSlider carries no symbiote metadata: the engine derives its events and color/image
+// processors from the library's ViewConfig, registered by ../register (the package barrel pulls
+// it). This is the React twin of the Vue wrapper; both drive the engine, NEITHER imports the
+// library's React Slider component. See CLAUDE.md <third_party_rn_packages_are_react_only>, ADR 0027.
+
+import { createElement, forwardRef, useCallback, useEffect, useState } from 'react';
+import type {
+  FC,
+  ForwardRefExoticComponent,
+  PropsWithoutRef,
+  ReactElement,
+  RefAttributes,
+} from 'react';
+import { descriptorToReact, Image } from '@symbiote-native/react';
+import { resolveAccessibilityProps } from '@symbiote-native/components';
+import type { IDescriptor, IDescriptorChild, IImageSourceProp } from '@symbiote-native/components';
+import { dlog, type ISymbioteEvent, type ISymbioteNode } from '@symbiote-native/engine';
+import {
+  sanitizeSliderValue,
+  resolveSliderDisabled,
+  resolveSliderAccessibilityState,
+  resolveSliderLowerLimit,
+  resolveSliderUpperLimit,
+  valueFromSliderEvent,
+  shouldRenderStepsIndicator,
+  resolveThumbTintColor,
+  shouldPassNativeThumbImage,
+  isInvalidLimitConfig,
+  computeStepOptions,
+  orderStepOptions,
+  stepNumberFontSize,
+  renderSlider,
+  renderSliderNative,
+  resolveStepsContainerStyle,
+  renderStepsIndicator,
+  STEP_INDICATOR_ELEMENT_STYLE,
+  TRACK_MARK_CONTAINER_STYLE,
+  THUMB_IMAGE_CONTAINER_STYLE,
+  THUMB_IMAGE_STYLE,
+  STEP_NUMBER_CONTAINER_STYLE,
+  SLIDER_DEFAULT_MINIMUM_VALUE,
+  SLIDER_DEFAULT_MAXIMUM_VALUE,
+  SLIDER_DEFAULT_STEP,
+  SLIDER_ON_CHANGE,
+  SLIDER_ON_VALUE_CHANGE,
+  SLIDER_ON_SLIDING_START,
+  SLIDER_ON_SLIDING_COMPLETE,
+  SLIDER_ON_ACCESSIBILITY_ACTION,
+  type ISliderPlatform,
+  type ISliderProps as ISliderBaseProps,
+  type ISliderViewProps,
+  type IStepMarkerProps,
+} from '../../core';
+
+// React's flavored prop type: the agnostic base plus the per-adapter StepMarker — a render
+// component returning a React element, which (per CLAUDE.md <prop_types_split_agnostic_vs_per_adapter>)
+// cannot live in the shared layer. Same name as the agnostic base by the split convention (cf.
+// IPressableProps declared per-adapter); Vue takes the same marker as a `#stepMarker` scoped slot.
+export interface ISliderProps extends ISliderBaseProps {
+  StepMarker?: FC<IStepMarkerProps>;
+  // Forwarded onto the OUTER wrapper View, like `style` (resolveSliderWrapperStyle) — resolves
+  // through the shared style registry. Explicitly destructured below, not left in `...passthrough`,
+  // which lands on the INNER native RNCSlider leaf (renderSliderNative) — the same wrapper/inner
+  // routing bug ImageBackground was fixed for.
+  className?: string;
+}
+
+type ISliderComponent = ForwardRefExoticComponent<
+  PropsWithoutRef<ISliderProps> & RefAttributes<ISymbioteNode>
+>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function toChild(child: IDescriptorChild): ReactElement | string {
+  return typeof child === 'string' ? child : descriptorToReact(child);
+}
+
+// renderSlider's Descriptor IS the outer wrapper (symbiote-view hosting the native leaf +
+// optional steps overlay); className is reapplied on it here, exactly like ImageBackground's
+// wrapper.
+function withClassName(descriptor: IDescriptor, className: string | undefined): ReactElement {
+  return createElement(
+    descriptor.type,
+    { key: descriptor.key, ...descriptor.props, className },
+    ...descriptor.children.map(toChild),
+  );
+}
+
+export function createSlider(platform: ISliderPlatform): ISliderComponent {
+  return forwardRef<ISymbioteNode, ISliderProps>((rawProps, forwardedRef) => {
+    // Slider owns its host wrapper rather than rendering through a symbiote View, so it folds
+    // aria/role into accessibility* here; the rest (testID, accessibilityLabel, accessibility-
+    // Actions, …) rides to the native node via `passthrough`.
+    const props = resolveAccessibilityProps(rawProps);
+    const {
+      value,
+      minimumValue,
+      maximumValue,
+      step,
+      lowerLimit,
+      upperLimit,
+      disabled,
+      inverted,
+      thumbTintColor,
+      thumbImage,
+      accessibilityState,
+      renderStepNumber,
+      style,
+      className,
+      StepMarker,
+      onValueChange,
+      onSlidingStart,
+      onSlidingComplete,
+      onAccessibilityAction,
+      ...passthrough
+    } = props;
+
+    const [reportedValue, setReportedValue] = useState<number | undefined>(undefined);
+    const [width, setWidth] = useState(0);
+
+    const handleValueChange = useCallback(
+      (event: ISymbioteEvent): void => {
+        const next = valueFromSliderEvent(event);
+        if (next === undefined) return;
+        setReportedValue(next);
+        onValueChange?.(next);
+      },
+      [onValueChange],
+    );
+    const handleSlidingStart = useCallback(
+      (event: ISymbioteEvent): void => {
+        const next = valueFromSliderEvent(event);
+        if (next !== undefined) onSlidingStart?.(next);
+      },
+      [onSlidingStart],
+    );
+    const handleSlidingComplete = useCallback(
+      (event: ISymbioteEvent): void => {
+        const next = valueFromSliderEvent(event);
+        if (next !== undefined) onSlidingComplete?.(next);
+      },
+      [onSlidingComplete],
+    );
+    const handleAccessibilityAction = useCallback(
+      (event: ISymbioteEvent): void => {
+        onAccessibilityAction?.(event);
+      },
+      [onAccessibilityAction],
+    );
+    const handleLayout = useCallback((event: ISymbioteEvent): void => {
+      const layout = event.nativeEvent.layout;
+      if (isRecord(layout) && typeof layout.width === 'number') setWidth(layout.width);
+    }, []);
+
+    const minimum = minimumValue ?? SLIDER_DEFAULT_MINIMUM_VALUE;
+    const maximum = maximumValue ?? SLIDER_DEFAULT_MAXIMUM_VALUE;
+    const stepValue = step ?? SLIDER_DEFAULT_STEP;
+    const lower = resolveSliderLowerLimit(lowerLimit);
+    const upper = resolveSliderUpperLimit(upperLimit);
+
+    useEffect(() => {
+      if (isInvalidLimitConfig(lower, upper))
+        dlog('Slider: lowerLimit must be smaller than upperLimit');
+    }, [lower, upper]);
+
+    const hasStepMarker = StepMarker !== undefined;
+    const hasThumbImage = thumbImage !== undefined;
+    const showSteps = shouldRenderStepsIndicator(hasStepMarker, renderStepNumber);
+    // Passed to the native view raw — the engine runs the image processor derived from RNCSlider's
+    // ViewConfig — and only when no custom marker draws its own thumb (matches the library).
+    const nativeThumbImage = shouldPassNativeThumbImage(hasStepMarker, hasThumbImage)
+      ? thumbImage
+      : undefined;
+
+    const view: ISliderViewProps = {
+      value: sanitizeSliderValue(value),
+      minimumValue: minimum,
+      maximumValue: maximum,
+      step: stepValue,
+      lowerLimit: lower,
+      upperLimit: upper,
+      disabled: resolveSliderDisabled(disabled, accessibilityState),
+      inverted: inverted ?? false,
+      thumbTintColor: resolveThumbTintColor(thumbTintColor, hasStepMarker, hasThumbImage),
+      thumbImage: nativeThumbImage,
+      accessibilityState: resolveSliderAccessibilityState(disabled, accessibilityState),
+      width,
+      style,
+      passthrough: {
+        ...passthrough,
+        ref: forwardedRef,
+        [SLIDER_ON_CHANGE]: handleValueChange,
+        [SLIDER_ON_VALUE_CHANGE]: handleValueChange,
+        [SLIDER_ON_SLIDING_START]: handleSlidingStart,
+        [SLIDER_ON_SLIDING_COMPLETE]: handleSlidingComplete,
+        [SLIDER_ON_ACCESSIBILITY_ACTION]: handleAccessibilityAction,
+      },
+    };
+
+    if (!showSteps) {
+      return withClassName(renderSlider(view, platform, { onLayout: handleLayout }), className);
+    }
+
+    const options = computeStepOptions(minimum, maximum, stepValue, platform.stepResolution);
+    const currentValue = reportedValue ?? view.value ?? minimum;
+
+    if (StepMarker !== undefined) {
+      const overlay = renderCustomStepsOverlay({
+        options,
+        currentValue,
+        inverted: view.inverted,
+        renderStepNumber: renderStepNumber === true,
+        thumbImage,
+        width,
+        platform,
+        StepMarker,
+      });
+      return createElement(
+        'symbiote-view',
+        { style: resolveStepsWrapperStyle(style, platform), onLayout: handleLayout, className },
+        overlay,
+        descriptorToReact(renderSliderNative(view, platform)),
+      );
+    }
+
+    const steps = renderStepsIndicator({
+      options,
+      currentValue,
+      width,
+      renderStepNumber: renderStepNumber === true,
+      thumbImage,
+      inverted: view.inverted,
+      platform,
+    });
+    return withClassName(
+      renderSlider(view, platform, { steps, onLayout: handleLayout }),
+      className,
+    );
+  });
+}
+
+// The wrapper style for the custom-marker steps path mirrors renderSlider's wrapper.
+function resolveStepsWrapperStyle(style: unknown, platform: ISliderPlatform): unknown {
+  return [platform.defaultStyle, style, { justifyContent: 'center' }];
+}
+
+type ICustomStepsParams = {
+  options: readonly number[];
+  currentValue: number;
+  inverted: boolean;
+  renderStepNumber: boolean;
+  thumbImage: IImageSourceProp | undefined;
+  width: number;
+  platform: ISliderPlatform;
+  StepMarker: FC<IStepMarkerProps>;
+};
+
+// The custom-marker overlay: the same flex row as the agnostic default, each mark hosting the
+// user's StepMarker element (plus the thumbImage on the current step and the optional step
+// number), mirroring the library's SliderTrackMark composition.
+function renderCustomStepsOverlay(params: ICustomStepsParams): ReactElement {
+  const fontSize = stepNumberFontSize(params.options.length);
+  const ordered = orderStepOptions(params.options, params.inverted);
+  const min = params.options[0];
+  const max = params.options[params.options.length - 1];
+  const cells = ordered.map((value, index) => {
+    const trackChildren: ReactElement[] = [
+      createElement(params.StepMarker, {
+        key: 'marker',
+        stepMarked: value === params.currentValue,
+        currentValue: params.currentValue,
+        index,
+        min,
+        max,
+      }),
+    ];
+    if (params.thumbImage !== undefined && value === params.currentValue) {
+      trackChildren.push(
+        createElement(
+          'symbiote-view',
+          {
+            key: 'thumb',
+            style: THUMB_IMAGE_CONTAINER_STYLE,
+            testID: 'sliderTrackMark-thumbImage',
+          },
+          createElement(Image, { source: params.thumbImage, style: THUMB_IMAGE_STYLE }),
+        ),
+      );
+    }
+    const cellChildren: ReactElement[] = [
+      createElement(
+        'symbiote-view',
+        { key: 'track', style: TRACK_MARK_CONTAINER_STYLE },
+        ...trackChildren,
+      ),
+    ];
+    if (params.renderStepNumber) {
+      cellChildren.push(
+        createElement(
+          'symbiote-view',
+          { key: 'number', style: STEP_NUMBER_CONTAINER_STYLE },
+          createElement(
+            'symbiote-text',
+            { testID: `${index}th-step`, style: { fontSize } },
+            String(value),
+          ),
+        ),
+      );
+    }
+    return createElement(
+      'symbiote-view',
+      { key: index, style: STEP_INDICATOR_ELEMENT_STYLE },
+      ...cellChildren,
+    );
+  });
+  return createElement(
+    'symbiote-view',
+    {
+      pointerEvents: 'none',
+      testID: 'StepsIndicator-Container',
+      style: resolveStepsContainerStyle(params.width, params.platform),
+    },
+    ...cells,
+  );
+}