xwidget 0.5.2

A package for building dynamic UIs in Flutter using an expressive, XML based markup language.

0.5.2

• BREAKING: Changed XWidget.navigateToFragment() to make BuildContext optional. Pass context: as a named argument when you need to use a specific navigator; otherwise assign XWidget.navigatorKey to your root app and let XWidget navigate without a context.
• BREAKING: Replaced Resources.instance.clearXmlCache() with Resources.instance.clearFragmentCache(). XWidget.clearXmlCache() remains as a deprecated compatibility wrapper.
• Added XRouter for context-free navigation by route path or name.
• Added route definitions through value resource files with a <routes> root, standalone <route> entries, and grouped <routeGroup> entries.
• Added route groups with callback navigation for PageView, TabBarView, IndexedStack, and similar multi-view widgets.
• Added route names, group-qualified names, group path aliases, default group routes, path parameters, query parameters, and per-route browser history control.
• Added web URL sync for callback route groups, including History API updates, browser back/forward handling, query-string preservation, and startup deep-link support after the first Flutter frame.
• Added XWidget.navigatorKey and exported XRouter from package:xwidget/xwidget.dart.
• Added XML navigation helpers registered during XWidget.initialize(): routeTo(target, [action]), routePop(), routePopAll(), and navigatorKey().
• Refactored resource handling into FragmentResourceBundle and ValueResourceBundle, moving fragment XML caching into the fragment bundle and value parsing into the value bundle.
• Added route loading to value resources so routes.xml is loaded alongside other value resource files for local and cloud resources.
• Deprecated XWidget.registerControllerFactory<T>() in favor of registerControllerFactoryForName() because T.toString() is not stable under dart2js minification.

0.5.1

• Added guard system to Controller — guard() runs before init() to enforce preconditions like authentication and authorization. When guard() returns false, init() is skipped and onGuardFailed() provides the rendered widget.
• guard() supports both synchronous (bool) and asynchronous (Future<bool>) return types via FutureOr<bool>.
• Added onGuardFailed() to Controller — override to provide a widget or schedule side effects (e.g. navigation redirect) when the guard denies access.
• Added navigateToFragment() to XWidget with configurable NavigatorAction — supports push, pushReplacement, pushAndRemoveAll, and pushAndRemoveUntil.
• Deprecated pushFragment() in favor of navigateToFragment().

0.5.0

• BREAKING: Resource configuration moved from XWidget.initialize() into LocalResources and CloudResources. Construct the appropriate instance and pass it to the new resources parameter. The fragmentsPath, valuesPath, projectKey, storageKey, channel, version, downloadTimeout, and assetBundle parameters have been removed from XWidget.initialize().
  • Upgrading guide
  • LocalResources
  • CloudResources
• Hot reload of fragments and values in debug builds. LocalResources registers VM service extensions that the XWidget IntelliJ plugin and VSCode extension invokes to apply edits without restarting.
  • IntelliJ plugin
  • VS Code extension
• Resources is now an extensible abstract base class. Subclass it for custom loading strategies. The built-in subclasses are LocalResources (asset bundle, default) and CloudResources (XWidget Cloud content server).
• Added LocalResources.withAnalytics for local resource delivery with XWidget Cloud analytics.
• Added register parameter to XWidget.initialize(). Pass the generated registerXWidgetComponents function to populate XWidget.config and register inflaters, icons, and controllers.
• Deprecated XWidget.xmlCacheEnabled and XWidget.clearXmlCache(). Parsed XML caching is now managed by Resources — use Resources.instance.clearXmlCache().
• Upgraded xwidget_el dependency to 0.5.0.

0.4.1

• Added EL resource accessor functions. The following functions are now registered globally during XWidget.initialize(), making value resources accessible directly in EL expressions:
  • resBool(name) — returns a bool resource
  • resColor(name) — returns a Color resource
  • resColorString(name) — returns a color resource as a string
  • resDouble(name) — returns a double resource
  • resInt(name) — returns an int resource
  • resString(name) — returns a string resource

  <Text data="${resString('app_title')}"/>
  <Container color="${resColor('primary')}"/>

• Upgraded xwidget_el dependency to 0.4.0.

