@seedgrid/fe-core 2026.4.20 → 2026.4.21

package/dist/ai/seedgrid-core.manifest.json

@@ -409,6 +409,103 @@
         }
       }
     },
+    {
+      "componentId": "hook.use-debounced-value",
+      "exportName": "useDebouncedValue",
+      "sgMeta": {
+        "version": "0.1",
+        "componentId": "hook.use-debounced-value",
+        "package": "@seedgrid/fe-core",
+        "exportName": "useDebouncedValue",
+        "slug": "use-debounced-value",
+        "displayName": "Use Debounced Value",
+        "category": "hook",
+        "subcategory": "interaction",
+        "description": "React hook that returns a debounced version of a value with optional normalization before commit.",
+        "tags": [
+          "hook",
+          "debounce",
+          "search",
+          "filter",
+          "input"
+        ],
+        "capabilities": [
+          "delay",
+          "normalize",
+          "typed-value",
+          "react-hook"
+        ],
+        "fieldSemantics": [
+          "search",
+          "filter",
+          "input",
+          "debounce"
+        ],
+        "props": [
+          {
+            "name": "value",
+            "type": "T",
+            "required": true,
+            "description": "Current source value that should be debounced.",
+            "semanticRole": "value"
+          },
+          {
+            "name": "delayMs",
+            "type": "number",
+            "required": true,
+            "description": "Debounce delay in milliseconds before the debounced value updates.",
+            "semanticRole": "behavior"
+          },
+          {
+            "name": "normalize",
+            "type": "(nextValue: T) => T",
+            "required": false,
+            "description": "Optional normalization function applied before the debounced value is stored.",
+            "semanticRole": "behavior"
+          }
+        ],
+        "states": [
+          "idle",
+          "pending",
+          "debounced"
+        ]
+      },
+      "aiHints": {
+        "version": "0.1",
+        "preferredUseCases": [
+          "Search inputs that should wait before querying paginated APIs.",
+          "Filter forms that should debounce local or remote state synchronization.",
+          "Shared debounce logic for multiple domain modules without pulling feature config into the core package."
+        ],
+        "avoidUseCases": [
+          "Immediate form validation that must react to every keystroke.",
+          "Complex stream composition better handled by dedicated observable pipelines."
+        ],
+        "synonyms": [
+          "debounced search",
+          "debounced input",
+          "debounced state",
+          "search debounce"
+        ],
+        "relatedEntityFields": [
+          "search",
+          "filter",
+          "query",
+          "text input"
+        ],
+        "compositionHints": [
+          "Wrap domain-specific normalization or min-length logic outside the hook and keep this hook generic.",
+          "Use with server-side pagination so list fetches are triggered only after the debounced value settles."
+        ],
+        "rankingSignals": {
+          "freeText": 0.3,
+          "structuredChoice": 0.25,
+          "date": 0,
+          "number": 0,
+          "denseLayout": 0.05
+        }
+      }
+    },
     {
       "componentId": "factory.api-client",
       "exportName": "createApiClient",
@@ -552,6 +649,92 @@
         }
       }
     },
