@ambientcss/components 2.1.0 → 3.0.1

package/src/core/useTravel.ts

@@ -0,0 +1,141 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { CSSProperties, KeyboardEvent, PointerEvent } from "react";
+import { useControllableValue } from "./controllable";
+import { clamp, commit, denormalise, normalise, valueKeyHandler } from "./numeric";
+import { capturePointer } from "./useRotary";
+import { stateData, stateStyle } from "./types";
+import type { ControlState } from "./types";
+
+export type TravelOrientation = "horizontal" | "vertical";
+
+export type UseTravelOptions = {
+  value?: number | undefined;
+  defaultValue?: number | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  step?: number | undefined;
+  detents?: number | undefined;
+  orientation?: TravelOrientation | undefined;
+  /** Flip which end of the axis is `min`. */
+  invert?: boolean | undefined;
+  disabled?: boolean | undefined;
+  onChange?: ((next: number) => void) | undefined;
+};
+
+/** A value riding a straight track.
+ *
+ *  One mechanism behind both the slider and the fader, which before v3 were
+ *  the same file twice with X and Y swapped. The only real difference is
+ *  which axis the pointer reads — and which end is `min`, where the two
+ *  disagree for a physical reason rather than a stylistic one: a horizontal
+ *  track runs min-at-the-left, and an upright one runs min-at-the-bottom,
+ *  because that is how a fader is built. Both are the default here, so
+ *  neither preset has to ask. */
+export function useTravel(options: UseTravelOptions) {
+  const {
+    min = 0,
+    max = 100,
+    step = 1,
+    orientation = "horizontal",
+    invert = false,
+    disabled = false
+  } = options;
+
+  const [value, setValue] = useControllableValue(
+    options.value,
+    options.defaultValue ?? min,
+    options.onChange
+  );
+
+  const [dragging, setDragging] = useState(false);
+  const draggingRef = useRef(false);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+
+  const vertical = orientation === "vertical";
+  const range = max - min;
+  const keyStep = step > 0 ? step : range / 100 || 1;
+  const percent = clamp(normalise(value, min, max), 0, 1);
+
+  const set = useCallback(
+    (next: number) => setValue(commit(next, min, max, step)),
+    [setValue, min, max, step]
+  );
+
+  const track = (event: PointerEvent<HTMLElement>) => {
+    const rect = rootRef.current?.getBoundingClientRect();
+    if (!rect) return;
+    // An upright track reads bottom-up: 1 at the top of the box.
+    const raw = vertical
+      ? 1 - (event.clientY - rect.top) / (rect.height || 1)
+      : (event.clientX - rect.left) / (rect.width || 1);
+    set(denormalise(clamp(invert ? 1 - raw : raw, 0, 1), min, max));
+  };
+
+  const state: ControlState = useMemo(
+    () => ({
+      value,
+      min,
+      max,
+      percent,
+      angle: 0,
+      travelStart: 0,
+      travelSweep: 0,
+      detents: options.detents ?? (step > 0 && range > 0 ? Math.round(range / step) : 0),
+      dragging,
+      disabled,
+      atMin: value <= min,
+      atMax: value >= max
+    }),
+    [value, min, max, percent, options.detents, step, range, dragging, disabled]
+  );
+
+  const onKeyDown = valueKeyHandler({
+    value,
+    min,
+    max,
+    step: keyStep,
+    disabled,
+    invert,
+    onChange: setValue
+  });
+
+  const rootProps = {
+    ref: rootRef,
+    role: "slider" as const,
+    "aria-valuemin": min,
+    "aria-valuemax": max,
+    "aria-valuenow": value,
+    "aria-orientation": orientation,
+    "aria-disabled": disabled || undefined,
+    tabIndex: disabled ? -1 : 0,
+    style: stateStyle(state) as CSSProperties,
+    "data-orientation": orientation,
+    ...stateData(state),
+    onPointerDown: (event: PointerEvent<HTMLDivElement>) => {
+      if (disabled || event.button !== 0) return;
+      capturePointer(event.currentTarget, event.pointerId);
+      draggingRef.current = true;
+      setDragging(true);
+      /* A track is absolute by nature: pressing anywhere on it means "put
+         the thumb here", which is what a fader does under a finger. */
+      track(event);
+    },
+    onPointerMove: (event: PointerEvent<HTMLDivElement>) => {
+      if (!draggingRef.current || disabled) return;
+      track(event);
+    },
+    onPointerUp: () => {
+      draggingRef.current = false;
+      setDragging(false);
+    },
+    onPointerCancel: () => {
+      draggingRef.current = false;
+      setDragging(false);
+    },
+    onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => {
+      onKeyDown(event);
+    }
+  };
+
+  return { state, rootProps, setValue: set };
+}

