@enigmax/primitives 0.17.0 → 0.18.0

package/src/react/input/index.tsx

@@ -0,0 +1,307 @@
+"use client";
+
+import { Icon } from "@/react/input/icon";
+import { INPUT_ICON_PATHS } from "@/core/input-icons";
+import { writeValue } from "@/react/input/write-value";
+import type { AnyInputProps, InputProps, FieldAction, BreachState } from "@/react/input/types";
+import { forwardRef, lazy, Suspense, useCallback, useEffect, useId, useRef, useState, type ChangeEvent, type ReactNode } from "react";
+
+/**
+ * `<Input>` - one field for every `type`, with the affordances each type needs and none of
+ * the styling.
+ *
+ * ```tsx
+ * <Input type="email" required />
+ * <Input type="password" generate strength breach={checkPasswordBreach} />
+ * <Input type="search" items={docs} keys={["title"]} renderResults={...} />
+ * ```
+ *
+ * ONE component keyed on `type`, because that is what HTML is: `type` is an attribute of a
+ * single element. What differs per type is which PROPS exist, and that is a discriminated
+ * union - `strength` on a text field is a compile error rather than a prop that silently
+ * does nothing. Widgets that are not one `<input>` stay their own components; the search
+ * PALETTE is a dialog, so it lives in `SearchPalette` rather than behind a prop here.
+ *
+ * WHAT LOADS. The field, its buttons and the reveal are this module and nothing else. The
+ * password estimator, the breach watcher and the search engine each live in their own chunk
+ * and are imported the moment the type that needs them is used - so a form of text and email
+ * fields ships none of them, and a page with one password field does not pay for search.
+ * The generator is loaded on the first press of its button, because until then it is a
+ * function nobody has called.
+ */
+
+const PasswordExtras = lazy(() => import("@/react/input/password").then((module) => ({ default: module.PasswordExtras })));
+const SearchExtras = lazy(() => import("@/react/input/search").then((module) => ({ default: module.SearchExtras })));
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(props, forwardedRef) {
+    const {
+        reveal,
+        revealLabels,
+        generate = false,
+        generateLabel = "Generate a password",
+        revealOnGenerate = true,
+        copyOnGenerate = false,
+        onGenerate,
+        actions = [],
+        position = "end",
+        strength = false,
+        onStrengthChange,
+        breach,
+        breachDelay = 500,
+        onBreachChange,
+        items,
+        keys,
+        delay,
+        limit,
+        fuse,
+        fuseOptions,
+        matcher,
+        onResults,
+        renderResults,
+        clearable,
+        clearLabel = "Clear",
+        wrapperProps,
+        fieldProps,
+        classNames,
+        children,
+        type = "text",
+        onChange,
+        ...rest
+    } = props as AnyInputProps;
+
+    const innerRef = useRef<HTMLInputElement | null>(null);
+    const [element, setElement] = useState<HTMLInputElement | null>(null);
+    const [revealed, setRevealed] = useState(false);
+    const describedBy = useId();
+
+    const isPassword = type === "password";
+    const isSearch = type === "search";
+    const showReveal = reveal ?? isPassword;
+    const showGenerate = generate !== false && isPassword;
+    const showClear = (clearable ?? isSearch) && isSearch;
+
+    // Tracked whether the field is controlled or not, because the meter, the breach check
+    // and the clear button need the current value, and an uncontrolled field never reports
+    // it as a prop.
+    const controlled = rest.value !== undefined;
+    const [ownValue, setOwnValue] = useState(String(rest.defaultValue ?? ""));
+    const value = controlled ? String(rest.value ?? "") : ownValue;
+
+    const handleChange = useCallback((event: ChangeEvent<HTMLInputElement>) => {
+        if (!controlled) setOwnValue(event.target.value);
+        onChange?.(event);
+    }, [controlled, onChange]);
+
+    /* -------- the reveal, and the caret it would otherwise eat -------- */
+
+    // Captured BEFORE the type switch. Assigning `type` while an input is focused resets
+    // the caret to 0 in Chromium, and it does it one MACROTASK later - so anything read
+    // after the switch is already the clobbered value.
+    const caret = useRef<[number, number] | null>(null);
+
+    const toggleReveal = useCallback(() => {
+        const input = innerRef.current;
+        if (input && typeof document !== "undefined" && document.activeElement === input) {
+            try {
+                const { selectionStart, selectionEnd } = input;
+                caret.current = selectionStart === null || selectionEnd === null ? null : [selectionStart, selectionEnd];
+            } catch {
+                caret.current = null;   // selection is not supported on every input type
+            }
+        }
+        setRevealed((current) => !current);
+    }, []);
+
+    useEffect(() => {
+        const selection = caret.current;
+        if (!selection) return;
+        caret.current = null;
+
+        const restore = (): void => {
+            const input = innerRef.current;
+            if (!input || document.activeElement !== input) return;
+            try { input.setSelectionRange(selection[0], selection[1]); } catch { /* unsupported */ }
+        };
+        restore();
+        // And again on the next macrotask, which is where Chromium actually clobbers it.
+        // A restore that only runs inline silently loses. Focus is re-checked first, so a
+        // visitor who clicked elsewhere meanwhile is not dragged back.
+        const timer = setTimeout(restore, 0);
+        return () => clearTimeout(timer);
+    }, [revealed]);
+
+    /* -------- the generator, loaded when it is first pressed -------- */
+
+    const handleGenerate = useCallback(async () => {
+        const input = innerRef.current;
+        if (!input) return;
+        // Imported here rather than at the top: a form with a password field that nobody
+        // ever asks to generate has no reason to carry a CSPRNG alphabet around.
+        const { generatePassword } = await import("@/core/password");
+        const password = generatePassword(typeof generate === "object" ? generate : {});
+        writeValue(input, password);
+        if (revealOnGenerate) setRevealed(true);
+        if (copyOnGenerate) void navigator.clipboard?.writeText(password).catch(() => {
+            // Denied permission or an insecure context. The password is in the field, which
+            // is the part that matters, so there is nothing to report.
+        });
+        input.focus();
+        onGenerate?.(password);
+    }, [generate, revealOnGenerate, copyOnGenerate, onGenerate]);
+
+    const handleClear = useCallback(() => {
+        const input = innerRef.current;
+        if (!input) return;
+        writeValue(input, "");
+        input.focus();
+    }, []);
+
+    /* -------- what the per-type chunks report back -------- */
+
+    const [score, setScore] = useState<number | null>(null);
+    const [breached, setBreached] = useState(false);
+
+    const handleBreach = useCallback((state: BreachState) => {
+        setBreached(state.status === "breached");
+        onBreachChange?.(state);
+    }, [onBreachChange]);
+
+    /* -------- rendering -------- */
+
+    const builtIn: FieldAction[] = [];
+    if (showGenerate) {
+        builtIn.push({
+            name: "generate",
+            label: generateLabel,
+            icon: <Icon paths={INPUT_ICON_PATHS.generate} />,
+            onSelect: () => { void handleGenerate(); }
+        });
+    }
+    if (showReveal) {
+        builtIn.push({
+            name: "reveal",
+            label: revealed ? revealLabels?.hide ?? "Hide password" : revealLabels?.show ?? "Show password",
+            icon: <Icon paths={revealed ? INPUT_ICON_PATHS.eyeOff : INPUT_ICON_PATHS.eye} />,
+            pressed: revealed,
+            onSelect: toggleReveal
+        });
+    }
+    if (showClear) {
+        builtIn.push({
+            name: "clear",
+            label: clearLabel,
+            icon: <Icon paths={INPUT_ICON_PATHS.clear} />,
+            // Nothing to clear is nothing to press: the button would be a target that does
+            // not respond, which reads as broken rather than as unavailable.
+            visible: value.length > 0,
+            onSelect: handleClear
+        });
+    }
+
+    const overridden = new Set(actions.map((action) => action.name));
+    const rendered = [...builtIn.filter((action) => !overridden.has(action.name)), ...actions]
+        .filter((action) => action.visible !== false);
+
+    const locked = rest.disabled === true || rest.readOnly === true;
+    const buttons = rendered.length === 0 ? null : (
+        <span data-enigma-input-actions="" data-position={position} className={classNames?.actions}>
+            {rendered.map((action) => (
+                <button
+                    key={action.name}
+                    type="button"
+                    data-enigma-input-action={action.name}
+                    className={classNames?.action}
+                    aria-label={action.label}
+                    title={action.label}
+                    aria-pressed={action.pressed}
+                    disabled={locked}
+                    // Keeps focus in the field: the visitor is mid-word and expects to keep
+                    // typing, and a caret that never left needs no restoring.
+                    onMouseDown={(event) => event.preventDefault()}
+                    onClick={action.onSelect}
+                >
+                    {action.icon}
+                </button>
+            ))}
+        </span>
+    );
+
+    const wantsPasswordChunk = isPassword && (strength !== false || Boolean(breach));
+    const wantsSearchChunk = isSearch && Boolean(items || matcher);
+
+    return (
+        <div
+            {...wrapperProps}
+            data-enigma-input-root=""
+            data-revealed={revealed ? "" : undefined}
+            data-breached={breached ? "" : undefined}
+            data-score={score ?? undefined}
+        >
+            <div {...fieldProps} data-enigma-input-field="">
+                {position === "start" && buttons}
+                <input
+                    {...rest}
+                    ref={(node) => {
+                        innerRef.current = node;
+                        setElement(node);
+                        if (typeof forwardedRef === "function") forwardedRef(node);
+                        else if (forwardedRef) forwardedRef.current = node;
+                    }}
+                    // Revealing a password is a type switch, which is what the caret dance
+                    // above exists for.
+                    type={revealed && isPassword ? "text" : type}
+                    onChange={handleChange}
+                    data-enigma-input=""
+                    aria-describedby={score !== null ? describedBy : rest["aria-describedby"]}
+                />
+                {position === "end" && buttons}
+            </div>
+            {/* No fallback: the field is already on screen and usable, and a spinner where a
+                meter is about to appear moves the layout twice for nothing. */}
+            {wantsPasswordChunk && (
+                <Suspense fallback={null}>
+                    <PasswordExtras
+                        id={describedBy}
+                        value={value}
+                        strength={strength}
+                        onStrengthChange={onStrengthChange}
+                        onScore={setScore}
+                        breach={breach}
+                        breachDelay={breachDelay}
+                        onBreachChange={handleBreach}
+                        classNames={classNames?.strength}
+                    />
+                </Suspense>
+            )}
+            {wantsSearchChunk && (
+                <Suspense fallback={null}>
+                    <SearchExtras
+                        input={element}
+                        items={items}
+                        keys={keys}
+                        delay={delay}
+                        limit={limit}
+                        fuse={fuse}
+                        fuseOptions={fuseOptions}
+                        matcher={matcher}
+                        onResults={onResults}
+                        renderResults={renderResults}
+                    />
+                </Suspense>
+            )}
+            {children}
+        </div>
+    );
+}) as <Item = unknown>(props: InputProps<Item> & { ref?: React.Ref<HTMLInputElement>; }) => ReactNode;
+
+/**
+ * Types only. A VALUE re-export here (`PasswordStrength`, say) would be a static edge into
+ * the password chunk, and a static edge is exactly what stops it being a chunk: the bundler
+ * would fold it back into whatever imports `Input`. The entry re-exports it instead, where
+ * an unused export is dropped.
+ */
+export type {
+    InputProps, InputBaseProps, InputType, FieldAction,
+    BreachChecker, BreachState, BreachStatus,
+    PasswordOnlyProps, SearchOnlyProps, PlainOnlyProps
+} from "@/react/input/types";

