{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "ribbon", "type": "registry:ui", "title": "Ribbon", "description": "Fluent 2-styled, Office-like Ribbon — the kit's flagship composite, with two layouts from one tree. **single-line** (Word's 'Faixa de Opções de Linha Única') composes the kit Tabs, Toolbar (APG roving-tabindex), and the headless Overflow priority system so the lowest-priority commands drop into a '…' menu as the row shrinks; each RibbonItem renders two ways at once (an icon in the bar and an icon + full-label row in the menu, grouped by source group). **classic** (Word's two-row band) swaps Overflow for the headless GroupCollapse manager: as the ~96px band shrinks, whole groups collapse — highest collapsePriority first — to a dropdown button whose Popover flyout holds the group's same children, then the band falls back to horizontal scroll. New classic form parts RibbonLargeButton / RibbonRow / RibbonColumn compose group content; a `layouts` escape hatch on RibbonItem/RibbonGroup shows a command in only one layout. Controlled/uncontrolled tab selection plus a `collapsed` (tabs-only) axis; unknown `layout` values degrade to single-line. Custom overflowRender lets split buttons/combos supply their own menu form; focus follows a command into the '…' trigger (single-line) or its group's dropdown button (classic) when it overflows/collapses. The `layout` axis is controllable (`layout`/`defaultLayout`/`onLayoutChange`), as is `autoAdjust` (`autoAdjust`/`defaultAutoAdjust`/`onAutoAdjustChange`); the optional RibbonLayoutSwitcher reproduces Word's far-right display-options chevron (Clássica / Linha Única + Sempre mostrar / Apenas as guias / Ajustar automaticamente), pinned via RibbonTabList's `actions` slot.", "author": "graundtech ", "dependencies": [ "@base-ui/react", "@fluentui/react-icons" ], "registryDependencies": [ "https://fluent2-react-kit.graund.io/r/utils.json", "https://fluent2-react-kit.graund.io/r/tabs.json", "https://fluent2-react-kit.graund.io/r/toolbar.json", "https://fluent2-react-kit.graund.io/r/overflow.json", "https://fluent2-react-kit.graund.io/r/dropdown-menu.json", "https://fluent2-react-kit.graund.io/r/popover.json", "https://fluent2-react-kit.graund.io/r/ribbon-collapse.json" ], "files": [ { "path": "components/ui/ribbon.tsx", "type": "registry:ui", "target": "components/ui/ribbon.tsx", "content": "\"use client\";\n\nimport {\n Children,\n cloneElement,\n createContext,\n isValidElement,\n useCallback,\n useContext,\n useEffect,\n useId,\n useLayoutEffect,\n useMemo,\n useRef,\n useState,\n useSyncExternalStore,\n} from \"react\";\nimport type {\n ComponentProps,\n CSSProperties,\n ReactElement,\n ReactNode,\n Ref,\n} from \"react\";\n\nimport { cn } from \"@/lib/utils\";\nimport {\n DropdownMenu,\n DropdownMenuCheckboxItem,\n DropdownMenuContent,\n DropdownMenuGroup,\n DropdownMenuItem,\n DropdownMenuLabel,\n DropdownMenuRadioGroup,\n DropdownMenuRadioItem,\n DropdownMenuSeparator,\n DropdownMenuTrigger,\n} from \"./dropdown-menu\";\nimport {\n Overflow,\n OverflowDivider,\n OverflowItem,\n useIsOverflowGroupVisible,\n useIsOverflowItemVisible,\n useOverflowMenu,\n} from \"./overflow\";\nimport { Popover, PopoverContent, PopoverTrigger } from \"./popover\";\nimport {\n CollapseGroup,\n GroupCollapse,\n useGroupMode,\n useIsScrollMode,\n} from \"./ribbon-collapse\";\nimport type {\n CollapseGetGap,\n CollapseGetOverflowSize,\n CollapseGetSize,\n} from \"./ribbon-collapse\";\nimport { Tabs, TabsContent, TabsList, TabsTrigger } from \"./tabs\";\nimport { Toolbar, ToolbarButton, ToolbarSeparator } from \"./toolbar\";\n\n/**\n * Ribbon — the kit's flagship composite: an Office-style **single-line** Ribbon\n * (Word Online's \"Faixa de Opções de Linha Única\"). It composes three primitives\n * that already exist in the kit — `Tabs` (the guide strip), `Toolbar` (the\n * command row, APG roving-tabindex), and the headless `Overflow` priority system\n * (which drops the lowest-priority commands into a \"…\" menu as the row shrinks) —\n * and adds the **item model** that makes every command render two ways at once:\n * an icon control in the bar, and an icon + full-label row inside the overflow\n * menu, grouped under a header named after its source group. That dual\n * presentation is the behavioral heart captured live from Word Online in\n * `docs/design/ribbon-behavior-spec.md` (\"Single-line mode\").\n *\n * ## Licensing / provenance\n * Fluent 2 is a **visual/behavioral reference only** (conventions §0). No Fluent\n * UI source was consulted; the contract comes from the spec doc + kit tokens.\n *\n * ## Part family (shadcn compound style)\n * | Part | Renders over | Role |\n * | --------------------- | ----------------------- | ----------------------------------------------- |\n * | `Ribbon` | kit `Tabs` (Root) | root: tab + collapse state + context |\n * | `RibbonTabList` | `TabsList` | the guide strip |\n * | `RibbonTab` | `TabsTrigger` | one guide (stamps the id the row is labelled by)|\n * | `RibbonContent` | `TabsContent` | one tab's single-line command row (Overflow+Toolbar) |\n * | `RibbonGroup` | context + `OverflowDivider` | a logical command group + its trailing divider |\n * | `RibbonItem` | `OverflowItem` + registry | one command: bar-form child + menu-form metadata |\n * | `RibbonOverflowMenu` | `useOverflowMenu` + `DropdownMenu` | the \"…\" trigger + grouped menu (auto-rendered) |\n * | `RibbonSeparator` | `ToolbarSeparator` | a standalone divider outside a group |\n *\n * A consumer only writes `Ribbon` → `RibbonTabList`/`RibbonTab` +\n * `RibbonContent` → `RibbonGroup` → `RibbonItem`. `RibbonContent` wires the\n * `Overflow` provider, the measured `Toolbar`, the item registry, **and** the\n * `RibbonOverflowMenu` for you (it appends the trigger after your groups) — this\n * productizes exactly the wiring proven in `apps/demo/app/preview/overflow`.\n *\n * ## The dual-presentation item model\n * `RibbonItem` does two things:\n * 1. wraps its `children` (the bar-form control — a `ToolbarButton`, `Toggle`,\n * `SplitButton`, dropdown trigger, …) in an `OverflowItem`, so the shared\n * priority manager can hide it (via CSS `display:none`, never unmount) when\n * the row is too narrow; and\n * 2. registers `{ id, label, icon, groupId, groupLabel, overflowRender?, onSelect? }`\n * in a `RibbonContent`-scoped registry, so `RibbonOverflowMenu` can render the\n * **hidden** ones as menu rows. The default menu form is a `DropdownMenuItem`\n * (icon + `label`, firing `onSelect`); a complex control supplies its own via\n * `overflowRender` (e.g. a split button → a submenu, a combo → a labeled\n * field). The container decides the form from context, not the item's props —\n * exactly the spec's \"API implications\" §1.\n *\n * ## Two layouts, one tree (v2 — the classic band)\n * The SAME `RibbonGroup`/`RibbonItem` tree renders in both layouts; the form\n * parts adapt to the root `layout`. This is the v2-plan \"one tree, two layouts +\n * escape hatch\" decision.\n * - **`layout=\"single-line\"`** (default) — the v1 command row above: `Overflow`\n * priority manager + the \"…\" menu. Unchanged; the v1 e2e suite is its\n * regression guard.\n * - **`layout=\"classic\"`** — Word's two-row **classic band** (~96px content\n * area). `RibbonContent` swaps the `Overflow` row for a `GroupCollapse`\n * provider (the headless C1 group-collapse manager) wrapping the SAME\n * `Toolbar`, and each `RibbonGroup` renders its classic anatomy: a horizontal\n * cluster of controls over a centered muted group label, an optional\n * dialog-launcher (↘), and a trailing hairline. When the band can't fit,\n * whole groups collapse — highest `collapsePriority` first — to a single\n * dropdown button whose flyout (kit `Popover`) holds the group's SAME\n * children; when every group is collapsed and it still overflows, the band\n * reports `scrollMode` (C1 stamps `data-scroll-mode`; the scroll UI is C3).\n * There is **no \"…\" overflow menu** in classic — Word classic has none; its\n * fallback is scroll. **Unknown `layout` values degrade to single-line** so\n * forward-compat callers never break.\n *\n * ### Escape hatch — per-layout content (`layouts`)\n * Word genuinely shows different command sets per layout, so both `RibbonItem`\n * and `RibbonGroup` accept `layouts?: (\"single-line\" | \"classic\")[]`: when set\n * and the active layout isn't listed, the part renders nothing (and, in\n * single-line, does not register in the overflow/menu registry). Default: both.\n *\n * ### Collapsed-flyout children placement (design note)\n * A group's children are a single React subtree that lives in exactly ONE place\n * per mode: inside the expanded shell when the group is expanded, and inside the\n * `Popover` flyout when the group is collapsed (and the flyout is open). The two\n * form SHELLS both stay mounted for measurement (C1's model), but the children\n * are never double-rendered — the collapsed shell is a fixed icon+label+chevron\n * button whose size is independent of the children. Flipping mode therefore\n * **remounts** the children (they move between the band and the portal); ribbon\n * controls are stateless commands, so this is acceptable (v2-plan design risk).\n *\n * ## The other two API axes (mirroring Word's own switcher)\n * - **`collapsed`** — Word's \"Mostrar apenas as guias\" (tabs-only). A\n * controlled/uncontrolled pair (`collapsed` / `defaultCollapsed` /\n * `onCollapsedChange`): when collapsed, the command rows are hidden (via CSS,\n * not unmounted — see `RibbonContent`'s `keepMounted` note); activating **any**\n * tab un-collapses (Word's behavior). Applies to both layouts. **Divergence\n * from desktop Office:** desktop shows the active tab's ribbon as a temporary\n * *overlay flyout* on click while staying collapsed; v1 simply un-collapses\n * (no overlay), matching the simpler web model.\n * - **`autoAdjust`** — Word's \"Ajustar automaticamente\", the **classic** adaptive\n * resize toggle. `true` (default) is the staged group collapse then scroll\n * fallback; `false` skips group collapse entirely — every group stays expanded\n * and the band goes **straight to the horizontal-scroll UI** the moment it\n * overflows (implemented by not mounting the `GroupCollapse` provider and\n * letting the always-scrollable band's clip detection drive the edge arrows).\n * **Ignored in single-line** (Word only exposes it for classic; the single-line\n * row always adapts via `Overflow`).\n *\n * ## Classic fallbacks (C3)\n * - **Horizontal scroll** — when every group has collapsed and the band still\n * overflows (`useIsScrollMode()`), or always once `autoAdjust={false}`, the band\n * scrolls horizontally (programmatic; no native scrollbar — Word's model) with\n * `‹`/`›` edge arrow buttons that appear only when there is clipped content on\n * that side. The arrows are **pointer affordances** rendered as absolute\n * siblings *outside* the `Toolbar` (so Base UI's roving tabindex never owns\n * them) and taken out of the tab order (`tabIndex={-1}`); keyboard users move\n * through commands with the toolbar's roving focus and the browser scrolls the\n * focused item into view natively (the band is a real scroll container even\n * though its overflow is clipped). Programmatic scroll respects\n * `prefers-reduced-motion` (`behavior:\"auto\"` instead of `\"smooth\"`).\n * - **Tab-strip overflow** — the `RibbonTabList` reuses the v1 `Overflow`\n * machinery: each `RibbonTab` is an `OverflowItem` (its child is cloned, no\n * wrapper element, so `TabsList`'s roving + sliding indicator keep working) and\n * a `⌄` chevron menu lists the hidden (trailing) tabs; selecting one activates\n * it. The active tab is pinned dynamically so it can never fold. Applies to\n * **both** layouts (Word folds tabs in single-line too).\n *\n * ## Accessibility contract\n * There is **no ARIA \"ribbon\" pattern** — the composite is APG **Tabs** (from kit\n * `Tabs`) over APG **Toolbar** (from kit `Toolbar`). Each command row is a\n * `role=\"toolbar\"` labelled by its owning tab via `aria-labelledby` (reusing the\n * tab's own id — the same id Base UI's `Tabs` already links the panel to, so no\n * new wiring is invented). The \"…\" trigger is an icon-only button and carries an\n * `aria-label` announcing the overflow count. Overflowed items are `aria-hidden`\n * in the row (the `Overflow` module sets this) and instead offered in the menu.\n *\n * ### Focus preservation on overflow (phase-2 handoff)\n * When the item holding focus is pushed into the \"…\" menu (its element becomes\n * `display:none`), focus would otherwise fall to `document.body`. `RibbonItem`\n * detects that transition — it snapshots, *during the render that flips it\n * hidden* (pre-commit DOM, so focus is still on it), whether it holds focus — and\n * on the following effect moves focus to the \"…\" trigger (which has, in the same\n * commit, become visible because something overflowed).\n *\n * ## Styling\n * Token-driven only (conventions §3). The row is a transparent surface on\n * `--background` with a `border-b` hairline — Word's ribbon band reads as chrome.\n * No new tokens. The Fluent tab underline comes from kit `Tabs`, untouched.\n *\n * ## `\"use client\"` — required\n * Owns React context, the item registry store, refs, and focus effects; also\n * pulls in client-only primitives (`Tabs`, `DropdownMenu`, `Overflow`).\n */\n\n/* -------------------------------------------------------------------------- */\n/* Small ref helpers (local, no external dep — mirrors overflow.tsx) */\n/* -------------------------------------------------------------------------- */\n\ntype PossibleRef = Ref | undefined;\n\nfunction assignRef(ref: PossibleRef, value: T | null) {\n if (typeof ref === \"function\") ref(value);\n else if (ref) (ref as { current: T | null }).current = value;\n}\n\nfunction mergeRefs(...refs: PossibleRef[]) {\n return (value: T | null) => {\n for (const ref of refs) assignRef(ref, value);\n };\n}\n\n/** In React 19 a JSX `ref` lives on `element.props.ref`. */\nfunction getChildRef(element: ReactElement): PossibleRef {\n return (element.props as { ref?: PossibleRef }).ref;\n}\n\n// useLayoutEffect on the client, useEffect on the server (avoids the SSR warning\n// — the same isomorphic pattern overflow.tsx uses).\nconst useLayoutEffectSafe =\n typeof document !== \"undefined\" ? useLayoutEffect : useEffect;\n\n/* -------------------------------------------------------------------------- */\n/* Item registry (RibbonContent-scoped store for the overflow menu) */\n/* -------------------------------------------------------------------------- */\n\n/** Metadata a `RibbonItem` publishes so the overflow menu can render it. */\nexport interface RibbonItemMeta {\n id: string;\n label: string;\n icon?: ReactNode;\n groupId?: string;\n groupLabel?: string;\n /** Custom menu form (split-button submenu, combo field, …). */\n overflowRender?: () => ReactNode;\n /** Fired by the *default* menu form (a `DropdownMenuItem`). */\n onSelect?: () => void;\n}\n\ninterface RibbonRegistry {\n register: (meta: RibbonItemMeta) => void;\n unregister: (id: string) => void;\n subscribe: (listener: () => void) => () => void;\n /** Registered items in source (registration) order. */\n getSnapshot: () => RibbonItemMeta[];\n getServerSnapshot: () => RibbonItemMeta[];\n}\n\nconst EMPTY_META: RibbonItemMeta[] = [];\n\nfunction createRibbonRegistry(): RibbonRegistry {\n const items = new Map();\n const listeners = new Set<() => void>();\n let snapshot: RibbonItemMeta[] = EMPTY_META;\n\n function rebuild() {\n // New array identity only on membership change → useSyncExternalStore stable.\n snapshot = [...items.values()];\n for (const listener of listeners) listener();\n }\n\n return {\n register(meta) {\n const existing = items.get(meta.id);\n if (existing) {\n // Same membership: mutate in place so an open menu reads fresh\n // icon/label/closures on its next natural render, WITHOUT a new snapshot\n // identity (which would loop, since icon/overflowRender/onSelect get new\n // identities every parent render).\n Object.assign(existing, meta);\n return;\n }\n items.set(meta.id, { ...meta });\n rebuild();\n },\n unregister(id) {\n if (items.delete(id)) rebuild();\n },\n subscribe(listener) {\n listeners.add(listener);\n return () => listeners.delete(listener);\n },\n getSnapshot() {\n return snapshot;\n },\n getServerSnapshot() {\n return EMPTY_META;\n },\n };\n}\n\n/* -------------------------------------------------------------------------- */\n/* Contexts */\n/* -------------------------------------------------------------------------- */\n\ntype RibbonLayout = \"single-line\" | \"classic\";\n\n/** Normalise any layout input to a known `RibbonLayout` (unknown → single-line). */\nfunction normalizeLayout(value: RibbonLayout | (string & {})): RibbonLayout {\n return value === \"classic\" ? \"classic\" : \"single-line\";\n}\n\ninterface RibbonContextValue {\n layout: RibbonLayout;\n collapsed: boolean;\n /**\n * Adaptive resize in **classic** (Word's \"Ajustar automaticamente\"). `true`\n * (default) = staged group collapse then scroll; `false` = no collapse,\n * straight to the scroll UI when the band overflows. Ignored in single-line.\n */\n autoAdjust: boolean;\n /** The currently-selected tab value (so `RibbonTab` can pin the active tab). */\n activeValue?: string;\n /** Activate a tab by value (used by the tab-strip overflow menu); un-collapses. */\n selectValue: (value: string) => void;\n /** Un-collapse when a tab is activated (Word behavior). */\n onTabActivate: () => void;\n /** Deterministic tab-element id for a value; the row is labelled by it. */\n tabId: (value: unknown) => string;\n /** Set the layout (used by `RibbonLayoutSwitcher`; honours controlled `layout`). */\n setLayout: (layout: RibbonLayout) => void;\n /** Set the tabs-only axis (used by `RibbonLayoutSwitcher`; honours controlled `collapsed`). */\n setCollapsed: (collapsed: boolean) => void;\n /** Set the classic adaptive-resize axis (used by `RibbonLayoutSwitcher`; honours controlled `autoAdjust`). */\n setAutoAdjust: (autoAdjust: boolean) => void;\n}\n\nconst RibbonContext = createContext(null);\n\nfunction useRibbonContext(): RibbonContextValue {\n const ctx = useContext(RibbonContext);\n if (!ctx) {\n throw new Error(\"Ribbon parts must be rendered inside a .\");\n }\n return ctx;\n}\n\ninterface RibbonContentContextValue {\n registry: RibbonRegistry;\n /** Set by `RibbonOverflowMenu`; read by `RibbonItem`'s focus effect. */\n overflowTriggerRef: { current: HTMLElement | null };\n}\n\nconst RibbonContentContext = createContext(\n null\n);\n\nfunction useRibbonContentContext(): RibbonContentContextValue {\n const ctx = useContext(RibbonContentContext);\n if (!ctx) {\n throw new Error(\n \"RibbonGroup / RibbonItem / RibbonOverflowMenu must be inside a .\"\n );\n }\n return ctx;\n}\n\ninterface RibbonGroupContextValue {\n groupId?: string;\n groupLabel?: string;\n}\n\nconst RibbonGroupContext = createContext({});\n\n/**\n * `RibbonTabList`-scoped registry, mirroring the `RibbonContent` item registry:\n * each `RibbonTab` publishes `{ id: value, label, icon }` so the tab-strip\n * overflow menu can list the tabs that folded behind its chevron.\n */\ninterface RibbonTabListContextValue {\n registry: RibbonRegistry;\n}\n\nconst RibbonTabListContext = createContext(\n null\n);\n\n/* -------------------------------------------------------------------------- */\n/* Controlled/uncontrolled helper */\n/* -------------------------------------------------------------------------- */\n\nfunction useControllableState(\n controlled: T | undefined,\n defaultValue: T,\n onChange?: (value: T) => void\n): [T, (value: T) => void] {\n const [uncontrolled, setUncontrolled] = useState(defaultValue);\n const isControlled = controlled !== undefined;\n const value = isControlled ? controlled : uncontrolled;\n const setValue = useCallback(\n (next: T) => {\n if (!isControlled) setUncontrolled(next);\n onChange?.(next);\n },\n [isControlled, onChange]\n );\n return [value, setValue];\n}\n\n/* -------------------------------------------------------------------------- */\n/* Ribbon (root) */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonProps\n extends Omit, \"value\" | \"defaultValue\"> {\n /**\n * `\"single-line\"` or `\"classic\"` (Word's two-row band) — **controlled**. Unknown\n * values degrade to single-line. Pair with `onLayoutChange` for a controlled\n * layout; omit it and use `defaultLayout` for the uncontrolled form.\n */\n layout?: RibbonLayout | (string & {});\n /** Initial layout (uncontrolled). Default `\"single-line\"`. Unknown values degrade to single-line. */\n defaultLayout?: RibbonLayout | (string & {});\n /** Called when the layout changes (e.g. via `RibbonLayoutSwitcher`). */\n onLayoutChange?: (layout: RibbonLayout) => void;\n /** Selected tab value (controlled). */\n value?: string;\n /** Initially-selected tab value (uncontrolled). */\n defaultValue?: string;\n /** Tabs-only \"Mostrar apenas as guias\" mode (controlled). */\n collapsed?: boolean;\n /** Initial tabs-only state (uncontrolled). */\n defaultCollapsed?: boolean;\n /** Called when the collapsed state changes. */\n onCollapsedChange?: (collapsed: boolean) => void;\n /**\n * **classic only** (Word's \"Ajustar automaticamente\") — **controlled**. `true` =\n * staged group collapse then scroll; `false` = no collapse, straight to the\n * scroll UI when the band overflows. Accepted but ignored in single-line. Pair\n * with `onAutoAdjustChange`, or use `defaultAutoAdjust` for the uncontrolled form.\n */\n autoAdjust?: boolean;\n /** Initial classic adaptive-resize state (uncontrolled). Default `true`. */\n defaultAutoAdjust?: boolean;\n /** Called when the `autoAdjust` axis changes (e.g. via `RibbonLayoutSwitcher`). */\n onAutoAdjustChange?: (autoAdjust: boolean) => void;\n}\n\n/**\n * Ribbon (root) — wraps kit `Tabs` and owns the two state axes (selected tab +\n * collapsed). Provides `RibbonContext`. Stamps `data-slot=\"ribbon\"`,\n * `data-layout`, and `data-collapsed`.\n */\nfunction Ribbon({\n className,\n layout,\n defaultLayout = \"single-line\",\n onLayoutChange,\n value,\n defaultValue,\n onValueChange,\n collapsed,\n defaultCollapsed = false,\n onCollapsedChange,\n autoAdjust,\n defaultAutoAdjust = true,\n onAutoAdjustChange,\n children,\n ...props\n}: RibbonProps) {\n const baseId = useId();\n\n // Controllable `layout`, mirroring `collapsed`. Unknown values are normalised\n // to single-line at the boundary (both the controlled prop and the default), so\n // the resolved layout — and the value passed to `onLayoutChange` — is always a\n // clean `RibbonLayout`, and a forward-compat caller never breaks.\n const [resolvedLayout, setLayout] = useControllableState(\n layout === undefined ? undefined : normalizeLayout(layout),\n normalizeLayout(defaultLayout),\n onLayoutChange\n );\n\n const [collapsedState, setCollapsedState] = useControllableState(\n collapsed,\n defaultCollapsed,\n onCollapsedChange\n );\n\n // Controllable `autoAdjust`, same pattern — so `RibbonLayoutSwitcher` can drive\n // it through the context while a controlled caller keeps ownership.\n const [autoAdjustState, setAutoAdjust] = useControllableState(\n autoAdjust,\n defaultAutoAdjust,\n onAutoAdjustChange\n );\n\n // Own the selected tab value (controllable) so the tab-strip overflow menu can\n // activate a folded tab and `RibbonTab` can pin the active one. External\n // `onValueChange` still fires with Base UI's original args (value, event).\n const [activeValue, setActiveValueInternal] = useControllableState<\n string | undefined\n >(value, defaultValue);\n const handleValueChange = useCallback(\n (next: string, ...rest: unknown[]) => {\n setActiveValueInternal(next);\n (onValueChange as ((v: string, ...r: unknown[]) => void) | undefined)?.(\n next,\n ...rest\n );\n },\n [setActiveValueInternal, onValueChange]\n );\n\n const tabId = useCallback(\n (v: unknown) => `${baseId}-tab-${String(v)}`,\n [baseId]\n );\n\n const onTabActivate = useCallback(() => {\n // Activating any tab exits tabs-only mode (Word behavior).\n setCollapsedState(false);\n }, [setCollapsedState]);\n\n const selectValue = useCallback(\n (next: string) => {\n handleValueChange(next);\n setCollapsedState(false);\n },\n [handleValueChange, setCollapsedState]\n );\n\n const ctx = useMemo(\n () => ({\n layout: resolvedLayout,\n collapsed: collapsedState,\n autoAdjust: autoAdjustState,\n activeValue,\n selectValue,\n onTabActivate,\n tabId,\n setLayout,\n setCollapsed: setCollapsedState,\n setAutoAdjust,\n }),\n [\n resolvedLayout,\n collapsedState,\n autoAdjustState,\n activeValue,\n selectValue,\n onTabActivate,\n tabId,\n setLayout,\n setCollapsedState,\n setAutoAdjust,\n ]\n );\n\n return (\n \n \n {children}\n \n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonTabList / RibbonTab */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonTabListProps extends ComponentProps {\n /**\n * **Extra** slack subtracted from the measured strip width, on top of the\n * `Overflow` manager's accurate accounting (tabs + flex gaps + the `⌄` trigger\n * are measured). Default `0`.\n */\n padding?: number;\n /**\n * Injectable measurement fn forwarded to the tab-strip `Overflow`. Default\n * reads `offsetWidth`. Escape hatch for tests/SSR — you rarely set this.\n */\n getSize?: ComponentProps[\"getSize\"];\n /**\n * Content pinned to the **far right** of the tab strip — Word's home for the\n * `RibbonLayoutSwitcher` chevron (validation finding #10). Rendered as a sibling\n * *outside* both the `role=\"tablist\"` (so a non-tab control never trips axe's\n * `aria-required-children`) **and** the tab-strip `Overflow` budget (so the\n * switcher never folds and the trailing tabs overflow *before* reaching it, just\n * like Word). Pass `` here, or any consumer affordance.\n */\n actions?: ReactNode;\n}\n\n/**\n * RibbonTabList — the guide strip. Composes kit `TabsList` (the Fluent sliding\n * underline is Figma-validated there) and wires the v1 `Overflow` machinery so\n * that when the strip is too narrow the **trailing** tabs fold behind a `⌄`\n * chevron menu (Word's tab-strip overflow, captured live at ~680px). The active\n * tab is pinned (see `RibbonTab`) so it can never fold. Stamps\n * `data-slot=\"ribbon-tab-list\"`.\n *\n * ### Far-right `actions` (the layout switcher's home)\n * The optional `actions` slot renders far-right, *outside* the `Overflow` viewport\n * so it is never part of the tab-strip budget — the tabs overflow into the `⌄`\n * menu before they'd ever collide with it (Word's pinned switcher position). The\n * `Overflow` viewport is `flex-1 min-w-0`, so `actions` genuinely reserves its\n * width from the strip. Placement decision (see the file doc comment / the\n * `RibbonLayoutSwitcher` note): the switcher is composable either here or\n * standalone; here mirrors Word.\n */\nfunction RibbonTabList({\n className,\n children,\n padding = 0,\n getSize,\n actions,\n ...props\n}: RibbonTabListProps) {\n const [registry] = useState(() => createRibbonRegistry());\n const tabListCtx = useMemo(\n () => ({ registry }),\n [registry]\n );\n return (\n \n
\n {/* The Overflow container is a flex viewport wrapping the TabsList and the\n `⌄` trigger. The trigger is a SIBLING of the tablist, never a child of\n it: a non-tab button inside `role=\"tablist\"` fails axe's\n `aria-required-children` (tablists may contain only tabs). The tabs\n stay inside TabsList, so its roving tabindex and sliding indicator are\n untouched. `flex-1 min-w-0` leaves room for the far-right `actions`. */}\n \n \n \n {children}\n \n \n
\n \n {actions ? (\n \n {actions}\n \n ) : null}\n \n \n );\n}\n\nexport interface RibbonTabProps extends ComponentProps {\n value: string;\n /**\n * Menu-form text for the tab-strip overflow menu when this tab folds. Defaults\n * to `children` when it is a string, else `value`.\n */\n label?: string;\n /** Icon shown beside the label in the tab-strip overflow menu. */\n icon?: ReactNode;\n}\n\n/**\n * RibbonTab — one guide. Composes kit `TabsTrigger` and stamps the deterministic\n * `id` its command row is labelled by (`aria-labelledby`). Clicking it (mouse or\n * keyboard) un-collapses a tabs-only ribbon, even when it is already the active\n * tab (Word behavior) — hence the un-collapse rides `onClick`, not just tab\n * selection.\n *\n * For tab-strip overflow it is wrapped in an `OverflowItem` (the child is cloned\n * — no wrapper element — so `TabsList`'s roving tabindex and the sliding\n * indicator keep working) and registered in the tab-list registry so the `⌄`\n * menu can offer it while it is folded. It is **pinned while it is the active\n * tab** (`pinned={value === activeValue}`) so the active tab can never fold; the\n * pinned flip re-registers with the `Overflow` manager, which re-ranks, so a just\n * -activated (previously folded) tab immediately becomes visible.\n *\n * `data-slot=\"ribbon-tab\"` is applied **after** the spread so it survives the\n * `OverflowItem` clone (which would otherwise stamp `overflow-item`).\n */\nfunction RibbonTab({\n className,\n value,\n id,\n label,\n icon,\n children,\n onClick,\n ...props\n}: RibbonTabProps) {\n const { tabId, onTabActivate, activeValue } = useRibbonContext();\n const tabListCtx = useContext(RibbonTabListContext);\n const menuLabel =\n label ?? (typeof children === \"string\" ? children : String(value));\n\n // Publish to the tab-list registry so the overflow menu can render this tab\n // while it is folded (mutates in place for an existing id — no snapshot churn).\n useLayoutEffectSafe(() => {\n tabListCtx?.registry.register({ id: value, label: menuLabel, icon });\n });\n useLayoutEffectSafe(() => {\n return () => tabListCtx?.registry.unregister(value);\n }, [tabListCtx, value]);\n\n const trigger = (\n {\n onTabActivate();\n onClick?.(event);\n }}\n // h-9 (36px): Word's ribbon guide strip is compact (~36px), unlike the\n // kit Tabs default 44px (Figma-validated for standalone use) — see\n // docs/design/ribbon-validation.md finding #1.\n className={cn(\"h-9\", className)}\n {...props}\n >\n {children}\n \n );\n\n // Outside a tab-list registry (defensive) there is no overflow wiring.\n if (!tabListCtx) return trigger;\n\n return (\n \n {trigger}\n \n );\n}\n\n/**\n * Inner tab trigger. `OverflowItem` clones its child and injects\n * `data-slot=\"overflow-item\"`; this wrapper re-applies `data-slot=\"ribbon-tab\"`\n * **after** the spread so the tab keeps its public slot (the overflow wiring —\n * ref/style/`aria-hidden`/`data-overflowing` — still flows through the spread).\n */\nfunction RibbonTabTrigger(props: ComponentProps) {\n return ;\n}\n\nfunction useRibbonTabListContext(): RibbonTabListContextValue {\n const ctx = useContext(RibbonTabListContext);\n if (!ctx) {\n throw new Error(\"RibbonTab overflow parts must be inside a .\");\n }\n return ctx;\n}\n\n/**\n * RibbonTabOverflowMenu — the `⌄` chevron + menu for folded tabs. Rendered\n * automatically by `RibbonTabList` (you don't place it), as the last child of the\n * `TabsList` so it stays inside the tab-strip `Overflow` context and its width is\n * reserved from the budget (`useOverflowMenu`). It is kept measurable-but-hidden\n * (out of flow + `visibility:hidden`) until a tab folds, then shows at the strip's\n * end. The menu lists only the **hidden** tabs (source order); choosing one\n * activates it via the ribbon context (which also un-collapses a tabs-only\n * ribbon). It is a real keyboard-reachable button (the only route to folded tabs).\n */\nfunction RibbonTabOverflowMenu() {\n const { registry } = useRibbonTabListContext();\n const { ref, isOverflowing, overflowCount } =\n useOverflowMenu();\n\n const tabs = useSyncExternalStore(\n registry.subscribe,\n registry.getSnapshot,\n registry.getServerSnapshot\n );\n\n return (\n \n \n \n \n }\n />\n \n {tabs.map((tab) => (\n \n ))}\n \n \n );\n}\n\n/** One folded tab, rendered only while it is hidden from the strip. */\nfunction RibbonHiddenTabRow({ meta }: { meta: RibbonItemMeta }) {\n const { selectValue } = useRibbonContext();\n const visible = useIsOverflowItemVisible(meta.id);\n if (visible) return null;\n return (\n selectValue(meta.id)}>\n {meta.icon}\n {meta.label}\n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonContent (the command row) */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonContentProps\n extends Omit, \"value\"> {\n value: string;\n /**\n * **Extra** slack subtracted from the measured row width, on top of the\n * `Overflow` manager's accurate accounting (item widths + group dividers +\n * flex gaps + the \"…\" trigger are all measured now — you no longer hand-tune\n * this to cover them). Default `0`.\n */\n padding?: number;\n /** Floor on non-pinned items kept in the bar (they clip rather than vanish). Default `1`. */\n minimumVisible?: number;\n /**\n * Injectable measurement fn. **single-line:** forwarded to `Overflow`;\n * **classic:** forwarded to `GroupCollapse` (its `axis` second arg is ignored\n * by an `(el) => number` fn). Default reads `offsetWidth`. Escape hatch for\n * tests/SSR where layout is unavailable — you almost never set this in app code.\n */\n getSize?: ComponentProps[\"getSize\"];\n /**\n * **classic only.** Optimistic width used for a group's collapsed dropdown\n * button *before* it has been measured (a `display:none` form reports 0).\n * Kept low so the collapse loop only under-collapses and the C1 settle net\n * corrects (see `ribbon-collapse.tsx`). Default `64`.\n */\n collapsedEstimate?: number;\n /** **classic only.** Injectable flex-gap reader forwarded to `GroupCollapse`. */\n getGap?: CollapseGetGap;\n /** **classic only.** Injectable overflow-extent reader for the C1 settle net. */\n getOverflowSize?: CollapseGetOverflowSize;\n}\n\n/**\n * RibbonContent — one tab's command band.\n *\n * **single-line:** a kit `Toolbar` wrapped in `Overflow`, wired end-to-end, with\n * the `RibbonOverflowMenu` appended after your groups (~40px tall, thin group\n * dividers).\n *\n * **classic:** the SAME `Toolbar` wrapped in a `GroupCollapse` provider (the C1\n * group-collapse manager) — a ~96px two-row band, no \"…\" menu (Word classic has\n * none; the terminal fallback is scroll, which `GroupCollapse` flags by stamping\n * `data-scroll-mode` on the band — the scroll UI itself is C3). Both layouts take\n * the toolbar's accessible name from the owning tab (`aria-labelledby` → tab id).\n *\n * When the ribbon is `collapsed` (tabs-only), the band is hidden (via the\n * `hidden` attribute, not unmounted — the `keepMounted` note below).\n */\nfunction RibbonContent({\n className,\n value,\n padding = 0,\n minimumVisible = 1,\n getSize,\n collapsedEstimate = 64,\n getGap,\n getOverflowSize,\n children,\n ...props\n}: RibbonContentProps) {\n const { tabId, collapsed, layout, autoAdjust } = useRibbonContext();\n const isClassic = layout === \"classic\";\n const [registry] = useState(() => createRibbonRegistry());\n const overflowTriggerRef = useRef(null);\n\n const contentCtx = useMemo(\n () => ({ registry, overflowTriggerRef }),\n [registry]\n );\n\n // Mark the last RibbonGroup so it drops its trailing divider (no dangling\n // hairline before the \"…\"). Only injected when the consumer didn't set it.\n const preparedChildren = useMemo(() => {\n const array = Children.toArray(children);\n let lastGroupIndex = -1;\n array.forEach((child, index) => {\n if (isValidElement(child) && child.type === RibbonGroup) {\n lastGroupIndex = index;\n }\n });\n if (lastGroupIndex === -1) return children;\n return array.map((child, index) => {\n if (\n index === lastGroupIndex &&\n isValidElement(child) &&\n (child.props as RibbonGroupProps).withTrailingDivider === undefined\n ) {\n return cloneElement(child as ReactElement, {\n withTrailingDivider: false,\n });\n }\n return child;\n });\n }, [children]);\n\n return (\n \n \n {/*\n When collapsed, hide the band with the `hidden` attribute (real\n display:none, and — unlike a CSS class — honoured by jsdom / the\n accessibility tree) instead of unmounting, so the `Overflow` /\n `GroupCollapse` manager survives (see the `keepMounted` note above).\n */}\n \n \n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* Classic band + horizontal-scroll fallback (C3) */\n/* -------------------------------------------------------------------------- */\n\ninterface ClassicBandProps {\n value: string;\n tabId: (value: unknown) => string;\n autoAdjust: boolean;\n collapsedEstimate: number;\n padding: number;\n getSize?: CollapseGetSize;\n getGap?: CollapseGetGap;\n getOverflowSize?: CollapseGetOverflowSize;\n children: ReactNode;\n}\n\n/**\n * ClassicBand — the classic command band plus its C3 horizontal-scroll fallback.\n *\n * The `Toolbar` is always a real (clipped) horizontal scroll container. Two paths:\n * - **`autoAdjust` (default):** the band is wrapped in the `GroupCollapse`\n * provider (staged group collapse). A zero-DOM `ScrollModeReporter` inside the\n * band lifts `useIsScrollMode()` up here, so the edge arrows only arm once every\n * group has collapsed and the band *still* overflows (the terminal scroll\n * fallback) — no arrow flicker during collapse.\n * - **`autoAdjust={false}`:** no `GroupCollapse` at all — every group stays\n * expanded (see `RibbonGroupClassicStatic`) and the arrows are always armed, so\n * the band goes straight to scroll the moment it overflows.\n *\n * The `‹`/`›` buttons are absolute siblings of the `Toolbar` (outside it, so Base\n * UI's roving tabindex never owns them) inside a `relative` wrapper; each shows\n * only when there is clipped content on its side.\n */\nfunction ClassicBand({\n value,\n tabId,\n autoAdjust,\n collapsedEstimate,\n padding,\n getSize,\n getGap,\n getOverflowSize,\n children,\n}: ClassicBandProps) {\n const bandRef = useRef(null);\n const [scrollMode, setScrollMode] = useState(false);\n\n // Non-adaptive: no collapse, so arm the arrows whenever content clips.\n // Adaptive: arm only in the terminal scroll fallback (all groups collapsed).\n const armed = autoAdjust ? scrollMode : true;\n const { left, right } = useScrollAffordance(bandRef, armed);\n\n const toolbar = (\n }\n aria-labelledby={tabId(value)}\n className={cn(\n // ~96px two-row classic band: content area + group labels row.\n // `items-stretch` so each group form fills the band height and can pin\n // its label to the bottom; `overflow-hidden` clips residuals so the C1\n // accounting + settle net see a real overrun AND makes the band a\n // programmatic (scrollbar-less) horizontal scroll container — Word's model.\n \"relative h-24 w-full flex-nowrap items-stretch overflow-hidden\",\n \"border-b border-border bg-background px-1\"\n )}\n >\n {children}\n {autoAdjust ? : null}\n \n );\n\n return (\n
\n {autoAdjust ? (\n \n {toolbar}\n \n ) : (\n toolbar\n )}\n {left ? (\n scrollBandBy(bandRef.current, \"left\")}\n />\n ) : null}\n {right ? (\n scrollBandBy(bandRef.current, \"right\")}\n />\n ) : null}\n
\n );\n}\n\n/**\n * ScrollModeReporter — a zero-DOM child that lives inside the `GroupCollapse`\n * context, reads `useIsScrollMode()`, and lifts it to `ClassicBand`. Rendering it\n * inside the band (rather than reading scroll mode outside `GroupCollapse`, where\n * the context is unavailable) keeps the arrows fully driven by the C1 snapshot\n * while staying siblings of the `Toolbar`. Returns `null`, so it neither joins the\n * roving order nor contributes to measurement.\n */\nfunction ScrollModeReporter({\n onChange,\n}: {\n onChange: (scrollMode: boolean) => void;\n}) {\n const scrollMode = useIsScrollMode();\n useEffect(() => {\n onChange(scrollMode);\n }, [onChange, scrollMode]);\n return null;\n}\n\n/** Does the user prefer reduced motion? (SSR-safe.) */\nfunction prefersReducedMotion(): boolean {\n return (\n typeof window !== \"undefined\" &&\n typeof window.matchMedia === \"function\" &&\n window.matchMedia(\"(prefers-reduced-motion: reduce)\").matches\n );\n}\n\n/** Scroll a band by ~half its visible width toward `direction` (motion-aware). */\nfunction scrollBandBy(el: HTMLElement | null, direction: \"left\" | \"right\") {\n if (!el) return;\n const amount = Math.max(1, Math.floor(el.clientWidth / 2));\n el.scrollBy({\n left: direction === \"left\" ? -amount : amount,\n behavior: prefersReducedMotion() ? \"auto\" : \"smooth\",\n });\n}\n\n/**\n * useScrollAffordance — tracks whether the band has clipped content on each edge.\n * `left` when `scrollLeft > 0`; `right` when there is more scrollable extent past\n * the right edge (with a 1px tolerance). Re-measures on scroll, on container\n * resize (`ResizeObserver`), and whenever `enabled` flips. State only changes when\n * a boolean actually flips, so it settles without loops (showing/hiding an\n * absolute arrow never resizes the observed band).\n */\nfunction useScrollAffordance(\n ref: { current: HTMLElement | null },\n enabled: boolean\n): { left: boolean; right: boolean } {\n const [state, setState] = useState({ left: false, right: false });\n\n const measure = useCallback(() => {\n const el = ref.current;\n if (!el || !enabled) {\n setState((prev) =>\n prev.left || prev.right ? { left: false, right: false } : prev\n );\n return;\n }\n const left = el.scrollLeft > 0;\n const right = el.scrollWidth - el.clientWidth - el.scrollLeft > 1;\n setState((prev) =>\n prev.left === left && prev.right === right ? prev : { left, right }\n );\n }, [ref, enabled]);\n\n useLayoutEffectSafe(() => {\n measure();\n const el = ref.current;\n if (!el) return;\n el.addEventListener(\"scroll\", measure, { passive: true });\n let observer: ResizeObserver | undefined;\n if (typeof ResizeObserver !== \"undefined\") {\n observer = new ResizeObserver(() => measure());\n observer.observe(el);\n }\n return () => {\n el.removeEventListener(\"scroll\", measure);\n observer?.disconnect();\n };\n }, [measure]);\n\n return state;\n}\n\n/** Left/right chevron glyph for the scroll arrows (inline SVG, breadcrumb style). */\nfunction ScrollChevron({ direction }: { direction: \"left\" | \"right\" }) {\n return (\n \n \n \n );\n}\n\n/**\n * ClassicScrollButton — one edge arrow. A real `\n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonGroup */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonGroupProps extends ComponentProps<\"div\"> {\n /** Stable group id; inherited by the group's items and used for its divider. */\n groupId: string;\n /** Human label — the overflow section header (single-line) / the centered muted band label + collapsed-button name (classic). */\n label: string;\n /** Render the trailing divider (auto-suppressed on the last group). Default `true`. */\n withTrailingDivider?: boolean;\n /**\n * **classic only.** Higher collapses FIRST as the band shrinks (Word:\n * Parágrafo before Fonte). Governs classic collapse order; **ignored in\n * single-line** (there `RibbonItem.priority` rules). Default `0`.\n */\n collapsePriority?: number;\n /** **classic only.** Icon shown on the group's collapsed dropdown button. */\n icon?: ReactNode;\n /**\n * **classic only.** Dialog-launcher (↘) slot in the group's bottom-right. Pass\n * a custom node here (full control), OR pass `onLauncherClick` for the default\n * ↘ icon-button. `launcher` wins if both are set. Omit both for no launcher.\n */\n launcher?: ReactNode;\n /** **classic only.** Sugar for the default ↘ launcher button (see `launcher`). */\n onLauncherClick?: () => void;\n /**\n * Render this group only in the listed layouts (Word shows different command\n * sets per mode). When set and the active layout isn't listed, the group\n * renders nothing. Default: both layouts.\n */\n layouts?: RibbonLayout[];\n}\n\n/**\n * RibbonGroup — a logical command cluster. Adapts to the root `layout`:\n * - **single-line:** a context provider (no DOM box) that flattens its items +\n * an `OverflowDivider`-wrapped `RibbonSeparator` into the toolbar row.\n * - **classic:** a `CollapseGroup` (C1) rendering the group's two forms — the\n * expanded band anatomy and the collapsed dropdown button.\n *\n * The `layouts` escape hatch renders nothing (and, in single-line, registers\n * nothing) when the active layout isn't listed.\n */\nfunction RibbonGroup(props: RibbonGroupProps) {\n const { layout, autoAdjust } = useRibbonContext();\n if (props.layouts && !props.layouts.includes(layout)) return null;\n if (layout === \"classic\") {\n // `autoAdjust={false}` → no GroupCollapse provider is mounted, so the group\n // must NOT call `useGroupMode`/render a `CollapseGroup` (both need that\n // context). It renders its expanded form only; the band goes straight to\n // scroll when it overflows.\n return autoAdjust ? (\n \n ) : (\n \n );\n }\n return ;\n}\n\n/**\n * RibbonGroup (single-line) — the v1 behavior, unchanged. Provides\n * `groupId` + `label` to its `RibbonItem`s via context (so each item inherits\n * its group + section header), renders them, then an `OverflowDivider`-wrapped\n * `RibbonSeparator`. The divider hides itself only when the whole group is\n * overflowed (`useIsOverflowGroupVisible` → `\"hidden\"`), so no separator dangles.\n * Renders no DOM element of its own.\n */\nfunction RibbonGroupSingleLine({\n groupId,\n label,\n withTrailingDivider = true,\n children,\n}: RibbonGroupProps) {\n const ctx = useMemo(\n () => ({ groupId, groupLabel: label }),\n [groupId, label]\n );\n return (\n \n {children}\n {withTrailingDivider ? (\n \n \n \n ) : null}\n \n );\n}\n\n/** Down-chevron glyph — inline SVG (no icon dependency), à la split-button. */\nfunction ChevronGlyph({ className = \"size-3\" }: { className?: string }) {\n return (\n \n \n \n );\n}\n\n/** Dialog-launcher glyph (↘) — the Fluent \"open dialog\" corner arrow. */\nfunction DialogLauncherGlyph() {\n return (\n \n \n \n );\n}\n\n/**\n * RibbonGroup (classic) — the crux. Renders a `CollapseGroup` (C1) with two form\n * shells, both kept mounted for measurement:\n *\n * - **expanded:** a `role=\"group\"` div — the horizontal cluster of children over\n * a centered muted `label`, an optional ↘ launcher bottom-right, and a trailing\n * hairline (suppressed on the last group). Children render here **only while\n * expanded**.\n * - **collapsed:** a fixed-size icon + label + chevron `ToolbarButton` (a kit\n * `Popover` trigger, so it joins the toolbar roving-tabindex) whose flyout holds\n * the group's SAME children — rendered there **only while collapsed** (and the\n * flyout is open). The shell's size is independent of the children.\n *\n * **Focus-on-collapse:** if the focused control's group flips to collapsed, focus\n * moves to that group's collapsed dropdown button — the ribbon's focus-to-trigger\n * pattern at group level (snapshot focus during the flipping render, move it in\n * the post-commit effect).\n */\nfunction RibbonGroupClassic({\n groupId,\n label,\n icon,\n collapsePriority = 0,\n launcher,\n onLauncherClick,\n withTrailingDivider = true,\n className,\n children,\n}: RibbonGroupProps) {\n const groupCtx = useMemo(\n () => ({ groupId, groupLabel: label }),\n [groupId, label]\n );\n const mode = useGroupMode(groupId);\n const isCollapsed = mode === \"collapsed\";\n const [open, setOpen] = useState(false);\n\n const expandedShellRef = useRef(null);\n const collapsedButtonRef = useRef(null);\n const heldFocusBeforeCollapseRef = useRef(false);\n\n // Snapshot focus during the render that flips this group collapsed — the DOM\n // is still pre-commit here (the expanded shell is visible and holds focus), so\n // we capture \"did a control in me hold focus?\" before C1's `display:none` lands.\n if (\n isCollapsed &&\n typeof document !== \"undefined\" &&\n expandedShellRef.current &&\n expandedShellRef.current.contains(document.activeElement)\n ) {\n heldFocusBeforeCollapseRef.current = true;\n }\n\n // After the collapse commit (expanded shell now display:none, collapsed button\n // visible) move focus to the button so it isn't dropped to .\n useLayoutEffectSafe(() => {\n if (isCollapsed && heldFocusBeforeCollapseRef.current) {\n collapsedButtonRef.current?.focus();\n heldFocusBeforeCollapseRef.current = false;\n }\n }, [isCollapsed]);\n\n // Un-collapsing while the flyout is open would leave a dangling popover.\n useEffect(() => {\n if (!isCollapsed && open) setOpen(false);\n }, [isCollapsed, open]);\n\n const showSeparator = withTrailingDivider !== false;\n const separator = showSeparator ? (\n \n ) : null;\n\n const launcherNode =\n launcher ??\n (onLauncherClick ? (\n \n \n \n ) : null);\n\n const expanded = (\n \n
\n \n
\n {!isCollapsed ? children : null}\n
\n \n
\n \n {label}\n \n {launcherNode ? (\n \n {launcherNode}\n \n ) : null}\n
\n
\n {separator}\n \n );\n\n const collapsed = (\n \n \n \n \n {icon}\n \n \n {label}\n \n \n \n }\n />\n \n \n
\n {isCollapsed ? children : null}\n
\n \n \n \n {separator}\n \n );\n\n return (\n \n );\n}\n\n/**\n * RibbonGroupClassicStatic — the `autoAdjust={false}` classic group: the expanded\n * band anatomy only, always showing its children. It calls **no** collapse hooks\n * and renders no `CollapseGroup` (there is no `GroupCollapse` provider in this\n * mode), so the band never collapses — it simply overflows into the scroll UI.\n * `collapsePriority`/`icon` are irrelevant here (nothing collapses) and ignored.\n */\nfunction RibbonGroupClassicStatic({\n groupId,\n label,\n launcher,\n onLauncherClick,\n withTrailingDivider = true,\n className,\n children,\n}: RibbonGroupProps) {\n const groupCtx = useMemo(\n () => ({ groupId, groupLabel: label }),\n [groupId, label]\n );\n\n const separator =\n withTrailingDivider !== false ? (\n \n ) : null;\n\n const launcherNode =\n launcher ??\n (onLauncherClick ? (\n \n \n \n ) : null);\n\n return (\n \n
\n \n
\n {children}\n
\n \n
\n \n {label}\n \n {launcherNode ? (\n \n {launcherNode}\n \n ) : null}\n
\n
\n {separator}\n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonItem (the crux) */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonItemProps {\n /** Required, unique within the row. */\n id: string;\n /** Menu-form text (bar form may be icon-only). */\n label: string;\n /** Icon reused in the menu form. */\n icon?: ReactNode;\n /**\n * **single-line only.** Higher survives longer as the row shrinks (priority\n * beats DOM order). **Ignored in classic** — there the group's\n * `collapsePriority` rules and the whole group collapses together.\n */\n priority?: number;\n /**\n * **single-line only.** Never overflows (e.g. Undo, a pinned command).\n * **Ignored in classic** (nothing item-overflows; groups collapse whole).\n */\n pinned?: boolean;\n /** **single-line only.** Custom menu form (split-button submenu, labeled combo, …). */\n overflowRender?: () => ReactNode;\n /** **single-line only.** Fired by the default menu form (a `DropdownMenuItem`). */\n onSelect?: () => void;\n /**\n * Render this item only in the listed layouts (Word shows different command\n * sets per mode). When set and the active layout isn't listed, the item renders\n * nothing — and, in single-line, does not register in the overflow menu.\n * Default: both layouts.\n */\n layouts?: RibbonLayout[];\n /** The bar-form control (ToolbarButton, Toggle, SplitButton, RibbonLargeButton, …). */\n children: ReactElement;\n}\n\n/**\n * RibbonItem — one command. Adapts to the root `layout`:\n * - **single-line:** wraps `children` in an `OverflowItem` and registers its\n * menu-form metadata (`RibbonOverflowMenu` renders it when hidden); owns the\n * focus-preservation move to the \"…\" trigger. `priority`/`pinned`/`onSelect`/\n * `overflowRender` apply here only.\n * - **classic:** renders `children` directly — no `OverflowItem`, no registry\n * (\"…\" doesn't exist in classic). Nothing item-overflows; the group collapses\n * whole (`RibbonGroup.collapsePriority`).\n *\n * The `layouts` escape hatch renders (and, in single-line, registers) nothing\n * when the active layout isn't listed.\n */\nfunction RibbonItem(props: RibbonItemProps) {\n const { layout } = useRibbonContext();\n if (props.layouts && !props.layouts.includes(layout)) return null;\n if (layout === \"classic\") return <>{props.children};\n return ;\n}\n\n/** RibbonItem's v1 (single-line) body — the OverflowItem + registry + focus move. */\nfunction RibbonItemSingleLine({\n id,\n label,\n icon,\n priority,\n pinned,\n overflowRender,\n onSelect,\n children,\n}: RibbonItemProps) {\n const { registry, overflowTriggerRef } = useRibbonContentContext();\n const { groupId, groupLabel } = useContext(RibbonGroupContext);\n const visible = useIsOverflowItemVisible(id);\n\n const childElementRef = useRef(null);\n const heldFocusBeforeHideRef = useRef(false);\n\n // Keep the registry entry current every commit (no deps). `register` mutates\n // in place for an existing id — no new snapshot identity, no re-render loop —\n // and only rebuilds + notifies on a membership change (first mount).\n useLayoutEffectSafe(() => {\n registry.register({\n id,\n label,\n icon,\n groupId,\n groupLabel,\n overflowRender,\n onSelect,\n });\n });\n\n // Unregister on unmount / id change.\n useLayoutEffectSafe(() => {\n return () => registry.unregister(id);\n }, [registry, id]);\n\n // Snapshot focus during the render that flips this item hidden — the DOM is\n // still pre-commit here (item visible, focus still on it), so we can capture\n // \"did I hold focus?\" before `OverflowItem`'s `display:none` lands this commit.\n if (\n !visible &&\n typeof document !== \"undefined\" &&\n childElementRef.current &&\n childElementRef.current.contains(document.activeElement)\n ) {\n heldFocusBeforeHideRef.current = true;\n }\n\n // A layout effect runs after the display:none commit, when the trigger is\n // already visible — move focus there so it isn't dropped to .\n useLayoutEffectSafe(() => {\n if (!visible && heldFocusBeforeHideRef.current) {\n overflowTriggerRef.current?.focus();\n heldFocusBeforeHideRef.current = false;\n }\n }, [visible, overflowTriggerRef]);\n\n const captureChild = useCallback((el: HTMLElement | null) => {\n childElementRef.current = el;\n }, []);\n\n const child = Children.only(children);\n if (!isValidElement(child)) {\n throw new Error(\" expects a single element child.\");\n }\n // Merge our capture ref with the child's own ref. `OverflowItem` merges again\n // with its measure ref (it reads `child.props.ref`), so the element carries\n // both. The merged ref is memoised on the child + captureChild so it doesn't\n // detach/reattach every render.\n const mergedRef = useMemo(\n () => mergeRefs(getChildRef(child), captureChild),\n [child, captureChild]\n );\n const childWithRef = cloneElement(child, {\n ref: mergedRef,\n } as Record);\n\n return (\n \n {childWithRef}\n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonLayoutSwitcher (Word's far-right display-options chevron) */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonLayoutSwitcherProps {\n /** Extra classes for the chevron trigger button. */\n className?: string;\n}\n\n/**\n * RibbonLayoutSwitcher — Word's far-right **display-options** control (validation\n * finding #10): a pinned chevron icon-button opening a menu with two sections that\n * mirror Word's own (pt-BR copy), driven entirely through the ribbon context:\n *\n * - **\"Layout da Faixa de Opções\"** — a radio pair, *Faixa de Opções Clássica* /\n * *Faixa de Opções de Linha Única*; the active `layout` carries the marker\n * (`menuitemradio` + `aria-checked`) and selecting one calls `setLayout` (honours\n * a controlled `layout`).\n * - **\"Mostrar Faixa de Opções\"** — a radio pair on the `collapsed` axis, *Sempre\n * mostrar faixa de opções* (`collapsed=false`) / *Mostrar apenas as guias*\n * (`collapsed=true`), plus *Ajustar automaticamente* — a checkbox on the\n * **classic-only** `autoAdjust` axis, rendered **disabled in single-line** (Word\n * only exposes it for classic; kept visible-but-disabled so its existence is\n * discoverable rather than silently missing).\n *\n * ## Placement (decision)\n * Designed to sit at the **end of the tab strip** (Word's position) via\n * `RibbonTabList`'s `actions` prop — which renders it *outside* the `role=\"tablist\"`\n * (so it never trips axe's `aria-required-children`, the same lesson as the\n * tab-strip `⌄`) **and** outside the tab-strip overflow budget (so it never folds).\n * It also works **standalone** anywhere inside a `` (it only reads context).\n * Both keep axe green — the trigger is an icon-only `\n }\n />\n \n \n Layout da Faixa de Opções\n setLayout(normalizeLayout(value as string))}\n >\n \n Faixa de Opções Clássica\n \n \n Faixa de Opções de Linha Única\n \n \n \n\n \n\n \n Mostrar Faixa de Opções\n setCollapsed(value === \"tabs-only\")}\n >\n \n Sempre mostrar faixa de opções\n \n \n Mostrar apenas as guias\n \n \n setAutoAdjust(next)}\n >\n Ajustar automaticamente\n \n \n \n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonSeparator */\n/* -------------------------------------------------------------------------- */\n\n/**\n * RibbonSeparator — a standalone vertical divider for the row (kit\n * `ToolbarSeparator`). Used inside `RibbonGroup` (wrapped in an `OverflowDivider`)\n * and available on its own for ad-hoc separation outside a group.\n */\nfunction RibbonSeparator({\n className,\n ...props\n}: ComponentProps) {\n return (\n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* Classic form parts (RibbonLargeButton / RibbonRow / RibbonColumn) */\n/* -------------------------------------------------------------------------- */\n\nexport interface RibbonLargeButtonProps extends ComponentProps<\"button\"> {\n /** The ~24px icon shown above the label. */\n icon?: ReactNode;\n /** Append a down chevron (for a menu/split composition — see the doc comment). */\n chevron?: boolean;\n /**\n * Base UI-style **element override** — swap the underlying `\n );\n}\n\n/**\n * RibbonRow — a tiny horizontal flex helper (`data-slot=\"ribbon-row\"`) for\n * composing a group's controls, e.g. one row of a 2×3 small-icon-button grid.\n * Forwards `ref` + props (React 19).\n */\nfunction RibbonRow({ className, ...props }: ComponentProps<\"div\">) {\n return (\n \n );\n}\n\n/**\n * RibbonColumn — a tiny vertical flex helper (`data-slot=\"ribbon-column\"`) for\n * stacking `RibbonRow`s (the 2×3 grid) or a vertical list of medium icon+label\n * buttons. Forwards `ref` + props (React 19).\n */\nfunction RibbonColumn({ className, ...props }: ComponentProps<\"div\">) {\n return (\n \n );\n}\n\n/* -------------------------------------------------------------------------- */\n/* RibbonOverflowMenu (the \"…\" trigger + grouped menu) */\n/* -------------------------------------------------------------------------- */\n\n// Kept measurable while hidden (out of flow + invisible), NOT display:none, so\n// the manager can still read the trigger's width to reserve it from the budget\n// (overflow.tsx's `useOverflowMenu` documents this requirement).\nconst HIDDEN_TRIGGER_STYLE: CSSProperties = {\n position: \"absolute\",\n right: 4,\n visibility: \"hidden\",\n pointerEvents: \"none\",\n};\n\n/** Fluent-style \"…\" glyph — inline SVG (no icon dependency), à la split-button. */\nfunction MoreGlyph() {\n return (\n \n \n \n \n \n );\n}\n\n/**\n * RibbonOverflowMenu — the \"…\" trigger + its menu. Rendered automatically by\n * `RibbonContent` (you don't place it). The trigger is a ghost icon-only\n * `ToolbarButton` wired via `useOverflowMenu` (kept measurable-but-hidden until\n * something overflows). The menu renders **only hidden** items, grouped: a\n * `DropdownMenuLabel` header per group whose items include a hidden one, then\n * each hidden item's menu form (default `DropdownMenuItem`, or its custom\n * `overflowRender`), source order preserved, separators between groups.\n */\nfunction RibbonOverflowMenu() {\n const { registry, overflowTriggerRef } = useRibbonContentContext();\n const { ref, isOverflowing, overflowCount } =\n useOverflowMenu();\n\n const items = useSyncExternalStore(\n registry.subscribe,\n registry.getSnapshot,\n registry.getServerSnapshot\n );\n\n // Group items in first-seen (source) order. Ungrouped items collapse into a\n // single trailing headerless section.\n const sections = useMemo(() => {\n const order: string[] = [];\n const map = new Map<\n string,\n { groupId?: string; groupLabel?: string; items: RibbonItemMeta[] }\n >();\n for (const item of items) {\n const key = item.groupId ?? \"__ungrouped__\";\n let entry = map.get(key);\n if (!entry) {\n entry = {\n groupId: item.groupId,\n groupLabel: item.groupLabel,\n items: [],\n };\n map.set(key, entry);\n order.push(key);\n }\n entry.items.push(item);\n }\n return order.map((key) => map.get(key)!);\n }, [items]);\n\n const triggerRef = useCallback(\n (el: HTMLButtonElement | null) => {\n ref(el);\n overflowTriggerRef.current = el;\n },\n [ref, overflowTriggerRef]\n );\n\n return (\n \n \n \n \n }\n />\n \n {sections.map((section, index) =>\n section.groupId ? (\n \n ) : (\n \n )\n )}\n \n \n );\n}\n\n/** A grouped section — header + hidden rows, shown only when the group isn't fully visible. */\nfunction RibbonOverflowGroupSection({\n groupId,\n groupLabel,\n items,\n index,\n}: {\n groupId: string;\n groupLabel?: string;\n items: RibbonItemMeta[];\n index: number;\n}) {\n const state = useIsOverflowGroupVisible(groupId);\n if (state === \"visible\") return null;\n return (\n <>\n {index > 0 ? : null}\n \n {groupLabel ? {groupLabel} : null}\n {items.map((item) => (\n \n ))}\n \n \n );\n}\n\n/** Ungrouped items — no header; each row self-hides while visible. */\nfunction RibbonOverflowUngroupedSection({\n items,\n index,\n}: {\n items: RibbonItemMeta[];\n index: number;\n}) {\n return (\n <>\n {index > 0 ? : null}\n \n {items.map((item) => (\n \n ))}\n \n \n );\n}\n\n/** One command, rendered only while it is overflowed (hidden in the row). */\nfunction RibbonOverflowRow({ meta }: { meta: RibbonItemMeta }) {\n const visible = useIsOverflowItemVisible(meta.id);\n if (visible) return null;\n if (meta.overflowRender) return <>{meta.overflowRender()};\n return (\n meta.onSelect?.()}\n >\n {meta.icon}\n {meta.label}\n \n );\n}\n\nexport {\n Ribbon,\n RibbonTabList,\n RibbonTab,\n RibbonContent,\n RibbonGroup,\n RibbonItem,\n RibbonOverflowMenu,\n RibbonLayoutSwitcher,\n RibbonSeparator,\n RibbonLargeButton,\n RibbonRow,\n RibbonColumn,\n};\n" } ], "docs": "Compose `Ribbon` > `RibbonTabList`/`RibbonTab` + one `RibbonContent` per tab > `RibbonGroup` > `RibbonItem`. `RibbonContent` wires the Overflow provider, the measured Toolbar, the item registry, AND the '…' overflow menu for you — you only supply groups and items.\n\n```tsx\n\n \n Home\n Insert\n \n \n \n } priority={80} pinned onSelect={bold}>\n \n \n {/* …more items */}\n \n {/* …more groups */}\n \n\n```\n\nEvery `RibbonItem` needs `id` + `label` (+ optional `icon`) so it can render as a bar icon AND a labeled menu row. `priority` (higher survives longer, beats DOM order) and `pinned` (never overflows) drive the overflow order. Supply `overflowRender` for a complex menu form (a split button → submenu, a combo → labeled field); otherwise the default menu form is a `DropdownMenuItem` firing `onSelect`. Axes mirror Word's switcher and are each controllable (controlled prop + `default*` + `on*Change`): `layout` ('single-line' or 'classic' — the same tree renders both; unknown values degrade to single-line), `collapsed` ('Mostrar apenas as guias' — tabs-only; activating any tab un-collapses), and `autoAdjust` (classic adaptive resize). Drop `` into `` for Word's far-right display-options chevron; it reads/writes all three axes through context and is placed outside the tablist + the tab-overflow budget so it never folds and stays axe-clean. In classic, give each RibbonGroup an `icon` + `collapsePriority` (higher collapses first) and optionally a launcher (`onLauncherClick` or `launcher`); compose group content with RibbonLargeButton / RibbonRow / RibbonColumn. Use `layouts` on a RibbonItem/RibbonGroup to scope it to one layout. There is no ARIA 'ribbon' pattern: the composite is APG Tabs over APG Toolbar, and each command row is labelled by its owning tab. See ribbon.tsx's doc comment for the full model, the desktop-Office divergence (no overlay flyout when collapsed), and the focus-preservation behavior." }