@enigmax/primitives 0.16.0 → 0.18.0

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;
+}

package/src/react/input/types.ts

@@ -0,0 +1,146 @@
+/**
+ * The prop shapes for `<Input>`, split from the component so the per-type chunks can import
+ * them without importing the component - and so every type in here is erased at build,
+ * which is what keeps a `type="text"` field from pulling the password estimator or a search
+ * engine into the bundle.
+ *
+ * The API is ONE component keyed on `type`, the way HTML itself is: `type` is an attribute
+ * of one element, not a different element. Radix splits Select, Checkbox and Slider into
+ * their own primitives because those are composed widgets rather than an `<input>` - that
+ * split is about the DOM, not about the props. What varies here is which props EXIST, and
+ * that is a discriminated union: `strength` on a text field and `items` on a password field
+ * are compile errors rather than props that quietly do nothing.
+ */
+
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { SearchMatch, FuseConstructor, SearchOptions } from "@/core/search";
+import type { GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport } from "@/core/password";
+
+/** An extra button inside the field. The built-ins are the same shape. */
+export interface FieldAction {
+    /** Stable id. Lands on `data-enigma-input-action`, and replaces a built-in of the same name. */
+    name: string;
+    /** Accessible name. Becomes `aria-label` and `title`. */
+    label: string;
+    icon: ReactNode;
+    onSelect: () => void;
+    /** Renders `aria-pressed`. Omit for actions that are not toggles. */
+    pressed?: boolean;
+    /** Default true. A false action is not rendered at all. */
+    visible?: boolean;
+}
+
+export type BreachStatus = "idle" | "checking" | "safe" | "breached" | "error";
+
+export interface BreachState {
+    status: BreachStatus;
+    /** How many breaches the password appears in. 0 unless `status` is "breached". */
+    count: number;
+    /** Whatever the checker threw. The form decides whether that is worth showing. */
+    error: unknown;
+}
+
+export type BreachChecker = (password: string, options: { signal: AbortSignal; }) => Promise<{ breached: boolean; count: number; }>;
+
+/** Every `type` a single `<input>` element takes, plus the two this component teaches. */
+export type InputType =
+    | "text" | "email" | "password" | "search" | "tel" | "url" | "number"
+    | "date" | "datetime-local" | "month" | "week" | "time"
+    | "color" | "file" | "range" | "hidden" | "checkbox" | "radio";
+
+export interface PasswordStrengthClassNames {
+    track?: string;
+    segment?: string;
+    label?: string;
+    warning?: string;
+}
+
+/** What every type has, whatever it is. */
+export interface InputBaseProps extends Omit<ComponentPropsWithoutRef<"input">, "children" | "type"> {
+    /** The reveal toggle. Defaults to on for `type="password"` and off for everything else. */
+    reveal?: boolean;
+    revealLabels?: { show?: string; hide?: string; };
+    /** Extra buttons, or a replacement for a built-in by name. */
+    actions?: FieldAction[];
+    /** Which end the buttons sit at. Position them yourself; this only orders the markup. */
+    position?: "start" | "end";
+    /** Props for the element wrapping the field, its buttons and anything under them. */
+    wrapperProps?: ComponentPropsWithoutRef<"div">;
+    /** Props for the row holding the field and its buttons - this is what you position. */
+    fieldProps?: ComponentPropsWithoutRef<"div">;
+    /**
+     * Classes for the parts you cannot reach with a ref, which is what Tailwind needs.
+     * `className` still goes to the `<input>` itself, where you would expect it.
+     */
+    classNames?: {
+        actions?: string;
+        action?: string;
+        strength?: PasswordStrengthClassNames;
+        results?: string;
+        result?: string;
+    };
+    /** Rendered inside the wrapper, after everything the type adds. Your error goes here. */
+    children?: ReactNode;
+}
+
+/** The half only a password field has. */
+export interface PasswordOnlyProps {
+    type: "password";
+    /** Offer to generate a password. `true` for the defaults, or the generator's options. */
+    generate?: boolean | GeneratePasswordOptions;
+    generateLabel?: string;
+    /** Show what was generated. On by default - a password nobody can read is not usable. */
+    revealOnGenerate?: boolean;
+    /**
+     * Also copy it to the clipboard. OFF by default and worth leaving off: the clipboard is
+     * shared with every other app on the machine and is not cleared.
+     */
+    copyOnGenerate?: boolean;
+    onGenerate?: (password: string) => void;
+    /** Score the password as it is typed, and render the meter under the field. */
+    strength?: boolean | EstimateOptions;
+    onStrengthChange?: (report: PasswordStrengthReport) => void;
+    /**
+     * Check the password against a breach corpus - pass `checkPasswordBreach` from
+     * @enigmax/utils, or your own. It is a prop rather than a built-in because it makes a
+     * network request, and that is not a decision a field should take on its own.
+     */
+    breach?: BreachChecker;
+    /** Quiet time before a check fires, in ms. Default 500. */
+    breachDelay?: number;
+    onBreachChange?: (state: BreachState) => void;
+}
+
+/** The half only a search field has. The palette is its own component, not a prop. */
+export interface SearchOnlyProps<Item = unknown> {
+    type: "search";
+    /** What to search. Leave it out for a field that only reports the query. */
+    items?: Item[];
+    /** Which fields to read. `["title", "body"]`, or leave it out for every string field. */
+    keys?: SearchOptions<Item>["keys"];
+    /** Quiet time before a search runs, in ms. Default 150. */
+    delay?: number;
+    /** Cap the result list. Applies to the empty query too. */
+    limit?: number;
+    /** Fuse.js's constructor, for fuzzy matching. Without it, a substring matcher is used. */
+    fuse?: FuseConstructor;
+    fuseOptions?: SearchOptions<Item>["fuseOptions"];
+    /** Replaces the engine outright, and wins over `fuse`. */
+    matcher?: SearchOptions<Item>["matcher"];
+    onResults?: (matches: SearchMatch<Item>[], query: string) => void;
+    /** Render the results under the field. Without it, the field only reports them. */
+    renderResults?: (matches: SearchMatch<Item>[], query: string) => ReactNode;
+    /** Clear button. On by default for a search field, because the platform's own is not. */
+    clearable?: boolean;
+    clearLabel?: string;
+}
+
+/** Everything else: one `<input>`, its native props, and no extras to bundle. */
+export interface PlainOnlyProps {
+    type?: Exclude<InputType, "password" | "search">;
+}
+
+export type InputProps<Item = unknown> = InputBaseProps & (PasswordOnlyProps | SearchOnlyProps<Item> | PlainOnlyProps);
+
+/** Everything the implementation reads, after the union has done its job at the call site. */
+export type AnyInputProps<Item = unknown> = InputBaseProps & Partial<Omit<PasswordOnlyProps, "type">> & Partial<Omit<SearchOnlyProps<Item>, "type">> & { type?: InputType; };

