webf-native-ui-dev by openwebf

---
name: webf-native-ui-dev
description: Develop custom native UI libraries based on Flutter widgets for WebF. Create reusable component libraries that wrap Flutter widgets as web-accessible custom elements. Use when building UI libraries, wrapping Flutter packages, or creating native component systems.
---

# 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"');
    _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()}));
  }
}
```

## CLI Command Reference

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

## Troubleshooting

### 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"
    }
  }
}
```

## Complete Example: Text Input Component

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

## Resources

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

## Next Steps

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

## Summary

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