package/src/react/input/password.tsx

@@ -0,0 +1,174 @@
+"use client";
+
+import type { BreachChecker, BreachState, PasswordStrengthClassNames } from "@/react/input/types";
+import { useEffect, useMemo, useRef, useState, type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { estimatePasswordStrength, type EstimateOptions, type PasswordStrengthReport, type PasswordScore } from "@/core/password";
+
+/**
+ * Everything only a password field needs: the estimator, the meter and the breach watcher.
+ *
+ * Its own chunk. `<Input>` imports it dynamically the moment a password field asks for
+ * `strength` or `breach`, so a form of text and email fields never downloads a word list, an
+ * entropy table or an abort controller it has no use for. Nothing here is imported by the
+ * field statically - that would fold the chunk straight back into it.
+ */
+
+const SCORE_LABELS = ["Very weak", "Weak", "Fair", "Strong", "Very strong"] as const;
+
+export interface PasswordExtrasProps {
+    /** Id the field points `aria-describedby` at. */
+    id: string;
+    value: string;
+    strength: boolean | EstimateOptions;
+    onStrengthChange?: (report: PasswordStrengthReport) => void;
+    /** Reports the score up so the ROOT can carry `data-score` for a theme to style. */
+    onScore: (score: number | null) => void;
+    breach?: BreachChecker;
+    breachDelay: number;
+    onBreachChange: (state: BreachState) => void;
+    classNames?: PasswordStrengthClassNames;
+}
+
+export function PasswordExtras({
+    id,
+    value,
+    strength,
+    onStrengthChange,
+    onScore,
+    breach,
+    breachDelay,
+    onBreachChange,
+    classNames
+}: PasswordExtrasProps): ReactNode {
+    const estimateOptions = typeof strength === "object" ? strength : undefined;
+    const userInputs = estimateOptions?.userInputs;
+    const report = useMemo(
+        () => (strength === false ? null : estimatePasswordStrength(value, { userInputs })),
+        // The array is compared by identity, so a literal would re-estimate every render.
+        [strength, value, userInputs]
+    );
+
+    const strengthListener = useRef(onStrengthChange);
+    strengthListener.current = onStrengthChange;
+    const scoreListener = useRef(onScore);
+    scoreListener.current = onScore;
+
+    useEffect(() => {
+        if (!report) return;
+        strengthListener.current?.(report);
+        scoreListener.current(report.empty ? null : report.score);
+    }, [report]);
+
+    /* -------- the breach check -------- */
+
+    const [breachState, setBreachState] = useState<BreachState>({ status: "idle", count: 0, error: null });
+    const breachListener = useRef(onBreachChange);
+    breachListener.current = onBreachChange;
+
+    useEffect(() => {
+        if (!breach || !value) {
+            setBreachState({ status: "idle", count: 0, error: null });
+            return;
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => {
+            setBreachState({ status: "checking", count: 0, error: null });
+            breach(value, { signal: controller.signal })
+                .then((result) => {
+                    if (controller.signal.aborted) return;
+                    setBreachState({ status: result.breached ? "breached" : "safe", count: result.count, error: null });
+                })
+                .catch((error: unknown) => {
+                    // An abort is this effect cleaning up after itself, not a failure.
+                    if (controller.signal.aborted) return;
+                    setBreachState({ status: "error", count: 0, error });
+                });
+        }, breachDelay);
+
+        return () => {
+            clearTimeout(timer);
+            // Cancels the request in flight, so the answer to a password that is three
+            // keystrokes old can never overwrite the answer to the current one.
+            controller.abort();
+        };
+    }, [breach, value, breachDelay]);
+
+    useEffect(() => {
+        breachListener.current(breachState);
+    }, [breachState]);
+
+    if (!report) return null;
+    return <PasswordStrength id={id} report={report} classNames={classNames} />;
+}
+
+export interface PasswordStrengthProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** The password to score. Ignored when `report` is given. */
+    value?: string;
+    /** A report you already have, e.g. from `<Input onStrengthChange>`. */
+    report?: PasswordStrengthReport;
+    userInputs?: string[];
+    /** Bars to draw. Five, so each score has one of its own. */
+    segments?: number;
+    /** Your own wording, worst first. */
+    labels?: readonly string[];
+    /** Show the top warning under the bars. On by default; it is the useful half. */
+    showWarning?: boolean;
+    /**
+     * Classes for the inner parts. The score is on the ROOT, so a segment colours itself
+     * with a group variant - `group-data-[score=0]/strength:bg-red-600` and so on.
+     */
+    classNames?: PasswordStrengthClassNames;
+}
+
+/**
+ * The bars under a password field.
+ *
+ * Structure and state only - `data-score` on the root and `data-filled` per segment are
+ * where the colours attach. The component picks no colours, because red-through-green is a
+ * palette decision and this package does not own one.
+ */
+export function PasswordStrength({
+    value = "",
+    report,
+    userInputs,
+    segments = 5,
+    labels = SCORE_LABELS,
+    showWarning = true,
+    classNames,
+    ...props
+}: PasswordStrengthProps): ReactNode {
+    const computed = useMemo(
+        () => report ?? estimatePasswordStrength(value, { userInputs }),
+        [report, value, userInputs]
+    );
+
+    const score: PasswordScore = computed.score;
+    return (
+        <div
+            {...props}
+            data-enigma-password-strength=""
+            data-score={computed.empty ? undefined : score}
+            data-empty={computed.empty ? "" : undefined}
+        >
+            <div data-enigma-password-strength-track="" aria-hidden="true" className={classNames?.track}>
+                {Array.from({ length: segments }, (unused, index) => (
+                    <span
+                        key={index}
+                        data-enigma-password-strength-segment=""
+                        className={classNames?.segment}
+                        // Score 0 still fills one bar: an empty track next to a filled
+                        // field reads as "not measured", not as "this is a bad password".
+                        data-filled={!computed.empty && index <= score ? "" : undefined}
+                    />
+                ))}
+            </div>
+            {/* Announced when the band changes, which is rarely enough not to chatter. */}
+            <p data-enigma-password-strength-label="" role="status" aria-live="polite" className={classNames?.label}>
+                {computed.empty ? "" : labels[score] ?? ""}
+            </p>
+            {showWarning && !computed.empty && computed.warnings.length > 0 && (
+                <p data-enigma-password-strength-warning="" className={classNames?.warning}>{computed.warnings[0]}</p>
+            )}
+        </div>
+    );
+}