+    {
+      "componentId": "utility.api-errors",
+      "exportName": "extractApiErrorMessage",
+      "sgMeta": {
+        "version": "0.1",
+        "componentId": "utility.api-errors",
+        "package": "@seedgrid/fe-core",
+        "exportName": "extractApiErrorMessage",
+        "slug": "extract-api-error-message",
+        "displayName": "API Error Message Extractor",
+        "category": "utility",
+        "subcategory": "http",
+        "description": "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before generic detail/title fields.",
+        "tags": [
+          "api",
+          "http",
+          "error",
+          "rfc7807",
+          "validation"
+        ],
+        "capabilities": [
+          "api-client-error",
+          "rfc7807",
+          "violations",
+          "error-message",
+          "json-string-body"
+        ],
+        "fieldSemantics": [
+          "error",
+          "validation",
+          "problem-details",
+          "http"
+        ],
+        "props": [
+          {
+            "name": "error",
+            "type": "unknown",
+            "required": true,
+            "description": "ApiClientError, ApiClientError-like object, Error instance, or unknown thrown value to inspect.",
+            "semanticRole": "data"
+          }
+        ],
+        "states": [
+          "empty",
+          "problem-details",
+          "violations",
+          "fallback-message"
+        ]
+      },
+      "aiHints": {
+        "version": "0.1",
+        "preferredUseCases": [
+          "Showing API validation or problem-detail messages in UI toasts, whistles, dialogs, or notices.",
+          "Normalizing backend RFC7807 responses before mapping them to feature-specific fallback translations.",
+          "Handling cases where errors cross bundle boundaries and no longer satisfy instanceof ApiClientError."
+        ],
+        "avoidUseCases": [
+          "Client-side form validation unrelated to API responses.",
+          "Flows that need full structured problem objects rather than a single human-readable message."
+        ],
+        "synonyms": [
+          "rfc7807 parser",
+          "problem details",
+          "api validation message",
+          "violations message"
+        ],
+        "relatedEntityFields": [
+          "responseBody",
+          "detail",
+          "title",
+          "violations",
+          "errors"
+        ],
+        "compositionHints": [
+          "Call extractApiErrorMessage(error) first, then apply feature-specific server/network/html fallbacks only if needed.",
+          "Use alongside createApiClient so ApiClientError.responseBody is preserved end-to-end."
+        ],
+        "rankingSignals": {
+          "freeText": 0.35,
+          "structuredChoice": 0.2,
+          "date": 0,
+          "number": 0,
+          "denseLayout": 0.05
+        }
+      }
+    },
     {
       "componentId": "utility.exception-capture",
       "exportName": "captureException",

package/dist/http/api-errors.d.ts

@@ -0,0 +1,9 @@
+export declare function isApiClientErrorLike(error: unknown): error is {
+    message?: unknown;
+    responseBody?: unknown;
+    detail?: unknown;
+    status?: unknown;
+};
+export declare function extractApiErrorMessage(error: unknown): string | null;
+export declare function readApiErrorMessage(body: unknown): string | null;
+//# sourceMappingURL=api-errors.d.ts.map

package/dist/http/api-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.d.ts","sourceRoot":"","sources":["../../src/http/api-errors.ts"],"names":[],"mappings":"AAMA,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI;IACV,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAEA;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAqBpE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAoChE"}

package/dist/http/api-errors.js

@@ -0,0 +1,78 @@
+// seedgrid:managed
+import { ApiClientError } from "./api-client";
+export function isApiClientErrorLike(error) {
+    return Boolean(error && typeof error === "object");
+}
+export function extractApiErrorMessage(error) {
+    if (error instanceof ApiClientError) {
+        return (readApiErrorMessage(error.responseBody) ??
+            pickString(error.message));
+    }
+    if (isApiClientErrorLike(error)) {
+        return (readApiErrorMessage(error.responseBody) ??
+            pickString(error.message) ??
+            pickString(error.detail));
+    }
+    if (error instanceof Error) {
+        return pickString(error.message);
+    }
+    return null;
+}
+export function readApiErrorMessage(body) {
+    const normalizedBody = normalizeApiBody(body);
+    if (!normalizedBody || typeof normalizedBody !== "object") {
+        return pickString(normalizedBody);
+    }
+    const record = normalizedBody;
+    if (Array.isArray(record.violations)) {
+        for (const entry of record.violations) {
+            const violationMessage = readRecordMessage(entry);
+            if (violationMessage) {
+                return violationMessage;
+            }
+        }
+    }
+    if (Array.isArray(record.errors)) {
+        for (const entry of record.errors) {
+            const nestedMessage = readRecordMessage(entry);
+            if (nestedMessage) {
+                return nestedMessage;
+            }
+        }
+    }
+    return (pickString(record.userMessage) ??
+        pickString(record.detail) ??
+        pickString(record.message) ??
+        pickString(record.error) ??
+        pickString(record.title));
+}
+function normalizeApiBody(body) {
+    if (typeof body !== "string") {
+        return body;
+    }
+    const normalized = body.trim();
+    if (!normalized) {
+        return body;
+    }
+    try {
+        return JSON.parse(normalized);
+    }
+    catch {
+        return body;
+    }
+}
+function readRecordMessage(value) {
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const record = value;
+    return (pickString(record.userMessage) ??
+        pickString(record.message) ??
+        pickString(record.error) ??
+        pickString(record.description));
+}
+function pickString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : null;
+}

