@dowel-ui/react 0.5.0 → 0.8.0

package/src/components/scrubber/scrubber.tsx

@@ -0,0 +1,348 @@
+"use client";
+
+// Ported from SmoothUI Scrubber (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import { Direction } from "radix-ui";
+import {
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type KeyboardEvent,
+  type PointerEvent,
+  type ReactNode,
+} from "react";
+
+import { focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/*
+ * A design-tool number field: a labelled bar you drag across to scrub a value,
+ * with the number at the end. The bar is a `role="slider"` — arrows, Shift +
+ * arrows and Page Up/Down for big steps, Home/End — and typing an exact value
+ * is one key away: Enter (or a double-click) swaps the number for a text field;
+ * Enter or leaving the field commits, Escape cancels, and focus comes back to
+ * the slider.
+ *
+ * The source animated the capsule thumb with a `motion` spring. It carries no
+ * gesture velocity, so here it is a CSS transition on data attributes, and the
+ * global reduced-motion rule stops it.
+ */
+
+const scrubberVariants = cva("relative w-full select-none", {
+  variants: {
+    size: {
+      sm: "h-7 text-xs",
+      md: "h-9 text-[0.8125rem]",
+      lg: "h-11 text-sm",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export interface ScrubberProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "defaultValue" | "onChange" | "children">,
+    VariantProps<typeof scrubberVariants> {
+  /** Visible label at the start of the bar. It also names the slider. */
+  label?: ReactNode;
+  value?: number;
+  defaultValue?: number;
+  /** Called on every change: while dragging, per key press, and on a typed entry. */
+  onValueChange?: (value: number) => void;
+  /** Called when an interaction ends: pointer released, key press or typed entry. */
+  onValueCommit?: (value: number) => void;
+  min?: number;
+  max?: number;
+  step?: number;
+  /** Steps moved by Shift + arrow and Page Up / Page Down. */
+  largeStep?: number;
+  /** Decimal places shown. Defaults to the precision of `step`. */
+  decimals?: number;
+  /** Number of evenly spaced tick marks; 0 hides them. */
+  ticks?: number;
+  /** Formats the displayed value and `aria-valuetext`. Defaults to `decimals` places. */
+  formatValue?: (value: number) => string;
+  /** Allow typing an exact value (Enter or double-click). */
+  editable?: boolean;
+  disabled?: boolean;
+  /** Submits the value with a form under this name. */
+  name?: string;
+}
+
+const clamp = (value: number, lo: number, hi: number) => Math.min(Math.max(value, lo), hi);
+
+function precisionOf(step: number): number {
+  const text = String(step);
+  const exponent = /e-(\d+)$/.exec(text);
+  if (exponent) return Number(exponent[1]);
+  return text.split(".")[1]?.length ?? 0;
+}
+
+/** A drag-to-scrub numeric control with keyboard stepping and typed entry. */
+export function Scrubber({
+  className,
+  size,
+  label = "Value",
+  value: valueProp,
+  defaultValue,
+  onValueChange,
+  onValueCommit,
+  min = 0,
+  max = 1,
+  step = 0.01,
+  largeStep = 10,
+  decimals: decimalsProp,
+  ticks = 9,
+  formatValue,
+  editable = true,
+  disabled = false,
+  name,
+  dir: dirProp,
+  "aria-label": ariaLabel,
+  "aria-labelledby": ariaLabelledBy,
+  "aria-describedby": ariaDescribedBy,
+  "aria-valuetext": ariaValueText,
+  ...props
+}: ScrubberProps) {
+  const dir = Direction.useDirection(dirProp as "ltr" | "rtl" | undefined);
+  const decimals = decimalsProp ?? precisionOf(step);
+  const snap = (raw: number) =>
+    Number(clamp(Math.round((raw - min) / step) * step + min, min, max).toFixed(10));
+
+  const [uncontrolled, setUncontrolled] = useState(() => snap(defaultValue ?? min));
+  const controlled = valueProp !== undefined;
+  const value = controlled ? valueProp : uncontrolled;
+  const [dragging, setDragging] = useState(false);
+  const [draft, setDraft] = useState<string | null>(null);
+  const editing = draft !== null;
+
+  const trackRef = useRef<HTMLDivElement>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
+  // The value an in-progress drag last produced, reported on release.
+  const latest = useRef(value);
+  // Whether a typed entry is open. A ref, because refocusing the slider blurs
+  // the field before React has re-rendered, and that blur must not commit an
+  // entry Escape has just cancelled.
+  const open = useRef(false);
+
+  // Typed entry replaces the number the user just asked to edit.
+  useEffect(() => {
+    if (!editing) return;
+    inputRef.current?.focus();
+    inputRef.current?.select();
+  }, [editing]);
+  const labelId = useId();
+  const range = max - min;
+  const percent = range > 0 ? ((clamp(value, min, max) - min) / range) * 100 : 0;
+  const text = formatValue ? formatValue(value) : value.toFixed(decimals);
+
+  function setValue(raw: number) {
+    const next = snap(raw);
+    latest.current = next;
+    if (next === value) return next;
+    if (!controlled) setUncontrolled(next);
+    onValueChange?.(next);
+    return next;
+  }
+
+  function fromPointer(clientX: number) {
+    const rect = trackRef.current?.getBoundingClientRect();
+    if (!rect || rect.width === 0) return value;
+    const ratio = clamp((clientX - rect.left) / rect.width, 0, 1);
+    return min + (dir === "rtl" ? 1 - ratio : ratio) * range;
+  }
+
+  function handlePointerDown(event: PointerEvent<HTMLDivElement>) {
+    if (disabled || editing || event.button !== 0) return;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    setDragging(true);
+    latest.current = value;
+    setValue(fromPointer(event.clientX));
+  }
+
+  function handlePointerMove(event: PointerEvent<HTMLDivElement>) {
+    if (!dragging) return;
+    setValue(fromPointer(event.clientX));
+  }
+
+  function handlePointerEnd() {
+    if (!dragging) return;
+    setDragging(false);
+    onValueCommit?.(latest.current);
+  }
+
+  function startEditing() {
+    if (disabled || !editable) return;
+    open.current = true;
+    setDraft(value.toFixed(decimals));
+  }
+
+  function handleKeyDown(event: KeyboardEvent<HTMLDivElement>) {
+    if (disabled) return;
+    if (event.key === "Enter" && editable) {
+      event.preventDefault();
+      startEditing();
+      return;
+    }
+    const forward = dir === "rtl" ? -1 : 1;
+    const big = event.shiftKey ? largeStep : 1;
+    const moves: Record<string, number> = {
+      ArrowRight: forward * big,
+      ArrowLeft: -forward * big,
+      ArrowUp: big,
+      ArrowDown: -big,
+      PageUp: largeStep,
+      PageDown: -largeStep,
+    };
+    let next: number;
+    if (event.key === "Home") next = min;
+    else if (event.key === "End") next = max;
+    else if (event.key in moves) next = value + (moves[event.key] ?? 0) * step;
+    else return;
+    event.preventDefault();
+    // Not inlined into the optional call: `f?.(x)` skips evaluating x when f is absent.
+    const committed = setValue(next);
+    onValueCommit?.(committed);
+  }
+
+  function finishEditing(commit: boolean, refocus: boolean) {
+    if (!open.current || draft === null) return;
+    open.current = false;
+    const parsed = Number.parseFloat(draft.replace(",", "."));
+    setDraft(null);
+    if (commit && Number.isFinite(parsed)) {
+      const committed = setValue(parsed);
+      onValueCommit?.(committed);
+    }
+    if (refocus) trackRef.current?.focus();
+  }
+
+  const active = "group-hover/scrubber:opacity-80 group-hover/scrubber:scale-100";
+
+  return (
+    <div
+      data-slot="scrubber"
+      data-disabled={disabled ? "" : undefined}
+      dir={dirProp}
+      className={cn(scrubberVariants({ size }), disabled && "opacity-55", className)}
+      {...props}
+    >
+      <div
+        ref={trackRef}
+        role="slider"
+        tabIndex={disabled ? -1 : 0}
+        data-slot="scrubber-track"
+        data-dragging={dragging ? "" : undefined}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabel ? undefined : (ariaLabelledBy ?? labelId)}
+        aria-describedby={ariaDescribedBy}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={Number(value.toFixed(decimals))}
+        aria-valuetext={ariaValueText ?? text}
+        aria-orientation="horizontal"
+        aria-disabled={disabled || undefined}
+        aria-keyshortcuts={editable && !disabled ? "Enter" : undefined}
+        className={cn(
+          "group/scrubber relative size-full touch-none overflow-hidden rounded-lg bg-muted",
+          disabled ? "cursor-not-allowed" : "cursor-ew-resize",
+          focusRing,
+        )}
+        onKeyDown={handleKeyDown}
+        onPointerDown={handlePointerDown}
+        onPointerMove={handlePointerMove}
+        onPointerUp={handlePointerEnd}
+        onPointerCancel={handlePointerEnd}
+        onDoubleClick={startEditing}
+      >
+        <span
+          data-slot="scrubber-fill"
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute inset-y-0 start-0 rounded-lg bg-foreground/14",
+            !dragging &&
+              "transition-[width] duration-[var(--duration-fast)] ease-[var(--ease-out-quint)]",
+          )}
+          style={{ width: `${String(percent)}%` }}
+        />
+        {Array.from({ length: Math.max(0, ticks) }, (_, index) => (
+          <span
+            key={index}
+            data-slot="scrubber-tick"
+            aria-hidden="true"
+            className="pointer-events-none absolute top-1/2 h-1.5 w-px -translate-y-1/2 rounded-full bg-foreground/25"
+            style={{ insetInlineStart: `${String(((index + 1) / (ticks + 1)) * 100)}%` }}
+          />
+        ))}
+        <span
+          data-slot="scrubber-thumb"
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute top-1/2 z-[1] h-3/5 w-1 -translate-y-1/2 rounded-full bg-foreground/90",
+            "scale-70 opacity-15 duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]",
+            dragging
+              ? "transition-[opacity,scale]"
+              : "transition-[opacity,scale,inset-inline-start]",
+            "group-focus-visible/scrubber:scale-100 group-focus-visible/scrubber:opacity-80",
+            "group-data-[dragging]/scrubber:scale-100 group-data-[dragging]/scrubber:opacity-80",
+            !disabled && active,
+          )}
+          style={{
+            insetInlineStart: `clamp(0.25rem, calc(${String(percent)}% - 0.5rem), calc(100% - 0.5rem))`,
+          }}
+        />
+        <span
+          id={labelId}
+          data-slot="scrubber-label"
+          className="pointer-events-none absolute start-3 top-1/2 z-[2] -translate-y-1/2 font-medium whitespace-nowrap text-foreground"
+        >
+          {label}
+        </span>
+        <span
+          data-slot="scrubber-value"
+          aria-hidden="true"
+          className={cn(
+            "pointer-events-none absolute end-2.5 top-1/2 z-[2] -translate-y-1/2 font-mono font-medium text-foreground tabular-nums",
+            editing && "invisible",
+          )}
+        >
+          {text}
+        </span>
+      </div>
+      {editing ? (
+        <input
+          type="text"
+          inputMode="decimal"
+          data-slot="scrubber-input"
+          aria-labelledby={ariaLabel ? undefined : (ariaLabelledBy ?? labelId)}
+          aria-label={ariaLabel}
+          ref={inputRef}
+          value={draft}
+          onChange={(event) => setDraft(event.target.value)}
+          onKeyDown={(event) => {
+            if (event.key === "Enter") {
+              event.preventDefault();
+              finishEditing(true, true);
+            } else if (event.key === "Escape") {
+              event.preventDefault();
+              finishEditing(false, true);
+            }
+          }}
+          onBlur={() => finishEditing(true, false)}
+          className={cn(
+            "absolute inset-y-1 end-1 z-[3] w-20 rounded-md border border-input bg-background px-1.5",
+            "text-end font-mono font-medium text-foreground tabular-nums",
+            focusRing,
+          )}
+        />
+      ) : null}
+      {name ? <input type="hidden" name={name} value={value} disabled={disabled} /> : null}
+    </div>
+  );
+}
+
+export { scrubberVariants };

