@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Selector/Selector.tsx

@@ -0,0 +1,206 @@
+import * as stylex from '@stylexjs/stylex';
+import type {ChangeEvent, ReactNode, SelectHTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useFieldControl} from '../Field/index.js';
+
+const styles = stylex.create({
+  // An input sinks below the card it sits on, and a select is an input: the
+  // muted fill and the strong hairline are what put it on the same rung as the
+  // text fields it shares a form with. Painted on `colorSurface` it read as a
+  // card among wells.
+  // The well is the frame, because the mark that says "this opens" is ours
+  // now. Left native, a select wore whichever arrow the platform draws — a
+  // blue chevron on one, a grey triangle on another — in the corner of a
+  // field this system had otherwise drawn to the hairline.
+  frame: {
+    alignItems: 'stretch',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    display: 'flex',
+    height: semanticTokens.sizeControlMd,
+    overflow: 'hidden',
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    width: '100%',
+    ':focus-within': {
+      borderColor: semanticTokens.borderInteractive,
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover': {borderColor: semanticTokens.borderInteractive},
+  },
+  frameDisabled: {
+    backgroundColor: semanticTokens.colorDisabledSurface,
+    borderColor: semanticTokens.borderDisabled,
+    ':hover': {borderColor: semanticTokens.borderDisabled},
+  },
+  frameInvalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-within': {borderColor: semanticTokens.statusDangerText},
+    ':hover': {borderColor: semanticTokens.statusDangerText},
+  },
+  // The chevron: two edges of an empty square stood on a corner, the same way
+  // the checkbox draws its tick and the number field its steps. It takes its
+  // colour from the palette, which is the whole point of not letting the
+  // engine draw it. `aria-hidden`, because the select already announces that
+  // it is a select.
+  chevron: {
+    borderBlockEndColor: semanticTokens.colorTextSecondary,
+    borderBlockEndStyle: semanticTokens.borderStyle,
+    borderBlockEndWidth: semanticTokens.borderWidth,
+    borderInlineEndColor: semanticTokens.colorTextSecondary,
+    borderInlineEndStyle: semanticTokens.borderStyle,
+    borderInlineEndWidth: semanticTokens.borderWidth,
+    blockSize: semanticTokens.spacingSm,
+    inlineSize: semanticTokens.spacingSm,
+    insetBlockStart: '50%',
+    insetInlineEnd: semanticTokens.spacingSm,
+    pointerEvents: 'none',
+    position: 'absolute',
+    transform: 'translateY(-70%) rotate(45deg)',
+  },
+  chevronDisabled: {
+    borderBlockEndColor: semanticTokens.colorDisabledText,
+    borderInlineEndColor: semanticTokens.colorDisabledText,
+  },
+  control: {
+    appearance: 'none',
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorText,
+    cursor: 'pointer',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingBlock: semanticTokens.spacingXs,
+    // Trailing room for the chevron: without it the longest option ran under
+    // the mark that says the field opens.
+    paddingInlineEnd: `calc(${semanticTokens.spacingSm} + ${semanticTokens.spacingLg})`,
+    paddingInlineStart: semanticTokens.spacingSm,
+    width: '100%',
+    ':disabled': {color: semanticTokens.colorDisabledText, cursor: 'default'},
+    ':focus-visible': {outlineStyle: 'none'},
+  },
+  invalid: {
+    borderColor: semanticTokens.statusDangerText,
+    ':focus-visible': {borderColor: semanticTokens.statusDangerText},
+    ':hover:not(:disabled)': {borderColor: semanticTokens.statusDangerText},
+  },
+});
+
+/** One option in a `Selector`. */
+export interface SelectorOption {
+  readonly disabled?: boolean;
+  readonly label: ReactNode;
+  readonly value: string;
+}
+
+type SharedSelectorProps = Omit<
+  SelectHTMLAttributes<HTMLSelectElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange' | 'value'
+> & {
+  readonly onValueChange?: (value: string) => void;
+  readonly options: readonly SelectorOption[];
+  readonly placeholder?: string;
+};
+
+type ControlledSelectorProps = SharedSelectorProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: string) => void;
+  readonly value: string;
+};
+
+type UncontrolledSelectorProps = SharedSelectorProps & {
+  readonly defaultValue?: string;
+  readonly value?: never;
+};
+
+/** Props for choosing one option from a closed list. */
+export type SelectorProps = ControlledSelectorProps | UncontrolledSelectorProps;
+
+/**
+ * Chooses one option from a closed list using the native control, so the
+ * platform supplies its own keyboard, touch, and screen-reader behaviour.
+ */
+export function Selector({
+  'aria-describedby': ariaDescribedBy,
+  'aria-invalid': ariaInvalid,
+  disabled,
+  id,
+  onValueChange,
+  options,
+  placeholder,
+  required,
+  ...props
+}: SelectorProps) {
+  const field = useFieldControl();
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+  const resolvedInvalid = ariaInvalid ?? field?.invalid;
+  const invalid =
+    resolvedInvalid !== undefined &&
+    resolvedInvalid !== false &&
+    resolvedInvalid !== 'false';
+
+  function handleChange(event: ChangeEvent<HTMLSelectElement>) {
+    onValueChange?.(event.currentTarget.value);
+  }
+
+  return (
+    <span
+      {...stylex.props(
+        styles.frame,
+        invalid && !disabled ? styles.frameInvalid : undefined,
+        disabled ? styles.frameDisabled : undefined,
+      )}
+    >
+      <select
+        {...props}
+        aria-describedby={describedBy}
+        aria-invalid={resolvedInvalid}
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        onChange={handleChange}
+        required={required ?? field?.required}
+        {...stylex.props(styles.control)}
+      >
+        {placeholder === undefined ? null : (
+          <option disabled value="">
+            {placeholder}
+          </option>
+        )}
+        {options.map(
+          ({disabled: optionDisabled, label, value: optionValue}) => (
+            <option
+              disabled={optionDisabled ?? false}
+              key={optionValue}
+              value={optionValue}
+            >
+              {label}
+            </option>
+          ),
+        )}
+      </select>
+      <span
+        aria-hidden="true"
+        {...stylex.props(
+          styles.chevron,
+          disabled ? styles.chevronDisabled : undefined,
+        )}
+      />
+    </span>
+  );
+}

