@ambientcss/components 2.1.0 → 3.0.1

package/src/components/AmbientSlider.tsx

@@ -1,127 +1,42 @@
-import { useId, useRef } from "react";
-import type { HTMLAttributes, KeyboardEvent, PointerEvent } from "react";
 import { cn } from "../lib/cn";
+import { AmbientTravel } from "../controls/AmbientTravel";
+import type { AmbientTravelProps } from "../controls/AmbientTravel";
+import { useDress } from "../core/kit";
+import type { KitLook } from "../core/kit";
+import { groundedKit } from "../kits/grounded";
+import type { AmbientMaterial } from "../core/material";
 
 export type AmbientSliderSize = "sm" | "md" | "lg";
 
-export type AmbientSliderProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
-  value: number;
-  min?: number;
-  max?: number;
-  step?: number;
-  label?: string;
-  material?: "matte" | "shiny" | "glass";
-  size?: AmbientSliderSize;
-  onChange?: (nextValue: number) => void;
+export type AmbientSliderProps = Omit<AmbientTravelProps, "parts" | "size" | "orientation"> & {
+  material?: AmbientMaterial | undefined;
+  size?: AmbientSliderSize | undefined;
+  /** Look options in the active kit's vocabulary. */
+  look?: KitLook | undefined;
 };
 
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
+/** A domed disc gliding over a shallow concave channel. */
 export function AmbientSlider({
-  value,
-  min = 0,
-  max = 100,
-  step = 1,
-  label,
   material,
+  look,
   size = "md",
-  onChange,
+  animate,
   className,
-  ...props
+  ...rest
 }: AmbientSliderProps) {
-  const id = useId();
-  const trackRef = useRef<HTMLDivElement | null>(null);
-  const safeStep = step > 0 ? step : 1;
-
-  const percent = ((value - min) / (max - min || 1)) * 100;
-
-  const updateFromClientX = (clientX: number) => {
-    const track = trackRef.current;
-    if (!track) return;
-
-    const rect = track.getBoundingClientRect();
-    const ratio = (clientX - rect.left) / rect.width;
-    const nextValue = min + clamp(ratio, 0, 1) * (max - min);
-    const snapped = Math.round(nextValue / safeStep) * safeStep;
-    onChange?.(clamp(snapped, min, max));
-  };
-
-  const setValue = (nextValue: number) => {
-    const snapped = Math.round(nextValue / safeStep) * safeStep;
-    onChange?.(clamp(snapped, min, max));
-  };
-
-  const onKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
-    const pageStep = safeStep * 10;
-    switch (event.key) {
-      case "ArrowRight":
-      case "ArrowUp":
-        event.preventDefault();
-        setValue(value + safeStep);
-        break;
-      case "ArrowLeft":
-      case "ArrowDown":
-        event.preventDefault();
-        setValue(value - safeStep);
-        break;
-      case "PageUp":
-        event.preventDefault();
-        setValue(value + pageStep);
-        break;
-      case "PageDown":
-        event.preventDefault();
-        setValue(value - pageStep);
-        break;
-      case "Home":
-        event.preventDefault();
-        setValue(min);
-        break;
-      case "End":
-        event.preventDefault();
-        setValue(max);
-        break;
-      default:
-        break;
-    }
-  };
-
-  const onPointerMove = (event: PointerEvent<HTMLDivElement>) => {
-    if (event.buttons !== 1) return;
-    updateFromClientX(event.clientX);
-  };
-
+  const { dress, defaults } = useDress(
+    "travel",
+    { material, orientation: "horizontal", ...look },
+    groundedKit.travel!
+  );
   return (
-    <div className={cn("ambx-stack", className)} {...props}>
-      <div
-        className={cn("amb-slider amb-groove ambx-slider", `ambx-slider-${size}`)}
-        ref={trackRef}
-        role="slider"
-        aria-label={label}
-        aria-labelledby={label ? id : undefined}
-        aria-valuemin={min}
-        aria-valuemax={max}
-        aria-valuenow={value}
-        aria-orientation="horizontal"
-        tabIndex={0}
-        onPointerDown={(event) => {
-          event.currentTarget.setPointerCapture(event.pointerId);
-          updateFromClientX(event.clientX);
-        }}
-        onPointerMove={onPointerMove}
-        onKeyDown={onKeyDown}
-      >
-        <div
-          className={cn("amb-slider-thumb ambient amb-fillet ambx-slider-thumb", material !== "glass" && "amb-surface-convex", material && `amb-mat-${material}`)}
-          style={{ left: `${percent}%` }}
-        />
-      </div>
-      {label ? (
-        <span id={id} className="ambx-label">
-          {label}
-        </span>
-      ) : null}
-    </div>
+    <AmbientTravel
+      {...rest}
+      orientation="horizontal"
+      size={size}
+      animate={animate ?? defaults?.animate}
+      className={cn(dress.className, className)}
+      parts={dress.parts}
+    />
   );
 }

