@ambientcss/components 2.1.0 → 3.0.1

package/src/controls/AmbientTravel.tsx

@@ -0,0 +1,83 @@
+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 { useTravel } from "../core/useTravel";
+import type { UseTravelOptions } from "../core/useTravel";
+
+export type AmbientTravelProps = Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> &
+  UseTravelOptions & {
+    parts?: ControlParts | undefined;
+    size?: ControlSize | undefined;
+    animate?: ControlAnimate | undefined;
+    label?: ReactNode | undefined;
+  };
+
+/** A value on a straight track, with no appearance of its own. */
+export function AmbientTravel({
+  parts,
+  size,
+  animate = "auto",
+  label,
+  className,
+  value,
+  defaultValue,
+  min,
+  max,
+  step,
+  detents,
+  orientation = "horizontal",
+  invert,
+  disabled,
+  onChange,
+  ...rest
+}: AmbientTravelProps) {
+  const labelId = useId();
+  const stackRef = useRef<HTMLDivElement>(null);
+  const { state, rootProps } = useTravel({
+    value,
+    defaultValue,
+    min,
+    max,
+    step,
+    detents,
+    orientation,
+    invert,
+    disabled,
+    onChange
+  });
+  useDevPartCheck(stackRef, "AmbientTravel");
+
+  const sized = sizeProps("travel", size);
+  const { style: restStyle, ...restProps } = rest;
+
+  return (
+    <div className="ambx-stack" ref={stackRef}>
+      <div
+        {...restProps}
+        {...rootProps}
+        aria-labelledby={label ? labelId : rest["aria-labelledby"]}
+        data-animate={animate}
+        className={cn(
+          "ambx-control ambx-travel",
+          `ambx-travel-${orientation}`,
+          sized.className,
+          className
+        )}
+        style={{ ...rootProps.style, ...sized.style, ...restStyle }}
+      >
+        <ControlStateProvider value={state}>
+          <Frames parts={parts} />
+        </ControlStateProvider>
+      </div>
+      {label ? (
+        <span id={labelId} className="ambx-label">
+          {label}
+        </span>
+      ) : null}
+    </div>
+  );
+}

package/src/core/context.tsx

@@ -0,0 +1,46 @@
+import { createContext, useContext } from "react";
+import type { ControlState } from "./types";
+import type { BankOption } from "./useBank";
+
+const ControlStateContext = createContext<ControlState | null>(null);
+
+export const ControlStateProvider = ControlStateContext.Provider;
+
+/** Read the enclosing control's state from inside a part.
+ *
+ *  This is the third outlet of the state channel, and the one to reach for
+ *  last: the custom properties on the control root are canonical, and a
+ *  part that can be styled from CSS should be. Use this when a part needs
+ *  the value as a JS number — a readout, a tick ring that has to emit N
+ *  children, an SVG whose path data depends on the value. */
+export function useControlState(): ControlState {
+  const state = useContext(ControlStateContext);
+  if (!state) {
+    throw new Error(
+      "useControlState() must be called from inside a control's parts. " +
+        "Pass the component through `parts` on AmbientRotary, AmbientTravel, " +
+        "AmbientPress, AmbientLatch or AmbientBank."
+    );
+  }
+  return state;
+}
+
+/** A bank key carries more than a number: its legend, its accessible name
+ *  and its own lamp colour all belong to the option, not to the state. So a
+ *  key's parts get this alongside `useControlState()`. */
+export type BankKeyState = { option: BankOption; on: boolean; index: number };
+
+const BankKeyContext = createContext<BankKeyState | null>(null);
+
+export const BankKeyProvider = BankKeyContext.Provider;
+
+export function useBankKey(): BankKeyState {
+  const key = useContext(BankKeyContext);
+  if (!key) {
+    throw new Error(
+      "useBankKey() must be called from inside a bank key's parts. Pass the " +
+        "component through `keyParts` on AmbientBank."
+    );
+  }
+  return key;
+}

package/src/core/controllable.ts

