core library

Platform-neutral models and layout decisions for adaptive actions.

Every public symbol exported by this library is part of the supported core contract. This library has no experimental renderer API: renderers integrate by exchanging immutable data with core instead of implementing a base class.

A renderer describes each root action, the space it has available, and the layout options it can draw. ActionLayoutResolver assigns every root to one region and applies the request's region-local order overrides without importing Flutter, measuring UI, or interpreting widgets.

The usual data flow is:

action tree + renderer costs + available capacity
                        |
                        v
               ActionLayoutResolver
                        |
                        v
      ordered primary | overflow | hidden

The renderer owns the meaning of option IDs and their numeric costs. Core only compares those costs, returns the selected IDs, and never invokes an action payload:

import 'package:adaptive_actions/core.dart';

final save = AdaptiveAction<String>.action(
  id: ActionId('save'),
  metadata: const ActionMetadata(label: 'Save'),
  payload: 'save-document',
);

final request = ActionLayoutRequest(
  actions: ActionCollection(roots: [save]),
  constraints: ActionLayoutConstraints(
    primaryCapacity: 48,
    profiles: [
      ActionLayoutProfile(
        actionId: save.id,
        options: [
          ActionLayoutOption(
            id: ActionLayoutOptionId('icon'),
            cost: 48,
          ),
        ],
      ),
    ],
  ),
  capabilities: const RendererCapabilities(),
);

final layout = const ActionLayoutResolver().resolve(request);
final optionId = layout.primary.single.optionId;
// Draw `save` using the renderer widget registered as `optionId`.

void handlePayload(String payload) {
  // Dispatch the caller-owned command outside core.
}

final action = layout.primary.single.action;
if (action.isEnabled) {
  final payload = action.payload;
  if (payload != null) {
    handlePayload(payload);
  }
}

Classes

ActionCollection<T extends Object>: The complete action tree and its root-level placement relationships.
ActionCollectionEntry<T extends Object>: One normalized declaration fragment for ActionCollection.fromEntries.
ActionLayoutConstraints: Available primary space and renderer costs for one resolution pass.
ActionLayoutOption: A renderer-owned way to draw an action in the primary region.
ActionLayoutProfile: The primary-region layouts available for one root action.
ActionLayoutRequest<T extends Object>: A validated snapshot of everything needed for one layout decision.
ActionLayoutResolver: Produces the final, renderer-ready layout for one ActionLayoutRequest.
ActionLayoutResult<T extends Object>: The final renderer input after optional region ordering is applied.
ActionMetadata: User-facing text and renderer lookup data for an action.
ActionPlacementConstraints: Shared placement rules for a set of root actions.
ActionPlacementDelegate: Assigns action roots to primary, overflow, or hidden regions.
ActionPlacementPolicy: The placement rule for one root action.
ActionPlacementResult<T extends Object>: The mutually exclusive regions produced by ActionPlacementDelegate.
AdaptiveAction<T extends Object>: An immutable, platform-neutral action node.
AdaptiveMenuDivider<T extends Object>: A visual separator between groups of adaptive action entries.
AdaptiveMenuEntry<T extends Object>: A platform-neutral entry in an adaptive action declaration.
AutomaticPlacementPreference: Automatic-placement preferences used when primary space is limited.
DefaultActionPlacementDelegate: The standard deterministic implementation of ActionPlacementDelegate.
HiddenAction<T extends Object>: A root excluded from both visible layout regions.
RendererCapabilities: Interaction features available from an action renderer.
ResolutionDiagnostic: Developer-facing information about a placement constraint.
ResolvedPrimaryAction<T extends Object>: A primary root and the renderer layout selected for it.

Enums

ActionPlacement: The layout region policy for an adaptive action.
ActionPlacementSplitPolicy: Whether actions governed by ActionPlacementConstraints may be placed separately.
HiddenActionReason: The reason a root is unavailable in a resolved layout.
ResolutionDiagnosticCode: Stable machine-readable categories emitted during resolution.

Extension Types

ActionId: The stable identity of an action across layout passes.
ActionLayoutOptionId: A renderer-owned key for one primary-region widget layout.
ActionPlacementConstraintId: The stable identity of root-level placement constraints.
PrimaryRetentionPriority: How strongly an automatic action should be retained in primary.

core library

Classes

Enums

Extension Types

adaptive_actions package

core library