package/src/index.ts

@@ -7,17 +7,137 @@ export type { AmbientPanelProps } from "./components/AmbientPanel";
 export { AmbientRack } from "./components/AmbientRack";
 export type { AmbientRackProps, AmbientRackGap } from "./components/AmbientRack";
 
+/* ------------------------------------------------------------------ *\
+   Presets — a mechanism with a set of parts already chosen. Start here.
+\* ------------------------------------------------------------------ */
+
 export { AmbientButton } from "./components/AmbientButton";
-export type { AmbientButtonProps, AmbientButtonShape, AmbientButtonSize } from "./components/AmbientButton";
+export type {
+  AmbientButtonProps,
+  AmbientButtonShape,
+  AmbientButtonSize
+} from "./components/AmbientButton";
 
 export { AmbientSwitch } from "./components/AmbientSwitch";
 export type { AmbientSwitchProps, AmbientSwitchSize } from "./components/AmbientSwitch";
 
+export { AmbientSelect } from "./components/AmbientSelect";
+export type {
+  AmbientSelectProps,
+  AmbientSelectOption,
+  AmbientSelectSize,
+  AmbientSelectOrientation
+} from "./components/AmbientSelect";
+
 export { AmbientKnob } from "./components/AmbientKnob";
-export type { AmbientKnobProps, AmbientKnobVariant, AmbientKnobSize } from "./components/AmbientKnob";
+export type {
+  AmbientKnobProps,
+  AmbientKnobMarkers,
+  AmbientKnobIndicator,
+  AmbientKnobSize
+} from "./components/AmbientKnob";
 
 export { AmbientFader } from "./components/AmbientFader";
 export type { AmbientFaderProps, AmbientFaderSize } from "./components/AmbientFader";
 
 export { AmbientSlider } from "./components/AmbientSlider";
 export type { AmbientSliderProps, AmbientSliderSize } from "./components/AmbientSlider";
