@gusnips/react 0.9.24 → 0.9.26

package/dist/api-error.d.ts

@@ -2,9 +2,9 @@ import type { ApiErrorBody } from "@gusnips/http";
 /**
  * A refusal, with the whole envelope intact.
  *
- * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries
- * the parts that make a refusal actionable — the `resetAt` on a 429, the plan that lifts a 402.
- * Keeping all of it means a caller never has to re-parse a response body that has already been
+ * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries the
+ * parts that make a refusal actionable, such as the `resetAt` on a 429 or the plan that lifts a
+ * 402. Keeping all of it means a caller never has to re-parse a response body that has already been
  * read once.
  *
  * A real `class` and not an interface with a factory: one donor used the interface shape, which
@@ -22,16 +22,16 @@ export declare class ApiError extends Error {
      *
      * Read from the `Retry-After` HEADER, which is where HTTP puts it and where a rate limiter
      * written by anyone puts it. The second migration is why this exists: that API sends
-     * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader —
-     * which looked in `details.retryAfterSecs`, the first donor's convention — found nothing, and
-     * both the copy and the retry rule were flying blind on the one refusal that states its own
-     * expiry. Two conventions, same fact; `retryAfterSecs` from `@gusnips/http/retry` reads either.
+     * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader looked in
+     * `details.retryAfterSecs`, the first donor's convention, and found nothing, and both the copy
+     * and the retry rule were flying blind on the one refusal that states its own expiry. Two
+     * conventions, same fact; `retryAfterSecs` from `@gusnips/http/retry` reads either.
      */
     readonly retryAfterSecs: number | undefined;
     /**
-     * The client raised this itself to stop a caller while it was already handling the
-     * situation — today, the 401 thrown after a dead session, where the person is already on
-     * their way to the sign-in page.
+     * The client raised this itself to stop a caller while it was already handling the situation.
+     * Today this is the 401 thrown after a dead session, where the person is already on their way to
+     * the sign-in page.
      *
      * It is control flow, not a fault. Exception reporting should skip it, and an error surface
      * should not ask somebody to retry something that is not broken. One donor had this and it is
@@ -46,7 +46,7 @@ export declare class ApiError extends Error {
     });
 }
 /**
- * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
+ * A request aborted by the caller's own `AbortController` or a navigation that unmounted the
  * component waiting on it.
  *
  * Worth its own predicate because it is the one failure that must NOT be reported, retried or

package/dist/api-error.js

@@ -1,9 +1,9 @@
 /**
  * A refusal, with the whole envelope intact.
  *
- * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries
- * the parts that make a refusal actionable — the `resetAt` on a 429, the plan that lifts a 402.
- * Keeping all of it means a caller never has to re-parse a response body that has already been
+ * `code` is what the UI switches on, `messageKey` is what gets localized, and `details` carries the
+ * parts that make a refusal actionable, such as the `resetAt` on a 429 or the plan that lifts a
+ * 402. Keeping all of it means a caller never has to re-parse a response body that has already been
  * read once.
  *
  * A real `class` and not an interface with a factory: one donor used the interface shape, which
@@ -21,16 +21,16 @@ export class ApiError extends Error {
      *
      * Read from the `Retry-After` HEADER, which is where HTTP puts it and where a rate limiter
      * written by anyone puts it. The second migration is why this exists: that API sends
-     * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader —
-     * which looked in `details.retryAfterSecs`, the first donor's convention — found nothing, and
-     * both the copy and the retry rule were flying blind on the one refusal that states its own
-     * expiry. Two conventions, same fact; `retryAfterSecs` from `@gusnips/http/retry` reads either.
+     * `Retry-After: 60` on every 429 and nothing in its body, so the package's only reader looked in
+     * `details.retryAfterSecs`, the first donor's convention, and found nothing, and both the copy
+     * and the retry rule were flying blind on the one refusal that states its own expiry. Two
+     * conventions, same fact; `retryAfterSecs` from `@gusnips/http/retry` reads either.
      */
     retryAfterSecs;
     /**
-     * The client raised this itself to stop a caller while it was already handling the
-     * situation — today, the 401 thrown after a dead session, where the person is already on
-     * their way to the sign-in page.
+     * The client raised this itself to stop a caller while it was already handling the situation.
+     * Today this is the 401 thrown after a dead session, where the person is already on their way to
+     * the sign-in page.
      *
      * It is control flow, not a fault. Exception reporting should skip it, and an error surface
      * should not ask somebody to retry something that is not broken. One donor had this and it is
@@ -51,7 +51,7 @@ export class ApiError extends Error {
     }
 }
 /**
- * An aborted request — the caller's own `AbortController`, or a navigation that unmounted the
+ * A request aborted by the caller's own `AbortController` or a navigation that unmounted the
  * component waiting on it.
  *
  * Worth its own predicate because it is the one failure that must NOT be reported, retried or

package/dist/auth-email.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The email a person has typed during sign-in, kept so the next auth screen opens with it filled.
+ *
+ * Sign-in, "use a code instead", "forgot password" and "create account" are separate screens, and
+ * each one used to start with an empty email field. Someone who typed their address, then chose
+ * another way in, typed it again. The fix is the same everywhere, so it lives here once.
+ *
+ * ```tsx
+ * <input name="email" type="email" defaultValue={recallAuthEmail()}
+ *   onChange={(event) => rememberAuthEmail(event.currentTarget.value)} />
+ * ```
+ *
+ * - **Not in the URL.** A query string rides in `Referer`, in access logs, in history and in every
+ *   analytics tool that records page addresses. An email is personal data and has no business there.
+ * - **`localStorage`, not `sessionStorage`.** An emailed link opens in a new tab, and a new tab
+ *   does not inherit `sessionStorage`. The person who confirms their account from the mail lands
+ *   on sign-in in that new tab, which is the screen that most needs the address.
+ * - **Thirty minutes, sliding.** Long enough to read a code in a mail client and come back; short
+ *   enough that a shared computer forgets. Every keystroke renews it, and a value found expired is
+ *   deleted when it is read, so it does not sit on disk afterwards.
+ * - **Memory behind it.** A browser that blocks site data throws on `localStorage` itself, and
+ *   React Native has none. The value then lasts until the page (or the app) is left, which still
+ *   covers moving between screens.
+ *
+ * Read it once when a screen opens, as a default value. It is not a live store: nothing re-renders
+ * when it changes, and a prerendered page must read it after hydration, never while rendering.
+ * Never put a password, a code or a token here. Call `forgetAuthEmail()` once a session exists, so
+ * the next person at this browser starts empty.
+ */
+/** The address typed earlier in this sign-in, or an empty string when there is none. */
+export declare function recallAuthEmail(): string;
+/**
+ * Keep what the person has typed. Call it from the email field's change handler, so every screen
+ * they reach next can open with it. The value is stored as typed: trim it where you submit it.
+ * An empty value forgets.
+ */
+export declare function rememberAuthEmail(value: string): void;
+/** Drop it. Call this once a session exists, so the next person at this browser starts empty. */
+export declare function forgetAuthEmail(): void;
+//# sourceMappingURL=auth-email.d.ts.map

