@cronus-ui/ui 0.6.0

package/dist/components/tags-input.d.ts

@@ -0,0 +1,39 @@
+export interface TagsInputProps {
+    /** Controlled list of committed tags. Pair with `onValueChange`. */
+    value?: string[];
+    /** Initial tags for uncontrolled usage. */
+    defaultValue?: string[];
+    /** Called with the next list of tags whenever a tag is added or removed. */
+    onValueChange?: (tags: string[]) => void;
+    /** Placeholder shown in the text field when it is empty. */
+    placeholder?: string;
+    /** Maximum number of tags. Once reached, further additions are ignored. */
+    max?: number;
+    /** Disables typing and tag removal. */
+    disabled?: boolean;
+    /** When true, the same tag may be added more than once. Defaults to false. */
+    allowDuplicates?: boolean;
+    /**
+     * Characters that commit the current input as a tag, in addition to Enter.
+     * Defaults to a comma, so both Enter and "," commit.
+     */
+    delimiter?: string | string[];
+    /** Reject a tag when this returns false. Receives the trimmed candidate. */
+    validate?: (tag: string) => boolean;
+    /** Marks the field as invalid, applying error styling. */
+    "aria-invalid"?: boolean | "true" | "false";
+    /** Native id for the text input (for an external `<label htmlFor>`). */
+    id?: string;
+    /** Accessible name for the text input when there is no visible label. */
+    "aria-label"?: string;
+    /** id of an element that labels the text input. */
+    "aria-labelledby"?: string;
+    /** Native name for the text input. */
+    name?: string;
+    /** Extra classes for the field wrapper. */
+    className?: string;
+    /** Extra classes for the inner text input. */
+    inputClassName?: string;
+}
+export declare const TagsInput: import("react").ForwardRefExoticComponent<TagsInputProps & import("react").RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=tags-input.d.ts.map

package/dist/components/tags-input.js

