@idealyst/tooling 1.2.4 → 1.2.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idealyst/tooling",
-  "version": "1.2.4",
+  "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)