+
+/* ------------------------------------------------------------------ *\
+   Mechanisms — kinematics, state and ARIA with no appearance at all.
+   Give one a set of parts and it becomes whatever you drew.
+\* ------------------------------------------------------------------ */
+
+export { AmbientRotary } from "./controls/AmbientRotary";
+export type { AmbientRotaryProps } from "./controls/AmbientRotary";
+
+export { AmbientTravel } from "./controls/AmbientTravel";
+export type { AmbientTravelProps } from "./controls/AmbientTravel";
+
+export { AmbientPress } from "./controls/AmbientPress";
+export type { AmbientPressProps } from "./controls/AmbientPress";
+
+export { AmbientLatch } from "./controls/AmbientLatch";
+export type { AmbientLatchProps } from "./controls/AmbientLatch";
+
+export { AmbientBank } from "./controls/AmbientBank";
+export type { AmbientBankProps } from "./controls/AmbientBank";
+
+/* ------------------------------------------------------------------ *\
+   Hooks — the mechanism without the markup, for a control you render
+   yourself from the ground up.
+\* ------------------------------------------------------------------ */
+
+export { useRotary } from "./core/useRotary";
+export type { UseRotaryOptions, RotaryInput, RotaryTravel } from "./core/useRotary";
+
+export { useTravel } from "./core/useTravel";
+export type { UseTravelOptions, TravelOrientation } from "./core/useTravel";
+
+export { usePress } from "./core/usePress";
+export type { UsePressOptions, PressMode } from "./core/usePress";
+
+export { useLatch } from "./core/useLatch";
+export type { UseLatchOptions } from "./core/useLatch";
+
+export { useBank } from "./core/useBank";
+export type { UseBankOptions, BankOption, BankOrientation } from "./core/useBank";
+
+/* ------------------------------------------------------------------ *\
+   Kits — a named bundle of parts, tokens and presentation defaults that
+   dresses every control below it. A kit is a plain object, so publishing
+   one is publishing a module. A kit that leaves a family undefined falls
+   through to `grounded`.
+\* ------------------------------------------------------------------ */
+
+export { AmbientKitProvider, useKit, useDress } from "./core/kit";
+export type {
+  ControlKit,
+  ControlFamily,
+  KitDress,
+  KitLook,
+  KitDefaults
+} from "./core/kit";
+
+export { groundedKit } from "./kits/grounded";
+export { consoleKit, ConsoleKnob, ConsoleToggle } from "./kits/console";
+export type { ConsoleKnobProps, ConsoleToggleProps } from "./kits/console";
+
+export {
+  ConsoleBar,
+  ConsoleMarks,
+  ConsoleWell,
+  ToggleTrack,
+  ToggleThumb
+} from "./parts/console";
+
+/* ------------------------------------------------------------------ *\
+   The state channel — read the enclosing control from inside a part.
+   The custom properties on the control root are canonical; these are a
+   typed view of the same values, for parts that need JS.
+\* ------------------------------------------------------------------ */
+
+export { useControlState, useBankKey } from "./core/context";
+export type { BankKeyState } from "./core/context";
+export type {
+  ControlParts,
+  ControlState,
+  ControlSize,
+  ControlAnimate,
+  FrameName
+} from "./core/types";
+export type { AmbientMaterial } from "./core/material";
+
+/* ------------------------------------------------------------------ *\
+   Default parts. Nothing privileged about them — each is markup with
+   some ambient classes, and a replacement of yours stands on exactly the
+   same footing. They live in their own modules so an app that ships only
+   its own parts does not pay for these.
+\* ------------------------------------------------------------------ */
+
+export { KnobBody, KnurledFace, IndicatorDot, IndicatorBar, ScaleRing } from "./parts/knob";
+export type { ScaleRingProps } from "./parts/knob";
+export { TravelTrack, FaderCap, SliderThumb } from "./parts/travel";
+export { ButtonCap } from "./parts/press";
+export { SwitchTrack, SwitchPill, Led } from "./parts/latch";
+export { KeyLens, KeyCap } from "./parts/bank";

package/src/kits/console.tsx