@@ -0,0 +1,86 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { X } from "lucide-react";
+import { forwardRef, useCallback, useImperativeHandle, useRef, useState, } from "react";
+import { cn } from "../lib/cn.js";
+import { Badge } from "./badge.js";
+const DEFAULT_DELIMITERS = [","];
+export const TagsInput = forwardRef(({ value: valueProp, defaultValue, onValueChange, placeholder, max, disabled = false, allowDuplicates = false, delimiter = DEFAULT_DELIMITERS, validate, "aria-invalid": ariaInvalid, id, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, name, className, inputClassName, }, ref) => {
+    const inputRef = useRef(null);
+    // Expose the inner input as the forwarded ref so consumers can focus it.
+    useImperativeHandle(ref, () => inputRef.current, []);
+    const [draft, setDraft] = useState("");
+    const isControlled = valueProp !== undefined;
+    const [internalValue, setInternalValue] = useState(defaultValue ?? []);
+    const tags = isControlled ? valueProp : internalValue;
+    const delimiters = Array.isArray(delimiter) ? delimiter : [delimiter];
+    const setTags = useCallback((next) => {
+        if (!isControlled)
+            setInternalValue(next);
+        onValueChange?.(next);
+    }, [isControlled, onValueChange]);
+    const addTag = useCallback((raw) => {
+        const tag = raw.trim();
+        if (tag === "")
+            return false;
+        if (max !== undefined && tags.length >= max)
+            return false;
+        if (!allowDuplicates && tags.includes(tag))
+            return false;
+        if (validate && !validate(tag))
+            return false;
+        setTags([...tags, tag]);
+        return true;
+    }, [tags, max, allowDuplicates, validate, setTags]);
+    const removeTag = useCallback((index) => {
+        setTags(tags.filter((_, i) => i !== index));
+    }, [tags, setTags]);
+    const handleKeyDown = useCallback((event) => {
+        if (disabled)
+            return;
+        if (event.key === "Enter") {
+            // Don't submit a surrounding form when committing a tag.
+            event.preventDefault();
+            if (addTag(draft))
+                setDraft("");
+            return;
+        }
+        if (delimiters.includes(event.key)) {
+            event.preventDefault();
+            if (addTag(draft))
+                setDraft("");
+            return;
+        }
+        if (event.key === "Backspace" && draft === "" && tags.length > 0) {
+            // Empty field: backspace edits the committed tags, not the text.
+            event.preventDefault();
+            removeTag(tags.length - 1);
+        }
+    }, [disabled, draft, delimiters, tags.length, addTag, removeTag]);
+    const handleBlur = useCallback(() => {
+        // Commit any pending text on blur so a typed-but-not-entered tag isn't lost.
+        if (disabled)
+            return;
+        if (addTag(draft))
+            setDraft("");
+    }, [disabled, draft, addTag]);
+    const handleFieldMouseDown = useCallback((event) => {
+        if (disabled)
+            return;
+        // Clicking anywhere in the field (the padding, between chips) focuses the
+        // input — but let clicks land on the remove buttons themselves.
+        if (event.target === inputRef.current)
+            return;
+        if (event.target.closest("[data-slot='tags-input-remove']"))
+            return;
+        event.preventDefault();
+        inputRef.current?.focus();
+    }, [disabled]);
+    const atMax = max !== undefined && tags.length >= max;
+    return (_jsxs("div", { "data-slot": "tags-input", "data-disabled": disabled ? "" : undefined, "aria-invalid": ariaInvalid, onMouseDown: handleFieldMouseDown, className: cn("flex min-h-10 w-full flex-wrap items-center gap-1.5 rounded-lg border border-border bg-surface-inset px-3 py-1.5 text-sm text-fg", "transition-[border-color,box-shadow] duration-150 ease-[var(--ease-out-quart)]", "focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2 focus-within:ring-offset-surface-base", "data-[disabled]:opacity-50 data-[disabled]:pointer-events-none", "aria-invalid:border-error aria-invalid:ring-2 aria-invalid:ring-error/30", className), children: [tags.map((tag, index) => (_jsxs(Badge, { variant: "secondary", className: "gap-1 pr-1", children: [_jsx("span", { className: "truncate", children: tag }), disabled ? null : (_jsx("button", { type: "button", tabIndex: -1, "aria-label": `Remove ${tag}`, "data-slot": "tags-input-remove", className: "flex size-3.5 items-center justify-center rounded-sm text-fg-tertiary outline-none transition-colors hover:text-fg focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset", onClick: () => removeTag(index), children: _jsx(X, { className: "size-3", "aria-hidden": "true" }) }))] }, `${tag}-${index}`))), _jsx("input", { ref: inputRef, id: id, name: name, type: "text", autoComplete: "off", disabled: disabled, 
+                // Once `max` is reached, keep the field present but read-only so focus
+                // and chip removal still work; clearing a tag re-enables typing.
+                readOnly: atMax, "aria-invalid": ariaInvalid, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, placeholder: tags.length === 0 ? placeholder : undefined, value: draft, "data-slot": "tags-input-field", className: cn("min-w-[6rem] flex-1 bg-transparent text-sm text-fg outline-none", "placeholder:text-fg-tertiary", "selection:bg-primary selection:text-primary-foreground", "disabled:pointer-events-none", inputClassName), onChange: (event) => setDraft(event.target.value), onKeyDown: handleKeyDown, onBlur: handleBlur })] }));
+});
+TagsInput.displayName = "TagsInput";
+//# sourceMappingURL=tags-input.js.map

package/dist/components/terminal.d.ts