0.4.0

• BREAKING: Removed nullable attribute from <builder> tag.
• BREAKING: Requires xwidget_builder 0.4.0. Regenerate inflaters after upgrading.
• Simplified <builder> tag by removing typed wrapper functions. Type adaptation is now handled by the generated inflater.
• Added verboseErrors parameter to XWidget.initialize(). Defaults to false.
• Added fragment name to XWidget.dump() error diagnostic output.
• Fixed platformLogHandler on IO and web to include record.error and record.stackTrace in log output.

0.3.0 (Mar 31, 2026)

• BREAKING: Resources.instance.loadResources() has been replaced with XWidget.initialize().
• BREAKING: Replaced package:logger/logger.dart dependency with package:logging/logging.dart.
• BREAKING: Updated minimum Dart SDK to 3.8.
• Cloud resource loading — download fragment and value bundles from XWidget Cloud at runtime with ETag-based caching and offline fallback.
• Automatic analytics — fragment renders, bundle downloads, errors, and navigation transitions tracked with zero instrumentation.
• AnalyticsNavigatorObserver auto-injected into MaterialApp, CupertinoApp, and Navigator when inflated from XML.
• Session-based navigation tracking with configurable timeout.
• XWidget.initialize() — unified initialization for resources, cloud configuration, and analytics.
• Fragment and value resource folder resolution.

0.2.0 (Jan 22, 2026)

BREAKING CHANGES: Please run dart run xwidget_builder:generate after upgrading.

• Support AssetManifest.bin with fallback to .json for older Flutter versions
• Increased Flutter version constraint from >=1.17.0 to >=3.10.0
• Increased Dart SDK constraint from >=2.19.6 to >=3.0.0
• Updated xwidget_el dependency from 0.2.0 to 0.2.2
• New documentation preview at docs.xwidget.dev

0.1.1 (Nov 20, 2025)

• Minor documentation updates

0.1.0 (Nov 20, 2025)

BREAKING CHANGES: After upgrading, please run the following commands:

 $ flutter pub add dev:xwidget_builder
 $ dart run xwidget_builder:generate

• Moved code generators and initializers to their own dev package. XWidget Builder

0.0.52 (Aug 23, 2025)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Fixed an issue with inflater generator where it was not generating deprecated, required constructor parameters.
• Upgraded xwidget_el dependency to ^0.2.0
• Upgraded analyzer dependency to ^7.7.1

0.0.51 (Feb 22, 2025)

• Removed deprecated usages
• Fixed package dependencies

0.0.50 (Feb 22, 2025)

• Removed deprecated usages
• Documentation updates
• Package updates

0.0.49 (Feb 9, 2025)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Moved EL functionality to it's own project. XWidget EL
• Improved documentation

0.0.48 (Oct 21, 2024)

• Fixed a bug where duplicate inflater declarations would generate invalid code.
• Fixed a bug where duplicate icon declarations would generate duplicate code.

0.0.47 (Oct 8, 2024)

• Fixed project initialization script bug.
• Created an Android Studio plugin for XWidget. Go to 'Settings' -> 'Plugins' -> 'Marketplace' and search for 'XWidget'. It's free, so check it out! Flutter XWidget plugin

0.0.46 (Sep 28, 2024)

• Fixed parseInt bug.

0.0.45 (Sep 28, 2024)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Added EL functions to references i.e. ${person.name.toUpperCase()}.
• Added EL functions to parenthesis expressions i.e. ${('abc' + 'xyz').toUpperCase()}.
• Minor performance improvements to EL parsing. Using a singleton instead of creating a new parser for each Dependencies instance.
• Documentation

0.0.44 (Sep 21, 2024)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Added ability for models to transform data during import using PropertyTransformer and PropertyTranslation. This lays the groundwork for auto generating models. Please see the Loading Data guide for more information.
• Export math and misc functions.
• Allow EL == expressions to compare enum to String.
• Fixed <param> bug where null values were defaulted to an empty string ("").
• Documentation updates

0.0.43 (Jul 16, 2024)

Please run dart run xwidget:generate after upgrading.