@@ -0,0 +1,80 @@
+import { cn } from "../lib/cn";
+import { AmbientKnob } from "../components/AmbientKnob";
+import type { AmbientKnobProps } from "../components/AmbientKnob";
+import { AmbientSwitch } from "../components/AmbientSwitch";
+import type { AmbientSwitchProps } from "../components/AmbientSwitch";
+import type { ControlKit, KitDress, KitLook } from "../core/kit";
+import { ConsoleBar, ConsoleMarks, ConsoleWell, ToggleThumb, ToggleTrack } from "../parts/console";
+
+/**
+ * A mixer-desk visual identity: cuboid bar knobs seated in a circular
+ * groove, and pill toggles that light up with the panel accent.
+ *
+ * It dresses two families and leaves the other three to fall through to
+ * `grounded` — which is what a real third-party kit looks like. A kit is not
+ * obliged to have an opinion about everything.
+ */
+
+function rotary(look: KitLook): KitDress {
+  const mark = look.mark !== false;
+  const legend = look.legend !== false;
+  return {
+    className: cn(
+      "amb-console-knob",
+      mark && "amb-console-knob-marked",
+      legend && "amb-console-knob-legended"
+    ),
+    parts: {
+      panel: mark || legend ? <ConsoleMarks mark={mark} legend={legend} /> : null,
+      base: <ConsoleWell />,
+      actuator: <ConsoleBar />
+    }
+  };
+}
+
+function latch(): KitDress {
+  return {
+    className: "amb-console-toggle",
+    parts: { base: <ToggleTrack />, actuator: <ToggleThumb /> }
+  };
+}
+
+export const consoleKit: ControlKit = {
+  name: "console",
+  rotary,
+  latch,
+  /* A visual identity may say how its controls feel to turn. The desk knob
+     this is drawn from is an absolute-position pot with a centre detent, so
+     it grabs where you press rather than tracking a drag. */
+  defaults: {
+    rotary: { input: "angle", travel: 280 }
+  },
+  looks: {
+    rotary: ["mark", "legend"],
+    latch: []
+  }
+};
+
+/* A kit can also ship presets of its own. They are three lines each — the
+   shared preset with this kit's look vocabulary typed — and they are how a
+   kit gives its own words the same compile-time checking `knurling` gets. */
+
+export type ConsoleKnobProps = Omit<
+  AmbientKnobProps,
+  "look" | "material" | "knurling" | "knurlColor" | "markers" | "indicator"
+> & {
+  /** The accent centre mark printed above the knob. */
+  mark?: boolean | undefined;
+  /** The −/+ legends at the ends of the travel. */
+  legend?: boolean | undefined;
+};
+
+export function ConsoleKnob({ mark, legend, ...rest }: ConsoleKnobProps) {
+  return <AmbientKnob {...rest} look={{ mark, legend }} />;
+}
+
+export type ConsoleToggleProps = Omit<AmbientSwitchProps, "look">;
+
+export function ConsoleToggle(props: ConsoleToggleProps) {
+  return <AmbientSwitch {...props} />;
+}

package/src/kits/grounded.tsx