package/src/react/input/search.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { createSearch, type SearchInstance, type SearchMatch, type SearchOptions } from "@/core/search";
+
+/**
+ * The search wiring for `<Input type="search">`: debouncing, ranking, cancellation, and the
+ * results the field reports.
+ *
+ * Its own chunk, imported the moment a search field is given something to search - so a
+ * password form never downloads a matcher, and a project that passes Fuse's constructor
+ * only pays for it on the page that has the field.
+ *
+ * The engine is attached to the field the base component rendered rather than rendering one
+ * of its own: two owners of one input is the thing that makes a wrapper feel wrong, and the
+ * field has to stay a plain `<input>` the consumer can pass any native prop to.
+ */
+
+export interface SearchExtrasProps<Item = unknown> {
+    /** The field itself. Null until it mounts, which is one render. */
+    input: HTMLInputElement | null;
+    items?: Item[];
+    keys?: SearchOptions<Item>["keys"];
+    delay?: number;
+    limit?: number;
+    fuse?: SearchOptions<Item>["fuse"];
+    fuseOptions?: SearchOptions<Item>["fuseOptions"];
+    matcher?: SearchOptions<Item>["matcher"];
+    onResults?: (matches: SearchMatch<Item>[], query: string) => void;
+    renderResults?: (matches: SearchMatch<Item>[], query: string) => ReactNode;
+}
+
+export function SearchExtras<Item>({
+    input,
+    items,
+    keys,
+    delay = 150,
+    limit,
+    fuse,
+    fuseOptions,
+    matcher,
+    onResults,
+    renderResults
+}: SearchExtrasProps<Item>): ReactNode {
+    const [results, setResults] = useState<SearchMatch<Item>[]>([]);
+    const [query, setQuery] = useState("");
+
+    const listener = useRef(onResults);
+    listener.current = onResults;
+
+    // Built once. The engine indexes on construction, so rebuilding it per render would
+    // re-index the whole list on every keystroke - the defect this exists to avoid.
+    const instance = useMemo<SearchInstance<Item>>(() => createSearch<Item>({
+        items,
+        keys,
+        fuse,
+        fuseOptions,
+        matcher,
+        debounce: delay,
+        limit,
+        onResults: (next, nextQuery) => {
+            setResults(next);
+            setQuery(nextQuery);
+            listener.current?.(next, nextQuery);
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }), []);
+
+    useEffect(() => () => instance.destroy(), [instance]);
+
+    // New data must re-index and re-run the visible query, or the list keeps showing
+    // matches against items that are gone.
+    useEffect(() => { instance.setItems(items ?? []); }, [instance, items]);
+    useEffect(() => { instance.update({ keys, fuse, fuseOptions, matcher, debounce: delay, limit }); }, [instance, keys, fuse, fuseOptions, matcher, delay, limit]);
+
+    useEffect(() => {
+        if (!input) return;
+        return instance.attach(input);
+    }, [instance, input]);
+
+    return renderResults ? <>{renderResults(results, query)}</> : null;
+}