# FloatingActionMenuButton A floating-action circle whose press opens an anchored menu of related actions above it. Version: 0.2.0-preview.1 (preview) Content digest: 70ac710f4d22dce040e7ac593379ba8aca9dcb59a0b9c0f839819cae0e2bb721 Contract kind: source-derived Source: packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx ## Guidance { "summary": "A floating-action circle whose press opens an anchored menu of related actions above it.", "guidance": [ { "heading": "Overview", "body": "The floating-action circle whose press opens an anchored menu of related actions —\nthe web counterpart of the iOS `FloatingActionMenuButton` (which wraps the native\npull-down menu). It shares `FloatingActionButton`'s chrome and anchoring but is a\nseparate component: the interaction contract differs (`aria-haspopup` trigger,\nopen/close state, no loading), which is the FAB/SpeedDial boundary every major\ndesign system draws." }, { "heading": "Anchored menu", "body": "The popover opens upward from the trigger, right-aligned, inside the same\ncontaining block — so it rides screen transitions with the FAB. Rows reuse the\nshared `Menu` contract (`MenuItem`: leading icon, `destructive`, `disabled`) and\ntheir haptics. Tapping outside or selecting a row closes it; selection closes\nbefore `onSelect` fires." } ], "usage": [ { "variant": "FloatingActionButton", "use": "The screen has ONE primary creation action — press runs it directly, with optional loading.", "avoid": "Cramming multiple actions behind a single tap." }, { "variant": "FloatingActionMenuButton", "use": "The screen has 2–5 closely related creation actions (compose via email / text / call). Press reveals them without leaving the screen.", "avoid": "A single action (use FloatingActionButton); long or data-driven pick lists (use Select or BottomSheet + Menu)." } ], "examples": [], "source": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.mdx", "status": "local-preview", "note": "Guidance is read from local documentation, originally imported from the frozen source. Platform assertions in guidance are not parity verification." } ## Contract and public API ```json { "props": [ { "name": "icon", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "Glyph rendered in the circle, usually an `Icon`.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 14 } }, { "name": "ariaLabel", "type": "string", "declared_type": "string", "required": true, "description": "Accessible name for the trigger; also labels the menu.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 16 } }, { "name": "items", "type": "MenuItem[]", "declared_type": "MenuItem[]", "required": true, "description": "Rows in the anchored menu (the shared `Menu` contract).", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 18 } }, { "name": "onSelect", "type": "(value: string) => void", "declared_type": "(value: string) => void", "required": true, "description": "Called with the pressed item's value; the menu closes first.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 20 } }, { "name": "hidden", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Removes the trigger (e.g. while a sheet is open).", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 22 }, "values": [ false, true ], "values_complete": true }, { "name": "defaultOpen", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Renders the menu open on mount.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 24 }, "values": [ false, true ], "values_complete": true }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for trigger presses. Defaults to `true` (`light`).", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 26 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Class hook on the anchor wrapper, e.g. lifting `bottom` above a tab bar.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 28 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "Inline style override on the anchor wrapper.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 30 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. The popover gets `${testId}-menu`.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 32 } } ], "prop_shapes": {}, "api": { "method": "typescript-type-checker", "typescript_version": "5.9.3", "public_export": "FloatingActionMenuButton", "public_path": "FloatingActionMenuButton", "import_path": "@cloakedinc/design-system", "root_kind": "component", "entrypoints": [ { "name": "FloatingActionMenuButton", "signature": 1, "visibility": "public", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 44 }, "props_type": "FloatingActionMenuButtonProps", "props": [ { "name": "icon", "type": "React.ReactNode", "declared_type": "React.ReactNode", "required": true, "description": "Glyph rendered in the circle, usually an `Icon`.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 14 } }, { "name": "ariaLabel", "type": "string", "declared_type": "string", "required": true, "description": "Accessible name for the trigger; also labels the menu.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 16 } }, { "name": "items", "type": "MenuItem[]", "declared_type": "MenuItem[]", "required": true, "description": "Rows in the anchored menu (the shared `Menu` contract).", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 18 } }, { "name": "onSelect", "type": "(value: string) => void", "declared_type": "(value: string) => void", "required": true, "description": "Called with the pressed item's value; the menu closes first.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 20 } }, { "name": "hidden", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Removes the trigger (e.g. while a sheet is open).", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 22 }, "values": [ false, true ], "values_complete": true }, { "name": "defaultOpen", "type": "boolean | undefined", "declared_type": "boolean", "required": false, "description": "Renders the menu open on mount.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 24 }, "values": [ false, true ], "values_complete": true }, { "name": "haptic", "type": "HapticFeedback | undefined", "declared_type": "HapticFeedback", "required": false, "description": "Haptic feedback for trigger presses. Defaults to `true` (`light`).", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 26 }, "values": [ "error", "heavy", "light", "medium", "selection", "success", "warning", false, true ], "values_complete": true, "default": "true", "default_kind": "source-expression" }, { "name": "className", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Class hook on the anchor wrapper, e.g. lifting `bottom` above a tab bar.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 28 } }, { "name": "style", "type": "React.CSSProperties | undefined", "declared_type": "React.CSSProperties", "required": false, "description": "Inline style override on the anchor wrapper.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 30 } }, { "name": "testId", "type": "string | undefined", "declared_type": "string", "required": false, "description": "Optional test selector. The popover gets `${testId}-menu`.", "source": { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 32 } } ], "branches": [], "constraints": [], "extraction_status": "extracted" } ], "type_sources": [ { "path": "packages/design-system/src/components/controls/Menu/Menu.tsx", "line": 15, "name": "MenuItem", "code": "export interface MenuItem {\n /** Emitted by `onSelect`, matched against `MenuProps.value`, and used as the React key. */\n value: string;\n /** Primary row text. A node, but keep it inline: it renders inside a `Text`. */\n label: React.ReactNode;\n /** Optional leading content, usually an `Icon`. */\n leading?: React.ReactNode;\n /** Second line under the label, for spelling out an action's consequence. */\n description?: React.ReactNode;\n /** Blocks the press and dims the row, so `onSelect` never fires for it. */\n disabled?: boolean;\n /** Applies danger text treatment for destructive actions. */\n destructive?: boolean;\n /** Optional test selector. Falls back to `${testId}-${value}`. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.tsx", "line": 12, "name": "FloatingActionMenuButtonProps", "code": "export interface FloatingActionMenuButtonProps {\n /** Glyph rendered in the circle, usually an `Icon`. */\n icon: React.ReactNode;\n /** Accessible name for the trigger; also labels the menu. */\n ariaLabel: string;\n /** Rows in the anchored menu (the shared `Menu` contract). */\n items: MenuItem[];\n /** Called with the pressed item's value; the menu closes first. */\n onSelect: (value: string) => void;\n /** Removes the trigger (e.g. while a sheet is open). */\n hidden?: boolean;\n /** Renders the menu open on mount. */\n defaultOpen?: boolean;\n /** Haptic feedback for trigger presses. Defaults to `true` (`light`). */\n haptic?: HapticFeedback;\n /** Class hook on the anchor wrapper, e.g. lifting `bottom` above a tab bar. */\n className?: string;\n /** Inline style override on the anchor wrapper. */\n style?: React.CSSProperties;\n /** Optional test selector. The popover gets `${testId}-menu`. */\n testId?: string;\n}" }, { "path": "packages/design-system/src/tokens/CdsHaptic.ts", "line": 6, "name": "HapticFeedback", "code": "export type HapticFeedback = boolean | HapticType;" }, { "path": "packages/design-system/src/tokens/HapticType.ts", "line": 2, "name": "HapticType", "code": "export type HapticType = 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'selection';" } ], "defaults_policy": "Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source." }, "spec": { "$schema": "../../../specs/component-spec.schema.json", "identity": { "name": "FloatingActionMenuButton", "status": "preview", "version": "1.0.0", "summary": "A floating-action circle whose press opens an anchored menu of related actions above it." }, "parts": [ { "id": "trigger", "label": "Trigger", "description": "The FloatingActionButton chrome carrying menu-trigger semantics (aria-haspopup, aria-expanded)." }, { "id": "popover", "label": "Popover", "description": "The anchored surface above the trigger holding the menu rows." }, { "id": "rows", "label": "Menu rows", "description": "Shared Menu rows with leading icons, destructive and disabled treatments." }, { "id": "dismiss-layer", "label": "Dismiss layer", "description": "Invisible full-screen layer that closes the menu on an outside tap." } ], "allowedDesignChoices": { "variants": { "default": { "label": "Default", "description": "Single treatment; there is no variant axis." } }, "sizes": { "default": { "label": "Default", "description": "Fixed 48px trigger; the popover sizes to its rows." } } }, "variants": [ { "id": "default", "label": "Default", "description": "Glass trigger circle with an anchored menu opening upward, right-aligned.", "platforms": [ "ios", "web" ] } ], "sizes": [ { "id": "default", "label": "Default", "description": "48px trigger matching FloatingActionButton; popover height follows content." } ], "measurements": [ { "id": "trigger-diameter", "label": "Trigger diameter", "kind": "exact", "token": "--cds-size-48", "value": 48, "unit": "px", "appliesTo": [ "trigger" ] }, { "id": "popover-gap", "label": "Gap between trigger and popover", "kind": "exact", "token": "--cds-space-8", "value": 8, "unit": "px", "appliesTo": [ "popover" ] }, { "id": "popover-min-width", "label": "Popover minimum width", "kind": "exact", "token": "--cds-size-240", "value": 240, "unit": "px", "appliesTo": [ "popover" ] }, { "id": "popover-radius", "label": "Popover corner radius", "kind": "exact", "token": "--cds-radius-lg", "value": 20, "unit": "px", "appliesTo": [ "popover" ] } ], "layout": { "alignment": "The popover is right-aligned to the trigger and opens upward with a bottom-right transform origin.", "flow": "A fixed anchor wrapper owns positioning and hosts the trigger, popover, and dismiss layer, so a positioning override moves the whole assembly.", "notes": [ "Not portaled, matching FloatingActionButton: a transformed screen container contains all three layers so the assembly rides screen transitions.", "The popover z-tier sits just above the trigger and far below the BottomSheet/Dialog overlay tier." ] }, "typographyAndColor": { "typography": [], "colors": [ { "label": "Trigger container", "description": "Shares FloatingActionButton's frosted-glass fill.", "token": "--cds-fab-container" }, { "label": "Popover surface", "description": "Frosted like the trigger, with the heavy menu-material blur for row legibility.", "token": "--cds-fab-container" } ] }, "states": [ { "id": "closed", "label": "Closed", "description": "Only the trigger is visible; aria-expanded is false." }, { "id": "open", "label": "Open", "description": "The popover scales in above the trigger; an outside tap or row selection closes it." }, { "id": "hidden", "label": "Hidden", "description": "The hidden prop removes the whole assembly." } ], "behavior": [ { "label": "Toggle", "description": "Pressing the trigger toggles the menu; it never runs an action directly and has no loading state." }, { "label": "Select", "description": "Row selection closes the menu, then calls onSelect with the row value." }, { "label": "Dismiss", "description": "Tapping anywhere outside the popover closes it without selecting." } ], "accessibility": [ { "label": "Menu trigger semantics", "description": "The trigger exposes aria-haspopup=menu and reflects open state via aria-expanded." }, { "label": "Menu semantics", "description": "Rows render through Menu, which provides role=menu and per-row accessible names." }, { "label": "Accessible name", "description": "ariaLabel is required and labels both the trigger and the menu." } ], "contentAdaptation": [ { "label": "Row count", "description": "Use 2-5 closely related actions; longer or data-driven lists belong in Select or a BottomSheet." } ], "motionHaptics": { "motion": [ { "label": "Open", "description": "The popover scales and fades in from its bottom-right anchor over the base duration; reduced-motion renders it instantly." }, { "label": "Close", "description": "Dismissal or selection scales and fades the popover out with the exit curve before unmounting." } ], "haptics": [ { "label": "Trigger and rows", "description": "The trigger fires a light haptic; rows fire their own through the shared Menu." } ] }, "platformDifferences": [ { "platforms": [ "web" ], "description": "iOS presents the native pull-down menu (glass, anchored by the system); web renders a private anchored popover styled with design-system surface tokens.", "rationale": "WKWebView content cannot invoke the native menu, so the web version approximates its anchoring and motion with the shared Menu rows." } ] }, "platforms": { "implemented": [ "web" ], "native": "Imported design guidance only; no native implementation or parity verification in this preview.", "react": { "implementation": "local", "status": "preview", "parity": "web-reference" }, "vue": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "swift": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" }, "kotlin": { "implementation": "absent", "parity": "not-verified", "status": "reference-only" } }, "tokens": [ { "name": "--cds-size-48", "light": "48px", "dark": "48px" }, { "name": "--cds-space-8", "light": "8px", "dark": "8px" }, { "name": "--cds-size-240", "light": "240px", "dark": "240px" }, { "name": "--cds-radius-lg", "light": "20px", "dark": "20px" }, { "name": "--cds-fab-container", "light": "#ffffff99", "dark": "#ffffff1a" } ], "review": { "local_status": "not-reviewed", "source_approval": null, "imported_spec_status": "approved", "spec_origin": "imported-adapted", "local_spec_source_status": "approved", "imported_source_revision": "f96f416e1c3bfbfaffcd155a88b87b18b8bb25f1", "note": "Inherited specification status is provenance, not approval of the current local implementation or extracted contract." }, "missing_facts": [ { "code": "human-review-pending", "detail": "This local preview has no recorded human design or engineering sign-off." }, { "code": "platform-parity-unverified", "detail": "Vue, Swift and Kotlin implementations are absent from this package; platform parity has not been verified." }, { "code": "figma-mapping-unverified", "detail": "No current component-level Figma node and immutable revision have been verified for this contract." } ] } ``` ## Visual states - [Playground](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionmenubutton--playground&viewMode=story) | export: Playground | source: packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.stories.tsx - [Open](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionmenubutton--open&viewMode=story) | export: Open | source: packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.stories.tsx - [Destructive Row](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionmenubutton--destructive-row&viewMode=story) | export: DestructiveRow | source: packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.stories.tsx - [Dark Theme](/storybook/iframe.html?id=cloaked-design-system-primitives-floatingactionmenubutton--dark-theme&viewMode=story) | export: DarkTheme | source: packages/design-system/src/components/primitives/FloatingActionMenuButton/FloatingActionMenuButton.stories.tsx Preview pending human sign-off. Source-derived APIs and successful checks do not certify accessibility, native parity or approval.