package/src/react/input/write-value.ts

@@ -0,0 +1,18 @@
+/**
+ * Write a value the way a keystroke would.
+ *
+ * Assigning `input.value` directly is invisible to React: it tracks the last value it
+ * rendered and skips the change event when the DOM disagrees with it. Going through the
+ * prototype's setter and dispatching a bubbling `input` event makes a generated password or
+ * a cleared search behave exactly like typing - which is what makes it work with a
+ * controlled field, an uncontrolled one, and a form library, without knowing which it is in.
+ *
+ * Its own module because both the field and the per-type chunks write values, and a helper
+ * imported from the field would tie a chunk back to the module that lazily loads it.
+ */
+export function writeValue(input: HTMLInputElement, next: string): void {
+    const setter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, "value")?.set;
+    if (setter) setter.call(input, next);
+    else input.value = next;
+    input.dispatchEvent(new Event("input", { bubbles: true }));
+}

package/src/react/palette/context.ts

@@ -0,0 +1,60 @@
+"use client";
+
+import type { SearchMatch } from "@/core/search";
+import { createContext, useContext } from "react";
+import type { RecentEntry } from "@/core/palette";
+
+/** One line in the palette, whatever it came from. */
+export interface PaletteRow<Item> {
+    /** Stable within a render. Used for React keys and for `aria-activedescendant`. */
+    id: string;
+    /** Which group it appears under. */
+    group: string;
+    /** `item` for a result, `recent` for a memory, `action` for a row the app declared. */
+    kind: "item" | "recent" | "action";
+    item?: Item;
+    recent?: RecentEntry;
+    /** Set for a result that came from the engine, so a renderer can show the score. */
+    match?: SearchMatch<Item>;
+    /** What running this row does. The palette closes afterwards unless this returns false. */
+    onSelect?: () => void | boolean;
+    label: string;
+    description?: string;
+}
+
+export interface PaletteContextValue<Item = unknown> {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+    query: string;
+    setQuery: (query: string) => void;
+    rows: PaletteRow<Item>[];
+    active: number;
+    setActive: (index: number) => void;
+    /** Run a row: its own action, or the palette's `onSelect`, then remember it. */
+    select: (row: PaletteRow<Item> | undefined) => void;
+    /** Wipe the remembered searches. */
+    clearRecents: () => void;
+    forgetRecent: (entry: RecentEntry) => void;
+    /** True while the engine is loading or an async source is in flight. */
+    busy: boolean;
+    /** ids the parts need to point at each other. */
+    ids: { field: string; list: string; title: string; };
+    /** `Ctrl K` or `⌘ K`, whichever this platform uses. */
+    shortcutLabel: string;
+    triggerRef: { current: HTMLElement | null; };
+    fieldRef: { current: HTMLInputElement | null; };
+    rowId: (row: PaletteRow<Item>) => string;
+}
+
+/**
+ * Null rather than a default value: a part rendered outside its Root is a mistake with a
+ * clear fix, and a silent default would leave it half-working - a field that types into
+ * nothing, an item that never highlights.
+ */
+export const PaletteContext = createContext<PaletteContextValue<never> | null>(null);
+
+export function usePaletteContext<Item = unknown>(part: string): PaletteContextValue<Item> {
+    const value = useContext(PaletteContext);
+    if (!value) throw new Error(`<${part}> must be rendered inside <SearchPalette.Root>.`);
+    return value as unknown as PaletteContextValue<Item>;
+}

