Skip to main content

codelessly_api 31.0.0 copy "codelessly_api: ^31.0.0" to clipboard
codelessly_api: ^31.0.0 copied to clipboard

Flutter's widgets and layouts as plain, immutable data with a JSON format. The model behind the Codelessly Editor and the Codelessly SDK. Pure Dart.

example/example.dart

// Builds a small Codelessly layout in code, encodes it to JSON, reads it
// back and inspects it, then wraps it as a publish bundle the Codelessly
// SDK can show (`Codelessly.fromBundle`).
//
//   dart run example/example.dart
import 'dart:convert';

import 'package:codelessly_api/codelessly_api.dart';

void main() {
  // 1. Nodes: a widget type, a layout, and the widget's own props. Props
  //    are Flutter's parameter names with Flutter's defaults.
  final title = const Node(
    id: 'title',
    type: 'text',
    name: 'Title',
    layout: Layout(width: AxisSize.hug(120), height: AxisSize.hug(28)),
    // A bound property: an expression the SDK evaluates while the app runs.
    bind: {'props.text': r'Hello, ${data.name}!'},
  ).withProp(TextProps.text, 'Hello!').withProp(
        TextProps.style,
        const TextStyle(fontSize: 24, fontWeight: 700, color: Color(0xFF111111)),
      );

  final counter = const Node(
    id: 'counter',
    type: 'text',
    layout: Layout(width: AxisSize.hug(80), height: AxisSize.hug(20)),
  ).withProp(TextProps.text, r'Taps: ${count}');

  final button = const Node(
    id: 'button',
    type: 'filledButton',
    layout: Layout(width: AxisSize.hug(120), height: AxisSize.fixed(44)),
    // A reaction: a trigger and the chain of actions it runs.
    actions: [
      Reaction(
        id: 'r1',
        trigger: Trigger(TriggerType.click),
        actions: [
          SetVariableAction(variable: 'count', write: ValueWrite(op: WriteOp.add, value: '1')),
          CallFunctionAction(name: 'onTap', params: {'count': r'${count}'}),
        ],
      ),
    ],
  ).withProp(ButtonProps.label, 'Tap me');

  final column = const Node(
    id: 'column',
    type: 'column',
    children: ['title', 'counter', 'button'],
    layout: Layout(
      width: AxisSize.fill(390),
      height: AxisSize.fill(844),
      padding: EdgeInsets.all(24),
    ),
  )
      // A prop is checked against its declaration: 12 is stored as 12.0.
      .withProp(FlexProps.spacing, 12)
      .withProp(FlexProps.crossAxisAlignment, CrossAxisAlignment.start);

  // A canvas is a screen. Its content is its `body` slot.
  const canvas = Node(
    id: 'home',
    type: 'canvas',
    name: 'Home',
    slots: {'body': 'column'},
    layout: Layout(width: AxisSize.fixed(390), height: AxisSize.fixed(844)),
    decoration: Decoration(fills: [Paint.solid(Color.white)]),
  );

  // 2. A document: canvases (roots) and every node in one flat map.
  final document = LayoutDocument(
    id: 'hello',
    roots: const ['home'],
    nodes: {for (final n in [canvas, column, title, counter, button]) n.id: n},
  );

  // 3. JSON: sparse (defaults are left out) and versioned ("schema": 3).
  final json = document.toJson();
  print(const JsonEncoder.withIndent('  ').convert(json));

  // 4. Decoding is total: it never throws, unknown keys and node types
  //    round-trip, bad values fall back to defaults.
  final decoded = LayoutDocument.fromJson(jsonDecode(jsonEncode(json)));
  assert(decoded.nodes['column'] == column, 'nodes have value equality');
  print('\nparent of title: ${decoded.parentOf('title')}');
  print('column spacing: ${decoded['column']!.prop(FlexProps.spacing)}');
  print('column mainAxisAlignment (Flutter\'s default): ${decoded['column']!.prop(FlexProps.mainAxisAlignment)}');
  print('home subtree: ${decoded.subtree('home').map((n) => n.type).join(' > ')}');

  // 5. Checking a document: every node's type is declared, and every child
  //    exists.
  for (final problem in problemsOf(decoded)) {
    print('problem: $problem');
  }

  // 6. A publish bundle: what the SDK loads. The layout carries the
  //    screen's variables; the model lists the layouts and the entry screen.
  final bundle = bundleOf(document);
  print('\nbundle: ${bundle.model.layouts.length} layout(s), entry ${bundle.model.entryLayoutId}, '
      '${jsonEncode(bundle.toJson()).length} bytes of JSON');
}

/// What's wrong with [document]: node types this version doesn't declare,
/// and children, slots and roots that name no node.
List<String> problemsOf(LayoutDocument document) => [
      for (final root in document.roots)
        if (document[root]?.type != CanvasProps.spec.type) 'root $root is not a canvas',
      for (final node in document.nodes.values) ...[
        if (node.spec == null) '${node.id}: unknown type "${node.type}"',
        for (final child in node.childIds)
          if (document[child] == null) '${node.id}: child $child does not exist',
      ],
    ];

/// [document] published as a project of one layout.
PublishBundle bundleOf(LayoutDocument document, {String projectId = 'example'}) {
  final layout = PublishLayout(
    document: document,
    projectId: projectId,
    variables: {
      for (final canvas in document.roots)
        canvas: [const Variable(id: 'v_count', name: 'count', type: VariableType.integer, value: 0).toJson()],
    },
  );
  return PublishBundle(
    model: PublishModel(
      projectId: projectId,
      entryLayoutId: layout.id,
      layouts: {layout.id: PublishLayoutInfo.of(layout)},
    ),
    layouts: {layout.id: layout},
  );
}
4
likes
150
points
3.27k
downloads

Documentation

Documentation
API reference

Publisher

verified publishercodelessly.com

Weekly Downloads

Flutter's widgets and layouts as plain, immutable data with a JSON format. The model behind the Codelessly Editor and the Codelessly SDK. Pure Dart.

Homepage
Repository (GitHub)
View/report issues

Topics

#server-driven-ui #ui #json #widget #design

License

BSD-3-Clause (license)

Dependencies

collection, meta

More

Packages that depend on codelessly_api