package/src/components/select/meta.ts

@@ -12,5 +12,6 @@ export const meta = defineMeta({
   a11y:
     "Full listbox keyboard model: arrows move, typeahead jumps, Enter selects, Escape closes and " +
     "restores focus. Give the trigger a name with aria-labelledby or a Label. Past about a dozen " +
-    "options prefer Combobox — scrolling a long listbox by keyboard is slow.",
+    "options prefer Combobox — scrolling a long listbox by keyboard is slow. The opening pop, " +
+    "option stagger and tick pop are decoration and stop under reduced motion.",
 });

package/src/components/select/select.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+// Motion from SmoothUI Select (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
 import { cva, type VariantProps } from "class-variance-authority";
 import { Select as SelectPrimitive } from "radix-ui";
 import type { ComponentPropsWithRef, ReactNode } from "react";
@@ -13,6 +14,11 @@ import { cn } from "@/lib/utils";
  * For a short, known list. Past roughly a dozen options people want to type
  * rather than scroll — reach for Combobox there. Unlike a native `<select>`,
  * the options are real elements, so they can carry icons and descriptions.
+ *
+ * The list opens with the same motion as DropdownMenu and ContextMenu — a pop
+ * from the trigger with a slight overshoot, options dropping in 20ms apart —
+ * and the selected option's tick pops in. All of it is decoration and stops
+ * under reduced motion.
  */
 export const Select = SelectPrimitive.Root;
 export const SelectGroup = SelectPrimitive.Group;