@@ -0,0 +1,113 @@
+import { cn } from "../lib/cn";
+import type { ControlKit, KitDress, KitLook } from "../core/kit";
+import type { AmbientMaterial } from "../core/material";
+import { IndicatorBar, IndicatorDot, KnobBody, KnurledFace, ScaleRing } from "../parts/knob";
+import { FaderCap, SliderThumb, TravelTrack } from "../parts/travel";
+import { ButtonCap } from "../parts/press";
+import { SwitchPill, SwitchTrack } from "../parts/latch";
+import { KeyCap, KeyLens } from "../parts/bank";
+
+/* The built-in look, packaged as a kit rather than hardwired into the
+   presets. That is the integrity test for the whole idea: if the grounded
+   parts needed a private back door the presets could reach and a third party
+   could not, the abstraction would be a fiction. They do not — everything
+   below is the same `(look) => { parts, className }` a published kit writes. */
+
+/* 12 divisions — 13 dots over the sweep, the pitch measured off the
+   reference panel. */
+const FULL_MARKERS = 13;
+
+function rotary(look: KitLook): KitDress {
+  const material = look.material as AmbientMaterial | undefined;
+  const knurling = look.knurling !== false;
+  const knurlColor = look.knurlColor as string | undefined;
+  const markers = (look.markers as "none" | "ends" | "full" | undefined) ?? "none";
+  const indicator = (look.indicator as "circle" | "rectangle" | undefined) ?? "circle";
+
+  return {
+    /* The full ring reaches past the knob's own box, so its layout clearance
+       has to be reserved — and only the kit knows it put a ring there. */
+    className: cn("amb-knob", markers === "full" && "amb-knob-markers-full"),
+    parts: {
+      panel:
+        markers === "none" ? null : <ScaleRing count={markers === "ends" ? 2 : FULL_MARKERS} />,
+      /* `material` goes on every element that paints. The cap always does —
+         it is the knob's top face either way — and the knurl ring does too
+         when there is one, so a knurled knob's rim and cap are the same
+         material rather than the rim being the only thing wearing it.
+
+         `knurlColor` is the one thing the ring may hold on its own: a
+         two-tone knob — dark grip round a pale cap — is a real piece of
+         hardware, and the cap has no matching prop because the cap's colour
+         is the control's colour, set the ordinary way with --amb-albedo. */
+      base: <KnobBody flush={!knurling} material={material} />,
+      actuator: (
+        <>
+          {knurling ? <KnurledFace material={material} color={knurlColor} /> : null}
+          {indicator === "circle" ? <IndicatorDot /> : <IndicatorBar />}
+        </>
+      )
+    }
+  };
+}
+
+function travel(look: KitLook): KitDress {
+  const material = look.material as AmbientMaterial | undefined;
+  const upright = look.orientation === "vertical";
+  return {
+    className: upright ? "amb-fader" : "amb-slider",
+    parts: {
+      base: <TravelTrack depth={upright ? "slot" : "channel"} />,
+      actuator: upright ? <FaderCap material={material} /> : <SliderThumb material={material} />
+    }
+  };
+}
+
+function press(look: KitLook): KitDress {
+  const shape = (look.shape as "pill" | "round" | "square" | undefined) ?? "pill";
+  return {
+    className: cn(
+      "amb-button amb-groove",
+      shape === "round" && "amb-button-round",
+      shape === "square" && "amb-button-square"
+    ),
+    parts: {
+      actuator: (
+        <ButtonCap material={(look.material as AmbientMaterial | undefined) ?? "matte"}>
+          {look.children as React.ReactNode}
+        </ButtonCap>
+      )
+    }
+  };
+}
+
+function latch(): KitDress {
+  return {
+    className: "amb-switch",
+    parts: { base: <SwitchTrack />, actuator: <SwitchPill /> }
+  };
+}
+
+function bank(): KitDress {
+  return {
+    className: "amb-select amb-groove",
+    parts: { base: <KeyLens />, actuator: <KeyCap /> }
+  };
+}
+
+/** The Blender-grounded hardware look: the default every preset falls back to. */
+export const groundedKit: ControlKit = {
+  name: "grounded",
+  rotary,
+  travel,
+  press,
+  latch,
+  bank,
+  looks: {
+    rotary: ["material", "knurling", "knurlColor", "markers", "indicator"],
+    travel: ["material", "orientation"],
+    press: ["material", "shape", "children"],
+    latch: [],
+    bank: []
+  }
+};

package/src/parts/bank.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { useBankKey } from "../core/context";
+
+/** The lamp under a key: a big disc lying on the pocket floor.
+ *
+ *  It has to paint BEFORE the cap, because the cap's `backdrop-filter` is
+ *  what diffuses it — which is the whole trick, and the reason the lens
+ *  belongs in the `base` frame and the cap in `actuator`. */
+export function KeyLens({ className }: { className?: string | undefined }) {
+  return <span className={cn("amb-select-lens", className)} />;
+}
+
+/** The translucent diffuser over the lamp, carrying the key's legend.
+ *
+ *  With no children it prints the option's own label, which is why a bank
+ *  of numerals needs no `renderKey`: the part reads the option it belongs
+ *  to out of the key context. */
+export function KeyCap({
+  className,
+  children
+}: {
+  className?: string | undefined;
+  children?: ReactNode | undefined;
+}) {
+  const { option } = useBankKey();
+  return (
+    <span className={cn("amb-select-cap ambient amb-chamfer amb-mat-glass", className)}>
+      {children ?? option.label ?? option.value}
+    </span>
+  );
+}

package/src/parts/console.tsx