package/src/components/AmbientSwitch.tsx

@@ -1,78 +1,78 @@
-import { useId, useState } from "react";
-import type { ButtonHTMLAttributes } from "react";
+import { useId } from "react";
 import { cn } from "../lib/cn";
+import { AmbientLatch } from "../controls/AmbientLatch";
+import type { AmbientLatchProps } from "../controls/AmbientLatch";
+import { useControllableValue } from "../core/controllable";
+import { useDress } from "../core/kit";
+import type { KitLook } from "../core/kit";
+import { groundedKit } from "../kits/grounded";
+import { Led } from "../parts/latch";
 
 export type AmbientSwitchSize = "sm" | "md" | "lg";
 
-export type AmbientSwitchProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "onChange"> & {
-  checked?: boolean;
-  defaultChecked?: boolean;
-  onCheckedChange?: (checked: boolean) => void;
-  size?: AmbientSwitchSize;
-  label?: string;
-  /** Show a small LED indicator that lights up when the switch is on. Pass `true` for default green or a CSS color string. */
-  led?: boolean | string;
+export type AmbientSwitchProps = Omit<AmbientLatchProps, "parts" | "size"> & {
+  size?: AmbientSwitchSize | undefined;
+  /** A lamp above the switch. `true` for the scene's own colour, or any
+   *  CSS colour string. */
+  led?: boolean | string | undefined;
+  /** Look options in the active kit's vocabulary. */
+  look?: KitLook | undefined;
 };
 
+/** A pill sliding in a dark stadium recess, with an optional lamp above.
+ *
+ *  The lamp is mounted beside the switch rather than inside it: the latch
+ *  control IS the track, so anything that is neither track nor pill belongs
+ *  to whatever composes them. That means the preset has to hold the state —
+ *  the lamp and the pill read the same boolean, and only their common
+ *  parent can see both.
+ */
 export function AmbientSwitch({
-  className,
-  checked,
-  defaultChecked,
-  onCheckedChange,
-  onClick,
   size = "md",
-  label,
   led,
-  children,
-  ...props
+  label,
+  look,
+  value,
+  defaultValue,
+  onChange,
+  animate,
+  className,
+  ...rest
 }: AmbientSwitchProps) {
   const labelId = useId();
-  const isControlled = checked !== undefined;
-  const [internalChecked, setInternalChecked] = useState(defaultChecked ?? false);
-  const active = isControlled ? (checked ?? false) : internalChecked;
+  const [on, setOn] = useControllableValue(value, defaultValue ?? false, onChange);
+  const { dress, defaults } = useDress("latch", { ...look }, groundedKit.latch!);
 
-  const button = (
-    <button
-      type="button"
-      role="switch"
-      aria-checked={active}
-      aria-labelledby={label ? labelId : props["aria-labelledby"]}
-      className={cn(
-        "amb-switch",
-        active && "amb-switch-on",
-        "ambx-switch",
-        `ambx-switch-${size}`,
-        className
-      )}
-      onClick={(event) => {
-        const next = !active;
-        if (!isControlled) setInternalChecked(next);
-        onCheckedChange?.(next);
-        onClick?.(event);
-      }}
-      {...props}
-    >
-      {led ? (
-        <span
-          className={cn("amb-led", !active && "amb-led-off")}
-          style={typeof led === "string" ? { "--amb-led-color": led } as React.CSSProperties : undefined}
-        />
-      ) : null}
-      <span className="amb-switch-track amb-groove">
-        <span className="amb-switch-pill ambient amb-fillet amb-surface-convex" />
-      </span>
-      {children}
-    </button>
+  const control = (
+    <AmbientLatch
+      {...rest}
+      value={on}
+      onChange={setOn}
+      size={size}
+      animate={animate ?? defaults?.animate}
+      aria-labelledby={label ? labelId : rest["aria-labelledby"]}
+      className={cn(dress.className, className)}
+      parts={dress.parts}
+    />
   );
 
-  if (!label) return button;
+  if (!led && !label) return control;
 
   return (
     <div className="ambx-stack">
-      {button}
-      <span id={labelId} className="ambx-label">
-        {label}
-      </span>
+      {led ? (
+        <span className="ambx-switch-mount">
+          <Led on={on} {...(typeof led === "string" ? { color: led } : null)} />
+          {control}
+        </span>
+      ) : (
+        control
+      )}
+      {label ? (
+        <span id={labelId} className="ambx-label">
+          {label}
+        </span>
+      ) : null}
     </div>
   );
 }

package/src/controls/AmbientBank.tsx

@@ -0,0 +1,139 @@
+import { useId } from "react";
+import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { BankKeyProvider, ControlStateProvider } from "../core/context";
+import { Frames } from "../core/frames";
+import { sizeProps, stateData, stateStyle } from "../core/types";
+import type { ControlParts, ControlSize, ControlState } from "../core/types";
+import { useBank } from "../core/useBank";
+import type { BankOption, UseBankOptions } from "../core/useBank";
+
+export type AmbientBankProps = Omit<
+  HTMLAttributes<HTMLDivElement>,
+  "onChange" | "defaultValue"
+> &
+  UseBankOptions & {
+    /** Parts applied to every key. The bank's own frames go in `parts`. */
+    keyParts?: ControlParts | undefined;
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    /** Lamp colour. Defaults to the scene's `--amb-highlight-color`. */
+    color?: string | undefined;
+    label?: ReactNode | undefined;
+    /** Per-key override, for a bank whose keys are not interchangeable. */
+    renderKey?: ((option: BankOption, on: boolean) => ReactNode) | undefined;
+  };
+
+function keyState(on: boolean, disabled: boolean): ControlState {
+  return {
+    value: on ? 1 : 0,
+    min: 0,
+    max: 1,
+    percent: on ? 1 : 0,
+    angle: 0,
+    travelStart: 0,
+    travelSweep: 0,
+    detents: 2,
+    dragging: false,
+    disabled,
+    atMin: !on,
+    atMax: on
+  };
+}
+
+/** N keys sharing a selection model, with no appearance of its own.
+ *
+ *  Parts apply per key rather than once, because that is what a bank is.
+ *  The focusable element is the key `<button>`, which this mechanism
+ *  renders — your parts go inside it, which is why the presentational-parts
+ *  rule still holds here. */
+export function AmbientBank({
+  options,
+  keyParts,
+  parts,
+  size,
+  color,
+  label,
+  renderKey,
+  className,
+  style,
+  value,
+  defaultValue,
+  onChange,
+  multiple,
+  orientation = "vertical",
+  disabled = false,
+  ...rest
+}: AmbientBankProps) {
+  const labelId = useId();
+  const { selected, rootProps, keyProps } = useBank({
+    options,
+    value,
+    defaultValue,
+    onChange,
+    multiple,
+    orientation,
+    disabled
+  });
+
+  const sized = sizeProps("bank", size);
+
+  const bank = (
+    <div
+      {...rest}
+      {...rootProps}
+      aria-labelledby={label ? labelId : rest["aria-labelledby"]}
+      className={cn(
+        "ambx-control ambx-bank",
+        `ambx-bank-${orientation}`,
+        sized.className,
+        className
+      )}
+      style={{
+        ...(color ? ({ "--amb-led-color": color } as CSSProperties) : null),
+        ...sized.style,
+        ...style
+      }}
+    >
+      <Frames parts={parts} />
+      {options.map((option, index) => {
+        const on = selected.includes(option.value);
+        /* Each key publishes its own state channel, exactly as a standalone
+           control does. Without this a key's parts would inherit the bank
+           root's neutral --ambx-percent and a pure-CSS part could never see
+           that its lamp is lit — the one family where "the properties are
+           canonical" would quietly not be true. */
+        const ks = keyState(on, option.disabled || disabled);
+        return (
+          <button
+            key={option.value}
+            {...keyProps(option, index)}
+            {...stateData(ks)}
+            className="ambx-key"
+            style={{
+              ...(stateStyle(ks) as CSSProperties),
+              ...(option.color ? ({ "--amb-led-color": option.color } as CSSProperties) : null)
+            }}
+          >
+            <ControlStateProvider value={ks}>
+              <BankKeyProvider value={{ option, on, index }}>
+                {renderKey ? renderKey(option, on) : <Frames parts={keyParts} />}
+              </BankKeyProvider>
+            </ControlStateProvider>
+          </button>
+        );
+      })}
+    </div>
+  );
+
+  if (!label) return bank;
+
+  return (
+    <div className="ambx-stack">
+      {bank}
+      <span id={labelId} className="ambx-label">
+        {label}
+      </span>
+    </div>
+  );
+}

package/src/controls/AmbientLatch.tsx

@@ -0,0 +1,78 @@
+import { useId, useRef } from "react";
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { ControlStateProvider } from "../core/context";
+import { Frames, useDevPartCheck } from "../core/frames";
+import { sizeProps } from "../core/types";
+import type { ControlAnimate, ControlParts, ControlSize } from "../core/types";
+import { useLatch } from "../core/useLatch";
+import type { UseLatchOptions } from "../core/useLatch";
+
+export type AmbientLatchProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "onChange" | "value" | "defaultValue" | "type"
+> &
+  UseLatchOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    animate?: ControlAnimate | undefined;
+    label?: ReactNode | undefined;
+  };
+
+/** A two-position slide, with no appearance of its own. The control IS the
+ *  track: its actuator is a pill-sized frame that travels across it, which
+ *  is why anything sitting beside a switch — a lamp, a legend — belongs to
+ *  whatever composes it rather than to the switch. */
+export function AmbientLatch({
+  parts,
+  size,
+  animate = "auto",
+  label,
+  className,
+  value,
+  defaultValue,
+  onChange,
+  disabled,
+  children,
+  ...rest
+}: AmbientLatchProps) {
+  const labelId = useId();
+  const ref = useRef<HTMLButtonElement>(null);
+  const { state, rootProps } = useLatch({ value, defaultValue, onChange, disabled });
+  useDevPartCheck(ref, "AmbientLatch");
+
+  const sized = sizeProps("latch", size);
+  const { style: restStyle, onClick, ...restProps } = rest;
+
+  const control = (
+    <button
+      {...restProps}
+      {...rootProps}
+      ref={ref}
+      aria-labelledby={label ? labelId : rest["aria-labelledby"]}
+      data-animate={animate}
+      className={cn("ambx-control ambx-latch", sized.className, className)}
+      style={{ ...rootProps.style, ...sized.style, ...restStyle }}
+      onClick={(event) => {
+        rootProps.onClick();
+        onClick?.(event);
+      }}
+    >
+      <ControlStateProvider value={state}>
+        <Frames parts={parts} />
+        {children}
+      </ControlStateProvider>
+    </button>
+  );
+
+  if (!label) return control;
+
+  return (
+    <div className="ambx-stack">
+      {control}
+      <span id={labelId} className="ambx-label">
+        {label}
+      </span>
+    </div>
+  );
+}

package/src/controls/AmbientPress.tsx

@@ -0,0 +1,74 @@
+import { useRef } from "react";
+import type { ButtonHTMLAttributes } from "react";
+import { cn } from "../lib/cn";
+import { ControlStateProvider } from "../core/context";
+import { Frames, useDevPartCheck } from "../core/frames";
+import { sizeProps } from "../core/types";
+import type { ControlParts, ControlSize } from "../core/types";
+import { usePress } from "../core/usePress";
+import type { UsePressOptions } from "../core/usePress";
+
+export type AmbientPressProps = Omit<
+  ButtonHTMLAttributes<HTMLButtonElement>,
+  "onChange" | "value" | "defaultValue" | "type"
+> &
+  UsePressOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+  };
+
+/** A key that sinks under a finger, with no appearance of its own.
+ *
+ *  Its frames are `display: contents` markers rather than boxes, because a
+ *  button is sized by its cap: the width is `min-width` plus the legend.
+ *  Wrapping the cap in a positioned frame would collapse the control. */
+export function AmbientPress({
+  parts,
+  size,
+  className,
+  mode,
+  value,
+  defaultValue,
+  onChange,
+  onPress,
+  repeatDelay,
+  repeatInterval,
+  disabled,
+  children,
+  ...rest
+}: AmbientPressProps) {
+  const ref = useRef<HTMLButtonElement>(null);
+  const { state, rootProps } = usePress({
+    mode,
+    value,
+    defaultValue,
+    onChange,
+    onPress,
+    repeatDelay,
+    repeatInterval,
+    disabled
+  });
+  useDevPartCheck(ref, "AmbientPress");
+
+  const sized = sizeProps("press", size);
+  const { style: restStyle, onClick, ...restProps } = rest;
+
+  return (
+    <button
+      {...restProps}
+      {...rootProps}
+      ref={ref}
+      className={cn("ambx-control ambx-press", sized.className, className)}
+      style={{ ...rootProps.style, ...sized.style, ...restStyle }}
+      onClick={(event) => {
+        rootProps.onClick();
+        onClick?.(event);
+      }}
+    >
+      <ControlStateProvider value={state}>
+        <Frames parts={parts} />
+        {children}
+      </ControlStateProvider>
+    </button>
+  );
+}

package/src/controls/AmbientRotary.tsx

@@ -0,0 +1,94 @@
+import { useId, useRef } from "react";
+import type { HTMLAttributes, ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { ControlStateProvider } from "../core/context";
+import { Frames, useDevPartCheck } from "../core/frames";
+import { sizeProps } from "../core/types";
+import type { ControlAnimate, ControlParts, ControlSize } from "../core/types";
+import { useRotary } from "../core/useRotary";
+import type { UseRotaryOptions } from "../core/useRotary";
+
+export type AmbientRotaryProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> &
+  UseRotaryOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    animate?: ControlAnimate | undefined;
+    label?: ReactNode | undefined;
+  };
+
+/** A rotary mechanism with no appearance of its own.
+ *
+ *  It owns the value, the three pointer mappings, the sweep, the keyboard
+ *  contract and the ARIA; what it looks like is entirely the `parts` you
+ *  give it. There is deliberately no `material` prop: which element a
+ *  material belongs on is a fact about a particular knob's construction —
+ *  on the clipped face when it is knurled, on the body when it is not —
+ *  and a mechanism cannot know that once the body is yours. Presets carry
+ *  `material`, because a preset knows its own parts. */
+export function AmbientRotary({
+  parts,
+  size,
+  animate = "auto",
+  label,
+  className,
+  value,
+  defaultValue,
+  min,
+  max,
+  step,
+  detents,
+  travel,
+  input,
+  dragDistance,
+  wrap,
+  disabled,
+  onChange,
+  ...rest
+}: AmbientRotaryProps) {
+  const labelId = useId();
+  const stackRef = useRef<HTMLDivElement>(null);
+  const { state, rootProps } = useRotary({
+    value,
+    defaultValue,
+    min,
+    max,
+    step,
+    detents,
+    travel,
+    input,
+    dragDistance,
+    wrap,
+    disabled,
+    onChange
+  });
+  useDevPartCheck(stackRef, "AmbientRotary");
+
+  const sized = sizeProps("rotary", size);
+  const { style: restStyle, ...restProps } = rest;
+
+  const control = (
+    <div
+      {...restProps}
+      {...rootProps}
+      aria-labelledby={label ? labelId : rest["aria-labelledby"]}
+      data-animate={animate}
+      className={cn("ambx-control ambx-rotary", sized.className, className)}
+      style={{ ...rootProps.style, ...sized.style, ...restStyle }}
+    >
+      <ControlStateProvider value={state}>
+        <Frames parts={parts} />
+      </ControlStateProvider>
+    </div>
+  );
+
+  return (
+    <div className="ambx-stack" ref={stackRef}>
+      {control}
+      {label ? (
+        <span id={labelId} className="ambx-label">
+          {label}
+        </span>
+      ) : null}
+    </div>
+  );
+}