package/dist/http/api-errors.meta.d.ts

@@ -0,0 +1,44 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=api-errors.meta.d.ts.map

package/dist/http/api-errors.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-errors.meta.d.ts","sourceRoot":"","sources":["../../src/http/api-errors.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EACT,OAAO,GACP,OAAO,GACP,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QA+BpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WA6BrB,CAAC"}

package/dist/http/api-errors.meta.js

@@ -0,0 +1,60 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "utility.api-errors",
+    package: "@seedgrid/fe-core",
+    exportName: "extractApiErrorMessage",
+    slug: "extract-api-error-message",
+    displayName: "API Error Message Extractor",
+    category: "utility",
+    subcategory: "http",
+    description: "Reads API problem payloads and extracts the best user-facing message, prioritizing RFC7807 violations before generic detail/title fields.",
+    tags: ["api", "http", "error", "rfc7807", "validation"],
+    capabilities: [
+        "api-client-error",
+        "rfc7807",
+        "violations",
+        "error-message",
+        "json-string-body",
+    ],
+    fieldSemantics: ["error", "validation", "problem-details", "http"],
+    props: [
+        {
+            name: "error",
+            type: "unknown",
+            required: true,
+            description: "ApiClientError, ApiClientError-like object, Error instance, or unknown thrown value to inspect.",
+            semanticRole: "data",
+        },
+    ],
+    states: ["empty", "problem-details", "violations", "fallback-message"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Showing API validation or problem-detail messages in UI toasts, whistles, dialogs, or notices.",
+        "Normalizing backend RFC7807 responses before mapping them to feature-specific fallback translations.",
+        "Handling cases where errors cross bundle boundaries and no longer satisfy instanceof ApiClientError.",
+    ],
+    avoidUseCases: [
+        "Client-side form validation unrelated to API responses.",
+        "Flows that need full structured problem objects rather than a single human-readable message.",
+    ],
+    synonyms: [
+        "rfc7807 parser",
+        "problem details",
+        "api validation message",
+        "violations message",
+    ],
+    relatedEntityFields: ["responseBody", "detail", "title", "violations", "errors"],
+    compositionHints: [
+        "Call extractApiErrorMessage(error) first, then apply feature-specific server/network/html fallbacks only if needed.",
+        "Use alongside createApiClient so ApiClientError.responseBody is preserved end-to-end.",
+    ],
+    rankingSignals: {
+        freeText: 0.35,
+        structuredChoice: 0.2,
+        date: 0,
+        number: 0,
+        denseLayout: 0.05,
+    },
+};

package/dist/index.d.ts

@@ -4,5 +4,7 @@ export * from "./i18n";
 export * from "./persistence";
 export * from "./http/api-exception-handler";
 export * from "./http/api-client";
+export * from "./http/api-errors";
 export * from "./server";
+export * from "./useDebouncedValue";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,eAAe,CAAC;AAC9B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC"}

package/dist/index.js

@@ -4,4 +4,6 @@ export * from "./i18n";
 export * from "./persistence";
 export * from "./http/api-exception-handler";
 export * from "./http/api-client";
+export * from "./http/api-errors";
 export * from "./server";
+export * from "./useDebouncedValue";

package/dist/useDebouncedValue.d.ts

@@ -0,0 +1,2 @@
+export declare function useDebouncedValue<T>(value: T, delayMs: number, normalize?: (nextValue: T) => T): T;
+//# sourceMappingURL=useDebouncedValue.d.ts.map

package/dist/useDebouncedValue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedValue.d.ts","sourceRoot":"","sources":["../src/useDebouncedValue.ts"],"names":[],"mappings":"AAKA,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,MAAM,EACf,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,KAkBhC"}

package/dist/useDebouncedValue.js

@@ -0,0 +1,16 @@
+// seedgrid:managed
+"use client";
+import { useEffect, useState } from "react";
+export function useDebouncedValue(value, delayMs, normalize) {
+    const normalizeValue = normalize ?? ((nextValue) => nextValue);
+    const [debouncedValue, setDebouncedValue] = useState(() => normalizeValue(value));
+    useEffect(() => {
+        const timer = window.setTimeout(() => {
+            setDebouncedValue(normalizeValue(value));
+        }, Math.max(0, delayMs));
+        return () => {
+            window.clearTimeout(timer);
+        };
+    }, [delayMs, normalizeValue, value]);
+    return debouncedValue;
+}