@@ -0,0 +1,86 @@
+import { type HTMLAttributes } from "react";
+/** One line of the terminal script. */
+export interface TerminalLine {
+    /**
+     * `"input"` lines render behind the prompt and type in char-by-char with a
+     * blinking block cursor; `"output"` lines fade in whole, like a command's
+     * result being printed.
+     */
+    type: "input" | "output";
+    /** The line's text, rendered verbatim (whitespace is preserved). */
+    text: string;
+    /**
+     * Milliseconds to wait before this line starts — before typing begins for
+     * inputs, before the reveal for outputs. Defaults to 400 for inputs (the
+     * prompt sits with a blinking cursor, like a person pausing) and 150 for
+     * outputs (a beat of "execution time").
+     */
+    delay?: number;
+}
+/**
+ * Whether the session animates. `"respect"` (default) honours the visitor's
+ * `prefers-reduced-motion` setting — reduced-motion visitors get the full
+ * transcript instantly. `"always"` forces the animation (e.g. a showcase that
+ * must demonstrate it); `"never"` always renders the finished transcript.
+ */
+export type TerminalMotionPreference = "respect" | "always" | "never";
+export interface TerminalProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The scripted session, played from first to last. */
+    lines: TerminalLine[];
+    /** Title shown centered in the chrome bar (e.g. `"zsh"` or a file path). */
+    title?: string;
+    /** Render the macOS-style chrome bar (three dots + title). Defaults to `true`. */
+    chrome?: boolean;
+    /** Prompt glyph rendered before each input line. Defaults to `"$"`. */
+    prompt?: string;
+    /** Milliseconds per typed character. Defaults to `30`. */
+    typingSpeed?: number;
+    /** Restart the script from the top after it finishes. Defaults to `false`. */
+    loop?: boolean;
+    /** Milliseconds the finished transcript rests before a loop restarts. Defaults to `2000`. */
+    loopDelay?: number;
+    /**
+     * Show a copy button that copies the joined `input` commands (one per line,
+     * without the prompt) — the exact text a reader wants to paste into their
+     * own shell. Defaults to `true`; hidden automatically when the script has
+     * no input lines.
+     */
+    copyButton?: boolean;
+    /**
+     * Whether the typing animation plays vs. honours `prefers-reduced-motion`:
+     * `"respect"` (default), `"always"` (force motion), or `"never"` (always
+     * static).
+     */
+    motionPreference?: TerminalMotionPreference;
+}
+/**
+ * An animated terminal window that replays a scripted shell session. Input
+ * lines type in char-by-char behind a `$` prompt with a blinking block
+ * cursor; output lines fade in whole after a beat of "execution time". The
+ * script is driven by a single chain of `setTimeout`s (one live timer at any
+ * moment, fully cleaned up on unmount/restart) that advances a tiny
+ * `{ revealed, typedChars }` state — no per-frame work, no layout thrash.
+ *
+ * **SSR-safe:** the server (and the hydration pass) renders the *finished*
+ * transcript, so no-JS readers and crawlers see the real content and there is
+ * no hydration mismatch. A layout effect flips to the animated state before
+ * first paint, so animated visitors never see a flash of the full transcript.
+ *
+ * **Reduced motion:** `prefers-reduced-motion` (or
+ * {@link TerminalProps.motionPreference} `"never"`) renders everything
+ * instantly — no typing, no cursor, no fades — and the preference is tracked
+ * live via `matchMedia`.
+ *
+ * **No layout shift:** an invisible copy of the finished transcript sits
+ * in-flow as a sizer and the animation plays in an absolutely-positioned
+ * overlay, so the window is final-size from the first frame and looping never
+ * collapses the page.
+ *
+ * **Accessibility:** the animated pane is `aria-hidden`; assistive tech gets
+ * the complete transcript immediately from a visually-hidden `<pre>` (no
+ * live-region spam, no half-typed announcements). The scrollable body is
+ * keyboard-focusable with a visible focus ring, and the copy button copies
+ * the joined input commands.
+ */
+export declare const Terminal: import("react").ForwardRefExoticComponent<TerminalProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=terminal.d.ts.map

package/dist/components/terminal.js

