rulecms_widget library

Flutter SDK for RuleCMS widgets.

Mirror of @rulecms/widget-react for Flutter hosts: fetch by token + key, walk the layout tree, render via registered libraries.

Classes

ChildCollection
ComponentLibrary
Contract for a RuleCMS component library (mirror of ComponentLibraryModule).
DisplayItemColumn
DisplayItemRow
GetRuleCMSWidgetResponse
Envelope returned by GET /api/v1/c/widget/get (and the dev twin).
Items
LibraryComponentBuildContext
LibraryComponentEntry
MappedColumnStyles
Maps RulesCMS style attribute values → Flutter layout primitives.
NoContainerResolverContext
What a resolver knows about the render it is being asked about.
NormalizedWidgetResolve
RenderComponents
Walks an Items tree and renders rows → columns via registered libraries.
RuleCMSHostClassName
Flutter stand-in for a class-bearing wrapper div.
RuleCMSWidget
Fetches (or accepts pre-fetched) RuleCMS widget data and renders it.
RuleCMSWidgetClient
HTTP client for RuleCMS widget GET and ruleset resolve endpoints.
RuleCMSWidgetData
Render-ready widget model after prepareRuleCMSWidgetData.
RuleCMSWidgetProvider
Supplies token, optional endpoint override, and component libraries.
WidgetCollection
WidgetCollectionRef
WidgetData
Raw widget payload from the client GET API.
WidgetOverlayLayers
Layers drawn over a widget's rows. An object rather than a bare array so the stacking contract has somewhere to grow later.
WidgetSelection
Which widget a ruleset picked. Returned alongside the widget payload.

Enums

DeviceDisplayType
Device buckets matching RulesCMS *-3-resolutions leaves.
PageViewType
Where this render happens. Cards that fill placeholders skip that work in PageViewType.compose, where the author should still see the tokens.
RuleCMSWidgetMode
WidgetSelectionOutcome
Which widget a ruleset picked, and why.

Constants

componentPropsPathSeparator → const String
Separator between column ids in a ComponentPropsMap path key.
cssClassesAttributeName → const String
Persisted attribute that holds host CSS classes for a column or row.
defaultBaseZIndex → const int
Base z-index when the author set none.
defaultPublishedWidgetCache → const Duration
How long a published-token GET stays in the in-process cache. Flutter has no Next.js revalidate; this is the same 60-second default widget-react applies on the server.
defaultWidgetResolveContentType → const String
Default Content-Type for the resolve POST. text/plain matches the web SDKs, which use it to stay CORS-simple. Flutter has no CORS preflight, but the body is the same JSON string.
kDevClientTokenPrefix → const String
Prefix on RulesCMS client tokens for Development / non-publishable environments.
kDevWidgetApiPath → const String
Live draft client API path — no cache; reads the widget table directly.
kDevWidgetResolveApiPath → const String
Live draft ruleset resolve path (POST).
kPublishedWidgetApiPath → const String
Published (cached) client API path.
kPublishedWidgetResolveApiPath → const String
Published ruleset resolve path (POST).
kRulecmsApiOrigin → const String
Live draft API host — RulesCMS production.
kWidgetCacheApiOrigin → const String
Published (cached) API host.
overlayLayerPointerEvents → const List<String>
pointerEventsWidgetAttributeName → const String
publishedKeySeparator → const String
Joins environmentId and the resource key in a published key.
rulecmsAnonymousIdStorageKey → const String
Same key the web SDKs use in localStorage.
widgetPlaceholderValuesKey → const String
The one key copied from RuleCMSWidget.placeholderValues onto a card. Must stay the key r-text reads. The renderer copies the value and does not look inside it.
zIndexWidgetAttributeName → const String
The base's own place in the stack. Read here rather than through a shared style mapper on purpose: z-index is only meaningful to the widget wrapper for now.

Functions

