@hjmds/design-contracts 0.8.2

package/dist/load-more.js

@@ -0,0 +1,124 @@
+export const loadMoreBehaviorDefaults = {
+    mode: "automatic",
+};
+function assertNonEmpty(value, field) {
+    if (value.trim().length === 0) {
+        throw new TypeError(`LoadMore ${field} must not be empty`);
+    }
+}
+export function validateLoadMoreState(state) {
+    const runtimeStatus = state.status;
+    if (runtimeStatus !== "ready" &&
+        runtimeStatus !== "loading" &&
+        runtimeStatus !== "error" &&
+        runtimeStatus !== "complete") {
+        throw new TypeError(`Unsupported LoadMore status: ${String(runtimeStatus)}`);
+    }
+    if (state.status === "complete")
+        return;
+    assertNonEmpty(state.requestKey, "requestKey");
+    if (state.requestKey !== state.requestKey.trim()) {
+        throw new TypeError("LoadMore requestKey must not start or end with whitespace");
+    }
+    if (state.status === "error")
+        assertNonEmpty(state.message, "message");
+}
+export function validateLoadMoreLabels(labels) {
+    if (labels === null || typeof labels !== "object") {
+        throw new TypeError("LoadMore labels must be an object");
+    }
+    for (const field of ["loadMore", "loading", "retry", "complete"]) {
+        const value = labels[field];
+        if (typeof value !== "string" || value.trim().length === 0) {
+            throw new TypeError(`LoadMore labels.${field} must not be empty`);
+        }
+    }
+}
+export function validateLoadMoreDescriptor(descriptor) {
+    validateLoadMoreState(descriptor.state);
+    validateLoadMoreLabels(descriptor.labels);
+}
+export function canRequestLoadMore(state, mode, reason) {
+    validateLoadMoreState(state);
+    if (mode !== "automatic" && mode !== "manual") {
+        throw new TypeError(`Unsupported LoadMore mode: ${String(mode)}`);
+    }
+    if (reason !== "viewport" && reason !== "manual" && reason !== "retry") {
+        throw new TypeError(`Unsupported LoadMore request reason: ${String(reason)}`);
+    }
+    if (reason === "viewport") {
+        return mode === "automatic" && state.status === "ready";
+    }
+    if (reason === "manual")
+        return state.status === "ready";
+    return state.status === "error";
+}
+/**
+ * Prevents duplicate and out-of-order page requests without owning collection
+ * data. Query state remains product-owned; this controller only gates events.
+ */
+export function createLoadMoreController(options) {
+    const mode = options.mode ?? loadMoreBehaviorDefaults.mode;
+    if (mode !== "automatic" && mode !== "manual") {
+        throw new TypeError(`Unsupported LoadMore mode: ${String(mode)}`);
+    }
+    if (typeof options.onLoadMore !== "function") {
+        throw new TypeError("LoadMore onLoadMore must be a function");
+    }
+    let inFlightRequestKey = null;
+    let disposed = false;
+    let cachedSnapshot = null;
+    const snapshot = () => {
+        cachedSnapshot ??= { mode, inFlightRequestKey, disposed };
+        return cachedSnapshot;
+    };
+    const invalidate = () => {
+        cachedSnapshot = null;
+    };
+    return {
+        getSnapshot: snapshot,
+        async request(state, reason) {
+            if (disposed)
+                throw new Error("Cannot use a disposed LoadMore controller");
+            if (!canRequestLoadMore(state, mode, reason)) {
+                return reason === "viewport" && mode === "manual"
+                    ? "blocked-by-mode"
+                    : "blocked-by-state";
+            }
+            // `canRequestLoadMore` rejects complete, but keep the discriminant local
+            // so emitted types never treat its absent requestKey as a valid cursor.
+            if (state.status === "complete")
+                return "blocked-by-state";
+            if (inFlightRequestKey !== null)
+                return "already-requesting";
+            const requestKey = state.requestKey;
+            inFlightRequestKey = requestKey;
+            invalidate();
+            try {
+                const pending = options.onLoadMore({ requestKey, reason });
+                if (pending === null ||
+                    typeof pending !== "object" ||
+                    typeof pending.then !== "function") {
+                    throw new TypeError("LoadMore onLoadMore must return a Promise that settles with the page request");
+                }
+                await pending;
+                return "started";
+            }
+            finally {
+                if (inFlightRequestKey === requestKey) {
+                    inFlightRequestKey = null;
+                    invalidate();
+                }
+            }
+        },
+        dispose() {
+            if (disposed)
+                return false;
+            disposed = true;
+            inFlightRequestKey = null;
+            invalidate();
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=load-more.js.map

package/dist/load-more.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-more.js","sourceRoot":"","sources":["../src/load-more.ts"],"names":[],"mappings":"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","sourcesContent":["export type LoadMoreMode = \"automatic\" | \"manual\";\nexport type LoadMoreRequestReason = \"viewport\" | \"manual\" | \"retry\";\n\nexport type LoadMoreReadyState = Readonly<{\n  status: \"ready\";\n  requestKey: string;\n}>;\n\nexport type LoadMoreLoadingState = Readonly<{\n  status: \"loading\";\n  requestKey: string;\n}>;\n\nexport type LoadMoreErrorState = Readonly<{\n  status: \"error\";\n  requestKey: string;\n  message: string;\n}>;\n\nexport type LoadMoreCompleteState = Readonly<{\n  status: \"complete\";\n  requestKey?: never;\n}>;\n\n/** Existing collection items stay mounted while this footer state changes. */\nexport type LoadMoreState =\n  | LoadMoreReadyState\n  | LoadMoreLoadingState\n  | LoadMoreErrorState\n  | LoadMoreCompleteState;\n\nexport type LoadMoreRequest = Readonly<{\n  requestKey: string;\n  reason: LoadMoreRequestReason;\n}>;\n\nexport type LoadMoreLabels = Readonly<{\n  loadMore: string;\n  loading: string;\n  retry: string;\n  complete: string;\n}>;\n\nexport type LoadMoreDescriptor = Readonly<{\n  state: LoadMoreState;\n  labels: LoadMoreLabels;\n}>;\n\nexport type LoadMoreRequestHandler = (\n  request: LoadMoreRequest,\n) => Promise<void>;\n\nexport type LoadMoreRequestOutcome =\n  | \"started\"\n  | \"blocked-by-mode\"\n  | \"blocked-by-state\"\n  | \"already-requesting\";\n\nexport type LoadMoreControllerOptions = Readonly<{\n  mode?: LoadMoreMode;\n  onLoadMore: LoadMoreRequestHandler;\n}>;\n\nexport type LoadMoreControllerSnapshot = Readonly<{\n  mode: LoadMoreMode;\n  inFlightRequestKey: string | null;\n  disposed: boolean;\n}>;\n\nexport type LoadMoreController = Readonly<{\n  getSnapshot(): LoadMoreControllerSnapshot;\n  request(\n    state: LoadMoreState,\n    reason: LoadMoreRequestReason,\n  ): Promise<LoadMoreRequestOutcome>;\n  dispose(): boolean;\n}>;\n\nexport const loadMoreBehaviorDefaults = {\n  mode: \"automatic\",\n} as const satisfies Readonly<{ mode: LoadMoreMode }>;\n\nfunction assertNonEmpty(value: string, field: string): void {\n  if (value.trim().length === 0) {\n    throw new TypeError(`LoadMore ${field} must not be empty`);\n  }\n}\n\nexport function validateLoadMoreState(state: LoadMoreState): void {\n  const runtimeStatus = (state as Readonly<{ status?: unknown }>).status;\n  if (\n    runtimeStatus !== \"ready\" &&\n    runtimeStatus !== \"loading\" &&\n    runtimeStatus !== \"error\" &&\n    runtimeStatus !== \"complete\"\n  ) {\n    throw new TypeError(`Unsupported LoadMore status: ${String(runtimeStatus)}`);\n  }\n  if (state.status === \"complete\") return;\n  assertNonEmpty(state.requestKey, \"requestKey\");\n  if (state.requestKey !== state.requestKey.trim()) {\n    throw new TypeError(\"LoadMore requestKey must not start or end with whitespace\");\n  }\n  if (state.status === \"error\") assertNonEmpty(state.message, \"message\");\n}\n\nexport function validateLoadMoreLabels(labels: LoadMoreLabels): void {\n  if (labels === null || typeof labels !== \"object\") {\n    throw new TypeError(\"LoadMore labels must be an object\");\n  }\n  for (const field of [\"loadMore\", \"loading\", \"retry\", \"complete\"] as const) {\n    const value = labels[field];\n    if (typeof value !== \"string\" || value.trim().length === 0) {\n      throw new TypeError(`LoadMore labels.${field} must not be empty`);\n    }\n  }\n}\n\nexport function validateLoadMoreDescriptor(descriptor: LoadMoreDescriptor): void {\n  validateLoadMoreState(descriptor.state);\n  validateLoadMoreLabels(descriptor.labels);\n}\n\nexport function canRequestLoadMore(\n  state: LoadMoreState,\n  mode: LoadMoreMode,\n  reason: LoadMoreRequestReason,\n): boolean {\n  validateLoadMoreState(state);\n  if (mode !== \"automatic\" && mode !== \"manual\") {\n    throw new TypeError(`Unsupported LoadMore mode: ${String(mode)}`);\n  }\n  if (reason !== \"viewport\" && reason !== \"manual\" && reason !== \"retry\") {\n    throw new TypeError(`Unsupported LoadMore request reason: ${String(reason)}`);\n  }\n  if (reason === \"viewport\") {\n    return mode === \"automatic\" && state.status === \"ready\";\n  }\n  if (reason === \"manual\") return state.status === \"ready\";\n  return state.status === \"error\";\n}\n\n/**\n * Prevents duplicate and out-of-order page requests without owning collection\n * data. Query state remains product-owned; this controller only gates events.\n */\nexport function createLoadMoreController(\n  options: LoadMoreControllerOptions,\n): LoadMoreController {\n  const mode = options.mode ?? loadMoreBehaviorDefaults.mode;\n  if (mode !== \"automatic\" && mode !== \"manual\") {\n    throw new TypeError(`Unsupported LoadMore mode: ${String(mode)}`);\n  }\n  if (typeof options.onLoadMore !== \"function\") {\n    throw new TypeError(\"LoadMore onLoadMore must be a function\");\n  }\n\n  let inFlightRequestKey: string | null = null;\n  let disposed = false;\n  let cachedSnapshot: LoadMoreControllerSnapshot | null = null;\n\n  const snapshot = (): LoadMoreControllerSnapshot => {\n    cachedSnapshot ??= { mode, inFlightRequestKey, disposed };\n    return cachedSnapshot;\n  };\n  const invalidate = () => {\n    cachedSnapshot = null;\n  };\n\n  return {\n    getSnapshot: snapshot,\n    async request(state, reason) {\n      if (disposed) throw new Error(\"Cannot use a disposed LoadMore controller\");\n      if (!canRequestLoadMore(state, mode, reason)) {\n        return reason === \"viewport\" && mode === \"manual\"\n          ? \"blocked-by-mode\"\n          : \"blocked-by-state\";\n      }\n      // `canRequestLoadMore` rejects complete, but keep the discriminant local\n      // so emitted types never treat its absent requestKey as a valid cursor.\n      if (state.status === \"complete\") return \"blocked-by-state\";\n      if (inFlightRequestKey !== null) return \"already-requesting\";\n\n      const requestKey = state.requestKey;\n      inFlightRequestKey = requestKey;\n      invalidate();\n      try {\n        const pending = options.onLoadMore({ requestKey, reason });\n        if (\n          pending === null ||\n          typeof pending !== \"object\" ||\n          typeof (pending as Readonly<{ then?: unknown }>).then !== \"function\"\n        ) {\n          throw new TypeError(\n            \"LoadMore onLoadMore must return a Promise that settles with the page request\",\n          );\n        }\n        await pending;\n        return \"started\";\n      } finally {\n        if (inFlightRequestKey === requestKey) {\n          inFlightRequestKey = null;\n          invalidate();\n        }\n      }\n    },\n    dispose() {\n      if (disposed) return false;\n      disposed = true;\n      inFlightRequestKey = null;\n      invalidate();\n      return true;\n    },\n  };\n}\n"]}

package/dist/mentions.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `docs/mentions.md`'s "이게 새 컴포넌트인가" verdict: Mentions is a `TextArea`
+ * whose candidate popup is Combobox's existing listbox contract
+ * (`comboboxRecipe`, `behaviorRegistry.combobox`) verbatim — arrow-key
+ * navigation, typeahead-free filtering, loading/empty/error announcement are
+ * already owned there and this module does not redeclare them. The one piece
+ * neither owns is *finding the trigger inside free-form text and computing
+ * what range gets replaced on commit* — that is genuinely new, and it is all
+ * this module contains.
+ */
+export type MentionTriggerConfig<TriggerId extends string = string> = Readonly<{
+    id: TriggerId;
+    /** Exactly one non-whitespace character, e.g. "@" or "#". */
+    trigger: string;
+}>;
+export type MentionMatch<TriggerId extends string = string> = Readonly<{
+    triggerId: TriggerId;
+    trigger: string;
+    /** UTF-16 code unit offset of the trigger character itself in `text`. */
+    triggerStart: number;
+    /** Text between the trigger and the cursor — drives candidate filtering. */
+    query: string;
+}>;
+/**
+ * Rejects the configuration shapes a naive Mentions implementation would
+ * accept and then fail on later: an empty trigger list (nothing to detect),
+ * a multi-character or whitespace trigger (the scan below assumes exactly one
+ * non-whitespace code unit), and two configs racing on the same character or
+ * id.
+ */
+export declare function validateMentionTriggers<TriggerId extends string>(triggers: readonly MentionTriggerConfig<TriggerId>[]): void;
+/**
+ * Scans left from the cursor for the nearest trigger character that starts a
+ * token (start-of-text or preceded by whitespace) with no whitespace between
+ * it and the cursor. The whitespace-between check is what must reject
+ * `"user@example.com"` — the char before `@` is `r`, not whitespace/start —
+ * and cancel an already-open mention the moment the user types a space, the
+ * same convention every mention UI (Slack, Discord, GitHub) uses so the query
+ * can never run away across word boundaries. Operating on the resolved text
+ * value and a single cursor offset (never individual keystrokes) is also why
+ * Hangul composition needs no special-casing here: a composing jamo is
+ * already a valid code point in that string the moment `onChange` fires,
+ * composed or not.
+ */
+export declare function findActiveMentionTrigger<TriggerId extends string>(text: string, cursorPosition: number, triggers: readonly MentionTriggerConfig<TriggerId>[]): MentionMatch<TriggerId> | null;
+export type MentionInsertionResult = Readonly<{
+    text: string;
+    /** Caret offset immediately after the inserted mention and its trailing space. */
+    cursorPosition: number;
+}>;
+/**
+ * Replaces `[match.triggerStart, cursorPosition)` — the trigger character
+ * through wherever the caret sits now — with the trigger plus the product's
+ * display text plus a trailing space, so typing can continue without fusing
+ * into the mention. The trigger character is always prepended here, not by
+ * the caller, so it can never be forgotten or duplicated.
+ */
+export declare function resolveMentionInsertion<TriggerId extends string>(text: string, match: MentionMatch<TriggerId>, cursorPosition: number, insertedText: string): MentionInsertionResult;
+/**
+ * No new recipe or behaviorRegistry entry: the popup is
+ * `behaviorRegistry.combobox` verbatim (roles, keyboard, dismiss, the
+ * `ime-composition-does-not-prematurely-filter-or-commit` scenario already
+ * covers composed text), layered on a plain `TextArea`. These scenarios are
+ * the trigger-detection slice combobox's list does not already cover.
+ */
+export declare const mentionsBehaviorScenarios: readonly ["trigger-preceded-by-a-non-whitespace-character-does-not-open-the-popup", "typing-a-space-after-the-trigger-closes-the-popup-without-committing", "empty-query-right-after-the-trigger-is-a-valid-active-match", "ime-composition-updates-the-query-like-any-other-text-change-no-special-casing-needed", "commit-always-inserts-the-trigger-character-exactly-once", "commit-replaces-exactly-the-trigger-through-the-current-cursor-nothing-before-or-after", "two-configured-triggers-never-share-a-character-or-an-id", "the-nearer-trigger-to-the-cursor-wins-when-an-earlier-token-also-looks-like-a-trigger"];
+//# sourceMappingURL=mentions.d.ts.map

package/dist/mentions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.d.ts","sourceRoot":"","sources":["../src/mentions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IAC7E,EAAE,EAAE,SAAS,CAAC;IACd,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,YAAY,CAAC,SAAS,SAAS,MAAM,GAAG,MAAM,IAAI,QAAQ,CAAC;IACrE,SAAS,EAAE,SAAS,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAMH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,SAAS,MAAM,EAC9D,QAAQ,EAAE,SAAS,oBAAoB,CAAC,SAAS,CAAC,EAAE,GACnD,IAAI,CAwBN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,SAAS,MAAM,EAC/D,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,SAAS,oBAAoB,CAAC,SAAS,CAAC,EAAE,GACnD,YAAY,CAAC,SAAS,CAAC,GAAG,IAAI,CAmBhC;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,SAAS,MAAM,EAC9D,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,YAAY,CAAC,SAAS,CAAC,EAC9B,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB,sBAAsB,CAcxB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,gmBAS5B,CAAC"}

package/dist/mentions.js

@@ -0,0 +1,107 @@
+function isWhitespace(char) {
+    return char !== undefined && /\s/.test(char);
+}
+/**
+ * Rejects the configuration shapes a naive Mentions implementation would
+ * accept and then fail on later: an empty trigger list (nothing to detect),
+ * a multi-character or whitespace trigger (the scan below assumes exactly one
+ * non-whitespace code unit), and two configs racing on the same character or
+ * id.
+ */
+export function validateMentionTriggers(triggers) {
+    if (triggers.length === 0) {
+        throw new TypeError("Mentions must configure at least one trigger");
+    }
+    const chars = new Set();
+    const ids = new Set();
+    for (const config of triggers) {
+        if (config.trigger.length !== 1) {
+            throw new TypeError(`Mentions trigger must be exactly one character: ${JSON.stringify(config.trigger)}`);
+        }
+        if (isWhitespace(config.trigger)) {
+            throw new TypeError("Mentions trigger must not be whitespace");
+        }
+        if (chars.has(config.trigger)) {
+            throw new TypeError(`Duplicate Mentions trigger character: ${config.trigger}`);
+        }
+        chars.add(config.trigger);
+        if (ids.has(config.id)) {
+            throw new TypeError(`Duplicate Mentions trigger id: ${config.id}`);
+        }
+        ids.add(config.id);
+    }
+}
+/**
+ * Scans left from the cursor for the nearest trigger character that starts a
+ * token (start-of-text or preceded by whitespace) with no whitespace between
+ * it and the cursor. The whitespace-between check is what must reject
+ * `"user@example.com"` — the char before `@` is `r`, not whitespace/start —
+ * and cancel an already-open mention the moment the user types a space, the
+ * same convention every mention UI (Slack, Discord, GitHub) uses so the query
+ * can never run away across word boundaries. Operating on the resolved text
+ * value and a single cursor offset (never individual keystrokes) is also why
+ * Hangul composition needs no special-casing here: a composing jamo is
+ * already a valid code point in that string the moment `onChange` fires,
+ * composed or not.
+ */
+export function findActiveMentionTrigger(text, cursorPosition, triggers) {
+    validateMentionTriggers(triggers);
+    if (cursorPosition < 0 || cursorPosition > text.length) {
+        throw new RangeError("Mentions cursorPosition must be within the text bounds");
+    }
+    for (let index = cursorPosition - 1; index >= 0; index -= 1) {
+        const char = text[index];
+        if (isWhitespace(char))
+            return null;
+        const config = triggers.find((candidate) => candidate.trigger === char);
+        if (config && (index === 0 || isWhitespace(text[index - 1]))) {
+            return {
+                triggerId: config.id,
+                trigger: config.trigger,
+                triggerStart: index,
+                query: text.slice(index + 1, cursorPosition),
+            };
+        }
+    }
+    return null;
+}
+/**
+ * Replaces `[match.triggerStart, cursorPosition)` — the trigger character
+ * through wherever the caret sits now — with the trigger plus the product's
+ * display text plus a trailing space, so typing can continue without fusing
+ * into the mention. The trigger character is always prepended here, not by
+ * the caller, so it can never be forgotten or duplicated.
+ */
+export function resolveMentionInsertion(text, match, cursorPosition, insertedText) {
+    if (insertedText.trim().length === 0) {
+        throw new TypeError("Mentions insertedText must not be empty");
+    }
+    if (cursorPosition < match.triggerStart || cursorPosition > text.length) {
+        throw new RangeError("Mentions cursorPosition must be at or after the matched trigger");
+    }
+    const before = text.slice(0, match.triggerStart);
+    const after = text.slice(cursorPosition);
+    const inserted = `${match.trigger}${insertedText} `;
+    return {
+        text: `${before}${inserted}${after}`,
+        cursorPosition: before.length + inserted.length,
+    };
+}
+/**
+ * No new recipe or behaviorRegistry entry: the popup is
+ * `behaviorRegistry.combobox` verbatim (roles, keyboard, dismiss, the
+ * `ime-composition-does-not-prematurely-filter-or-commit` scenario already
+ * covers composed text), layered on a plain `TextArea`. These scenarios are
+ * the trigger-detection slice combobox's list does not already cover.
+ */
+export const mentionsBehaviorScenarios = [
+    "trigger-preceded-by-a-non-whitespace-character-does-not-open-the-popup",
+    "typing-a-space-after-the-trigger-closes-the-popup-without-committing",
+    "empty-query-right-after-the-trigger-is-a-valid-active-match",
+    "ime-composition-updates-the-query-like-any-other-text-change-no-special-casing-needed",
+    "commit-always-inserts-the-trigger-character-exactly-once",
+    "commit-replaces-exactly-the-trigger-through-the-current-cursor-nothing-before-or-after",
+    "two-configured-triggers-never-share-a-character-or-an-id",
+    "the-nearer-trigger-to-the-cursor-wins-when-an-earlier-token-also-looks-like-a-trigger",
+];
+//# sourceMappingURL=mentions.js.map

package/dist/mentions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mentions.js","sourceRoot":"","sources":["../src/mentions.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `docs/mentions.md`'s \"이게 새 컴포넌트인가\" verdict: Mentions is a `TextArea`\n * whose candidate popup is Combobox's existing listbox contract\n * (`comboboxRecipe`, `behaviorRegistry.combobox`) verbatim — arrow-key\n * navigation, typeahead-free filtering, loading/empty/error announcement are\n * already owned there and this module does not redeclare them. The one piece\n * neither owns is *finding the trigger inside free-form text and computing\n * what range gets replaced on commit* — that is genuinely new, and it is all\n * this module contains.\n */\nexport type MentionTriggerConfig<TriggerId extends string = string> = Readonly<{\n  id: TriggerId;\n  /** Exactly one non-whitespace character, e.g. \"@\" or \"#\". */\n  trigger: string;\n}>;\n\nexport type MentionMatch<TriggerId extends string = string> = Readonly<{\n  triggerId: TriggerId;\n  trigger: string;\n  /** UTF-16 code unit offset of the trigger character itself in `text`. */\n  triggerStart: number;\n  /** Text between the trigger and the cursor — drives candidate filtering. */\n  query: string;\n}>;\n\nfunction isWhitespace(char: string | undefined): boolean {\n  return char !== undefined && /\\s/.test(char);\n}\n\n/**\n * Rejects the configuration shapes a naive Mentions implementation would\n * accept and then fail on later: an empty trigger list (nothing to detect),\n * a multi-character or whitespace trigger (the scan below assumes exactly one\n * non-whitespace code unit), and two configs racing on the same character or\n * id.\n */\nexport function validateMentionTriggers<TriggerId extends string>(\n  triggers: readonly MentionTriggerConfig<TriggerId>[],\n): void {\n  if (triggers.length === 0) {\n    throw new TypeError(\"Mentions must configure at least one trigger\");\n  }\n  const chars = new Set<string>();\n  const ids = new Set<TriggerId>();\n  for (const config of triggers) {\n    if (config.trigger.length !== 1) {\n      throw new TypeError(\n        `Mentions trigger must be exactly one character: ${JSON.stringify(config.trigger)}`,\n      );\n    }\n    if (isWhitespace(config.trigger)) {\n      throw new TypeError(\"Mentions trigger must not be whitespace\");\n    }\n    if (chars.has(config.trigger)) {\n      throw new TypeError(`Duplicate Mentions trigger character: ${config.trigger}`);\n    }\n    chars.add(config.trigger);\n    if (ids.has(config.id)) {\n      throw new TypeError(`Duplicate Mentions trigger id: ${config.id}`);\n    }\n    ids.add(config.id);\n  }\n}\n\n/**\n * Scans left from the cursor for the nearest trigger character that starts a\n * token (start-of-text or preceded by whitespace) with no whitespace between\n * it and the cursor. The whitespace-between check is what must reject\n * `\"user@example.com\"` — the char before `@` is `r`, not whitespace/start —\n * and cancel an already-open mention the moment the user types a space, the\n * same convention every mention UI (Slack, Discord, GitHub) uses so the query\n * can never run away across word boundaries. Operating on the resolved text\n * value and a single cursor offset (never individual keystrokes) is also why\n * Hangul composition needs no special-casing here: a composing jamo is\n * already a valid code point in that string the moment `onChange` fires,\n * composed or not.\n */\nexport function findActiveMentionTrigger<TriggerId extends string>(\n  text: string,\n  cursorPosition: number,\n  triggers: readonly MentionTriggerConfig<TriggerId>[],\n): MentionMatch<TriggerId> | null {\n  validateMentionTriggers(triggers);\n  if (cursorPosition < 0 || cursorPosition > text.length) {\n    throw new RangeError(\"Mentions cursorPosition must be within the text bounds\");\n  }\n  for (let index = cursorPosition - 1; index >= 0; index -= 1) {\n    const char = text[index]!;\n    if (isWhitespace(char)) return null;\n    const config = triggers.find((candidate) => candidate.trigger === char);\n    if (config && (index === 0 || isWhitespace(text[index - 1]))) {\n      return {\n        triggerId: config.id,\n        trigger: config.trigger,\n        triggerStart: index,\n        query: text.slice(index + 1, cursorPosition),\n      };\n    }\n  }\n  return null;\n}\n\nexport type MentionInsertionResult = Readonly<{\n  text: string;\n  /** Caret offset immediately after the inserted mention and its trailing space. */\n  cursorPosition: number;\n}>;\n\n/**\n * Replaces `[match.triggerStart, cursorPosition)` — the trigger character\n * through wherever the caret sits now — with the trigger plus the product's\n * display text plus a trailing space, so typing can continue without fusing\n * into the mention. The trigger character is always prepended here, not by\n * the caller, so it can never be forgotten or duplicated.\n */\nexport function resolveMentionInsertion<TriggerId extends string>(\n  text: string,\n  match: MentionMatch<TriggerId>,\n  cursorPosition: number,\n  insertedText: string,\n): MentionInsertionResult {\n  if (insertedText.trim().length === 0) {\n    throw new TypeError(\"Mentions insertedText must not be empty\");\n  }\n  if (cursorPosition < match.triggerStart || cursorPosition > text.length) {\n    throw new RangeError(\"Mentions cursorPosition must be at or after the matched trigger\");\n  }\n  const before = text.slice(0, match.triggerStart);\n  const after = text.slice(cursorPosition);\n  const inserted = `${match.trigger}${insertedText} `;\n  return {\n    text: `${before}${inserted}${after}`,\n    cursorPosition: before.length + inserted.length,\n  };\n}\n\n/**\n * No new recipe or behaviorRegistry entry: the popup is\n * `behaviorRegistry.combobox` verbatim (roles, keyboard, dismiss, the\n * `ime-composition-does-not-prematurely-filter-or-commit` scenario already\n * covers composed text), layered on a plain `TextArea`. These scenarios are\n * the trigger-detection slice combobox's list does not already cover.\n */\nexport const mentionsBehaviorScenarios = [\n  \"trigger-preceded-by-a-non-whitespace-character-does-not-open-the-popup\",\n  \"typing-a-space-after-the-trigger-closes-the-popup-without-committing\",\n  \"empty-query-right-after-the-trigger-is-a-valid-active-match\",\n  \"ime-composition-updates-the-query-like-any-other-text-change-no-special-casing-needed\",\n  \"commit-always-inserts-the-trigger-character-exactly-once\",\n  \"commit-replaces-exactly-the-trigger-through-the-current-cursor-nothing-before-or-after\",\n  \"two-configured-triggers-never-share-a-character-or-an-id\",\n  \"the-nearer-trigger-to-the-cursor-wins-when-an-earlier-token-also-looks-like-a-trigger\",\n] as const;\n"]}

package/dist/number-field.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared by NumberField and Slider: both solve "pick a number within a range."
+ * Keeping min/max/step/value judgment in one place keeps the two components
+ * from drifting into two different meanings of the same numeric domain.
+ */
+export type NumericRangeConfig = Readonly<{
+    min: number;
+    max: number;
+    step?: number;
+}>;
+export declare const numericRangeDefaults: {
+    readonly step: 1;
+};
+export declare function assertFiniteNumber(value: number, field: string): void;
+export declare function validateNumericRangeConfig(config: NumericRangeConfig): void;
+export declare function clampToRange(value: number, config: NumericRangeConfig): number;
+/** Snaps to the nearest step from `min`, then clamps into [min, max]. */
+export declare function snapToStep(value: number, config: NumericRangeConfig): number;
+/** Move to the next valid grid boundary in the requested direction. */
+export declare function stepNumericValue(value: number, config: NumericRangeConfig, direction: "increment" | "decrement"): number;
+/**
+ * `null` means no value has been entered yet — distinct from any in-range
+ * number, including `min`. Products decide whether empty is allowed to submit.
+ */
+export type NumberFieldValue = number | null;
+/**
+ * Parses the renderer's editable text without guessing at locale, currency,
+ * or unit formatting. Empty text is a first-class `null` value; `undefined`
+ * means the draft is not a complete finite decimal number yet.
+ *
+ * Exponent notation is accepted because `String(number)` may produce it for
+ * very small or large finite values. Renderers keep incomplete drafts such as
+ * `-` or `1e` locally and only commit once this parser succeeds.
+ */
+export declare function parseNumberFieldInput(input: string): NumberFieldValue | undefined;
+/**
+ * Turns an editable draft into a model value at blur/submit boundaries.
+ * Direct input is clamped and snapped with the same range math used by the
+ * steppers and Slider. Invalid/incomplete text remains `undefined`, allowing a
+ * renderer to restore the last committed value without inventing an error.
+ */
+export declare function commitNumberFieldInput(input: string, config: NumericRangeConfig): NumberFieldValue | undefined;
+export type NumberFieldDescriptor = Readonly<{
+    value: NumberFieldValue;
+    min: number;
+    max: number;
+    step?: number;
+}>;
+export type ResolvedNumberFieldDescriptor = Omit<NumberFieldDescriptor, "step"> & Readonly<{
+    step: number;
+}>;
+export declare function validateNumberFieldDescriptor(descriptor: NumberFieldDescriptor): void;
+export declare function resolveNumberFieldDescriptor(descriptor: NumberFieldDescriptor): ResolvedNumberFieldDescriptor;
+export type NumberFieldStepperState = Readonly<{
+    incrementDisabled: boolean;
+    decrementDisabled: boolean;
+}>;
+/** Empty has no boundary yet, so neither stepper direction is disabled. */
+export declare function resolveNumberFieldStepperState(descriptor: NumberFieldDescriptor): NumberFieldStepperState;
+/** Resolve stepper availability from the visible draft, falling back safely. */
+export declare function resolveNumberFieldInputStepperState(input: string, descriptor: NumberFieldDescriptor): NumberFieldStepperState;
+/** Stepping from empty lands on the boundary you are moving toward. */
+export declare function stepNumberFieldValue(descriptor: NumberFieldDescriptor, direction: "increment" | "decrement"): number;
+/**
+ * Resolves a step action from the editable draft without first snapping and
+ * then stepping a second time. Off-grid drafts move to the next valid boundary
+ * in the requested direction; invalid drafts fall back to the committed model.
+ */
+export declare function stepNumberFieldInput(input: string, descriptor: NumberFieldDescriptor, direction: "increment" | "decrement"): number;
+export type NumberFieldSize = "medium" | "large";
+/**
+ * Reuses the Field frame (`fieldFrameContract`) and form support copy
+ * (`formSupportContract`) verbatim — a second field frame would drift from
+ * Field the first time either one's border or height changes.
+ */
+export declare const numberFieldRecipe: {
+    readonly slots: readonly ["root", "frame", "input", "decrement", "increment", "description", "error"];
+    readonly defaults: {
+        readonly size: "medium";
+    };
+    readonly frame: {
+        readonly background: Readonly<{
+            source: "theme";
+            key: "surface";
+            alpha?: number;
+        }>;
+        readonly border: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly focusBorder: Readonly<{
+            source: "theme";
+            key: "contentBrand";
+            alpha?: number;
+        }>;
+        readonly invalidBorder: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+        readonly radius: "md";
+        readonly borderWidth: 1;
+        readonly minHeight: 44;
+        readonly paddingHorizontal: 16;
+    };
+    readonly support: {
+        readonly label: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textBody";
+                alpha?: number;
+            }>;
+            readonly textVariant: "body";
+            readonly fontWeight: "600";
+        };
+        readonly hint: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "textMuted";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly error: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "danger";
+                alpha?: number;
+            }>;
+            readonly textVariant: "label";
+        };
+        readonly gap: 8;
+    };
+    readonly sizes: {
+        readonly medium: {
+            readonly minHeight: 44;
+            readonly paddingHorizontal: 16;
+            readonly textVariant: "body";
+            readonly stepperDiameter: 44;
+        };
+        readonly large: {
+            readonly minHeight: 52;
+            readonly paddingHorizontal: 20;
+            readonly textVariant: "bodyLarge";
+            readonly stepperDiameter: 44;
+        };
+    };
+    readonly value: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textBody";
+            alpha?: number;
+        }>;
+        readonly numericVariant: "tabular";
+    };
+    readonly stepper: {
+        readonly color: Readonly<{
+            source: "theme";
+            key: "textMuted";
+            alpha?: number;
+        }>;
+        readonly minTarget: 44;
+    };
+    readonly states: {
+        readonly focus: {
+            readonly color: Readonly<{
+                source: "theme";
+                key: "contentBrand";
+                alpha?: number;
+            }>;
+            readonly width: 2;
+            readonly offset: 2;
+        };
+        readonly invalidBorder: Readonly<{
+            source: "theme";
+            key: "danger";
+            alpha?: number;
+        }>;
+        readonly disabledOpacity: 0.5;
+    };
+};
+/**
+ * Held-repeat on the stepper buttons is deliberately not part of this
+ * contract: no product using NumberField has measured demand for press-and-
+ * hold, and adding it now would mean guessing at a repeat-rate/acceleration
+ * curve nobody has validated. A single activation per press only.
+ */
+export declare const numberFieldBehavior: {
+    readonly controlled: readonly ["value", "defaultValue", "onValueChange"];
+    readonly stateAxes: {
+        readonly availability: readonly ["enabled", "disabled", "readOnly"];
+        readonly value: readonly ["empty", "filled"];
+        readonly validation: readonly ["valid", "invalid"];
+    };
+    readonly web: {
+        readonly roles: readonly ["spinbutton"];
+        readonly keyboard: readonly ["Tab", "ArrowUp", "ArrowDown"];
+        readonly focus: "native";
+    };
+    readonly native: {
+        readonly roles: readonly ["text", "button"];
+        readonly states: readonly ["disabled"];
+        readonly actions: readonly ["focus", "setText", "increment", "decrement"];
+    };
+    readonly scenarios: readonly ["value-and-range-are-independent-controlled-inputs", "stepper-buttons-disable-at-min-and-max", "empty-disables-neither-stepper-direction", "keyboard-arrow-up-down-step-like-the-stepper-buttons", "invalid-is-a-numberfield-only-axis-independent-of-range", "held-repeat-is-not-part-of-the-contract"];
+};
+//# sourceMappingURL=number-field.d.ts.map

