/webf-native-ui-dev

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

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

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

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

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

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