@enigmax/primitives 0.16.0 → 0.18.0

package/src/index.ts

@@ -27,3 +27,21 @@ export {
     type RelativeTimePrecision,
     type RelativeTimeStyle
 } from "@/core/relative-time";
+export {
+    flagSrc,
+    flagView,
+    flagAttributes,
+    flagName,
+    normalizeFlagCode,
+    configureFlags,
+    flagConfig,
+    resetFlagConfig,
+    FLAG_RATIO,
+    FLAG_CDN,
+    type FlagOptions,
+    type FlagConfig,
+    type FlagView,
+    type FlagShape,
+    type FlagFormat,
+    type FlagSource
+} from "@/core/flags";

package/src/react/button.tsx

@@ -1,9 +1,10 @@
 "use client";
 
+import { Slot } from "@/react/slot";
 import { useButton } from "@/react/use-button";
 import { getLinkComponent } from "@/react/link";
 import type { ButtonOptions, ButtonState } from "@/core/button";
-import { createElement, forwardRef, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from "react";
+import { createElement, forwardRef, isValidElement, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from "react";
 
 /**
  * `<Button>` - the component, for the ninety percent.
@@ -51,6 +52,49 @@ export interface ButtonProps extends ButtonOptions, Omit<ComponentPropsWithoutRe
     pending?: ReactNode;
     /** `type` on a real button. Ignored on a link, which has none. */
     type?: "button" | "submit" | "reset";
+    /**
+     * Show the shortcut as a key badge after the label, the way Stripe writes
+     * "Create invoice n".
+     *
+     * `"auto"` (the default) shows it when there is a shortcut AND the label renders text:
+     * beside a lone glyph on an icon-only button the badge is noise, and it would double the
+     * width of the smallest control on the screen. `true` and `false` decide it outright.
+     */
+    shortcutHint?: boolean | "auto";
+    /** Render the badge yourself. Return null to drop it for one button. */
+    renderShortcut?: (key: string) => ReactNode;
+    /**
+     * Put the behaviour on YOUR element instead of ours - a `motion.button`, your design
+     * system's button, a router Link, anything.
+     *
+     * ```tsx
+     * <Button asChild cooldown={30_000} onPress={resend}>
+     *     <motion.button whileTap={{ scale: 0.98 }}>Resend</motion.button>
+     * </Button>
+     * ```
+     *
+     * The child owns its own markup, so the shortcut badge is not injected - the child is
+     * rendered exactly as written. Read `state.shortcut` from `useButton` to place your own.
+     */
+    asChild?: boolean;
+}
+
+/**
+ * Whether a label renders any TEXT.
+ *
+ * Walked rather than assumed: `<Button shortcut="s"><Icon /></Button>` and
+ * `<Button shortcut="s"><Icon /> Save</Button>` differ only in a string buried in the tree,
+ * and that string is the whole difference between a hint and a decoration. An element whose
+ * text arrives from somewhere this cannot see reports false, so `auto` errs towards the
+ * quieter button; `shortcutHint` overrides it in one word.
+ */
+function hasText(node: ReactNode): boolean {
+    if (node === null || node === undefined || typeof node === "boolean") return false;
+    if (typeof node === "string") return node.trim().length > 0;
+    if (typeof node === "number") return true;
+    if (Array.isArray(node)) return node.some(hasText);
+    if (isValidElement(node)) return hasText((node.props as { children?: ReactNode; }).children);
+    return false;
 }
 
 export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
@@ -66,6 +110,9 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
     onClick,
     onChange,
     type = "button",
+    shortcutHint = "auto",
+    renderShortcut,
+    asChild = false,
     ...rest
 }, ref) {
     const button = useButton({ href, disabled, loading, cooldown, shortcut, onPress: onPress ?? onClick, onChange });
@@ -75,17 +122,36 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
     // to setLinkComponent - and a plain <a> when nothing was. The package cannot import a
     // router itself, so registering one is what turns every href into a client navigation
     // without a word at the call site.
-    const Tag: ElementType = as ?? (state.element === "a" ? getLinkComponent() : "button");
+    const Tag: ElementType = asChild ? Slot : as ?? (state.element === "a" ? getLinkComponent() : "button");
 
     // `type="button"` is the default on purpose. A bare <button> inside a form submits it,
-    // so an action button that forgot it posts the form instead of doing its job.
+    // so an action button that forgot it posts the form instead of doing its job. Never
+    // injected through a slot: the child may be an anchor or a div, where `type` is either
+    // invalid or means something else entirely.
     const native = Tag === "button" ? { type } : {};
 
     const label = typeof children === "function" ? children(state) : children;
+    const content = state.loading && pending !== undefined ? pending : label;
+
+    // Not while it is working: the label has already been replaced by whatever `pending`
+    // says, and a key that does nothing right now is not a hint.
+    // Never through a slot: it takes exactly one child, and a second one would throw.
+    const showHint = !asChild && Boolean(state.shortcut) && !state.loading &&
+        (shortcutHint === "auto" ? hasText(content) : shortcutHint);
+    const hint = showHint && state.shortcut
+        ? renderShortcut?.(state.shortcut) ?? createElement(
+            "kbd",
+            // Hidden from the accessible name - the button already carries
+            // `aria-keyshortcuts`, and "Save n" is not what anyone wants read out.
+            { "data-enigma-button-key": "", "aria-hidden": true },
+            state.shortcut
+        )
+        : null;
 
     return createElement(
         Tag,
         { ref, ...button.props, ...native, ...rest },
-        state.loading && pending !== undefined ? pending : label
+        content,
+        hint
     );
 });

