@yarcl/react 0.1.0

package/src/components/Skeleton.tsx

@@ -0,0 +1,95 @@
+import type { ComponentProps, CSSProperties } from 'react';
+import { cx, radiusClass, sizeClass, typeClass } from '../classes';
+import type { Radius, Size, TextStyle } from '../types';
+import { useDefaults } from '../runtime';
+
+
+/** Props for {@link Skeleton}. */
+export interface SkeletonProps extends Omit<ComponentProps<'span'>, 'children'> {
+  /**
+   * `text`: lines matching a text style; `control`: the height of a control of the given `size`;
+   * `circle`: a circle, e.g. for an avatar; `rect`: a block sized by `width` and `height`.
+   * @default 'text'
+   */
+  shape?: 'text' | 'control' | 'circle' | 'rect';
+  /** Number of lines for `shape="text"`. The last line is shorter. */
+  lines?: number;
+  /**
+   * Text style whose font size and line height the lines match, for `shape="text"`.
+   * @default config.defaults.textStyle
+   */
+  textStyle?: TextStyle;
+  /**
+   * Control size, from the `sizes` config. Sets the height for `shape="control"` and the diameter for `shape="circle"`.
+   * @default config.defaults.size
+   */
+  size?: Size;
+  /**
+   * Corner radius for `control` and `rect`, from the `radii` config.
+   * @default config.defaults.radius
+   */
+  radius?: Radius | 'size';
+  /** Width as a CSS length. */
+  width?: string;
+  /** Height as a CSS length, for `shape="rect"`. */
+  height?: string;
+}
+
+/**
+ * A placeholder shown while content loads. Hidden from assistive technology;
+ * mark the loading region with `aria-busy` instead.
+ *
+ * @example
+ * ```tsx
+ * <Stack aria-busy>
+ *   <Skeleton shape="text" textStyle="title" width="40%" />
+ *   <Skeleton shape="text" lines={3} />
+ *   <Skeleton shape="control" width="12rem" />
+ * </Stack>
+ * ```
+ */
+export function Skeleton({
+  shape = 'text',
+  lines = 1,
+  textStyle,
+  size,
+  radius,
+  width,
+  height,
+  className,
+  style,
+  ...props
+}: SkeletonProps) {
+  const own = useDefaults('Skeleton');
+  const dimensions = { width, height, ...style } as CSSProperties;
+
+  if (shape === 'text') {
+    return (
+      <span
+        aria-hidden="true"
+        className={cx('yarcl-skeleton-text', textStyle && typeClass(textStyle), className)}
+        style={dimensions}
+        {...props}
+      >
+        {Array.from({ length: lines }, (_, i) => (
+          <span key={i} className="yarcl-skeleton yarcl-skeleton-line" />
+        ))}
+      </span>
+    );
+  }
+
+  return (
+    <span
+      aria-hidden="true"
+      className={cx(
+        'yarcl-skeleton',
+        `yarcl-skeleton-${shape}`,
+        shape !== 'rect' && sizeClass(size ?? own.size),
+        shape !== 'circle' && radiusClass(radius ?? own.radius, size ?? own.size),
+        className,
+      )}
+      style={dimensions}
+      {...props}
+    />
+  );
+}

package/src/components/Slider.tsx

