@enigmax/primitives 0.17.0 → 0.18.0

package/dist/index-D-ARvWpQ.d.ts

@@ -0,0 +1,306 @@
+import { ComponentPropsWithoutRef, ReactNode } from 'react';
+import { b as SearchMatch, c as SearchOptions } from './search-CsO3L1Lw.js';
+
+/**
+ * The parts of a command palette that are not rendering: what was searched before, how a
+ * flat list becomes groups, and where the highlight goes when a key is pressed.
+ *
+ * Pure functions and one storage wrapper, so all three are testable without a browser and
+ * reusable by a renderer that is not React. The palette's React parts are a thin layer over
+ * this file.
+ */
+interface RecentEntry {
+    /** What was typed. The palette puts it back in the field when the row is chosen. */
+    term: string;
+    /** A result that was opened, rather than a query that was run. */
+    label?: string;
+    /** Where that result was. */
+    href?: string;
+    /** Which scope it was searched in, when the palette has scopes. */
+    scope?: string | null;
+    /** Epoch ms. Used only for ordering. */
+    at: number;
+}
+interface RecentStoreOptions {
+    /** Storage key. One per palette, so two palettes on a site do not share a history. */
+    key?: string;
+    /** How many entries to keep. */
+    limit?: number;
+    /** `local` outlives the tab, `session` does not. Default local. */
+    storage?: "local" | "session";
+}
+interface RecentStore {
+    list(): RecentEntry[];
+    remember(entry: Omit<RecentEntry, "at"> & {
+        at?: number;
+    }): RecentEntry[];
+    forget(entry: RecentEntry): RecentEntry[];
+    clear(): void;
+}
+/** Two entries are the same memory when they point at the same thing in the same scope. */
+declare function recentKey(entry: Pick<RecentEntry, "term" | "href" | "scope">): string;
+/**
+ * What was searched before, in this browser.
+ *
+ * Every read and write is guarded: storage throws in a private window, when the quota is
+ * full, and whenever a page is opened from a file URL - and a palette that cannot remember
+ * is still a working palette, so none of that is allowed to reach the renderer. Reads also
+ * survive a corrupted value, because the key is shared with whatever else the site stores.
+ */
+declare function createRecentStore(options?: RecentStoreOptions): RecentStore;
+/** A row after grouping: its own index in the FLAT list is what the keyboard moves through. */
+interface PositionedRow<Row> {
+    row: Row;
+    position: number;
+}
+interface RowGroup<Row> {
+    label: string;
+    rows: PositionedRow<Row>[];
+}
+/**
+ * Group a flat list while keeping every row's flat position.
+ *
+ * The flat position is the whole point: the highlight moves through ONE sequence, so a
+ * group boundary is invisible to the arrow keys - and a renderer that grouped rows into
+ * separate arrays would have to reconstruct that sequence, which is where an off-by-one
+ * makes Enter open the row above the highlighted one. Groups keep first-seen order.
+ */
+declare function groupRows<Row>(rows: Row[], labelOf: (row: Row) => string): RowGroup<Row>[];
+/** Keys the list responds to. Anything else belongs to the field. */
+type PaletteKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" | "PageUp";
+/**
+ * Where the highlight lands.
+ *
+ * It WRAPS, because a palette is a short list and the row after the last one is the first:
+ * clamping instead leaves the arrow key doing nothing at the end, which reads as the panel
+ * having frozen. An empty list stays at 0 rather than going negative.
+ */
+declare function moveActive(current: number, length: number, key: PaletteKey, page?: number): number;
+/**
+ * The shortcut label for this platform: `Cmd K` on a Mac, `Ctrl K` everywhere else.
+ *
+ * Read from the platform rather than hardcoded, because the wrong modifier in the trigger
+ * is a hint that actively misleads - and it is the first thing anyone tries.
+ */
+declare function shortcutLabel(key?: string): string;
+/** Whether an event is the palette's open shortcut. Meta on a Mac, Control elsewhere. */
+declare function isPaletteShortcut(event: KeyboardEvent, key?: string): boolean;
+
+/** One line in the palette, whatever it came from. */
+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;
+}
+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;
+}
+declare function usePaletteContext<Item = unknown>(part: string): PaletteContextValue<Item>;
+
+/**
+ * The command palette: the panel that opens on Ctrl/Cmd+K, searches as you type, remembers
+ * what was searched before, and is driven entirely from the keyboard.
+ *
+ * It is a DIALOG, which is why it is its own component rather than a prop on `<Input>`: a
+ * palette is a trigger, an overlay, a focus trap, a listbox and a footer, and the thing that
+ * makes those usable together is composition. Radix draws the line in the same place, and
+ * for the same reason - one `<input>` is a component, a widget made of parts is an anatomy:
+ *
+ * ```tsx
+ * <SearchPalette.Root items={docs} keys={["title"]} onSelect={open}>
+ *     <SearchPalette.Trigger />
+ *     <SearchPalette.Content>
+ *         <SearchPalette.Field placeholder="Search the docs" />
+ *         <SearchPalette.List />
+ *         <SearchPalette.Footer />
+ *     </SearchPalette.Content>
+ * </SearchPalette.Root>
+ * ```
+ *
+ * `<SearchPalette>` on its own renders exactly that, for the case that needs no arguing
+ * with. Every part takes `asChild`, so any of them can be your own element instead.
+ *
+ * The keyboard sequence is ONE flat list across every group - a group boundary is invisible
+ * to the arrow keys - and the highlight wraps, because in a short list the row after the
+ * last one is the first, and a key that does nothing at the end reads as a frozen panel.
+ */
+interface PaletteSection<Item> {
+    label: string;
+    items: Item[];
+    /** Shown whatever the query, e.g. a list of commands. Off by default. */
+    always?: boolean;
+}
+interface PaletteRootProps<Item> {
+    /** What to search. */
+    items?: Item[];
+    /** Fields to read. Dotted paths work. */
+    keys?: SearchOptions<Item>["keys"];
+    /** Fuse.js's constructor, for fuzzy matching. Without it, a substring matcher runs. */
+    fuse?: SearchOptions<Item>["fuse"];
+    fuseOptions?: SearchOptions<Item>["fuseOptions"];
+    /** Replaces the engine outright. */
+    matcher?: SearchOptions<Item>["matcher"];
+    /** ms after the last keystroke. Default 120: a palette should feel immediate. */
+    delay?: number;
+    limit?: number;
+    /** Which group a result belongs under. One group when this is left out. */
+    groupBy?: (item: Item) => string;
+    /** The row's text. Falls back to the first string field. */
+    labelOf?: (item: Item) => string;
+    descriptionOf?: (item: Item) => string | undefined;
+    /** Rows the app always offers - commands, shortcuts, "create new". */
+    sections?: PaletteSection<Item>[];
+    /** What running a row does. Closing afterwards is the default; return false to stay. */
+    onSelect?: (item: Item) => void | boolean;
+    /** Remember what was searched, in this browser. On by default. */
+    recents?: boolean;
+    recentsKey?: string;
+    recentsLimit?: number;
+    /** The key that opens it, with Ctrl or Cmd. `null` binds nothing. Default "k". */
+    shortcut?: string | null;
+    /** Controlled open state. Leave both out for an uncontrolled palette. */
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    defaultOpen?: boolean;
+    /** Wording for the empty group heading of ungrouped results. Default "Results". */
+    resultsLabel?: string;
+    recentsLabel?: string;
+    children?: ReactNode;
+}
+declare function PaletteRoot<Item>({ items, keys, fuse, fuseOptions, matcher, delay, limit, groupBy, labelOf, descriptionOf, sections, onSelect, recents, recentsKey, recentsLimit, shortcut, open: openProp, onOpenChange, defaultOpen, resultsLabel, recentsLabel, children }: PaletteRootProps<Item>): ReactNode;
+interface PaletteTriggerProps extends ComponentPropsWithoutRef<"button"> {
+    asChild?: boolean;
+}
+/** Opens the palette. Carries the shortcut in `aria-keyshortcuts`, so it is announced. */
+declare function PaletteTrigger({ asChild, children, onClick, ...props }: PaletteTriggerProps): ReactNode;
+interface PaletteContentProps extends ComponentPropsWithoutRef<"div"> {
+    /** Accessible name for the dialog. Rendered for screen readers only. */
+    title?: string;
+    /** Render into `document.body`. On by default: a palette inside a clipped or
+     *  transformed ancestor is a panel nobody can see. */
+    portal?: boolean;
+    /** Rendered behind the panel. Pass null for no overlay of ours. */
+    overlayProps?: ComponentPropsWithoutRef<"div"> | null;
+}
+/**
+ * The panel: overlay, focus trap, Escape, scroll lock, and focus handed back to the trigger.
+ *
+ * Mounted only while open, so nothing of the palette is in the document (or in the tab
+ * order) the rest of the time.
+ */
+declare function PaletteContent({ title, portal, overlayProps, children, ...props }: PaletteContentProps): ReactNode;
+interface PaletteFieldProps extends Omit<ComponentPropsWithoutRef<"input">, "value" | "onChange"> {
+    asChild?: boolean;
+}
+/**
+ * The query field.
+ *
+ * A `combobox` that keeps the caret while the arrows move a highlight somewhere else -
+ * which is exactly what `aria-activedescendant` is for. Without it a screen reader hears
+ * nothing move, because focus never leaves the field.
+ */
+declare function PaletteField({ asChild, onKeyDown, ...props }: PaletteFieldProps): ReactNode;
+interface PaletteListProps<Item> extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** Render one row. The default prints its label, which is enough to be usable. */
+    children?: (row: PaletteRow<Item>, state: {
+        active: boolean;
+        index: number;
+    }) => ReactNode;
+    /** Rendered when there is nothing to show. */
+    empty?: ReactNode;
+    /** The group heading. Pass null for a flat list with no headings. */
+    heading?: ((label: string) => ReactNode) | null;
+}
+/** The results, grouped, with one flat keyboard sequence running through them. */
+declare function PaletteList<Item>({ children, empty, heading, ...props }: PaletteListProps<Item>): ReactNode;
+interface PaletteItemProps<Item> extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    row: PaletteRow<Item>;
+    index: number;
+    children?: ReactNode;
+}
+/**
+ * One row.
+ *
+ * The pointer MOVES the highlight rather than running a second one of its own: two
+ * highlights on screen is the thing that makes a palette feel unpredictable, because Enter
+ * then opens the row the mouse is not on.
+ */
+declare function PaletteItem<Item>({ row, index, children, ...props }: PaletteItemProps<Item>): ReactNode;
+interface PaletteFooterProps extends ComponentPropsWithoutRef<"div"> {
+    /** Replace the hints. The default names the three keys that actually matter. */
+    hints?: ReactNode;
+}
+/** The strip along the bottom that says which keys do what. */
+declare function PaletteFooter({ hints, children, ...props }: PaletteFooterProps): ReactNode;
+
+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.
+ */
+declare function SearchPalette<Item>({ placeholder, trigger, renderItem, empty, footer, children, ...root }: SearchPaletteProps<Item>): ReactNode;
+declare namespace SearchPalette {
+    var Root: typeof PaletteRoot;
+    var Trigger: typeof PaletteTrigger;
+    var Content: typeof PaletteContent;
+    var Field: typeof PaletteField;
+    var List: typeof PaletteList;
+    var Item: typeof PaletteItem;
+    var Footer: typeof PaletteFooter;
+}
+
+export { PaletteContent as P, type RecentEntry as R, SearchPalette as S, type PaletteContextValue as a, PaletteField as b, PaletteFooter as c, PaletteItem as d, PaletteList as e, type PaletteListProps as f, PaletteRoot as g, type PaletteRootProps as h, type PaletteRow as i, type PaletteSection as j, PaletteTrigger as k, type RecentStore as l, type SearchPaletteProps as m, createRecentStore as n, groupRows as o, isPaletteShortcut as p, moveActive as q, recentKey as r, shortcutLabel as s, usePaletteContext as u };