package/dist/auth-email.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-email.d.ts","sourceRoot":"","sources":["../src/auth-email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAgDH,wFAAwF;AACxF,wBAAgB,eAAe,IAAI,MAAM,CAQxC;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CASrD;AAED,iGAAiG;AACjG,wBAAgB,eAAe,IAAI,IAAI,CAOtC"}

package/dist/auth-email.js

@@ -0,0 +1,106 @@
+/**
+ * The email a person has typed during sign-in, kept so the next auth screen opens with it filled.
+ *
+ * Sign-in, "use a code instead", "forgot password" and "create account" are separate screens, and
+ * each one used to start with an empty email field. Someone who typed their address, then chose
+ * another way in, typed it again. The fix is the same everywhere, so it lives here once.
+ *
+ * ```tsx
+ * <input name="email" type="email" defaultValue={recallAuthEmail()}
+ *   onChange={(event) => rememberAuthEmail(event.currentTarget.value)} />
+ * ```
+ *
+ * - **Not in the URL.** A query string rides in `Referer`, in access logs, in history and in every
+ *   analytics tool that records page addresses. An email is personal data and has no business there.
+ * - **`localStorage`, not `sessionStorage`.** An emailed link opens in a new tab, and a new tab
+ *   does not inherit `sessionStorage`. The person who confirms their account from the mail lands
+ *   on sign-in in that new tab, which is the screen that most needs the address.
+ * - **Thirty minutes, sliding.** Long enough to read a code in a mail client and come back; short
+ *   enough that a shared computer forgets. Every keystroke renews it, and a value found expired is
+ *   deleted when it is read, so it does not sit on disk afterwards.
+ * - **Memory behind it.** A browser that blocks site data throws on `localStorage` itself, and
+ *   React Native has none. The value then lasts until the page (or the app) is left, which still
+ *   covers moving between screens.
+ *
+ * Read it once when a screen opens, as a default value. It is not a live store: nothing re-renders
+ * when it changes, and a prerendered page must read it after hydration, never while rendering.
+ * Never put a password, a code or a token here. Call `forgetAuthEmail()` once a session exists, so
+ * the next person at this browser starts empty.
+ */
+const KEY = "frontkit.auth-email";
+const TTL_MS = 30 * 60 * 1000;
+/** The longest an address can be (RFC 5321). A longer value is not one, and is not kept. */
+const MAX_LENGTH = 254;
+let memory = null;
+function isSaved(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "email" in value &&
+        typeof value.email === "string" &&
+        "at" in value &&
+        typeof value.at === "number");
+}
+function readStored() {
+    try {
+        const raw = globalThis.localStorage?.getItem(KEY);
+        if (!raw)
+            return null;
+        const parsed = JSON.parse(raw);
+        return isSaved(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Storage and memory are written together, so they only differ when one of them missed a write:
+ * storage that is full keeps an older address while memory holds the new one, and a second tab
+ * writes storage while this tab's memory goes stale. The newer of the two is the one the person
+ * typed last.
+ */
+function newest() {
+    const stored = readStored();
+    if (!stored || !memory)
+        return stored ?? memory;
+    return stored.at >= memory.at ? stored : memory;
+}
+/** The address typed earlier in this sign-in, or an empty string when there is none. */
+export function recallAuthEmail() {
+    const saved = newest();
+    if (!saved)
+        return "";
+    if (Date.now() - saved.at > TTL_MS) {
+        forgetAuthEmail();
+        return "";
+    }
+    return saved.email;
+}
+/**
+ * Keep what the person has typed. Call it from the email field's change handler, so every screen
+ * they reach next can open with it. The value is stored as typed: trim it where you submit it.
+ * An empty value forgets.
+ */
+export function rememberAuthEmail(value) {
+    if (value === "")
+        return forgetAuthEmail();
+    if (value.length > MAX_LENGTH)
+        return;
+    memory = { email: value, at: Date.now() };
+    try {
+        globalThis.localStorage?.setItem(KEY, JSON.stringify(memory));
+    }
+    catch {
+        // Blocked or full: the memory copy above carries it until the page is left.
+    }
+}
+/** Drop it. Call this once a session exists, so the next person at this browser starts empty. */
+export function forgetAuthEmail() {
+    memory = null;
+    try {
+        globalThis.localStorage?.removeItem(KEY);
+    }
+    catch {
+        // Blocked: nothing was stored, so there is nothing to drop.
+    }
+}
+//# sourceMappingURL=auth-email.js.map

package/dist/auth-email.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-email.js","sourceRoot":"","sources":["../src/auth-email.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,MAAM,GAAG,GAAG,qBAAqB,CAAC;AAClC,MAAM,MAAM,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAC9B,4FAA4F;AAC5F,MAAM,UAAU,GAAG,GAAG,CAAC;AAOvB,IAAI,MAAM,GAAiB,IAAI,CAAC;AAEhC,SAAS,OAAO,CAAC,KAAc;IAC7B,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,OAAO,IAAI,KAAK;QAChB,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ;QAC/B,IAAI,IAAI,KAAK;QACb,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ,CAC7B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU;IACjB,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;QAClD,IAAI,CAAC,GAAG;YAAE,OAAO,IAAI,CAAC;QACtB,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACzC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,SAAS,MAAM;IACb,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM;QAAE,OAAO,MAAM,IAAI,MAAM,CAAC;IAChD,OAAO,MAAM,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAClD,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,eAAe;IAC7B,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC;IACvB,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,CAAC;IACtB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,CAAC;QACnC,eAAe,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa;IAC7C,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,eAAe,EAAE,CAAC;IAC3C,IAAI,KAAK,CAAC,MAAM,GAAG,UAAU;QAAE,OAAO;IACtC,MAAM,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;IAC1C,IAAI,CAAC;QACH,UAAU,CAAC,YAAY,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,CAAC;IAAC,MAAM,CAAC;QACP,4EAA4E;IAC9E,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,eAAe;IAC7B,MAAM,GAAG,IAAI,CAAC;IACd,IAAI,CAAC;QACH,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,4DAA4D;IAC9D,CAAC;AACH,CAAC"}

package/dist/auth-store.d.ts

@@ -2,14 +2,14 @@ import { type StoreApi, type UseBoundStore } from "zustand";
 /**
  * Session FLAGS only.
  *
- * Who the person is — their plan, their staff bit, whether they are suspended — comes from
- * `GET /auth/me` through react-query, never from here. Mirroring server state in a client store
- * is how two sources of truth start disagreeing, and the one that is wrong is always the one on
- * screen. Three repos wrote this same store; two of them wrote that same warning in a comment.
+ * Who the person is, including their plan, staff bit and suspension status, comes from `GET
+ * /auth/me` through react-query, never from here. Mirroring server state in a client store is how
+ * two sources of truth start disagreeing, and the one that is wrong is always the one on screen.
+ * Three repos wrote this same store; two of them wrote that same warning in a comment.
  *
  * `TUser` stays generic because it is the one part that differs: one product carries an
- * anonymous-browsing flag, another does not. Keep it to what a GUARD needs — an id and an
- * email is what all three donors had.
+ * anonymous-browsing flag, another does not. Keep it to what a GUARD needs. All three donors had an
+ * id and an email.
  */
 export interface AuthState<TUser> {
     user: TUser | null;
@@ -20,10 +20,10 @@ export interface AuthState<TUser> {
      */
     isLoading: boolean;
     /**
-     * Set (or clear) the signed-in user. This ENDS the loading state — knowing who they are is
-     * what the bootstrap was waiting for. Two of the three donors left `isLoading` alone here and
-     * relied on a separate `setLoading(false)`; forgetting that call leaves every guard spinning,
-     * so the safe default is to do it in one write.
+     * Set (or clear) the signed-in user. This ENDS the loading state, because the bootstrap was
+     * waiting to learn who they are. Two of the three donors left `isLoading` alone here and relied
+     * on a separate `setLoading(false)`; forgetting that call leaves every guard spinning, so the
+     * safe default is to do it in one write.
      */
     setUser: (user: TUser | null) => void;
     setLoading: (isLoading: boolean) => void;
@@ -36,12 +36,12 @@ export interface AuthState<TUser> {
  * The whole reason this is a factory and not a store: `isLoading` must start FALSE where there
  * is no window, and only a factory can decide that at the call site rather than at import.
  *
- * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files
- * with no window at all, so `true` there is a wait that never ends — one donor shipped a route
- * guard holding its loading screen forever, and prerendered a public page as 1,174 bytes of
- * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be
- * found. With no browser there is no session and never will be, which is exactly the state a
- * first-time visitor arrives in, so that is what the page should render.
+ * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files with
+ * no window at all, so `true` there is a wait that never ends. One donor shipped a route guard
+ * holding its loading screen forever, and prerendered a public page as 1,174 bytes of
+ * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be found.
+ * With no browser there is no session and never will be, which is exactly the state a first-time
+ * visitor arrives in, so that is what the page should render.
  *
  * Only one of the three donors knew this. It is invariant 7.
  */
@@ -59,13 +59,13 @@ type AuthSet<TUser, TExtra> = (partial: (TExtra & Partial<AuthState<TUser>>) | P
 /**
  * The session flags as a plain object, for a product whose store needs more than them.
  *
- * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product
- * cannot wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that
- * met it had a superset and neither could use it. One holds a remember-me choice, a profile row
- * and the sign-in methods themselves, under `persist`. The other adds `isAnonymous` — and that
- * one is the reason this takes a `derive` function rather than just letting the caller spread
- * extra keys in: `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and
- * `clear`, which are exactly the two writes the product does not own.
+ * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product cannot
+ * wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that met it had
+ * a superset and neither could use it. One holds a remember-me choice, a profile row and the
+ * sign-in methods themselves, under `persist`. The other adds `isAnonymous`, which is the reason
+ * this takes a `derive` function rather than just letting the caller spread extra keys in:
+ * `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and `clear`, which are
+ * exactly the two writes the product does not own.
  *
  * The caller keeps `create`, so middleware, extra actions and the store's own name stay theirs:
  *

package/dist/auth-store.js

@@ -5,12 +5,12 @@ import { create } from "zustand";
  * The whole reason this is a factory and not a store: `isLoading` must start FALSE where there
  * is no window, and only a factory can decide that at the call site rather than at import.
  *
- * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files
- * with no window at all, so `true` there is a wait that never ends — one donor shipped a route
- * guard holding its loading screen forever, and prerendered a public page as 1,174 bytes of
- * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be
- * found. With no browser there is no session and never will be, which is exactly the state a
- * first-time visitor arrives in, so that is what the page should render.
+ * A session bootstrap can only be in flight in a browser. The BUILD renders this app to files with
+ * no window at all, so `true` there is a wait that never ends. One donor shipped a route guard
+ * holding its loading screen forever, and prerendered a public page as 1,174 bytes of
+ * `role="status"`: a spinner as the indexable body of a page whose entire purpose was to be found.
+ * With no browser there is no session and never will be, which is exactly the state a first-time
+ * visitor arrives in, so that is what the page should render.
  *
  * Only one of the three donors knew this. It is invariant 7.
  */
@@ -20,13 +20,13 @@ export function createAuthStore() {
 /**
  * The session flags as a plain object, for a product whose store needs more than them.
  *
- * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product
- * cannot wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that
- * met it had a superset and neither could use it. One holds a remember-me choice, a profile row
- * and the sign-in methods themselves, under `persist`. The other adds `isAnonymous` — and that
- * one is the reason this takes a `derive` function rather than just letting the caller spread
- * extra keys in: `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and
- * `clear`, which are exactly the two writes the product does not own.
+ * `createAuthStore` owns its `create()` call, which means it owns the whole store: a product cannot
+ * wrap it in `persist`, cannot add an action, and cannot add a field. Both adopters that met it had
+ * a superset and neither could use it. One holds a remember-me choice, a profile row and the
+ * sign-in methods themselves, under `persist`. The other adds `isAnonymous`, which is the reason
+ * this takes a `derive` function rather than just letting the caller spread extra keys in:
+ * `isAnonymous` is read off the user, so it has to be rewritten by `setUser` and `clear`, which are
+ * exactly the two writes the product does not own.
  *
  * The caller keeps `create`, so middleware, extra actions and the store's own name stay theirs:
  *

package/dist/commands.d.ts

@@ -0,0 +1,80 @@
+export interface SlashCommand {
+    /** One token, without the leading slash. */
+    name: string;
+    description: string;
+    /** Other executable names. Tags only help search. */
+    aliases: readonly string[];
+    tags: readonly string[];
+    takesArg?: boolean;
+}
+export interface ParsedCommand {
+    name: string;
+    /** Undefined before a space; empty after a space with no argument yet. */
+    arg?: string;
+}
+/** Multiline text and a slash inside a message are not commands. */
+export declare function parseCommand(text: string): ParsedCommand | null;
+export type CommandResolution<T extends SlashCommand = SlashCommand> = {
+    kind: "matched";
+    command: T;
+} | {
+    kind: "unknown";
+    name: string;
+} | {
+    kind: "ambiguous";
+    name: string;
+    commands: readonly T[];
+};
+/** Exact names win over aliases. Search tags never execute an action. */
+export declare function resolveCommand<T extends SlashCommand>(commands: readonly T[], name: string): CommandResolution<T>;
+/** One row per name, in registry order when two results have the same rank. */
+export declare function matchCommands<T extends SlashCommand>(commands: readonly T[], query: string): T[];
+/** Replace only the name, keeping the argument already typed. */
+export declare function completeCommand(command: SlashCommand, text: string): string;
+export type CommandProblem<T extends SlashCommand = SlashCommand> = Exclude<CommandResolution<T>, {
+    kind: "matched";
+}>;
+export interface CommandOptions<T extends SlashCommand> {
+    text: string;
+    /** Supply only commands allowed here, with current translated descriptions and tags. */
+    commands: readonly T[];
+    onChange: (text: string) => void;
+    /** The app owns authorization, errors, draft cleanup and attachments. */
+    onExecute: (command: T, arg: string | undefined, altKey: boolean) => void;
+    /** Required: show a way back to the available commands, never send this text to the model. */
+    onError: (problem: CommandProblem<T>) => void;
+}
+/** Structural so React events and small test events both fit. */
+export interface CommandKeyEvent {
+    key: string;
+    shiftKey?: boolean;
+    altKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    isComposing?: boolean;
+    keyCode?: number;
+    nativeEvent?: {
+        isComposing?: boolean;
+        keyCode?: number;
+    };
+    preventDefault: () => void;
+}
+export interface SlashCommandMenu<T extends SlashCommand = SlashCommand> {
+    parsed: ParsedCommand | null;
+    open: boolean;
+    items: readonly T[];
+    index: number;
+    active: T | undefined;
+    listId: string;
+    itemId: (command: T) => string;
+    activeId: string | undefined;
+    highlight: (index: number) => void;
+    close: () => void;
+    showAll: () => void;
+    pick: (command: T, altKey?: boolean) => void;
+    submit: (altKey?: boolean) => boolean;
+    handleKeyDown: (event: CommandKeyEvent) => boolean;
+}
+/** A controlled textarea menu. No UI, browser globals, timers or attachment state. */
+export declare function useSlashCommands<T extends SlashCommand>({ text, commands, onChange, onExecute, onError, }: CommandOptions<T>): SlashCommandMenu<T>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../src/commands.ts"],"names":[],"mappings":"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"}

package/dist/commands.js

@@ -0,0 +1,192 @@
+import { useId, useState } from "react";
+/** Multiline text and a slash inside a message are not commands. */
+export function parseCommand(text) {
+    if (/[\r\n\u{2028}\u{2029}]/u.test(text))
+        return null;
+    const match = /^\s*\/(\S*)(?:[^\S\r\n]+(.*))?$/u.exec(text);
+    if (!match)
+        return null;
+    const name = (match[1] ?? "").toLowerCase();
+    return match[2] === undefined ? { name } : { name, arg: match[2] };
+}
+/** Exact names win over aliases. Search tags never execute an action. */
+export function resolveCommand(commands, name) {
+    const token = name.toLowerCase();
+    if (!token)
+        return { kind: "unknown", name };
+    let matches = commands.filter((command) => command.name.toLowerCase() === token);
+    if (matches.length === 0) {
+        matches = commands.filter((command) => command.aliases.some((alias) => alias.toLowerCase() === token));
+    }
+    if (matches.length > 1)
+        return { kind: "ambiguous", name, commands: matches };
+    const command = matches[0];
+    return command ? { kind: "matched", command } : { kind: "unknown", name };
+}
+function searchText(text) {
+    return text.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+}
+function rank(command, query) {
+    if (!query)
+        return 0;
+    const name = searchText(command.name);
+    const aliases = command.aliases.map(searchText);
+    if (name === query)
+        return 0;
+    if (aliases.includes(query))
+        return 1;
+    if (name.startsWith(query))
+        return 2;
+    if (aliases.some((alias) => alias.startsWith(query)))
+        return 3;
+    if (command.tags.some((tag) => searchText(tag).includes(query)))
+        return 4;
+    if (searchText(command.description).includes(query))
+        return 5;
+    return Infinity;
+}
+/** One row per name, in registry order when two results have the same rank. */
+export function matchCommands(commands, query) {
+    const token = searchText(query.trim());
+    const names = new Set();
+    return commands
+        .filter((command) => {
+        const name = command.name.toLowerCase();
+        if (names.has(name))
+            return false;
+        names.add(name);
+        return true;
+    })
+        .map((command) => ({ command, rank: rank(command, token) }))
+        .filter((match) => Number.isFinite(match.rank))
+        .sort((a, b) => a.rank - b.rank)
+        .map((match) => match.command);
+}
+/** Replace only the name, keeping the argument already typed. */
+export function completeCommand(command, text) {
+    const arg = parseCommand(text)?.arg;
+    if (arg !== undefined)
+        return `/${command.name} ${arg}`;
+    return `/${command.name}${command.takesArg ? " " : ""}`;
+}
+/** A controlled textarea menu. No UI, browser globals, timers or attachment state. */
+export function useSlashCommands({ text, commands, onChange, onExecute, onError, }) {
+    const parsed = parseCommand(text);
+    const resolution = parsed ? resolveCommand(commands, parsed.name) : null;
+    const editingName = parsed !== null && (parsed.arg === undefined || resolution?.kind !== "matched");
+    const items = editingName ? matchCommands(commands, parsed.name) : [];
+    const key = JSON.stringify([text, items.map((command) => command.name)]);
+    const [state, setState] = useState({ key, text, index: 0, deliberate: false, dismissed: false });
+    // Reset selection on a changed result set, but keep Escape's dismissal until the draft changes.
+    if (state.key !== key) {
+        setState({
+            key,
+            text,
+            index: 0,
+            deliberate: false,
+            dismissed: state.text === text && state.dismissed,
+        });
+    }
+    const listId = `${useId()}-commands`;
+    const open = editingName && !state.dismissed;
+    const active = open ? items[state.index] : undefined;
+    const itemId = (command) => `${listId}-${encodeURIComponent(command.name)}`;
+    function close() {
+        setState((current) => ({ ...current, dismissed: true }));
+    }
+    function showAll() {
+        setState((current) => ({ ...current, index: 0, deliberate: false, dismissed: false }));
+        onChange("/");
+    }
+    function highlight(index) {
+        if (!items[index])
+            return;
+        setState((current) => ({ ...current, index, deliberate: true }));
+    }
+    function pick(command, altKey = false) {
+        // Re-resolve against current capabilities, not a descriptor retained by a caller.
+        const selected = resolveCommand(commands, command.name);
+        if (selected.kind !== "matched") {
+            onError(selected);
+            return;
+        }
+        if (selected.command.takesArg || parsed?.arg) {
+            onChange(completeCommand(selected.command, text));
+            return;
+        }
+        onExecute(selected.command, parsed?.arg, altKey);
+    }
+    /** Call before the normal send/queue/quota path, including button and imperative submits. */
+    function submit(altKey = false) {
+        if (!parsed || !resolution)
+            return false;
+        if (resolution.kind !== "matched") {
+            onError(resolution);
+            return true;
+        }
+        if (resolution.command.takesArg &&
+            parsed.arg === undefined &&
+            parsed.name !== resolution.command.name.toLowerCase()) {
+            onChange(completeCommand(resolution.command, text));
+            return true;
+        }
+        onExecute(resolution.command, parsed.arg, altKey);
+        return true;
+    }
+    /** Call first. True means skip your own key handler; IME still gets the browser's default. */
+    function handleKeyDown(event) {
+        const native = event.nativeEvent ?? event;
+        if (native.isComposing || native.keyCode === 229)
+            return true;
+        if (event.shiftKey)
+            return false;
+        if (open && event.key === "Escape") {
+            event.preventDefault();
+            close();
+            return true;
+        }
+        if (open && items.length > 0 && !event.ctrlKey && !event.metaKey) {
+            if (event.key === "ArrowDown" || event.key === "ArrowUp") {
+                event.preventDefault();
+                const step = event.key === "ArrowDown" ? 1 : -1;
+                highlight((state.index + step + items.length) % items.length);
+                return true;
+            }
+            if (active && (event.key === "Enter" || event.key === "Tab")) {
+                event.preventDefault();
+                if (event.key === "Tab") {
+                    onChange(completeCommand(active, text));
+                }
+                else if (resolution?.kind === "ambiguous" && !state.deliberate) {
+                    onError(resolution);
+                }
+                else {
+                    pick(active, event.altKey);
+                }
+                return true;
+            }
+        }
+        if (parsed && event.key === "Enter") {
+            event.preventDefault();
+            return submit(event.altKey);
+        }
+        return false;
+    }
+    return {
+        parsed,
+        open,
+        items,
+        index: state.index,
+        active,
+        listId,
+        itemId,
+        activeId: active ? itemId(active) : undefined,
+        highlight,
+        close,
+        showAll,
+        pick,
+        submit,
+        handleKeyDown,
+    };
+}
+//# sourceMappingURL=commands.js.map