@dowel-ui/react 0.7.0 → 0.8.0

package/src/components/scramble-text/index.ts

@@ -0,0 +1,8 @@
+export {
+  ScrambleText,
+  scrambleFrame,
+  scrambleTextVariants,
+  type ScrambleTextElement,
+  type ScrambleTextProps,
+  type ScrambleTextTrigger,
+} from "./scramble-text";

package/src/components/scramble-text/meta.ts

@@ -0,0 +1,17 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "scramble-text",
+  title: "Scramble Text",
+  description:
+    "Text whose characters churn through random glyphs and resolve from the inline start, on hover, focus, mount or view.",
+  category: "effects",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["scramble-text.tsx"],
+  a11y:
+    "The scrambling glyphs are aria-hidden; an sr-only copy of the real text is what assistive technology reads, " +
+    "so nothing is announced per frame. The server renders the real text. It is not itself interactive: hover and " +
+    "keyboard focus on the nearest link or button that wraps it trigger the effect. No scramble under reduced motion.",
+});

package/src/components/scramble-text/scramble-text.tsx

@@ -0,0 +1,250 @@
+"use client";
+
+// Ported from SmoothUI Scramble Hover (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type Ref,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/*
+ * Characters churn through random glyphs, then settle on the real text.
+ *
+ * - The server, and the first client render, always show the real text:
+ *   randomness only ever runs inside event handlers and effects, after
+ *   hydration, so the markup is stable.
+ * - The visible glyphs are aria-hidden and the real string sits beside them in
+ *   an sr-only copy that never changes, so a screen reader reads the text once
+ *   and nothing is announced per tick.
+ * - The source re-randomised every character on every tick and snapped to the
+ *   text at the end. Here characters resolve from the inline start as the
+ *   scramble runs, so the text is readable sooner and the end is not a jump.
+ * - Hover is the source's trigger. It also fires on keyboard focus of the
+ *   nearest interactive ancestor (a link or button wrapping the text), and not
+ *   on touch, where there is no hover to leave.
+ * - Under reduced motion there is no scramble at all.
+ */
+
+const CHARACTERS =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*()_+-=<>?";
+
+/** Elements text effects render as. They are all phrasing or heading content. */
+export type ScrambleTextElement =
+  "span" | "p" | "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+export type ScrambleTextTrigger = "hover" | "mount" | "in-view";
+
+const scrambleTextVariants = cva("", {
+  variants: {
+    /** `mono` holds every glyph to one width, so the line does not jitter while it churns. */
+    font: {
+      inherit: "",
+      mono: "font-mono",
+    },
+  },
+  defaultVariants: {
+    font: "inherit",
+  },
+});
+
+export interface ScrambleTextProps
+  extends
+    Omit<ComponentPropsWithRef<"span">, "ref" | "children">,
+    VariantProps<typeof scrambleTextVariants> {
+  ref?: Ref<HTMLElement>;
+  /** The real text. */
+  children: string;
+  /** The element to render. */
+  as?: ScrambleTextElement;
+  /** Total scramble time, in milliseconds. */
+  duration?: number;
+  /** Time between scramble frames, in milliseconds. */
+  speed?: number;
+  /** The glyphs to scramble through. */
+  characters?: string;
+  /**
+   * What starts the scramble. `hover` (default) runs on pointer hover and
+   * keyboard focus; `mount` and `in-view` also play once on their own, and
+   * hover replays it.
+   */
+  trigger?: ScrambleTextTrigger;
+}
+
+function reducedMotion(): boolean {
+  return (
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+/** A frame of the scramble: the first `settled` characters are real. */
+export function scrambleFrame(text: string, settled: number, characters = CHARACTERS): string {
+  let frame = "";
+  for (let index = 0; index < text.length; index++) {
+    const char = text.charAt(index);
+    frame +=
+      index < settled || /\s/.test(char)
+        ? char
+        : characters.charAt(Math.floor(Math.random() * characters.length));
+  }
+  return frame;
+}
+
+const INTERACTIVE = "a[href],button,summary,label,[tabindex]";
+
+/** Text that scrambles through random glyphs and resolves, on hover, focus, mount or view. */
+export function ScrambleText({
+  as: Component = "span",
+  children,
+  duration = 600,
+  speed = 30,
+  characters = CHARACTERS,
+  trigger = "hover",
+  font,
+  className,
+  ref,
+  ...props
+}: ScrambleTextProps) {
+  const [display, setDisplay] = useState(children);
+  const [running, setRunning] = useState(false);
+  const node = useRef<HTMLElement | null>(null);
+  const interval = useRef<ReturnType<typeof setInterval> | null>(null);
+  const timeout = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const clear = useCallback(() => {
+    if (interval.current) clearInterval(interval.current);
+    if (timeout.current) clearTimeout(timeout.current);
+    interval.current = null;
+    timeout.current = null;
+  }, []);
+
+  const settle = useCallback(() => {
+    clear();
+    setDisplay(children);
+    setRunning(false);
+  }, [children, clear]);
+
+  const play = useCallback(() => {
+    clear();
+    if (reducedMotion() || duration <= 0) {
+      setDisplay(children);
+      return;
+    }
+    const started = Date.now();
+    setRunning(true);
+    setDisplay(scrambleFrame(children, 0, characters));
+    interval.current = setInterval(
+      () => {
+        const progress = Math.min((Date.now() - started) / duration, 1);
+        setDisplay(scrambleFrame(children, Math.floor(progress * children.length), characters));
+      },
+      Math.max(speed, 1),
+    );
+    timeout.current = setTimeout(settle, duration);
+  }, [characters, children, clear, duration, settle, speed]);
+
+  // A new string replaces whatever frame was showing: stop during render, and
+  // clear the old string's timers when it goes (and on unmount).
+  const [scrambling, setScrambling] = useState(children);
+  if (scrambling !== children) {
+    setScrambling(children);
+    setRunning(false);
+  }
+  useEffect(() => clear, [children, clear]);
+
+  // Hover and keyboard focus, on the text or on the control that wraps it.
+  useEffect(() => {
+    const element = node.current;
+    if (!element) return;
+    const target = element.closest<HTMLElement>(INTERACTIVE) ?? element;
+    const hoverCapable =
+      typeof window.matchMedia !== "function" ||
+      window.matchMedia("(hover: hover) and (pointer: fine)").matches;
+
+    const onEnter = (event: PointerEvent) => {
+      if (event.pointerType !== "touch" && hoverCapable) play();
+    };
+    // Keyboard focus only: a tap or click focuses too, and a scramble on tap is
+    // a glitch. Focus that follows a press came from the pointer.
+    let pressed = false;
+    const onPress = () => {
+      pressed = true;
+    };
+    const onFocus = () => {
+      if (!pressed) play();
+      pressed = false;
+    };
+
+    target.addEventListener("pointerdown", onPress);
+    target.addEventListener("pointerenter", onEnter);
+    target.addEventListener("pointerleave", settle);
+    target.addEventListener("focusin", onFocus);
+    target.addEventListener("focusout", settle);
+    return () => {
+      target.removeEventListener("pointerdown", onPress);
+      target.removeEventListener("pointerenter", onEnter);
+      target.removeEventListener("pointerleave", settle);
+      target.removeEventListener("focusin", onFocus);
+      target.removeEventListener("focusout", settle);
+    };
+  }, [play, settle]);
+
+  // The latest `play`, for the one-shot triggers below, which should not
+  // replay just because the string or timing props changed.
+  const latestPlay = useRef(play);
+  useEffect(() => {
+    latestPlay.current = play;
+  }, [play]);
+
+  // Mount and in-view play once by themselves.
+  useEffect(() => {
+    const element = node.current;
+    if (trigger === "hover" || !element) return;
+    if (trigger === "mount" || typeof IntersectionObserver !== "function") {
+      latestPlay.current();
+      return;
+    }
+    const observer = new IntersectionObserver((entries) => {
+      if (entries.some((entry) => entry.isIntersecting)) {
+        observer.disconnect();
+        latestPlay.current();
+      }
+    });
+    observer.observe(element);
+    return () => {
+      observer.disconnect();
+    };
+  }, [trigger]);
+
+  const setRef = useCallback(
+    (element: HTMLElement | null) => {
+      node.current = element;
+      if (typeof ref === "function") ref(element);
+      else if (ref) ref.current = element;
+    },
+    [ref],
+  );
+
+  return (
+    <Component
+      ref={setRef}
+      data-slot="scramble-text"
+      data-state={running ? "scrambling" : "idle"}
+      className={cn(scrambleTextVariants({ font }), className)}
+      {...props}
+    >
+      <span data-slot="scramble-text-glyphs" aria-hidden="true">
+        {running ? display : children}
+      </span>
+      <span className="sr-only">{children}</span>
+    </Component>
+  );
+}
+
+export { scrambleTextVariants };

package/src/components/scroll-reveal-text/index.ts

@@ -0,0 +1,6 @@
+export {
+  ScrollRevealText,
+  scrollRevealTextVariants,
+  type ScrollRevealTextElement,
+  type ScrollRevealTextProps,
+} from "./scroll-reveal-text";

package/src/components/scroll-reveal-text/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "scroll-reveal-text",
+  title: "Scroll Reveal Text",
+  description:
+    "A paragraph whose words brighten from dim to full as it scrolls through the viewport.",
+  category: "effects",
+  status: "beta",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["scroll-reveal-text.tsx"],
+  a11y:
+    "The words are aria-hidden and the paragraph is read once from an sr-only copy. Driven by CSS scroll-driven " +
+    "animation where supported, with a frame-throttled scroll fallback; without either, and under reduced motion, " +
+    "every word is fully legible. Dimmed words are below contrast by design until revealed, so keep essential " +
+    "content out of it.",
+});