• Added WidgetStatePropertyOf<T> class to replace MaterialStatePropertyOf<T>, which is now deprecated.
• Added directional alignment options to AlignmentGeometry parser.
• Added TextInputType parser.
• Added first and last EL functions.
• Updated EL arithmetic operators (+,-,*,/,%,~/) to work with any class that overrides them.

0.0.42 (Jul 2, 2024)

Please run dart run xwidget:generate after upgrading.

• Added an initialization command to setup a new XWidget project. Please see the Quick Start guide.
• Updated Example project to use Material3.

0.0.41 (May 26, 2024)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

This is a big release with many changes. Please read the release notes carefully.

• Reorganized utility functions to eliminate duplication, clarify purpose, and better support reuse. They are divided into the following groups: converters, math, parsers, validators, and misc. All parsing function now only parse String values; conversion function convert dynamic values and may call a parsing function if the value is a String.
• Added the following EL functions:
  • formatDuration
  • isBlank
  • isNotBlank
  • toColor
  • toDays
  • toHours
  • toMillis
  • toMinutes
  • toSeconds
  • tryToBool
  • tryToColor
  • tryToDateTime
  • tryToDays
  • tryToDouble
  • tryToDuration
  • tryToHours
  • tryToInt
  • tryToMillis
  • tryToMinutes
  • tryToSeconds
• Added the following parsing functions:
  • parseInt
  • parseDouble
  • tryParseBool
  • tryParseDateTime
  • tryParseDouble
  • tryParseDuration
  • tryParseEnum
  • tryParseInt
• You can now listen changes to nested model properties with <ValueListener>, Model.listenForChanges or Dependencies.listenForChanges when using Model.setValue or Dependencies.setValue. For example:

  final user = Model({
    "first": "Mike",
    "last": "Smith",
    "email": "[e-mail]"
  });
  dependecies.setValue("profile", user);
  

  <ValueListener varName="profile">
    <Row>
        <Text data="${profile.first}"/>
        <Text data="${profile.last}"/>
        <Text data="${profile.email}"/>
    </Row>
  </ValueListener>
  

  Any changes to first, last or email using setValue will trigger the <ValueListener> to rebuild.
• Model instances now default to mutable.
• Added named constructor Model.immutable.
• Added <Item> tag to <List> for situations where you want to build a list from values stored in Dependencies or EL functions.

  <List for="...">
    <Item value="${color}"/>
    <Item value="${toColor('0xFF272727')}"/>
    <Item value="${backgroundColor}"/>
  </List>
  

• You can now pass int values to inflaters that previously required doubles and they will be automatically converted to doubles i.e. any widget that takes width and height.
• Updated EL Functions and Tips & Tricks documentation.
• Removed the following EL functions: durationInDays - use toDays instead durationInHours - use toHours instead durationInMinutes - use toMinutes instead durationInSeconds - use toSeconds instead durationInMills - use toMillis instead
• Removed the following parser functions: parseWidth - use parseDouble instead parseHeight - use parseDouble instead

0.0.40 (May 9, 2024)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Added abs, ceil, floor, and round EL functions.
• Added grouping functionality to forEach tag. Useful for creating simple multi-column layouts.

  <!-- forEach grouping example -->
  <forEach var="group" items="${items}" groupSize="2">
      <Row>
          <forEach var="item" items="${group}">
              <Text data="${item.title}"/>
          </forEach>
      </Row>
  </forEach>
  

• Added returnType attribute to builder tag. Valid values are Widget, Widget?, List:Widget, and List:PopupMenuEntry. Defaults to Widget if empty.
• Added return type List<PopupMenuEntry> (display name List:PopupMenuEntry) to builder tag.
• Added support for defining inflaters with generic types i.e. AlwaysStoppedAnimation<T>, MaterialStatePropertyOf<T>, etc.

  // inflater_spec.dart example
  const inflaters = [
    AlwaysStoppedAnimation<Color>
    MaterialStatePropertyOf<Color>,
    MaterialStatePropertyOf<Size>,
    MaterialStatePropertyOf<TextStyle>,
  ];
  

    <!-- simple fragment examples -->
    <AlwaysStoppedAnimationColor for="..." value="@color/primary"/>
    <MaterialStatePropertyOfColor for="..." primary="#272727" disabled="#676767"/>
    <MaterialStatePropertyOfSize for="..." primary="8x8" focused="12x12" error="x24"/>
    <MaterialStatePropertyOfTextStyle for="...">
        <TextStyle for="primary" fontWeight="400"/>
        <TextStyle for="selected" fontWeight="600"/>
    </MaterialStatePropertyOfTextStyle>
  