@@ -0,0 +1,33 @@
+import { useCallback, useRef, useState } from "react";
+
+/** One controlled/uncontrolled convention for every control.
+ *
+ *  Pass `value` to drive it from outside; pass `defaultValue` (or neither)
+ *  to let the control hold its own. `onChange` fires either way, so a
+ *  caller can read an uncontrolled control without taking it over.
+ *
+ *  Before v3 this was inconsistent: AmbientSwitch and AmbientSelect took a
+ *  default, while knob, slider and fader were controlled-only and would
+ *  sit frozen if you forgot `onChange`. */
+export function useControllableValue<T>(
+  controlled: T | undefined,
+  defaultValue: T,
+  onChange?: (next: T) => void
+): [T, (next: T) => void] {
+  const isControlled = controlled !== undefined;
+  const [internal, setInternal] = useState<T>(defaultValue);
+
+  /* The setter is called from pointer handlers that run many times per
+     drag, so it must not change identity between renders. */
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const controlledRef = useRef(isControlled);
+  controlledRef.current = isControlled;
+
+  const set = useCallback((next: T) => {
+    if (!controlledRef.current) setInternal(next);
+    onChangeRef.current?.(next);
+  }, []);
+
+  return [isControlled ? (controlled as T) : internal, set];
+}

package/src/core/dev.ts

@@ -0,0 +1,15 @@
+declare const process: { env: Record<string, string | undefined> };
+
+/** True outside a production build.
+ *
+ *  Written as a bare `process.env.NODE_ENV` comparison so bundlers replace
+ *  it textually and drop the guarded code from production output, and
+ *  wrapped in try/catch so an unbundled ESM consumer — a CDN import with no
+ *  `process` shim — gets `false` rather than a ReferenceError. */
+export const isDev: boolean = (() => {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+})();

package/src/core/frames.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useRef } from "react";
+import type { RefObject } from "react";
+import { isDev } from "./dev";
+import { FRAME_ORDER } from "./types";
+import type { ControlParts } from "./types";
+
+/** Render the frames a control has parts for, in paint order.
+ *
+ *  Frames are markers by default (`display: contents` in styles.css) and
+ *  become boxes only where the control has a size of its own — a rotary's
+ *  rotating face, a travel thumb. That distinction is not cosmetic: a
+ *  button takes its width from `min-width` plus its cap's legend, so an
+ *  absolutely-positioned actuator would collapse it to nothing. */
+export function Frames({ parts }: { parts?: ControlParts | undefined }) {
+  if (!parts) return null;
+  return (
+    <>
+      {FRAME_ORDER.map((name) =>
+        parts[name] == null ? null : (
+          <div key={name} data-frame={name} className={`ambx-frame ambx-frame-${name}`}>
+            {parts[name]}
+          </div>
+        )
+      )}
+    </>
+  );
+}
+
+const FOCUSABLE =
+  "a[href], button, input, select, textarea, [tabindex], [contenteditable=true]," +
+  "[role=button], [role=checkbox], [role=radio], [role=slider], [role=switch], [role=link]";
+
+/** Development-only enforcement of the rule that parts are presentational.
+ *
+ *  The control root owns `role`, `aria-value*`, `tabIndex` and the keyboard
+ *  handler. A part that smuggles in its own focusable element gives the
+ *  control two tab stops and, usually, a second conflicting role.
+ *
+ *  Scoped to inside `[data-frame]` subtrees rather than to the whole root,
+ *  because a bank's key IS a `<button>` that the mechanism renders and the
+ *  frames sit inside it. Querying from the root would flag every preset we
+ *  ship. */
+export function useDevPartCheck(ref: RefObject<HTMLElement | null>, control: string): void {
+  const warned = useRef(false);
+  /* Mount only, and at most once. A part set is fixed by the code that wrote
+     it, so re-querying on every render would buy nothing and cost a DOM walk
+     on every frame of a drag. */
+  useEffect(() => {
+    if (!isDev || warned.current) return;
+    const root = ref.current;
+    if (!root) return;
+    const offenders = root.querySelectorAll(`[data-frame] :is(${FOCUSABLE})`);
+    if (offenders.length === 0) return;
+    warned.current = true;
+    const tags = Array.from(offenders, (node) => `<${node.tagName.toLowerCase()}>`).join(", ");
+    console.warn(
+      `[@ambientcss/components] ${control}: a part contains a focusable element ` +
+        `(${tags}). Parts are presentational — the control root already owns the ` +
+        `role, the tab stop and the keyboard handler, so this creates a second ` +
+        `tab stop and usually a conflicting role.`
+    );
+  }, [ref, control]);
+}

package/src/core/kit.tsx

