@ambientcss/components 2.1.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ambientcss/components",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "React skeuomorphic components powered by Ambient CSS",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "dependencies": {
-    "@ambientcss/css": "2.0.0"
+    "@ambientcss/css": "3.0.0"
   },
   "devDependencies": {
     "@types/react": "^19.0.8",

package/src/components/AmbientButton.tsx

@@ -1,5 +1,10 @@
-import type { ButtonHTMLAttributes } from "react";
 import { cn } from "../lib/cn";
+import { AmbientPress } from "../controls/AmbientPress";
+import type { AmbientPressProps } from "../controls/AmbientPress";
+import { useDress } from "../core/kit";
+import type { KitLook } from "../core/kit";
+import { groundedKit } from "../kits/grounded";
+import type { AmbientMaterial } from "../core/material";
 
 /* Cap silhouettes from the referent lineup (ambient3d/generate.py):
    - "pill":   the default wide stadium key (transport-key style)
@@ -10,40 +15,31 @@ import { cn } from "../lib/cn";
 export type AmbientButtonShape = "pill" | "round" | "square";
 export type AmbientButtonSize = "sm" | "md" | "lg";
 
-export interface AmbientButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  material?: "matte" | "shiny" | "glass";
-  shape?: AmbientButtonShape;
-  size?: AmbientButtonSize;
-}
+export type AmbientButtonProps = Omit<AmbientPressProps, "parts" | "size"> & {
+  material?: AmbientMaterial | undefined;
+  shape?: AmbientButtonShape | undefined;
+  size?: AmbientButtonSize | undefined;
+  /** Look options in the active kit's vocabulary. */
+  look?: KitLook | undefined;
+};
 
+/** A key cap seated in a clearance well. */
 export function AmbientButton({
   className,
   children,
+  look,
   material = "matte",
   shape = "pill",
   size = "md",
-  ...props
+  ...rest
 }: AmbientButtonProps) {
+  const { dress } = useDress("press", { material, shape, children, ...look }, groundedKit.press!);
   return (
-    <button
-      type="button"
-      className={cn(
-        "amb-button amb-groove ambx-button",
-        `ambx-button-${size}`,
-        shape === "round" && "amb-button-round",
-        shape === "square" && "amb-button-square",
-        className
-      )}
-      {...props}
-    >
-      <span
-        className={cn(
-          "amb-button-cap ambient amb-chamfer amb-surface amb-heading-3",
-          material === "matte" ? "amb-mat-matte" : material === "shiny" ? "amb-mat-shiny" : "amb-mat-glass"
-        )}
-      >
-        {children}
-      </span>
-    </button>
+    <AmbientPress
+      {...rest}
+      size={size}
+      className={cn(dress.className, className)}
+      parts={dress.parts}
+    />
   );
 }

package/src/components/AmbientFader.tsx

@@ -1,129 +1,43 @@
-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 AmbientFaderSize = "sm" | "md" | "lg";
 
