# Duck quickstart (plain text)
# Flutter over-the-air (OTA) UI updates. Package: duck 1.0.3 on pub.dev (Apache-2.0).
# Duck updates UI configuration (JSON canvases), not compiled Dart code or native code. Free tier: 1 app, 1 page.
# Page version: https://duck.flexxxlab.com/docs   Index: https://duck.flexxxlab.com/llms.txt

## 1. Install
flutter pub add duck

# or in pubspec.yaml:
dependencies:
  duck: ^1.0.3

## 2. Initialise Duck (once, at startup, in lib/main.dart)
import 'package:duck/duck.dart';
import 'package:flutter/material.dart';

void main() {
  // Public demo API. Replace with your own Duck API base URL.
  Duck(baseUrl: 'https://duck-demo.flexxxlab.com/api', components: {});

  runApp(const MyApp());
}

## 3. Create a canvas
Open https://duck-demo.flexxxlab.com/ (Duck Builder), arrange components, save, copy the canvas id.
Built-in component types: container, sectionHeader, heroCard, smallCard, infoDisplay, tableCell.

## 4. Render the canvas (this is the OTA step)
import 'package:duck/core/duck_canvas/duck_canvas_widget.dart';
import 'package:flutter/material.dart';

class MyHomePage extends StatelessWidget {
  const MyHomePage({super.key});

  @override
  Widget build(BuildContext context) {
    // Canvas id from Duck Builder (https://duck-demo.flexxxlab.com/).
    const canvasId = '6956a659beea0c7c40b51e8c'; // public demo canvas
    return Scaffold(
      appBar: AppBar(title: const Text('Duck demo')),
      body: const DuckCanvasWidget(canvasId: canvasId),
    );
  }
}

# Edit and save the canvas in Duck Builder; the app shows the new layout next time it loads
# (DuckCanvasWidget also supports pull-to-refresh). No store release needed for supported views.

## 5. Optional: custom components
# Extend DuckComponent, build the widget, run build_runner for the json_serializable part file,
# then register the parser.
import 'package:duck/core/duck_component/duck_component.dart';
import 'package:duck/core/duck_component/duck_component_list_converter.dart';
import 'package:flutter/widgets.dart';
import 'package:json_annotation/json_annotation.dart';

part 'horizontal_container_data.g.dart';

@JsonSerializable()
class HorizontalContainerData extends DuckComponent {
  static const String componentType = 'horizontalContainer';

  @override
  String get type => componentType;

  @DuckComponentListConverter()
  final List<DuckComponent> list;

  HorizontalContainerData({required this.list});

  @override
  Widget buildWidget(BuildContext context) =>
      HorizontalContainerWidget(data: this);

  factory HorizontalContainerData.fromJson(Map<String, dynamic> json) =>
      _$HorizontalContainerDataFromJson(json);

  @override
  Map<String, dynamic> toJson() => _$HorizontalContainerDataToJson(this);
}

# Register in main.dart:
Duck(
  baseUrl: baseUrl,
  components: {
    HorizontalContainerData.componentType: HorizontalContainerData.fromJson,
  },
);

## Limits
- New component types, app logic and native changes need an app release.
- A canvas that names an unregistered component type renders an error-coloured placeholder text.

## Links
- https://pub.dev/packages/duck
- https://github.com/Flexxxlab/duck
- https://duck-demo.flexxxlab.com/
- Contact: helpdesk@flexxxlab.com