@enigmax/primitives 0.17.0 → 0.19.0

package/dist/flags-BBJc9unY.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Country flags as ASSETS, which is the only form of them that renders everywhere.
+ *
+ * The emoji flag is the thing this replaces. It is a pair of regional-indicator code
+ * points, and the glyph for that pair exists only where the platform ships one: Windows
+ * has never shipped country flags in Segoe UI Emoji, so `\u{1F1EA}\u{1F1F8}` renders as
+ * the letters "ES" for the largest desktop platform there is - and a language picker built
+ * out of them looks broken to those readers, with nothing in the code to explain why.
+ * There is no font stack that fixes it, so the fix is not a font: it is an image.
+ *
+ * Three sets, all SVG, all served by enigma itself:
+ *
+ * - `rect` (4:3) and `square` (1:1) - the classic rectangular artwork.
+ * - `circle` - round, which is what a flag next to an avatar or inside a chip wants.
+ *
+ * They are served from enigma's own tree rather than from anyone else's, because a
+ * component whose default source is a third party is a component that breaks when that
+ * third party moves, renames a branch, or goes away.
+ *
+ * Nothing here touches the DOM, so it renders on a server.
+ */
+type FlagShape = "rect" | "square" | "circle";
+/**
+ * `svg` is what the sets are stored as, so it is what a remote source can serve. `png` and
+ * `webp` exist for a LOCAL set (`enigma add flags --flags local --flag-formats webp`), which
+ * rasterises what it downloads, and for a mirror of your own.
+ */
+type FlagFormat = "svg" | "png" | "webp";
+/**
+ * Where the files come from.
+ *
+ * - `"cdn"` - enigma's own artwork, over a CDN. Nothing to install.
+ * - `"local"` - files under `basePath` in your own public directory.
+ * - any URL - a mirror of your own with the same layout
+ *   (`<base>/<shape>/<code>.<format>`), which is exactly the tree the downloader writes.
+ */
+type FlagSource = "cdn" | "local" | (string & {});
+/** enigma's own artwork, over a CDN. Every source shares this layout. */
+declare const FLAG_CDN = "https://cdn.jsdelivr.net/gh/FJRG2007/enigma@main/assets/flags";
+interface FlagOptions {
+    shape?: FlagShape;
+    format?: FlagFormat;
+    source?: FlagSource;
+    /** Where a local set is served from. Default `/flags`. */
+    basePath?: string;
+    /** Rendered HEIGHT in px. The width follows the shape's ratio. Default 16. */
+    size?: number;
+    /**
+     * Language the automatic name is written in. Left out, it follows the document's own
+     * `lang`, which is what a translated page wants.
+     */
+    locale?: string;
+}
+interface FlagConfig extends Required<Omit<FlagOptions, "size" | "locale">> {
+    size: number;
+    locale?: string;
+}
+/**
+ * Set the defaults for every flag on the page, once, at startup.
+ *
+ * This is what makes the CDN/local decision a one-line change rather than a prop on every
+ * call site: `configureFlags({ source: "local" })` moves the whole app onto the files the
+ * downloader wrote, and nothing else in the codebase mentions where a flag comes from.
+ */
+declare function configureFlags(patch: Partial<FlagConfig>): FlagConfig;
+declare function flagConfig(): FlagConfig;
+/** Test seam and a way back to the shipped defaults. */
+declare function resetFlagConfig(): FlagConfig;
+/** Width / height of each shape. The circle set is square; only `rect` is 4:3. */
+declare const FLAG_RATIO: Record<FlagShape, number>;
+/**
+ * Anything a codebase calls a country into the file name the sets use, or null.
+ *
+ * Null rather than a guess: a code this cannot resolve would otherwise become a 404 image
+ * with no alt text, and a broken flag beside a country name is worse than no flag at all.
+ * An emoji flag is accepted and converted, so migrating an existing picker is a rename of
+ * the component and nothing else.
+ */
+declare function normalizeFlagCode(value: string | null | undefined): string | null;
+/**
+ * The country's name, in the reader's language, or null.
+ *
+ * `Intl.DisplayNames` is the whole implementation: the names are in the runtime already,
+ * translated, and maintained by whoever maintains the platform - so this ships no table of
+ * 250 country names to go stale, and a Spanish page says "España" without being told.
+ *
+ * Null for anything it cannot name, and that is deliberate for SUBDIVISIONS: `gb-eng` is
+ * England, and falling back to the region (`gb`, "United Kingdom") would put a confidently
+ * wrong name on the flag. A name nobody can source is worse than no name.
+ */
+declare function flagName(code: string | null | undefined, locale?: string): string | null;
+/** Everything a renderer needs, computed in one pass. Null when the code is unusable. */
+interface FlagView {
+    /** The file name, e.g. `es`, `gb-eng`. */
+    code: string;
+    src: string;
+    shape: FlagShape;
+    format: FlagFormat;
+    width: number;
+    height: number;
+    /** The automatic name, when there is one. */
+    name: string | null;
+}
+/**
+ * The URL for one flag. Null when the code cannot be resolved.
+ *
+ * A raster format asked of the CDN falls back to SVG rather than producing a 404: the sets
+ * are stored as SVG, so `format: "webp"` is only meaningful against a local set or a mirror.
+ * It says so once, in development, instead of silently disagreeing with the call site.
+ */
+declare function flagSrc(code: string | null | undefined, options?: FlagOptions): string | null;
+/** `flagSrc` plus the resolved geometry and name, for a renderer that has to size the box. */
+declare function flagView(code: string | null | undefined, options?: FlagOptions): FlagView | null;
+interface FlagAttributeOptions extends FlagOptions {
+    /** Your own accessible name, which wins over the automatic one. */
+    label?: string;
+    /**
+     * Beside a country name that is already on screen, the flag is decoration and repeating
+     * the name only makes a screen reader say it twice.
+     */
+    decorative?: boolean;
+}
+/**
+ * Attributes for a plain `<img>`, for vanilla, Astro and any template language.
+ *
+ * The accessible name is AUTOMATIC: the country's own name, in the reader's language, from
+ * `Intl.DisplayNames`. `label` replaces it and `decorative` drops it. Nothing is ever
+ * invented - a subdivision the platform cannot name, or a runtime without `Intl`, renders
+ * as decoration rather than putting a bare "ES" into a screen reader.
+ */
+declare function flagAttributes(code: string | null | undefined, options?: FlagAttributeOptions): Record<string, string | number> | null;
+
+export { FLAG_CDN as F, FLAG_RATIO as a, type FlagConfig as b, type FlagFormat as c, type FlagOptions as d, type FlagShape as e, type FlagSource as f, type FlagView as g, configureFlags as h, flagAttributes as i, flagConfig as j, flagName as k, flagSrc as l, flagView as m, normalizeFlagCode as n, resetFlagConfig as r };

package/dist/index-dTdAbOWl.d.ts

@@ -0,0 +1,144 @@
+import { ReactNode, ComponentPropsWithoutRef } from 'react';
+import { c as SearchOptions, F as FuseConstructor, b as SearchMatch } from './search-DXxY8SEH.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 };