FxDesktop #

FxDesktop is a desktop-first Flutter component and layout library for building Xojo-style UI design tools, previews, and generators.

It provides:

• CSS-like layout widgets: FxFlexLayout and FxGridLayout
• Xojo-comparable desktop components such as FxButton, FxTextField, and FxGroupBox
• Xojo-first custom controls such as FxListBox and FxGrid
• A Flutter-native FxRibbonToolbar plus embeddable FxRibbonDesigner
• Serializable layout contracts for AI agents, JinjaX, and Xojo generation
• App-level semantic undo primitives for desktop workflows
• Flutter-native localization with ARB source files, four bundled locales, and .po/.pot translator bridge tooling, including ribbon/designer strings

FxDesktop is not a mobile design-system wrapper. Flutter already has strong mobile and tablet layout primitives. Responsive features are added here only when they help desktop windows, Flutter Web/WASM, split panes, inspectors, or multi-size desktop workflows.

Install #

dependencies:
  fx_desktop: ^0.6.0

Quick Start #

import 'package:flutter/material.dart';
import 'package:fx_desktop/fx_desktop.dart';

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

  @override
  Widget build(BuildContext context) {
    return FxFlexLayout(
      direction: FxFlexDirection.column,
      gap: 12,
      padding: const EdgeInsets.all(16),
      children: [
        const FxFlexItem(
          child: FxTextField(
            label: 'Customer',
            hintText: 'Company or person name',
            requiredInput: true,
            constraints: FxTextInputConstraints(
              maxLength: 80,
              showCharacterCount: true,
            ),
          ),
        ),
        FxFlexItem(
          grow: 1,
          child: FxListBox(
            columns: const [
              FxListBoxColumn(id: 'number', caption: 'Order', width: 100),
              FxListBoxColumn(id: 'status', caption: 'Status', width: 120),
            ],
            rows: const [
              FxListBoxRow(
                id: 'order-1',
                cells: {'number': '1001', 'status': 'Open'},
              ),
            ],
          ),
        ),
      ],
    );
  }
}

Xojo Mapping #

FxGridLayout is a CSS Grid-like layout manager. FxGrid is a data/cell grid control comparable to Xojo DesktopGrid.

Milestone 3 introduces deep FxListBox and FxGrid controls (refined in v0.3.3 through v0.3.6). This includes selection models, keyboard navigation/traversal, sorting, column sizing/visibility policies, capped auto-fit resizing, editable cell types (text, number, boolean, options) with validation, database-grade multi-column lookups, input masking, ellipsis cell action buttons, background-saturation row/column highlights, clipboard operations (TSV copy/paste), layout undo/redo integration, performance virtualization (up to 10k+ rows and 100+ columns), and rich accessibility support via Semantics. Milestone 3 is delivered through v0.3.6; the original plan remains in the milestone document as the acceptance map, and the delivered release history is now tracked there. See Milestone 3: ListBox And Grid Depth and Advanced Grid Features (v0.3.6).

Ribbon Toolbar And Designer #

FxRibbonToolbar is a widget-native ribbon for Flutter desktop and web. It uses a serializable FxRibbonDefinition model with tabs, groups, large, medium, and small commands, dropdowns, split buttons, embedded galleries, column breaks, toggles, checkboxes, contextual tabs, collapse behavior, SVG/PNG/Material icon sources, keytips, mouse interaction, keyboard shortcuts, touch hit targets, and localized command text. The default Explorer sample is organized as an application-button ribbon with divider-separated groups and equal-width command columns for large desktop and web windows.

FxRibbonDesigner is an embeddable visual designer for the same model. It shows a live toolbar preview, structure tree, JSON preview, inspector, localized caption editor, validation status, and export callback.

MaterialApp(
  localizationsDelegates: FxDesktopLocalizations.localizationsDelegates,
  supportedLocales: FxDesktopLocalizations.supportedLocales,
  home: Scaffold(
    body: FxRibbonToolbar(definition: FxRibbonSamples.explorer()),
  ),
);

See Ribbon Schema and Ribbon Designer.

ListBox And Grid #