• Removed nullable and multiChild attributes from builder tag. Use returnType instead.
• Removed erroneous start, end attributes from forEach schema definition.
• Removed previously added MaterialStateXXX custom inflaters. Use MaterialStatePropertyOf<T> instead.
• Removed support for original inflater specification format. Use the new specification format.

  // old format - no longer supported
  const Column? _column = null;
  const Text? _text = null;
  const TextStyle? _textStyle = null;
  
  // new format
  const inflaters = [
    Column,
    Text,
    TextStyle,
  ];
  

0.0.39 (May 6, 2024)

Please run dart run xwidget:generate --only inlfaters after upgrading.

• Added default inflater constructor value for BoxShadow:color.
• parseBool now parses ints. Zero is false, non-zero values are true.
• Added custom MaterialState implementations and parsers to better support MaterialState properties.

  // inflater_spec.dart example
  const inflaters = [
    MaterialStateBorderSide,
    MaterialStateColor,
    MaterialStateDouble,
    MaterialStateEdgeInsets
    MaterialStateMouseCursor,
    MaterialStateOutlineBorder,
    MaterialStateSize,
    MaterialStateTextStyle,
  ];
  

    <!-- simple fragment examples -->
    <MaterialStateColor for="..." primary="#272727" disabled="#676767"/>
    <MaterialStateSize for="..." primary="8x8" focused="12x12" error="x24"/>
    <MaterialStateTextStyle for="...">
        <TextStyle for="primary" fontWeight="400"/>
        <TextStyle for="selected" fontWeight="600"/>
    </MaterialStateTextStyle>
  

  Configured default parsers:

    # default_config.yaml
    "MaterialStateProperty<Color>": "parseMaterialStateColor(value)"
    "MaterialStateProperty<double>": "parseMaterialStateDouble(value)"
    "MaterialStateProperty<EdgeInsetsGeometry>": "parseMaterialStatePadding(value)"
    "MaterialStateProperty<Size>": "parseMaterialStateSize(value)"
  

0.0.38 (Apr 29, 2024)

• Fixed EL RangeError when referencing data using an out of range index i.e. ${items[2].name} where items.length == 2 now returns a null. This is consistent with how null property references are handled i.e ${person.name} where person == null. Maybe in the future we'll add a strict mode that throws Exceptions.

0.0.37 (Mar 28, 2024)

• Added toDouble and toInt EL functions.
• Minor documentation updates

0.0.36 (Feb 11, 2024)

Please run dart run xwidget:generate after upgrading.

• Added EventNotifier component.

  <EventNotifier event="UserEvents.login">
    ...
  </EventNotifier>
  

• Added mapped Controller options.

  <Controller name="...">
      <Map for="options">
          <Entry key="name" value="${value}"/>
      </Map>
  </Controller>
  

• Added arguments to XWidget.inflateXmlElementChildren that optionally include or exclude the processing of attributes defined as children i.e. for='<parent_attribute>'
• Removed ValueListener's onChange callback.

0.0.35 (Feb 2, 2024)

• Fixed readability issues with README.md file.
• Added documentation builder tool (internal).

0.0.34 (Feb 2, 2024)

BREAKING CHANGES: Please up all usages of Data to Model.

• Renamed Data to Model to more accurately represent its purpose.
• Fixed a bug where Model operators [] and []= were incorrectly calling getValue and setValue respectively. They now directly access the underlying collection.
• Added static instance management methods to Model to help with state management: singleInstance, keyedInstance, clearInstances, hasInstance
• Reorganized documentation.

0.0.33 (Jan 28, 2024)

• Fixed dot/bracket notation parsing of List paths.
• Fixed relative import statements.
• Export MediaQueryWidget.

0.0.32 (Jan 23, 2024)

