@enigmax/primitives 0.5.0 → 0.7.0

package/dist/{chunk-2DVVWPHM.js → chunk-42Y7OOJM.js}

@@ -293,8 +293,21 @@ function createMarquee(lane, track, options = {}) {
 }
 
 // src/core/input.ts
-var EYE = '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z"/><circle cx="12" cy="12" r="3"/></svg>';
-var EYE_OFF = '<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9"/><path d="m2 2 20 20"/><path d="M9.9 9.9a3 3 0 0 0 4.2 4.2"/></svg>';
+var INPUT_ICON_PATHS = {
+  eye: ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z", "M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"],
+  eyeOff: [
+    "M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9",
+    "m2 2 20 20",
+    "M9.9 9.9a3 3 0 0 0 4.2 4.2"
+  ],
+  generate: ["m12 3 1.9 4.6L18.5 9.5 13.9 11.4 12 16l-1.9-4.6L5.5 9.5l4.6-1.9Z", "M19 15l.8 2.2 2.2.8-2.2.8-.8 2.2-.8-2.2-2.2-.8 2.2-.8Z"]
+};
+function iconMarkup(paths) {
+  const body = paths.map((path) => `<path d="${path}"/>`).join("");
+  return `<svg viewBox="0 0 24 24" width="1em" height="1em" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+}
+var EYE = iconMarkup(INPUT_ICON_PATHS.eye);
+var EYE_OFF = iconMarkup(INPUT_ICON_PATHS.eyeOff);
 function resolve(value, state) {
   return typeof value === "function" ? value(state) : value;
 }
@@ -477,4 +490,331 @@ function createInput(input, options = {}) {
   };
 }
 
-export { createInput, createMarquee };
+// src/core/button.ts
+var TICK_MS = 100;
+function store(cooldown) {
+  if (!cooldown.key || typeof window === "undefined") return null;
+  try {
+    const target = cooldown.storage === "local" ? window.localStorage : window.sessionStorage;
+    const probe = "__enigma_probe__";
+    target.setItem(probe, "1");
+    target.removeItem(probe);
+    return target;
+  } catch {
+    return null;
+  }
+}
+function normalize(cooldown) {
+  if (cooldown == null) return null;
+  return typeof cooldown === "number" ? { ms: cooldown } : cooldown;
+}
+function isTyping(target) {
+  const element = target;
+  if (!element) return false;
+  const tag = element.tagName;
+  return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || element.isContentEditable === true;
+}
+function createButton(options = {}) {
+  let opts = { ...options };
+  let loading = Boolean(opts.loading);
+  let readyAt = 0;
+  let timer = null;
+  let destroyed = false;
+  const listeners = /* @__PURE__ */ new Set();
+  const storageKey = () => {
+    const cooldown = normalize(opts.cooldown);
+    return cooldown?.key ? `enigma:cooldown:${cooldown.key}` : null;
+  };
+  function restore() {
+    const cooldown = normalize(opts.cooldown);
+    if (!cooldown) return;
+    const target = store(cooldown);
+    const key = storageKey();
+    if (!target || !key) return;
+    const saved = Number(target.getItem(key));
+    if (Number.isFinite(saved) && saved > Date.now()) readyAt = saved;
+  }
+  function remaining() {
+    return Math.max(0, readyAt - Date.now());
+  }
+  function snapshot() {
+    const disabled = Boolean(opts.disabled);
+    const cooldown = remaining();
+    return {
+      element: opts.href ? "a" : "button",
+      available: !disabled && !loading && cooldown === 0,
+      loading,
+      disabled,
+      cooldown,
+      shortcut: opts.shortcut ?? null
+    };
+  }
+  function emit() {
+    const state = snapshot();
+    opts.onChange?.(state);
+    for (const listener of listeners) listener(state);
+  }
+  function stopTicking() {
+    if (timer === null) return;
+    clearInterval(timer);
+    timer = null;
+  }
+  function startTicking() {
+    if (timer !== null || remaining() === 0) return;
+    timer = setInterval(() => {
+      if (remaining() > 0) {
+        emit();
+        return;
+      }
+      stopTicking();
+      emit();
+    }, TICK_MS);
+  }
+  function beginCooldown() {
+    const cooldown = normalize(opts.cooldown);
+    if (!cooldown || cooldown.ms <= 0) return;
+    readyAt = Date.now() + cooldown.ms;
+    const target = store(cooldown);
+    const key = storageKey();
+    if (target && key) {
+      try {
+        target.setItem(key, String(readyAt));
+      } catch {
+      }
+    }
+    startTicking();
+  }
+  async function press(event) {
+    if (destroyed || !snapshot().available) return;
+    const result = opts.onPress?.(event);
+    if (result instanceof Promise) {
+      loading = true;
+      emit();
+      try {
+        await result;
+      } finally {
+        loading = false;
+        beginCooldown();
+        emit();
+      }
+      return;
+    }
+    beginCooldown();
+    emit();
+  }
+  function onKeyDown(event) {
+    if (!opts.shortcut || isTyping(event.target)) return;
+    if (event.ctrlKey || event.metaKey || event.altKey || event.shiftKey) return;
+    if (event.key.toLowerCase() !== opts.shortcut.toLowerCase()) return;
+    if (!snapshot().available) return;
+    event.preventDefault();
+    void press(event);
+  }
+  if (typeof window !== "undefined") {
+    restore();
+    startTicking();
+    window.addEventListener("keydown", onKeyDown);
+  }
+  return {
+    get state() {
+      return snapshot();
+    },
+    press,
+    update(next) {
+      const hadCooldown = JSON.stringify(normalize(opts.cooldown));
+      opts = { ...opts, ...next };
+      if (next.loading !== void 0) loading = Boolean(next.loading);
+      if (JSON.stringify(normalize(opts.cooldown)) !== hadCooldown) restore();
+      emit();
+    },
+    reset() {
+      readyAt = 0;
+      stopTicking();
+      const cooldown = normalize(opts.cooldown);
+      const key = storageKey();
+      if (cooldown && key) store(cooldown)?.removeItem(key);
+      emit();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    destroy() {
+      destroyed = true;
+      stopTicking();
+      listeners.clear();
+      if (typeof window !== "undefined") window.removeEventListener("keydown", onKeyDown);
+    }
+  };
+}
+
+// src/core/password.ts
+var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var DIGITS = "0123456789";
+var SYMBOLS = "!@#$%^&*()-_=+[]{};:,.?";
+var AMBIGUOUS = "Il1O0";
+function randomIndex(bound) {
+  const random = globalThis.crypto?.getRandomValues?.bind(globalThis.crypto);
+  if (!random) {
+    throw new Error("Generating a password needs crypto.getRandomValues, which browsers only expose over HTTPS (or on localhost).");
+  }
+  const limit = Math.floor(2 ** 32 / bound) * bound;
+  const buffer = new Uint32Array(1);
+  let value;
+  do {
+    random(buffer);
+    value = buffer[0];
+  } while (value >= limit);
+  return value % bound;
+}
+function pick(alphabet) {
+  return alphabet[randomIndex(alphabet.length)];
+}
+function classes(options) {
+  const { lowercase = true, uppercase = true, digits = true, symbols = true, excludeAmbiguous = false, exclude = "" } = options;
+  const banned = /* @__PURE__ */ new Set([...excludeAmbiguous ? AMBIGUOUS : "", ...exclude]);
+  const clean = (source) => [...source].filter((character) => !banned.has(character)).join("");
+  return [
+    lowercase ? clean(LOWERCASE) : "",
+    uppercase ? clean(UPPERCASE) : "",
+    digits ? clean(DIGITS) : "",
+    symbols ? clean(SYMBOLS) : ""
+  ].filter(Boolean);
+}
+function shuffle(characters) {
+  for (let index = characters.length - 1; index > 0; index--) {
+    const swap = randomIndex(index + 1);
+    [characters[index], characters[swap]] = [characters[swap], characters[index]];
+  }
+  return characters;
+}
+function generatePassword(options = {}) {
+  const { length = 20, requireEachClass = true } = options;
+  const pools = classes(options);
+  if (!pools.length) throw new Error("generatePassword: every character class was excluded.");
+  if (length < 1) throw new Error("generatePassword: length must be at least 1.");
+  if (requireEachClass && length < pools.length) {
+    throw new Error(`generatePassword: length ${length} cannot hold one character from each of the ${pools.length} classes requested.`);
+  }
+  const everything = pools.join("");
+  const required = requireEachClass ? pools.map(pick) : [];
+  const rest = Array.from({ length: length - required.length }, () => pick(everything));
+  return shuffle([...required, ...rest]).join("");
+}
+var COMMON = /* @__PURE__ */ new Set([
+  "password",
+  "passwd",
+  "123456",
+  "12345678",
+  "123456789",
+  "1234567890",
+  "qwerty",
+  "qwertyuiop",
+  "abc123",
+  "111111",
+  "123123",
+  "admin",
+  "letmein",
+  "welcome",
+  "monkey",
+  "dragon",
+  "sunshine",
+  "iloveyou",
+  "princess",
+  "football",
+  "baseball",
+  "master",
+  "shadow",
+  "superman",
+  "batman",
+  "trustno1",
+  "hello",
+  "freedom",
+  "whatever",
+  "starwars",
+  "changeme",
+  "secret",
+  "login",
+  "root",
+  "toor",
+  "test",
+  "guest",
+  "azerty",
+  "1q2w3e4r",
+  "zaq12wsx"
+]);
+var SEQUENCES = ["abcdefghijklmnopqrstuvwxyz", "0123456789", "qwertyuiop", "asdfghjkl", "zxcvbnm"];
+function poolSize(password) {
+  let size = 0;
+  if (/[a-z]/.test(password)) size += 26;
+  if (/[A-Z]/.test(password)) size += 26;
+  if (/\d/.test(password)) size += 10;
+  if (/[^\w\s]|_/.test(password)) size += SYMBOLS.length;
+  if (/\s/.test(password)) size += 1;
+  return size || 1;
+}
+function longestRun(password) {
+  let longest = 1, run = 1;
+  for (let index = 1; index < password.length; index++) {
+    run = password[index] === password[index - 1] ? run + 1 : 1;
+    longest = Math.max(longest, run);
+  }
+  return longest;
+}
+function longestSequence(password) {
+  const lower = password.toLowerCase();
+  let longest = 0;
+  for (const line of SEQUENCES) {
+    const reversed = [...line].reverse().join("");
+    for (const source of [line, reversed]) {
+      for (let start = 0; start < source.length; start++) {
+        for (let end = source.length; end > start + longest; end--) {
+          if (lower.includes(source.slice(start, end))) {
+            longest = Math.max(longest, end - start);
+            break;
+          }
+        }
+      }
+    }
+  }
+  return longest;
+}
+function core(password) {
+  return password.toLowerCase().replace(/^[^a-z]+/, "").replace(/[^a-z]+$/, "").replace(/[0!@$]/g, (character) => ({ "0": "o", "!": "i", "@": "a", "$": "s" })[character] ?? character);
+}
+function estimatePasswordStrength(password, options = {}) {
+  if (!password) return { score: 0, bits: 0, warnings: [], empty: true };
+  const warnings = [];
+  let bits = password.length * Math.log2(poolSize(password));
+  const stripped = core(password);
+  if (COMMON.has(password.toLowerCase()) || COMMON.has(stripped)) {
+    bits = Math.min(bits, 8);
+    warnings.push("This is one of the most common passwords there is.");
+  }
+  for (const input of options.userInputs ?? []) {
+    const needle = input.trim().toLowerCase();
+    if (needle.length < 4 || !password.toLowerCase().includes(needle)) continue;
+    bits = Math.min(bits, 16);
+    warnings.push("It contains something you already typed on this form.");
+    break;
+  }
+  const run = longestRun(password);
+  if (run >= 3) {
+    bits -= (run - 2) * Math.log2(poolSize(password));
+    warnings.push("A character repeats several times in a row.");
+  }
+  const sequence = longestSequence(password);
+  if (sequence >= 4) {
+    bits -= sequence * Math.log2(poolSize(password)) * 0.75;
+    warnings.push("Part of it runs straight along the keyboard or the alphabet.");
+  }
+  if (password.length < 8) warnings.push("Short passwords fall to a brute force whatever they contain.");
+  bits = Math.max(0, Math.round(bits));
+  const score = bits < 28 ? 0 : bits < 40 ? 1 : bits < 60 ? 2 : bits < 80 ? 3 : 4;
+  return { score, bits, warnings, empty: false };
+}
+
+export { INPUT_ICON_PATHS, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup };

package/dist/index.d.ts

@@ -155,6 +155,21 @@ interface InputInstance {
     update(options: Partial<InputOptions>): void;
     destroy(): void;
 }
+/**
+ * The built-in glyphs, as path data.
+ *
+ * Path data rather than markup because there are two renderers: this file writes an SVG
+ * string into a button it created, and the React component builds elements. Keeping the
+ * shapes here means one definition, and a theme that replaces an icon replaces it in both.
+ * Everything is stroked with `currentColor` at 1em, so an icon inherits the field's text.
+ */
+declare const INPUT_ICON_PATHS: {
+    readonly eye: readonly ["M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z", "M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"];
+    readonly eyeOff: readonly ["M10.6 5.2A9.8 9.8 0 0 1 12 5c6.5 0 10 7 10 7a17.6 17.6 0 0 1-3.2 4.2M6.2 6.2A17.7 17.7 0 0 0 2 12s3.5 7 10 7a9.6 9.6 0 0 0 4.2-.9", "m2 2 20 20", "M9.9 9.9a3 3 0 0 0 4.2 4.2"];
+    readonly generate: readonly ["m12 3 1.9 4.6L18.5 9.5 13.9 11.4 12 16l-1.9-4.6L5.5 9.5l4.6-1.9Z", "M19 15l.8 2.2 2.2.8-2.2.8-.8 2.2-.8-2.2-2.2-.8 2.2-.8Z"];
+};
+/** The same shapes as a standalone SVG string, for the DOM renderer below. */
+declare function iconMarkup(paths: readonly string[]): string;
 /**
  * Wire a field's in-field actions.
  *
@@ -162,4 +177,136 @@ interface InputInstance {
  */
 declare function createInput(input: HTMLInputElement, options?: InputOptions): InputInstance;
 
-export { type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, createInput, createMarquee };
+/**
+ * Button behaviour: what makes it unavailable, and everything that follows from that.
+ *
+ * Disabled, loading and a cooldown are three reasons for the same state, so they collapse
+ * into one `available` the renderer reads, instead of three flags every call site has to
+ * combine correctly. The element to render is reported rather than chosen, because a
+ * framework-agnostic package cannot import next/link.
+ */
+/** Which tag the consumer should render. An href makes it a link, and a link is not a button. */
+type ButtonElement = "button" | "a";
+interface ButtonCooldown {
+    /** How long the button stays unavailable after a press, in ms. */
+    ms: number;
+    /**
+     * Survive a reload under this key. Without it the cooldown is in memory only, and a
+     * refresh is a free retry - which is the whole thing a cooldown exists to prevent.
+     */
+    key?: string;
+    storage?: "local" | "session";
+}
+interface ButtonOptions {
+    /** Turns into an `a`, and a link cannot be `disabled` - only `aria-disabled`. */
+    href?: string;
+    disabled?: boolean;
+    /** Unavailable and busy. Set it yourself, or let an async `onPress` manage it. */
+    loading?: boolean;
+    /** ms, or the full shape for a cooldown that outlives a reload. */
+    cooldown?: number | ButtonCooldown;
+    /**
+     * A single key that presses the button. Ignored while the visitor is typing, and
+     * while any modifier is held, so it never steals a real shortcut.
+     */
+    shortcut?: string;
+    /** Async work flips `loading` for its duration and only then starts the cooldown. */
+    onPress?: (event?: Event) => void | Promise<void>;
+    /** Called whenever anything below changes. */
+    onChange?: (state: ButtonState) => void;
+}
+interface ButtonState {
+    /** The tag to render. */
+    element: ButtonElement;
+    /** Pressable: not disabled, not loading, not cooling down. */
+    available: boolean;
+    loading: boolean;
+    disabled: boolean;
+    /** ms left on the cooldown, 0 when there is none. */
+    cooldown: number;
+    /** The accessible name for the shortcut, when there is one. */
+    shortcut: string | null;
+}
+interface ButtonInstance {
+    readonly state: ButtonState;
+    /** Run the press as if it had been clicked. Ignored while unavailable. */
+    press(event?: Event): Promise<void>;
+    update(options: Partial<ButtonOptions>): void;
+    /** Clear a cooldown early, including its stored entry. */
+    reset(): void;
+    subscribe(listener: (state: ButtonState) => void): () => void;
+    destroy(): void;
+}
+declare function createButton(options?: ButtonOptions): ButtonInstance;
+
+/**
+ * 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;
+
+export { type ButtonCooldown, type ButtonElement, type ButtonInstance, type ButtonOptions, type ButtonState, type EstimateOptions, type GeneratePasswordOptions, INPUT_ICON_PATHS, type InputAction, type InputActionState, type InputIcon, type InputInstance, type InputOptions, type MarqueeHover, type MarqueeInstance, type MarqueeOptions, type PasswordAlphabet, type PasswordScore, type PasswordStrengthReport, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup };

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createInput, createMarquee } from './chunk-2DVVWPHM.js';
+export { INPUT_ICON_PATHS, createButton, createInput, createMarquee, estimatePasswordStrength, generatePassword, iconMarkup } from './chunk-42Y7OOJM.js';
 export { createSearch } from './chunk-UZFEEFMF.js';

package/dist/react/index.d.ts

@@ -1,6 +1,7 @@
-import { RefObject } from 'react';
-import { MarqueeOptions, InputOptions } from '../index.js';
-export { InputAction, InputIcon, MarqueeHover, MarqueeInstance } from '../index.js';
+import * as react from 'react';
+import { RefObject, ReactNode, ComponentPropsWithoutRef } from 'react';
+import { MarqueeOptions, InputOptions, ButtonState, ButtonOptions, GeneratePasswordOptions, EstimateOptions, PasswordStrengthReport } from '../index.js';
+export { InputAction, InputIcon, MarqueeHover, MarqueeInstance, PasswordScore, estimatePasswordStrength, generatePassword } from '../index.js';
 import { b as SearchMatch, c as SearchOptions } from '../search-CsO3L1Lw.js';
 export { F as FuseConstructor } from '../search-CsO3L1Lw.js';
 
@@ -94,4 +95,148 @@ interface UseSearchResult<T> {
  */
 declare function useSearch<T>(options?: SearchOptions<T>): UseSearchResult<T>;
 
-export { InputOptions, MarqueeOptions, SearchMatch, SearchOptions, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useInput, useMarquee, useSearch };
+interface UseButtonResult extends ButtonState {
+    /** Spread onto the element named by `element`. */
+    props: {
+        onClick: (event: {
+            preventDefault(): void;
+        }) => void;
+        "aria-disabled": boolean;
+        "aria-busy": boolean;
+        "data-loading"?: "";
+        "data-cooldown"?: "";
+        /** Only on a real button: an anchor has no `disabled`. */
+        disabled?: boolean;
+        href?: string;
+        title?: string;
+    };
+    press: () => void;
+    reset: () => void;
+}
+/**
+ * Button behaviour: disabled, loading, a cooldown and a keyboard shortcut collapsed into
+ * one `available`, plus the attributes that follow from it.
+ *
+ * ```tsx
+ * const { element: Tag, props, loading, cooldown } = useButton({
+ *     cooldown: { ms: 30_000, key: "resend-code", storage: "local" },
+ *     shortcut: "r",
+ *     onPress: () => resendCode()
+ * });
+ *
+ * return <Tag {...props}>{loading ? "Sending" : cooldown ? `Wait ${Math.ceil(cooldown / 1000)}s` : "Resend"}</Tag>;
+ * ```
+ */
+declare function useButton(options?: ButtonOptions): UseButtonResult;
+
+/** 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;
+}>;
+interface InputProps extends Omit<ComponentPropsWithoutRef<"input">, "children"> {
+    /** The reveal toggle. Defaults to on for `type="password"` and off for everything else. */
+    reveal?: boolean;
+    revealLabels?: {
+        show?: string;
+        hide?: string;
+    };
+    /** 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;
+    /** Extra buttons, or a replacement for `reveal` / `generate` by name. */
+    actions?: FieldAction[];
+    /** Which end the buttons sit at. Position them yourself; this only orders the markup. */
+    position?: "start" | "end";
+    /** 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;
+    /** Props for the element wrapping the field, its buttons and the meter. */
+    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?: PasswordStrengthProps["classNames"];
+    };
+    /** Rendered inside the wrapper, after the meter. Your error message goes here. */
+    children?: ReactNode;
+}
+declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
+interface PasswordStrengthProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+    /** The password to score. Ignored when `report` is given. */
+    value?: string;
+    /** A report you already have, e.g. from `<Input onStrengthChange>`. */
+    report?: PasswordStrengthReport;
+    userInputs?: string[];
+    /** Bars to draw. Five, so each score has one of its own. */
+    segments?: number;
+    /** Your own wording, worst first. */
+    labels?: readonly string[];
+    /** Show the top warning under the bars. On by default; it is the useful half. */
+    showWarning?: boolean;
+    /**
+     * Classes for the inner parts. The score is on the ROOT, so a segment colours itself
+     * with a group variant - `group-data-[score=0]/strength:bg-red-600` and so on.
+     */
+    classNames?: {
+        track?: string;
+        segment?: string;
+        label?: string;
+        warning?: string;
+    };
+}
+/**
+ * The bars under a password field.
+ *
+ * Structure and state only - `data-score` on the root and `data-filled` per segment are
+ * where the colours attach. The component picks no colours, because red-through-green is a
+ * palette decision and this package does not own one.
+ */
+declare function PasswordStrength({ value, report, userInputs, segments, labels, showWarning, classNames, ...props }: PasswordStrengthProps): ReactNode;
+
+export { type BreachChecker, type BreachState, type BreachStatus, ButtonOptions, ButtonState, EstimateOptions, type FieldAction, GeneratePasswordOptions, Input, InputOptions, type InputProps, MarqueeOptions, PasswordStrength, type PasswordStrengthProps, PasswordStrengthReport, SearchMatch, SearchOptions, type UseButtonResult, type UseInputResult, type UseMarqueeResult, type UseSearchResult, useButton, useInput, useMarquee, useSearch };