@enigmax/primitives 0.22.0 → 0.24.0

package/dist/clipboard-menu-B_ouitfS.d.ts

@@ -0,0 +1,264 @@
+import { F as FuseConstructor, c as SearchOptions } from './search-DYgqRp37.js';
+
+/**
+ * The parts of a context menu that are not rendering: which branch is open, where the
+ * highlight is inside it, what a submenu's rows are once they have been fetched, and which
+ * of those rows survived the filter.
+ *
+ * Framework-agnostic like every other core here, and for the same reason: the arithmetic of
+ * a menu is not React. What IS specific to this one is that a menu is a TREE and a select is
+ * a list, so everything below is keyed by a PATH - the list of item ids from the root down to
+ * the open submenu - rather than by an index.
+ *
+ * The behaviour it copies is the Windows one, deliberately: a right-click opens it at the
+ * pointer, a submenu opens after a beat of hovering and closes after a beat of leaving,
+ * arrows walk the rows and skip everything that cannot be chosen, Right opens a submenu and
+ * Left goes back, and typing jumps to a row.
+ */
+
+/** A row that does something. The default kind, so `type` can be left off. */
+interface ContextMenuAction {
+    type?: "item";
+    /** Unique among its SIBLINGS. The path down the tree is built from these. */
+    id: string;
+    label: string;
+    /** A second line under the label, for a row whose consequence is not obvious. */
+    description?: string;
+    /** Anything the renderer can draw - a node, a URL, a name. `unknown` because a core cannot know. */
+    icon?: unknown;
+    /**
+     * Printed on the right, the way every desktop menu prints it: `"Mod+C"`, `"F2"`,
+     * `"Delete"`. Written by `shortcutTokens` for the platform it is rendered on, so one
+     * spec is `⌘C` on a Mac and `Ctrl+C` elsewhere.
+     */
+    shortcut?: string;
+    /** Listed, announced as unavailable, never highlighted and never invoked. */
+    disabled?: boolean;
+    /** Deletes something. Rendered in the destructive colour and reported as such. */
+    destructive?: boolean;
+    /** A checkable row: a tick, or a radio dot when `group` is set. */
+    checked?: boolean;
+    /** Rows carrying the same group render together under its name, and check as a radio set. */
+    group?: string;
+    /** Extra words the filter should match. */
+    keywords?: string[];
+    /** A heading over this row's submenu. See `ContextMenuOptions.title` for what it is for. */
+    title?: string;
+    /** A submenu, known up front. An empty list is not a submenu: the row keeps no arrow. */
+    items?: readonly ContextMenuEntry[];
+    /**
+     * A submenu fetched on demand, once. What it returns is cached under this row's path for
+     * `cacheMs`, so reopening the branch shows the rows immediately instead of spinning
+     * again - which is the whole reason a slow submenu is bearable.
+     */
+    loadItems?: () => Promise<readonly ContextMenuEntry[]>;
+    /** Put a filter in this submenu. `"auto"` (the default) adds one from `SEARCHABLE_FROM` rows. */
+    searchable?: boolean | "auto";
+    /** Anything the caller wants back in `onSelect`. */
+    data?: unknown;
+}
+/** A rule between two blocks of rows. Never highlighted, never counted by the keyboard. */
+interface ContextMenuSeparator {
+    type: "separator";
+    id?: string;
+}
+/** A caption over a block of rows. Same rules as a separator: visible, unreachable. */
+interface ContextMenuLabel {
+    type: "label";
+    id?: string;
+    label: string;
+}
+type ContextMenuEntry = ContextMenuAction | ContextMenuSeparator | ContextMenuLabel;
+/** Whether an entry is a row the keyboard and the pointer can land on. */
+declare function isAction(entry: ContextMenuEntry): entry is ContextMenuAction;
+/** The fields the filter reads when the caller does not say. */
+declare const CONTEXT_MENU_SEARCH_KEYS: string[];
+/** Where a menu was opened. Viewport coordinates, which is what a pointer event reports. */
+interface ContextMenuPoint {
+    x: number;
+    y: number;
+}
+/** One open level: the root, then one per submenu below it. */
+interface ContextMenuLevel {
+    /** Ids from the root down to the item that opened this level. Empty for the root. */
+    path: string[];
+    /** A heading over the rows, or null. Also the panel's accessible name. */
+    title: string | null;
+    /** Every entry at this level, separators and labels included. */
+    entries: ContextMenuEntry[];
+    /** What the panel shows: the entries, or what survived the filter. */
+    visible: ContextMenuEntry[];
+    /** Index into `visible`. -1 when nothing is highlighted. */
+    active: number;
+    query: string;
+    /** Whether this level draws a filter field. */
+    searchable: boolean;
+    /** An awaited submenu that has not answered yet. */
+    loading: boolean;
+    /** What the load rejected with, so the level can say so instead of staying empty. */
+    error: Error | null;
+}
+interface ContextMenuState {
+    open: boolean;
+    /** Where it was opened, in viewport coordinates. Null while closed. */
+    point: ContextMenuPoint | null;
+    /** The root level first, then one per open submenu. */
+    levels: ContextMenuLevel[];
+}
+interface ContextMenuOptions {
+    items?: readonly ContextMenuEntry[];
+    /**
+     * A heading over the rows, naming what the menu is acting ON - the file that was
+     * right-clicked, or "12 items selected". A menu opened at the pointer is the one surface
+     * with no context around it, so without this the rows are the only clue about what they
+     * will happen to.
+     */
+    title?: string;
+    /** Fuse.js's constructor, for fuzzy filtering. Omit it for the built-in matcher. */
+    fuse?: FuseConstructor;
+    fuseOptions?: Record<string, unknown>;
+    matcher?: SearchOptions<ContextMenuEntry>["matcher"];
+    searchKeys?: string[];
+    /** How long a fetched submenu stays cached. 0 refetches every time. Default 5 minutes. */
+    cacheMs?: number;
+    /** Every state change. */
+    onChange?: (state: ContextMenuState) => void;
+    /** A row was invoked. The menu has already closed unless the row keeps it open. */
+    onSelect?: (item: ContextMenuAction, path: string[]) => void;
+    onOpenChange?: (open: boolean) => void;
+}
+interface ContextMenuInstance {
+    readonly state: ContextMenuState;
+    /**
+     * Open at a point, or reopen somewhere else - a second right-click MOVES the menu.
+     *
+     * Returns whether it opened. A menu with no rows to show does NOT open: an empty box at
+     * the pointer says nothing, and refusing here is what lets the trigger leave the press
+     * alone so the browser's own menu appears instead of nothing at all.
+     */
+    open(point: ContextMenuPoint): boolean;
+    close(): void;
+    /** Move the highlight inside the deepest open level, skipping what cannot be chosen. */
+    move(key: ContextMenuMoveKey): void;
+    setActive(level: number, index: number): void;
+    setQuery(level: number, query: string): void;
+    /**
+     * Open the submenu of the row at `index` in `level`, closing any deeper branch.
+     *
+     * `focus` highlights its first row, which is what the KEYBOARD needs and what a pointer
+     * must not do: a row that looks hovered before the pointer arrives reads as the menu
+     * having chosen for you. Default false, so hovering is the plain case.
+     */
+    openSubmenu(level: number, index: number, focus?: boolean): void;
+    /** Close every level below `level`. */
+    closeBelow(level: number): void;
+    /** Invoke a row: reports it, and closes unless it is disabled or opens a submenu. */
+    select(level: number, index: number): void;
+    /** Invoke whatever is highlighted in the deepest open level. */
+    selectActive(): void;
+    /** Right on a row with a submenu opens it; on any other row it does nothing. */
+    enterSubmenu(): void;
+    /** Left closes the deepest submenu and puts the highlight back on the row that opened it. */
+    leaveSubmenu(): void;
+    /** Jump to the row starting with what was typed, the way a desktop menu does. */
+    typeahead(character: string): void;
+    /** Drop what a fetched submenu returned, so the next open asks again. */
+    invalidate(path?: string[]): void;
+    update(options: Partial<ContextMenuOptions>): void;
+    subscribe(listener: (state: ContextMenuState) => void): () => void;
+    destroy(): void;
+}
+type ContextMenuMoveKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" | "PageUp";
+declare function createContextMenu(options?: ContextMenuOptions): ContextMenuInstance;
+
+/**
+ * The rows every context menu on a desktop already has: Copy, Cut and Paste.
+ *
+ * A menu opened over a selection or over a field is expected to offer them - the browser's own
+ * does, and replacing that menu with a custom one takes them away without saying so. Which is
+ * why they are ON by default here and turned off with a prop, rather than the other way round:
+ * the defect is silent, so the default has to be the safe one.
+ *
+ * WHAT DECIDES THEY APPEAR is what was right-clicked, and it is read at the moment the menu
+ * opens, not from React state - by then the selection is settled (a `contextmenu` event fires
+ * after the press has adjusted it) and the caret is still where the visitor left it.
+ *
+ * - **Copy**, when there is selected text under the pointer.
+ * - **Cut**, when that selection is also in something writable.
+ * - **Paste**, in anything writable - and disabled when the clipboard is known to be empty.
+ *
+ * Not a React module: what a selection is, whether a field takes writes, and how text is put
+ * back into one are DOM questions, so a menu drawn by anything else gets the same rows.
+ */
+
+/** The ids these rows carry. Namespaced, so they can never collide with a caller's own. */
+declare const CLIPBOARD_PREFIX = "enigma:clipboard:";
+type ClipboardAction = "copy" | "cut" | "paste";
+/** What the menu was opened over, as far as the clipboard is concerned. */
+interface ClipboardTarget {
+    /** The field or contenteditable under the pointer, or null when it is neither. */
+    editable: HTMLElement | null;
+    /** Whether that element takes writes: not disabled, not read-only. */
+    writable: boolean;
+    /** The selected text, from the field's own selection or the document's. */
+    selection: string;
+    /**
+     * Whether that text may be put on the clipboard.
+     *
+     * False for a password field. The clipboard is shared with every other application on the
+     * machine and is not cleared, so a menu that copies a password out of a masked field
+     * leaks it somewhere the visitor cannot see - and the browser's own menu refuses too.
+     */
+    copyable: boolean;
+    /** Where the selection was, so it can be put back after the menu has taken focus. */
+    range: {
+        start: number;
+        end: number;
+    } | null;
+}
+interface ClipboardMenuLabels {
+    copy?: string;
+    cut?: string;
+    paste?: string;
+}
+interface ClipboardMenuOptions {
+    copy?: boolean;
+    cut?: boolean;
+    paste?: boolean;
+    labels?: ClipboardMenuLabels;
+    /** Whatever the renderer draws icons with. `unknown`, because a core cannot know. */
+    icons?: {
+        copy?: unknown;
+        cut?: unknown;
+        paste?: unknown;
+    };
+    /** The clipboard is known to be empty, so Paste is listed and greyed rather than missing. */
+    clipboardEmpty?: boolean;
+}
+/** What was right-clicked, read the moment the menu opens. */
+declare function inspectClipboardTarget(node: EventTarget | null): ClipboardTarget;
+/**
+ * Whether the clipboard has text in it, or null when that cannot be known.
+ *
+ * Null is the common answer and not a failure: reading the clipboard needs permission, and
+ * asking for it puts a browser prompt on screen just to decide whether to grey out a row -
+ * which is a worse trade than showing an enabled Paste that turns out to do nothing. So the
+ * permission is only READ, never requested, and the clipboard is only opened where it has
+ * already been granted.
+ */
+declare function clipboardHasText(): Promise<boolean | null>;
+/** The rows for this target, in the order every desktop menu puts them. */
+declare function clipboardEntries(target: ClipboardTarget, options?: ClipboardMenuOptions): ContextMenuEntry[];
+/** Which clipboard row an id belongs to, or null for anything that is not one of ours. */
+declare function clipboardAction(id: string): ClipboardAction | null;
+/**
+ * Do what the row says.
+ *
+ * Called straight from the press that chose it, so the browser still counts it as a user
+ * gesture - which is what the clipboard API requires and what makes a paste possible at all.
+ * Returns whether the action happened: a refused permission and an empty clipboard are both
+ * "no", and neither is worth an exception the caller has to catch.
+ */
+declare function performClipboardAction(action: ClipboardAction, target: ClipboardTarget): Promise<boolean>;
+
+export { CLIPBOARD_PREFIX as C, CONTEXT_MENU_SEARCH_KEYS as a, type ClipboardAction as b, type ClipboardMenuLabels as c, type ClipboardMenuOptions as d, type ClipboardTarget as e, type ContextMenuAction as f, type ContextMenuEntry as g, type ContextMenuInstance as h, type ContextMenuLabel as i, type ContextMenuLevel as j, type ContextMenuMoveKey as k, type ContextMenuOptions as l, type ContextMenuPoint as m, type ContextMenuSeparator as n, type ContextMenuState as o, clipboardAction as p, clipboardEntries as q, clipboardHasText as r, createContextMenu as s, inspectClipboardTarget as t, isAction as u, performClipboardAction as v };

