webf-native-ui-dev

# WebF Native UI Development Want to create your own native UI library for WebF by wrapping Flutter widgets? This skill guides you through the complete process of building custom native UI libraries that make Flutter widgets accessible from JavaScript/TypeScript with React and Vue support. ## What is Native UI Development? Native UI development in WebF means: - **Wrapping Flutter widgets** as WebF custom elements - **Bridging native Flutter UI** to web technologies (HTML/JavaScript) - **Creating reusable component libraries** that work with React, Vue, and vanilla JavaScript - **Publishing npm packages** with type-safe TypeScript definitions ## When to Create a Native UI Library ### Use Cases: - ✅ You want to expose Flutter widgets to web developers - ✅ You need to wrap a Flutter package for WebF use - ✅ You're building a design system with native performance - ✅ You want to create platform-specific components (iOS, Android, etc.) - ✅ You need custom widgets beyond HTML/CSS capabilities ### Don't Create a Native UI Library When: - ❌ HTML/CSS can achieve the same result (use standard web) - ❌ You just need to use existing UI libraries (see `webf-native-ui` skill) - ❌ You're building a one-off component (use WebF widget element directly) ## Architecture Overview A native UI library consists of three layers: ``` ┌─────────────────────────────────────────┐ │ JavaScript/TypeScript (React/Vue) │ ← Generated by CLI │ @openwebf/my-component-lib │ ├─────────────────────────────────────────┤ │ TypeScript Definitions (.d.ts) │ ← You write this │ Component interfaces and events │ ├─────────────────────────────────────────┤ │ Dart (Flutter) │ ← You write this │ Flutter widget wrappers │ │ my_component_lib package │ └─────────────────────────────────────────┘ ``` ## Development Workflow ### Overview ```bash # 1. Create Flutter package with Dart wrappers # 2. Write TypeScript definition files # 3. Generate React/Vue components with WebF CLI # 4. Test and publish webf codegen my-ui-lib --flutter-package-src=./flutter_package ``` ## Step-by-Step Guide ### Step 1: Create Flutter Package Structure Create a standard Flutter package: ```bash # Create Flutter package flutter create --template=package my_component_lib cd my_component_lib ``` **Directory structure:** ``` my_component_lib/ ├── lib/ │ ├── my_component_lib.dart # Main export file │ └── src/ │ ├── button.dart # Dart widget wrapper │ ├── button.d.ts # TypeScript definitions │ ├── input.dart │ └── input.d.ts ├── pubspec.yaml └── README.md ``` **pubspec.yaml dependencies:** ```yaml dependencies: flutter: sdk: flutter webf: ^0.24.0 # Latest WebF version ``` ### Step 2: Write Dart Widget Wrappers Create a Dart class that wraps your Flutter widget: **Example: lib/src/button.dart** ```dart import 'package:flutter/widgets.dart'; import 'package:webf/webf.dart'; import 'button_bindings_generated.dart'; // Will be generated by CLI /// Custom button component wrapping Flutter widgets class MyCustomButton extends MyCustomButtonBindings { MyCustomButton(super.context); // Internal state String _variant = 'filled'; bool _disabled = false; // Property getters/setters (implement interface from bindings) @override String get variant => _variant; @override set variant(String value) { _variant = value; // Trigger rebuild when property changes setState(() {}); } @override bool get disabled => _disabled; @override set disabled(bool value) { _disabled = value; setState(() {}); } @override WebFWidgetElementState createState() { return MyCustomButtonState(this); } } class MyCustomButtonState extends WebFWidgetElementState { MyCustomButtonState(super.widgetElement); @override MyCustomButton get widgetElement => super.widgetElement as MyCustomButton; @override Widget build(BuildContext context) { return GestureDetector( onTap: widgetElement.disabled ? null : () { // Dispatch click event to JavaScript widgetElement.dispatchEvent(Event('click')); }, child: Container( padding: EdgeInsets.all(12), decoration: BoxDecoration( color: _getBackgroundColor(), borderRadius: BorderRadius.circular(8), ), child: Text( // Get text from child nodes widgetElement.getTextContent() ?? 'Button', style: TextStyle( color: widgetElement.disabled ? Colors.grey : Colors.white, ), ), ), ); } Color _getBackgroundColor() { if (widgetElement.disabled) return Colors.grey[400]!; switch (widgetElement.variant) { case 'filled': return Colors.blue; case 'outlined': return Colors.transparent; default: return Colors.blue; } } } ``` ### Step 3: Write TypeScript Definitions Create a `.d.ts` file alongside your Dart file: **Example: lib/src/button.d.ts** ```typescript /** * Custom button component with multiple variants. */ /** * Properties for <my-custom-button>. */ interface MyCustomButtonProperties { /** * Button variant style. * Supported values: 'filled' | 'outlined' | 'text' * @default 'filled' */ variant?: string; /** * Whether the button is disabled. * @default false */ disabled?: boolean; } /** * Events for <my-custom-button>. */ interface MyCustomButtonEvents { /** * Fired when the button is clicked. */ click: Event; } ``` **TypeScript Guidelines:** - Interface names must end with `Properties` or `Events` - Use `?` for optional properties (except booleans, which are always non-nullable in Dart) - Use `CustomEvent<T>` for events with data - Add JSDoc comments for documentation - See the [TypeScript Definition Guide](./typescript-guide.md) for more details ### Step 4: Create Main Export File **lib/my_component_lib.dart:** ```dart library my_component_lib; import 'package:webf/webf.dart'; import 'src/button.dart'; export 'src/button.dart'; /// Install all components in this library void installMyComponentLib() { // Register custom elements WebFController.defineCustomElement( 'my-custom-button', (context) => MyCustomButton(context), ); // Add more components here // WebFController.defineCustomElement('my-custom-input', ...); } ``` ### Step 5: Generate React/Vue Components Use the WebF CLI to generate JavaScript/TypeScript components: ```bash # Install WebF CLI globally (if not already installed) npm install -g @openwebf/webf-cli # Generate TypeScript bindings and React/Vue components webf codegen my-ui-lib-react \ --flutter-package-src=./my_component_lib \ --framework=react webf codegen my-ui-lib-vue \ --flutter-package-src=./my_component_lib \ --framework=vue ``` **What the CLI does:** 1. ✅ Parses your `.d.ts` files 2. ✅ Generates Dart binding classes (`*_bindings_generated.dart`) 3. ✅ Creates React components with proper TypeScript types 4. ✅ Creates Vue components with TypeScript support 5. ✅ Copies `.d.ts` files to output directory 6. ✅ Creates `package.json` with correct metadata 7. ✅ Runs `npm run build` if a build script exists **Generated output structure:** ``` my-ui-lib-react/ ├── src/ │ ├── MyCustomButton.tsx # React component │ └── index.ts # Main export ├── dist/ # Built files (after npm run build) ├── package.json ├── tsconfig.json └── README.md ``` ### Step 6: Test Your Components #### Test in Flutter App **In your Flutter app's main.dart:** ```dart import 'package:my_component_lib/my_component_lib.dart'; void main() { WebFControllerManager.instance.initialize(WebFControllerManagerConfig( maxAliveInstances: 2, maxAttachedInstances: 1, )); // Install your component library installMyComponentLib(); runApp(MyApp()); } ``` #### Test in JavaScript/TypeScript **React example:** ```tsx import { MyCustomButton } from '@openwebf/my-ui-lib-react'; function App() { return ( <div> <MyCustomButton variant="filled" onClick={() => console.log('Clicked!')} > Click Me </MyCustomButton> </div> ); } ``` **Vue example:** ```vue <template> <div> <MyCustomButton variant="filled" @click="handleClick" > Click Me </MyCustomButton> </div> </template> <script setup> import { MyCustomButton } from '@openwebf/my-ui-lib-vue'; const handleClick = () => { console.log('Clicked!'); }; </script> ``` ### Step 7: Publish Your Library #### Publish Flutter Package ```bash # In Flutter package directory flutter pub publish # Or for private packages flutter pub publish --server=https://your-private-registry.com ``` #### Publish npm Packages ```bash # Automatic publishing with CLI webf codegen my-ui-lib-react \ --flutter-package-src=./my_component_lib \ --framework=react \ --publish-to-npm # Or manual publishing cd my-ui-lib-react npm publish ``` **For custom npm registry:** ```bash webf codegen my-ui-lib-react \ --flutter-package-src=./my_component_lib \ --framework=react \ --publish-to-npm \ --npm-registry=https://registry.your-company.com/ ``` ## Advanced Patterns ### 1. Handling Complex Properties **TypeScript:** ```typescript interface MyComplexWidgetProperties { // JSON string properties for complex data items?: string; // Will be JSON.parse() in Dart // Enum-like values alignment?: 'left' | 'center' | 'right'; // Numeric properties maxLength?: number; opacity?: number; } ``` **Dart:** ```dart @override set items(String? value) { if (value != null) { try { final List<dynamic> parsed = jsonDecode(value); _items = parsed.cast<Map<String, dynamic>>(); setState(() {}); } catch (e) { print('Error parsing items: $e'); } } } ``` ### 2. Dispatching Custom Events with Data **Dart:** ```dart void _handleValueChange(String newValue) { // Dispatch CustomEvent with data widgetElement.dispatchEvent(CustomEvent( 'change', detail: {'value': newValue}, )); } ``` **TypeScript:** ```typescript interface MyInputEvents { change: CustomEvent<{value: string}>; } ``` ### 3. Calling Methods from JavaScript **TypeScript:** ```typescript interface MyInputProperties { // Regular properties value?: string; // Methods focus(): void; clear(): void; } ``` **Dart:** ```dart class MyInput extends MyInputBindings { final FocusNode _focusNode = FocusNode(); @override void focus() { _focusNode.requestFocus(); } @override void clear() { // Clear the input value = ''; // Dispatch event dispatchEvent(Event('input')); } } ``` ### 4. Reading CSS Styles **Dart:** ```dart @override Widget build(BuildContext context) { // Read CSS properties final renderStyle = widgetElement.renderStyle; final backgroundColor = renderStyle.backgroundColor?.value; final borderRadius = renderStyle.borderRadius; return Container( decoration: BoxDecoration( color: backgroundColor ?? Colors.blue, borderRadius: BorderRadius.circular( borderRadius?.topLeft?.x ?? 8.0 ), ), child: buildChild(), ); } ``` ### 5. Handling Child Elements **Dart:** ```dart @override Widget build(BuildContext context) { // Get text content from child nodes final text = widgetElement.getTextContent() ?? ''; // Build child widgets final children = widgetElement.children.map((child) { return child.renderObject?.widget ?? SizedBox(); }).toList(); return Column( children: children, ); } ``` ## Common Patterns and Best Practices ### 1. Property Validation ```dart @override set variant(String value) { const validVariants = ['filled', 'outlined', 'text']; if (validVariants.contains(value)) { _variant = value; } else { print('Warning: Invalid variant "$value"');