FxListBox and FxGrid are the deepest controls in the package. They cover dense desktop tables with virtualized scrolling, keyboard traversal, selection models, inline editing, validation, TSV clipboard operations, undo/redo integration, custom renderers, hosted lookup editors, input masks, cell action buttons, and accessibility semantics.

Localization #

FxDesktop uses Flutter's standard localization flow. Apps can add FxDesktopLocalizations.localizationsDelegates and FxDesktopLocalizations.supportedLocales to MaterialApp, then switch locale the same way they would for other Flutter widgets.

MaterialApp(
  localizationsDelegates: FxDesktopLocalizations.localizationsDelegates,
  supportedLocales: FxDesktopLocalizations.supportedLocales,
  locale: const Locale('th'),
  home: const FxLocalizationGallery(),
);

Bundled package strings cover English, Thai, Japanese, and Nepali. ARB files are the runtime source of truth; .po and .pot files are import/export formats for translators.

Text Input Constraints #

FxTextField and FxTextArea include caption-style labels, helper text, error text, required indicators, and serializable constraint metadata. Desktop apps can use these APIs directly while AI/Xojo generators can export the same metadata into templates.

const FxTextField(
  label: 'Phone',
  hintText: '#-####-####',
  requiredInput: true,
  constraints: FxTextInputConstraints(
    kind: FxTextInputConstraintKind.numeric,
    maxLength: 11,
  ),
  format: FxTextInputFormat.pattern('#-####-####'),
);

const FxTextField(
  label: 'Budget',
  format: FxTextInputFormat.number(decimalDigits: 2),
);

Pattern masks clean visible single-line input as the user types. Number formats are applied on submit or focus loss so app-level undo records one committed value change.

For form grids that mix inputs with and without helper, error, or counter text, set reserveSupportingTextSpace: true on decorated inputs that should share the same visual rhythm.

Agent And Generator Use #

FxDesktop specs can be serialized and passed into Xojo-side generators:

const spec = FxLayoutSpec.flex(
  id: 'root',
  direction: FxFlexDirection.row,
  gap: 8,
  flexChildren: [
    FxFlexItemSpec(id: 'sidebar', basis: 240),
    FxFlexItemSpec(id: 'content', grow: 1),
  ],
);

final context = FxFlexLayoutManager(spec: spec).toTemplateMap();

The resulting map is intended for AI agents, JinjaX templates, and Xojo export adapters.

Undo And Redo #

FxDesktop provides FxUndoController, FxUndoAction, and FxUndoScope for desktop-style semantic undo. The undo layer records committed app-state changes, not every keystroke or transient widget frame.

final undo = FxUndoController();
var status = 'Draft';

undo.commitValue<String>(
  'Change status',
  oldValue: status,
  newValue: 'Approved',
  apply: (value) => status = value,
);

undo.undo();
undo.redo();

Text controls can still use Flutter's native focused text-editing undo for typing. FxDesktop commit callbacks such as FxTextField.onCommit and FxSlider.onChangeEnd are for app-visible history entries like Change customer or Change priority.

See Undo Guide.

Development #

Run the full local quality harness before committing:

dart run tool/agent_harness.dart

The fx-desktop-example/ app is the vertical component harness for the component suite, including the ribbon toolbar. The ribbon-toolbar-designer/ app is the standalone visual designer. The example-listbox-demo/ app is the interactive ListBox/Grid spec gallery used to review the 0.3.x table surface, including lookup editors, input masks, cell action buttons, row reordering, undo/redo, and large-table behavior.

The harness runs formatting checks, static analysis, tests, Dartdoc, pub.flutter-io.cn dry-run checks, release version-sync checks, all three demo packages, web smoke builds for the ribbon-facing demos, and public API policy checks.

Version tags and optional GitHub Releases are created only after a milestone is implemented, documented, validated, and accepted. See Release Versioning.

For phase work after v0.2.1, each implementation phase must keep the process docs current as part of the release: review the active Flutter desktop skill, update AGENT.md, update CHANGELOG.md, update README when user-facing usage or workflow changes, then merge, tag, and create the GitHub Release from the accepted phase branch.