@@ -0,0 +1,107 @@
+import { createContext, useContext } from "react";
+import type { PropsWithChildren } from "react";
+import { isDev } from "./dev";
+import type { ControlParts } from "./types";
+import type { RotaryInput, RotaryTravel } from "./useRotary";
+import type { ControlAnimate } from "./types";
+
+/** The five control families a kit can dress. */
+export type ControlFamily = "rotary" | "travel" | "press" | "latch" | "bank";
+
+/** What a preset hands its kit: the look options the caller asked for.
+ *
+ *  Deliberately loose. Look props are *kit vocabulary* — `knurling` and
+ *  `markers` are words the grounded kit made up — so a kit reads the keys it
+ *  understands and ignores the rest, exactly as a stylesheet that never
+ *  implemented a class simply does not react to it. See `looks` below for
+ *  how that stays honest rather than silent. */
+export type KitLook = Record<string, unknown>;
+
+/** A dressed control: what goes in the frames, and what the root wears.
+ *
+ *  The class comes from the kit rather than the preset because it is part of
+ *  the look — `.amb-knob` carries the grounded knob's own token table, and a
+ *  kit that replaces the parts has no use for it. */
+export type KitDress = {
+  parts: ControlParts;
+  className?: string | undefined;
+};
+
+/** Presentation defaults a visual identity may legitimately set.
+ *
+ *  Narrow on purpose: a kit says how its controls should *feel* to turn, not
+ *  what they are worth. Anything touching value, range or handlers stays with
+ *  the caller. */
+export type KitDefaults = {
+  rotary?: { travel?: RotaryTravel; input?: RotaryInput; animate?: ControlAnimate } | undefined;
+  travel?: { animate?: ControlAnimate } | undefined;
+  latch?: { animate?: ControlAnimate } | undefined;
+};
+
+export type ControlKit = {
+  name: string;
+  rotary?: ((look: KitLook) => KitDress) | undefined;
+  travel?: ((look: KitLook) => KitDress) | undefined;
+  press?: ((look: KitLook) => KitDress) | undefined;
+  latch?: ((look: KitLook) => KitDress) | undefined;
+  bank?: ((look: KitLook) => KitDress) | undefined;
+  defaults?: KitDefaults | undefined;
+  /** Look keys each family honours. Used only to warn in development when a
+   *  caller passes a prop the active kit is going to drop on the floor —
+   *  the one real cost of letting look props pass through untyped. */
+  looks?: Partial<Record<ControlFamily, readonly string[]>> | undefined;
+};
+
+const KitContext = createContext<ControlKit | null>(null);
+
+/** Dress every control below this point in `kit`.
+ *
+ *  A kit is a plain object, so shipping one is shipping a module: no
+ *  registry, no lifecycle, nothing to initialise. A kit that leaves a family
+ *  undefined falls through to the default, which is what a real third-party
+ *  kit will do for most of them. */
+export function AmbientKitProvider({ kit, children }: PropsWithChildren<{ kit: ControlKit }>) {
+  return <KitContext.Provider value={kit}>{children}</KitContext.Provider>;
+}
+
+export function useKit(): ControlKit | null {
+  return useContext(KitContext);
+}
+
+const warned = new Set<string>();
+
+/** Resolve a family's dressing: the active kit if it dresses this family,
+ *  otherwise the fallback the preset was built around. */
+export function useDress<F extends ControlFamily>(
+  family: F,
+  look: KitLook,
+  fallback: (look: KitLook) => KitDress
+): { dress: KitDress; defaults: F extends keyof KitDefaults ? KitDefaults[F] : undefined } {
+  const kit = useKit();
+  const dressed = kit?.[family];
+
+  if (isDev && kit && dressed) {
+    const honoured = kit.looks?.[family];
+    if (honoured) {
+      for (const key of Object.keys(look)) {
+        if (look[key] === undefined || honoured.includes(key)) continue;
+        const id = `${kit.name}:${family}:${key}`;
+        if (warned.has(id)) continue;
+        warned.add(id);
+        console.warn(
+          `[@ambientcss/components] the "${kit.name}" kit's ${family} does not use ` +
+            `\`${key}\` — it is a look prop from another kit's vocabulary, so it will ` +
+            `have no effect here.`
+        );
+      }
+    }
+  }
+
+  return {
+    dress: (dressed ?? fallback)(look),
+    /* Defaults come from the kit that actually dressed the control: a kit
+       that falls through to grounded for a family has no say in how that
+       family behaves either. */
+    defaults: (dressed ? kit?.defaults?.[family as keyof KitDefaults] : undefined) as never
+  };
+}