package/src/react/flag.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+import { type ImgHTMLAttributes, type ReactNode } from "react";
+import { flagView, type FlagOptions, type FlagShape, type FlagFormat, type FlagSource } from "@/core/flags";
+
+export interface FlagProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "width" | "height"> {
+    /** `es`, `ES`, `en-GB`, `gb-eng`, or the emoji flag you are replacing. */
+    code: string | null | undefined;
+    /**
+     * Your own accessible name. Left out, the country's own name is used, in the reader's
+     * language - so a flag standing on its own is never a silent image.
+     */
+    label?: string;
+    /**
+     * Beside a country name that is already on screen the flag is decoration, and repeating
+     * the name only makes a screen reader say it twice.
+     */
+    decorative?: boolean;
+    /** Language the automatic name is written in. Follows the document's `lang` otherwise. */
+    locale?: string;
+    shape?: FlagShape;
+    format?: FlagFormat;
+    source?: FlagSource;
+    basePath?: string;
+    /** Rendered height in px. The width follows the shape. Default 16. */
+    size?: number;
+    /** Rendered when the code resolves to nothing. Nothing, by default. */
+    fallback?: ReactNode;
+}
+
+/**
+ * `<Flag code="es" />` - a country flag as an image, at the size you asked for, from the
+ * source the app configured once.
+ *
+ * The defaults come from `configureFlags`, so moving the whole application from the CDN to
+ * a downloaded set is one line at startup and no change at any call site.
+ */
+export function Flag({ code, label, decorative = false, locale, shape, format, source, basePath, size, fallback = null, ...rest }: FlagProps): ReactNode {
+    const options: FlagOptions = { shape, format, source, basePath, size, locale };
+    // An explicit `undefined` prop must not beat the configured default, so the unset ones
+    // are dropped rather than spread over the config.
+    for (const key of Object.keys(options) as (keyof FlagOptions)[]) {
+        if (options[key] === undefined) delete options[key];
+    }
+
+    const view = flagView(code, options);
+    if (!view) return fallback;
+
+    // Automatic unless told otherwise: the country's own name, in the reader's language.
+    const name = decorative ? "" : label?.trim() || view.name || "";
+    return (
+        <img
+            src={view.src}
+            alt={name}
+            width={view.width}
+            height={view.height}
+            loading="lazy"
+            decoding="async"
+            aria-hidden={name ? undefined : true}
+            // The name comes from the reader's own runtime, so a server render and its
+            // hydration can legitimately disagree on the language it is written in. Same
+            // escape hatch, and same reason, as the relative timestamp.
+            suppressHydrationWarning
+            data-enigma-flag=""
+            data-flag-code={view.code}
+            data-flag-shape={view.shape}
+            {...rest}
+        />
+    );
+}