package/src/components/scroll-reveal-text/scroll-reveal-text.tsx

@@ -0,0 +1,193 @@
+"use client";
+
+// Ported from SmoothUI Scroll Reveal Paragraph (MIT, © 2024 Eduardo Calvo). See THIRD_PARTY_NOTICES.md.
+import { cva, type VariantProps } from "class-variance-authority";
+import {
+  Fragment,
+  useCallback,
+  useEffect,
+  useRef,
+  type ComponentPropsWithRef,
+  type CSSProperties,
+  type Ref,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/*
+ * Words brighten from dim to full, one after another, as the paragraph scrolls
+ * up the viewport.
+ *
+ * The source tracked scroll with a Motion `useScroll` value between
+ * `start 0.9` and `start 0.25` — the paragraph's top edge crossing 90%, then
+ * 25%, of the viewport height — and gave each of n words an equal slice of
+ * that progress. Here the same range drives a CSS scroll-driven animation:
+ *
+ * - The paragraph names a view timeline. Its `cover` range starts when the top
+ *   edge meets the bottom of the viewport, so `cover 10vh` is the top at 90%
+ *   and `cover 75vh` the top at 25%. Word i animates over its 1/n slice of
+ *   those 65vh. No JavaScript runs per frame; no React state changes on scroll.
+ * - Where scroll-driven animation is unsupported, a scroll listener throttled
+ *   to one read per animation frame writes the same progress to a CSS variable
+ *   on the paragraph, and each word derives its opacity from it in CSS.
+ * - The source's two stacked layers (a 10% ghost under a fading full-colour
+ *   copy) composite to exactly `0.1 + 0.9 × progress` opacity, so each word is
+ *   one span fading from `dimOpacity` to 1. It keeps the consumer's colour.
+ *
+ * Every word is legible unless something is actively animating it: without
+ * JavaScript and without scroll-timeline support, and under reduced motion,
+ * the text is simply the text. The words are aria-hidden and the paragraph is
+ * read once from an sr-only copy.
+ */
+
+const PREFIX = "dowel-scroll-reveal-text";
+const I = `--${PREFIX}-i`;
+const N = `--${PREFIX}-n`;
+const DIM = `--${PREFIX}-dim`;
+const PROGRESS = `--${PREFIX}-progress`;
+
+// The source's offsets: the top edge from 90% to 25% of the viewport.
+const START_VH = 10;
+const SPAN_VH = 65;
+
+const STYLES = `
+@supports (animation-timeline:view()){@media (prefers-reduced-motion:no-preference){
+[data-slot=scroll-reveal-text]{view-timeline-name:--${PREFIX}}
+[data-slot=scroll-reveal-text-word]{animation:${PREFIX}-word linear both;animation-timeline:--${PREFIX};animation-range-start:cover calc(${String(START_VH)}vh + ${String(SPAN_VH)}vh * var(${I}) / var(${N}));animation-range-end:cover calc(${String(START_VH)}vh + ${String(SPAN_VH)}vh * (var(${I}) + 1) / var(${N}))}
+}}
+[data-slot=scroll-reveal-text][data-fallback] [data-slot=scroll-reveal-text-word]{opacity:clamp(var(${DIM}),calc(var(${DIM}) + (1 - var(${DIM})) * (var(${PROGRESS},1) * var(${N}) - var(${I}))),1)}
+@keyframes ${PREFIX}-word{from{opacity:var(${DIM})}to{opacity:1}}
+`;
+
+/** Elements text effects render as. They are all phrasing or heading content. */
+export type ScrollRevealTextElement =
+  "span" | "p" | "div" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6";
+
+const scrollRevealTextVariants = cva("", {
+  variants: {
+    size: {
+      sm: "text-base leading-relaxed",
+      md: "text-lg leading-relaxed",
+      lg: "text-2xl leading-snug",
+      xl: "text-4xl leading-tight font-semibold tracking-tight",
+    },
+  },
+  defaultVariants: {
+    size: "md",
+  },
+});
+
+export interface ScrollRevealTextProps
+  extends
+    Omit<ComponentPropsWithRef<"p">, "ref" | "children">,
+    VariantProps<typeof scrollRevealTextVariants> {
+  ref?: Ref<HTMLElement>;
+  /** The paragraph. Split into words on whitespace. */
+  children: string;
+  /** The element to render. */
+  as?: ScrollRevealTextElement;
+  /** Opacity of a word before it is revealed, from 0 to 1. */
+  dimOpacity?: number;
+}
+
+function scrollTimelineSupported(): boolean {
+  return typeof CSS !== "undefined" && typeof CSS.supports === "function"
+    ? CSS.supports("animation-timeline: view()")
+    : false;
+}
+
+function reducedMotion(): boolean {
+  return (
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  );
+}
+
+/**
+ * The fallback: progress through the source's range, written to a CSS
+ * variable at most once per frame. Returns a cleanup.
+ */
+function trackScroll(element: HTMLElement): () => void {
+  let frame = 0;
+  const update = () => {
+    frame = 0;
+    const height = window.innerHeight || 1;
+    const top = element.getBoundingClientRect().top;
+    const progress = ((1 - START_VH / 100) * height - top) / ((SPAN_VH / 100) * height);
+    element.style.setProperty(PROGRESS, String(Math.min(Math.max(progress, 0), 1)));
+  };
+  const schedule = () => {
+    if (frame === 0) frame = requestAnimationFrame(update);
+  };
+
+  element.setAttribute("data-fallback", "");
+  update();
+  window.addEventListener("scroll", schedule, { passive: true, capture: true });
+  window.addEventListener("resize", schedule, { passive: true });
+  return () => {
+    if (frame !== 0) cancelAnimationFrame(frame);
+    window.removeEventListener("scroll", schedule, { capture: true });
+    window.removeEventListener("resize", schedule);
+    element.removeAttribute("data-fallback");
+    element.style.removeProperty(PROGRESS);
+  };
+}
+
+/** A paragraph whose words brighten from dim to full as it scrolls through the viewport. */
+export function ScrollRevealText({
+  as: Component = "p",
+  children,
+  dimOpacity = 0.1,
+  size,
+  className,
+  style,
+  ref,
+  ...props
+}: ScrollRevealTextProps) {
+  const node = useRef<HTMLElement | null>(null);
+  const words = children.split(/\s+/).filter(Boolean);
+
+  useEffect(() => {
+    const element = node.current;
+    if (!element || scrollTimelineSupported() || reducedMotion()) return;
+    return trackScroll(element);
+  }, []);
+
+  const setRef = useCallback(
+    (element: HTMLElement | null) => {
+      node.current = element;
+      if (typeof ref === "function") ref(element);
+      else if (ref) ref.current = element;
+    },
+    [ref],
+  );
+
+  return (
+    <>
+      <style href={PREFIX} precedence="dowel">
+        {STYLES}
+      </style>
+      <Component
+        ref={setRef}
+        data-slot="scroll-reveal-text"
+        className={cn(scrollRevealTextVariants({ size }), className)}
+        style={{ [N]: words.length, [DIM]: dimOpacity, ...style } as CSSProperties}
+        {...props}
+      >
+        <span data-slot="scroll-reveal-text-words" aria-hidden="true">
+          {words.map((word, index) => (
+            <Fragment key={index}>
+              {index > 0 ? " " : null}
+              <span data-slot="scroll-reveal-text-word" style={{ [I]: index } as CSSProperties}>
+                {word}
+              </span>
+            </Fragment>
+          ))}
+        </span>
+        <span className="sr-only">{children}</span>
+      </Component>
+    </>
+  );
+}
+
+export { scrollRevealTextVariants };

package/src/components/scrubber/index.ts

@@ -0,0 +1 @@
+export { Scrubber, scrubberVariants, type ScrubberProps } from "./scrubber";

package/src/components/scrubber/meta.ts

@@ -0,0 +1,20 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "scrubber",
+  title: "Scrubber",
+  description:
+    "A design-tool number field: drag across a labelled bar to scrub a value, step it from the keyboard, or type it.",
+  category: "form",
+  status: "beta",
+  dependencies: ["class-variance-authority", "radix-ui"],
+  registryDependencies: [],
+  files: ["scrubber.tsx"],
+  a11y:
+    'The bar is a focusable role="slider" named by its visible label, with aria-valuenow, -valuemin, -valuemax ' +
+    "and an aria-valuetext matching the number on screen. Arrow keys step (Left/Right follow the reading " +
+    "direction), Shift + arrow and Page Up/Down take large steps, Home/End jump to the ends. Enter or a " +
+    "double-click opens a text field for an exact value (advertised with aria-keyshortcuts); Enter or blur commits, " +
+    "Escape cancels, and focus returns to the slider. Ticks, fill and thumb are aria-hidden. The thumb's " +
+    "transitions stop under reduced motion.",
+});