@supernal/interface 1.0.0

package/dist/esm/src/interfaces/StatefulComponent.js

@@ -0,0 +1,47 @@
+/**
+ * Stateful Component Interface
+ *
+ * Week 2: State Integration
+ *
+ * Defines the interface that all stateful components must implement
+ * to enable state management through ComponentRegistry and story execution.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   name: 'counter',
+ *   stateful: true,
+ * })
+ * class CounterComponent implements StatefulComponent<CounterState> {
+ *   private state: CounterState = { count: 0 };
+ *
+ *   getState(): CounterState {
+ *     return { ...this.state };
+ *   }
+ *
+ *   setState(newState: Partial<CounterState>): void {
+ *     this.state = { ...this.state, ...newState };
+ *     this.render();
+ *   }
+ *
+ *   resetState(): void {
+ *     this.state = { count: 0 };
+ *     this.render();
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Type guard to check if a component implements StatefulComponent
+ *
+ * @param component - Component to check
+ * @returns True if component implements StatefulComponent interface
+ */
+export function isStatefulComponent(component) {
+    return (component !== null &&
+        typeof component === 'object' &&
+        typeof component.getState === 'function' &&
+        typeof component.setState === 'function' &&
+        typeof component.resetState === 'function');
+}
+//# sourceMappingURL=StatefulComponent.js.map

package/dist/esm/src/interfaces/StatefulComponent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatefulComponent.js","sourceRoot":"","sources":["../../../../src/interfaces/StatefulComponent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAoCH;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,SAAc;IAChD,OAAO,CACL,SAAS,KAAK,IAAI;QAClB,OAAO,SAAS,KAAK,QAAQ;QAC7B,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU;QACxC,OAAO,SAAS,CAAC,QAAQ,KAAK,UAAU;QACxC,OAAO,SAAS,CAAC,UAAU,KAAK,UAAU,CAC3C,CAAC;AACJ,CAAC"}

package/dist/esm/src/name-contracts/ContractScanner.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Abstract Contract Scanner Interface
+ *
+ * All name contract scanners (components, routes, API, CLI) implement this interface
+ */
+export interface ScanResult {
+    contracts: Map<string, ContractEntry>;
+    metadata?: Record<string, any>;
+}
+export interface ContractEntry {
+    name: string;
+    value: string;
+    category?: string;
+    files: string[];
+    metadata?: Record<string, any>;
+}
+export interface GenerateOptions {
+    outputPath: string;
+    dryRun?: boolean;
+    includeJsDocs?: boolean;
+}
+export interface MigrateOptions {
+    targetPaths?: string[];
+    dryRun?: boolean;
+    createBackup?: boolean;
+    contractsPath?: string;
+    verbose?: boolean;
+}
+export interface MigrateResult {
+    changes: number;
+    skipped: number;
+    files: string[];
+}
+/**
+ * Base interface that all contract scanners must implement
+ */
+export declare abstract class ContractScanner {
+    abstract readonly type: string;
+    abstract readonly description: string;
+    /**
+     * Scan codebase for this contract type
+     */
+    abstract scan(): Promise<ScanResult>;
+    /**
+     * Generate contract file from scan results
+     */
+    abstract generate(result: ScanResult, options: GenerateOptions): Promise<string>;
+    /**
+     * Migrate code to use contracts
+     */
+    abstract migrate(options: MigrateOptions): Promise<MigrateResult>;
+    /**
+     * Validate contracts match codebase
+     */
+    abstract validate(): Promise<string[]>;
+    /**
+     * Get default output path for this contract type
+     */
+    abstract getDefaultOutputPath(): string;
+}
+//# sourceMappingURL=ContractScanner.d.ts.map

package/dist/esm/src/name-contracts/ContractScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractScanner.d.ts","sourceRoot":"","sources":["../../../../src/name-contracts/ContractScanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,8BAAsB,eAAe;IACnC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAEhF;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAEjE;;OAEG;IACH,QAAQ,CAAC,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,oBAAoB,IAAI,MAAM;CACxC"}

package/dist/esm/src/name-contracts/ContractScanner.js