@@ -0,0 +1,315 @@
+import {
+  useContext,
+  useId,
+  useRef,
+  type ComponentProps,
+  type CSSProperties,
+  type KeyboardEvent,
+  type PointerEvent,
+} from 'react';
+import { colorClass, cx, radiusClass, sizeClass } from '../classes';
+import { FieldContext, useFieldProps } from '../field-context';
+import { useControllable } from '../hooks';
+import type { TokenProps } from '../types';
+import { useDefaults } from '../runtime';
+
+/** A {@link Slider} value: one number, or a `[start, end]` pair for a range. */
+export type SliderValue = number | [number, number];
+
+/** Props for {@link Slider}. Accepts all native `<div>` attributes except `color`, `defaultValue`, `onChange` and `children`. */
+export interface SliderProps<V extends SliderValue = number>
+  extends TokenProps,
+    Omit<ComponentProps<'div'>, 'color' | 'defaultValue' | 'onChange' | 'children'> {
+  /**
+   * Controlled value. Pass a `[start, end]` pair for a range with two thumbs.
+   * @example
+   * ```tsx
+   * <Slider value={volume} onValueChange={setVolume} aria-label="Volume" />
+   * ```
+   */
+  value?: V;
+  /**
+   * Initial value when uncontrolled. Pass a `[start, end]` pair for a range with two thumbs.
+   * @default min
+   * @example
+   * ```tsx
+   * <Slider defaultValue={[20, 80]} aria-label="Price" />
+   * ```
+   */
+  defaultValue?: V;
+  /**
+   * Called with the new value while the user drags or presses a key.
+   * @example
+   * ```tsx
+   * <Slider onValueChange={(value) => setVolume(value)} aria-label="Volume" />
+   * ```
+   */
+  onValueChange?: (value: V) => void;
+  /**
+   * Lowest value.
+   * @default 0
+   * @example
+   * ```tsx
+   * <Slider min={-10} max={10} aria-label="Offset" />
+   * ```
+   */
+  min?: number;
+  /**
+   * Highest value.
+   * @default 100
+   * @example
+   * ```tsx
+   * <Slider max={10} aria-label="Rating" />
+   * ```
+   */
+  max?: number;
+  /**
+   * Interval between values. Values snap to multiples of it, counted from `min`.
+   * @default 1
+   * @example
+   * ```tsx
+   * <Slider step={5} aria-label="Opacity" />
+   * ```
+   */
+  step?: number;
+  /**
+   * Jump for PageUp and PageDown.
+   * @default a tenth of the range, rounded to a whole number of steps
+   * @example
+   * ```tsx
+   * <Slider step={1} largeStep={25} aria-label="Progress" />
+   * ```
+   */
+  largeStep?: number;
+  /**
+   * Prevents interaction and dims the slider.
+   * @default false
+   * @example
+   * ```tsx
+   * <Slider disabled defaultValue={40} aria-label="Volume" />
+   * ```
+   */
+  disabled?: boolean;
+  /**
+   * Form field name. Renders a hidden input per thumb with its value.
+   * @example
+   * ```tsx
+   * <Slider name="volume" aria-label="Volume" />
+   * ```
+   */
+  name?: string;
+  /**
+   * Formats a value for screen readers (`aria-valuetext`).
+   * @example
+   * ```tsx
+   * <Slider formatValue={(value) => `${value} percent`} aria-label="Volume" />
+   * ```
+   */
+  formatValue?: (value: number) => string;
+  /**
+   * Names of the two thumbs of a range, added to the slider's label.
+   * @default ['Minimum', 'Maximum']
+   * @example
+   * ```tsx
+   * <Slider defaultValue={[9, 17]} thumbLabels={['Opens', 'Closes']} aria-label="Hours" />
+   * ```
+   */
+  thumbLabels?: readonly [string, string];
+}
+
+const clamp = (value: number, low: number, high: number) => Math.min(Math.max(value, low), high);
+
+function decimals(value: number): number {
+  const text = String(value);
+  const exponent = text.match(/e-(\d+)$/);
+  if (exponent) return Number(exponent[1]);
+  return text.split('.')[1]?.length ?? 0;
+}
+
+const DEFAULT_THUMB_LABELS = ['Minimum', 'Maximum'] as const;
+
+/**
+ * Picks a number, or a range with two thumbs, by dragging along a track.
+ * Each thumb has `role="slider"` and supports the arrow keys, Home, End, PageUp and PageDown.
+ * Shares the size scale with the other controls. Works inside a {@link Field}; outside one, give it an `aria-label`.
+ *
+ * @example
+ * ```tsx
+ * <Field label="Volume">
+ *   <Slider defaultValue={40} />
+ * </Field>
+ * ```
+ */
+export function Slider<V extends SliderValue = number>(props: SliderProps<V>) {
+  const own = useDefaults('Slider');
+  const field = useContext(FieldContext);
+  const uid = useId();
+  const {
+    value: valueProp,
+    defaultValue,
+    onValueChange,
+    min = 0,
+    max = 100,
+    step = 1,
+    largeStep,
+    disabled = false,
+    name,
+    formatValue,
+    thumbLabels = DEFAULT_THUMB_LABELS,
+    size,
+    radius,
+    color,
+    className,
+    style,
+    id,
+    required: _required,
+    'aria-label': ariaLabel,
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+    'aria-invalid': ariaInvalid,
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    onLostPointerCapture,
+    ...rest
+  } = useFieldProps(props) as SliderProps<V> & { required?: boolean };
+
+  const [value, setValue] = useControllable<V>(valueProp, defaultValue ?? (min as V), onValueChange);
+  const trackRef = useRef<HTMLDivElement>(null);
+  const thumbRefs = useRef<(HTMLDivElement | null)[]>([]);
+  const dragging = useRef<number | null>(null);
+
+  const range = Array.isArray(value);
+  const values = (range ? value : [value]).map((v) => clamp(v, min, max));
+  const precision = decimals(step);
+  const big = largeStep ?? Math.max(step, Math.round((max - min) / 10 / step) * step);
+
+  const snap = (raw: number) => Number(clamp(min + Math.round((raw - min) / step) * step, min, max).toFixed(precision));
+  const lowerBound = (index: number) => (range && index === 1 ? values[0] : min);
+  const upperBound = (index: number) => (range && index === 0 ? values[1] : max);
+  const percent = (v: number) => (max > min ? ((v - min) / (max - min)) * 100 : 0);
+
+  function update(index: number, raw: number) {
+    const next = clamp(snap(raw), lowerBound(index), upperBound(index));
+    if (next === values[index]) return;
+    const nextValues = values.slice();
+    nextValues[index] = next;
+    setValue((range ? [nextValues[0], nextValues[1]] : nextValues[0]) as V);
+  }
+
+  const rtl = () => trackRef.current != null && getComputedStyle(trackRef.current).direction === 'rtl';
+
+  function valueAt(clientX: number): number {
+    const rect = trackRef.current!.getBoundingClientRect();
+    const ratio = rect.width > 0 ? clamp((clientX - rect.left) / rect.width, 0, 1) : 0;
+    return min + (rtl() ? 1 - ratio : ratio) * (max - min);
+  }
+
+  function handlePointerDown(event: PointerEvent<HTMLDivElement>) {
+    onPointerDown?.(event);
+    if (disabled || event.defaultPrevented || event.button !== 0) return;
+    event.preventDefault();
+    const raw = valueAt(event.clientX);
+    let index = 0;
+    if (range) {
+      const [start, end] = values;
+      const toStart = Math.abs(raw - start);
+      const toEnd = Math.abs(raw - end);
+      index = toEnd < toStart || (toEnd === toStart && raw > end) ? 1 : 0;
+    }
+    dragging.current = index;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    thumbRefs.current[index]?.focus();
+    update(index, raw);
+  }
+
+  function handlePointerMove(event: PointerEvent<HTMLDivElement>) {
+    onPointerMove?.(event);
+    if (dragging.current != null) update(dragging.current, valueAt(event.clientX));
+  }
+
+  function handlePointerUp(event: PointerEvent<HTMLDivElement>) {
+    onPointerUp?.(event);
+    dragging.current = null;
+  }
+
+  function handleLostPointerCapture(event: PointerEvent<HTMLDivElement>) {
+    onLostPointerCapture?.(event);
+    dragging.current = null;
+  }
+
+  function handleKeyDown(index: number, event: KeyboardEvent<HTMLDivElement>) {
+    if (disabled) return;
+    const current = values[index];
+    const forward = rtl() ? -step : step;
+    const moves: Record<string, number> = {
+      ArrowRight: current + forward,
+      ArrowLeft: current - forward,
+      ArrowUp: current + step,
+      ArrowDown: current - step,
+      PageUp: current + big,
+      PageDown: current - big,
+      Home: lowerBound(index),
+      End: upperBound(index),
+    };
+    if (!(event.key in moves)) return;
+    event.preventDefault();
+    update(index, moves[event.key]);
+  }
+
+  const outerLabelledBy = ariaLabelledBy ?? (field ? field.labelId : undefined);
+  const start = range ? percent(values[0]) : 0;
+  const end = percent(values[values.length - 1]);
+
+  return (
+    <div
+      className={cx(
+        'yarcl-slider',
+        sizeClass(size ?? own.size),
+        radiusClass(radius ?? own.radius, size ?? own.size),
+        colorClass(color ?? own.color),
+        className,
+      )}
+      style={{ ...style, '--yarcl-slider-start': `${start}%`, '--yarcl-slider-end': `${end}%` } as CSSProperties}
+      data-disabled={disabled || undefined}
+      onPointerDown={handlePointerDown}
+      onPointerMove={handlePointerMove}
+      onPointerUp={handlePointerUp}
+      onLostPointerCapture={handleLostPointerCapture}
+      {...rest}
+    >
+      <div ref={trackRef} className="yarcl-slider-track">
+        <div className="yarcl-slider-range" />
+        {values.map((v, index) => {
+          const thumbId = index === 0 && id ? id : `${uid}-thumb-${index}`;
+          const thumbLabel = range ? thumbLabels[index] : undefined;
+          return (
+            <div
+              key={index}
+              ref={(el) => {
+                thumbRefs.current[index] = el;
+              }}
+              id={thumbId}
+              role="slider"
+              tabIndex={disabled ? undefined : 0}
+              className="yarcl-slider-thumb"
+              style={{ '--yarcl-slider-position': `${percent(v)}%` } as CSSProperties}
+              aria-valuemin={lowerBound(index)}
+              aria-valuemax={upperBound(index)}
+              aria-valuenow={v}
+              aria-valuetext={formatValue?.(v)}
+              aria-orientation="horizontal"
+              aria-disabled={disabled || undefined}
+              aria-invalid={ariaInvalid}
+              aria-describedby={ariaDescribedBy}
+              aria-label={thumbLabel && !outerLabelledBy && ariaLabel ? `${ariaLabel} ${thumbLabel}` : (thumbLabel ?? ariaLabel)}
+              aria-labelledby={outerLabelledBy && (thumbLabel ? `${outerLabelledBy} ${thumbId}` : outerLabelledBy)}
+              onKeyDown={(event) => handleKeyDown(index, event)}
+            />
+          );
+        })}
+      </div>
+      {name != null && values.map((v, index) => <input key={index} type="hidden" name={name} value={v} disabled={disabled} />)}
+    </div>
+  );
+}