@@ -108,6 +114,31 @@ function ScrollButton({
   );
 }
 
+const PREFIX = "dowel-select";
+
+/** Stagger delays for the first dozen entries; later ones arrive with the twelfth. */
+const STAGGER = Array.from(
+  { length: 11 },
+  (_, i) =>
+    `[data-slot=select-viewport]>:nth-child(${String(i + 2)}){animation-delay:calc(${String((i + 1) * 20)}ms * var(--motion-scale))}`,
+).join("\n");
+
+const STYLES = `
+@keyframes ${PREFIX}-in{from{opacity:0;transform:translateY(-4px) scale(.95)}}
+@keyframes ${PREFIX}-item-in{from{opacity:0;transform:translateY(-4px)}}
+@keyframes ${PREFIX}-check-in{from{opacity:0;transform:scale(0)}}
+${STAGGER}
+[data-slot=select-viewport]>:nth-child(n+13){animation-delay:calc(240ms * var(--motion-scale))}
+`;
+
+function Styles() {
+  return (
+    <style href={PREFIX} precedence="dowel">
+      {STYLES}
+    </style>
+  );
+}
+
 export type SelectContentProps = ComponentPropsWithRef<typeof SelectPrimitive.Content>;
 
 export function SelectContent({
@@ -118,27 +149,37 @@ export function SelectContent({
   ...props
 }: SelectContentProps) {
   return (
-    <SelectPrimitive.Portal>
-      <SelectPrimitive.Content
-        data-slot="select-content"
-        position={position}
-        sideOffset={position === "popper" ? sideOffset : undefined}
-        className={cn(
-          "relative z-[var(--z-popover)] max-h-[var(--radix-select-content-available-height)]",
-          "min-w-32 overflow-x-hidden overflow-y-auto rounded-lg border border-border bg-popover",
-          "p-1 text-popover-foreground shadow-lg",
-          "origin-[var(--radix-select-content-transform-origin)]",
-          "data-[state=closed]:animate-float-out data-[state=open]:animate-float-in",
-          position === "popper" && "w-full min-w-[var(--radix-select-trigger-width)]",
-          className,
-        )}
-        {...props}
-      >
-        <ScrollButton direction="up" />
-        <SelectPrimitive.Viewport className="p-0">{children}</SelectPrimitive.Viewport>
-        <ScrollButton direction="down" />
-      </SelectPrimitive.Content>
-    </SelectPrimitive.Portal>
+    <>
+      <Styles />
+      <SelectPrimitive.Portal>
+        <SelectPrimitive.Content
+          data-slot="select-content"
+          position={position}
+          sideOffset={position === "popper" ? sideOffset : undefined}
+          className={cn(
+            "relative z-[var(--z-popover)] max-h-[var(--radix-select-content-available-height)]",
+            "min-w-32 overflow-x-hidden overflow-y-auto rounded-lg border border-border bg-popover",
+            "p-1 text-popover-foreground shadow-lg",
+            "origin-[var(--radix-select-content-transform-origin)]",
+            // Keyframe names spelled out because Tailwind reads class names from the source.
+            "data-[state=closed]:animate-float-out",
+            "data-[state=open]:animate-[dowel-select-in_calc(250ms*var(--motion-scale))_var(--ease-overshoot)]",
+            position === "popper" && "w-full min-w-[var(--radix-select-trigger-width)]",
+            className,
+          )}
+          {...props}
+        >
+          <ScrollButton direction="up" />
+          <SelectPrimitive.Viewport
+            data-slot="select-viewport"
+            className="p-0 [&>*]:animate-[dowel-select-item-in_calc(250ms*var(--motion-scale))_var(--ease-overshoot)_both]"
+          >
+            {children}
+          </SelectPrimitive.Viewport>
+          <ScrollButton direction="down" />
+        </SelectPrimitive.Content>
+      </SelectPrimitive.Portal>
+    </>
   );
 }
 
@@ -158,7 +199,7 @@ export function SelectItem({ className, label, children, ...props }: SelectItemP
     <SelectPrimitive.Item
       data-slot="select-item"
       className={cn(
-        "relative flex w-full cursor-default items-center gap-2 rounded-md py-1.5 pr-8 pl-2 text-sm outline-none select-none",
+        "relative flex w-full cursor-default items-center gap-2 rounded-md py-1.5 ps-2 pe-8 text-sm outline-none select-none",
         "transition-colors duration-[var(--duration-instant)]",
         "data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground",
         "data-[disabled]:pointer-events-none data-[disabled]:opacity-55",
@@ -176,9 +217,15 @@ export function SelectItem({ className, label, children, ...props }: SelectItemP
         </>
       )}
       {/* Decorative: selection is already announced through aria-selected. */}
-      <span className="absolute right-2 grid size-4 place-items-center">
+      <span className="absolute end-2 grid size-4 place-items-center">
         <SelectPrimitive.ItemIndicator>
-          <svg viewBox="0 0 24 24" fill="none" aria-hidden="true" className="size-3.5">
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            aria-hidden="true"
+            data-slot="select-item-check"
+            className="size-3.5 animate-[dowel-select-check-in_calc(200ms*var(--motion-scale))_var(--ease-overshoot)]"
+          >
             <path
               d="m5 13 4 4L19 7"
               stroke="currentColor"

package/src/components/selection-list/index.ts

@@ -0,0 +1,6 @@
+export {
+  SelectionList,
+  selectionListVariants,
+  type SelectionListItem,
+  type SelectionListProps,
+} from "./selection-list";

package/src/components/selection-list/meta.ts

@@ -0,0 +1,21 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "selection-list",
+  title: "Selection List",
+  description:
+    "A multi-select list of people with a liquid tick and an action that springs out from under it once someone is picked.",
+  category: "form",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["avatar", "button"],
+  files: ["selection-list.tsx", "selection-list-spring.ts"],
+  a11y:
+    'The list is a role="listbox" aria-multiselectable="true" with a single tab stop; name it with aria-label ' +
+    '(default "Select people") or aria-labelledby. Rows are role="option" with aria-selected. ArrowUp/ArrowDown ' +
+    "rove with wrap-around, Home/End jump, Space/Enter toggle and Ctrl/Cmd+A selects or clears everything. The " +
+    "hover highlight follows keyboard focus as well as the pointer. The action button is disabled, inert and " +
+    "aria-hidden while tucked away (nothing selected); a pending action shows aria-busy, and the done label is " +
+    "announced through a polite live region. When the action tucks away again focus returns to the list. The " +
+    "tick, avatars and highlight are aria-hidden; under reduced motion the goo fill becomes a plain fill.",
+});

package/src/components/selection-list/selection-list-spring.ts

@@ -0,0 +1,33 @@
+/*
+ * A damped spring expressed as a CSS `linear()` easing, so a state-driven
+ * spring (overshoot, settle) runs as a plain CSS transition: no animation
+ * library, and the global reduced-motion rule and --motion-scale still apply.
+ *
+ * `bounce` 0..1 (0 = critically damped, no overshoot; 1 = very lively).
+ * Returns the easing string. Pair it with a duration from the caller.
+ * Browsers without linear() drop the declaration, so set it through a CSS
+ * variable consumed inside `@supports (transition-timing-function: linear(0, 1))`
+ * in the hoisted stylesheet, with a cubic-bezier fallback in the class list.
+ */
+export function springEasing(bounce: number, samples = 48): string {
+  const b = Math.min(Math.max(bounce, 0), 1);
+  const zeta = 1 - b * 0.7; // damping ratio 1 → 0.3
+  // Choose ω so the envelope has decayed to ~0.1% at t = 1.
+  const omega = Math.log(1000) / zeta;
+  const points: string[] = [];
+  for (let i = 0; i <= samples; i += 1) {
+    const t = i / samples;
+    let x: number;
+    if (zeta >= 0.999) {
+      x = 1 - Math.exp(-omega * t) * (1 + omega * t);
+    } else {
+      const wd = omega * Math.sqrt(1 - zeta * zeta);
+      x =
+        1 -
+        Math.exp(-zeta * omega * t) *
+          (Math.cos(wd * t) + ((zeta * omega) / wd) * Math.sin(wd * t));
+    }
+    points.push(i === samples ? "1" : String(Math.round(x * 1000) / 1000));
+  }
+  return `linear(${points.join(", ")})`;
+}