package/dist/useDebouncedValue.meta.d.ts

@@ -0,0 +1,44 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaV0 = {
+    version: "0.1";
+    componentId: string;
+    package: string;
+    exportName: string;
+    slug: string;
+    displayName: string;
+    category: string;
+    subcategory?: string;
+    description: string;
+    tags?: string[];
+    capabilities?: string[];
+    fieldSemantics?: string[];
+    props?: SgMetaPropV0[];
+    states?: string[];
+};
+type SgAiHintsV0 = {
+    version: "0.1";
+    preferredUseCases: string[];
+    avoidUseCases?: string[];
+    synonyms?: string[];
+    relatedEntityFields?: string[];
+    compositionHints?: string[];
+    rankingSignals?: {
+        freeText?: number;
+        structuredChoice?: number;
+        date?: number;
+        number?: number;
+        denseLayout?: number;
+    };
+};
+export declare const sgMeta: SgMetaV0;
+export declare const aiHints: SgAiHintsV0;
+export {};
+//# sourceMappingURL=useDebouncedValue.meta.d.ts.map

package/dist/useDebouncedValue.meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDebouncedValue.meta.d.ts","sourceRoot":"","sources":["../src/useDebouncedValue.meta.ts"],"names":[],"mappings":"AAAA,KAAK,YAAY,GAAG;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EACT,OAAO,GACP,OAAO,GACP,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,OAAO,GACP,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,QAAQ,GAAG;IACd,OAAO,EAAE,KAAK,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE,YAAY,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,KAAK,WAAW,GAAG;IACjB,OAAO,EAAE,KAAK,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,cAAc,CAAC,EAAE;QACf,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,MAAM,EAAE,QAsCpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAwBrB,CAAC"}

package/dist/useDebouncedValue.meta.js

@@ -0,0 +1,63 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "hook.use-debounced-value",
+    package: "@seedgrid/fe-core",
+    exportName: "useDebouncedValue",
+    slug: "use-debounced-value",
+    displayName: "Use Debounced Value",
+    category: "hook",
+    subcategory: "interaction",
+    description: "React hook that returns a debounced version of a value with optional normalization before commit.",
+    tags: ["hook", "debounce", "search", "filter", "input"],
+    capabilities: ["delay", "normalize", "typed-value", "react-hook"],
+    fieldSemantics: ["search", "filter", "input", "debounce"],
+    props: [
+        {
+            name: "value",
+            type: "T",
+            required: true,
+            description: "Current source value that should be debounced.",
+            semanticRole: "value",
+        },
+        {
+            name: "delayMs",
+            type: "number",
+            required: true,
+            description: "Debounce delay in milliseconds before the debounced value updates.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "normalize",
+            type: "(nextValue: T) => T",
+            required: false,
+            description: "Optional normalization function applied before the debounced value is stored.",
+            semanticRole: "behavior",
+        },
+    ],
+    states: ["idle", "pending", "debounced"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Search inputs that should wait before querying paginated APIs.",
+        "Filter forms that should debounce local or remote state synchronization.",
+        "Shared debounce logic for multiple domain modules without pulling feature config into the core package.",
+    ],
+    avoidUseCases: [
+        "Immediate form validation that must react to every keystroke.",
+        "Complex stream composition better handled by dedicated observable pipelines.",
+    ],
+    synonyms: ["debounced search", "debounced input", "debounced state", "search debounce"],
+    relatedEntityFields: ["search", "filter", "query", "text input"],
+    compositionHints: [
+        "Wrap domain-specific normalization or min-length logic outside the hook and keep this hook generic.",
+        "Use with server-side pagination so list fetches are triggered only after the debounced value settles.",
+    ],
+    rankingSignals: {
+        freeText: 0.3,
+        structuredChoice: 0.25,
+        date: 0,
+        number: 0,
+        denseLayout: 0.05,
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/fe-core",
-  "version": "2026.4.20",
+  "version": "2026.4.21",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",