-export type AmbientFaderProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
-  value: number;
-  min?: number;
-  max?: number;
-  step?: number;
-  label?: string;
-  material?: "matte" | "shiny" | "glass";
-  size?: AmbientFaderSize;
-  onChange?: (nextValue: number) => void;
+export type AmbientFaderProps = Omit<AmbientTravelProps, "parts" | "size" | "orientation"> & {
+  material?: AmbientMaterial | undefined;
+  size?: AmbientFaderSize | 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 pill cap on a stem, riding an upright slot. Min is at the bottom,
+ *  which `AmbientTravel` already does for a vertical track. */
 export function AmbientFader({
-  value,
-  min = 0,
-  max = 100,
-  step = 1,
-  label,
   material,
+  look,
   size = "md",
-  onChange,
+  animate,
   className,
-  ...props
+  ...rest
 }: AmbientFaderProps) {
-  const id = useId();
-  const trackRef = useRef<HTMLDivElement | null>(null);
-  const safeStep = step > 0 ? step : 1;
-
-  const percent = ((value - min) / (max - min || 1)) * 100;
-
-  const updateFromClientY = (clientY: number) => {
-    const track = trackRef.current;
-    if (!track) return;
-
-    const rect = track.getBoundingClientRect();
-    const ratio = 1 - (clientY - rect.top) / rect.height;
-    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 "ArrowUp":
-      case "ArrowRight":
-        event.preventDefault();
-        setValue(value + safeStep);
-        break;
-      case "ArrowDown":
-      case "ArrowLeft":
-        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;
-    updateFromClientY(event.clientY);
-  };
-
+  const { dress, defaults } = useDress(
+    "travel",
+    { material, orientation: "vertical", ...look },
+    groundedKit.travel!
+  );
   return (
-    <div className={cn("ambx-stack", className)} {...props}>
-      <div
-        className={cn("amb-fader amb-groove ambx-fader", `ambx-fader-${size}`)}
-        ref={trackRef}
-        role="slider"
-        aria-label={label}
-        aria-labelledby={label ? id : undefined}
-        aria-valuemin={min}
-        aria-valuemax={max}
-        aria-valuenow={value}
-        aria-orientation="vertical"
-        tabIndex={0}
-        onPointerDown={(event) => {
-          event.currentTarget.setPointerCapture(event.pointerId);
-          updateFromClientY(event.clientY);
-        }}
-        onPointerMove={onPointerMove}
-        onKeyDown={onKeyDown}
-      >
-        <div
-          className={cn("amb-fader-thumb ambient amb-fillet ambx-fader-thumb", material !== "glass" && "amb-surface-concave", material && `amb-mat-${material}`)}
-          style={{ top: `${100 - percent}%` }}
-        >
-          <span className="amb-fader-gripline" />
-        </div>
-      </div>
-      {label ? (
-        <span id={id} className="ambx-label">
-          {label}
-        </span>
-      ) : null}
-    </div>
+    <AmbientTravel
+      {...rest}
+      orientation="vertical"
+      size={size}
+      animate={animate ?? defaults?.animate}
+      className={cn(dress.className, className)}
+      parts={dress.parts}
+    />
   );
 }

package/src/components/AmbientKnob.tsx

@@ -1,237 +1,75 @@
-import { useId, useRef } from "react";
-import type { HTMLAttributes, KeyboardEvent, PointerEvent } from "react";
 import { cn } from "../lib/cn";
+import { AmbientRotary } from "../controls/AmbientRotary";
+import type { AmbientRotaryProps } from "../controls/AmbientRotary";
+import { useDress } from "../core/kit";
+import type { KitLook } from "../core/kit";
+import type { AmbientMaterial } from "../core/material";
+import { groundedKit } from "../kits/grounded";
 
-/* Straight-knurled silhouettes for the rotating face, in
-   objectBoundingBox units so the clip scales with the component. Each
-   variant family mirrors its referent's rib section
-   (ambient3d/ground_components.py): trapezoid teeth between the outer
-   radius and the tooth-root radius. The circular body underneath keeps
-   the smooth drop shadow. */
-type KnurlSpec = {
-  teeth: number; // rib count
-  root: number; // tooth-root radius (bounding-box units; outer is 0.5)
-  rise: number; // fraction of the pitch spent climbing to the crest
-  fall: [number, number]; // crest-end and root-return pitch fractions
-};
-
-const KNURLS: Record<"standard" | "flute" | "fine", KnurlSpec> = {
-  /* 36 ribs — the grounded referent knob (dot and line variants) */
-  standard: { teeth: 36, root: 0.468, rise: 0.12, fall: [0.5, 0.62] },
-  /* 14 broad flutes with deeper roots (OP-Z-style flute variant) */
-  flute: { teeth: 14, root: 0.44, rise: 0.08, fall: [0.72, 0.8] },
-  /* 48-rib fine knurl, shallower (cap and wheel variants) */
-  fine: { teeth: 48, root: 0.476, rise: 0.12, fall: [0.5, 0.62] }
-};
-
-function knurlPath({ teeth, root, rise, fall }: KnurlSpec): string {
-  const outer = 0.5;
-  const pitch = (Math.PI * 2) / teeth;
-  const pts: string[] = [];
-  for (let i = 0; i < teeth; i++) {
-    const a = i * pitch;
-    const tooth: Array<[number, number]> = [
-      [0, root],
-      [rise, outer],
-      [fall[0], outer],
-      [fall[1], root]
-    ];
-    for (const [frac, radius] of tooth) {
-      const t = a + frac * pitch;
-      pts.push(
-        `${(0.5 + radius * Math.cos(t)).toFixed(4)} ${(0.5 + radius * Math.sin(t)).toFixed(4)}`
-      );
-    }
-  }
-  return `M${pts.join(" L")} Z`;
-}
+/** Printed scale dots on the panel around the knob: the arc's two ends, the
+ *  full graduated ring, or nothing. */
+export type AmbientKnobMarkers = "none" | "ends" | "full";
 
-const KNURL_PATHS = {
-  standard: knurlPath(KNURLS.standard),
-  flute: knurlPath(KNURLS.flute),
-  fine: knurlPath(KNURLS.fine)
-};
-
-/* Knob types from the referent lineup (ambient3d/generate.py):
-   - "dot":   the grounded referent — 36-rib knurl, offset indicator dot
-   - "line":  same body with a radial indicator line (classic pot)
-   - "flute": 14 broad flutes, centered dot (OP-Z-style encoder)
-   - "cap":   fine knurl under a smooth accent top disc (OP-1-style)
-   - "wheel": bare fine knurl, no indicator (machined wheel — pair with
-     material="shiny") */
-export type AmbientKnobVariant = "dot" | "line" | "flute" | "cap" | "wheel";
-
-const VARIANT_FAMILY: Record<AmbientKnobVariant, keyof typeof KNURL_PATHS> = {
-  dot: "standard",
-  line: "standard",
-  flute: "flute",
-  cap: "fine",
-  wheel: "fine"
-};
+/** The pointer riding the rotating face: a radial bar or an offset dot. */
+export type AmbientKnobIndicator = "rectangle" | "circle";
 
 export type AmbientKnobSize = "sm" | "md" | "lg";
 
-export type AmbientKnobProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange"> & {
-  value: number;
-  min?: number;
-  max?: number;
-  step?: number;
-  label?: string;
-  material?: "matte" | "shiny" | "glass";
-  variant?: AmbientKnobVariant;
-  size?: AmbientKnobSize;
-  onChange?: (nextValue: number) => void;
+export type AmbientKnobProps = Omit<AmbientRotaryProps, "parts" | "size"> & {
+  material?: AmbientMaterial | undefined;
+  /** Ribbed grip around the rotating body. Off gives a smooth turned body. */
+  knurling?: boolean | undefined;
+  /** The grip ring's own colour, for a two-tone knob — any CSS colour, read
+   *  as an albedo, so it still takes the scene's light rather than being
+   *  painted flat. Unset, the ring is the same material as the cap. */
+  knurlColor?: string | undefined;
+  markers?: AmbientKnobMarkers | undefined;
+  indicator?: AmbientKnobIndicator | undefined;
+  size?: AmbientKnobSize | undefined;
+  /** Look options in another kit's vocabulary.
+   *
+   *  The five props above are the *grounded* kit's words. A kit that dresses
+   *  knobs differently has its own, and they arrive here rather than as
+   *  loose props so the common path stays typed and a misspelt `knurling`
+   *  is still a compile error. Kits usually ship a preset of their own that
+   *  types this properly — see `ConsoleKnob`. */
+  look?: KitLook | undefined;
 };
 
-function clamp(value: number, min: number, max: number): number {
-  return Math.min(max, Math.max(min, value));
-}
-
+/**
+ * The rotary preset: `AmbientRotary` wearing whatever the active kit says a
+ * knob looks like, and the grounded hardware knob when no kit is set.
+ */
 export function AmbientKnob({
-  value,
-  min = 0,
-  max = 100,
-  step = 1,
-  label,
   material,
-  variant = "dot",
+  knurling,
+  knurlColor,
+  markers,
+  indicator,
+  look,
   size = "md",
-  onChange,
   className,
-  ...props
+  travel,
+  input,
+  animate,
+  ...rest
 }: AmbientKnobProps) {
-  const id = useId();
-  const clipId = `amb-knurl-${id.replace(/:/g, "")}`;
-  const draggingRef = useRef(false);
-  const knobRef = useRef<HTMLDivElement>(null);
-  const safeStep = step > 0 ? step : 1;
-  const family = VARIANT_FAMILY[variant];
-
-  const percent = (value - min) / (max - min || 1);
-  const rotation = percent * 270 - 135;
-
-  // Convert pointer position to a knob angle in [-180, 180] where 0 = up,
-  // positive = clockwise. The knob's active range is [-135, 135] (270°),
-  // with the dead zone at the bottom (~135° to ~225° i.e. past ±135°).
-  const pointerToValue = (event: PointerEvent<HTMLDivElement>) => {
-    const rect = knobRef.current!.getBoundingClientRect();
-    const cx = rect.left + rect.width / 2;
-    const cy = rect.top + rect.height / 2;
-    // atan2 with screen coords: 0=right, 90=down; add 90 to rotate so 0=up
-    const atan2Deg = Math.atan2(event.clientY - cy, event.clientX - cx) * (180 / Math.PI);
-    let angle = atan2Deg + 90;
-    // Normalize to [-180, 180]
-    if (angle > 180) angle -= 360;
-
-    // Clamp dead zone based on current value position
-    if (angle < -135 || angle > 135) {
-      angle = percent >= 0.5 ? 135 : -135;
-    }
-
-    const range = max - min;
-    const raw = min + ((angle + 135) / 270) * range;
-    const snapped = Math.round(raw / 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 "ArrowUp":
-      case "ArrowRight":
-        event.preventDefault();
-        setValue(value + safeStep);
-        break;
-      case "ArrowDown":
-      case "ArrowLeft":
-        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 { dress, defaults } = useDress(
+    "rotary",
+    { material, knurling, knurlColor, markers, indicator, ...look },
+    groundedKit.rotary!
+  );
 
   return (
-    <div className={cn("ambx-stack", className)} {...props}>
-      <div
-        ref={knobRef}
-        className={cn("amb-knob ambx-knob", `ambx-knob-${size}`)}
-        role="slider"
-        aria-label={label}
-        aria-valuemin={min}
-        aria-valuemax={max}
-        aria-valuenow={value}
-        aria-labelledby={label ? id : undefined}
-        aria-orientation="vertical"
-        tabIndex={0}
-        onPointerDown={(event) => {
-          event.currentTarget.setPointerCapture(event.pointerId);
-          draggingRef.current = true;
-          pointerToValue(event);
-        }}
-        onPointerMove={(event) => {
-          if (draggingRef.current) pointerToValue(event);
-        }}
-        onPointerUp={() => {
-          draggingRef.current = false;
-        }}
-        onPointerCancel={() => {
-          draggingRef.current = false;
-        }}
-        onKeyDown={onKeyDown}
-      >
-        <svg width={0} height={0} style={{ position: "absolute" }} aria-hidden focusable={false}>
-          <defs>
-            <clipPath id={clipId} clipPathUnits="objectBoundingBox">
-              <path d={KNURL_PATHS[family]} />
-            </clipPath>
-          </defs>
-        </svg>
-        <span className="amb-knob-body ambient amb-thickness-2 amb-surface" />
-        <div
-          className={cn(
-            "ambx-knob-rotation amb-knob-face",
-            family === "flute" && "amb-knob-face-flute",
-            family === "fine" && "amb-knob-face-fine",
-            variant === "cap" && "amb-knob-face-cap",
-            material && `amb-mat-${material}`
-          )}
-          style={{ transform: `rotate(${rotation}deg)`, clipPath: `url(#${clipId})` }}
-        >
-          {variant === "dot" ? <span className="amb-knob-indicator-dot" /> : null}
-          {variant === "line" ? <span className="amb-knob-indicator-line" /> : null}
-          {variant === "flute" ? (
-            <span className="amb-knob-indicator-dot amb-knob-indicator-dot-center" />
-          ) : null}
-        </div>
-      </div>
-      {label ? (
-        <span id={id} className="ambx-label">
-          {label}
-        </span>
-      ) : null}
-    </div>
+    <AmbientRotary
+      {...rest}
+      /* Caller wins over kit, kit wins over the mechanism's own default. */
+      travel={travel ?? defaults?.travel}
+      input={input ?? defaults?.input}
+      animate={animate ?? defaults?.animate}
+      size={size}
+      className={cn(dress.className, className)}
+      parts={dress.parts}
+    />
   );
 }

package/src/components/AmbientPanel.tsx

@@ -1,16 +1,22 @@
 import type { HTMLAttributes } from "react";
 import { cn } from "../lib/cn";
+import type { AmbientMaterial } from "../core/material";
 
 export interface AmbientPanelProps extends HTMLAttributes<HTMLDivElement> {
-  material?: "matte" | "shiny" | "glass";
+  material?: AmbientMaterial;
 }
 
+/** A panel is a plain surface, so it can wear any finish directly: it spends
+ *  neither pseudo-element of its own, which is what the two micro-relief
+ *  materials need. Their grain paints below the panel's children, and their
+ *  `overflow: hidden` clips whatever hangs outside it — a control's drop
+ *  shadow at the very edge included. */
 export function AmbientPanel({ className, material = "matte", ...props }: AmbientPanelProps) {
   return (
     <div
       className={cn(
         "ambient amb-surface amb-chamfer amb-elevation-2 ambx-panel",
-        material === "matte" ? "amb-mat-matte" : material === "shiny" ? "amb-mat-shiny" : "amb-mat-glass",
+        `amb-mat-${material}`,
         className
       )}
       {...props}

package/src/components/AmbientProvider.tsx

@@ -47,6 +47,9 @@ export function AmbientProvider({ children, className, style, theme }: AmbientPr
   ].join(" ");
   themeVars["--amb-label"] =
     "hsl(var(--amb-light-hue) var(--amb-light-saturation) calc((1 - var(--amb-key-light-intensity)) * 60% + 20%))";
+  // --amb-curve-delta deliberately absent: unlike these two it is declared
+  // per element in ambient.css, so it already re-resolves against the light
+  // overridden here. Re-declaring it would only re-copy the fit.
   const mergedStyle = { ...themeVars, ...style } as CSSProperties;
 
   return (

package/src/components/AmbientSelect.tsx

@@ -0,0 +1,40 @@
+import { cn } from "../lib/cn";
+import { AmbientBank } from "../controls/AmbientBank";
+import type { AmbientBankProps } from "../controls/AmbientBank";
+import type { BankOption, BankOrientation } from "../core/useBank";
+import { useDress } from "../core/kit";
+import type { KitLook } from "../core/kit";
+import { groundedKit } from "../kits/grounded";
+
+export type AmbientSelectOption = BankOption;
+export type AmbientSelectOrientation = BankOrientation;
+export type AmbientSelectSize = "sm" | "md" | "lg";
+
+export type AmbientSelectProps = Omit<AmbientBankProps, "keyParts" | "parts" | "size"> & {
+  size?: AmbientSelectSize | undefined;
+  /** Look options in the active kit's vocabulary. */
+  look?: KitLook | undefined;
+};
+
+/**
+ * A bank of lamp-lit keys in a shared rail — the hardware idiom for a
+ * mode selector, where the state is a lamp rather than a mark.
+ *
+ * Three physical layers per key, and the ORDER is the whole trick: the key
+ * itself is the pocket floor, the lens is a disc lying on it, and the cap
+ * is a translucent diffuser over both. The cap is `.amb-mat-glass`, so its
+ * backdrop-filter blurs the lens behind it — which is why the lens goes in
+ * the `base` frame and the cap in `actuator`, and why swapping them would
+ * put out every lamp.
+ */
+export function AmbientSelect({ size = "md", look, className, ...rest }: AmbientSelectProps) {
+  const { dress } = useDress("bank", { ...look }, groundedKit.bank!);
+  return (
+    <AmbientBank
+      {...rest}
+      size={size}
+      className={cn(dress.className, className)}
+      keyParts={dress.parts}
+    />
+  );
+}