@@ -0,0 +1,11 @@
+/**
+ * Abstract Contract Scanner Interface
+ *
+ * All name contract scanners (components, routes, API, CLI) implement this interface
+ */
+/**
+ * Base interface that all contract scanners must implement
+ */
+export class ContractScanner {
+}
+//# sourceMappingURL=ContractScanner.js.map

package/dist/esm/src/name-contracts/ContractScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContractScanner.js","sourceRoot":"","sources":["../../../../src/name-contracts/ContractScanner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAmCH;;GAEG;AACH,MAAM,OAAgB,eAAe;CA4BpC"}

package/dist/esm/src/name-contracts/RouteContractScanner.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Route Contract Scanner
+ *
+ * Scans codebase for route patterns and generates type-safe route contracts
+ *
+ * Integrates with existing route scanning system:
+ * - NextjsDynamicScanner for route discovery
+ * - RouteContractGenerator for contract generation
+ */
+import { ContractScanner, ScanResult, GenerateOptions, MigrateOptions, MigrateResult } from './ContractScanner';
+import { RouteContractsConfig } from '../routes/RouteContractsConfig';
+export declare class RouteContractScanner extends ContractScanner {
+    readonly type = "routes";
+    readonly description = "Next.js route patterns (Views + API)";
+    private config;
+    private projectRoot;
+    constructor(projectRoot: string, config?: RouteContractsConfig);
+    private loadConfigFromSupernal;
+    private getDefaultConfig;
+    scan(): Promise<ScanResult>;
+    generate(result: ScanResult, options: GenerateOptions): Promise<string>;
+    migrate(_options: MigrateOptions): Promise<MigrateResult>;
+    validate(): Promise<string[]>;
+    getDefaultOutputPath(): string;
+    /**
+     * Load config from file if exists
+     */
+    static loadConfig(configPath: string): Promise<RouteContractsConfig | null>;
+}
+//# sourceMappingURL=RouteContractScanner.d.ts.map

package/dist/esm/src/name-contracts/RouteContractScanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RouteContractScanner.d.ts","sourceRoot":"","sources":["../../../../src/name-contracts/RouteContractScanner.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EACL,eAAe,EACf,UAAU,EAEV,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AAKtE,qBAAa,oBAAqB,SAAQ,eAAe;IACvD,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,WAAW,0CAA0C;IAE9D,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,WAAW,CAAS;gBAEhB,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,oBAAoB;IAM9D,OAAO,CAAC,sBAAsB;IAsC9B,OAAO,CAAC,gBAAgB;IAiBlB,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;IA8B3B,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAgCvE,OAAO,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAezD,QAAQ,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA6BnC,oBAAoB,IAAI,MAAM;IAI9B;;OAEG;WACU,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;CAiBlF"}

package/dist/esm/src/name-contracts/RouteContractScanner.js