Please run dart run xwidget:generate after upgrading.

• Fixed issues with code generator not recognizing some List types.
• Improved EL dot notation path resolution error messages.
• Changed <builder/>'s for attribute from required to optional. This is needed for creating lists of builders as required by BottomNavLayout.pages.
• Added innerLists attribute to <List/> for configuration of how inner lists are handled. The options are add and spread. add (default) will add the inner list object. spread will add the inner list's items to the containing list.
• Added visible attribute to <fragment/>.
• Added new EL functions: randomDouble, randomInt, replaceAll, replaceFirst
• Improved code generator's handling of private constant defaults.
• Added <Media/> component. Writes MediaQuery values to Dependencies.
• Added createMaterialColor, parseMaterialColor utility functions.

0.0.31 (Jan 1, 2024)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Renamed ListOf element to List for consistency
• Added Map element. Example usage:

  <Map for="attribute">
    <Entry key="name" value="name"/>
    <Entry value="description">description</Entry>
  </Map>
  

• Allow param, forEach, and if elements as optional children of fragment element. Example usage:

  <fragment name="header">
      <param name="bottom" value="tab_bar"/>
  </fragment>
  

• Auto scope dependencies for elements that support the dependenciesScope attribute.
• Updated minimum petitparser version to 6.0.0.
• Removed deprecated imports.

0.0.30 (Dec 12, 2023)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Controller now extends StatefulWidget. This allows Controllers to use mixins designed for stateful widgets such as TickerProviderStateMixin.
• Renamed Controller.initialize to Controller.init.
• Removed build parameter from Controller constructor.
• Removed multi-controller support from Controllers.
• Some code cleanup

0.0.29 (Nov 8, 2023)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Renamed execution parameter to build in ControllerWidget constructor.
• Fixed ControllerWidget's async build.
• Enhanced parseDuration function to accept m, min, mins, h, hr, hrs, d, day, days duration suffixes i.e. 5m, 1hr, 3days.
• Added isTrue, isFalse, and logDebug EL functions.
• Improved invalid EL function error message.
• Minor XML parsing performance improvements.

0.0.28 (Oct 31, 2023)

• Fixed reference parser 'null' error.
• Fixed parseEnum method signature.

0.0.27 (Oct 2, 2023)

• Added varDisposal option to ValueListener. Possible values are none, byOwner, and byLastListener.
• Added onChange callback to ValueListener.
• Updated DataValueNotifier to be owner and listener aware.
• Added removeValue method to Dependencies and MapBrackets extension. This method is dot/bracket notation aware.
• Deleted remove method from Dependencies. Use removeValue instead.

0.0.26 (Sep 17, 2023)

• Updated dependencies.

0.0.25 (Sep 17, 2023)

• Updated documentation.

0.0.24 (Sep 12, 2023)

• Added EL functions isTrueOrNull and isFalseOrNull.
• Updated documentation.

0.0.23 (Sep 8, 2023)

• Removed disposeOfDependencies parameter from DynamicBuilder constructor.
• Inflater.parseAttribute now returns the unparsed value if the value is not parsed.

0.0.22 (Sep 5, 2023)

• Updated analyzer and linter rules
• Minor code formatting
• Added publishing tool

0.0.21 (Aug 22, 2023)

• Improved inflater builder's generation of default values from variables.
• Added new built-in EL function toBool.
• Updated documentation.

0.0.20 (Aug 16, 2023)

BREAKING CHANGES: Please run dart run xwidget:generate after upgrading.

• Changed Inflater.inflate signature to pass a list of unprocessed child strings instead of a single preprocessed string. The inflater's implementation now determines how to process the strings i.e. Text inflater uses XWidgetUtils.joinStrings(text).
• Removed includeAttributes argument from XWidget.inflateXmlElementChildren signature. Use excludeAttributes argument instead.
• Removed XWidget.inflateFromXml convenience method. Use XWidget.inflateFromXmlElement instead.
• Added an excution option to the Controller inflater that specifies its inflation method, either asynchronous or synchronous. Valid values are async and sync. The default is sync.
• Minor performance improvements when setting or retrieving Dependencies values and parsing certain attribute types.
• Added XWidgetUtils.joinStrings utility function.
• Added fragment XML caching to improve inflater performance. Use XWidget.xmlCacheEnabled to enable or disable the cache. Enabled by default.

