@idealyst/tooling 1.2.3 → 1.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/tooling",
-  "version": "1.2.3",
+  "version": "1.2.6",
   "description": "Code analysis and validation utilities for Idealyst Framework",
   "readme": "README.md",
   "main": "src/index.ts",

package/src/analyzer/component-analyzer.ts

@@ -18,6 +18,7 @@ import type {
   ComponentAnalyzerOptions,
   ThemeValues,
   ComponentCategory,
+  SampleProps,
 } from './types';
 import { analyzeTheme } from './theme-analyzer';
 
@@ -191,15 +192,153 @@ function analyzeComponentDir(
   // Determine category
   const category = inferCategory(componentName);
 
+  // Look for docs.ts to extract sample props
+  const sampleProps = extractSampleProps(dir);
+
   return {
     name: componentName,
     description,
     props,
     category,
     filePath: path.relative(process.cwd(), dir),
+    sampleProps,
   };
 }
 
+/**
+ * Extract sample props from docs.ts file if it exists.
+ * The docs.ts file should export a `sampleProps` object.
+ */
+function extractSampleProps(dir: string): SampleProps | undefined {
+  const docsPath = path.join(dir, 'docs.ts');
+
+  if (!fs.existsSync(docsPath)) {
+    return undefined;
+  }
+
+  try {
+    const content = fs.readFileSync(docsPath, 'utf-8');
+
+    // Create a simple TypeScript program to extract the sampleProps export
+    const sourceFile = ts.createSourceFile(
+      'docs.ts',
+      content,
+      ts.ScriptTarget.ES2020,
+      true,
+      ts.ScriptKind.TS
+    );
+
+    let samplePropsNode: ts.ObjectLiteralExpression | null = null;
+
+    // Find the sampleProps export
+    ts.forEachChild(sourceFile, (node) => {
+      // Handle: export const sampleProps = { ... }
+      if (ts.isVariableStatement(node)) {
+        const isExported = node.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword);
+        if (isExported) {
+          for (const decl of node.declarationList.declarations) {
+            if (ts.isIdentifier(decl.name) && decl.name.text === 'sampleProps' && decl.initializer) {
+              if (ts.isObjectLiteralExpression(decl.initializer)) {
+                samplePropsNode = decl.initializer;
+              }
+            }
+          }
+        }
+      }
+    });
+
+    if (!samplePropsNode) {
+      return undefined;
+    }
+
+    // Extract the object literal as JSON-compatible structure
+    // This is a simplified extraction - it handles basic literals
+    const result: SampleProps = {};
+
+    for (const prop of samplePropsNode.properties) {
+      if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+        const propName = prop.name.text;
+
+        if (propName === 'props' && ts.isObjectLiteralExpression(prop.initializer)) {
+          result.props = extractObjectLiteral(prop.initializer, content);
+        } else if (propName === 'children') {
+          // For children, we store the raw source text
+          result.children = prop.initializer.getText(sourceFile);
+        } else if (propName === 'state' && ts.isObjectLiteralExpression(prop.initializer)) {
+          // Extract state configuration for controlled components
+          result.state = extractObjectLiteral(prop.initializer, content);
+        }
+      }
+    }
+
+    return Object.keys(result).length > 0 ? result : undefined;
+  } catch (e) {
+    console.warn(`[component-analyzer] Error reading docs.ts in ${dir}:`, e);
+    return undefined;
+  }
+}
+
+/**
+ * Extract an object literal to a plain object (for simple literal values).
+ */
+function extractObjectLiteral(node: ts.ObjectLiteralExpression, sourceContent: string): Record<string, any> {
+  const result: Record<string, any> = {};
+
+  for (const prop of node.properties) {
+    if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+      const key = prop.name.text;
+      const init = prop.initializer;
+
+      if (ts.isStringLiteral(init)) {
+        result[key] = init.text;
+      } else if (ts.isNumericLiteral(init)) {
+        result[key] = Number(init.text);
+      } else if (init.kind === ts.SyntaxKind.TrueKeyword) {
+        result[key] = true;
+      } else if (init.kind === ts.SyntaxKind.FalseKeyword) {
+        result[key] = false;
+      } else if (ts.isArrayLiteralExpression(init)) {
+        result[key] = extractArrayLiteral(init, sourceContent);
+      } else if (ts.isObjectLiteralExpression(init)) {
+        result[key] = extractObjectLiteral(init, sourceContent);
+      } else {
+        // For complex expressions (JSX, functions), store the raw source
+        result[key] = init.getText();
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Extract an array literal to a plain array.
+ */
+function extractArrayLiteral(node: ts.ArrayLiteralExpression, sourceContent: string): any[] {
+  const result: any[] = [];
+
+  for (const element of node.elements) {
+    if (ts.isStringLiteral(element)) {
+      result.push(element.text);
+    } else if (ts.isNumericLiteral(element)) {
+      result.push(Number(element.text));
+    } else if (element.kind === ts.SyntaxKind.TrueKeyword) {
+      result.push(true);
+    } else if (element.kind === ts.SyntaxKind.FalseKeyword) {
+      result.push(false);
+    } else if (ts.isObjectLiteralExpression(element)) {
+      result.push(extractObjectLiteral(element, sourceContent));
+    } else if (ts.isArrayLiteralExpression(element)) {
+      result.push(extractArrayLiteral(element, sourceContent));
+    } else {
+      // For complex expressions, store raw source
+      result.push(element.getText());
+    }
+  }
+
+  return result;
+}
+
 /**
  * Analyze a single property symbol.
  */

package/src/analyzer/types.ts

@@ -28,6 +28,30 @@ export interface PropDefinition {
   required: boolean;
 }
 
+/**
+ * Configuration for a controlled state binding
+ */
+export interface ControlledState {
+  /** Initial value for the state */
+  initial: any;
+  /** The prop name that receives the onChange callback */
+  onChangeProp: string;
+  /** If true, the callback toggles a boolean value instead of receiving a new value */
+  toggle?: boolean;
+}
+
+/**
+ * Sample props for rendering the component in documentation
+ */
+export interface SampleProps {
+  /** Props needed to render the component (required props, sample data) */
+  props?: Record<string, any>;
+  /** Default children for the component */
+  children?: any;
+  /** Controlled state bindings - key is the prop name, value is the state config */
+  state?: Record<string, ControlledState>;
+}
+
 /**
  * Definition of a component in the registry
  */
@@ -46,6 +70,9 @@ export interface ComponentDefinition {
 
   /** Path to the component file (relative) */
   filePath?: string;
+
+  /** Sample props for rendering in documentation (from docs.ts) */
+  sampleProps?: SampleProps;
 }
 
 /**

package/src/index.ts

@@ -27,6 +27,8 @@ export {
   type PropDefinition,
   type ThemeValues,
   type ComponentAnalyzerOptions,
+  type SampleProps,
+  type ControlledState,
 } from './analyzer';
 
 // Vite Plugin (also available via @idealyst/tooling/vite)

package/src/vite-plugin.ts

@@ -7,7 +7,7 @@
  * Usage:
  * ```ts
  * // vite.config.ts
- * import { idealystDocsPlugin } from '@idealyst/tooling/vite';
+ * import { idealystDocsPlugin } from '@idealyst/tooling';
  *
  * export default defineConfig({
  *   plugins: [
@@ -19,7 +19,7 @@
  * });
  * ```
  *
- * Then in your app (no virtual module setup needed!):
+ * Then in your app:
  * ```ts
  * import { componentRegistry, componentNames, getComponentsByCategory } from '@idealyst/tooling';
  * ```
@@ -31,13 +31,6 @@ import * as path from 'path';
 import { analyzeComponents } from './analyzer';
 import type { IdealystDocsPluginOptions, ComponentRegistry } from './analyzer/types';
 
-// Virtual module for backwards compatibility
-const VIRTUAL_MODULE_ID = 'virtual:idealyst-docs';
-const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
-
-// Marker for the tooling package that needs transformation
-const TOOLING_REGISTRY_MARKER = '@idealyst/tooling';
-
 /**
  * Create the Idealyst Docs Vite plugin.
  */
@@ -45,7 +38,7 @@ export function idealystDocsPlugin(options: IdealystDocsPluginOptions): Plugin {
   let registry: ComponentRegistry | null = null;
   let server: ViteDevServer | null = null;
 
-  const { debug = false, output = 'virtual', outputPath } = options;
+  const { debug = false, output, outputPath } = options;
 
   const log = (...args: any[]) => {
     if (debug) console.log('[idealyst-docs]', ...args);
@@ -56,10 +49,15 @@ export function idealystDocsPlugin(options: IdealystDocsPluginOptions): Plugin {
    */
   function generateRegistry(): ComponentRegistry {
     log('Generating component registry...');
+    log('Component paths:', options.componentPaths);
+    log('Theme path:', options.themePath);
 
     try {
       registry = analyzeComponents(options);
       log(`Generated registry with ${Object.keys(registry).length} components`);
+      if (debug) {
+        log('Components found:', Object.keys(registry));
+      }
 
       // Optionally write to file
       if (output === 'file' && outputPath) {
@@ -82,51 +80,6 @@ export function idealystDocsPlugin(options: IdealystDocsPluginOptions): Plugin {
     }
   }
 
-  /**
-   * Generate the virtual module code.
-   */
-  function generateModuleCode(): string {
-    if (!registry) {
-      registry = generateRegistry();
-    }
-
-    return `
-// Auto-generated by @idealyst/tooling
-// This module provides component metadata extracted from TypeScript source
-
-export const componentRegistry = ${JSON.stringify(registry, null, 2)};
-
-// Helper to get component names
-export const componentNames = Object.keys(componentRegistry);
-
-// Helper to get components by category
-export function getComponentsByCategory(category) {
-  return Object.entries(componentRegistry)
-    .filter(([_, def]) => def.category === category)
-    .map(([name]) => name);
-}
-
-// Helper to get prop config for playground
-export function getPropConfig(componentName) {
-  const def = componentRegistry[componentName];
-  if (!def) return {};
-
-  return Object.entries(def.props).reduce((acc, [key, prop]) => {
-    if (prop.values && prop.values.length > 0) {
-      acc[key] = { type: 'select', options: prop.values, default: prop.default };
-    } else if (prop.type === 'boolean') {
-      acc[key] = { type: 'boolean', default: prop.default ?? false };
-    } else if (prop.type === 'string') {
-      acc[key] = { type: 'text', default: prop.default ?? '' };
-    } else if (prop.type === 'number') {
-      acc[key] = { type: 'number', default: prop.default ?? 0 };
-    }
-    return acc;
-  }, {});
-}
-`;
-  }
-
   return {
     name: 'idealyst-docs',
 
@@ -134,18 +87,6 @@ export function getPropConfig(componentName) {
       server = _server;
     },
 
-    resolveId(id) {
-      if (id === VIRTUAL_MODULE_ID) {
-        return RESOLVED_VIRTUAL_MODULE_ID;
-      }
-    },
-
-    load(id) {
-      if (id === RESOLVED_VIRTUAL_MODULE_ID) {
-        return generateModuleCode();
-      }
-    },
-
     // Transform @idealyst/tooling to inject the actual registry
     transform(code, id) {
       // Check if this is the tooling package's index file
@@ -153,7 +94,7 @@ export function getPropConfig(componentName) {
       const isToolingSrc = id.includes('/packages/tooling/src/index.ts');
 
       if (isToolingIndex || isToolingSrc) {
-        log(`Transforming tooling index: ${id}`);
+        console.log(`[idealyst-docs] Transforming tooling index: ${id}`);
 
         if (!registry) {
           registry = generateRegistry();
@@ -162,21 +103,26 @@ export function getPropConfig(componentName) {
         // Replace the placeholder exports with actual values
         let transformed = code;
 
-        // Replace: export const componentRegistry: ComponentRegistry = {};
+        // Replace: export const componentRegistry = {};
+        // Note: TypeScript types are stripped before transform, so we match JS not TS
         transformed = transformed.replace(
-          /export const componentRegistry:\s*ComponentRegistry\s*=\s*\{\};?/,
+          /export const componentRegistry\s*=\s*\{\s*\};?/,
           `export const componentRegistry = ${JSON.stringify(registry, null, 2)};`
         );
 
-        // Replace: export const componentNames: string[] = [];
+        log(`Code transformed: ${code !== transformed}`);
+
+        // Replace: export const componentNames = [];
+        // Note: TypeScript types are stripped before transform
         transformed = transformed.replace(
-          /export const componentNames:\s*string\[\]\s*=\s*\[\];?/,
+          /export const componentNames\s*=\s*\[\s*\];?/,
           `export const componentNames = ${JSON.stringify(Object.keys(registry))};`
         );
 
         // Replace getComponentsByCategory with actual implementation that uses the real registry
+        // Match JS version (no type annotations)
         transformed = transformed.replace(
-          /export function getComponentsByCategory\(category: string\): string\[\] \{[\s\S]*?^\}/m,
+          /export function getComponentsByCategory\(category\)\s*\{[\s\S]*?^\}/m,
           `export function getComponentsByCategory(category) {
   return Object.entries(componentRegistry)
     .filter(([_, def]) => def.category === category)
@@ -185,8 +131,9 @@ export function getPropConfig(componentName) {
         );
 
         // Replace getPropConfig with actual implementation
+        // Match JS version (no type annotations)
         transformed = transformed.replace(
-          /export function getPropConfig\(componentName: string\): Record<string, any> \{[\s\S]*?^\}/m,
+          /export function getPropConfig\(componentName\)\s*\{[\s\S]*?^\}/m,
           `export function getPropConfig(componentName) {
   const def = componentRegistry[componentName];
   if (!def) return {};
@@ -230,21 +177,14 @@ export function getPropConfig(componentName) {
         // Clear cached registry
         registry = null;
 
-        // Invalidate the virtual module (for backwards compatibility)
-        const mod = server.moduleGraph.getModuleById(RESOLVED_VIRTUAL_MODULE_ID);
-        if (mod) {
-          server.moduleGraph.invalidateModule(mod);
-        }
-
-        // Also invalidate the tooling module if it's loaded
+        // Invalidate the tooling module to trigger re-transform
         const toolingMods = Array.from(server.moduleGraph.idToModuleMap.values())
           .filter(m => m.id && (m.id.includes('@idealyst/tooling') || m.id.includes('/packages/tooling/src/index')));
 
-        const modsToInvalidate = mod ? [mod, ...toolingMods] : toolingMods;
-        modsToInvalidate.forEach(m => server.moduleGraph.invalidateModule(m));
+        toolingMods.forEach(m => server.moduleGraph.invalidateModule(m));
 
-        if (modsToInvalidate.length > 0) {
-          return modsToInvalidate;
+        if (toolingMods.length > 0) {
+          return toolingMods;
         }
       }
     },