@@ -0,0 +1,188 @@
+/**
+ * Route Contract Scanner
+ *
+ * Scans codebase for route patterns and generates type-safe route contracts
+ *
+ * Integrates with existing route scanning system:
+ * - NextjsDynamicScanner for route discovery
+ * - RouteContractGenerator for contract generation
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { ContractScanner } from './ContractScanner.js';
+import { NextjsDynamicScanner } from '../routes/scanners/NextjsDynamicScanner.js';
+import { RouteContractGenerator } from '../routes/RouteContractGenerator.js';
+export class RouteContractScanner extends ContractScanner {
+    constructor(projectRoot, config) {
+        super();
+        this.type = 'routes';
+        this.description = 'Next.js route patterns (Views + API)';
+        this.projectRoot = projectRoot;
+        this.config = config || this.loadConfigFromSupernal();
+    }
+    loadConfigFromSupernal() {
+        const supernalYamlPath = path.join(this.projectRoot, 'supernal.yaml');
+        try {
+            const yaml = require('js-yaml');
+            const fs = require('fs');
+            const supernalConfig = yaml.load(fs.readFileSync(supernalYamlPath, 'utf8'));
+            if (supernalConfig?.name_contracts?.routes) {
+                const routesConfig = supernalConfig.name_contracts.routes;
+                return {
+                    routingSystem: routesConfig.routing_system || 'nextjs-dynamic',
+                    scanPaths: {
+                        routes: routesConfig.scan_paths?.routes || [],
+                        components: routesConfig.scan_paths?.components || [],
+                    },
+                    output: {
+                        contractsPath: routesConfig.output?.contracts_path || 'src/lib/routing/Routes.ts',
+                        testUtilsPath: routesConfig.output?.test_utils_path,
+                    },
+                    generation: {
+                        includeJsDocs: routesConfig.generation?.include_jsdocs !== false,
+                        includeValidation: routesConfig.generation?.include_validation || false,
+                        includeTypeGuards: routesConfig.generation?.include_type_guards || false,
+                    },
+                };
+            }
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // eslint-disable-next-line no-console
+            console.warn(`⚠️ Could not load route contracts config from supernal.yaml: ${errorMessage}`);
+            // eslint-disable-next-line no-console
+            console.warn('   Using default configuration');
+        }
+        return this.getDefaultConfig();
+    }
+    getDefaultConfig() {
+        return {
+            routingSystem: 'nextjs-name-extraction',
+            scanPaths: {
+                routes: ['apps/supernal-dashboard/src/app'],
+                components: ['apps/supernal-dashboard/src/lib/routing/slugService.ts'],
+            },
+            output: {
+                contractsPath: 'apps/supernal-dashboard/src/lib/routing/Routes.ts',
+                testUtilsPath: 'apps/supernal-dashboard/tests/utils/routes.ts',
+            },
+            generation: {
+                includeJsDocs: true,
+            },
+        };
+    }
+    async scan() {
+        const scanner = new NextjsDynamicScanner(this.config);
+        const routeScanResult = await scanner.scan();
+        // Convert RouteInfo[] to ContractEntry map
+        const contracts = new Map();
+        for (const route of routeScanResult.routes) {
+            contracts.set(route.id, {
+                name: route.id,
+                value: route.pattern,
+                category: route.metadata?.category || 'General',
+                files: [route.metadata?.source || 'generated'],
+                metadata: {
+                    params: route.params,
+                    methods: route.metadata?.methods, // Preserve HTTP methods
+                    description: route.metadata?.description,
+                },
+            });
+        }
+        return {
+            contracts,
+            metadata: {
+                routingSystem: this.config.routingSystem,
+                totalRoutes: contracts.size,
+            },
+        };
+    }
+    async generate(result, options) {
+        // Convert back to RouteInfo[] for generator
+        const routes = Array.from(result.contracts.values()).map(entry => ({
+            id: entry.name,
+            pattern: entry.value,
+            params: entry.metadata?.params || [],
+            metadata: {
+                category: entry.category,
+                methods: entry.metadata?.methods, // Restore HTTP methods
+                description: entry.metadata?.description,
+            },
+        }));
+        const generator = new RouteContractGenerator();
+        const content = generator.generate({
+            routes,
+            metadata: {
+                timestamp: new Date().toISOString(),
+                scannedPaths: this.config.scanPaths.routes || [],
+                routingSystem: this.config.routingSystem,
+            },
+        });
+        if (!options.dryRun) {
+            const outputPath = path.join(this.projectRoot, options.outputPath);
+            await fs.mkdir(path.dirname(outputPath), { recursive: true });
+            await fs.writeFile(outputPath, content, 'utf-8');
+        }
+        return content;
+    }
+    async migrate(_options) {
+        // TODO: Implement route migration
+        // For now, return empty result
+        // eslint-disable-next-line no-console
+        console.log('⚠️  Route migration not yet implemented');
+        // eslint-disable-next-line no-console
+        console.log('   Use test utilities in tests/utils/TestRoutes.ts instead');
+        return {
+            changes: 0,
+            skipped: 0,
+            files: [],
+        };
+    }
+    async validate() {
+        const errors = [];
+        // Check if generated contracts exist
+        const contractsPath = path.join(this.projectRoot, this.config.output.contractsPath);
+        try {
+            await fs.access(contractsPath);
+        }
+        catch {
+            errors.push(`Contracts file not found: ${this.config.output.contractsPath}`);
+            errors.push('Run: sc code generate --type=routes');
+            return errors;
+        }
+        // Scan current routes
+        const scanResult = await this.scan();
+        // Read generated contracts
+        const contractsContent = await fs.readFile(contractsPath, 'utf-8');
+        // Basic validation: check if route counts match
+        const generatedRouteCount = (contractsContent.match(/:\s*'\/[^']+'/g) || []).length;
+        if (generatedRouteCount !== scanResult.contracts.size) {
+            errors.push(`Route count mismatch: Generated has ${generatedRouteCount}, codebase has ${scanResult.contracts.size}`);
+            errors.push('Run: sc code generate --type=routes');
+        }
+        return errors;
+    }
+    getDefaultOutputPath() {
+        return this.config.output.contractsPath;
+    }
+    /**
+     * Load config from file if exists
+     */
+    static async loadConfig(configPath) {
+        try {
+            const fullPath = path.isAbsolute(configPath)
+                ? configPath
+                : path.join(process.cwd(), configPath);
+            // Use dynamic import for TypeScript config files
+            if (configPath.endsWith('.ts')) {
+                require('ts-node/register');
+            }
+            const config = require(fullPath);
+            return config.default || config;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=RouteContractScanner.js.map

package/dist/esm/src/name-contracts/RouteContractScanner.js.map

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

package/dist/esm/src/name-contracts/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Name Contracts - Abstract Base
+ *
+ * Provides base classes and interfaces for scanning codebases
+ * and generating type-safe name contracts.
+ */
+export { ContractScanner } from './ContractScanner';
+export type { ScanResult, ContractEntry } from './ContractScanner';
+export { RouteContractScanner } from './RouteContractScanner';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/src/name-contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/name-contracts/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/esm/src/name-contracts/index.js

@@ -0,0 +1,10 @@
+/**
+ * Name Contracts - Abstract Base
+ *
+ * Provides base classes and interfaces for scanning codebases
+ * and generating type-safe name contracts.
+ */
+export { ContractScanner } from './ContractScanner.js';
+// Route Contract Scanner (uses ContractScanner as base)
+export { RouteContractScanner } from './RouteContractScanner.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/src/name-contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/name-contracts/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGpD,wDAAwD;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/esm/src/names/createNames.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Create Component Names Helper
+ *
+ * Creates a component namespace with automatic kebab-case conversion and registry.
+ *
+ * Supports multiple formats for maximum flexibility:
+ *
+ * @example Minimal array format (fastest to write)
+ * ```typescript
+ * export const Blog = createNames('blog', ['container', 'searchInput', 'postCard']);
+ * // Result: { container: 'blog-container', searchInput: 'blog-search-input', postCard: 'blog-post-card' }
+ * ```
+ *
+ * @example Object format (same as current)
+ * ```typescript
+ * export const Blog = createNames('blog', {
+ *   container: 'container',
+ *   searchInput: 'searchInput',
+ *   postCard: 'postCard',
+ * });
+ * ```
+ *
+ * @example Custom suffixes (for special cases)
+ * ```typescript
+ * export const Blog = createNames('blog', {
+ *   container: 'main-wrapper',  // Becomes 'blog-main-wrapper'
+ *   searchInput: 'search',       // Becomes 'blog-search'
+ * });
+ * ```
+ */
+export declare function createNames<P extends string, K extends string>(prefix: P, names: readonly K[]): {
+    [Key in K]: `${P}-${string}`;
+};
+export declare function createNames<P extends string, N extends Record<string, string>>(prefix: P, names: N): {
+    [K in keyof N]: `${P}-${string}`;
+};
+/**
+ * Type helper to extract component ID type
+ */
+export type ComponentId<T> = T extends Record<string, infer U> ? U : never;
+/**
+ * Get all component IDs from a namespace as a flat array
+ */
+export declare function getComponentIds<T extends Record<string, string>>(namespace: T): string[];
+/**
+ * Validate that a string is a valid component ID in a namespace
+ */
+export declare function isComponentId<T extends Record<string, string>>(namespace: T, id: string): id is T[keyof T];
+//# sourceMappingURL=createNames.d.ts.map

package/dist/esm/src/names/createNames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createNames.d.ts","sourceRoot":"","sources":["../../../../src/names/createNames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgBH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAC5D,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,SAAS,CAAC,EAAE,GAClB;KAAG,GAAG,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,EAAE;CAAE,CAAC;AAGpC,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5E,MAAM,EAAE,CAAC,EACT,KAAK,EAAE,CAAC,GACP;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,GAAG,CAAC,IAAI,MAAM,EAAE;CAAE,CAAC;AAoCxC;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AAE3E;;GAEG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9D,SAAS,EAAE,CAAC,GACX,MAAM,EAAE,CAEV;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC5D,SAAS,EAAE,CAAC,EACZ,EAAE,EAAE,MAAM,GACT,EAAE,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAElB"}

package/dist/esm/src/names/createNames.js

@@ -0,0 +1,81 @@
+/**
+ * Create Component Names Helper
+ *
+ * Creates a component namespace with automatic kebab-case conversion and registry.
+ *
+ * Supports multiple formats for maximum flexibility:
+ *
+ * @example Minimal array format (fastest to write)
+ * ```typescript
+ * export const Blog = createNames('blog', ['container', 'searchInput', 'postCard']);
+ * // Result: { container: 'blog-container', searchInput: 'blog-search-input', postCard: 'blog-post-card' }
+ * ```
+ *
+ * @example Object format (same as current)
+ * ```typescript
+ * export const Blog = createNames('blog', {
+ *   container: 'container',
+ *   searchInput: 'searchInput',
+ *   postCard: 'postCard',
+ * });
+ * ```
+ *
+ * @example Custom suffixes (for special cases)
+ * ```typescript
+ * export const Blog = createNames('blog', {
+ *   container: 'main-wrapper',  // Becomes 'blog-main-wrapper'
+ *   searchInput: 'search',       // Becomes 'blog-search'
+ * });
+ * ```
+ */
+import { architectureRegistry } from '../architecture/registry.js';
+/**
+ * Convert camelCase to kebab-case
+ */
+function camelToKebab(str) {
+    return str
+        .replace(/([A-Z])/g, '-$1')
+        .toLowerCase()
+        .replace(/^-/, ''); // Remove leading dash if first char was uppercase
+}
+/**
+ * Create component names with automatic prefixing and kebab-case conversion
+ *
+ * @param prefix - The prefix for all component IDs (e.g., 'blog', 'demo')
+ * @param names - Array of keys or object mapping keys to suffixes
+ * @returns Object with fully qualified component IDs (prefix-suffix in kebab-case)
+ */
+// eslint-disable-next-line no-redeclare
+export function createNames(prefix, names) {
+    const result = {};
+    if (Array.isArray(names)) {
+        // Array format: ['container', 'searchInput'] -> { container: 'blog-container', searchInput: 'blog-search-input' }
+        for (const key of names) {
+            const kebab = camelToKebab(key);
+            result[key] = `${prefix}-${kebab}`;
+        }
+    }
+    else {
+        // Object format: { container: 'container' } -> { container: 'blog-container' }
+        for (const [key, value] of Object.entries(names)) {
+            const kebab = camelToKebab(value);
+            result[key] = `${prefix}-${kebab}`;
+        }
+    }
+    // Register with architecture registry
+    architectureRegistry.registerComponent(prefix, result);
+    return result;
+}
+/**
+ * Get all component IDs from a namespace as a flat array
+ */
+export function getComponentIds(namespace) {
+    return Object.values(namespace);
+}
+/**
+ * Validate that a string is a valid component ID in a namespace
+ */
+export function isComponentId(namespace, id) {
+    return Object.values(namespace).includes(id);
+}
+//# sourceMappingURL=createNames.js.map

package/dist/esm/src/names/createNames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createNames.js","sourceRoot":"","sources":["../../../../src/names/createNames.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE;;GAEG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG;SACP,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC;SAC1B,WAAW,EAAE;SACb,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,kDAAkD;AAC1E,CAAC;AAeD;;;;;;GAMG;AACH,wCAAwC;AACxC,MAAM,UAAU,WAAW,CACzB,MAAS,EACT,KAAiD;IAEjD,MAAM,MAAM,GAAQ,EAAE,CAAC;IAEvB,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,kHAAkH;QAClH,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;YAChC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,+EAA+E;QAC/E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACjD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YAClC,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,MAAM,IAAI,KAAK,EAAE,CAAC;QACrC,CAAC;IACH,CAAC;IAED,sCAAsC;IACtC,oBAAoB,CAAC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEvD,OAAO,MAAM,CAAC;AAChB,CAAC;AAOD;;GAEG;AACH,MAAM,UAAU,eAAe,CAC7B,SAAY;IAEZ,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAY,EACZ,EAAU;IAEV,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AAC/C,CAAC"}

package/dist/esm/src/react/hooks/useChatWithContext.d.ts

@@ -0,0 +1,68 @@
+/**
+ * useChatWithContext - Hook for integrating AI chat with application context
+ *
+ * Provides chat capabilities that can be plugged into any UI:
+ * - Automatic context injection (current view, available tools, app state)
+ * - Tool execution
+ * - Prompt building with context
+ * - Message handling
+ */
+export interface ChatContext {
+    containerId?: string;
+    currentRoute?: string;
+    viewType?: string;
+    userId?: string;
+    userRole?: string;
+    appState?: Record<string, any>;
+    filters?: Record<string, any>;
+    searchQuery?: string;
+    metadata?: Record<string, any>;
+}
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: Date;
+    context?: Partial<ChatContext>;
+    toolCalls?: Array<{
+        toolId: string;
+        args: any;
+        result?: any;
+    }>;
+}
+export interface PromptWithContext {
+    userMessage: string;
+    context: ChatContext;
+    availableTools: string[];
+    systemPrompt: string;
+}
+export interface UseChatWithContextConfig {
+    containerId?: string;
+    userId?: string;
+    onMessage?: (message: ChatMessage) => void;
+    onToolExecute?: (toolId: string, args: any, result: any) => void;
+    onError?: (error: Error) => void;
+    getAppState?: () => Record<string, any>;
+    systemPrompt?: string;
+}
+export declare function useChatWithContext(config?: UseChatWithContextConfig): {
+    messages: ChatMessage[];
+    isProcessing: boolean;
+    availableTools: import("../..").ToolMetadata[];
+    currentContext: ChatContext;
+    sendMessage: (content: string) => Promise<void>;
+    addMessage: (content: string, role?: "user" | "assistant" | "system") => ChatMessage;
+    clearMessages: () => void;
+    executeTool: (toolId: string, args?: any) => Promise<{
+        success: boolean;
+        result: any;
+        error: undefined;
+    } | {
+        success: boolean;
+        result: undefined;
+        error: string;
+    }>;
+    buildPromptWithContext: (userMessage: string) => PromptWithContext;
+    suggestTools: (query: string) => import("../..").ToolMetadata[];
+};
+//# sourceMappingURL=useChatWithContext.d.ts.map

package/dist/esm/src/react/hooks/useChatWithContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useChatWithContext.d.ts","sourceRoot":"","sources":["../../../../../src/react/hooks/useChatWithContext.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,MAAM,WAAW,WAAW;IAE1B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAGlB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IAGrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,SAAS,CAAC,EAAE,KAAK,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,GAAG,CAAC;QACV,MAAM,CAAC,EAAE,GAAG,CAAC;KACd,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;IACrB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IAEvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAGhB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,IAAI,CAAC;IAC3C,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IACjE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;IAGjC,WAAW,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAGxC,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,wBAA6B;;;;;2BAoHtB,MAAM;0BAlB3C,MAAM,SACT,MAAM,GAAG,WAAW,GAAG,QAAQ;;0BA1CQ,MAAM,SAAQ,GAAG;;;;;;;;;0CA9BP,MAAM,KAAG,iBAAiB;0BA6J1C,MAAM;EAgChD"}