@enigmax/primitives 0.23.0 → 0.25.0

package/dist/{context-menu-D3FtTn7v.d.ts → clipboard-menu-B_ouitfS.d.ts}

@@ -171,4 +171,94 @@ interface ContextMenuInstance {
 type ContextMenuMoveKey = "ArrowDown" | "ArrowUp" | "Home" | "End" | "PageDown" | "PageUp";
 declare function createContextMenu(options?: ContextMenuOptions): ContextMenuInstance;
 
-export { CONTEXT_MENU_SEARCH_KEYS as C, type ContextMenuAction as a, type ContextMenuEntry as b, type ContextMenuInstance as c, type ContextMenuLabel as d, type ContextMenuLevel as e, type ContextMenuMoveKey as f, type ContextMenuOptions as g, type ContextMenuPoint as h, type ContextMenuSeparator as i, type ContextMenuState as j, createContextMenu as k, isAction as l };
+/**
+ * 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 };