package/src/react/palette/index.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import type { ReactNode } from "react";
+import type { PaletteRow } from "@/react/palette/context";
+import {
+    PaletteRoot, PaletteTrigger, PaletteContent, PaletteField, PaletteList, PaletteItem, PaletteFooter,
+    type PaletteRootProps, type PaletteListProps
+} from "@/react/palette/root";
+
+export interface SearchPaletteProps<Item> extends PaletteRootProps<Item> {
+    placeholder?: string;
+    /** The trigger's own content. Pass null for a palette that only opens on the shortcut. */
+    trigger?: ReactNode | null;
+    /** Render one row, same signature as `SearchPalette.List`. */
+    renderItem?: PaletteListProps<Item>["children"];
+    empty?: ReactNode;
+    footer?: ReactNode;
+}
+
+/**
+ * The palette, assembled.
+ *
+ * ```tsx
+ * <SearchPalette items={docs} keys={["title", "body"]} onSelect={(doc) => go(doc.href)} />
+ * ```
+ *
+ * Everything it renders is a part you can render yourself instead - see `SearchPalette.Root`
+ * for the anatomy. This is the composition that covers the common case, not a different
+ * component: it is those parts, in the order they belong in.
+ */
+export function SearchPalette<Item>({
+    placeholder = "Search",
+    trigger,
+    renderItem,
+    empty,
+    footer,
+    children,
+    ...root
+}: SearchPaletteProps<Item>): ReactNode {
+    return (
+        <PaletteRoot<Item> {...root}>
+            {trigger !== null && <PaletteTrigger>{trigger}</PaletteTrigger>}
+            <PaletteContent>
+                <PaletteField placeholder={placeholder} aria-label={placeholder} />
+                <PaletteList<Item> empty={empty}>{renderItem}</PaletteList>
+                {footer === null ? null : <PaletteFooter>{footer}</PaletteFooter>}
+            </PaletteContent>
+            {children}
+        </PaletteRoot>
+    );
+}
+
+SearchPalette.Root = PaletteRoot;
+SearchPalette.Trigger = PaletteTrigger;
+SearchPalette.Content = PaletteContent;
+SearchPalette.Field = PaletteField;
+SearchPalette.List = PaletteList;
+SearchPalette.Item = PaletteItem;
+SearchPalette.Footer = PaletteFooter;
+
+export {
+    PaletteRoot, PaletteTrigger, PaletteContent, PaletteField, PaletteList, PaletteItem, PaletteFooter,
+    type PaletteRootProps, type PaletteListProps, type PaletteSection
+} from "@/react/palette/root";
+export { usePaletteContext, type PaletteRow, type PaletteContextValue } from "@/react/palette/context";
+export type { PaletteRow as SearchPaletteRow };