flutter_adaptive_cards_fs 0.8.0 copy "flutter_adaptive_cards_fs: ^0.8.0" to clipboard
flutter_adaptive_cards_fs: ^0.8.0 copied to clipboard

Published 9 days ago • Latest: 0.10.0
[unknown platforms]
→

Metadata

Adaptive Cards are platform-agnostic snippets of UI, authored in JSON, that apps and services can openly exchange.

More...

Adaptive Cards in Flutter #

This is an Adaptive Card implementation for Flutter that is built from a fork of a fork of a library that is no longer available on GitHub. The intermediate forking chain is pretty much all abandoned. This is available on pub.dev and is hosted on GitHub at freemansoft Flutter-AdaptiveCards

Microsoft Adaptive Cards #

This project is in no way associated with Microsoft. It is an open source project to create an adaptive card implementation for Flutter.

Adaptive Cards

References #

Flutter-AdaptiveCards mono repo #

Libraries avaiable on pub.dev from this repository include:

Package / Library Location
The core of Adaptive Cards is supported via flutter_adaptive_cards_fs
Supplemental Adaptive Card based charts are supported via flutter_adaptive_charts_fs
Templating is supported via the flutter_adaptive_template_fs

Utility programs available in this repository that are not published to pub.dev include:

Design time utility Location
The Adaptive Card Explorer Editor (adaptive_explorer)
A Widgetbook for demonstrating cards and their features: (widgetbook)

Consumption Patterns #

Adaptive Cards are intended to be served up via some presentation service or API letting the service control the UX flow. It is possible to just use them with local JSON templates but that's not the intended use.

Teams often create a presentation or flow management service layer in front of the core business services that acts a bridge to the UI. It coughs up Adaptive Cards as the response to user actions. The cannonical flow would be

sequenceDiagram
    participant user as User
    participant browser as Client or Browser or Device
    participant flutter-app as Flutter App
    participant flow-services as Flow Services
    participant remote-site as Backend API

    user        ->> browser: User Action
    browser     ->> flutter-app: Submit Request
    activate flutter-app
    flutter-app ->> remote-site: API Call
    remote-site -->> flutter-app: Results
    flutter-app ->> flow-services: Activate Flow
    activate flow-services
    flow-services ->>  remote-site: Invoke API
    activate remote-site
    remote-site -->> flow-services: API Results
    deactivate remote-site
    flow-services ->>  flow-services: Generate Flow
    flow-services -->> flutter-app: Adaptive Card
    deactivate flow-services
    flutter-app ->>  flutter-app: Create Widget Tree from Adaptive Cards
    flutter-app ->> remote-site: API Call
    remote-site -->> flutter-app: Results
    flutter-app -->> browser: Device markup / Controls
    deactivate flutter-app

Adaptive Card Color handling has changed #

It used to be there were 3 background styles and 5 foreground styles plus light/dark. Then Microsoft defined 5 background styles that align with the 5 foregound styles. This library makes the assumption that the 'default' foreground color for a style should align with the background color for that style. This means we can map the Flutter container styles and onContainer styles to the Adaptive Card styles. So if you pick a container style then you will automatically get the right foreground color for that style if you don't specify anything.

Adaptive Card Container ColorStyles now map to themed Flutter container styles.

flowchart
  subgraph ContainerStyles[Background Color from ContainerStyles]
  notset[ContainerStyle not specified] --> inherited[inherited from parent]
  default[ContainerStyle default] --> primaryContainer
  emphasis[ContainerStyle emphasis] --> secondaryContainer
  good[ContainerStyle good] --> tertiaryContainer
  attention[ContainerStyle attention] --> errorContainer
  warning[ContainerStyle waring] --> errorContainer
  end

The CardStyle foreground color comes from the containers when the foreground style is 'default'. All other foreground styles are retrieved from the host_config.

