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.
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 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.

Enums

DeviceDisplayType
Device buckets matching RulesCMS *-3-resolutions leaves.
RuleCMSWidgetMode

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.
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.
kPublishedWidgetApiPath → const String
Published (cached) client API path.
kRulecmsApiOrigin → const String
Live draft API host — RulesCMS production.
kWidgetCacheApiOrigin → const String
Published (cached) API host.
overlayLayerPointerEvents → const List<String>
pointerEventsWidgetAttributeName → const String
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.
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.
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.
mapColumnStyles(ResolvedDeviceAttributes attrs) → MappedColumnStyles
normalizeCssClasses(Object? value) → String?
Untrusted leaf from a persisted payload → a safe class string, or null.
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}) → 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.
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.

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