@openwebf/webf 0.22.4 → 0.22.6

package/TYPING_GUIDE.md

@@ -0,0 +1,208 @@
+# WebF TypeScript Definition Files (.d.ts) Writing Guide
+
+This guide explains how to write TypeScript definition files (.d.ts) for WebF custom elements that will be parsed by the WebF CLI to generate Dart bindings and React/Vue components.
+
+## Basic Structure
+
+Each WebF custom element should have two interfaces:
+1. `<ComponentName>Properties` - Defines the element's properties/attributes
+2. `<ComponentName>Events` - Defines the element's events
+
+The component name is derived by removing the "Properties" or "Events" suffix.
+
+## Interface Naming Convention
+
+```typescript
+// For a component named "FlutterCupertinoButton"
+interface FlutterCupertinoButtonProperties {
+  // properties...
+}
+
+interface FlutterCupertinoButtonEvents {
+  // events...
+}
+```
+
+## Properties Interface
+
+### Basic Property Types
+
+The CLI supports the following TypeScript types that map to Dart types:
+
+- `string` → `String` (Dart)
+- `number` → `double` (Dart) 
+- `int` → `int` (Dart) - Use type alias `type int = number`
+- `boolean` → `bool` (Dart)
+- `any` → `dynamic` (Dart)
+- `void` → `void` (Dart)
+
+### Property Syntax
+
+```typescript
+interface FlutterCupertinoButtonProperties {
+  // Required property
+  variant: string;
+  
+  // Optional property (use ? modifier)
+  size?: string;
+  
+  // Boolean property (always non-nullable in Dart)
+  disabled?: boolean;
+  
+  // Kebab-case properties (for HTML attributes)
+  'pressed-opacity'?: string;
+}
+```
+
+### Important Rules for Properties
+
+1. **Boolean properties are always non-nullable** in the generated Dart code, even if marked as optional with `?`
+2. **Kebab-case properties** should be quoted (e.g., `'pressed-opacity'`)
+3. **Optional properties** use the `?` modifier and will be nullable in Dart (except booleans)
+4. **Methods in Properties interface** become instance methods on the element
+
+### Methods in Properties
+
+Methods defined in the Properties interface become callable methods on the element:
+
+```typescript
+interface FlutterCupertinoInputProperties {
+  // Properties
+  val?: string;
+  placeholder?: string;
+  
+  // Methods
+  getValue(): string;
+  setValue(value: string): void;
+  focus(): void;
+  blur(): void;
+}
+```
+
+## Events Interface
+
+Events are defined as properties of the Events interface, where:
+- Property name = event name
+- Property type = event type (usually `Event` or `CustomEvent<T>`)
+
+```typescript
+interface FlutterCupertinoButtonEvents {
+  // Standard DOM event
+  click: Event;
+}
+
+interface FlutterCupertinoInputEvents {
+  // CustomEvent with string detail
+  input: CustomEvent<string>;
+  submit: CustomEvent<string>;
+}
+
+interface FlutterCupertinoSwitchEvents {
+  // CustomEvent with boolean detail
+  change: CustomEvent<boolean>;
+}
+```
+
+### Event Type Guidelines
+
+- Use `Event` for standard DOM events
+- Use `CustomEvent<T>` for custom events with data:
+  - `CustomEvent<string>` for string data
+  - `CustomEvent<number>` for numeric data
+  - `CustomEvent<boolean>` for boolean data
+
+## Attribute Handling
+
+The CLI automatically handles type conversion for HTML attributes:
+
+1. **Boolean attributes**: 
+   - HTML: `disabled` or `disabled="true"` → Dart: `true`
+   - HTML: `disabled="false"` or absent → Dart: `false`
+
+2. **Numeric attributes**:
+   - HTML: `maxlength="100"` → Dart: `100` (int)
+   - HTML: `opacity="0.5"` → Dart: `0.5` (double)
+
+3. **String attributes**: Passed through as-is
+
+## Complete Example
+
+Here's a complete example for a switch component:
+
+```typescript
+// Type alias for int (optional, for clarity)
+type int = number;
+
+interface FlutterCupertinoSwitchProperties {
+  // Boolean property (non-nullable in Dart)
+  checked?: boolean;
+  
+  // Boolean property 
+  disabled?: boolean;
+  
+  // Kebab-case string properties
+  'active-color'?: string;
+  'inactive-color'?: string;
+}
+
+interface FlutterCupertinoSwitchEvents {
+  // CustomEvent with boolean detail
+  change: CustomEvent<boolean>;
+}
+```
+
+## Special Types and Features
+
+### Arrays
+Arrays are supported but rarely used in element properties:
+```typescript
+interface ExampleProperties {
+  items?: string[];  // Generates String[]? in Dart
+}
+```
+
+### Object Types
+Reference other interfaces for complex types:
+```typescript
+interface ItemData {
+  id: string;
+  label: string;
+}
+
+interface ListProperties {
+  selectedItem?: ItemData;
+}
+```
+
+## Best Practices
+
+1. **Keep interfaces simple** - Properties should represent HTML attributes or simple methods
+2. **Use optional properties** for all attributes that have default values
+3. **Document complex properties** with JSDoc comments (these are preserved in generated code)
+4. **Follow naming conventions**:
+   - PascalCase for interface names
+   - camelCase for property names (except kebab-case HTML attributes)
+   - Properties interface name must end with "Properties"
+   - Events interface name must end with "Events"
+
+## What to Avoid
+
+1. **Don't use complex union types** - Keep types simple
+2. **Don't use generics** in property types (except CustomEvent<T>)
+3. **Don't use function types** as properties - Define them as methods instead
+4. **Don't forget the Events interface** - Even if there are no events, include an empty interface
+
+## Testing Your Definitions
+
+After writing your .d.ts file:
+
+1. Run the CLI generator to ensure it parses correctly
+2. Check the generated Dart bindings match your expectations
+3. Verify the React/Vue components have the correct prop types
+
+## File Naming
+
+Name your .d.ts files to match the Dart file:
+- `button.dart` → `button.d.ts`
+- `switch.dart` → `switch.d.ts`
+- `tab.dart` → `tab.d.ts`