package/src/core/material.ts

@@ -0,0 +1,27 @@
+/** The grounded surface finishes from @ambientcss/css.
+ *
+ *  Lives on parts and presets, never on a mechanism: which element a
+ *  material belongs on is a fact about a particular control's construction,
+ *  and a mechanism cannot know that once the parts are yours.
+ *
+ *  `brushed`, `brushed-round` and `blasted` are micro-relief materials: they
+ *  paint their grain into BOTH of the host's pseudo-elements, so a part that
+ *  already spends one of its own has to give them an inner layer rather than
+ *  wear them directly. `ButtonCap` is the only part in this package that does.
+ *
+ *  `brushed-round` is the same aluminium as `brushed` with the grain spun
+ *  round the element's centre, so it belongs on round faces — a knob cap, a
+ *  round button — where the centre it turns about is a real feature. */
+export type AmbientMaterial =
+  | "matte"
+  | "shiny"
+  | "glass"
+  | "brushed"
+  | "brushed-round"
+  | "blasted";
+
+/** Whether a finish carries micro-relief, and therefore needs both
+ *  pseudo-elements of whatever it is put on. */
+export function isRelief(material: AmbientMaterial | undefined): boolean {
+  return material === "brushed" || material === "brushed-round" || material === "blasted";
+}

package/src/core/numeric.ts

@@ -0,0 +1,88 @@
+/* Value maths shared by every control.
+
+   These four functions were previously inlined — identically — in
+   AmbientKnob, AmbientSlider and AmbientFader. The keyboard handler below
+   was copied three times with the same `pageStep = step * 10`, the same
+   Home/End edges and the same snap-then-clamp order. */
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, value));
+}
+
+/** Quantise to the step grid, anchored at `min` rather than at zero so a
+ *  range like 10..100 step 25 rests on 10/35/60/85 instead of 25/50/75. */
+export function snap(value: number, min: number, step: number): number {
+  if (!(step > 0)) return value;
+  return min + Math.round((value - min) / step) * step;
+}
+
+/** Value to its 0-1 position in the range. */
+export function normalise(value: number, min: number, max: number): number {
+  return (value - min) / (max - min || 1);
+}
+
+/** A 0-1 position back to a value. */
+export function denormalise(t: number, min: number, max: number): number {
+  return min + t * (max - min);
+}
+
+/** Snap and clamp in the order every control needs: quantise first, then
+ *  hold the result inside the range, so a step that does not divide the
+ *  range still cannot push the value past `max`. */
+export function commit(value: number, min: number, max: number, step: number): number {
+  return clamp(snap(value, min, max === min ? 1 : step), min, max);
+}
+
+export type ValueKeysOptions = {
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  disabled?: boolean;
+  /** Swap the direction of the arrow keys along the control's own axis. */
+  invert?: boolean;
+  onChange: (next: number) => void;
+};
+
+/** The Arrow/Page/Home/End contract, in one place.
+ *
+ *  Both arrow axes act on every control: a knob has no "left", and a
+ *  horizontal slider has no "up", but a keyboard user should not have to
+ *  know which. Page steps are ten of `step`, the figure all three
+ *  components already used. */
+export function valueKeyHandler(options: ValueKeysOptions) {
+  return (event: { key: string; preventDefault(): void }): boolean => {
+    const { value, min, max, step, invert, onChange, disabled } = options;
+    if (disabled) return false;
+    const dir = invert ? -1 : 1;
+    const set = (next: number) => {
+      event.preventDefault();
+      onChange(commit(next, min, max, step));
+    };
+
+    switch (event.key) {
+      case "ArrowUp":
+      case "ArrowRight":
+        set(value + step * dir);
+        return true;
+      case "ArrowDown":
+      case "ArrowLeft":
+        set(value - step * dir);
+        return true;
+      case "PageUp":
+        set(value + step * 10 * dir);
+        return true;
+      case "PageDown":
+        set(value - step * 10 * dir);
+        return true;
+      case "Home":
+        set(min);
+        return true;
+      case "End":
+        set(max);
+        return true;
+      default:
+        return false;
+    }
+  };
+}

package/src/core/types.ts