package/src/components/Spinner.tsx

@@ -0,0 +1,38 @@
+import type { ComponentProps } from 'react';
+import { colorClass, cx, sizeClass } from '../classes';
+import type { Color, Size } from '../types';
+import { useDefaults } from '../runtime';
+
+
+/** Props for {@link Spinner}. */
+export interface SpinnerProps extends Omit<ComponentProps<'span'>, 'color'> {
+  /** Diameter from the size's `iconSize`, from the `sizes` config. Inherits the surrounding control's size when omitted. */
+  size?: Size;
+  /** Semantic color, from the `colors` config. Uses the current text color when omitted. */
+  color?: Color;
+  /**
+   * Accessible label announced to screen readers.
+   * @default 'Loading'
+   */
+  label?: string;
+}
+
+/**
+ * An indeterminate loading indicator. Sized like an icon, so it fits inside controls of the same size.
+ *
+ * @example
+ * ```tsx
+ * <Spinner size="lg" color="brand" />
+ * ```
+ */
+export function Spinner({ size, color, label = 'Loading', className, ...props }: SpinnerProps) {
+  const own = useDefaults('Spinner');
+  return (
+    <span
+      role="status"
+      aria-label={label}
+      className={cx('yarcl-spinner', (size ?? own.size) && sizeClass(size ?? own.size), (color ?? own.color) && cx('yarcl-spinner-colored', colorClass(color ?? own.color)), className)}
+      {...props}
+    />
+  );
+}