package/dist/index-DNXPtY9X.d.ts

@@ -0,0 +1,144 @@
+import { ReactNode, ComponentPropsWithoutRef } from 'react';
+import { c as SearchOptions, F as FuseConstructor, b as SearchMatch } from './search-CsO3L1Lw.js';
+import { G as GeneratePasswordOptions, E as EstimateOptions, b as PasswordStrengthReport } from './password-C8lG4Zm9.js';
+
+/**
+ * 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.
+ */
+
+/** An extra button inside the field. The built-ins are the same shape. */
+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;
+}
+type BreachStatus = "idle" | "checking" | "safe" | "breached" | "error";
+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;
+}
+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. */
+type InputType = "text" | "email" | "password" | "search" | "tel" | "url" | "number" | "date" | "datetime-local" | "month" | "week" | "time" | "color" | "file" | "range" | "hidden" | "checkbox" | "radio";
+interface PasswordStrengthClassNames {
+    track?: string;
+    segment?: string;
+    label?: string;
+    warning?: string;
+}
+/** What every type has, whatever it is. */
+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. */
+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. */
+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. */
+interface PlainOnlyProps {
+    type?: Exclude<InputType, "password" | "search">;
+}
+type InputProps<Item = unknown> = InputBaseProps & (PasswordOnlyProps | SearchOnlyProps<Item> | PlainOnlyProps);
+
+declare const Input: <Item = unknown>(props: InputProps<Item> & {
+    ref?: React.Ref<HTMLInputElement>;
+}) => ReactNode;
+
+export { type BreachChecker as B, type FieldAction as F, Input as I, type PasswordOnlyProps as P, type SearchOnlyProps as S, type BreachState as a, type BreachStatus as b, type InputBaseProps as c, type InputProps as d, type InputType as e, type PasswordStrengthClassNames as f, type PlainOnlyProps as g };