flowchart
  subgraph ForegroundStyles[Foreground Color from Styles]
  notset[widget style not specified] --> inherit[Inherit from parent]
  default[widget style default] --> associatedContainer["onContainer that matches the current container bound by style above" ]
  emphasis[widget style emphasis] --> container["onContainer that matches the container bound by style above"]
  good[widget style good] --> container
  attention[widget style attention] --> container
  warning[widget style warning] --> container
  unrecognized --> <tbd>
  end

Loading Data into fields outside of the AdaptiveCard JSON with initData / initInput #

You can create an AdaptiveCard stack with the AdaptiveCard json and also pass in a data map that will seed input overlays on the document notifier.

  • initData is a widget parameter on RawAdaptiveCard / AdaptiveCardsCanvas.
  • On first frame, values are written to the document notifier (scalar entries become {value: …} patches; map entries are full per-id patches via applyUpdatesFromMap).
  • initInput(map) on RawAdaptiveCardState seeds flat {id: value} maps or patch maps when values are objects.
  • initInput does not call setState on the card — input widgets rebuild when their resolvedElementProvider listener fires. See doc/reactive-riverpod.md.
  • loadInput(id, map) replaces Input.ChoiceSet choices for [id] via setChoices (title → value map converted to Input.Choice list).

Runtime overlays (host API on RawAdaptiveCardState) #

Without mutating card JSON, hosts can patch document state via:

API Use
applyUpdates(elements:, actions:) Bulk sparse patches (AdaptiveElementUpdate / AdaptiveActionUpdate)
applyUpdatesFromMap(byId) Server-style { id: { value, choices, … } } payloads
setText(id, text) / clearText(id) Replace TextBlock display text
setInputError(id, message:, isInvalid:) / clearInputError(id) Host validation on inputs
setActionEnabled(id, enabled:) / setActionsEnabled(map) Enable/disable Action.* (AC 1.5)

See doc/reactive-riverpod.md.

Event Handlers #

You can insert a DefaultAdaptiveCardHandlers in the Widget tree prior to loading the AdaptiveCards. Those handlers will be used for all actions.

Your program can pass it's own handlers to the AdaptiveCard constructors. See the NetworkPage class in the example app.

Example Execution #

There are two example apps and a bunch of tests that demonstrate card usage.

  1. We abused Widgetbook to show the cards in a way that is more useful than single adaptive card components. Everything in Widgetbook is a JSON markup sitting in the file system. Many of these ar emodified versions of what is avaialble on the INterenet from Microsoft and others
  2. The other example app is the Adaptive Card Explorer Editor which is a full featured editor for creating , previewing and testing Adaptive Cards.
  3. The tests are in the test folder and are run using the standard flutter testing mechanism.

Tests #

There are functional Unit tests and golden unit tests located in the test folder. They all use use the standard flutter testing mechanism. Golden tests may load a font so as not to use the ahem block font.

  • The tests load the Roboto fonts so that the golden tests don't just show the block font. Spacing can be off between platforms so the golden tests are organized into platform-specific subdirectories (e.g., gold_files/linux/, gold_files/macos/).
  • Golden images are platform-specific. The Linux (CI) images are the project's source of truth. Golden tests dynamically select the appropriate subdirectory based on the host OS. See: https://github.com/flutter/flutter/issues/2943.

Compatibility #

Compatability changes should be captured in the Changelog section below

  • Video player doesn't work on windows because the 3rd party library doesn't support windows fat clients.

Flutter Version #

Flutter versioning is managed with fvm. The current Flutter version is as follows..

PS C:\dev\flutter> flutter --version
Flutter 3.44.0 • channel stable • https://github.com/flutter/flutter.git
Framework • revision 559ffa3f75 (10 days ago) • 2026-05-15 14:13:13 -0700
Engine • hash fcf463a2242790d1fdcd9d044f533080f5022e18 (revision 4c525dac5e) (10 days ago) • 2026-05-15 19:00:04.000Z
Tools • Dart 3.12.0 • DevTools 2.57.0

You can move to this version of flutter by installing fvm and then:

fvm install 3.44.0
#fvm use 3.44.0

