@seedgrid/fe-core 2026.4.19 → 2026.4.21

package/dist/persistence-localstorage.meta.js

@@ -0,0 +1,55 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "hook.persistence-localstorage",
+    package: "@seedgrid/fe-core",
+    exportName: "createLocalStorageStrategy",
+    slug: "create-localstorage-strategy",
+    displayName: "Local Storage Persistence Strategy",
+    category: "hook",
+    subcategory: "persistence",
+    description: "Creates a persistence strategy that stores and retrieves application state from browser localStorage with optional key prefix.",
+    tags: ["persistence", "storage", "state", "localStorage", "browser"],
+    capabilities: ["persistence", "offline", "browser-native"],
+    fieldSemantics: ["state", "persistence", "storage"],
+    props: [
+        {
+            name: "options",
+            type: "{ prefix?: string }",
+            required: false,
+            description: "Optional configuration: prefix for localStorage keys (default: no prefix).",
+            semanticRole: "data",
+        },
+    ],
+    states: ["ready", "loading", "error"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Client-side application state persistence across browser sessions.",
+        "Caching user preferences, form state, or temporary data in the browser.",
+        "Single-origin applications where cross-origin data sharing is not needed.",
+    ],
+    avoidUseCases: [
+        "Sensitive data (passwords, tokens) — use secure server-side persistence instead.",
+        "Large datasets that exceed localStorage limit (~5-10MB per origin).",
+        "Server-synchronized state that requires real-time consistency across tabs.",
+    ],
+    synonyms: [
+        "browser persistence",
+        "local storage strategy",
+        "client-side state storage",
+    ],
+    relatedEntityFields: ["persistence", "state", "storage", "caching"],
+    compositionHints: [
+        "Use prefix option to namespace data when multiple apps share the same origin.",
+        "Combine with createCompositePersistenceStrategy to fall back to API persistence on failure.",
+        "State should be serializable to JSON — complex objects are converted via stringify.",
+    ],
+    rankingSignals: {
+        freeText: 0.2,
+        structuredChoice: 0.3,
+        date: 0,
+        number: 0,
+        denseLayout: 0.1,
+    },
+};

package/dist/registry.meta.d.ts

@@ -0,0 +1,61 @@
+type SgMetaPropV0 = {
+    name: string;
+    type: string;
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    semanticRole?: "value" | "label" | "validation" | "behavior" | "appearance" | "event" | "data";
+    bindable?: boolean;
+};
+type SgMetaExampleV0 = {
+    id: string;
+    title: string;
+    file: string;
+    kind: "sample" | "playground";
+};
+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[];
+    examples?: SgMetaExampleV0[];
+    showcase?: {
+        route: string;
+        hasPlayground: boolean;
+        hasPropsTable: boolean;
+    };
+    sdui?: {
+        rendererType: string;
+        acceptsDataBinding?: boolean;
+        defaultProps?: Record<string, unknown>;
+    };
+};
+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=registry.meta.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.meta.d.ts","sourceRoot":"","sources":["../src/registry.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,EAAE,OAAO,GAAG,OAAO,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/F,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;CAC/B,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;IAClB,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;IAC7B,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,OAAO,CAAC;QACvB,aAAa,EAAE,OAAO,CAAC;KACxB,CAAC;IACF,IAAI,CAAC,EAAE;QACL,YAAY,EAAE,MAAM,CAAC;QACrB,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,CAAC;CACH,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,QA6DpB,CAAC;AAEF,eAAO,MAAM,OAAO,EAAE,WAyBrB,CAAC"}

package/dist/registry.meta.js

@@ -0,0 +1,85 @@
+export const sgMeta = {
+    version: "0.1",
+    componentId: "provider.registry",
+    package: "@seedgrid/fe-core",
+    exportName: "SeedGridRegistry",
+    slug: "seedgrid-registry",
+    displayName: "SeedGrid Registry",
+    category: "provider",
+    subcategory: "registry",
+    description: "Centralized provider and route registry for modular SeedGrid applications. Manages composition of providers, navigation items, and routes with ordering support.",
+    tags: ["registry", "provider", "composition", "modular", "architecture"],
+    capabilities: ["navItem", "provider", "route", "ordering"],
+    fieldSemantics: ["registry", "composition", "navigation"],
+    props: [
+        {
+            name: "addProvider",
+            type: "(provider: SeedGridProvider) => void",
+            required: true,
+            description: "Register a React provider component (context wrapper).",
+            semanticRole: "behavior",
+        },
+        {
+            name: "addNavItem",
+            type: "(item: SeedGridNavItem) => void",
+            required: true,
+            description: "Register a navigation item with id, labelKey, href, optional icon and order.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "addRoute",
+            type: "(route: SeedGridRoute) => void",
+            required: true,
+            description: "Register an application route with id, path, and auth requirements.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "getProviders",
+            type: "() => SeedGridProvider[]",
+            required: true,
+            description: "Retrieve all registered providers as a flat array.",
+            semanticRole: "behavior",
+        },
+        {
+            name: "getNavItems",
+            type: "() => SeedGridNavItem[]",
+            required: true,
+            description: "Retrieve all registered navigation items sorted by order (default 999).",
+            semanticRole: "behavior",
+        },
+        {
+            name: "getRoutes",
+            type: "() => SeedGridRoute[]",
+            required: true,
+            description: "Retrieve all registered routes.",
+            semanticRole: "behavior",
+        },
+    ],
+    states: ["initialized", "empty", "populated"],
+};
+export const aiHints = {
+    version: "0.1",
+    preferredUseCases: [
+        "Modular application architecture where features register themselves independently.",
+        "Dynamic provider composition to avoid prop drilling and provider hell.",
+        "Centralized routing and navigation configuration across modules.",
+    ],
+    avoidUseCases: [
+        "Simple single-feature applications that don't need modular composition.",
+        "Direct React Context usage when a single provider suffices.",
+    ],
+    synonyms: ["module registry", "provider registry", "app composer", "navigation builder"],
+    relatedEntityFields: ["module", "provider", "navigation", "route", "composition"],
+    compositionHints: [
+        "Registry is typically paired with SeedGridModuleManifest for self-contained module definitions.",
+        "Providers registered to the registry should be wrapped to inject dependencies from environment/core.",
+        "Order-based nav item sorting enables feature modules to control their menu position without cross-module coupling.",
+    ],
+    rankingSignals: {
+        freeText: 0.3,
+        structuredChoice: 0.4,
+        date: 0,
+        number: 0,
+        denseLayout: 0.2,
+    },
+};

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+export { ApiClientError, createApiClient, type ApiClientConfig, type ApiRequestOptions, type ApiRetryOptions, } from "./http/api-client";
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC"}

package/dist/server.js

@@ -0,0 +1,2 @@
+// seedgrid:managed
+export { ApiClientError, createApiClient, } from "./http/api-client";

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.19",
+  "version": "2026.4.21",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,7 +28,7 @@
     "@types/react": "^19.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/build-ai-manifest.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }