webf-native-ui-dev

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

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)

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 │

└─────────────────────────────────────────┘

```

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 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 .

*/

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 .

*/

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 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 (

);

}

```

Vue example:

```vue

```

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/

```

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 parsed = jsonDecode(value);

_items = parsed.cast>();

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,

);

}

```

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"');

_variant = 'filled';

}

setState(() {});

}

```

2. Debouncing Frequent Updates

```dart

Timer? _debounceTimer;

@override

set searchQuery(String value) {

_searchQuery = value;

// Debounce search

_debounceTimer?.cancel();

_debounceTimer = Timer(Duration(milliseconds: 300), () {

_performSearch();

});

}

```

3. Lifecycle Management

```dart

@override

void didMount() {

super.didMount();

// Called when element is inserted into DOM

_initializeWidget();

}

@override

void dispose() {

// Clean up resources

_debounceTimer?.cancel();

_focusNode.dispose();

super.dispose();

}

```

4. Error Handling

```dart

@override

set jsonData(String? value) {

if (value == null || value.isEmpty) {

_data = null;

return;

}

try {

_data = jsonDecode(value);

setState(() {});

} catch (e) {

print('Error parsing JSON: $e');

// Dispatch error event

dispatchEvent(CustomEvent('error', detail: {'message': e.toString()}));

}

}

```

Basic Generation

```bash

# Generate React components

webf codegen output-dir --flutter-package-src=./my_package --framework=react

# Generate Vue components

webf codegen output-dir --flutter-package-src=./my_package --framework=vue

# Specify package name

webf codegen output-dir \

--flutter-package-src=./my_package \

--framework=react \

--package-name=@mycompany/my-ui-lib

```

Auto-Publishing

```bash

# Publish to npm after generation

webf codegen output-dir \

--flutter-package-src=./my_package \

--framework=react \

--publish-to-npm

# Publish to custom registry

webf codegen output-dir \

--flutter-package-src=./my_package \

--framework=react \

--publish-to-npm \

--npm-registry=https://registry.company.com/

```

Project Auto-Creation

The CLI auto-creates projects if files are missing:

• If package.json, tsconfig.json, or global.d.ts are missing, it creates a new project
• If framework is not specified, it prompts interactively
• Uses existing configuration if project already exists

Issue: Bindings file not found

Error: Error: Could not find 'button_bindings_generated.dart'

Solution:

1. Make sure you've run the CLI code generation
2. Check that .d.ts files are in the same directory as .dart files
3. Verify interface naming (must end with Properties or Events)

Issue: Properties not updating in UI

Cause: Not calling setState() after property changes

Solution:

```dart

@override

set myProperty(String value) {

_myProperty = value;

setState(() {}); // ← Don't forget this!

}

```

Issue: Events not firing in JavaScript

Cause: Event name mismatch or not dispatching events

Solution:

```dart

// Make sure event names match your TypeScript definitions

widgetElement.dispatchEvent(Event('click')); // matches 'click' in TypeScript

```

Issue: TypeScript types not working

Cause: Generated types not exported properly

Solution: Check that generated package.json exports types:

```json

{

"types": "./dist/index.d.ts",

"exports": {

".": {

"types": "./dist/index.d.ts",

"import": "./dist/index.js"

}

}

}

```

See [Complete Example](./example-input.md) for a full implementation of a text input component with:

• Flutter TextFormField wrapper
• TypeScript definitions
• Event handling
• Validation
• Methods (focus, blur, clear)
• CSS integration

• CLI Development Guide: [cli/CLAUDE.md](https://github.com/openwebf/webf/blob/main/cli/CLAUDE.md)
• TypeScript Guide: [CLI TYPING_GUIDE.md](https://github.com/openwebf/webf/blob/main/cli/TYPING_GUIDE.md)
• Example Package: [native_uis/webf_cupertino_ui](https://github.com/openwebf/webf/tree/main/native_uis/webf_cupertino_ui)
• WebF Architecture: [docs/ARCHITECTURE.md](https://github.com/openwebf/webf/blob/main/docs/ARCHITECTURE.md)
• Official Documentation: https://openwebf.com/en/docs/developer-guide/native-ui

After creating your native UI library:

1. Test thoroughly on all target platforms (iOS, Android, desktop)
2. Write documentation for each component (see existing .md files in webf_cupertino_ui)
3. Create example apps demonstrating usage
4. Publish to pub.dev (Flutter) and npm (JavaScript)
5. Maintain compatibility with WebF version updates

• ✅ Native UI libraries wrap Flutter widgets as web-accessible custom elements
• ✅ Write Dart wrappers extending WebFWidgetElement
• ✅ Write TypeScript definitions (.d.ts) for each component
• ✅ Use WebF CLI to generate React/Vue components
• ✅ Test in both Flutter and JavaScript environments
• ✅ Publish to pub.dev (Flutter) and npm (JavaScript)
• ✅ Follow existing patterns from webf_cupertino_ui for reference