Released Flutter / Dart bundling versions are located here: https://docs.flutter.dev/release/archive?tab=windows

Development Tools #

VS Code #

This repo has been reformatted and updated using VS Code extensions. The VS Code Flutter/Dart extension cleaned up some imports and mad other changes that have been comitted to the repository.

Notes:

  1. VSCode told me to enable Developer Mode in Windows settings in order to run the examples. Is that for the Windows app or the Web app?

Antigravity #

A fair amoiunt of development has been done using Antigravity

Plugins used during coding

  • Flutter
  • Dart
  • dart-import
  • markdownlint
  • Markdown Preview Mermaid
  • Intellicode
  • AdaptiveCards
  • GitHub Actions
  • GitLens
  • Antigravity

Widget Hierarchy with Flutter-AdaptiveCards #

The Widgets marked with (*)are Flutter-AdaptiveCars specific including those scoped via Riverpod ProviderScope.

Demo Adaptive Card*
├── Selection Area (copy/paste enable)
│   └── Padding
│       └── Column
│           └── AdaptiveCardsCanvas(*)
│               └── RawAdaptiveCard(*)
│                   └── ProviderScope(*)
│                       ├── cardTypeRegistryProvider override
│                       ├── actionTypeRegistryProvider override
│                       ├── styleReferenceResolverProvider override (HostConfig only)
│                       └── adaptiveCardDocumentProvider
│                           └── Card
│                               └── Column
│                                   ├── TextButton
│                                   ├── Divider
│                                   └── AdaptiveCardElement(*)
│                                       └── ProviderScope(*)
│                                           └── expandedShowCardIdProvider
│                                               └── Form
│                                                   └── Container
│                                                       └── Column
|                                                           ├── AdaptiveTextBlock(*)
│                                                           ├.   └── Visble
│                                                           │        └── SeparatorElement
│                                                           │            └── Column
│                                                           │                └── ...
│                                                           └── AdaptiveColumnSet(*)
│                                                               └── SeparatorElement
│                                                                   └── Column
│                                                                       └── SizedBox
│                                                                           └── AdaptiveTapable(*)

Taken from the example (deleted) App

Open TODO and open issues and bugs defects items #