package/src/Selector/index.ts

@@ -0,0 +1 @@
+export {Selector, type SelectorOption, type SelectorProps} from './Selector.js';

package/src/SideNav/SideNav.doc.ts

@@ -0,0 +1,29 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const sideNavDoc = {
+  name: 'SideNav',
+  description: 'Holds persistent navigation beside the main content.',
+  props: [
+    {name: 'children', description: 'Supplies the navigation sections.'},
+    {name: 'footer', description: 'Pins content to the end of the rail.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example: '<SideNav><SideNavSection title="Work">…</SideNavSection></SideNav>',
+  storyId: 'core-side-nav--default',
+} satisfies ComponentDoc;
+
+export const sideNavSectionDoc = {
+  name: 'SideNavSection',
+  description: 'Groups related destinations under an optional heading.',
+  props: [
+    {name: 'children', description: 'Supplies the destinations.'},
+    {name: 'title', description: 'Names the group.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and title',
+  ],
+  example: '<SideNavSection title="Work">…</SideNavSection>',
+  storyId: 'core-side-nav--default',
+} satisfies ComponentDoc;

package/src/SideNav/SideNav.tsx

@@ -0,0 +1,110 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// A rail wide enough for two words and a glyph. The scale cannot name it, so
+// it is built from the scale rather than written as a length.
+const railWidth = `calc(9 * ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  // The rail is the binding edge of the same sheet the page is printed on, not
+  // a panel standing on it: the strong rule down its inline end is the fold,
+  // and it is the only thing that parts the two. A `colorSurface` rail put the
+  // navigation on the same rung as the cards it leads to.
+  rail: {
+    backgroundColor: semanticTokens.colorCanvas,
+    borderInlineEndColor: semanticTokens.borderStrong,
+    borderInlineEndStyle: semanticTokens.borderStyle,
+    borderInlineEndWidth: semanticTokens.borderWidth,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    rowGap: semanticTokens.spacingLg,
+    paddingBlockEnd: semanticTokens.spacingLg,
+    paddingBlockStart: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingMd,
+    width: railWidth,
+  },
+  // An eyebrow: the smallest size, opened right up, in the second rank of ink
+  // and cut in the display face — group labels and table headers are the two
+  // places this system sets mincho, because a run of destinations wants a
+  // caption above it rather than another destination. It is indented to the
+  // destinations' own text, so the labels and the words they name share a
+  // margin and the selection mark keeps the edge to itself.
+  heading: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSize: semanticTokens.fontSizeXs,
+    fontSynthesis: 'none',
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+    paddingBlockEnd: semanticTokens.spacingXs,
+    paddingInlineEnd: 0,
+    paddingInlineStart: semanticTokens.spacingMd,
+  },
+  // The rows tile: one hairline apart, so the run reads as a single column of
+  // destinations rather than a stack of separated buttons.
+  section: {
+    display: 'flex',
+    flexDirection: 'column',
+    rowGap: semanticTokens.borderWidth,
+  },
+  // `auto` pins the block to the end of the rail; it is a position, not the
+  // gutter between siblings, which the rail's own gap already owns.
+  footer: {
+    borderBlockStartColor: semanticTokens.borderDefault,
+    borderBlockStartStyle: semanticTokens.borderStyle,
+    borderBlockStartWidth: semanticTokens.borderWidth,
+    marginBlockStart: 'auto',
+    paddingBlockStart: semanticTokens.spacingMd,
+  },
+});
+
+/** Props for the vertical navigation rail. */
+export interface SideNavProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className'
+> {
+  readonly children: ReactNode;
+  readonly footer?: ReactNode;
+}
+
+/** Holds persistent navigation beside the main content. */
+export function SideNav({children, footer, ...props}: SideNavProps) {
+  return (
+    <div {...props} {...stylex.props(styles.rail)}>
+      {children}
+      {footer === undefined ? null : (
+        <div {...stylex.props(styles.footer)}>{footer}</div>
+      )}
+    </div>
+  );
+}
+
+/** Props for one titled group inside a `SideNav`. */
+export interface SideNavSectionProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'title'
+> {
+  readonly children: ReactNode;
+  readonly title?: ReactNode;
+}
+
+/** Groups related destinations under an optional heading. */
+export function SideNavSection({
+  children,
+  title,
+  ...props
+}: SideNavSectionProps) {
+  return (
+    <div {...props} {...stylex.props(styles.section)}>
+      {title === undefined ? null : (
+        <p {...stylex.props(styles.heading)}>{title}</p>
+      )}
+      {children}
+    </div>
+  );
+}

package/src/SideNav/index.ts

@@ -0,0 +1,6 @@
+export {
+  SideNav,
+  SideNavSection,
+  type SideNavProps,
+  type SideNavSectionProps,
+} from './SideNav.js';

package/src/Skeleton/Skeleton.doc.ts

@@ -3,7 +3,7 @@ import type {ComponentDoc} from '../docs/types.js';
 export const skeletonDoc = {
   name: 'Skeleton',
   description:
-    'Displays a decorative or explicitly labelled loading placeholder with a static reduced-motion fallback.',
+    'Displays a decorative or explicitly labelled loading placeholder as a still bar that never pulses.',
   props: [
     {name: 'label', description: 'Optionally announces what is loading.'},
   ],

package/src/Skeleton/Skeleton.tsx

@@ -3,23 +3,16 @@ import type {HTMLAttributes} from 'react';
 
 import {semanticTokens} from '../authoring.stylex.js';
 
-const pulse = stylex.keyframes({
-  '50%': {backgroundColor: semanticTokens.colorSurface},
-});
-
 const styles = stylex.create({
+  // A bar of timber standing in for ink that has not dried yet. It does not
+  // breathe, shimmer or travel: a page of placeholders that pulses turns the
+  // wait into the loudest thing on the screen, and the placeholder's whole job
+  // is to hold a line quietly until the line arrives.
   base: {
-    animationDirection: 'alternate',
-    animationDuration: semanticTokens.durationSlow,
-    animationIterationCount: 'infinite',
-    animationName: {
-      default: pulse,
-      '@media (prefers-reduced-motion: reduce)': 'none',
-    },
-    animationTimingFunction: semanticTokens.easingStandard,
     backgroundColor: semanticTokens.colorSurfaceMuted,
     borderRadius: semanticTokens.radiusElement,
-    minHeight: semanticTokens.sizeControlMd,
+    // The rule of type it stands in for, not the control it might become.
+    minHeight: semanticTokens.spacingMd,
     width: '100%',
   },
 });

package/src/Slider/Slider.doc.ts

@@ -0,0 +1,24 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const sliderDoc = {
+  name: 'Slider',
+  description: 'Chooses a number along a visible range.',
+  props: [
+    {name: 'defaultValue', description: 'Sets the initial uncontrolled value.'},
+    {
+      name: 'formatValue',
+      description: 'Supplies the text shown and announced for a value.',
+    },
+    {name: 'max', description: 'Sets the upper bound of the range.'},
+    {name: 'min', description: 'Sets the lower bound of the range.'},
+    {name: 'onValueChange', description: 'Receives the newly chosen number.'},
+    {name: 'step', description: 'Sets the increment between allowed values.'},
+    {name: 'value', description: 'Controls the current number.'},
+  ],
+  inheritedProps: [
+    'InputHTMLAttributes<HTMLInputElement> except children, className, defaultValue, onChange, type, and value',
+  ],
+  example:
+    '<Slider formatValue={(v) => `${v} percent`} onValueChange={setLevel} value={level} />',
+  storyId: 'core-slider--default',
+} satisfies ComponentDoc;

package/src/Slider/Slider.tsx

@@ -0,0 +1,264 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useState,
+  type ChangeEvent,
+  type CSSProperties,
+  type InputHTMLAttributes,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {useFieldControl} from '../Field/index.js';
+import {clamp} from '../utils/index.js';
+
+/*
+ * A range control is drawn by the engine, and each engine exposes its own
+ * pseudo-elements for the parts and ignores the other's — hence the doubled
+ * declarations. `appearance: 'none'` on the input is what hands authorship
+ * over: without it WebKit keeps painting its own thumb and the one declared
+ * here is ignored outright.
+ *
+ * The filled portion is a gradient on the track rather than a native part,
+ * because only Gecko exposes one (`::-moz-range-progress`) and WebKit has no
+ * counterpart. Painting it the same way in both engines makes them agree by
+ * construction; the Gecko part is then held transparent so it cannot lay a
+ * second fill over the gradient. Styling the track at all also stops WebKit
+ * painting the `accent-color` fill it would otherwise draw, so `accentColor`
+ * has nothing left to colour and is gone.
+ *
+ * The stop position is data — the current value — so it arrives as an inline
+ * custom property, the way `ProgressBar` carries its width.
+ */
+const progressProperty = '--kioku-ui-slider-progress';
+// CSS has no logical direction keyword for a gradient, so this is physical.
+// Under `direction: rtl` the engine flips the control but not the gradient,
+// and the fill would sit on the wrong side.
+//
+// Written out twice rather than built by a helper. StyleX statically evaluates
+// every identifier a style refers to, and a function is not something it can
+// evaluate: a two-argument helper compiled fine through the CLI and failed the
+// consumer that builds this package from source, which is the build that
+// matters because it is the one a user of the library runs.
+const restFill = `linear-gradient(to right, ${semanticTokens.colorAccent} 0 var(${progressProperty}, 0%), ${semanticTokens.colorSurfaceMuted} var(${progressProperty}, 0%) 100%)`;
+const disabledFill = `linear-gradient(to right, ${semanticTokens.colorDisabledText} 0 var(${progressProperty}, 0%), ${semanticTokens.colorDisabledSurface} var(${progressProperty}, 0%) 100%)`;
+
+// The knob's size is a relationship to the rule it rides, not a token that
+// happens to look right: the track plus one spacing step of relief on each
+// side, so it always covers the rule and always overhangs it by the same
+// amount. WebKit then lays it out in flow on top of the track rather than
+// centring it, so it is pulled back by half the difference between the two.
+const trackThickness = semanticTokens.spacingSm;
+const thumbRelief = semanticTokens.spacingXs;
+const thumbSize = `calc(${trackThickness} + ${thumbRelief} * 2)`;
+const thumbCentring = `calc((${trackThickness} - ${thumbSize}) / 2)`;
+
+const styles = stylex.create({
+  // The control and the figure it reports are one field, so the gap between
+  // them belongs to this container rather than to a margin on either.
+  field: {
+    alignItems: 'center',
+    display: 'flex',
+    gap: semanticTokens.spacingSm,
+  },
+  /*
+   * The value, in the mono face with tabular figures. A slider that does not
+   * say where it is stopped is a control you have to guess at, and a
+   * proportional readout re-flows the row by a hair on every step, which reads
+   * as a wobble. It is secondary ink: it reports the control, it is not the
+   * control. `aria-hidden` because the input already announces the same value
+   * through `aria-valuetext`.
+   */
+  readout: {
+    color: semanticTokens.colorTextSecondary,
+    flexShrink: 0,
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeSm,
+    fontVariantNumeric: 'tabular-nums',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+    textAlign: 'end',
+  },
+  // Muted, not disabled-text: the track and thumb already carry the disabled
+  // paint, and a figure nobody can read is not a softer figure, it is a lost
+  // one. Disabled-text on this theme's canvas is 3.85:1.
+  readoutDisabled: {color: semanticTokens.colorTextMuted},
+  /*
+   * There is deliberately no hover state. Every visible part is drawn by the
+   * engine, so a hover would have to hand-roll a ring shadow, which rule 2
+   * forbids — depth here is a hairline, not an invented one. A native range
+   * has no hover affordance worth inventing, and `:focus-visible` plus the
+   * disabled treatment carry the state matrix in both engines.
+   */
+  control: {
+    appearance: 'none',
+    backgroundColor: 'transparent',
+    blockSize: semanticTokens.sizeHitTarget,
+    cursor: 'pointer',
+    flexShrink: 1,
+    inlineSize: '100%',
+    marginBlock: 0,
+    marginInline: 0,
+    minInlineSize: 0,
+    '::-webkit-slider-runnable-track': {
+      backgroundColor: semanticTokens.colorSurfaceMuted,
+      backgroundImage: restFill,
+      blockSize: trackThickness,
+      borderRadius: semanticTokens.radiusFull,
+    },
+    '::-webkit-slider-thumb': {
+      appearance: 'none',
+      backgroundColor: semanticTokens.colorSurface,
+      blockSize: thumbSize,
+      borderRadius: semanticTokens.radiusFull,
+      boxShadow: semanticTokens.elevationLow,
+      inlineSize: thumbSize,
+      marginBlockStart: thumbCentring,
+    },
+    '::-moz-range-track': {
+      backgroundColor: semanticTokens.colorSurfaceMuted,
+      backgroundImage: restFill,
+      blockSize: trackThickness,
+      borderRadius: semanticTokens.radiusFull,
+    },
+    // Held transparent so Gecko's own filled part cannot paint over the
+    // gradient the track already carries.
+    '::-moz-range-progress': {backgroundColor: 'transparent'},
+    '::-moz-range-thumb': {
+      backgroundColor: semanticTokens.colorSurface,
+      blockSize: thumbSize,
+      borderRadius: semanticTokens.radiusFull,
+      borderStyle: 'none',
+      borderWidth: 0,
+      boxShadow: semanticTokens.elevationLow,
+      inlineSize: thumbSize,
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  // The engine draws every visible part, so a disabled slider has to restate
+  // them rather than tint the element. Driven from React, not from a selector.
+  // The fill stays legible: a disabled slider still reports its value.
+  disabled: {
+    cursor: 'default',
+    '::-webkit-slider-runnable-track': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      backgroundImage: disabledFill,
+    },
+    '::-webkit-slider-thumb': {
+      backgroundColor: semanticTokens.colorDisabledText,
+      boxShadow: 'none',
+    },
+    '::-moz-range-track': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      backgroundImage: disabledFill,
+    },
+    '::-moz-range-thumb': {
+      backgroundColor: semanticTokens.colorDisabledText,
+      boxShadow: 'none',
+    },
+  },
+});
+
+type SharedSliderProps = Omit<
+  InputHTMLAttributes<HTMLInputElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange' | 'type' | 'value'
+> & {
+  readonly formatValue?: (value: number) => string;
+  readonly max?: number;
+  readonly min?: number;
+  readonly onValueChange?: (value: number) => void;
+  readonly step?: number;
+};
+
+type ControlledSliderProps = SharedSliderProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: number) => void;
+  readonly value: number;
+};
+
+type UncontrolledSliderProps = SharedSliderProps & {
+  readonly defaultValue?: number;
+  readonly value?: never;
+};
+
+/** Props for choosing a number along a visible range. */
+export type SliderProps = ControlledSliderProps | UncontrolledSliderProps;
+
+/**
+ * Chooses a number along a visible range, and states where it is stopped in
+ * tabular figures beside the track. `formatValue` supplies both that figure and
+ * the spoken text, so "40 percent" can be read and announced where the raw
+ * number would not help.
+ */
+export function Slider({
+  'aria-describedby': ariaDescribedBy,
+  defaultValue,
+  disabled,
+  formatValue,
+  id,
+  max = 100,
+  min = 0,
+  onValueChange,
+  step = 1,
+  style,
+  value,
+  ...props
+}: SliderProps) {
+  const field = useFieldControl();
+  const [internalValue, setInternalValue] = useState(defaultValue ?? min);
+  const current = value ?? internalValue;
+  const describedBy =
+    [field?.describedBy, ariaDescribedBy].filter(Boolean).join(' ') ||
+    undefined;
+
+  // Measured from the value the input itself renders, so a controlled and an
+  // uncontrolled slider fill alike, and clamped so a value outside the bounds
+  // cannot put the gradient stop past either end.
+  const span = max - min;
+  const filled = span > 0 ? ((clamp(current, min, max) - min) / span) * 100 : 0;
+
+  function handleChange(event: ChangeEvent<HTMLInputElement>) {
+    const next = Number(event.currentTarget.value);
+    if (value === undefined) {
+      setInternalValue(next);
+    }
+    onValueChange?.(next);
+  }
+
+  return (
+    <span {...stylex.props(styles.field)}>
+      <input
+        {...props}
+        aria-describedby={describedBy}
+        {...(formatValue ? {'aria-valuetext': formatValue(current)} : {})}
+        disabled={disabled}
+        id={field?.controlId ?? id}
+        max={max}
+        min={min}
+        onChange={handleChange}
+        step={step}
+        {...stylex.props(
+          styles.control,
+          disabled ? styles.disabled : undefined,
+        )}
+        // The stop position is data, so it stays inline — after stylex.props,
+        // which would otherwise overwrite the style attribute it is carried in.
+        style={{...style, [progressProperty]: `${filled}%`} as CSSProperties}
+        type="range"
+        value={current}
+      />
+      <span
+        aria-hidden="true"
+        {...stylex.props(
+          styles.readout,
+          disabled ? styles.readoutDisabled : undefined,
+        )}
+      >
+        {formatValue ? formatValue(current) : String(current)}
+      </span>
+    </span>
+  );
+}

package/src/Slider/index.ts

@@ -0,0 +1 @@
+export {Slider, type SliderProps} from './Slider.js';