0.0.19 (Aug 9, 2023)

• Attribute parsing performance improvements.
• Documentation updates and additions.
• Minor code cleanup.

0.0.18 (Aug 3, 2023)

• Added support for a simplified inflater and icon specification format. See the 'Inflaters Configuration' and 'Icons Configuration' README sections.
• Updated documentation.

0.0.17 (Jul 7, 2023)

• Substantially increased attribute value parsing performance.
• Added embedded expression parsing to attribute values i.e. <Text data="Dear ${name},"/>
• Removed @fragment attribute directive. Use the fragment tag accompanied with the for attribute instead.
• Replaced copyDependencies option with dependenciesScope. Can be new, copy, or inherit.
• Added dependenciesScope option to frgament tag.
• Updated documentation.

0.0.16 (Jul 4, 2023)

• Improved fragment XML validation.
• Auto generate inflater attribute restrictions for enum types.
• Removed ability to override built-in functions.
• Controller no longer extends WidgetsBindingObserver. Subclasses can add it as a mixin, if needed.
• Added callback schema element.
• Updated documentation

0.0.15 (Jul 2, 2023)

• Overhauled EL functions to simplify implementation.
• Renamed handler tag to callback.
• Fixed action attribute evaluation in callback tag.
• Added returnVar attribute to callback tag.
• Deleted deprecated attribute tag. Use ListOf inflater instead.
• Documentation updates and additions.

0.0.14 (Jun 23, 2023)

• Inflater parsers now return the unparsed value if there's no attribute name match.
• Inflater builder now skips deprecated elements by default.
• Resources can now use an alternate AssetBundle, when passed to loadResources method. Otherwise, it uses rootBundle.
• Documentation updates.
• Added fragment tag unit tests.

0.0.13 (Jun 18, 2023)

• Removed unnecessary import that was causing a web compatibility issue.
• Updated var tag to allow dot/bracket notation in name attribute.
• Continued work on documentation.

0.0.12 (Jun 15, 2023)

• Improved CommonLog callback feature. Callback now returns a bool to continue or skip logging.
• Updated xwidget dependency in example 'pubspec.yaml' to point to pub.dev.
• Fixed invalid identifier parsing error.
• Fixed deprecated usages.

0.0.11 (Jun 12, 2023)

• Improved log messages from code generator.
• Replaced deprecated commands in documentation.

0.0.10 (Jun 12, 2023)

• Continued work on documentation.
• Added license.

0.0.9 (Jun 10, 2023)

• ControllerWidget now supports multiple controllers.
• Initialize CommonLog with callback functions instead of class instance.
• EL parser now capable of referencing global dependencies.
• Improved Dependencies toString() format.
• Added more unit tests.

0.0.8 (Jun 5, 2023)

• Fixed inflater builder getOnlyChild function call.
• Fixed example inflaters.

0.0.7 (Jun 4, 2023)

• Renamed logging class from Log to CommonLog.
• Created XWidgetUtils to hold XWidget helper functions.
• Created CommonUtils to hold common helper functions.
• Cleaned up messy exports.
• Documentation updates.

0.0.6 (Jun 4, 2023)

• Added example folder.
• Fixed async resources loading issue.

0.0.5 (Jun 4, 2023)

• Fixed inflater builder's default imports.
• Fixed default inflater config location.
• Fixed controller builder's type scanner.
• Export EL parser.
• Export custom widgets.
• Export logger.

0.0.4 (Jun 4, 2023)

• Restructured project files.
• Statically create required inflaters.
• Added InvalidType checks to inflater builder.
• Added inflater test.

0.0.3 (Jun 3, 2023)

• Fixed library resolution issue.

0.0.2 (Jun 2, 2023)

• Continued work on documentation.
• Fixed an issue with source analysis.
• Automatically scan 'lib/xwidget/controllers' for controllers.

0.0.1 (May 31, 2023)

• Initial release.
• Fully functional, but lacking proper documentation and unit tests.