TODO for the example programs moved to example README

  • initData does not appear to be working on date fields. The initData button in the sample program demonstrates this
  • Currently uses Provider for inherited state. Determine if this 3rd party dependency is a good idea given `Provider`` is essentially EOL or frozen.
  • There is currently no way to unset a container style inside a child container. This means you can't get back to a card background color in a nested container if you set it somewhere in the widget tree betwen you and the card.
  • Make a single purpose dart file for consumer imports with no code in it in place of flutter_adaptive_cards_fs.dart or move the code in that file.
  • Inject locale behavior into money, time and dates including parsing
  • Card Elements missing implementations and features
  • Inputs missing implementations and features
  • Inputs have been migrated to use Flutter Form APIs and standardised keys to improve testing and validation.
    • Input field keys are now ValueKey(id). Example: ValueKey('myText').
    • Parent card keys for input widgets use ValueKey('${id}_adaptive') to avoid collisions with the inner field.
    • Selector item keys use ValueKey('${id}_${itemKey}') (useful for targeting specific options in tests).
  • RawAdaptiveCard.searchList accepts an optional inputId that is propagated to the modal search ChoiceFilter so the modal's search field receives a predictable key.
  • Actions missing implementations and features
  • Tests
  • Input reset uses document notifier resetAllInputs() / resetInput(id) (factory reset to baseline JSON). Subclass resetInput() overrides sync controllers only — see docs/reactive-riverpod.md.
  • mandatory inputs checks may not include all inputs because possible overrides may not be implement
  • Visitors are at the raw adaptive card level meaning all adaptive cards and their children are in scope. All forms are impacted at that level.
  • Possibly add the deprecated Action.HTTP
  • markdown bullet point spacing is wrong.
  • Material time picker doesn't support min and max time

Repository History #

Everything below this line is from the original README.md

The referenced GitHub repository has vanished. Look at the forking train to figure out where the current repository was forked from or look here:

  1. https://github.com/freemansoft/Flutter-AdaptiveCards Mine forked from
  2. https://github.com/lannes/Flutter-AdaptiveCards forked from
  3. https://github.com/juansoilan/Flutter-AdaptiveCards forked from the original
  4. https://github.com/rodydavis/Flutter-AdaptiveCards the original but possibly from the no longer here repo
  5. https://github.com/neohelden/Flutter-AdaptiveCards

Installing #

Version 0.3.0 is the first release of this package under the _fs namespace.

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_adaptive_cards_fs: ^0.3.0

import 'package:flutter_adaptive_cards_fs/flutter_adaptive_cards_fs.dart';

Using #

Using Adaptive Cards in Flutter coudn't be simpler: All you need is the AdaptiveCardsCanvas widget.

⚠️ Markdown support vs. ColumnSet content alignment #

Due to issue #171 of the Flutter Markdown package, the flag supportMarkdown was introduced to all Adaptive Card contractors. The default value of this property is true, to stay compatible with older versions of this package, which didn't support content alignment in ColumnSets. If the value is set to false the content alignment in ColumnSets is working accordingly, but every TextBlock is displayed without Markdown rendering. As soon if the issue is resolved this flag will be removed.

Loading an AdaptiveCard #

There are several constructors which handle loading of the AC from different sources. AdaptiveCardsCanvas.network takes a url to download the payload and display it. AdaptiveCardsCanvas.asset takes an asset path to load the payload from the local data. AdaptiveCardsCanvas.map takes a map (which can be obtained but decoding a string using the json class) and displays it.

Example #

AdaptiveCardsCanvas.network(
  placeholder: Text("Loading, please wait"),
  url: "www.someUrlThatPoints.To/A.json",
  hostConfigPath: "assets/host_config.json",
  onSubmit: (map) {
    // Send to server or handle locally
  },
  onOpenUrl: (url) {
    // Open url using the browser or handle differently
  },
  // If this is set, a button will appear next to each adaptive card which when clicked shows the JSON payload.
  // NOTE: this flag only has impact in development mode, this attribute does change nothing for realease builds.
  // This is very useful for debugging purposes
  showDebugJson: true,
);

Widgetbook #

The Widgetbook demonstrates components loaded via JSON. It does not implement any of the controls to change the seettings.

Running the tests #

Test files must end in _test , _test.dart in order to be recognized by the test jig.

flutter test

to see the result of each test

flutter test -r expanded

Golden tests are platform-specific and stored in subdirectories (e.g., gold_files/linux/). If you run tests on a platform without checked-in goldens (like macOS), they will fail unless you generate local goldens. All golden tests are tagged with @tag golden. You can run all tests other than golden with:

flutter test packages/flutter_adaptive_cards_fs --exclude-tags=golden

or from a terminal inside the package

flutter test --exclude-tags=golden

This updates or creates the golden files for the current platform in the appropriate subdirectory (e.g., gold_files/macos/). For the CI / CD setup, Linux-based goldens are required and should be generated using a Docker container:

# run the following command in the root folder of this project
docker run -it -v `pwd`:/app cirrusci/flutter:dev bash

# and inside the container execute
cd /app
flutter test --update-goldens

# afterwards commit the freshly generated sample files (after checking them)

Authors #

This has been heavilty rewritten and upgraded for later libraries and Flutter versions including null safety. See README_orig.md for origianl attribution

Contributing #

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

← Metadata

0
likes
0
points
385
downloads

Publisher

unverified uploader

Weekly Downloads

Metadata

Adaptive Cards are platform-agnostic snippets of UI, authored in JSON, that apps and services can openly exchange.

Repository (GitHub)
View/report issues

License

unknown (license)

Dependencies

chewie, flutter, flutter_markdown_plus, flutter_riverpod, flutter_svg, http, intl, url_launcher, video_player

More

Packages that depend on flutter_adaptive_cards_fs

Back