package/dist/commands.js

@@ -317,6 +317,8 @@ function generateCommand(distPath, options) {
         const hasTsConfig = fs_1.default.existsSync(tsConfigPath);
         // 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;
         // Validate and sanitize package name if provided
@@ -526,7 +528,7 @@ function generateCommand(distPath, options) {
         // Handle npm publishing if requested via command line option
         if (options.publishToNpm && framework) {
             try {
-                yield buildAndPublishPackage(resolvedDistPath, options.npmRegistry);
+                yield buildAndPublishPackage(resolvedDistPath, options.npmRegistry, isExistingProject);
             }
             catch (error) {
                 console.error('\nError during npm publish:', error);
@@ -561,7 +563,7 @@ function generateCommand(distPath, options) {
                         }
                     }]);
                 try {
-                    yield buildAndPublishPackage(resolvedDistPath, registryAnswer.registry || undefined);
+                    yield buildAndPublishPackage(resolvedDistPath, registryAnswer.registry || undefined, isExistingProject);
                 }
                 catch (error) {
                     console.error('\nError during npm publish:', error);
@@ -652,17 +654,34 @@ function buildPackage(packagePath) {
         }
     });
 }
-function buildAndPublishPackage(packagePath, registry) {
-    return __awaiter(this, void 0, void 0, function* () {
+function buildAndPublishPackage(packagePath_1, registry_1) {
+    return __awaiter(this, arguments, void 0, function* (packagePath, registry, isExistingProject = false) {
         const packageJsonPath = path_1.default.join(packagePath, 'package.json');
         if (!fs_1.default.existsSync(packageJsonPath)) {
             throw new Error(`No package.json found in ${packagePath}`);
         }
-        const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf-8'));
+        let packageJson = JSON.parse(fs_1.default.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
         yield 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 = (0, child_process_1.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_1.default.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/global.d.ts

@@ -0,0 +1,2 @@
+type double = number;
+type int = number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwebf/webf",
-  "version": "0.22.4",
+  "version": "0.22.6",
   "description": "Command line tools for WebF",
   "main": "index.js",
   "bin": {
@@ -11,7 +11,10 @@
     "dist",
     "src",
     "templates",
-    "test"
+    "test",
+    "global.d.ts",
+    "tsconfig.json",
+    "TYPING_GUIDE.md"
   ],
   "scripts": {
     "build": "tsc",

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/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es6",
+    "lib": [
+      "es6",
+      "es7",
+      "DOM"
+    ],
+    "allowJs": false,
+    "moduleResolution": "node",
+    "forceConsistentCasingInFileNames": false,
+    "noImplicitReturns": true,
+    "noImplicitThis": true,
+    "noImplicitAny": true,
+    "strictNullChecks": true,
+    "noUnusedLocals": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "declaration": false,
+    "outDir": "./dist"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+  ]
+}