@@ -0,0 +1,101 @@
+import { cn } from "../lib/cn";
+
+/* Parts for the `console` kit — a mixer-desk visual language, measured off
+   photographs of the real controls. Nothing here is a variant of a grounded
+   part: a bar knob and a lit pill track are a different vocabulary, which is
+   the reason kits exist rather than another round of boolean props. */
+
+/** The knob's base: a flat face housed in a circular groove.
+ *
+ *  Two elements, because they are two pieces of the panel: the groove is the
+ *  cut, and the face is the flat disc sitting in it, showing the ring of the
+ *  cut around itself. Neither carries `.ambient` — the face has no body, so
+ *  there is no edge to cut and nothing to cast, and every cue that reads as
+ *  depth here belongs either to the walls of the housing or to the bar
+ *  standing on the face.
+ *
+ *  It sits in the `base` frame, so it does not turn. A plain disc looks the
+ *  same at every angle, and leaving it still keeps the scene's light on it
+ *  untouched — only the bar has to do the work below. */
+export function ConsoleWell({ className }: { className?: string | undefined }) {
+  return (
+    <span className={cn("amb-console-housing amb-groove", className)}>
+      <span className="amb-console-face amb-surface" />
+    </span>
+  );
+}
+
+/** The actuator: a cuboid bar lying across the disc on its diameter.
+ *
+ *  Two spans, and the nesting is load-bearing. The bar rides the rotating
+ *  actuator frame, so a chamfer highlight painted from the inherited light
+ *  would turn with it and put the lit edge on the wrong side of the screen
+ *  at half the angles. The fix is to rotate the LIGHT the other way: the
+ *  outer span captures the scene's light vector, the inner one re-states it
+ *  in the frame's own turned coordinates, so the bright edge and the drop
+ *  shadow both stay put on screen while the bar sweeps under them.
+ *
+ *  It has to be two elements because a custom property cannot read itself —
+ *  `--amb-light-x: calc(var(--amb-light-x) ...)` is a cycle, which resolves
+ *  to invalid at computed-value time and takes the whole `box-shadow`
+ *  composite down with it, silently. */
+export function ConsoleBar({ className }: { className?: string | undefined }) {
+  return (
+    <span className={cn("amb-console-bar", className)}>
+      <span className="amb-console-bar-body ambient amb-surface amb-chamfer amb-thickness-2">
+        {/* Printed on the bar near one end, the way the reference prints a
+            short black mark at the outer edge of its pointer: with a bar
+            that crosses the whole face, this is what says which end reads. */}
+        <span className="amb-console-indicator" />
+      </span>
+    </span>
+  );
+}
+
+/** Panel graphics around the knob: the centre mark above it, and the
+ *  −/+ legends at the ends of the travel. Both sit outside the knob's own
+ *  box, which is what the `panel` frame is for. */
+export function ConsoleMarks({
+  mark = true,
+  legend = true,
+  className
+}: {
+  mark?: boolean | undefined;
+  legend?: boolean | undefined;
+  className?: string | undefined;
+}) {
+  return (
+    <span className={cn("amb-console-marks", className)} aria-hidden>
+      {mark ? <span className="amb-console-mark amb-surface" /> : null}
+      {legend ? (
+        <>
+          <span className="amb-console-legend amb-console-legend-min">−</span>
+          <span className="amb-console-legend amb-console-legend-max">+</span>
+        </>
+      ) : null}
+    </span>
+  );
+}
+
+/** The toggle's track: a pill groove that fills with the accent as the
+ *  switch travels.
+ *
+ *  A pure-CSS part — it reads `--ambx-percent` off the control root and
+ *  mixes its own colour from it, so the mechanism does not know this element
+ *  exists and no React state reaches it. */
+export function ToggleTrack({ className }: { className?: string | undefined }) {
+  return <span className={cn("amb-console-track amb-groove", className)} />;
+}
+
+/** The travelling thumb: an albedo disc inside a light ring.
+ *
+ *  Flat on top and deliberately so — no chamfer, no fillet — but still a
+ *  knob-scale body, so it casts. That pairing is why the classes are spelt
+ *  out rather than reached through `.amb-fillet-2`: the edge treatments set
+ *  a thickness of their own, and here the thickness is wanted without the
+ *  cut that usually comes with it. It wears `amb-surface`, so its colour IS
+ *  the scene's albedo under the current light rather than a fixed paint —
+ *  it re-shades when the lamp moves or the intensities change. */
+export function ToggleThumb({ className }: { className?: string | undefined }) {
+  return <span className={cn("amb-console-thumb ambient amb-surface amb-thickness-2", className)} />;
+}