@enigmax/primitives 0.17.0 → 0.18.0

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