package/src/react/index.ts

@@ -10,16 +10,23 @@ export { useButton, type UseButtonResult } from "@/react/use-button";
 export { Button, type ButtonProps } from "@/react/button";
 export { setLinkComponent, getLinkComponent } from "@/react/link";
 export { type ButtonOptions, type ButtonState } from "@/core/button";
+export { Input } from "@/react/input";
 export {
-    Input,
-    PasswordStrength,
     type InputProps,
-    type PasswordStrengthProps,
+    type InputBaseProps,
+    type InputType,
     type FieldAction,
     type BreachChecker,
     type BreachState,
-    type BreachStatus
-} from "@/react/input";
+    type BreachStatus,
+    type PasswordOnlyProps,
+    type SearchOnlyProps,
+    type PlainOnlyProps
+} from "@/react/input/types";
+// The meter as a standalone component, for a form that renders it somewhere else. Re-exported
+// from the chunk rather than through `Input`, so importing only `Input` leaves it behind.
+export { PasswordStrength, type PasswordStrengthProps } from "@/react/input/password";
+export { Slot, mergeSlotProps, type SlotProps } from "@/react/slot";
 export {
     generatePassword,
     estimatePasswordStrength,
@@ -33,3 +40,43 @@ export { Toaster, type ToasterProps, type ToastPosition, type ToastControls } fr
 export { useNetworkState } from "@/react/use-network-state";
 export { type NetworkState } from "@/core/network";
 export { RelativeTime, type RelativeTimeProps } from "@/react/relative-time";
+export { Flag, type FlagProps } from "@/react/flag";
+export {
+    flagSrc,
+    flagView,
+    flagAttributes,
+    flagName,
+    normalizeFlagCode,
+    configureFlags,
+    type FlagOptions,
+    type FlagShape,
+    type FlagFormat,
+    type FlagSource
+} from "@/core/flags";
+export {
+    SearchPalette,
+    PaletteRoot,
+    PaletteTrigger,
+    PaletteContent,
+    PaletteField,
+    PaletteList,
+    PaletteItem,
+    PaletteFooter,
+    usePaletteContext,
+    type SearchPaletteProps,
+    type PaletteRootProps,
+    type PaletteListProps,
+    type PaletteSection,
+    type PaletteRow,
+    type PaletteContextValue
+} from "@/react/palette";
+export {
+    createRecentStore,
+    recentKey,
+    groupRows,
+    moveActive,
+    shortcutLabel,
+    isPaletteShortcut,
+    type RecentEntry,
+    type RecentStore
+} from "@/core/palette";

package/src/react/input/icon.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+/**
+ * The built-in glyphs, drawn from the shared path data.
+ *
+ * Stroked with `currentColor` at 1em, so an icon inherits the field's text colour and size
+ * and needs no styling of its own. Replacing one is a `FieldAction` with the same `name`.
+ */
+const ICON_PROPS = {
+    viewBox: "0 0 24 24", width: "1em", height: "1em", fill: "none",
+    stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round",
+    "aria-hidden": true
+} as const;
+
+export function Icon({ paths }: { paths: readonly string[]; }): ReactNode {
+    return <svg {...ICON_PROPS}>{paths.map((path) => <path key={path} d={path} />)}</svg>;
+}

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";