@@ -0,0 +1,116 @@
+import type { CSSProperties, ReactNode } from "react";
+
+/** The four frames every control renders, in paint order.
+ *
+ *  - `panel`    static, behind the control, allowed to overflow its box
+ *  - `base`     static, the control's own footprint
+ *  - `actuator` the moving part: the frame the control transforms
+ *  - `fixture`  static, above the actuator
+ *
+ *  A part dropped into a frame is ordinary markup. The control moves the
+ *  frame; the part only has to look like something. */
+export type ControlParts = {
+  panel?: ReactNode | undefined;
+  base?: ReactNode | undefined;
+  actuator?: ReactNode | undefined;
+  fixture?: ReactNode | undefined;
+};
+
+export type FrameName = keyof ControlParts;
+
+export const FRAME_ORDER: FrameName[] = ["panel", "base", "actuator", "fixture"];
+
+/** `"sm" | "md" | "lg"` picks a size from the family's table; any other
+ *  string is used as a CSS length for `--ambx-size`. */
+export type ControlSize = "sm" | "md" | "lg" | (string & {});
+
+/** How the actuator moves to a new position.
+ *
+ *  - `follow` 1:1 with the pointer, no transition — right while dragging
+ *  - `ease`   transitions, right for keyboard and click-to-set
+ *  - `snap`   instant, for a detented control that should read as clicking
+ *
+ *  The default is contextual: follow while `data-dragging` is on the root,
+ *  ease otherwise. That needs no JS — see `.ambx-control` in styles.css. */
+export type ControlAnimate = "auto" | "follow" | "ease" | "snap";
+
+/** What a part can read, via `useControlState()`. The same values are on
+ *  the control root as custom properties, which are canonical; this is a
+ *  typed view of them for parts that genuinely need JS. */
+export type ControlState = {
+  /** The raw value. Booleans arrive as 0/1, selections as the index. */
+  value: number;
+  min: number;
+  max: number;
+  /** Normalised position, 0-1. */
+  percent: number;
+  /** Degrees clockwise from 12 o'clock. 0 for non-rotary controls. */
+  angle: number;
+  /** Sweep origin and extent in degrees. 0 for non-rotary controls. */
+  travelStart: number;
+  travelSweep: number;
+  /** Rest positions along the travel; 0 means continuous. */
+  detents: number;
+  dragging: boolean;
+  disabled: boolean;
+  atMin: boolean;
+  atMax: boolean;
+};
+
+export const IDLE_STATE: ControlState = {
+  value: 0,
+  min: 0,
+  max: 1,
+  percent: 0,
+  angle: 0,
+  travelStart: 0,
+  travelSweep: 0,
+  detents: 0,
+  dragging: false,
+  disabled: false,
+  atMin: true,
+  atMax: false
+};
+
+/** The state channel, written onto the control root.
+ *
+ *  Every property is declared here even when a family does not use it,
+ *  because these inherit: a control nested inside another control's frame
+ *  would otherwise read its ancestor's angle. `.ambx-control` carries the
+ *  neutral defaults and this overrides them per instance. */
+export function stateStyle(state: ControlState): CSSProperties {
+  return {
+    "--ambx-value": state.value,
+    "--ambx-percent": state.percent,
+    "--ambx-angle": `${state.angle}deg`,
+    "--ambx-travel-start": `${state.travelStart}deg`,
+    "--ambx-travel-sweep": `${state.travelSweep}deg`,
+    "--ambx-detents": state.detents
+  } as CSSProperties;
+}
+
+/** The discrete half of the state channel: conditions a part can style
+ *  against but cannot detect for itself. */
+export function stateData(state: ControlState): Record<string, string | undefined> {
+  return {
+    "data-dragging": state.dragging ? "" : undefined,
+    "data-disabled": state.disabled ? "" : undefined,
+    "data-at-min": state.atMin ? "" : undefined,
+    "data-at-max": state.atMax ? "" : undefined
+  };
+}
+
+/** Resolve `size` into the class suffix and/or the `--ambx-size` override.
+ *  A named size picks the family's table; a length goes straight through,
+ *  which is what lets a part scale off one property instead of matching a
+ *  class it cannot know about. */
+export function sizeProps(
+  family: string,
+  size: ControlSize | undefined
+): { className?: string; style?: CSSProperties } {
+  if (size === undefined) return {};
+  if (size === "sm" || size === "md" || size === "lg") {
+    return { className: `ambx-${family}-${size}` };
+  }
+  return { style: { "--ambx-size": size } as CSSProperties };
+}