@openwebf/webf 0.22.5 → 0.22.8

package/src/analyzer.ts

@@ -1,4 +1,5 @@
 import ts, {HeritageClause, ScriptTarget, VariableStatement} from 'typescript';
+import { TSDocParser, TextRange, DocComment } from '@microsoft/tsdoc';
 import {IDLBlob} from './IDLBlob';
 import {
   ClassObject,
@@ -30,6 +31,9 @@ const sourceFileCache = new Map<string, ts.SourceFile>();
 // Cache for type conversions to avoid redundant processing
 const typeConversionCache = new Map<string, ParameterType>();
 
+// TSDoc parser instance
+const tsdocParser = new TSDocParser();
+
 // Type mapping constants for better performance
 const BASIC_TYPE_MAP: Partial<Record<ts.SyntaxKind, FunctionArgumentType>> = {
   [ts.SyntaxKind.StringKeyword]: FunctionArgumentType.dom_string,
@@ -62,7 +66,7 @@ export function analyzer(blob: IDLBlob, definedPropertyCollector: DefinedPropert
     blob.objects = sourceFile.statements
       .map(statement => {
         try {
-          return walkProgram(blob, statement, definedPropertyCollector, unionTypeCollector);
+          return walkProgram(blob, statement, sourceFile, definedPropertyCollector, unionTypeCollector);
         } catch (error) {
           console.error(`Error processing statement in ${blob.source}:`, error);
           return null;
@@ -98,6 +102,118 @@ function getInterfaceName(statement: ts.Statement): string {
   return statement.name.escapedText as string;
 }
 
+function getJSDocComment(node: ts.Node, sourceFile: ts.SourceFile): string | undefined {
+  
+  const sourceText = sourceFile.getFullText();
+  const nodeStart = node.getFullStart();
+  const nodePos = node.getStart(sourceFile);
+  
+  // Get the text between full start and actual start (includes leading trivia)
+  const leadingText = sourceText.substring(nodeStart, nodePos);
+  
+  
+  // Find JSDoc comment in the leading text
+  const jsDocMatch = leadingText.match(/\/\*\*([\s\S]*?)\*\/\s*$/);
+  if (!jsDocMatch) return undefined;
+  
+  // Extract the full JSDoc comment including delimiters
+  const commentText = jsDocMatch[0];
+  const commentStartPos = nodeStart + leadingText.lastIndexOf(commentText);
+  
+  // Create a TextRange for the comment
+  const textRange = TextRange.fromStringRange(
+    sourceText,
+    commentStartPos,
+    commentStartPos + commentText.length
+  );
+  
+  // Parse the JSDoc comment using TSDoc
+  const parserContext = tsdocParser.parseRange(textRange);
+  const docComment = parserContext.docComment;
+  
+  // For now, always use the raw comment to preserve all tags including @default
+  // TSDoc parser doesn't handle @default tags properly out of the box
+  
+  // Fallback to raw comment if TSDoc parsing fails
+  const comment = jsDocMatch[1]
+    .split('\n')
+    .map(line => line.replace(/^\s*\*\s?/, ''))
+    .join('\n')
+    .trim();
+  return comment || undefined;
+}
+
+// Helper function to render TSDoc nodes to string
+function renderDocNodes(nodes: ReadonlyArray<any>): string {
+  return nodes.map(node => {
+    if (node.kind === 'PlainText') {
+      return node.text;
+    } else if (node.kind === 'SoftBreak') {
+      return '\n';
+    } else if (node.kind === 'Paragraph') {
+      return renderDocNodes(node.nodes);
+    }
+    return '';
+  }).join('').trim();
+}
+
+// Special function to get the first JSDoc comment in a file for the first interface
+function getFirstInterfaceJSDoc(statement: ts.InterfaceDeclaration, sourceFile: ts.SourceFile): string | undefined {
+  
+  // Find all interfaces in the file
+  const interfaces: ts.InterfaceDeclaration[] = [];
+  ts.forEachChild(sourceFile, child => {
+    if (ts.isInterfaceDeclaration(child)) {
+      interfaces.push(child);
+    }
+  });
+  
+  // If this is the first interface, check for a file-level JSDoc
+  if (interfaces.length > 0 && interfaces[0] === statement) {
+    const sourceText = sourceFile.getFullText();
+    const firstInterfacePos = statement.getFullStart();
+    
+    // Get all text before the first interface
+    const textBeforeInterface = sourceText.substring(0, firstInterfacePos);
+    
+    // Find the last JSDoc comment before the interface
+    const jsDocMatches = textBeforeInterface.match(/\/\*\*([\s\S]*?)\*\//g);
+    if (jsDocMatches && jsDocMatches.length > 0) {
+      const lastJsDoc = jsDocMatches[jsDocMatches.length - 1];
+      const commentStartPos = textBeforeInterface.lastIndexOf(lastJsDoc);
+      
+      // Create a TextRange for the comment
+      const textRange = TextRange.fromStringRange(
+        sourceText,
+        commentStartPos,
+        commentStartPos + lastJsDoc.length
+      );
+      
+      // Parse the JSDoc comment using TSDoc
+      const parserContext = tsdocParser.parseRange(textRange);
+      const docComment = parserContext.docComment;
+      
+      // Extract the parsed content
+      if (docComment.summarySection) {
+        const summary = renderDocNodes(docComment.summarySection.nodes);
+        if (summary) return summary;
+      }
+      
+      // Fallback to raw comment
+      const comment = lastJsDoc
+        .replace(/^\/\*\*/, '')
+        .replace(/\*\/$/, '')
+        .split('\n')
+        .map(line => line.replace(/^\s*\*\s?/, ''))
+        .join('\n')
+        .trim();
+      return comment || undefined;
+    }
+  }
+  
+  return undefined;
+}
+
 function getHeritageType(heritage: HeritageClause): string | null {
   if (!heritage.types.length) return null;
   
@@ -217,11 +333,15 @@ function getParameterBaseType(type: ts.TypeNode, mode?: ParameterMode): Paramete
   }
   
   if (type.kind === ts.SyntaxKind.LiteralType) {
-    // Handle literal types - check if it's a null literal
+    // Handle literal types
     const literalType = type as ts.LiteralTypeNode;
     if (literalType.literal.kind === ts.SyntaxKind.NullKeyword) {
       return FunctionArgumentType.null;
     }
+    if (literalType.literal.kind === ts.SyntaxKind.StringLiteral) {
+      // Return the string literal value itself
+      return (literalType.literal as ts.StringLiteral).text;
+    }
     return FunctionArgumentType.any;
   }
   
@@ -411,10 +531,10 @@ function isParamsReadOnly(m: ts.PropertySignature): boolean {
   return m.modifiers.some(k => k.kind === ts.SyntaxKind.ReadonlyKeyword);
 }
 
-function walkProgram(blob: IDLBlob, statement: ts.Statement, definedPropertyCollector: DefinedPropertyCollector, unionTypeCollector: UnionTypeCollector) {
+function walkProgram(blob: IDLBlob, statement: ts.Statement, sourceFile: ts.SourceFile, definedPropertyCollector: DefinedPropertyCollector, unionTypeCollector: UnionTypeCollector) {
   switch(statement.kind) {
     case ts.SyntaxKind.InterfaceDeclaration:
-      return processInterfaceDeclaration(statement as ts.InterfaceDeclaration, blob, definedPropertyCollector, unionTypeCollector);
+      return processInterfaceDeclaration(statement as ts.InterfaceDeclaration, blob, sourceFile, definedPropertyCollector, unionTypeCollector);
       
     case ts.SyntaxKind.VariableStatement:
       return processVariableStatement(statement as VariableStatement, unionTypeCollector);
@@ -444,12 +564,19 @@ function processTypeAliasDeclaration(
 function processInterfaceDeclaration(
   statement: ts.InterfaceDeclaration,
   blob: IDLBlob,
+  sourceFile: ts.SourceFile,
   definedPropertyCollector: DefinedPropertyCollector,
   unionTypeCollector: UnionTypeCollector
 ): ClassObject | null {
   const interfaceName = statement.name.escapedText.toString();
   const obj = new ClassObject();
   
+  // Capture JSDoc comment for the interface
+  const directComment = getJSDocComment(statement, sourceFile);
+  const fileComment = getFirstInterfaceJSDoc(statement, sourceFile);
+  obj.documentation = directComment || fileComment;
+  
+  
   // Process heritage clauses
   if (statement.heritageClauses) {
     const heritage = statement.heritageClauses[0];
@@ -470,7 +597,7 @@ function processInterfaceDeclaration(
   
   // Process members in batches for better performance
   const members = Array.from(statement.members);
-  processMembersBatch(members, obj, definedPropertyCollector, unionTypeCollector);
+  processMembersBatch(members, obj, sourceFile, definedPropertyCollector, unionTypeCollector);
   
   ClassObject.globalClassMap[interfaceName] = obj;
   
@@ -480,12 +607,13 @@ function processInterfaceDeclaration(
 function processMembersBatch(
   members: ts.TypeElement[],
   obj: ClassObject,
+  sourceFile: ts.SourceFile,
   definedPropertyCollector: DefinedPropertyCollector,
   unionTypeCollector: UnionTypeCollector
 ): void {
   for (const member of members) {
     try {
-      processMember(member, obj, definedPropertyCollector, unionTypeCollector);
+      processMember(member, obj, sourceFile, definedPropertyCollector, unionTypeCollector);
     } catch (error) {
       console.error(`Error processing member:`, error);
     }
@@ -495,24 +623,25 @@ function processMembersBatch(
 function processMember(
   member: ts.TypeElement,
   obj: ClassObject,
+  sourceFile: ts.SourceFile,
   definedPropertyCollector: DefinedPropertyCollector,
   unionTypeCollector: UnionTypeCollector
 ): void {
   switch(member.kind) {
     case ts.SyntaxKind.PropertySignature:
-      processPropertySignature(member as ts.PropertySignature, obj, definedPropertyCollector, unionTypeCollector);
+      processPropertySignature(member as ts.PropertySignature, obj, sourceFile, definedPropertyCollector, unionTypeCollector);
       break;
       
     case ts.SyntaxKind.MethodSignature:
-      processMethodSignature(member as ts.MethodSignature, obj, unionTypeCollector);
+      processMethodSignature(member as ts.MethodSignature, obj, sourceFile, unionTypeCollector);
       break;
       
     case ts.SyntaxKind.IndexSignature:
-      processIndexSignature(member as ts.IndexSignatureDeclaration, obj, unionTypeCollector);
+      processIndexSignature(member as ts.IndexSignatureDeclaration, obj, sourceFile, unionTypeCollector);
       break;
       
     case ts.SyntaxKind.ConstructSignature:
-      processConstructSignature(member as ts.ConstructSignatureDeclaration, obj, unionTypeCollector);
+      processConstructSignature(member as ts.ConstructSignatureDeclaration, obj, sourceFile, unionTypeCollector);
       break;
   }
 }
@@ -520,12 +649,14 @@ function processMember(
 function processPropertySignature(
   member: ts.PropertySignature,
   obj: ClassObject,
+  sourceFile: ts.SourceFile,
   definedPropertyCollector: DefinedPropertyCollector,
   unionTypeCollector: UnionTypeCollector
 ): void {
   const prop = new PropsDeclaration();
   prop.name = getPropName(member.name!, prop);
   prop.readonly = isParamsReadOnly(member);
+  prop.documentation = getJSDocComment(member, sourceFile);
   
   definedPropertyCollector.properties.add(prop.name);
   
@@ -577,10 +708,12 @@ function createAsyncProperty(prop: PropsDeclaration, mode: ParameterMode): Props
 function processMethodSignature(
   member: ts.MethodSignature,
   obj: ClassObject,
+  sourceFile: ts.SourceFile,
   unionTypeCollector: UnionTypeCollector
 ): void {
   const f = new FunctionDeclaration();
   f.name = getPropName(member.name!);
+  f.documentation = getJSDocComment(member, sourceFile);
   f.args = member.parameters.map(params => 
     paramsNodeToArguments(params, unionTypeCollector)
   );
@@ -639,6 +772,7 @@ function createAsyncMethod(
 function processIndexSignature(
   member: ts.IndexSignatureDeclaration,
   obj: ClassObject,
+  sourceFile: ts.SourceFile,
   unionTypeCollector: UnionTypeCollector
 ): void {
   const prop = new IndexedPropertyDeclaration();
@@ -659,6 +793,7 @@ function processIndexSignature(
 function processConstructSignature(
   member: ts.ConstructSignatureDeclaration,
   obj: ClassObject,
+  sourceFile: ts.SourceFile,
   unionTypeCollector: UnionTypeCollector
 ): void {
   const c = new FunctionDeclaration();

package/src/commands.ts

@@ -395,6 +395,9 @@ async function generateCommand(distPath: string, options: GenerateOptions): Prom
   // Determine if we need to create a new project
   const needsProjectCreation = !hasPackageJson || !hasGlobalDts || !hasTsConfig;
   
+  // Track if this is an existing project (has all required files)
+  const isExistingProject = hasPackageJson && hasGlobalDts && hasTsConfig;
+  
   let framework = options.framework;
   let packageName = options.packageName;
   
@@ -620,7 +623,7 @@ async function generateCommand(distPath: string, options: GenerateOptions): Prom
   // Handle npm publishing if requested via command line option
   if (options.publishToNpm && framework) {
     try {
-      await buildAndPublishPackage(resolvedDistPath, options.npmRegistry);
+      await buildAndPublishPackage(resolvedDistPath, options.npmRegistry, isExistingProject);
     } catch (error) {
       console.error('\nError during npm publish:', error);
       process.exit(1);
@@ -655,7 +658,8 @@ async function generateCommand(distPath: string, options: GenerateOptions): Prom
       try {
         await buildAndPublishPackage(
           resolvedDistPath, 
-          registryAnswer.registry || undefined
+          registryAnswer.registry || undefined,
+          isExistingProject
         );
       } catch (error) {
         console.error('\nError during npm publish:', error);
@@ -760,20 +764,40 @@ async function buildPackage(packagePath: string): Promise<void> {
   }
 }
 
-async function buildAndPublishPackage(packagePath: string, registry?: string): Promise<void> {
+async function buildAndPublishPackage(packagePath: string, registry?: string, isExistingProject: boolean = false): Promise<void> {
   const packageJsonPath = path.join(packagePath, 'package.json');
   
   if (!fs.existsSync(packageJsonPath)) {
     throw new Error(`No package.json found in ${packagePath}`);
   }
   
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+  let packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
   const packageName = packageJson.name;
-  const packageVersion = packageJson.version;
+  let packageVersion = packageJson.version;
   
   // First, ensure dependencies are installed and build the package
   await buildPackage(packagePath);
   
+  // If this is an existing project, increment the patch version before publishing
+  if (isExistingProject) {
+    console.log(`\nIncrementing version for existing project...`);
+    const versionResult = spawnSync(NPM, ['version', 'patch', '--no-git-tag-version'], {
+      cwd: packagePath,
+      encoding: 'utf-8',
+      stdio: 'pipe'
+    });
+    
+    if (versionResult.status !== 0) {
+      console.error('Failed to increment version:', versionResult.stderr);
+      throw new Error('Failed to increment version');
+    }
+    
+    // Re-read package.json to get the new version
+    packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    packageVersion = packageJson.version;
+    console.log(`Version updated to ${packageVersion}`);
+  }
+  
   // Set registry if provided
   if (registry) {
     console.log(`\nUsing npm registry: ${registry}`);

package/src/declaration.ts

@@ -45,6 +45,7 @@ export class PropsDeclaration {
   isSymbol?: boolean;
   readonly: boolean;
   optional: boolean;
+  documentation?: string;
 }
 
 export class IndexedPropertyDeclaration extends PropsDeclaration {
@@ -77,6 +78,7 @@ export class ClassObject {
   staticMethods: FunctionDeclaration[] = [];
   construct?: FunctionDeclaration;
   kind: ClassObjectKind = ClassObjectKind.interface;
+  documentation?: string;
 }
 
 export class FunctionObject {

package/src/react.ts

@@ -4,13 +4,16 @@ import path from 'path';
 import {ParameterType} from "./analyzer";
 import {ClassObject, FunctionArgumentType, FunctionDeclaration, TypeAliasObject} from "./declaration";
 import {IDLBlob} from "./IDLBlob";
-import {getPointerType, isPointerType} from "./utils";
+import {getPointerType, isPointerType, isUnionType} from "./utils";
 
 function readTemplate(name: string) {
   return fs.readFileSync(path.join(__dirname, '../templates/' + name + '.tpl'), {encoding: 'utf-8'});
 }
 
 function generateReturnType(type: ParameterType) {
+  if (isUnionType(type)) {
+    return (type.value as ParameterType[]).map(v => `'${v.value}'`).join(' | ');
+  }
   if (isPointerType(type)) {
     const pointerType = getPointerType(type);
     return pointerType;
@@ -79,6 +82,20 @@ function generateMethodDeclaration(method: FunctionDeclaration) {
   return `${methodName}(${args}): ${returnType};`;
 }
 
+function generateMethodDeclarationWithDocs(method: FunctionDeclaration, indent: string = ''): string {
+  let result = '';
+  if (method.documentation) {
+    result += `${indent}/**\n`;
+    const docLines = method.documentation.split('\n');
+    docLines.forEach(line => {
+      result += `${indent} * ${line}\n`;
+    });
+    result += `${indent} */\n`;
+  }
+  result += `${indent}${generateMethodDeclaration(method)}`;
+  return result;
+}
+
 function toReactEventName(name: string) {
   const eventName = 'on-' + name;
   return _.camelCase(eventName);
@@ -115,10 +132,14 @@ export function generateReactComponent(blob: IDLBlob, packageName?: string, rela
   const events = classObjects.filter(object => {
     return object.name.endsWith('Events');
   });
+  const methods = classObjects.filter(object => {
+    return object.name.endsWith('Methods');
+  });
 
   const others = classObjects.filter(object => {
     return !object.name.endsWith('Properties')
-      && !object.name.endsWith('Events');
+      && !object.name.endsWith('Events')
+      && !object.name.endsWith('Methods');
   });
 
   // Include type aliases
@@ -128,6 +149,21 @@ export function generateReactComponent(blob: IDLBlob, packageName?: string, rela
   
   const dependencies = [
     typeAliasDeclarations,
+    // Include Methods interfaces as dependencies
+    methods.map(object => {
+      const methodDeclarations = object.methods.map(method => {
+        return generateMethodDeclarationWithDocs(method, '  ');
+      }).join('\n');
+
+      let interfaceDoc = '';
+      if (object.documentation) {
+        interfaceDoc = `/**\n${object.documentation.split('\n').map(line => ` * ${line}`).join('\n')}\n */\n`;
+      }
+
+      return `${interfaceDoc}interface ${object.name} {
+${methodDeclarations}
+}`;
+    }).join('\n\n'),
     others.map(object => {
       const props = object.props.map(prop => {
         if (prop.optional) {
@@ -146,8 +182,8 @@ interface ${object.name} {
   // Generate all components from this file
   const components: string[] = [];
   
-  // Create a map of component names to their properties and events
-  const componentMap = new Map<string, { properties?: ClassObject, events?: ClassObject }>();
+  // Create a map of component names to their properties, events, and methods
+  const componentMap = new Map<string, { properties?: ClassObject, events?: ClassObject, methods?: ClassObject }>();
   
   // Process all Properties interfaces
   properties.forEach(prop => {
@@ -167,6 +203,15 @@ interface ${object.name} {
     componentMap.get(componentName)!.events = event;
   });
   
+  // Process all Methods interfaces
+  methods.forEach(method => {
+    const componentName = method.name.replace(/Methods$/, '');
+    if (!componentMap.has(componentName)) {
+      componentMap.set(componentName, {});
+    }
+    componentMap.get(componentName)!.methods = method;
+  });
+  
   // If we have multiple components, we need to generate a combined file
   const componentEntries = Array.from(componentMap.entries());
   
@@ -202,6 +247,7 @@ interface ${object.name} {
       className: className,
       properties: component.properties,
       events: component.events,
+      methods: component.methods,
       classObjectDictionary,
       dependencies,
       blob,
@@ -209,6 +255,7 @@ interface ${object.name} {
       toWebFTagName,
       generateReturnType,
       generateMethodDeclaration,
+      generateMethodDeclarationWithDocs,
       generateEventHandlerType,
       getEventType,
     });
@@ -240,6 +287,7 @@ interface ${object.name} {
       className: className,
       properties: component.properties,
       events: component.events,
+      methods: component.methods,
       classObjectDictionary,
       dependencies: '', // Dependencies will be at the top
       blob,
@@ -247,6 +295,7 @@ interface ${object.name} {
       toWebFTagName,
       generateReturnType,
       generateMethodDeclaration,
+      generateMethodDeclarationWithDocs,
       generateEventHandlerType,
       getEventType,
     });

package/templates/react.component.tsx.tpl

@@ -7,12 +7,18 @@ export interface <%= className %>Props {
   <% _.forEach(properties?.props, function(prop, index) { %>
     <% var propName = _.camelCase(prop.name); %>
     <% var attributeName = _.kebabCase(prop.name); %>
+    <% if (prop.documentation) { %>
+  /**
+   * <%= prop.documentation.split('\n').join('\n   * ') %>
+   */
+    <% } else { %>
   /**
    * <%= propName %> property
     <% if (prop.optional) { %>
    * @default undefined
     <% } %>
    */
+    <% } %>
     <% if (prop.optional) { %>
   <%= propName %>?: <%= generateReturnType(prop.type) %>;
     <% } else { %>
@@ -22,9 +28,15 @@ export interface <%= className %>Props {
   <% }); %>
   <% _.forEach(events?.props, function(prop, index) { %>
     <% var propName = toReactEventName(prop.name); %>
+    <% if (prop.documentation) { %>
+  /**
+   * <%= prop.documentation.split('\n').join('\n   * ') %>
+   */
+    <% } else { %>
   /**
    * <%= prop.name %> event handler
    */
+    <% } %>
   <%= propName %>?: (event: <%= getEventType(prop.type) %>) => void;
   
   <% }); %>
@@ -44,24 +56,63 @@ export interface <%= className %>Props {
   className?: string;
 }
 
+<% if (methods && methods.methods.length > 0) { %>
+/**
+ * Element interface with methods accessible via ref
+ * @example
+ * ```tsx
+ * const ref = useRef<<%= className %>Element>(null);
+ * // Call methods on the element
+ * ref.current?.finishRefresh('success');
+ * ```
+ */
+<% } %>
 export interface <%= className %>Element extends WebFElementWithMethods<{
-  <% _.forEach(properties?.methods, function(method, index) { %>
-  <%= generateMethodDeclaration(method) %>
+  <% _.forEach(methods?.methods, function(method, index) { %>
+<%= generateMethodDeclarationWithDocs(method, '  ') %>
   <% }); %>
 }> {}
 
+<% if (properties?.documentation || methods?.documentation || events?.documentation) { %>
+  <% const docs = properties?.documentation || methods?.documentation || events?.documentation; %>
+/**
+ * <%= docs %>
+ * 
+ * @example
+ * ```tsx<% if (methods && methods.methods.length > 0) { %>
+ * const ref = useRef<<%= className %>Element>(null);<% } %>
+ * 
+ * <<%= className %><% if (methods && methods.methods.length > 0) { %>
+ *   ref={ref}<% } %>
+ *   // Add props here
+ * >
+ *   Content
+ * </<%= className %>><% if (methods && methods.methods.length > 0) { %>
+ * 
+ * // Call methods on the element
+ * ref.current?.finishRefresh('success');<% } %>
+ * ```
+ */
+<% } else { %>
 /**
  * <%= className %> - WebF <%= className %> component
  * 
  * @example
- * ```tsx
- * <<%= className %>
- *   // Add example props here
+ * ```tsx<% if (methods && methods.methods.length > 0) { %>
+ * const ref = useRef<<%= className %>Element>(null);<% } %>
+ * 
+ * <<%= className %><% if (methods && methods.methods.length > 0) { %>
+ *   ref={ref}<% } %>
+ *   // Add props here
  * >
  *   Content
- * </<%= className %>>
+ * </<%= className %>><% if (methods && methods.methods.length > 0) { %>
+ * 
+ * // Call methods on the element
+ * ref.current?.finishRefresh('success');<% } %>
  * ```
  */
+<% } %>
 export const <%= className %> = createWebFComponent<<%= className %>Element, <%= className %>Props>({
   tagName: '<%= toWebFTagName(className) %>',
   displayName: '<%= className %>',