buildWidgetFetchUrl({required String publishedKey, required String token, String? endpoint}) → String
Builds the widget fetch URL.
buildWidgetResolveRequestBody({required String token, required String rulesetPublishedKey, Map<String, Object?>? params}) → Map<String, Object?>
Body for the resolve POST. Published tokens send { token, rulesetPublishedKey, params, mode: 'payload' }. dev. tokens hit the draft route, which wants the bare rulesetKey and no mode.
buildWidgetResolveUrl({required String token, String? endpoint}) → String
Ruleset resolve URL. The token, ruleset key, and params travel in the POST body, so the URL has no query string.
clearPublishedWidgetFetchCache() → void
Drops the in-process published-widget cache. Tests call this between cases.
collectComponentInstancePaths({required Items? displayItemList, required Map<String, WidgetCollection>? widgetCollections}) → List<String>
Every component instance in a config, as the /-joined column-id path that ComponentPropsMap keys are matched against. Collections contribute their holding column to the path rather than a path of their own.
deviceTypeForWidth(double width) → DeviceDisplayType
Breakpoints aligned with common web composer defaults (px logical width).
deviceTypeOf(BuildContext context) → DeviceDisplayType
findUnmatchedComponentPropsKeys({required ComponentPropsMap? componentProps, required Items? displayItemList, required Map<String, WidgetCollection>? widgetCollections}) → List<String>
Names the componentProps keys that address no component in this config.
generateAnonymousId() → String
RFC 4122 v4. Used when the platform has no persisted id yet.
getOrCreateAnonymousId() → Future<String>
Anonymous id used as params.anonId for experiments.
getOverlayLayerZIndex(int baseZIndex, int layerIndex) → int
Where a layer sits above a base at baseZIndex: the first layer takes baseZIndex + 1, the second baseZIndex + 2, and so on.
hasOverlayLayers(Items? items) → bool
True when this Items asks for at least one layer over its rows.
isDevClientToken(String? token) → bool
isOverlayLayerEmptyForDevice({required Items layer, required DeviceDisplayType deviceDisplayType}) → bool
True when a layer has nothing to put on screen at this width, so its Positioned.fill is not worth emitting. Its z-index slot still goes unclaimed — see getOverlayLayerZIndex.
isWidgetHiddenForDevice({Map<String, dynamic>? containerAttributes, required DeviceDisplayType deviceDisplayType}) → bool
True when the author asked for the whole widget to be hidden at this device width. Callers must skip this in compose mode — a hidden widget on the canvas leaves nothing to edit.
isWidgetResolveFallbackStatus(int status) → bool
Whether a failed resolve should be retried through the plain GET of fallbackPublishedKey. Only 5xx qualifies: a 4xx means the request itself is wrong, and a fallback widget would hide that.
mapColumnStyles(ResolvedDeviceAttributes attrs, {Map<String, String>? cssVariables}) → MappedColumnStyles
normalizeCssClasses(Object? value) → String?
Untrusted leaf from a persisted payload → a safe class string, or null.
normalizeWidgetResolveResponse({required String token, required String rulesetPublishedKey, required Object? body}) → NormalizedWidgetResolve?
Reduces either resolve response to the existing widget payload plus a WidgetSelection. Published: { success, data: { …payload, selection } }. Draft (dev. token): unwrapped { resolution, widget, childCollections }. Returns null when the body is not a successful resolve.
overlayLayerKey(int layerIndex, {int? zIndex}) → Key
Stand-in for web's data-rulecms-overlay-layer. Flutter has no data attributes; widget tests find the layer box by this ValueKey.
prepareRuleCMSWidgetData({required WidgetData widget, required Map<String, ChildCollection> childCollections, Map<String, String>? cssVariables, bool? includeCssVariables, Map<String, String>? classDefinitions, bool? includeClassDefinitions}) → RuleCMSWidgetData
Transform raw widget API data into render-ready displayItemList + collections. Mirrors prepareRuleCMSWidgetData in @rulecms/widget-react.
resolveBaseZIndex({Map<String, dynamic>? containerAttributes, required DeviceDisplayType deviceDisplayType}) → int
The base's z-index for this device, or 0 when unset or unusable. Accepts the number and the numeric string, since hand-authored JSON produces both.
resolveNoContainer(LibraryComponentEntry? entry, NoContainerResolverContext context) → bool
Decides whether a component needs the dimension-style wrapper.
resolveOverlayLayerPointerEvents({Map<String, dynamic>? containerAttributes, required DeviceDisplayType deviceDisplayType}) → String?
A layer's pointer-events for this device, lifted from the layer's own container settings. null leaves IgnorePointer off the box entirely.
resolveRendersOwnElement(LibraryComponentEntry? entry, NoContainerResolverContext context) → bool
Decides whether a card's own root can carry a className — i.e. whether the renderer can hand the card a class instead of wrapping it to carry one.
resolveWidgetApiOrigin(String token, {String? endpoint}) → String
Resolves the API origin. Consumers normally omit endpoint — Development tokens hit RulesCMS; published tokens hit widget-cache.
resolveWidgetInstanceProps({ComponentPropsMap? componentProps, List<String>? ancestorColumnIds, required String columnId}) → WidgetInstanceProps?
Picks the host-supplied props for one component instance out of the componentProps map.
shouldWrapInOverlayStack({required Items? items, required bool isComposeMode}) → bool
Whether preview/published rendering should wrap the base in an overlay Stack. Compose mode ignores layers. An empty base keeps its existing empty Column — the base has to invent the size.
toRulesetKey(String rulesetPublishedKey) → String
The draft resolve route wants the bare ruleset-… key. Callers may hand us a published key ({environmentId}---ruleset-…); strip the environment prefix so both spellings work with a dev. token.
warnUnmatchedComponentProps({required ComponentPropsMap? componentProps, required Items? displayItemList, required Map<String, WidgetCollection>? widgetCollections, required String publishedKey}) → void
Debug-only warning for componentProps keys that address nothing.
withWidgetPlaceholderValues({WidgetInstanceProps? widgetInstanceProps, Object? placeholderValues}) → WidgetInstanceProps?
Widget-wide placeholder values for one component instance.

Typedefs

ComponentPropsMap = Map<String, WidgetInstanceProps>
Host-supplied per-instance props, keyed by the column id of the component instance they are meant for. Column ids are the UUIDs persisted in the widget config; the composer's Modify drawer shows the selected one.
LibraryComponentBuilder = Widget Function(LibraryComponentBuildContext context)
LibraryRegistrationMap = Map<String, ComponentLibrary>
Consumer registration map, e.g. { 'default': sourceComponentsLibrary }.
MountsMap = Map<String, MountWidgetBuilder>
Host-app widgets r-mount can render, keyed by the name an author types in the composer. The name is a map lookup, not a string that becomes code. A miss is a placeholder.
MountWidgetBuilder = Widget Function(Map<String, Object?> props)
Host-app widget factory for one Custom (r-mount) name.
ResolveNoContainer = bool Function(NoContainerResolverContext context)
ResolveRendersOwnElement = bool Function(NoContainerResolverContext context)
WidgetInstanceProps = Map<String, Object?>
Extra props a host application supplies for one component instance, handed to the component as LibraryComponentBuildContext.widgetInstanceProps.

Exceptions / Errors

RuleCMSWidgetFetchException