package/dist/color-D_rZ83Oc.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Making a password, and judging one.
+ *
+ * Both are opt-in. A sign-in form wants neither: offering to generate a password where one
+ * already exists is noise, and scoring one the visitor cannot change is worse. They belong
+ * on a registration form and a change-password form, which is where an agent should switch
+ * them on.
+ */
+/** Character classes a generated password can draw from. */
+interface PasswordAlphabet {
+    lowercase?: boolean;
+    uppercase?: boolean;
+    digits?: boolean;
+    symbols?: boolean;
+}
+interface GeneratePasswordOptions extends PasswordAlphabet {
+    /** Default 20. Long beats clever: length is the only term that scales. */
+    length?: number;
+    /**
+     * Drop the characters that are read wrong off a screen or off paper - I l 1 O 0.
+     * Worth it when the password will be typed by hand, not worth the entropy otherwise.
+     */
+    excludeAmbiguous?: boolean;
+    /** Characters to remove from every class, e.g. ones your backend rejects. */
+    exclude?: string;
+    /**
+     * Guarantee at least one character from every class asked for. Most password policies
+     * demand it; it costs a little entropy, because it removes every password that happens
+     * to lack one.
+     */
+    requireEachClass?: boolean;
+}
+/**
+ * A random password from the classes asked for.
+ *
+ * @throws when the runtime has no CSPRNG, or when the options ask for something impossible
+ *         (every class excluded, or a length too short to hold one of each).
+ */
+declare function generatePassword(options?: GeneratePasswordOptions): string;
+type PasswordScore = 0 | 1 | 2 | 3 | 4;
+interface PasswordStrengthReport {
+    /** 0 worst, 4 best. What the bars under the field render. */
+    score: PasswordScore;
+    /** Estimated bits of entropy after the penalties below. */
+    bits: number;
+    /**
+     * Why it scored what it scored, worst first. Show the first one; showing all of them
+     * turns a hint into a lecture.
+     */
+    warnings: string[];
+    /** Empty field. Render nothing rather than a zero score, which reads as a failure. */
+    empty: boolean;
+}
+interface EstimateOptions {
+    /**
+     * Values the visitor has already typed elsewhere - email, name, company. A password
+     * containing one of them is guessable by anyone who has the sign-up form in front of
+     * them, and no character-class rule catches it.
+     */
+    userInputs?: string[];
+}
+/**
+ * Score a password.
+ *
+ * The bits are an estimate and the bands are a convention, not a measurement - they exist
+ * to move a bar, not to certify anything. Swap this out for zxcvbn where the number has to
+ * mean something, and check the breach corpus for the cases no estimator can see.
+ */
+declare function estimatePasswordStrength(password: string, options?: EstimateOptions): PasswordStrengthReport;
+
+/**
+ * Reading a colour, writing one, and converting between the two models a picker needs.
+ *
+ * Arithmetic only, like every other core here: no DOM, no framework. The picker drags a
+ * saturation/value square and a hue rail, which are HSV; a form field holds `#3b82f6`,
+ * `rgb(59, 130, 246)` or an `hsl()`, which is what a stylesheet and a database take. This
+ * module is the translation between them.
+ *
+ * Two things it does NOT do, both on purpose:
+ *
+ * - **Named colours.** `red`, `rebeccapurple` and the other 146 are a table nobody needs in
+ *   a bundle to drag a square, and the DOM already resolves them for free (assign the name
+ *   to `style.color` and read it back). The picker's canonical value is a hex string.
+ * - **Colour spaces past sRGB.** `oklch()` and `color()` describe colours a hex cannot, so
+ *   accepting one here and handing back `#rrggbb` would silently clip it. Parsing returns
+ *   null instead, which the field reports as unparseable rather than as a different colour.
+ */
+/** sRGB, 0-255 per channel, with alpha 0-1. The transport shape everything converts through. */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/** Hue 0-360, saturation and value 0-1, alpha 0-1. What the picker's two controls move. */
+interface Hsv {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+}
+/** Hue 0-360, saturation and lightness 0-1, alpha 0-1. Only used by `hsl()` in and out. */
+interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+}
+/** How a colour is written back into the field. */
+type ColorFormat = "hex" | "rgb" | "hsl";
+interface FormatColorOptions {
+    /** Write the alpha channel. Off drops it, so a half-transparent colour becomes opaque. */
+    alpha?: boolean;
+}
+/**
+ * A colour string to sRGB, or null when it is not one.
+ *
+ * Null is the whole point of the return type: a field is unparseable for as long as someone
+ * is halfway through typing `#3b8`, and a picker that guesses at that moment fights the
+ * caret. Everything here is tolerant of what a person types - a missing `#`, upper case,
+ * stray spaces - and intolerant of what would be a guess.
+ */
+declare function parseColor(input: string): Rgb | null;
+/** `#rrggbb`, or `#rrggbbaa` when alpha is asked for and the colour is not opaque. */
+declare function toHex(color: Rgb, options?: FormatColorOptions): string;
+/**
+ * A colour back to a string.
+ *
+ * The legacy comma syntax for `rgb()` and `hsl()`, deliberately: this string is going into a
+ * field someone will paste into a stylesheet, a spreadsheet or an older toolchain, and the
+ * space-and-slash form is the one those still refuse.
+ */
+declare function formatColor(color: Rgb, format?: ColorFormat, options?: FormatColorOptions): string;
+/**
+ * sRGB to HSV, keeping a hue the arithmetic cannot see.
+ *
+ * THE colour picker bug, and it is in almost every hand-rolled one: hue is undefined at
+ * black, at white and at every grey, because those have no dominant channel. Recomputing it
+ * from the RGB therefore returns 0 - red - so dragging the square into its bottom-left
+ * corner and back out again resets a hue the visitor picked, and the rail jumps under their
+ * finger. `fallbackHue` is the hue they last chose, and it is what the picker keeps its own
+ * state for.
+ */
+declare function rgbToHsv(color: Rgb, fallbackHue?: number): Hsv;
+declare function hsvToRgb(color: Hsv): Rgb;
+/** sRGB to HSL. Same undefined hue at the greys, same reason to pass the one being kept. */
+declare function rgbToHsl(color: Rgb, fallbackHue?: number): Hsl;
+declare function hslToRgb(color: Hsl): Rgb;
+/** Same colour, to the byte. Used to tell a value the picker wrote from one someone typed. */
+declare function colorEquals(a: Rgb | null, b: Rgb | null): boolean;
+
+export { type ColorFormat as C, type EstimateOptions as E, type FormatColorOptions as F, type GeneratePasswordOptions as G, type Hsl as H, type PasswordAlphabet as P, type Rgb as R, type Hsv as a, type PasswordScore as b, type PasswordStrengthReport as c, colorEquals as d, estimatePasswordStrength as e, formatColor as f, generatePassword as g, hslToRgb as h, hsvToRgb as i, rgbToHsv as j, parseColor as p, rgbToHsl as r, toHex as t };