@@ -0,0 +1,182 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
+import { cn } from "../lib/cn.js";
+import { CopyButton } from "./copy-button.js";
+/**
+ * Grapheme segmenter so char-by-char typing never splits a user-perceived
+ * character. Slicing by UTF-16 code units shatters emoji (✅, 🇧🇷) and complex
+ * scripts mid-glyph; segmenting by grapheme types each cluster as one unit.
+ * Null on platforms without `Intl.Segmenter`, where we fall back to code
+ * points (still safe for surrogate pairs).
+ */
+const graphemeSegmenter = typeof Intl !== "undefined" && "Segmenter" in Intl
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+function segmentGraphemes(text) {
+    if (graphemeSegmenter) {
+        return Array.from(graphemeSegmenter.segment(text), (segment) => segment.segment);
+    }
+    return Array.from(text);
+}
+const DEFAULT_TYPING_SPEED = 30;
+const DEFAULT_LOOP_DELAY = 2000;
+const DEFAULT_INPUT_DELAY = 400;
+const DEFAULT_OUTPUT_DELAY = 150;
+/**
+ * Fixed (not per-instance) keyframe names are safe here because every
+ * instance declares the exact same frames — later identical declarations are
+ * no-ops. Output lines rise-and-fade in; `both` keeps them visible after the
+ * animation so finished lines never flicker. The blinking cursor reuses the
+ * theme's `animate-caret-blink` utility.
+ */
+const TERMINAL_KEYFRAMES = "@keyframes cronus-terminal-fade{from{opacity:0;transform:translateY(2px)}to{opacity:1;transform:none}}";
+function finitePositive(value, fallback) {
+    return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+/**
+ * One rendered line. Input lines carry the prompt in `text-fg-tertiary` and
+ * the command in `text-fg`; output lines print flush-left in
+ * `text-fg-secondary`, matching a real shell.
+ */
+function TerminalRow({ line, prompt, typedChars, showCursor = false, reveal = false, }) {
+    const isInput = line.type === "input";
+    const graphemes = useMemo(() => segmentGraphemes(line.text), [line.text]);
+    const shown = typedChars === undefined ? line.text : graphemes.slice(0, typedChars).join("");
+    return (_jsxs("div", { "data-slot": "terminal-line", "data-line-type": line.type, className: cn("flex gap-2", !isInput &&
+            reveal &&
+            "[animation:cronus-terminal-fade_240ms_ease-out_both] motion-reduce:[animation:none]"), children: [isInput ? (_jsx("span", { "data-slot": "terminal-prompt", className: "select-none text-fg-tertiary", children: prompt })) : null, _jsxs("span", { className: cn("min-w-0 flex-1 whitespace-pre-wrap break-words", isInput ? "text-fg" : "text-fg-secondary"), children: [shown, showCursor ? (_jsx("span", { "data-slot": "terminal-cursor", className: "ml-px inline-block h-[1.1em] w-[0.55em] translate-y-[0.18em] rounded-[1px] bg-fg animate-caret-blink" })) : null] })] }));
+}
+/**
+ * An animated terminal window that replays a scripted shell session. Input
+ * lines type in char-by-char behind a `$` prompt with a blinking block
+ * cursor; output lines fade in whole after a beat of "execution time". The
+ * script is driven by a single chain of `setTimeout`s (one live timer at any
+ * moment, fully cleaned up on unmount/restart) that advances a tiny
+ * `{ revealed, typedChars }` state — no per-frame work, no layout thrash.
+ *
+ * **SSR-safe:** the server (and the hydration pass) renders the *finished*
+ * transcript, so no-JS readers and crawlers see the real content and there is
+ * no hydration mismatch. A layout effect flips to the animated state before
+ * first paint, so animated visitors never see a flash of the full transcript.
+ *
+ * **Reduced motion:** `prefers-reduced-motion` (or
+ * {@link TerminalProps.motionPreference} `"never"`) renders everything
+ * instantly — no typing, no cursor, no fades — and the preference is tracked
+ * live via `matchMedia`.
+ *
+ * **No layout shift:** an invisible copy of the finished transcript sits
+ * in-flow as a sizer and the animation plays in an absolutely-positioned
+ * overlay, so the window is final-size from the first frame and looping never
+ * collapses the page.
+ *
+ * **Accessibility:** the animated pane is `aria-hidden`; assistive tech gets
+ * the complete transcript immediately from a visually-hidden `<pre>` (no
+ * live-region spam, no half-typed announcements). The scrollable body is
+ * keyboard-focusable with a visible focus ring, and the copy button copies
+ * the joined input commands.
+ */
+export const Terminal = forwardRef(({ lines, title, chrome = true, prompt = "$", typingSpeed = DEFAULT_TYPING_SPEED, loop = false, loopDelay = DEFAULT_LOOP_DELAY, copyButton = true, motionPreference = "respect", className, ...props }, ref) => {
+    const [mounted, setMounted] = useState(false);
+    const [reducedMotion, setReducedMotion] = useState(false);
+    const [progress, setProgress] = useState({ revealed: 0, typedChars: 0 });
+    const safeTypingSpeed = Math.max(finitePositive(typingSpeed, DEFAULT_TYPING_SPEED), 1);
+    const safeLoopDelay = finitePositive(loopDelay, DEFAULT_LOOP_DELAY);
+    // Content signature: identity-stable across parent re-renders (an inline
+    // `lines={[...]}` literal must NOT restart the session every render), yet
+    // changes whenever the script's content actually changes.
+    const signature = useMemo(() => lines.map((line) => `${line.type}
${line.text}
${line.delay ?? ""}`).join(""), [lines]);
+    // The engine reads lines through a ref at tick time so a same-content,
+    // new-identity array never restarts (nor stales) a running session. This
+    // effect is declared BEFORE the engine effect so the ref is fresh by the
+    // time a signature change re-runs the script.
+    const linesRef = useRef(lines);
+    useEffect(() => {
+        linesRef.current = lines;
+    });
+    // Mount + reduced-motion resolve in ONE layout effect (before first
+    // client paint): the SSR/hydration render shows the finished transcript,
+    // and by the time the browser paints we already know whether to animate —
+    // reduced-motion visitors never see content clear, animated visitors
+    // never see it flash.
+    useLayoutEffect(() => {
+        setMounted(true);
+        if (typeof window.matchMedia !== "function")
+            return;
+        const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+        setReducedMotion(query.matches);
+        const onChange = (event) => setReducedMotion(event.matches);
+        query.addEventListener("change", onChange);
+        return () => query.removeEventListener("change", onChange);
+    }, []);
+    const animate = motionPreference === "never"
+        ? false
+        : motionPreference === "always"
+            ? mounted
+            : mounted && !reducedMotion;
+    // The script engine: a chain of setTimeouts advancing one shared timer.
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `signature` stands in for `lines` (restart on content change, not identity change); the line data itself is read from `linesRef` at tick time.
+    useEffect(() => {
+        if (!animate)
+            return;
+        let disposed = false;
+        let timer;
+        const run = (index) => {
+            if (disposed)
+                return;
+            const script = linesRef.current;
+            setProgress({ revealed: Math.min(index, script.length), typedChars: 0 });
+            if (index >= script.length) {
+                if (loop && script.length > 0) {
+                    timer = setTimeout(() => run(0), safeLoopDelay);
+                }
+                return;
+            }
+            const line = script[index];
+            if (!line)
+                return;
+            const wait = line.delay ?? (line.type === "input" ? DEFAULT_INPUT_DELAY : DEFAULT_OUTPUT_DELAY);
+            if (line.type === "output") {
+                // Outputs reveal atomically after their delay; the fade is CSS.
+                timer = setTimeout(() => run(index + 1), wait);
+                return;
+            }
+            const graphemes = segmentGraphemes(line.text);
+            const typeChar = (count) => {
+                if (disposed)
+                    return;
+                setProgress({ revealed: index, typedChars: count });
+                if (count >= graphemes.length) {
+                    run(index + 1);
+                    return;
+                }
+                timer = setTimeout(() => typeChar(count + 1), safeTypingSpeed);
+            };
+            timer = setTimeout(() => typeChar(graphemes.length > 0 ? 1 : 0), wait);
+        };
+        run(0);
+        return () => {
+            disposed = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+        };
+    }, [animate, signature, loop, safeLoopDelay, safeTypingSpeed]);
+    const totalLines = lines.length;
+    const revealedCount = animate ? Math.min(progress.revealed, totalLines) : totalLines;
+    const activeLine = animate ? lines[progress.revealed] : undefined;
+    const finished = revealedCount >= totalLines;
+    const copyValue = useMemo(() => lines
+        .filter((line) => line.type === "input")
+        .map((line) => line.text)
+        .join("\n"), [lines]);
+    const showCopy = copyButton && copyValue.length > 0;
+    const transcript = useMemo(() => lines
+        .map((line) => (line.type === "input" ? `${prompt} ${line.text}` : line.text))
+        .join("\n"), [lines, prompt]);
+    const regionLabel = title ? `Terminal, ${title}` : "Terminal";
+    return (_jsxs("div", { ref: ref, "data-slot": "terminal", "data-state": !animate ? "static" : finished ? "done" : "animating", className: cn("overflow-hidden rounded-xl border border-border bg-surface-inset text-fg shadow-sm", className), ...props, children: [_jsx("style", { children: TERMINAL_KEYFRAMES }), chrome ? (_jsxs("div", { "data-slot": "terminal-chrome", className: "flex items-center gap-2 border-b border-border bg-surface-raised px-4 py-2.5", children: [_jsxs("div", { "aria-hidden": "true", className: "flex shrink-0 items-center gap-1.5", children: [_jsx("span", { className: "size-2.5 rounded-full bg-error/80" }), _jsx("span", { className: "size-2.5 rounded-full bg-warning/80" }), _jsx("span", { className: "size-2.5 rounded-full bg-success/80" })] }), _jsx("span", { "data-slot": "terminal-title", className: "min-w-0 flex-1 select-none truncate text-center text-xs font-medium text-fg-tertiary", children: title }), showCopy ? (_jsx(CopyButton, { value: copyValue, size: "icon-sm", "aria-label": "Copy commands", className: "-mr-1.5 shrink-0" })) : (_jsx("span", { "aria-hidden": "true", className: "w-10 shrink-0" }))] })) : null, _jsxs("div", { className: "relative", children: [!chrome && showCopy ? (_jsx(CopyButton, { value: copyValue, size: "icon-sm", "aria-label": "Copy commands", className: "absolute right-2 top-2 z-10 shrink-0 bg-surface-overlay/80 backdrop-blur-sm" })) : null, _jsxs("section", { "data-slot": "terminal-body", 
+                        // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region is intentionally focusable so keyboard users can scroll it.
+                        tabIndex: 0, "aria-label": regionLabel, className: "relative overflow-auto font-mono text-sm leading-relaxed tabular-nums outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-inset", children: [_jsx("pre", { "data-slot": "terminal-transcript", className: "sr-only", children: transcript }), _jsxs("div", { "aria-hidden": "true", className: "relative p-4", children: [_jsx("div", { "data-slot": "terminal-sizer", className: "invisible", children: lines.map((line, index) => (_jsx(TerminalRow, { line: line, prompt: prompt }, index))) }), _jsxs("div", { "data-slot": "terminal-screen", className: "absolute inset-0 overflow-hidden p-4", children: [lines.slice(0, revealedCount).map((line, index) => (_jsx(TerminalRow, { line: line, prompt: prompt, reveal: animate }, index))), activeLine?.type === "input" ? (_jsx(TerminalRow, { line: activeLine, prompt: prompt, typedChars: progress.typedChars, showCursor: true })) : null] })] })] })] })] }));
+});
+Terminal.displayName = "Terminal";
+//# sourceMappingURL=terminal.js.map

package/dist/components/text-effect.d.ts

@@ -0,0 +1,71 @@
+/** How the text is broken up before staggering the enter animation. */
+export type TextEffectPer = "word" | "char";
+/** Which per-unit enter animation plays. */
+export type TextEffectPreset = "fade" | "blur" | "slide";
+/** When the reveal fires. */
+export type TextEffectTrigger = "mount" | "inView";
+export interface TextEffectProps extends Omit<React.HTMLAttributes<HTMLElement>, "children"> {
+    /**
+     * The text to reveal. Must be a plain string so it can be split into words
+     * or characters — pass interpolated values as a single template string, not
+     * as child nodes.
+     */
+    children: string;
+    /** Split granularity. `"word"` (default) staggers words; `"char"` staggers letters. */
+    per?: TextEffectPer;
+    /** Which enter animation each unit plays. Defaults to `"blur"`. */
+    preset?: TextEffectPreset;
+    /**
+     * The rendered wrapper element/tag (e.g. `"h1"`, `"span"`). Defaults to `"p"`.
+     * The wrapper itself is not animated — it carries the accessible label while
+     * inner `motion.span`s do the animating.
+     */
+    as?: React.ElementType;
+    /** Delay (seconds) before the first unit animates. Defaults to `0`. */
+    delay?: number;
+    /**
+     * Time (seconds) between consecutive units. Defaults to `0.04` for words and
+     * `0.02` for characters.
+     */
+    stagger?: number;
+    /** Per-unit animation duration (seconds). Defaults to `0.4`. */
+    duration?: number;
+    /**
+     * `"inView"` (default) animates once when the element scrolls into view;
+     * `"mount"` animates immediately on mount.
+     */
+    trigger?: TextEffectTrigger;
+    /**
+     * How `prefers-reduced-motion` is honoured. Defaults to `"user"` (render the
+     * text statically for users who opt out). Pass `"never"` to always play the
+     * stagger — e.g. a showcase that must demonstrate it — or `"always"` to force
+     * the static render.
+     */
+    reducedMotion?: "user" | "always" | "never";
+}
+/**
+ * Reveal a string by splitting it into words or characters and staggering an
+ * enter animation across the units. Built for heros, section titles, and
+ * onboarding moments where copy should "arrive" rather than pop.
+ *
+ * **Presets** — `fade` (opacity), `blur` (opacity + a clearing 8px blur, the
+ * default and most premium-feeling), and `slide` (opacity + an 8px rise). The
+ * container drives timing via `staggerChildren`; each unit only animates its own
+ * property, so the settled state is byte-identical to plain text.
+ *
+ * **Trigger** — `inView` (default) plays the reveal once when the text scrolls
+ * into view; `mount` plays it immediately. In-view detection fires a little
+ * before the element fully enters the viewport so the motion feels anticipatory.
+ *
+ * **Accessibility** — split text is hostile to screen readers, selection, and
+ * find-in-page. So the wrapper carries `aria-label={children}` (assistive tech
+ * reads the whole string once, naturally) while the animated `motion.span` tree
+ * is marked `aria-hidden`. Sighted users see the staggered reveal; AT users get
+ * the clean string.
+ *
+ * **Reduced motion** — when the user prefers reduced motion the text renders
+ * fully visible with no blur, transform, or stagger (a single instant fade at
+ * most). Honours `prefers-reduced-motion` via {@link useReducedMotion}.
+ */
+export declare const TextEffect: import("react").ForwardRefExoticComponent<TextEffectProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=text-effect.d.ts.map

package/dist/components/text-effect.js

@@ -0,0 +1,166 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { motion, useInView, useReducedMotion } from "motion/react";
+import { forwardRef, useMemo, useRef, useState } from "react";
+import { cn } from "../lib/cn.js";
+/**
+ * Grapheme segmenter for `per: "char"` so user-perceived characters stay whole.
+ * Splitting by code point shatters ZWJ emoji (👨‍👩‍👧‍👦), flags (🇧🇷), and complex
+ * scripts; segmenting by grapheme keeps each cluster as one animated unit. Null
+ * on platforms without `Intl.Segmenter`, where we fall back to code-point split.
+ */
+const graphemeSegmenter = typeof Intl !== "undefined" && "Segmenter" in Intl
+    ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
+    : null;
+/**
+ * Per-unit enter animations. Each is a {@link Variants} pair keyed `hidden` /
+ * `visible`; the container orchestrates timing via `staggerChildren`, so the
+ * per-unit `transition` only carries the easing/duration (duration is injected
+ * at runtime from the `duration` prop). All presets land on the fully-visible
+ * resting state — no residual transform/filter — so layout and text rendering
+ * are pixel-identical to plain text once the animation settles.
+ */
+const PRESETS = {
+    fade: {
+        hidden: { opacity: 0 },
+        visible: { opacity: 1 },
+    },
+    blur: {
+        hidden: { opacity: 0, filter: "blur(8px)" },
+        visible: { opacity: 1, filter: "blur(0px)" },
+    },
+    slide: {
+        hidden: { opacity: 0, y: 8 },
+        visible: { opacity: 1, y: 0 },
+    },
+};
+/** Default per-unit stagger, tuned so a whole title still reads as one gesture. */
+const DEFAULT_STAGGER = {
+    word: 0.04,
+    char: 0.02,
+};
+/**
+ * Container variants: hold children hidden, then release them on a stagger.
+ * When `reduced` is set the stagger collapses to an instant, zero-delay release
+ * so reduced-motion users get fully-static text the frame after hydration.
+ */
+function buildContainerVariants(stagger, delay, reduced) {
+    return {
+        hidden: {},
+        visible: {
+            transition: reduced
+                ? { staggerChildren: 0, delayChildren: 0, duration: 0 }
+                : { staggerChildren: stagger, delayChildren: delay },
+        },
+    };
+}
+/**
+ * Split text into renderable units while keeping word boundaries intact.
+ *
+ * For `per: "word"` each token is a word and a trailing space is preserved as a
+ * separate token so wrapping/justification behave exactly like normal text. For
+ * `per: "char"` we split into words *first*, then into characters, so a word can
+ * never wrap mid-token — the word stays an inline-block group whose own letters
+ * stagger inside it.
+ */
+function splitText(text, per) {
+    // Split on whitespace runs but keep the separators, so multiple/explicit
+    // spaces survive round-tripping.
+    const tokens = text.split(/(\s+)/).filter((token) => token.length > 0);
+    if (per === "word") {
+        return tokens.map((token) => [token]);
+    }
+    return tokens.map((token) => /^\s+$/.test(token)
+        ? [token]
+        : graphemeSegmenter
+            ? Array.from(graphemeSegmenter.segment(token), (s) => s.segment)
+            : Array.from(token));
+}
+/**
+ * Reveal a string by splitting it into words or characters and staggering an
+ * enter animation across the units. Built for heros, section titles, and
+ * onboarding moments where copy should "arrive" rather than pop.
+ *
+ * **Presets** — `fade` (opacity), `blur` (opacity + a clearing 8px blur, the
+ * default and most premium-feeling), and `slide` (opacity + an 8px rise). The
+ * container drives timing via `staggerChildren`; each unit only animates its own
+ * property, so the settled state is byte-identical to plain text.
+ *
+ * **Trigger** — `inView` (default) plays the reveal once when the text scrolls
+ * into view; `mount` plays it immediately. In-view detection fires a little
+ * before the element fully enters the viewport so the motion feels anticipatory.
+ *
+ * **Accessibility** — split text is hostile to screen readers, selection, and
+ * find-in-page. So the wrapper carries `aria-label={children}` (assistive tech
+ * reads the whole string once, naturally) while the animated `motion.span` tree
+ * is marked `aria-hidden`. Sighted users see the staggered reveal; AT users get
+ * the clean string.
+ *
+ * **Reduced motion** — when the user prefers reduced motion the text renders
+ * fully visible with no blur, transform, or stagger (a single instant fade at
+ * most). Honours `prefers-reduced-motion` via {@link useReducedMotion}.
+ */
+export const TextEffect = forwardRef(({ children, per = "word", preset = "blur", as: Component = "p", delay = 0, stagger, duration = 0.4, trigger = "inView", reducedMotion = "user", className, ...props }, forwardedRef) => {
+    const localRef = useRef(null);
+    const systemReducedMotion = useReducedMotion();
+    const prefersReducedMotion = reducedMotion === "never" ? false : reducedMotion === "always" ? true : systemReducedMotion;
+    // `will-change` is only worth its GPU layer while a unit is actually moving;
+    // gating on this flag (set/cleared by the container's animation lifecycle)
+    // lets the leaf spans drop their promoted layers at rest.
+    const [isAnimating, setIsAnimating] = useState(false);
+    const resolvedStagger = stagger ?? DEFAULT_STAGGER[per];
+    // Observe for the in-view trigger. We render a single DOM tree for server
+    // and client (no early reduced-motion return) so reduced motion is driven
+    // purely through animation props below — not through divergent markup.
+    const isInView = useInView(localRef, { once: true, margin: "-80px" });
+    // Reduced-motion users snap straight to `visible` (post-hydration, instantly
+    // via the zero-duration transitions); everyone else plays on mount/in-view.
+    const shouldPlay = prefersReducedMotion ? true : trigger === "mount" ? true : isInView;
+    const units = useMemo(() => splitText(children, per), [children, per]);
+    const containerVariants = useMemo(() => buildContainerVariants(resolvedStagger, delay, !!prefersReducedMotion), [resolvedStagger, delay, prefersReducedMotion]);
+    const itemVariants = PRESETS[preset];
+    const itemTransition = useMemo(() => ({ duration, ease: "easeOut" }), [duration]);
+    const setRef = (node) => {
+        localRef.current = node;
+        if (typeof forwardedRef === "function") {
+            forwardedRef(node);
+        }
+        else if (forwardedRef) {
+            forwardedRef.current = node;
+        }
+    };
+    return (_jsxs(Component, { ref: setRef, "data-slot": "text-effect", className: cn(className), ...props, children: [_jsx("span", { className: "sr-only", children: children }), _jsx(motion.span, { "aria-hidden": "true", 
+                // `initial` is the only variant framer renders into the SSR'd HTML, so
+                // it must be deterministic across server (reduced-motion null) and a
+                // reduced-motion client — keep it `"hidden"` unconditionally to avoid a
+                // hydration mismatch. Reduced motion is expressed by the transitions.
+                initial: "hidden", animate: shouldPlay ? "visible" : "hidden", variants: containerVariants, 
+                // Drive the will-change flag from the container's animation lifecycle so
+                // the leaf spans only promote a GPU layer while motion is in flight.
+                onAnimationStart: () => setIsAnimating(true), onAnimationComplete: () => setIsAnimating(false), 
+                // inline so the wrapper's own typography (line-height, alignment) is
+                // unaffected; child word-groups handle wrapping.
+                style: { display: "inline" }, children: units.map((unit, unitIndex) => {
+                    const unitKey = `unit-${unitIndex}`;
+                    // A whitespace-only token: render as a plain inline span so the
+                    // space can break/collapse like normal text (not an inline-block).
+                    if (unit.length === 1 && /^\s+$/.test(unit[0] ?? "")) {
+                        return (_jsx("span", { style: { whiteSpace: "pre" }, children: unit[0] }, unitKey));
+                    }
+                    // For `per: "word"` the unit is a single word token; for
+                    // `per: "char"` it is the word's characters. Either way wrap the
+                    // group inline-block so it never breaks mid-word.
+                    return (_jsx("span", { className: "inline-block", children: unit.map((piece, pieceIndex) => (_jsx(motion.span
+                        // biome-ignore lint/suspicious/noArrayIndexKey: split text pieces are positional and stable within their word.
+                        , { className: "inline-block", variants: itemVariants, 
+                            // Reduced motion snaps instantly to `visible` (no movement);
+                            // otherwise carry the easing/duration from the `duration` prop.
+                            transition: prefersReducedMotion ? { duration: 0 } : itemTransition, 
+                            // `will-change` only while animating; the `inline-block`
+                            // class (not will-change) gives transforms/filters their
+                            // formatting context, so dropping the hint at rest is safe.
+                            style: { willChange: isAnimating ? "transform, filter, opacity" : undefined }, children: piece }, `${unitKey}-piece-${pieceIndex}`))) }, unitKey));
+                }) })] }));
+});
+TextEffect.displayName = "TextEffect";
+//# sourceMappingURL=text-effect.js.map

package/dist/components/textarea.d.ts

@@ -0,0 +1,6 @@
+import { type TextareaHTMLAttributes } from "react";
+export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    invalid?: boolean;
+}
+export declare const Textarea: import("react").ForwardRefExoticComponent<TextareaProps & import("react").RefAttributes<HTMLTextAreaElement>>;
+//# sourceMappingURL=textarea.d.ts.map