community-ff-mcp 0.4.0

package/docs/ff-yaml/05-actions.md

@@ -0,0 +1,953 @@
+# Actions
+
+Actions define the behavior triggered by user interactions or lifecycle events in FlutterFlow. Each action is stored as an individual YAML file inside a widget node's `trigger_actions/` directory.
+
+---
+
+## File Location Pattern
+
+Actions follow a strict directory hierarchy:
+
+```
+page/id-Scaffold_{id}/
+  page-widget-tree-outline/
+    node/id-{Widget}_{id}/
+      trigger_actions/
+        id-{TRIGGER_TYPE}/          # Trigger YAML file (orchestrator)
+          action/
+            id-{actionKey}.yaml     # Individual action files
+```
+
+For components the path mirrors pages:
+
+```
+component/id-Container_{id}/
+  component-widget-tree-outline/
+    node/id-{Widget}_{id}/
+      trigger_actions/
+        id-{TRIGGER_TYPE}/
+          action/
+            id-{actionKey}.yaml
+```
+
+Each trigger directory contains:
+- A **trigger YAML file** (`id-ON_TAP.yaml`) that defines the `rootAction` tree -- the execution order, conditional branching, and references to action keys
+- An **`action/` subdirectory** with one YAML file per action, each keyed by its unique action ID
+
+---
+
+## Trigger Types
+
+| Trigger | Directory Name | When It Fires |
+|---|---|---|
+| `ON_TAP` | `id-ON_TAP` | Widget tapped |
+| `ON_INIT_STATE` | `id-ON_INIT_STATE` | Page or component initializes |
+| `ON_TEXTFIELD_CHANGE` | `id-ON_TEXTFIELD_CHANGE` | TextField value changes |
+| `ON_TOGGLE_ON` | `id-ON_TOGGLE_ON` | Switch/toggle turned on |
+| `ON_TOGGLE_OFF` | `id-ON_TOGGLE_OFF` | Switch/toggle turned off |
+| `ON_LONG_PRESS` | `id-ON_LONG_PRESS` | Widget long-pressed |
+| `ON_TIMER_END` | `id-ON_TIMER_END` | Timer widget completes |
+| `CALLBACK-{id}` | `id-CALLBACK-{id}` | Named callback from parent component |
+
+---
+
+## Trigger YAML Structure
+
+The trigger file (`id-ON_TAP.yaml`) defines execution order using a `rootAction` tree. Each node in the tree references action files by `key`:
+
+```yaml
+rootAction:
+  key: 5ycxygcz
+  action:
+    key: qsw0br81          # References action/id-qsw0br81.yaml
+  followUpAction:
+    key: jmvd96i3
+    action:
+      key: 54wwjscn        # Next action in sequence
+trigger:
+  triggerType: ON_TAP
+```
+
+Simple trigger (single action, no chaining):
+
+```yaml
+rootAction:
+  key: 2xwagsw6
+  action:
+    key: 2b2dwjgo
+trigger:
+  triggerType: ON_TAP
+```
+
+---
+
+## Action Types
+
+### `navigate` -- Navigate to Page
+
+Navigates to another page, optionally passing parameters.
+
+```yaml
+navigate:
+  allowBack: true
+  replaceRoute: false
+  isNavigateBack: false
+  pageNodeKeyRef:
+    key: Scaffold_r4acaui6
+  passedParameters:
+    parameterPasses:
+      xd2r1k:
+        paramIdentifier:
+          name: establishment
+          key: xd2r1k
+        variable:
+          source: WIDGET_CLASS_PARAMETER
+          baseVariable:
+            widgetClass:
+              paramIdentifier:
+                name: estableshment
+                key: 974ngd
+          nodeKeyRef:
+            key: Container_qsdo2h11
+    widgetClassNodeKeyRef:
+      key: Scaffold_r4acaui6
+key: udyk1rjj
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `allowBack` | boolean | Whether back navigation is allowed |
+| `replaceRoute` | boolean | Replace current route instead of push |
+| `isNavigateBack` | boolean | Navigate back (pop) instead of forward |
+| `pageNodeKeyRef.key` | string | Scaffold key of the target page |
+| `passedParameters.parameterPasses` | map | Parameters passed to the target page |
+
+### `localStateUpdate` -- Update Widget or App State
+
+Updates one or more state variables.
+
+```yaml
+localStateUpdate:
+  updates:
+    - fieldIdentifier:
+        key: gdgw8
+      setValue:
+        inputValue:
+          serializedValue: "1"
+    - fieldIdentifier:
+        key: ty6re
+      setValue:
+        variable:
+          source: ENUMS
+          baseVariable:
+            enumVariable:
+              enumIdentifier:
+                name: subscription
+                key: 8a348
+              enumElementIdentifier:
+                name: monthly
+                key: 3lp2p
+  updateType: WIDGET
+  stateVariableType: WIDGET_CLASS_STATE
+key: ebx7vt69
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `updates` | list | Fields to update |
+| `updates[].fieldIdentifier.key` | string | Key of the state field |
+| `updates[].setValue` | value | New value (literal `inputValue` or `variable`) |
+| `updates[].clearValue` | `{}` | Clear the field instead of setting |
+| `updateType` | enum | `WIDGET` for component state |
+| `stateVariableType` | enum | `WIDGET_CLASS_STATE` or `APP_STATE` |
+
+### `database.firestoreQuery` -- Firestore Query
+
+Queries a Firestore collection with filters.
+
+```yaml
+database:
+  firestoreQuery:
+    collectionIdentifier:
+      name: stripe_customer_subscriptions
+      key: 94977h9r
+    hideOnEmpty: false
+    singleTimeQuery: true
+    where:
+      filters:
+        - baseFilter:
+            collectionFieldIdentifier:
+              name: customer_phone
+            relation: EQUAL_TO
+            variable:
+              source: FIREBASE_AUTH_USER
+              baseVariable:
+                auth:
+                  property: PHONE_NUMBER
+        - baseFilter:
+            collectionFieldIdentifier:
+              name: expiration_date
+            relation: GREATER_THAN
+            variable:
+              source: GLOBAL_PROPERTIES
+              baseVariable:
+                globalProperties:
+                  property: CURRENT_TIMESTAMP
+      isAnd: true
+  returnParameter:
+    dataType:
+      listType:
+        scalarType: Document
+      subType:
+        collectionIdentifier:
+          name: stripe_customer_subscriptions
+          key: 94977h9r
+outputVariableName: subscribedUser
+key: 30vd1j0o
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `collectionIdentifier` | name+key | Target Firestore collection |
+| `singleTimeQuery` | boolean | Query once (not a stream) |
+| `where.filters` | list | Filter conditions |
+| `where.filters[].baseFilter.relation` | enum | `EQUAL_TO`, `GREATER_THAN`, etc. |
+| `where.isAnd` | boolean | AND vs OR filters |
+| `outputVariableName` | string | Name for the action output variable |
+| `returnParameter.dataType` | type | Return type (usually `listType: Document`) |
+
+### `database.createDocument` -- Create Firestore Document
+
+Creates a new document in a Firestore collection.
+
+```yaml
+database:
+  createDocument:
+    collectionIdentifier:
+      name: RedeemedUserDeals
+      key: lzo3gj3d
+    write:
+      updates:
+        UserRef:
+          fieldIdentifier:
+            name: UserRef
+          variable:
+            source: FIREBASE_AUTH_USER
+            baseVariable:
+              auth:
+                property: USER_REFERENCE
+        RedeemedAt:
+          fieldIdentifier:
+            name: RedeemedAt
+          variable:
+            source: GLOBAL_PROPERTIES
+            baseVariable:
+              globalProperties:
+                property: CURRENT_TIMESTAMP
+    parentReference:
+      source: WIDGET_CLASS_PARAMETER
+      baseVariable:
+        widgetClass:
+          paramIdentifier:
+            name: establishment
+            key: u32pu8
+      nodeKeyRef:
+        key: Container_p61gj0ld
+key: u00ieh05
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `collectionIdentifier` | name+key | Target collection |
+| `write.updates` | map | Field name to value mappings |
+| `write.updates.{field}.fieldIdentifier.name` | string | Firestore field name |
+| `write.updates.{field}.inputValue` | value | Literal value |
+| `write.updates.{field}.variable` | variable | Dynamic value |
+| `write.updates.{field}.dataStructFieldUpdate` | object | Nested data struct value |
+| `parentReference` | variable | Parent document reference (for subcollections) |
+
+### `database.updateDocument` -- Update Firestore Document
+
+Updates fields on an existing document.
+
+```yaml
+database:
+  updateDocument:
+    write:
+      updates:
+        push_notifications:
+          fieldIdentifier:
+            name: push_notifications
+          inputValue:
+            serializedValue: "true"
+    reference:
+      source: FIREBASE_AUTH_USER
+      baseVariable:
+        auth:
+          property: USER_REFERENCE
+key: 2d5pxkrp
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `write.updates` | map | Fields to update |
+| `reference` | variable | Document reference to update |
+
+### `database.apiCall` -- Call API Endpoint
+
+Calls a configured API endpoint.
+
+```yaml
+database:
+  apiCall:
+    endpointIdentifier:
+      name: SendDiscountEmail
+      key: qegob
+    variables:
+      - variableIdentifier:
+          name: token
+          key: b7vj02x7
+        variable:
+          source: FIREBASE_AUTH_USER
+          baseVariable:
+            auth:
+              property: JWT_TOKEN
+outputVariableName: apiResultrla
+key: km9eei8s
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `endpointIdentifier` | name+key | API endpoint identifier |
+| `variables` | list | API call parameters |
+| `outputVariableName` | string | Name for the response output |
+
+### `customAction` -- Execute Custom Action
+
+Calls a custom Dart function.
+
+```yaml
+customAction:
+  customActionIdentifier:
+    name: linkAnonymousUser
+    key: nujdl
+  argumentValues:
+    arguments:
+      snaq9d:
+        value:
+          variable:
+            source: WIDGET_STATE
+            baseVariable:
+              widgetState:
+                returnParameter:
+                  dataType:
+                    scalarType: String
+            nodeKeyRef:
+              key: TextField_mxlvp4hj
+outputVariableName: linkUserResult
+key: ww6ook8u
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `customActionIdentifier` | name+key | Custom action reference |
+| `argumentValues.arguments` | map | Argument key to value mappings |
+| `outputVariableName` | string | Name for the return value |
+
+### `snackBar` -- Show Snack Bar Notification
+
+Displays a snack bar message.
+
+```yaml
+snackBar:
+  textMessage:
+    inputValue:
+      serializedValue: Code sent!
+  textStyle:
+    variableColor:
+      inputValue:
+        color:
+          themeColor: PRIMARY_TEXT
+  durationMillis: 4000
+  subAction:
+    action:
+      navigate:
+        allowBack: true
+  shouldHidePreviousSnackbar: false
+  backgroundColor:
+    inputValue:
+      color:
+        themeColor: PRIMARY
+key: 72bzwegp
+```
+
+The `textMessage` can also use a `variable` for dynamic text (string interpolation, etc.) instead of a literal `inputValue`.
+
+| Field | Type | Description |
+|---|---|---|
+| `textMessage` | value | Message text (literal or variable) |
+| `durationMillis` | integer | Display duration in milliseconds |
+| `backgroundColor` | color | Background color |
+| `textStyle.variableColor` | color | Text color |
+| `shouldHidePreviousSnackbar` | boolean | Dismiss existing snack bar first |
+| `subAction` | action | Action to execute when snack bar is tapped |
+
+### `revenueCat.paywall` -- Show RevenueCat Paywall
+
+Displays the RevenueCat paywall for a given entitlement.
+
+```yaml
+revenueCat:
+  paywall:
+    entitlementId:
+      inputValue:
+        serializedValue: Pro
+key: erd8m4q2
+```
+
+### `revenueCat.restore` -- Restore RevenueCat Purchases
+
+```yaml
+revenueCat:
+  restore: {}
+key: 81j500xc
+```
+
+### `pageView` -- Control PageView Widget
+
+Programmatically navigates a PageView widget.
+
+```yaml
+pageView:
+  type: JUMP_TO
+  jumpToIndex:
+    inputValue:
+      serializedValue: "1"
+  pageViewNodeKeyRef:
+    key: PageView_txxkvt09
+key: 9u9dws4x
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | enum | `JUMP_TO`, `NEXT`, `PREVIOUS` |
+| `jumpToIndex` | value | Target page index (for `JUMP_TO`) |
+| `pageViewNodeKeyRef.key` | string | Key of the target PageView widget |
+
+### `timer` -- Start or Stop Timer
+
+Controls a Timer widget.
+
+```yaml
+timer:
+  type: START_TIMER
+key: yfifxw3z
+```
+
+```yaml
+timer:
+  type: STOP_TIMER
+key: ucm9biyi
+```
+
+### `executeCallbackAction` -- Execute Component Callback
+
+Invokes a callback parameter defined on a parent component.
+
+```yaml
+executeCallbackAction:
+  parameterIdentifier:
+    name: onManage
+    key: aulgkx
+  argumentValues: {}
+key: 2b2dwjgo
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `parameterIdentifier` | name+key | Callback parameter to invoke |
+| `argumentValues` | map | Arguments to pass to the callback |
+
+### `alertDialog` -- Show Dialog
+
+Displays a dialog, either a custom component or dismisses an existing one.
+
+Show a custom dialog:
+
+```yaml
+alertDialog:
+  customDialog:
+    passedParameters:
+      parameterPasses:
+        t8j0tg:
+          paramIdentifier:
+            name: dealTitle
+            key: t8j0tg
+          variable:
+            source: GENERATOR_VARIABLE
+            baseVariable:
+              generatorVariable: {}
+            operations:
+              - accessDocumentField:
+                  fieldIdentifier:
+                    name: Name
+            nodeKeyRef:
+              key: ListView_8lh3xfe2
+      widgetClassNodeKeyRef:
+        key: Container_qsdo2h11
+    dimensions:
+      width:
+        percentOfScreenSizeValue:
+          inputValue: 80
+    barrierColor: {}
+    nonDismissible: true
+    isGlobal: true
+    componentClassNodeKeyRef:
+      key: Container_gtqk3kbu
+key: u43n5c2l
+```
+
+Dismiss dialog:
+
+```yaml
+alertDialog:
+  dismissDialog: {}
+key: b5f5u42p
+```
+
+### `waitAction` -- Wait/Delay
+
+Pauses execution for a specified duration.
+
+```yaml
+waitAction:
+  durationMillisValue:
+    inputValue: 4000
+key: pzxnwi4u
+```
+
+### `requestPermissions` -- Request Device Permissions
+
+```yaml
+requestPermissions:
+  permissionType: NOTIFICATIONS
+key: lu5gfw3c
+```
+
+```yaml
+requestPermissions:
+  permissionType: LOCATION
+key: wgmnqfwt
+```
+
+---
+
+## Conditional Actions
+
+Conditional branching is defined in the trigger YAML file (not in individual action files) using `conditionActions`. The structure supports single conditions, multiple conditions, and nested conditions.
+
+### Basic Conditional (true/false branch)
+
+```yaml
+rootAction:
+  key: 5ycxygcz
+  action:
+    key: qsw0br81
+  followUpAction:
+    key: jmvd96i3
+    conditionActions:
+      trueActions:
+        - condition:
+            variable:
+              source: FUNCTION_CALL
+              functionCall:
+                values:
+                  - variable:
+                      source: GLOBAL_PROPERTIES
+                      baseVariable:
+                        globalProperties:
+                          property: IS_IOS
+                  - inputValue:
+                      serializedValue: "true"
+                condition:
+                  relation: EQUAL_TO
+      falseAction:
+        key: opj63zwi
+        action:
+          key: 54wwjscn
+      hasMultiConditions: false
+      key: ugl3mgen
+trigger:
+  triggerType: ON_TAP
+```
+
+### Multiple Conditions
+
+When `hasMultiConditions: true`, the `trueActions` list contains multiple condition branches evaluated in order:
+
+```yaml
+conditionActions:
+  trueActions:
+    - condition:
+        variable:
+          source: FUNCTION_CALL
+          functionCall:
+            values:
+              - variable:
+                  source: ACTION_OUTPUTS
+                  baseVariable:
+                    actionOutput:
+                      outputVariableIdentifier:
+                        name: updateState
+                      actionKeyRef:
+                        key: 00tn7yxo
+              - variable:
+                  source: ENUMS
+                  baseVariable:
+                    enumVariable:
+                      enumIdentifier:
+                        name: AppUpdateState
+                        key: fta87
+                      enumElementIdentifier:
+                        name: forceUpdate
+                        key: biqqk
+            condition:
+              relation: EQUAL_TO
+      trueAction:
+        key: g4iwdyck
+        action:
+          key: u43n5c2l
+    - condition:
+        # Second condition...
+      trueAction:
+        key: riqztjef
+        action:
+          key: dkb400cy
+  hasMultiConditions: true
+  key: 2jfp921u
+```
+
+### Combined Conditions (AND/OR)
+
+Multiple conditions can be combined using `combineConditions`:
+
+```yaml
+conditionActions:
+  trueActions:
+    - condition:
+        variable:
+          source: FUNCTION_CALL
+          functionCall:
+            values:
+              - variable:
+                  source: LOCAL_STATE
+                  baseVariable:
+                    localState:
+                      fieldIdentifier:
+                        name: isAnonymous
+                        key: bfu0ivv2
+                      stateVariableType: APP_STATE
+              - variable:
+                  source: LOCAL_STATE
+                  baseVariable:
+                    localState:
+                      fieldIdentifier:
+                        name: doneFree
+                        key: e4yygjed
+                      stateVariableType: APP_STATE
+            combineConditions:
+              operator: AND_OP     # or OR_OP
+```
+
+### RevenueCat Entitlement Condition
+
+A special condition type for RevenueCat subscription checks:
+
+```yaml
+conditionActions:
+  trueActions:
+    - condition:
+        revenueCatEntitlementResponse: {}
+      trueAction:
+        key: lewj54wz
+        action:
+          key: l00bd53j
+  falseAction:
+    key: p5lhm9f5
+    action:
+      key: 50132f9w
+```
+
+---
+
+## Action Chaining
+
+Actions execute sequentially using `followUpAction`. Each node in the chain can contain an `action` reference, another `conditionActions` block, or `terminate` to stop execution.
+
+### Sequential Execution
+
+```yaml
+rootAction:
+  key: 5dyi3ba5
+  action:
+    key: first_action
+  followUpAction:
+    key: abc123
+    action:
+      key: second_action
+    followUpAction:
+      key: def456
+      action:
+        key: third_action
+      followUpAction:
+        key: ghi789
+        action:
+          key: fourth_action
+```
+
+### Terminate Execution
+
+`terminate: {}` stops the action chain early, typically used inside conditional branches:
+
+```yaml
+trueAction:
+  key: bc1vt0ak
+  action:
+    navigate:
+      allowBack: false
+      pageNodeKeyRef:
+        key: Scaffold_u52v700s
+  followUpAction:
+    key: r6wrgnpz
+    terminate: {}
+```
+
+---
+
+## Disabled Actions
+
+FlutterFlow uses `disableAction` to mark actions or conditionals as disabled. There are three distinct patterns depending on what is being disabled.
+
+### Pattern 1: Disabling a Leaf Action (Unconditional)
+
+To fully disable a single action (navigate, database, revenueCat, etc.), wrap the action content in `disableAction` at the **action file level**. The trigger chain continues to reference the same key — FlutterFlow reads the file, sees `disableAction`, and skips execution.
+
+```yaml
+# Action file: id-epxy2a0w.yaml
+key: epxy2a0w
+disableAction:
+  actionNode:
+    key: gm8dis03           # Internal node key (can be any unique key)
+    action:
+      navigate:
+        allowBack: false
+        passedParameters:
+          widgetClassNodeKeyRef:
+            key: Scaffold_tydsj8ql
+        isNavigateBack: false
+        transition:
+          transitionType: FADE_IN
+          durationMillis: 500
+        pageNodeKeyRef:
+          key: Scaffold_tydsj8ql
+      key: epxy2a0w          # Must match the outer key
+```
+
+| Field | Description |
+|-------|-------------|
+| `key` (outer) | The action's original key — chain references this |
+| `disableAction.actionNode.key` | Internal node key (any unique value) |
+| `disableAction.actionNode.action` | The original action content, preserved for re-enabling |
+| `disableAction.actionNode.action.key` | Must match the outer `key` |
+
+**Important:** Disabling a leaf action at the file level does NOT disable `followUpAction` chains defined in the trigger YAML. If the trigger chain has a `followUpAction` after this action reference, that follow-up will still execute.
+
+### Pattern 2: Disabling a Conditional Node
+
+To disable an entire `conditionActions` block in the trigger chain, two changes are required:
+
+**Step 1 — Create a new action file** that wraps the full conditional in `disableAction.actionNode.conditionActions`. Leaf actions within the conditional are inlined (not file references) with their own `disableAction` wrappers:
+
+```yaml
+# Action file: id-ds8cnd01.yaml (new file)
+key: ds8cnd01
+disableAction:
+  actionNode:
+    key: f441awwi               # Original conditional node key from the chain
+    conditionActions:
+      falseAction:
+        key: wkklfcpy
+        action:
+          key: epxy2a0w
+          disableAction:          # Leaf action inlined with its own disable
+            actionNode:
+              key: gm8dis03
+              action:
+                navigate:
+                  allowBack: false
+                  pageNodeKeyRef:
+                    key: Scaffold_tydsj8ql
+                key: epxy2a0w
+      trueActions:
+        - condition:
+            revenueCatEntitlementResponse: {}
+          trueAction:
+            key: 5uq5p5vt
+            action:
+              key: bgxsmj4b
+              disableAction:      # Another leaf action inlined
+                actionNode:
+                  key: gm8dis04
+                  action:
+                    navigate:
+                      allowBack: false
+                      pageNodeKeyRef:
+                        key: Scaffold_91ca3wwv
+                    key: bgxsmj4b
+      hasMultiConditions: false
+      key: ev7ush66
+```
+
+**Step 2 — Update the trigger chain YAML.** Replace the `conditionActions` block with an `action` reference to a noop key (a key with no corresponding action file):
+
+```yaml
+# Before (in trigger chain):
+followUpAction:
+  key: f441awwi
+  conditionActions:
+    falseAction: ...
+    trueActions: ...
+    hasMultiConditions: false
+    key: ev7ush66
+
+# After (in trigger chain):
+followUpAction:
+  key: f441awwi
+  action:
+    key: np8noop1              # Noop key — no action file exists for this key
+```
+
+**Note:** The noop key has no corresponding action file. When pushed via the UI, FlutterFlow handles this internally. When pushed via the API, you may need to create the action file with the disabled conditional content under the noop key itself (see API Limitations).
+
+### Pattern 3: Conditionally Disabled Action
+
+Actions can be conditionally disabled using `disableAction` with a condition. When the condition evaluates to true, the wrapped action executes; otherwise it is skipped.
+
+```yaml
+key: hfzr0kmk
+disableAction:
+  actionNode:
+    key: 6zoe9nca
+    conditionActions:
+      trueActions:
+        - condition:
+            variable:
+              source: FUNCTION_CALL
+              functionCall:
+                values:
+                  - variable:
+                      source: FIREBASE_AUTH_USER
+                      baseVariable:
+                        auth:
+                          property: USERS_DATA_FIELD
+                          usersDataField:
+                            name: zipCode
+                  - inputValue:
+                      serializedValue: "0"
+                condition:
+                  relation: EQUAL_TO
+          trueAction:
+            key: 664phh8p
+            action:
+              localStateUpdate:
+                # ...action body inline...
+            followUpAction:
+              key: pqmxin3v
+              terminate: {}
+      hasMultiConditions: false
+      key: xsa3loej
+```
+
+### Key Rules
+
+- `disableAction` is only valid in **action files**, never in the trigger chain YAML directly
+- Leaf actions inlined inside `disableAction` use the full action body, not key references
+- The original action content is preserved inside the wrapper for easy re-enabling
+- Disabling a leaf action does NOT prevent `followUpAction` chains in the trigger from continuing
+
+---
+
+## Action Output Variables
+
+Actions that produce results use `outputVariableName` to store the value. Subsequent actions can reference these outputs via the `ACTION_OUTPUTS` variable source:
+
+**Producing an output:**
+
+```yaml
+database:
+  firestoreQuery:
+    collectionIdentifier:
+      name: RedeemedUserDeals
+      key: lzo3gj3d
+    # ...query config...
+outputVariableName: deals
+key: iw14lghd
+```
+
+**Consuming an output:**
+
+```yaml
+variable:
+  source: ACTION_OUTPUTS
+  baseVariable:
+    actionOutput:
+      outputVariableIdentifier:
+        name: deals
+      actionKeyRef:
+        key: iw14lghd
+  nodeKeyRef:
+    key: Scaffold_4qdr9nq8
+  actionComponentKeyRef: {}
+```
+
+The `actionKeyRef.key` must match the `key` of the action that produced the output. When the output comes from an action component (reusable action block), `actionComponentKeyRef.key` references the component.
+
+---
+
+## App Action Components
+
+Reusable action sequences can be defined as **app action components** and referenced across pages. These live under `app-action-components/`:
+
+```yaml
+identifier:
+  name: checkUpdateBlock
+  key: ld3jo3
+actions:
+  rootAction:
+    key: dmm3dw7g
+    action:
+      customAction:
+        customActionIdentifier:
+          name: checkAppUpdateStatus
+          key: zjg1l
+        argumentValues:
+          arguments:
+            fr6rim:
+              value:
+                variable:
+                  source: FIREBASE_AUTH_USER
+                  baseVariable:
+                    auth:
+                      property: USERS_DATA_FIELD
+                      usersDataField:
+                        name: app_version
+      outputVariableName: updateState
+      key: 00tn7yxo
+    followUpAction:
+      key: isp97zrh
+      conditionActions:
+        # ...branching logic...
+description: ""
+```
+
+App action components use the same action and chaining structures but are not tied to any specific widget trigger.