package/dist/number-field.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"number-field.d.ts","sourceRoot":"","sources":["../src/number-field.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,eAAO,MAAM,oBAAoB;;CAEc,CAAC;AAEhD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAIrE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAc3E;AA2BD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAI9E;AAED,yEAAyE;AACzE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAO5E;AAED,uEAAuE;AACvE,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,WAAW,GAAG,WAAW,GACnC,MAAM,CAOR;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAC;AAE7C;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAQjF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,kBAAkB,GACzB,gBAAgB,GAAG,SAAS,CAK9B;AAED,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,KAAK,EAAE,gBAAgB,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,MAAM,MAAM,6BAA6B,GAAG,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,GAC7E,QAAQ,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7B,wBAAgB,6BAA6B,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAQrF;AAED,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,qBAAqB,GAChC,6BAA6B,CAG/B;AAED,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,iBAAiB,EAAE,OAAO,CAAC;CAC5B,CAAC,CAAC;AAEH,2EAA2E;AAC3E,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,qBAAqB,GAChC,uBAAuB,CASzB;AAED,gFAAgF;AAChF,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,qBAAqB,GAChC,uBAAuB,CAWzB;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,qBAAqB,EACjC,SAAS,EAAE,WAAW,GAAG,WAAW,GACnC,MAAM,CAMR;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,qBAAqB,EACjC,SAAS,EAAE,WAAW,GAAG,WAAW,GACnC,MAAM,CAQR;AAED,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqE7B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;CAyBK,CAAC"}