@enigmax/primitives 0.17.0 → 0.19.0

package/src/core/search.ts

@@ -106,6 +106,61 @@ function substringMatcher<T>(query: string, items: readonly T[], keys: string[])
     return results.sort((left, right) => left.score - right.score);
 }
 
+/**
+ * Subsequence ranking: every letter of the query, in order, anywhere in the text.
+ *
+ * This is what a COMMAND palette wants and a substring filter cannot do: "qgate" finds
+ * "Quality gate" and "plyg" finds "Playground", because the letters only have to appear in
+ * order. The score rewards consecutive runs and word starts and penalises gaps, so the
+ * closest thing to what was typed comes first rather than the first thing that happened to
+ * contain the letters.
+ *
+ * Pass it as `matcher`, or take it as the default from the palette. The substring matcher
+ * stays the default for a plain search FIELD, where a typo should fail rather than quietly
+ * match something four words away.
+ */
+export function subsequenceMatcher<T>(keys: string[] = []): NonNullable<SearchOptions<T>["matcher"]> {
+    return (query, items) => {
+        const needle = fold(query);
+        const results: SearchMatch<T>[] = [];
+
+        for (const item of items) {
+            const fields = keys.length ? keys : [""];
+            let best: SearchMatch<T> | null = null;
+
+            for (const key of fields) {
+                const haystack = fold(key ? readPath(item, key) : String(item));
+                const score = subsequenceScore(needle, haystack);
+                if (score < 0) continue;
+                // The engine orders by ASCENDING score (Fuse's convention, 0 is exact), and
+                // this one counts upwards, so it is negated rather than compared backwards -
+                // getting that wrong ranks the worst match first and looks like a broken
+                // search rather than a sign error.
+                const ranked = -score;
+                if (!best || ranked < best.score) best = { item, score: ranked, key: key || undefined };
+            }
+            if (best) results.push(best);
+        }
+
+        return results.sort((left, right) => left.score - right.score);
+    };
+}
+
+/** -1 when the query is not a subsequence of the text; otherwise higher is better. */
+function subsequenceScore(query: string, text: string): number {
+    if (!query) return 0;
+    let from = 0, score = 0, run = 0;
+    for (let i = 0; i < query.length; i++) {
+        const at = text.indexOf(query[i], from);
+        if (at === -1) return -1;
+        run = i > 0 && at === from ? run + 1 : 0;
+        const wordStart = at === 0 || /[^a-z0-9]/.test(text[at - 1]);
+        score += 10 + run * 6 + (wordStart ? 8 : 0) - Math.min(at - from, 6);
+        from = at + 1;
+    }
+    return score;
+}
+
 export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<T> {
     let opts: SearchOptions<T> = { ...options };
     let items: readonly T[] = opts.items ?? [];
@@ -205,6 +260,11 @@ export function createSearch<T>(options: SearchOptions<T> = {}): SearchInstance<
             input.addEventListener("input", onInput);
             input.addEventListener("keydown", onKeyDown);
             input.dataset.enigmaSearch = "";
+            // A field can already hold a value when the engine reaches it: a query restored
+            // from the URL, a browser refill, or simply someone typing before the module
+            // that searches finished loading. Binding without reading it leaves the field
+            // full and the list empty until the NEXT keystroke, which reads as broken.
+            if (input.value) this.searchNow(input.value);
             return () => {
                 input.removeEventListener("input", onInput);
                 input.removeEventListener("keydown", onKeyDown);

package/src/index.ts

@@ -1,6 +1,6 @@
 export { createMarquee, type MarqueeOptions, type MarqueeInstance, type MarqueeHover } from "@/core/marquee";
 export { createInput, type InputOptions, type InputInstance, type InputAction, type InputIcon, type InputActionState } from "@/core/input";
-export { createSearch, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
+export { createSearch, subsequenceMatcher, type SearchOptions, type SearchInstance, type SearchMatch, type FuseConstructor, type FuseLike } from "@/core/search";
 export { createButton, type ButtonOptions, type ButtonInstance, type ButtonState, type ButtonElement, type ButtonCooldown } from "@/core/button";
 export { INPUT_ICON_PATHS, iconMarkup } from "@/core/input";
 export {
@@ -31,13 +31,13 @@ export {
     flagSrc,
     flagView,
     flagAttributes,
+    flagName,
     normalizeFlagCode,
     configureFlags,
     flagConfig,
     resetFlagConfig,
     FLAG_RATIO,
-    FLAG_ICONS_VERSION,
-    CIRCLE_FLAGS_REF,
+    FLAG_CDN,
     type FlagOptions,
     type FlagConfig,
     type FlagView,
@@ -45,3 +45,19 @@ export {
     type FlagFormat,
     type FlagSource
 } from "@/core/flags";
+// The palette's non-rendering half: no framework anywhere near it, so a vanilla or Astro
+// page can run the same keyboard arithmetic, grouping and history the React palette does.
+export {
+    createRecentStore,
+    recentKey,
+    groupRows,
+    moveActive,
+    shortcutLabel,
+    isPaletteShortcut,
+    type RecentEntry,
+    type RecentStore,
+    type RecentStoreOptions,
+    type RowGroup,
+    type PositionedRow,
+    type PaletteKey
+} from "@/core/palette";

package/src/react/button.tsx

@@ -1,9 +1,10 @@
 "use client";
 
+import { Slot } from "@/react/slot";
 import { useButton } from "@/react/use-button";
 import { getLinkComponent } from "@/react/link";
 import type { ButtonOptions, ButtonState } from "@/core/button";
-import { createElement, forwardRef, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from "react";
+import { createElement, forwardRef, isValidElement, type ComponentPropsWithoutRef, type ElementType, type ReactNode } from "react";
 
 /**
  * `<Button>` - the component, for the ninety percent.
@@ -51,6 +52,49 @@ export interface ButtonProps extends ButtonOptions, Omit<ComponentPropsWithoutRe
     pending?: ReactNode;
     /** `type` on a real button. Ignored on a link, which has none. */
     type?: "button" | "submit" | "reset";
+    /**
+     * Show the shortcut as a key badge after the label, the way Stripe writes
+     * "Create invoice n".
+     *
+     * `"auto"` (the default) shows it when there is a shortcut AND the label renders text:
+     * beside a lone glyph on an icon-only button the badge is noise, and it would double the
+     * width of the smallest control on the screen. `true` and `false` decide it outright.
+     */
+    shortcutHint?: boolean | "auto";
+    /** Render the badge yourself. Return null to drop it for one button. */
+    renderShortcut?: (key: string) => ReactNode;
+    /**
+     * Put the behaviour on YOUR element instead of ours - a `motion.button`, your design
+     * system's button, a router Link, anything.
+     *
+     * ```tsx
+     * <Button asChild cooldown={30_000} onPress={resend}>
+     *     <motion.button whileTap={{ scale: 0.98 }}>Resend</motion.button>
+     * </Button>
+     * ```
+     *
+     * The child owns its own markup, so the shortcut badge is not injected - the child is
+     * rendered exactly as written. Read `state.shortcut` from `useButton` to place your own.
+     */
+    asChild?: boolean;
+}
+
+/**
+ * Whether a label renders any TEXT.
+ *
+ * Walked rather than assumed: `<Button shortcut="s"><Icon /></Button>` and
+ * `<Button shortcut="s"><Icon /> Save</Button>` differ only in a string buried in the tree,
+ * and that string is the whole difference between a hint and a decoration. An element whose
+ * text arrives from somewhere this cannot see reports false, so `auto` errs towards the
+ * quieter button; `shortcutHint` overrides it in one word.
+ */
+function hasText(node: ReactNode): boolean {
+    if (node === null || node === undefined || typeof node === "boolean") return false;
+    if (typeof node === "string") return node.trim().length > 0;
+    if (typeof node === "number") return true;
+    if (Array.isArray(node)) return node.some(hasText);
+    if (isValidElement(node)) return hasText((node.props as { children?: ReactNode; }).children);
+    return false;
 }
 
 export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
@@ -66,6 +110,9 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
     onClick,
     onChange,
     type = "button",
+    shortcutHint = "auto",
+    renderShortcut,
+    asChild = false,
     ...rest
 }, ref) {
     const button = useButton({ href, disabled, loading, cooldown, shortcut, onPress: onPress ?? onClick, onChange });
@@ -75,17 +122,36 @@ export const Button = forwardRef<HTMLElement, ButtonProps>(function Button({
     // to setLinkComponent - and a plain <a> when nothing was. The package cannot import a
     // router itself, so registering one is what turns every href into a client navigation
     // without a word at the call site.
-    const Tag: ElementType = as ?? (state.element === "a" ? getLinkComponent() : "button");
+    const Tag: ElementType = asChild ? Slot : as ?? (state.element === "a" ? getLinkComponent() : "button");
 
     // `type="button"` is the default on purpose. A bare <button> inside a form submits it,
-    // so an action button that forgot it posts the form instead of doing its job.
+    // so an action button that forgot it posts the form instead of doing its job. Never
+    // injected through a slot: the child may be an anchor or a div, where `type` is either
+    // invalid or means something else entirely.
     const native = Tag === "button" ? { type } : {};
 
     const label = typeof children === "function" ? children(state) : children;
+    const content = state.loading && pending !== undefined ? pending : label;
+
+    // Not while it is working: the label has already been replaced by whatever `pending`
+    // says, and a key that does nothing right now is not a hint.
+    // Never through a slot: it takes exactly one child, and a second one would throw.
+    const showHint = !asChild && Boolean(state.shortcut) && !state.loading &&
+        (shortcutHint === "auto" ? hasText(content) : shortcutHint);
+    const hint = showHint && state.shortcut
+        ? renderShortcut?.(state.shortcut) ?? createElement(
+            "kbd",
+            // Hidden from the accessible name - the button already carries
+            // `aria-keyshortcuts`, and "Save n" is not what anyone wants read out.
+            { "data-enigma-button-key": "", "aria-hidden": true },
+            state.shortcut
+        )
+        : null;
 
     return createElement(
         Tag,
         { ref, ...button.props, ...native, ...rest },
-        state.loading && pending !== undefined ? pending : label
+        content,
+        hint
     );
 });

package/src/react/flag.tsx

@@ -7,10 +7,17 @@ export interface FlagProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "sr
     /** `es`, `ES`, `en-GB`, `gb-eng`, or the emoji flag you are replacing. */
     code: string | null | undefined;
     /**
-     * The accessible name. Leave it out and the flag is decorative, which is what it is
-     * beside a country name - the reader hears the name once instead of twice.
+     * Your own accessible name. Left out, the country's own name is used, in the reader's
+     * language - so a flag standing on its own is never a silent image.
      */
     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;
+    /** Language the automatic name is written in. Follows the document's `lang` otherwise. */
+    locale?: string;
     shape?: FlagShape;
     format?: FlagFormat;
     source?: FlagSource;
@@ -28,8 +35,8 @@ export interface FlagProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "sr
  * The defaults come from `configureFlags`, so moving the whole application from the CDN to
  * a downloaded set is one line at startup and no change at any call site.
  */
-export function Flag({ code, label, shape, format, source, basePath, size, fallback = null, ...rest }: FlagProps): ReactNode {
-    const options: FlagOptions = { shape, format, source, basePath, size };
+export function Flag({ code, label, decorative = false, locale, shape, format, source, basePath, size, fallback = null, ...rest }: FlagProps): ReactNode {
+    const options: FlagOptions = { shape, format, source, basePath, size, locale };
     // An explicit `undefined` prop must not beat the configured default, so the unset ones
     // are dropped rather than spread over the config.
     for (const key of Object.keys(options) as (keyof FlagOptions)[]) {
@@ -39,16 +46,21 @@ export function Flag({ code, label, shape, format, source, basePath, size, fallb
     const view = flagView(code, options);
     if (!view) return fallback;
 
-    const name = label?.trim();
+    // Automatic unless told otherwise: the country's own name, in the reader's language.
+    const name = decorative ? "" : label?.trim() || view.name || "";
     return (
         <img
             src={view.src}
-            alt={name ?? ""}
+            alt={name}
             width={view.width}
             height={view.height}
             loading="lazy"
             decoding="async"
             aria-hidden={name ? undefined : true}
+            // The name comes from the reader's own runtime, so a server render and its
+            // hydration can legitimately disagree on the language it is written in. Same
+            // escape hatch, and same reason, as the relative timestamp.
+            suppressHydrationWarning
             data-enigma-flag=""
             data-flag-code={view.code}
             data-flag-shape={view.shape}

package/src/react/index.ts

@@ -10,16 +10,23 @@ export { useButton, type UseButtonResult } from "@/react/use-button";
 export { Button, type ButtonProps } from "@/react/button";
 export { setLinkComponent, getLinkComponent } from "@/react/link";
 export { type ButtonOptions, type ButtonState } from "@/core/button";
+export { Input } from "@/react/input";
 export {
-    Input,
-    PasswordStrength,
     type InputProps,
-    type PasswordStrengthProps,
+    type InputBaseProps,
+    type InputType,
     type FieldAction,
     type BreachChecker,
     type BreachState,
-    type BreachStatus
-} from "@/react/input";
+    type BreachStatus,
+    type PasswordOnlyProps,
+    type SearchOnlyProps,
+    type PlainOnlyProps
+} from "@/react/input/types";
+// The meter as a standalone component, for a form that renders it somewhere else. Re-exported
+// from the chunk rather than through `Input`, so importing only `Input` leaves it behind.
+export { PasswordStrength, type PasswordStrengthProps } from "@/react/input/password";
+export { Slot, mergeSlotProps, type SlotProps } from "@/react/slot";
 export {
     generatePassword,
     estimatePasswordStrength,
@@ -33,11 +40,22 @@ export { Toaster, type ToasterProps, type ToastPosition, type ToastControls } fr
 export { useNetworkState } from "@/react/use-network-state";
 export { type NetworkState } from "@/core/network";
 export { RelativeTime, type RelativeTimeProps } from "@/react/relative-time";
+// The option types too: a wrapper around any of these has to be able to name its own props.
+export type {
+    RelativeTimeOptions,
+    RelativeTimeFormat,
+    RelativeTimeTense,
+    RelativeTimePrecision,
+    RelativeTimeStyle
+} from "@/core/relative-time";
+export type { NotificationTone, NotificationAction, NotificationInput, Notification, NotificationsOptions } from "@/core/notifications";
+export type { SearchInstance, FuseLike } from "@/core/search";
 export { Flag, type FlagProps } from "@/react/flag";
 export {
     flagSrc,
     flagView,
     flagAttributes,
+    flagName,
     normalizeFlagCode,
     configureFlags,
     type FlagOptions,
@@ -45,3 +63,30 @@ export {
     type FlagFormat,
     type FlagSource
 } from "@/core/flags";
+export {
+    SearchPalette,
+    PaletteRoot,
+    PaletteTrigger,
+    PaletteContent,
+    PaletteField,
+    PaletteList,
+    PaletteItem,
+    PaletteFooter,
+    usePaletteContext,
+    type SearchPaletteProps,
+    type PaletteRootProps,
+    type PaletteListProps,
+    type PaletteSection,
+    type PaletteRow,
+    type PaletteContextValue
+} from "@/react/palette";
+export {
+    createRecentStore,
+    recentKey,
+    groupRows,
+    moveActive,
+    shortcutLabel,
+    isPaletteShortcut,
+    type RecentEntry,
+    type RecentStore
+} from "@/core/palette";

package/src/react/input/icon.tsx

@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+
+/**
+ * The built-in glyphs, drawn from the shared path data.
+ *
+ * Stroked with `currentColor` at 1em, so an icon inherits the field's text colour and size
+ * and needs no styling of its own. Replacing one is a `FieldAction` with the same `name`.
+ */
+const ICON_PROPS = {
+    viewBox: "0 0 24 24", width: "1em", height: "1em", fill: "none",
+    stroke: "currentColor", strokeWidth: 2, strokeLinecap: "round", strokeLinejoin: "round",
+    "aria-hidden": true
+} as const;
+
+export function Icon({ paths }: { paths: readonly string[]; }): ReactNode {
+    return <svg {...ICON_PROPS}>{paths.map((path) => <path key={path} d={path} />)}</svg>;
+}