package/src/components/Stack.tsx

@@ -0,0 +1,57 @@
+import type { ComponentProps } from 'react';
+import { cx, gapClass } from '../classes';
+import type { Align, Justify, Spacing } from '../types';
+import { useDefaults } from '../runtime';
+
+
+/** Elements layout components can render as. */
+export type LayoutElement = 'div' | 'section' | 'article' | 'aside' | 'header' | 'footer' | 'main' | 'nav' | 'form' | 'ul' | 'ol';
+
+/** Props shared by {@link Stack} and {@link Inline}. */
+export interface LayoutProps extends ComponentProps<'div'> {
+  /**
+   * Element to render.
+   * @default 'div'
+   */
+  as?: LayoutElement;
+  /**
+   * Space between children, from the `spacing` config.
+   * @default config.defaults.gap
+   */
+  gap?: Spacing;
+  /** Cross-axis alignment of children. */
+  align?: Align;
+  /** Main-axis distribution of children. */
+  justify?: Justify;
+}
+
+/** Props for {@link Stack}. */
+export type StackProps = LayoutProps;
+
+/**
+ * Lays out children vertically with a gap from the spacing scale.
+ *
+ * @example
+ * ```tsx
+ * <Stack gap="loose">
+ *   <Heading level={2}>Profile</Heading>
+ *   <Field label="Name"><Input /></Field>
+ * </Stack>
+ * ```
+ */
+export function Stack({ as = 'div', gap, align, justify, className, ...props }: StackProps) {
+  const own = useDefaults('Stack');
+  const Tag = as as 'div';
+  return (
+    <Tag
+      className={cx(
+        'yarcl-stack',
+        gapClass(gap ?? own.gap),
+        align && `yarcl-align-${align}`,
+        justify && `yarcl-justify-${justify}`,
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/Switch.tsx

@@ -0,0 +1,42 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { colorClass, cx, sizeClass } from '../classes';
+import { useFieldProps } from '../field-context';
+import type { Color, Size } from '../types';
+import { useDefaults } from '../runtime';
+
+
+/** Props for {@link Switch}. Accepts all native `<input>` attributes except `type`, `color` and `size`. */
+export interface SwitchProps extends Omit<ComponentProps<'input'>, 'type' | 'color' | 'size' | 'children'> {
+  /** Label shown next to the switch. */
+  children?: ReactNode;
+  /**
+   * Switch size, from the `sizes` config (scaled from the size's `iconSize`).
+   * @default config.defaults.size
+   */
+  size?: Size;
+  /**
+   * Track color when on, from the `colors` config.
+   * @default config.defaults.color
+   */
+  color?: Color;
+}
+
+/**
+ * An on/off toggle. A native checkbox with `role="switch"`, so `checked`,
+ * `defaultChecked` and `onChange` work as usual.
+ *
+ * @example
+ * ```tsx
+ * <Switch defaultChecked>Notifications</Switch>
+ * ```
+ */
+export function Switch(props: SwitchProps) {
+  const own = useDefaults('Switch');
+  const { children, size, color, className, style, ...rest } = useFieldProps(props);
+  return (
+    <label className={cx('yarcl-switch', sizeClass(size ?? own.size), colorClass(color ?? own.color), className)} style={style}>
+      <input type="checkbox" role="switch" className="yarcl-switch-input" {...rest} />
+      {children != null && <span className="yarcl-switch-label">{children}</span>}
+    </label>
+  );
+}

package/src/components/Table.tsx

@@ -0,0 +1,99 @@
+import type { ComponentProps, ReactNode } from 'react';
+import { cx, densityClass } from '../classes';
+import type { Density } from '../types';
+import { useDefaults } from '../runtime';
+
+
+/** Props for {@link Table}. */
+export interface TableProps extends ComponentProps<'table'> {
+  /**
+   * Cell padding and font size, from the `density` config.
+   * @default config.defaults.density
+   */
+  density?: Density;
+  /** Shades every other row. */
+  striped?: boolean;
+  /** Highlights the row under the pointer. Use when rows are clickable. */
+  interactive?: boolean;
+  /** Visible caption describing the table. Also its accessible name. */
+  caption?: ReactNode;
+}
+
+function TableRoot({ density, striped, interactive, caption, className, children, ...props }: TableProps) {
+  const own = useDefaults('Table');
+  return (
+    <div className="yarcl-table-wrap">
+      <table
+        className={cx(
+          'yarcl-table',
+          densityClass(density ?? own.density),
+          striped && 'yarcl-table-striped',
+          interactive && 'yarcl-table-interactive',
+          className,
+        )}
+        {...props}
+      >
+        {caption != null && <caption className="yarcl-table-caption">{caption}</caption>}
+        {children}
+      </table>
+    </div>
+  );
+}
+
+/** Horizontal alignment of a cell's content. `end` also uses tabular numbers, for numeric columns. */
+export type CellAlign = 'start' | 'center' | 'end';
+
+/** Props for `Table.HeaderCell`. */
+export interface TableHeaderCellProps extends Omit<ComponentProps<'th'>, 'align'> {
+  /**
+   * Content alignment.
+   * @default 'start'
+   */
+  align?: CellAlign;
+}
+
+function TableHeaderCell({ align = 'start', scope = 'col', className, ...props }: TableHeaderCellProps) {
+  return <th scope={scope} className={cx(`yarcl-cell-${align}`, className)} {...props} />;
+}
+
+/** Props for `Table.Cell`. */
+export interface TableCellProps extends Omit<ComponentProps<'td'>, 'align'> {
+  /**
+   * Content alignment.
+   * @default 'start'
+   */
+  align?: CellAlign;
+}
+
+function TableCell({ align = 'start', className, ...props }: TableCellProps) {
+  return <td className={cx(`yarcl-cell-${align}`, className)} {...props} />;
+}
+
+/**
+ * A data table with density from the config. Scrolls horizontally when it doesn't fit.
+ *
+ * @example
+ * ```tsx
+ * <Table density="compact" striped caption="Invoices">
+ *   <Table.Head>
+ *     <Table.Row>
+ *       <Table.HeaderCell>Customer</Table.HeaderCell>
+ *       <Table.HeaderCell align="end">Amount</Table.HeaderCell>
+ *     </Table.Row>
+ *   </Table.Head>
+ *   <Table.Body>
+ *     <Table.Row>
+ *       <Table.Cell>Ada</Table.Cell>
+ *       <Table.Cell align="end">$120.00</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table>
+ * ```
+ */
+export const Table = Object.assign(TableRoot, {
+  Head: (props: ComponentProps<'thead'>) => <thead {...props} />,
+  Body: (props: ComponentProps<'tbody'>) => <tbody {...props} />,
+  Row: (props: ComponentProps<'tr'>) => <tr {...props} />,
+  HeaderCell: TableHeaderCell,
+  Cell: TableCell,
+});