From b687bceed52c7515be1655af9e407c48e8f20901 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Wed, 7 Oct 2026 21:32:30 +0400
Subject: [PATCH 01/20] feat(m3-foundation): Search styles and layout
 primitives were added

---
 .../assets/stylesheets/components/index.scss  |   1 +
 .../stylesheets/components/search/index.scss  | 319 ++++++++++++++++++
 m3-foundation/lib/search.ts                   |  55 +++
 m3-foundation/tests/search.test.ts            |  50 +++
 m3-foundation/types/components/search.d.ts    |  30 ++
 5 files changed, 455 insertions(+)
 create mode 100644 m3-foundation/assets/stylesheets/components/search/index.scss
 create mode 100644 m3-foundation/lib/search.ts
 create mode 100644 m3-foundation/tests/search.test.ts
 create mode 100644 m3-foundation/types/components/search.d.ts

diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index bb14fd6..26d5d7e 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -17,6 +17,7 @@
 @use 'rich-tooltip';
 @use 'ripple';
 @use 'scrim';
+@use 'search';
 @use 'scroll-box';
 @use 'scroll-rail';
 @use 'select';
diff --git a/m3-foundation/assets/stylesheets/components/search/index.scss b/m3-foundation/assets/stylesheets/components/search/index.scss
new file mode 100644
index 0000000..3b7e026
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/search/index.scss
@@ -0,0 +1,319 @@
+@use '../../basics/motion' as m3-motion;
+@use '../../basics/typography' as m3-typography;
+
+.m3-search {
+  display: block;
+  inline-size: 100%;
+  max-inline-size: 720px;
+  color: var(--m3-sys-on-surface);
+
+  &__bar {
+    display: flex;
+    block-size: 56px;
+    box-sizing: border-box;
+    align-items: center;
+    border-radius: 28px;
+    background: var(--m3-sys-surface-container-high);
+    overflow: hidden;
+  }
+
+  &_open &__bar {
+    visibility: hidden;
+  }
+
+  &__trigger {
+    display: flex;
+    min-inline-size: 0;
+    block-size: 100%;
+    padding-block: 0;
+    padding-inline: 4px;
+    border: 0;
+    flex: 1 1 auto;
+    align-items: center;
+    gap: 4px;
+    background: transparent;
+    color: var(--m3-sys-on-surface-variant);
+    cursor: text;
+    text-align: start;
+    @include m3-typography.body-large;
+  }
+
+  &__trigger:hover {
+    background: color-mix(in srgb, var(--m3-sys-on-surface) 8%, transparent);
+  }
+
+  &__trigger:active {
+    background: color-mix(in srgb, var(--m3-sys-on-surface) 12%, transparent);
+  }
+
+  &__trigger:focus-visible {
+    outline: 2px solid var(--m3-sys-secondary);
+    outline-offset: -4px;
+  }
+
+  &__trigger-text {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &__trigger-text_filled {
+    color: var(--m3-sys-on-surface);
+  }
+
+  &__trigger-icon {
+    display: flex;
+    inline-size: 48px;
+    block-size: 48px;
+    flex: 0 0 48px;
+    align-items: center;
+    justify-content: center;
+  }
+
+  &__leading,
+  &__trailing,
+  &__actions {
+    display: flex;
+    flex: 0 0 auto;
+    align-items: center;
+  }
+
+  &__leading .m3-icon-button,
+  &__trailing .m3-icon-button,
+  &__actions .m3-icon-button,
+  &__header > .m3-icon-button {
+    inline-size: 48px;
+    block-size: 48px;
+  }
+
+  &__leading {
+    min-inline-size: 52px;
+    padding-inline-start: 4px;
+    justify-content: center;
+  }
+
+  &__trailing {
+    padding-inline-end: 4px;
+  }
+
+  &__trailing > .m3-icon {
+    margin-inline: 12px;
+  }
+
+  &__overlay {
+    pointer-events: none;
+    position: fixed;
+    inset: 0;
+    z-index: var(--m3-search-z-index, 1200);
+  }
+
+  &__scrim {
+    background: color-mix(in srgb, var(--m3-sys-on-surface) 32%, transparent);
+    pointer-events: auto;
+    position: absolute;
+    inset: 0;
+  }
+
+  &__view {
+    display: flex;
+    box-sizing: border-box;
+    min-inline-size: 0;
+    max-block-size: 100dvh;
+    flex-direction: column;
+    background: var(--m3-sys-surface-container-high);
+    box-shadow: var(--m3-elevation-3);
+    color: var(--m3-sys-on-surface);
+    overflow: hidden;
+    pointer-events: auto;
+    position: absolute;
+  }
+
+  &__view_full-screen {
+    inline-size: 100%;
+    block-size: 100%;
+    inset: 0;
+  }
+
+  &__view_docked {
+    inline-size: var(--m3-search-docked-width, 360px);
+    min-block-size: min(240px, calc(100dvh - var(--m3-search-docked-top, 12px) - 12px));
+    max-block-size: min(66.667dvh, calc(100dvh - var(--m3-search-docked-top, 12px) - 12px));
+    border-radius: 28px;
+    left: var(--m3-search-docked-left, 12px);
+    top: var(--m3-search-docked-top, 12px);
+  }
+
+  &__view_contained {
+    gap: 2px;
+    clip-path: inset(0 0 0 0 round 0px);
+  }
+
+  &__view_contained.m3-search__view_full-screen {
+    padding: 12px;
+    background: var(--m3-sys-surface-container-low);
+    box-shadow: none;
+  }
+
+  &__view_contained.m3-search__view_docked {
+    background: transparent;
+    box-shadow: none;
+  }
+
+  &__header {
+    display: flex;
+    block-size: 56px;
+    min-block-size: 56px;
+    padding-inline: 4px;
+    align-items: center;
+    background: var(--m3-sys-surface-container-high);
+  }
+
+  &__view_contained &__header {
+    border-radius: 28px;
+  }
+
+  &__view_divided.m3-search__view_full-screen &__header {
+    block-size: 72px;
+    min-block-size: 72px;
+  }
+
+  &__input {
+    min-inline-size: 0;
+    block-size: 100%;
+    padding-block: 0;
+    padding-inline: 4px;
+    border: 0;
+    flex: 1 1 auto;
+    background: transparent;
+    color: var(--m3-sys-on-surface);
+    outline: 0;
+    @include m3-typography.body-large;
+  }
+
+  &__input::placeholder {
+    color: var(--m3-sys-on-surface-variant);
+    opacity: 1;
+  }
+
+  &__input::-webkit-search-cancel-button {
+    display: none;
+  }
+
+  &__results {
+    min-block-size: 0;
+    padding-block: 8px;
+    flex: 1 1 auto;
+    overflow: auto;
+    overscroll-behavior: contain;
+    outline: 0;
+  }
+
+  &__results .m3-list {
+    inline-size: 100%;
+    background: transparent;
+  }
+
+  &__view_contained &__results {
+    border-radius: 16px;
+    background: var(--m3-sys-surface-container-high);
+  }
+
+  &__view_divided &__results {
+    border-block-start: 1px solid var(--m3-sys-outline);
+  }
+
+  &__status {
+    inline-size: 1px;
+    block-size: 1px;
+    overflow: hidden;
+    position: absolute;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+}
+
+.m3-search-enter .m3-search__view_divided,
+.m3-search-enter-from .m3-search__view_divided,
+.m3-search-exit-active .m3-search__view_divided,
+.m3-search-leave-to .m3-search__view_divided {
+  opacity: 0;
+  transform: translateY(-8px) scale(0.98);
+}
+
+.m3-search-enter-active:not(.m3-search-enter-from) .m3-search__view_divided {
+  opacity: 1;
+  transform: none;
+}
+
+.m3-search-enter-active .m3-search__view_divided,
+.m3-search-exit-active .m3-search__view_divided,
+.m3-search-leave-active .m3-search__view_divided {
+  transition:
+    opacity #{m3-motion.duration('medium2')} #{m3-motion.easing('standard')},
+    transform #{m3-motion.duration('medium2')} #{m3-motion.easing('standard')};
+}
+
+.m3-search-enter .m3-search__view_contained.m3-search__view_full-screen,
+.m3-search-enter-from .m3-search__view_contained.m3-search__view_full-screen,
+.m3-search-exit-active .m3-search__view_contained.m3-search__view_full-screen,
+.m3-search-leave-to .m3-search__view_contained.m3-search__view_full-screen {
+  clip-path: inset(12px var(--m3-search-origin-right) calc(100% - 68px) var(--m3-search-origin-left) round 28px);
+  transform: translateY(var(--m3-search-origin-offset-y));
+}
+
+.m3-search-enter .m3-search__view_contained.m3-search__view_docked,
+.m3-search-enter-from .m3-search__view_contained.m3-search__view_docked,
+.m3-search-exit-active .m3-search__view_contained.m3-search__view_docked,
+.m3-search-leave-to .m3-search__view_contained.m3-search__view_docked {
+  clip-path: inset(0px var(--m3-search-origin-right) calc(100% - 56px) var(--m3-search-origin-left) round 28px);
+  transform: translateY(var(--m3-search-origin-offset-y));
+}
+
+.m3-search-enter-active:not(.m3-search-enter-from) .m3-search__view_contained.m3-search__view_full-screen,
+.m3-search-enter-active:not(.m3-search-enter-from) .m3-search__view_contained.m3-search__view_docked {
+  clip-path: inset(0 0 0 0 round 0px);
+  transform: none;
+}
+
+.m3-search-enter-active .m3-search__view_contained,
+.m3-search-exit-active .m3-search__view_contained,
+.m3-search-leave-active .m3-search__view_contained {
+  transition:
+    clip-path #{m3-motion.duration('medium2')} #{m3-motion.easing('standard')},
+    transform #{m3-motion.duration('medium2')} #{m3-motion.easing('standard')};
+}
+
+.m3-search-enter .m3-search__scrim,
+.m3-search-enter-from .m3-search__scrim,
+.m3-search-exit-active .m3-search__scrim,
+.m3-search-leave-to .m3-search__scrim {
+  opacity: 0;
+}
+
+.m3-search-enter-active:not(.m3-search-enter-from) .m3-search__scrim {
+  opacity: 1;
+}
+
+.m3-search-enter-active .m3-search__scrim,
+.m3-search-exit-active .m3-search__scrim,
+.m3-search-leave-active .m3-search__scrim {
+  transition: m3-motion.timing-standard(opacity, 'short4');
+}
+
+.m3-search-exit-active .m3-search__view,
+.m3-search-exit-active .m3-search__scrim,
+.m3-search-leave-active .m3-search__view,
+.m3-search-leave-active .m3-search__scrim {
+  pointer-events: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .m3-search-enter-active .m3-search__view,
+  .m3-search-exit-active .m3-search__view,
+  .m3-search-leave-active .m3-search__view,
+  .m3-search-enter-active .m3-search__scrim,
+  .m3-search-exit-active .m3-search__scrim,
+  .m3-search-leave-active .m3-search__scrim {
+    transition-duration: 0ms;
+  }
+}
diff --git a/m3-foundation/lib/search.ts b/m3-foundation/lib/search.ts
new file mode 100644
index 0000000..d9bcfd3
--- /dev/null
+++ b/m3-foundation/lib/search.ts
@@ -0,0 +1,55 @@
+import type {
+  ResolvedSearchLayout,
+  SearchAnchorRect,
+  SearchBreakpoint,
+  SearchDockedPosition,
+  SearchLayout,
+  SearchRevealOrigin,
+  SearchViewport,
+} from '../types/components/search'
+
+const DOCKED_MARGIN = 12
+const DOCKED_MIN_WIDTH = 360
+const DOCKED_MAX_WIDTH = 720
+const DOCKED_MIN_HEIGHT = 240
+
+export const resolveSearchLayout = (layout: SearchLayout, breakpoint: SearchBreakpoint): ResolvedSearchLayout => layout === 'auto'
+  ? breakpoint === 'compact' ? 'full-screen' : 'docked'
+  : layout
+
+export const getSearchDockedPosition = (
+  anchor: SearchAnchorRect,
+  viewport: SearchViewport
+): SearchDockedPosition => {
+  const availableWidth = Math.max(0, viewport.width - 2 * DOCKED_MARGIN)
+  const width = Math.min(availableWidth, DOCKED_MAX_WIDTH, Math.max(DOCKED_MIN_WIDTH, anchor.width + 2 * DOCKED_MARGIN))
+  const left = Math.min(
+    Math.max(DOCKED_MARGIN, anchor.left - (width - anchor.width) / 2),
+    Math.max(DOCKED_MARGIN, viewport.width - width - DOCKED_MARGIN)
+  )
+  const top = Math.min(
+    Math.max(DOCKED_MARGIN, anchor.top),
+    Math.max(DOCKED_MARGIN, viewport.height - DOCKED_MIN_HEIGHT - DOCKED_MARGIN)
+  )
+
+  return { left, top, width }
+}
+
+export const getSearchRevealOrigin = (
+  anchor: SearchAnchorRect,
+  viewport: SearchViewport,
+  position: SearchDockedPosition,
+  layout: ResolvedSearchLayout
+): SearchRevealOrigin => {
+  const viewLeft = layout === 'docked' ? position.left : 0
+  const viewTop = layout === 'docked' ? position.top : 0
+  const viewWidth = layout === 'docked' ? position.width : viewport.width
+  const headerInset = layout === 'full-screen' ? 12 : 0
+  const left = anchor.left - viewLeft
+
+  return {
+    left,
+    right: viewWidth - left - anchor.width,
+    offsetY: anchor.top - viewTop - headerInset,
+  }
+}
diff --git a/m3-foundation/tests/search.test.ts b/m3-foundation/tests/search.test.ts
new file mode 100644
index 0000000..d18af3c
--- /dev/null
+++ b/m3-foundation/tests/search.test.ts
@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  getSearchDockedPosition,
+  getSearchRevealOrigin,
+  resolveSearchLayout,
+} from '../lib/search'
+
+describe('Search layout', () => {
+  it('uses full-screen only at the compact breakpoint in auto mode', () => {
+    expect(resolveSearchLayout('auto', 'compact')).toBe('full-screen')
+    expect(resolveSearchLayout('auto', 'medium')).toBe('docked')
+    expect(resolveSearchLayout('auto', 'expanded')).toBe('docked')
+    expect(resolveSearchLayout('auto', 'large')).toBe('docked')
+    expect(resolveSearchLayout('full-screen', 'large')).toBe('full-screen')
+    expect(resolveSearchLayout('docked', 'compact')).toBe('docked')
+  })
+
+  it('keeps the docked view within a narrow viewport', () => {
+    expect(getSearchDockedPosition(
+      { left: 24, top: 80, width: 340 },
+      { width: 400, height: 700 }
+    )).toEqual({ left: 12, top: 80, width: 364 })
+  })
+
+  it('keeps a maximum-width bar aligned with its docked view', () => {
+    expect(getSearchDockedPosition(
+      { left: 60, top: 80, width: 720 },
+      { width: 1000, height: 800 }
+    )).toEqual({ left: 60, top: 80, width: 720 })
+  })
+
+  it('clamps the view at the right and bottom edges', () => {
+    expect(getSearchDockedPosition(
+      { left: 1100, top: 700, width: 760 },
+      { width: 1200, height: 800 }
+    )).toEqual({ left: 468, top: 548, width: 720 })
+  })
+
+  it('starts the contained reveal at the collapsed bar in either layout', () => {
+    const anchor = { left: 24, top: 80, width: 342 }
+    const viewport = { width: 390, height: 760 }
+    const position = { left: 12, top: 80, width: 366 }
+
+    expect(getSearchRevealOrigin(anchor, viewport, position, 'full-screen'))
+      .toEqual({ left: 24, right: 24, offsetY: 68 })
+    expect(getSearchRevealOrigin(anchor, viewport, position, 'docked'))
+      .toEqual({ left: 12, right: 12, offsetY: 0 })
+  })
+})
diff --git a/m3-foundation/types/components/search.d.ts b/m3-foundation/types/components/search.d.ts
new file mode 100644
index 0000000..2ba26cb
--- /dev/null
+++ b/m3-foundation/types/components/search.d.ts
@@ -0,0 +1,30 @@
+import type { Breakpoint } from '../breakpoint'
+
+export type SearchAppearance = 'contained' | 'divided'
+export type SearchLayout = 'auto' | 'full-screen' | 'docked'
+export type ResolvedSearchLayout = Exclude<SearchLayout, 'auto'>
+
+export interface SearchDockedPosition {
+  left: number;
+  top: number;
+  width: number;
+}
+
+export interface SearchAnchorRect {
+  left: number;
+  top: number;
+  width: number;
+}
+
+export interface SearchViewport {
+  width: number;
+  height: number;
+}
+
+export interface SearchRevealOrigin {
+  left: number;
+  right: number;
+  offsetY: number;
+}
+
+export type SearchBreakpoint = Breakpoint

From 5bf2026f93ae988d7bb04807e058dac0692350c7 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Wed, 7 Oct 2026 21:32:48 +0400
Subject: [PATCH 02/20] feat(m3-react): Search component and examples were
 added

---
 m3-react/src/components/index.ts              |   1 +
 m3-react/src/components/search/M3Search.tsx   | 330 ++++++++++++++++++
 m3-react/src/components/search/index.ts       |   2 +
 m3-react/storybook/components/M3Search.mdx    | 155 ++++++++
 .../storybook/components/M3Search.stories.tsx |  54 +++
 .../examples/search/SearchExample.tsx         | 125 +++++++
 m3-react/tests/M3Search.e2e.tsx               |  49 +++
 m3-react/tests/M3Search.test.tsx              | 106 ++++++
 8 files changed, 822 insertions(+)
 create mode 100644 m3-react/src/components/search/M3Search.tsx
 create mode 100644 m3-react/src/components/search/index.ts
 create mode 100644 m3-react/storybook/components/M3Search.mdx
 create mode 100644 m3-react/storybook/components/M3Search.stories.tsx
 create mode 100644 m3-react/storybook/examples/search/SearchExample.tsx
 create mode 100644 m3-react/tests/M3Search.e2e.tsx
 create mode 100644 m3-react/tests/M3Search.test.tsx

diff --git a/m3-react/src/components/index.ts b/m3-react/src/components/index.ts
index e6eb0ba..58419af 100644
--- a/m3-react/src/components/index.ts
+++ b/m3-react/src/components/index.ts
@@ -18,6 +18,7 @@ export * from './radio'
 export * from './rich-tooltip'
 export * from './ripple'
 export * from './scroll-rail'
+export * from './search'
 export * from './select'
 export * from './side-sheet'
 export * from './snackbar'
diff --git a/m3-react/src/components/search/M3Search.tsx b/m3-react/src/components/search/M3Search.tsx
new file mode 100644
index 0000000..1213454
--- /dev/null
+++ b/m3-react/src/components/search/M3Search.tsx
@@ -0,0 +1,330 @@
+import type { ComponentSetupContext } from '@/utils/component'
+import type {
+  CSSProperties,
+  FC,
+  FormEvent,
+  HTMLAttributes,
+  ReactNode,
+  Ref,
+} from 'react'
+import type {
+  SearchAnchorRect,
+  SearchAppearance,
+  SearchDockedPosition,
+  SearchLayout,
+  SearchViewport,
+} from '@modulify/m3-foundation/types/components/search'
+
+import { activateModalFocus } from '@modulify/m3-foundation/lib/modal'
+import { createPortal } from 'react-dom'
+import { CSSTransition } from 'react-transition-group'
+import { durations } from '@modulify/m3-foundation/lib/motion'
+import {
+  getSearchDockedPosition,
+  getSearchRevealOrigin,
+  resolveSearchLayout,
+} from '@modulify/m3-foundation/lib/search'
+import {
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+
+import defineComponent from '@/utils/component'
+import { defineSlot, distinct } from '@/utils/content'
+import { toClassName } from '@/utils/styling'
+import { useBreakpoint, useId } from '@/hooks'
+
+export interface SearchResultsContext {
+  query: string;
+  close(): void;
+  submit(): void;
+}
+
+interface ResultsProps {
+  render?: (context: SearchResultsContext) => ReactNode;
+  children?: ReactNode;
+}
+
+type SearchViewStyle = CSSProperties & {
+  '--m3-search-docked-left'?: string;
+  '--m3-search-docked-top'?: string;
+  '--m3-search-docked-width'?: string;
+  '--m3-search-origin-left'?: string;
+  '--m3-search-origin-right'?: string;
+  '--m3-search-origin-offset-y'?: string;
+}
+
+export interface M3SearchProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSubmit'> {
+  ref?: Ref<M3SearchExposed>;
+  query: string;
+  label: string;
+  status: string;
+  open: boolean;
+  hint?: string;
+  backLabel?: string;
+  clearLabel?: string;
+  appearance?: SearchAppearance;
+  layout?: SearchLayout;
+  onQueryChange: (query: string) => void;
+  onOpenChange: (open: boolean) => void;
+  onSubmit?: (query: string) => void;
+}
+
+export interface M3SearchExposed {
+  open(): void;
+  close(): void;
+  focus(): void;
+}
+
+const Leading = defineSlot('M3Search.Leading')
+const Trailing = defineSlot('M3Search.Trailing')
+const Actions = defineSlot('M3Search.Actions')
+const Results: FC<ResultsProps> = defineSlot('M3Search.Results', () => null)
+
+const resultSelector = 'a[href], button:not(:disabled), [tabindex="0"]'
+const SEARCH_TRANSITION_MS = durations.medium2
+
+export default defineComponent(function M3Search({
+  ref: _ref,
+  id,
+  query,
+  label,
+  status,
+  open,
+  hint = label,
+  backLabel = 'Back',
+  clearLabel = 'Clear search',
+  appearance = 'contained',
+  layout = 'auto',
+  className = '',
+  children = [],
+  onQueryChange,
+  onOpenChange,
+  onSubmit,
+  ...attrs
+}: M3SearchProps, { expose }: ComponentSetupContext<M3SearchExposed>) {
+  const breakpoint = useBreakpoint()
+  const resolvedLayout = resolveSearchLayout(layout, breakpoint.name)
+  const rootId = useId(id, 'm3-search')
+  const viewId = rootId + '-view'
+  const resultsId = rootId + '-results'
+  const accessibleName = hint === label ? label : `${hint} ${label}`
+
+  const bar = useRef<HTMLDivElement | null>(null)
+  const overlay = useRef<HTMLDivElement | null>(null)
+  const dialog = useRef<HTMLDivElement | null>(null)
+  const input = useRef<HTMLInputElement | null>(null)
+  const results = useRef<HTMLDivElement | null>(null)
+  const scrim = useRef<HTMLDivElement | null>(null)
+  const callbacks = useRef({ onOpenChange, onQueryChange, onSubmit })
+  callbacks.current = { onOpenChange, onQueryChange, onSubmit }
+
+  const [position, setPosition] = useState<SearchDockedPosition>({ left: 12, top: 12, width: 360 })
+  const [anchor, setAnchor] = useState<SearchAnchorRect>({ left: 12, top: 12, width: 360 })
+  const [viewport, setViewport] = useState<SearchViewport>({ width: 384, height: 640 })
+  const parsed = useMemo(() => distinct(children, {
+    slots: { leading: Leading, trailing: Trailing, actions: Actions, results: Results },
+  }), [children])
+
+  const close = () => callbacks.current.onOpenChange(false)
+  const submit = () => {
+    callbacks.current.onSubmit?.(query)
+    results.current?.focus()
+  }
+
+  expose({
+    open: () => callbacks.current.onOpenChange(true),
+    close,
+    focus: () => open ? input.current?.focus() : bar.current?.querySelector('button')?.focus(),
+  })
+
+  useLayoutEffect(() => {
+    if (!open || !bar.current) return
+
+    const update = () => {
+      if (!bar.current) return
+      const rect = bar.current.getBoundingClientRect()
+      const nextViewport = {
+        width: window.innerWidth,
+        height: window.innerHeight,
+      }
+      setAnchor({ left: rect.left, top: rect.top, width: rect.width })
+      setViewport(nextViewport)
+      if (resolvedLayout === 'docked') setPosition(getSearchDockedPosition(rect, nextViewport))
+    }
+
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update)
+    observer?.observe(bar.current)
+    window.addEventListener('resize', update)
+    window.addEventListener('scroll', update, true)
+    update()
+
+    return () => {
+      observer?.disconnect()
+      window.removeEventListener('resize', update)
+      window.removeEventListener('scroll', update, true)
+    }
+  }, [open, resolvedLayout])
+
+  useLayoutEffect(() => {
+    if (!open || !dialog.current) return
+
+    const deactivate = activateModalFocus({
+      dialog: dialog.current,
+      exempt: () => [scrim.current],
+      onEscape: () => callbacks.current.onOpenChange(false),
+    })
+    input.current?.focus()
+    return deactivate
+  }, [open])
+
+  const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
+    event.preventDefault()
+    submit()
+  }
+
+  const focusResult = (last: boolean) => {
+    const items = results.current?.querySelectorAll<HTMLElement>(resultSelector)
+    const target = last ? items?.[items.length - 1] : items?.[0]
+    target?.focus()
+  }
+
+  const origin = getSearchRevealOrigin(anchor, viewport, position, resolvedLayout)
+  const viewStyle: SearchViewStyle = {
+    '--m3-search-docked-left': `${position.left}px`,
+    '--m3-search-docked-top': `${position.top}px`,
+    '--m3-search-docked-width': `${position.width}px`,
+    '--m3-search-origin-left': `${origin.left}px`,
+    '--m3-search-origin-right': `${origin.right}px`,
+    '--m3-search-origin-offset-y': `${origin.offsetY}px`,
+  }
+
+  const context: SearchResultsContext = { query, close, submit }
+  const resultsSlot = parsed.slots.results
+  const resultsContent = resultsSlot
+    ? resultsSlot.props.render?.(context) ?? resultsSlot.props.children
+    : parsed.content
+
+  return (
+    <>
+      <div id={rootId} className={toClassName(['m3-search', className, { 'm3-search_open': open }])} {...attrs}>
+        <div ref={bar} className="m3-search__bar">
+          {parsed.slots.leading ? <div className="m3-search__leading">{parsed.slots.leading}</div> : null}
+          <button
+            type="button"
+            className="m3-search__trigger"
+            aria-label={accessibleName}
+            aria-haspopup="dialog"
+            aria-expanded={open}
+            aria-controls={open ? viewId : undefined}
+            onClick={() => onOpenChange(true)}
+          >
+            {!parsed.slots.leading ? (
+              <span className="m3-search__trigger-icon"><M3Icon name="search" aria-hidden="true" /></span>
+            ) : null}
+            <span className={toClassName(['m3-search__trigger-text', { 'm3-search__trigger-text_filled': query.length > 0 }])}>
+              {query || hint}
+            </span>
+          </button>
+          {parsed.slots.trailing ? <div className="m3-search__trailing">{parsed.slots.trailing}</div> : null}
+        </div>
+      </div>
+
+      {typeof document !== 'undefined' ? createPortal(
+        <CSSTransition
+          nodeRef={overlay}
+          in={open}
+          timeout={SEARCH_TRANSITION_MS}
+          classNames="m3-search"
+          mountOnEnter
+          unmountOnExit
+        >
+          <div ref={overlay} className="m3-search__overlay" aria-hidden={!open}>
+            {resolvedLayout === 'docked' ? (
+              <div ref={scrim} className="m3-search__scrim" onClick={close} />
+            ) : null}
+            <div
+              ref={dialog}
+              id={viewId}
+              role="dialog"
+              aria-modal={open ? true : undefined}
+              aria-label={label}
+              inert={!open}
+              tabIndex={-1}
+              style={viewStyle}
+              className={toClassName(['m3-search__view', {
+                [`m3-search__view_${appearance}`]: true,
+                [`m3-search__view_${resolvedLayout}`]: true,
+              }])}
+            >
+              <form role="search" className="m3-search__header" onSubmit={handleSubmit}>
+                <M3IconButton aria-label={backLabel} onClick={close}>
+                  <M3Icon name="arrow_back" />
+                </M3IconButton>
+                <input
+                  ref={input}
+                  type="search"
+                  className="m3-search__input"
+                  value={query}
+                  placeholder={hint}
+                  aria-label={accessibleName}
+                  aria-controls={resultsId}
+                  onChange={event => callbacks.current.onQueryChange(event.target.value)}
+                  onKeyDown={event => {
+                    if (event.key === 'ArrowDown') {
+                      event.preventDefault()
+                      focusResult(false)
+                    } else if (event.key === 'ArrowUp') {
+                      event.preventDefault()
+                      focusResult(true)
+                    }
+                  }}
+                />
+                <div className="m3-search__actions">
+                  {query ? (
+                    <M3IconButton aria-label={clearLabel} onClick={() => {
+                      callbacks.current.onQueryChange('')
+                      input.current?.focus()
+                    }}>
+                      <M3Icon name="close" />
+                    </M3IconButton>
+                  ) : null}
+                  {parsed.slots.actions}
+                </div>
+              </form>
+              <div
+                ref={results}
+                id={resultsId}
+                className="m3-search__results"
+                tabIndex={-1}
+                onKeyDown={event => {
+                  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+                  const items = [...event.currentTarget.querySelectorAll<HTMLElement>(resultSelector)]
+                  const current = items.indexOf(event.target as HTMLElement)
+                  const next = event.key === 'ArrowDown'
+                    ? items[Math.min(current + 1, items.length - 1)]
+                    : items[Math.max(current - 1, 0)]
+                  if (next) {
+                    event.preventDefault()
+                    next.focus()
+                  }
+                }}
+              >
+                {resultsContent}
+              </div>
+              <div className="m3-search__status" role="status" aria-live="polite">{status}</div>
+            </div>
+          </div>
+        </CSSTransition>,
+        document.body
+      ) : null}
+    </>
+  )
+}, {
+  slots: { Leading, Trailing, Actions, Results },
+})
diff --git a/m3-react/src/components/search/index.ts b/m3-react/src/components/search/index.ts
new file mode 100644
index 0000000..134c11b
--- /dev/null
+++ b/m3-react/src/components/search/index.ts
@@ -0,0 +1,2 @@
+export { default as M3Search } from './M3Search'
+export type { M3SearchExposed, M3SearchProps, SearchResultsContext } from './M3Search'
diff --git a/m3-react/storybook/components/M3Search.mdx b/m3-react/storybook/components/M3Search.mdx
new file mode 100644
index 0000000..6168b5b
--- /dev/null
+++ b/m3-react/storybook/components/M3Search.mdx
@@ -0,0 +1,155 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import { Localized } from '../i18n'
+import * as M3SearchStories from './M3Search.stories'
+
+<Meta of={M3SearchStories} />
+
+<Localized locale="en-US">
+
+# Search
+
+Search combines a persistent entry bar with an expanded area for suggestions or results. Use it to help people find items in a large collection. Place the bar near the content it searches. The [Material 3 Search guidelines](https://m3.material.io/components/search/guidelines) recommend the contained style for new interfaces; the divided baseline style remains available.
+
+## Guide
+
+### Appearance and layout
+
+The contained style keeps a rounded filled bar when search opens. Divided uses a divider between the input header and results. `layout="auto"` opens full screen below 600 px and docked at wider breakpoints. Choose a fixed layout only when the surrounding product calls for it. The docked surface has a scrim; both expanded layouts behave as modal dialogs in this web implementation.
+
+Search starts with an empty results container. Put an `M3List` or custom content in `M3Search.Results`. Show recent queries before typing if they help; suggestions may appear while typing, and results may appear after submission. Keep filtering, async requests, ranking, empty states, and result navigation in your application. Group distinct result sections with gaps and clear headings.
+
+### Query, focus, and keyboard
+
+`query` and `open` are controlled. Update them in `onQueryChange` and `onOpenChange`; `onSubmit` receives the current query. Submitting leaves the query visible and moves focus from the input to the results area. The back button, Escape, and the docked scrim request closing; focus returns to the control that opened search. Arrow Down/Up moves from the input into the result controls and between them. `Tab` follows the dialog's interactive controls.
+
+Provide a localized `label` describing the searched content, not just “Search.” `hint` is the visible prompt; by default it matches `label`. When they differ, the control's accessible name includes both. Translate `backLabel` and `clearLabel`. Pass a short localized `status` whenever suggestions or results change, such as “3 results”; the polite live region announces it without reading the whole list. Name every custom icon button. A simple list of results uses list/link/button semantics; do not put a rich list under `role="listbox"` without implementing the corresponding combobox pattern.
+
+### Avoid
+
+- Do not use M3Search as a replacement for a small static navigation list.
+- Do not place more than two trailing actions in the expanded bar; when clear is visible, count it as one.
+- Do not let a late async response reopen a closed search or move focus back into its input.
+- Do not treat `type="search"` on M3TextField as the complete Search pattern.
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `M3Search` | Entry bar and modal expanded search view. |
+| `M3SearchProps`, `M3SearchExposed`, `SearchResultsContext` | Typed component contract, imperative methods, and results render context. |
+
+| Prop / callback | Default | Effect |
+| --- | --- | --- |
+| `query`, `onQueryChange` | required | Controlled input value and update request. |
+| `open`, `onOpenChange` | required | Controlled expanded state and request from trigger/back/Escape/scrim. |
+| `label`, `status` | required | Accessible search name and polite result announcement. |
+| `hint` | `label` | Visible prompt when query is empty. |
+| `appearance` | `contained` | `contained` or `divided`. |
+| `layout` | `auto` | `auto`, `full-screen`, or `docked`. |
+| `backLabel`, `clearLabel` | English labels | Accessible names for built-in icon buttons; translate them. |
+| `onSubmit` | — | Called with the query on Enter. |
+| HTML attributes | — | Passed to the collapsed root. |
+
+| Named child | Purpose |
+| --- | --- |
+| `M3Search.Leading` | Optional collapsed-bar leading control; without it a decorative search icon appears in the trigger. |
+| `M3Search.Trailing` | Optional actions at the end of the collapsed bar. |
+| `M3Search.Actions` | Optional expanded-bar trailing actions after the clear button. |
+| `M3Search.Results` | Results content; pass `render={({ query, close, submit }) => ...}` to use the current context. Unslotted children are used when Results is absent. |
+
+The ref exposes `open()`, `close()`, and `focus()`. These request controlled state changes or focus the visible search control; `open()` and `close()` do not mutate parent state.
+
+```tsx
+const [query, setQuery] = useState('')
+const [open, setOpen] = useState(false)
+
+<M3Search
+  query={query}
+  open={open}
+  label="Search messages"
+  status={`${results.length} results`}
+  onQueryChange={setQuery}
+  onOpenChange={setOpen}
+  onSubmit={search}
+>
+  <M3Search.Results render={({ close }) => (
+    <M3List>{results.map(item => (
+      <M3ListItem key={item.id} headline={item.title} onClick={() => { select(item); close() }} />
+    ))}</M3List>
+  )} />
+</M3Search>
+```
+
+## Sources
+
+- [Material Search overview](https://m3.material.io/components/search/overview)
+- [Material Search specs](https://m3.material.io/components/search/specs)
+- [Material Search guidelines](https://m3.material.io/components/search/guidelines)
+- [Material Search accessibility](https://m3.material.io/components/search/accessibility)
+- [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+
+</Localized>
+
+<Localized locale="ru-RU">
+
+# Поиск
+
+Search объединяет постоянную строку входа и раскрытую область подсказок или результатов. Используйте его для поиска в большом наборе объектов и ставьте рядом с искомым содержимым. [Material 3](https://m3.material.io/components/search/guidelines) рекомендует contained для новых интерфейсов; baseline divided остаётся доступен.
+
+## Руководство
+
+### Вид и расположение
+
+Contained сохраняет округлую заполненную строку после раскрытия. Divided разделяет заголовок и результаты линией. `layout="auto"` выбирает полный экран при ширине меньше 600 px и docked при большей. Фиксируйте layout, когда этого требует компоновка продукта. У docked есть затемнение фона; оба раскрытых layout реализованы здесь как модальные диалоги.
+
+Контейнер результатов по умолчанию пуст. Передайте `M3List` или своё содержимое в `M3Search.Results`. До ввода можно показывать историю; во время ввода — подсказки; после отправки — результаты. Фильтрация, асинхронные запросы, сортировка, пустое состояние и переход к результату принадлежат приложению. Разделяйте группы результатов промежутками и понятными заголовками.
+
+### Запрос, фокус и клавиатура
+
+`query` и `open` — управляемые значения. Обновляйте их через `onQueryChange` и `onOpenChange`; `onSubmit` получает текущий запрос. После Enter текст остаётся видимым, а фокус переходит из поля в область результатов. Кнопка назад, Escape и нажатие на затемнение docked запрашивают закрытие; фокус возвращается к инициатору. Стрелки вниз/вверх переводят фокус к действиям результатов и между ними. `Tab` идёт по интерактивным элементам диалога.
+
+Передайте локализованную `label`, называющую область поиска, а не просто «Поиск». `hint` — видимая подсказка; по умолчанию совпадает с `label`. Если они различаются, доступное имя включает оба текста. Переведите `backLabel` и `clearLabel`. При изменении подсказок/результатов обновляйте короткий `status`, например «3 результата»: polite live region объявит его, не читая весь список. Давайте названия всем своим кнопкам с иконкой. Для богатого списка используйте семантику списка/ссылок/кнопок; `listbox` требует отдельной реализации соответствующего combobox-паттерна.
+
+### Чего избегать
+
+- Не заменяйте Search небольшой статический список навигации.
+- Не помещайте больше двух trailing-действий в раскрытую строку; clear считается одним из них.
+- Не позволяйте запоздалому ответу сервера вновь открыть закрытый поиск или перевести фокус в его поле.
+- Не считайте `type="search"` у M3TextField полноценным Search.
+
+## API
+
+| Экспорт | Назначение |
+| --- | --- |
+| `M3Search` | Строка входа и модальная раскрытая область. |
+| `M3SearchProps`, `M3SearchExposed`, `SearchResultsContext` | Типизированный контракт, методы и контекст результатов. |
+
+| Свойство / callback | По умолчанию | Действие |
+| --- | --- | --- |
+| `query`, `onQueryChange` | обязательны | Управляемый текст и запрос обновления. |
+| `open`, `onOpenChange` | обязательны | Управляемое раскрытие и запрос от trigger/back/Escape/scrim. |
+| `label`, `status` | обязательны | Доступное имя и объявление результата. |
+| `hint` | `label` | Видимая подсказка при пустом запросе. |
+| `appearance` | `contained` | `contained` или `divided`. |
+| `layout` | `auto` | `auto`, `full-screen` или `docked`. |
+| `backLabel`, `clearLabel` | английский текст | Доступные имена встроенных кнопок; переведите их. |
+| `onSubmit` | — | Вызывается по Enter с текущим запросом. |
+| HTML-атрибуты | — | Передаются корню свёрнутого поиска. |
+
+| Именованный потомок | Назначение |
+| --- | --- |
+| `M3Search.Leading` | Необязательное действие в начале свёрнутой строки; иначе у trigger декоративная лупа. |
+| `M3Search.Trailing` | Действия в конце свёрнутой строки. |
+| `M3Search.Actions` | Действия раскрытой строки после clear. |
+| `M3Search.Results` | Содержимое; `render={({ query, close, submit }) => ...}` получает текущий контекст. Без Results используются обычные children. |
+
+Ref открывает методы `open()`, `close()` и `focus()`. Первые два запрашивают смену управляемого состояния; родитель обновляет его сам.
+
+## Источники
+
+- [Обзор Material Search](https://m3.material.io/components/search/overview)
+- [Размеры и токены](https://m3.material.io/components/search/specs)
+- [Рекомендации](https://m3.material.io/components/search/guidelines)
+- [Доступность](https://m3.material.io/components/search/accessibility)
+
+</Localized>
diff --git a/m3-react/storybook/components/M3Search.stories.tsx b/m3-react/storybook/components/M3Search.stories.tsx
new file mode 100644
index 0000000..ba9262e
--- /dev/null
+++ b/m3-react/storybook/components/M3Search.stories.tsx
@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { M3Search } from '@/components/search'
+
+import SearchExample from '../examples/search/SearchExample'
+
+const meta = {
+  title: 'Components/M3Search',
+  component: M3Search,
+  args: {
+    appearance: 'contained',
+    layout: 'auto',
+    query: '',
+    label: 'Search your messages',
+    status: '',
+    open: false,
+    onQueryChange: () => {},
+    onOpenChange: () => {},
+  },
+  argTypes: {
+    appearance: { control: 'select', options: ['contained', 'divided'] },
+    layout: { control: 'select', options: ['auto', 'full-screen', 'docked'] },
+    query: { control: false },
+    open: { control: false },
+    status: { control: false },
+    onQueryChange: { control: false },
+    onOpenChange: { control: false },
+    onSubmit: { control: false },
+  },
+  render: (args, { globals }) => (
+    <SearchExample appearance={args.appearance} layout={args.layout} locale={globals.locale} />
+  ),
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof M3Search>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const AdaptiveContained: Story = {}
+export const DockedContained: Story = { args: { layout: 'docked' } }
+export const FullScreenContained: Story = { args: { layout: 'full-screen' } }
+export const DockedDivided: Story = { args: { layout: 'docked', appearance: 'divided' } }
+export const FullScreenDivided: Story = { args: { layout: 'full-screen', appearance: 'divided' } }
+export const ProgrammaticOpen: Story = {
+  render: (args, { globals }) => (
+    <SearchExample appearance={args.appearance} layout={args.layout} locale={globals.locale} externalTrigger />
+  ),
+}
+export const InitiallyOpen: Story = {
+  render: (args, { globals }) => (
+    <SearchExample appearance={args.appearance} layout={args.layout} locale={globals.locale} initialOpen />
+  ),
+}
diff --git a/m3-react/storybook/examples/search/SearchExample.tsx b/m3-react/storybook/examples/search/SearchExample.tsx
new file mode 100644
index 0000000..1dc516e
--- /dev/null
+++ b/m3-react/storybook/examples/search/SearchExample.tsx
@@ -0,0 +1,125 @@
+import type {
+  SearchAppearance,
+  SearchLayout,
+} from '@modulify/m3-foundation/types/components/search'
+
+import { useState } from 'react'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import { M3List, M3ListItem } from '@/components/list'
+import { M3Search } from '@/components/search'
+
+import { localize } from '../../i18n'
+
+const messages = {
+  'en-US': {
+    heading: 'Mail',
+    hint: 'Search your messages',
+    back: 'Back to mail',
+    clear: 'Clear search',
+    example: 'Use a recent query',
+    open: 'Open search programmatically',
+    recent: 'Recent searches',
+    suggestions: 'Suggestions',
+    results: 'Results',
+    inbox: 'Inbox',
+    cards: ['Planning the next release', 'Notes from yesterday', 'Design review', 'Project status'],
+  },
+  'ru-RU': {
+    heading: 'Почта',
+    hint: 'Поиск по сообщениям',
+    back: 'Назад к почте',
+    clear: 'Очистить поиск',
+    example: 'Вставить недавний запрос',
+    open: 'Открыть поиск программно',
+    recent: 'Недавние запросы',
+    suggestions: 'Подсказки',
+    results: 'Результаты',
+    inbox: 'Входящие',
+    cards: ['План следующего выпуска', 'Заметки за вчера', 'Обзор дизайна', 'Состояние проекта'],
+  },
+}
+
+interface SearchExampleProps {
+  appearance?: SearchAppearance;
+  layout?: SearchLayout;
+  locale: string;
+  initialOpen?: boolean;
+  externalTrigger?: boolean;
+}
+
+export default function SearchExample({
+  appearance = 'contained',
+  layout = 'auto',
+  locale,
+  initialOpen = false,
+  externalTrigger = false,
+}: SearchExampleProps) {
+  const text = localize(locale, messages)
+  const [query, setQuery] = useState('')
+  const [open, setOpen] = useState(initialOpen)
+  const [submitted, setSubmitted] = useState(false)
+  const matching = text.cards.filter(item => item.toLocaleLowerCase(locale).includes(query.toLocaleLowerCase(locale)))
+  const entries = query ? matching : text.cards.slice(0, 3)
+  const section = submitted ? text.results : query ? text.suggestions : text.recent
+  const status = `${section}: ${entries.length}`
+
+  const updateQuery = (value: string) => {
+    setQuery(value)
+    setSubmitted(false)
+  }
+  const choose = (value: string) => {
+    setQuery(value)
+  }
+
+  return (
+    <main style={{ minHeight: '100vh', padding: '24px', background: 'var(--m3-sys-surface-container-low)' }}>
+      <div style={{ maxWidth: 880, marginInline: 'auto' }}>
+        <header style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', justifyContent: 'space-between', gap: 16, marginBlockEnd: 16 }}>
+          <h1 style={{ margin: 0 }}>{text.heading}</h1>
+          {externalTrigger ? <M3Button onClick={() => setOpen(true)}>{text.open}</M3Button> : null}
+        </header>
+        <M3Search
+          appearance={appearance}
+          layout={layout}
+          label={text.hint}
+          hint={text.hint}
+          backLabel={text.back}
+          clearLabel={text.clear}
+          query={query}
+          status={status}
+          open={open}
+          onQueryChange={updateQuery}
+          onOpenChange={setOpen}
+          onSubmit={() => setSubmitted(true)}
+        >
+          <M3Search.Actions>
+            <M3IconButton aria-label={text.example} onClick={() => updateQuery(text.cards[0])}><M3Icon name="history" /></M3IconButton>
+          </M3Search.Actions>
+          <M3Search.Results render={({ close }) => (
+            <>
+              <p style={{ margin: '8px 16px', color: 'var(--m3-sys-on-surface-variant)' }}>{section}</p>
+              <M3List>
+                {entries.map(entry => (
+                  <M3ListItem key={entry} headline={entry} onClick={() => { choose(entry); close() }}>
+                    <M3ListItem.Leading><M3Icon name={query ? 'mail' : 'history'} /></M3ListItem.Leading>
+                  </M3ListItem>
+                ))}
+              </M3List>
+            </>
+          )} />
+        </M3Search>
+        <h2 style={{ marginBlock: '32px 16px' }}>{text.inbox}</h2>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 16 }}>
+          {text.cards.map(card => (
+            <article key={card} style={{ minHeight: 96, padding: 20, borderRadius: 24, background: 'var(--m3-sys-surface-container)' }}>
+              {card}
+            </article>
+          ))}
+        </div>
+      </div>
+    </main>
+  )
+}
diff --git a/m3-react/tests/M3Search.e2e.tsx b/m3-react/tests/M3Search.e2e.tsx
new file mode 100644
index 0000000..b2a1ae9
--- /dev/null
+++ b/m3-react/tests/M3Search.e2e.tsx
@@ -0,0 +1,49 @@
+import { act, fireEvent } from '@testing-library/react'
+import { page } from 'vitest/browser'
+import { render, screen } from '@testing-library/react'
+import { useState } from 'react'
+import { waitFor } from '@testing-library/react'
+
+import { M3Search } from '@/components/search'
+
+const SearchHarness = () => {
+  const [query, setQuery] = useState('')
+  const [open, setOpen] = useState(false)
+
+  return <M3Search
+    query={query}
+    open={open}
+    label="Search messages"
+    status="Results"
+    onQueryChange={setQuery}
+    onOpenChange={setOpen}
+  />
+}
+
+test('adapts an open search without losing the query or overflowing the viewport', async () => {
+  await page.viewport(390, 760)
+  const view = render(<SearchHarness />)
+
+  try {
+    fireEvent.click(screen.getByRole('button', { name: 'Search messages' }))
+    const input = screen.getByRole('searchbox', { name: 'Search messages' }) as HTMLInputElement
+    fireEvent.change(input, { target: { value: 'notes' } })
+
+    const dialog = screen.getByRole('dialog', { name: 'Search messages' })
+    expect(dialog.classList.contains('m3-search__view_full-screen')).toBe(true)
+    expect(getComputedStyle(document.querySelector('.m3-search__bar')!).visibility).toBe('hidden')
+    expect(dialog.offsetWidth).toBe(390)
+    expect(document.documentElement.scrollWidth).toBeLessThanOrEqual(390)
+
+    await act(async () => { await page.viewport(900, 760) })
+    await waitFor(() => expect(dialog.classList.contains('m3-search__view_docked')).toBe(true))
+    const docked = dialog.getBoundingClientRect()
+    expect(docked.width).toBeLessThanOrEqual(720)
+    expect(docked.left).toBeGreaterThanOrEqual(12)
+    expect(docked.right).toBeLessThanOrEqual(888)
+    expect(input.value).toBe('notes')
+    expect(document.activeElement).toBe(input)
+  } finally {
+    view.unmount()
+  }
+})
diff --git a/m3-react/tests/M3Search.test.tsx b/m3-react/tests/M3Search.test.tsx
new file mode 100644
index 0000000..cd3094d
--- /dev/null
+++ b/m3-react/tests/M3Search.test.tsx
@@ -0,0 +1,106 @@
+import type { M3SearchExposed } from '@/components/search'
+
+import { act } from '@testing-library/react'
+import { createRef } from 'react'
+import { fireEvent, render, screen } from '@testing-library/react'
+import { useState } from 'react'
+
+import { M3Search } from '@/components/search'
+
+const SearchHarness = ({ onSubmit = () => {} }: { onSubmit?: (query: string) => void }) => {
+  const [query, setQuery] = useState('')
+  const [open, setOpen] = useState(false)
+
+  return (
+    <>
+      <button type="button">Outside</button>
+      <M3Search
+        query={query}
+        open={open}
+        label="Search messages"
+        status={query ? '1 result' : '2 suggestions'}
+        onQueryChange={setQuery}
+        onOpenChange={setOpen}
+        onSubmit={onSubmit}
+      >
+        <M3Search.Results render={({ close }) => (
+          <div>
+            <button type="button" onClick={close}>First result</button>
+            <button type="button">Second result</button>
+          </div>
+        )} />
+      </M3Search>
+    </>
+  )
+}
+
+describe('m3-react/search', () => {
+  test('opens from the bar, edits and submits while keeping the query visible', () => {
+    const onSubmit = vi.fn()
+    render(<SearchHarness onSubmit={onSubmit} />)
+    const trigger = screen.getByRole('button', { name: 'Search messages' })
+    trigger.focus()
+    fireEvent.click(trigger)
+
+    const dialog = screen.getByRole('dialog', { name: 'Search messages' })
+    const input = screen.getByRole('searchbox', { name: 'Search messages' }) as HTMLInputElement
+    expect(dialog.getAttribute('aria-modal')).toBe('true')
+    expect(document.activeElement).toBe(input)
+    expect(screen.getByRole('status').textContent).toBe('2 suggestions')
+
+    fireEvent.change(input, { target: { value: 'plan' } })
+    expect(input.value).toBe('plan')
+    expect(screen.getByRole('status').textContent).toBe('1 result')
+    fireEvent.submit(input.closest('form')!)
+    expect(onSubmit).toHaveBeenCalledWith('plan')
+    expect(input.value).toBe('plan')
+    expect(document.activeElement).toBe(dialog.querySelector('.m3-search__results'))
+  })
+
+  test('navigates results, clears input and returns focus after Escape', async () => {
+    render(<SearchHarness />)
+    const trigger = screen.getByRole('button', { name: 'Search messages' })
+    trigger.focus()
+    fireEvent.click(trigger)
+    const input = screen.getByRole('searchbox', { name: 'Search messages' })
+
+    fireEvent.keyDown(input, { key: 'ArrowDown' })
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'First result' }))
+    fireEvent.keyDown(document.activeElement!, { key: 'ArrowDown' })
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Second result' }))
+
+    fireEvent.change(input, { target: { value: 'draft' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Clear search' }))
+    expect((input as HTMLInputElement).value).toBe('')
+    expect(document.activeElement).toBe(input)
+
+    fireEvent.keyDown(document, { key: 'Escape' })
+    await act(async () => { await Promise.resolve() })
+    expect(document.activeElement).toBe(trigger)
+    expect(trigger.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  test('selects a forced layout and exposes programmatic requests', () => {
+    const ref = createRef<M3SearchExposed>()
+    const onOpenChange = vi.fn()
+    render(
+      <M3Search
+        ref={ref}
+        query=""
+        open={true}
+        label="Search messages"
+        status="No results"
+        appearance="divided"
+        layout="docked"
+        onQueryChange={() => {}}
+        onOpenChange={onOpenChange}
+      />
+    )
+
+    expect(document.querySelector('.m3-search__view_divided.m3-search__view_docked')).not.toBeNull()
+    act(() => ref.current?.close())
+    act(() => ref.current?.open())
+    expect(onOpenChange).toHaveBeenNthCalledWith(1, false)
+    expect(onOpenChange).toHaveBeenNthCalledWith(2, true)
+  })
+})

From b47d9acbdcee6d0065e175774c98ea5ec1126dc0 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Wed, 7 Oct 2026 21:33:03 +0400
Subject: [PATCH 03/20] feat(m3-vue): Search component and examples were added

Closes #21
---
 m3-vue/src/components/index.ts                |   1 +
 m3-vue/src/components/search/M3Search.vue     | 295 ++++++++++++++++++
 m3-vue/src/components/search/index.ts         |   2 +
 m3-vue/src/components/search/types.ts         |  11 +
 m3-vue/storybook/components/M3Search.mdx      | 156 +++++++++
 .../storybook/components/M3Search.stories.ts  |  52 +++
 .../examples/search/SearchExample.vue         | 148 +++++++++
 m3-vue/tests/M3Search.e2e.ts                  |  66 ++++
 m3-vue/tests/M3Search.test.ts                 |  88 ++++++
 9 files changed, 819 insertions(+)
 create mode 100644 m3-vue/src/components/search/M3Search.vue
 create mode 100644 m3-vue/src/components/search/index.ts
 create mode 100644 m3-vue/src/components/search/types.ts
 create mode 100644 m3-vue/storybook/components/M3Search.mdx
 create mode 100644 m3-vue/storybook/components/M3Search.stories.ts
 create mode 100644 m3-vue/storybook/examples/search/SearchExample.vue
 create mode 100644 m3-vue/tests/M3Search.e2e.ts
 create mode 100644 m3-vue/tests/M3Search.test.ts

diff --git a/m3-vue/src/components/index.ts b/m3-vue/src/components/index.ts
index 167bc89..de0b141 100644
--- a/m3-vue/src/components/index.ts
+++ b/m3-vue/src/components/index.ts
@@ -19,6 +19,7 @@ export * from './radio'
 export * from './rich-tooltip'
 export * from './ripple'
 export * from './scroll-rail'
+export * from './search'
 export * from './select'
 export * from './side-sheet'
 export * from './snackbar'
diff --git a/m3-vue/src/components/search/M3Search.vue b/m3-vue/src/components/search/M3Search.vue
new file mode 100644
index 0000000..5cfc046
--- /dev/null
+++ b/m3-vue/src/components/search/M3Search.vue
@@ -0,0 +1,295 @@
+<template>
+    <div
+        :id="rootId"
+        v-bind="$attrs"
+        :class="{ 'm3-search': true, 'm3-search_open': open }"
+    >
+        <div ref="bar" class="m3-search__bar">
+            <div v-if="'leading' in $slots" class="m3-search__leading">
+                <slot name="leading" />
+            </div>
+            <button
+                :aria-label="accessibleName"
+                :aria-expanded="open"
+                :aria-controls="open ? viewId : undefined"
+                type="button"
+                class="m3-search__trigger"
+                aria-haspopup="dialog"
+                @click="emit('update:open', true)"
+            >
+                <span v-if="!('leading' in $slots)" class="m3-search__trigger-icon">
+                    <M3Icon name="search" aria-hidden="true" />
+                </span>
+                <span
+                    :class="{
+                        'm3-search__trigger-text': true,
+                        'm3-search__trigger-text_filled': query.length > 0,
+                    }"
+                >{{ query || displayHint }}</span>
+            </button>
+            <div v-if="'trailing' in $slots" class="m3-search__trailing">
+                <slot name="trailing" />
+            </div>
+        </div>
+    </div>
+
+    <Teleport to="body">
+        <Transition :duration="SEARCH_TRANSITION_MS" name="m3-search">
+            <div v-if="open" class="m3-search__overlay">
+                <div
+                    v-if="resolvedLayout === 'docked'"
+                    ref="scrim"
+                    class="m3-search__scrim"
+                    @click="close"
+                />
+                <div
+                    :id="viewId"
+                    ref="dialog"
+                    :style="viewStyle"
+                    :class="{
+                        'm3-search__view': true,
+                        ['m3-search__view_' + appearance]: true,
+                        ['m3-search__view_' + resolvedLayout]: true,
+                    }"
+                    :aria-label="label"
+                    role="dialog"
+                    aria-modal="true"
+                    tabindex="-1"
+                >
+                    <form role="search" class="m3-search__header" @submit.prevent="submit">
+                        <M3IconButton :aria-label="backLabel" @click="close">
+                            <M3Icon name="arrow_back" />
+                        </M3IconButton>
+                        <input
+                            ref="input"
+                            :value="query"
+                            :placeholder="displayHint"
+                            :aria-label="accessibleName"
+                            :aria-controls="resultsId"
+                            type="search"
+                            class="m3-search__input"
+                            @input="onInput"
+                            @keydown="onInputKeyDown"
+                        />
+                        <div class="m3-search__actions">
+                            <M3IconButton v-if="query" :aria-label="clearLabel" @click="clear">
+                                <M3Icon name="close" />
+                            </M3IconButton>
+                            <slot name="actions" />
+                        </div>
+                    </form>
+                    <div
+                        :id="resultsId"
+                        ref="results"
+                        class="m3-search__results"
+                        tabindex="-1"
+                        @keydown="onResultsKeyDown"
+                    >
+                        <slot name="results" v-bind="resultsContext">
+                            <slot />
+                        </slot>
+                    </div>
+                    <div class="m3-search__status" role="status" aria-live="polite">
+                        {{ status }}
+                    </div>
+                </div>
+            </div>
+        </Transition>
+    </Teleport>
+</template>
+
+<script lang="ts" setup>
+import type { M3SearchMethods } from './types'
+import type { PropType } from 'vue'
+import type {
+  SearchAnchorRect,
+  SearchAppearance,
+  SearchDockedPosition,
+  SearchLayout,
+} from '@modulify/m3-foundation/types/components/search'
+import type { SearchResultsContext } from './types'
+import type { SearchViewport } from '@modulify/m3-foundation/types/components/search'
+import type { VNode } from 'vue'
+
+import { activateModalFocus } from '@modulify/m3-foundation/lib/modal'
+import { computed } from 'vue'
+import { durations } from '@modulify/m3-foundation/lib/motion'
+import { getSearchDockedPosition } from '@modulify/m3-foundation/lib/search'
+import { getSearchRevealOrigin } from '@modulify/m3-foundation/lib/search'
+import { ref } from 'vue'
+import { resolveSearchLayout } from '@modulify/m3-foundation/lib/search'
+import { watch } from 'vue'
+
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+
+import { useBreakpoint } from '@/composables/breakpoint'
+import { useId } from '@/composables/id'
+
+defineOptions({ inheritAttrs: false })
+
+const SEARCH_TRANSITION_MS = durations.medium2
+
+const props = defineProps({
+  id: {
+    type: String,
+    default: undefined,
+  },
+  query: {
+    type: String,
+    required: true,
+  },
+  label: {
+    type: String,
+    required: true,
+  },
+  status: {
+    type: String,
+    required: true,
+  },
+  open: {
+    type: Boolean,
+    required: true,
+  },
+  hint: {
+    type: String,
+    default: undefined,
+  },
+  backLabel: {
+    type: String,
+    default: 'Back',
+  },
+  clearLabel: {
+    type: String,
+    default: 'Clear search',
+  },
+  appearance: {
+    type: String as PropType<SearchAppearance>,
+    default: 'contained',
+  },
+  layout: {
+    type: String as PropType<SearchLayout>,
+    default: 'auto',
+  },
+})
+
+const emit = defineEmits<{
+  'update:query': [query: string];
+  'update:open': [open: boolean];
+  submit: [query: string];
+}>()
+
+defineSlots<{
+  default?: () => VNode[];
+  leading?: () => VNode[];
+  trailing?: () => VNode[];
+  actions?: () => VNode[];
+  results?: (context: SearchResultsContext) => VNode[];
+}>()
+
+const bar = ref<HTMLElement | null>(null)
+const dialog = ref<HTMLElement | null>(null)
+const input = ref<HTMLInputElement | null>(null)
+const results = ref<HTMLElement | null>(null)
+const scrim = ref<HTMLElement | null>(null)
+const position = ref<SearchDockedPosition>({ left: 12, top: 12, width: 360 })
+const anchor = ref<SearchAnchorRect>({ left: 12, top: 12, width: 360 })
+const viewport = ref<SearchViewport>({ width: 384, height: 640 })
+
+const breakpoint = useBreakpoint()
+const rootId = useId('m3-search', computed(() => props.id))
+const viewId = computed(() => rootId.value + '-view')
+const resultsId = computed(() => rootId.value + '-results')
+const resolvedLayout = computed(() => resolveSearchLayout(props.layout, breakpoint.value.name))
+const displayHint = computed(() => props.hint ?? props.label)
+const accessibleName = computed(() => displayHint.value === props.label ? props.label : `${displayHint.value} ${props.label}`)
+const origin = computed(() => getSearchRevealOrigin(anchor.value, viewport.value, position.value, resolvedLayout.value))
+const viewStyle = computed(() => ({
+  '--m3-search-docked-left': `${position.value.left}px`,
+  '--m3-search-docked-top': `${position.value.top}px`,
+  '--m3-search-docked-width': `${position.value.width}px`,
+  '--m3-search-origin-left': `${origin.value.left}px`,
+  '--m3-search-origin-right': `${origin.value.right}px`,
+  '--m3-search-origin-offset-y': `${origin.value.offsetY}px`,
+}))
+
+const close = () => emit('update:open', false)
+const submit = () => {
+  emit('submit', props.query)
+  results.value?.focus()
+}
+const clear = () => {
+  emit('update:query', '')
+  input.value?.focus()
+}
+const onInput = (event: Event) => emit('update:query', (event.target as HTMLInputElement).value)
+const resultsContext = computed<SearchResultsContext>(() => ({ query: props.query, close, submit }))
+
+const resultSelector = 'a[href], button:not(:disabled), [tabindex="0"]'
+const focusResult = (last: boolean) => {
+  const items = results.value?.querySelectorAll<HTMLElement>(resultSelector)
+  const target = last ? items?.[items.length - 1] : items?.[0]
+  target?.focus()
+}
+const onInputKeyDown = (event: KeyboardEvent) => {
+  if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+    event.preventDefault()
+    focusResult(event.key === 'ArrowUp')
+  }
+}
+const onResultsKeyDown = (event: KeyboardEvent) => {
+  if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+  const items = [...(results.value?.querySelectorAll<HTMLElement>(resultSelector) ?? [])]
+  const current = items.indexOf(event.target as HTMLElement)
+  const next = event.key === 'ArrowDown'
+    ? items[Math.min(current + 1, items.length - 1)]
+    : items[Math.max(current - 1, 0)]
+  if (next) {
+    event.preventDefault()
+    next.focus()
+  }
+}
+
+defineExpose<M3SearchMethods>({
+  open: () => emit('update:open', true),
+  close,
+  focus: () => props.open ? input.value?.focus() : bar.value?.querySelector('button')?.focus(),
+})
+
+watch([() => props.open, resolvedLayout, bar], ([open, layout], _, onCleanup) => {
+  if (!open || !bar.value) return
+
+  const update = () => {
+    if (!bar.value) return
+    const rect = bar.value.getBoundingClientRect()
+    const nextViewport = {
+      width: window.innerWidth,
+      height: window.innerHeight,
+    }
+    anchor.value = { left: rect.left, top: rect.top, width: rect.width }
+    viewport.value = nextViewport
+    if (layout === 'docked') position.value = getSearchDockedPosition(rect, nextViewport)
+  }
+  const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update)
+  observer?.observe(bar.value)
+  window.addEventListener('resize', update)
+  window.addEventListener('scroll', update, true)
+  update()
+
+  onCleanup(() => {
+    observer?.disconnect()
+    window.removeEventListener('resize', update)
+    window.removeEventListener('scroll', update, true)
+  })
+}, { immediate: true, flush: 'post' })
+
+watch([() => props.open, dialog], ([open, element], _, onCleanup) => {
+  if (!open || !element) return
+  onCleanup(activateModalFocus({
+    dialog: element,
+    exempt: () => [scrim.value],
+    onEscape: close,
+  }))
+  input.value?.focus()
+}, { immediate: true, flush: 'post' })
+</script>
diff --git a/m3-vue/src/components/search/index.ts b/m3-vue/src/components/search/index.ts
new file mode 100644
index 0000000..cb5365d
--- /dev/null
+++ b/m3-vue/src/components/search/index.ts
@@ -0,0 +1,2 @@
+export { default as M3Search } from './M3Search.vue'
+export type { M3SearchMethods, SearchResultsContext } from './types'
diff --git a/m3-vue/src/components/search/types.ts b/m3-vue/src/components/search/types.ts
new file mode 100644
index 0000000..859acd5
--- /dev/null
+++ b/m3-vue/src/components/search/types.ts
@@ -0,0 +1,11 @@
+export interface SearchResultsContext {
+  query: string;
+  close(): void;
+  submit(): void;
+}
+
+export interface M3SearchMethods {
+  open(): void;
+  close(): void;
+  focus(): void;
+}
diff --git a/m3-vue/storybook/components/M3Search.mdx b/m3-vue/storybook/components/M3Search.mdx
new file mode 100644
index 0000000..ed62c40
--- /dev/null
+++ b/m3-vue/storybook/components/M3Search.mdx
@@ -0,0 +1,156 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import { Localized } from '../i18n'
+import * as M3SearchStories from './M3Search.stories'
+
+<Meta of={M3SearchStories} />
+
+<Localized locale="en-US">
+
+# Search
+
+Search combines a persistent entry bar with an expanded area for suggestions or results. Use it for a large collection and place it near the content it searches. The [Material 3 guidelines](https://m3.material.io/components/search/guidelines) recommend the contained style for new interfaces; the divided baseline style remains available.
+
+## Guide
+
+### Appearance and layout
+
+Contained keeps a rounded filled bar in the expanded view. Divided separates the input header and results with a divider. `layout="auto"` opens full screen below 600 px and docked on wider windows. Both expanded layouts are modal in this web implementation; docked has a scrim. Use a fixed layout only if the surrounding product needs one.
+
+The results container starts empty. Add an `M3List` or your own content in `#results`. Recent queries may appear before typing; suggestions while typing; results after submission. The application handles data requests, filtering, ranking, grouping, empty/error states, and result navigation.
+
+### Query, focus, and accessibility
+
+Use `v-model:query` and `v-model:open`. `submit` emits the current query. Submitting retains the query and moves focus from the input to the results area. Back, Escape, and the docked scrim request closing; focus returns to the original control. Arrow Down/Up enters and navigates result controls. `Tab` follows the dialog's controls.
+
+Give `label` a localized description of the searchable content. `hint` is the visible prompt and defaults to `label`. When they differ, the control's accessible name includes both. Translate `backLabel` and `clearLabel`. Update the short localized `status` when suggestions/results change; its polite live region announces the change without speaking the whole list. Label custom icon buttons. A rich list with links and buttons should keep native list/link/button semantics, not pretend to be a listbox without the complete combobox behavior.
+
+### Avoid
+
+- Do not substitute Search for a small static navigation list.
+- Do not place more than two trailing actions in the expanded bar; count clear as one.
+- Do not let an outdated async response reopen a closed search or refocus its input.
+- Do not treat `type="search"` on M3TextField as the complete Search pattern.
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `M3Search` | Entry bar and modal expanded search view. |
+| `M3SearchMethods`, `SearchResultsContext` | Exposed methods and typed result slot properties. |
+
+| Prop / event | Default | Effect |
+| --- | --- | --- |
+| `query`, `update:query` | required | Controlled input value and update. |
+| `open`, `update:open` | required | Controlled expanded state, trigger/back/Escape/scrim update. |
+| `label`, `status` | required | Accessible name and polite result announcement. |
+| `hint` | `label` | Visible prompt when the query is empty. |
+| `appearance` | `contained` | `contained` or `divided`. |
+| `layout` | `auto` | `auto`, `full-screen`, or `docked`. |
+| `backLabel`, `clearLabel` | English labels | Accessible built-in button names; translate them. |
+| `submit` | — | Emits the current query on Enter. |
+| HTML attributes | — | Passed to the collapsed root. |
+
+| Slot | Purpose |
+| --- | --- |
+| `#leading` | Optional collapsed-bar leading control; otherwise the trigger contains a decorative search icon. |
+| `#trailing` | Collapsed-bar trailing actions. |
+| `#actions` | Expanded-bar trailing actions after clear. |
+| `#results="{ query, close, submit }"` | Results content and controls. The default slot is used when `#results` is absent. |
+
+The template ref exposes `open()`, `close()`, and `focus()`. The first two emit `update:open`; the parent owns the state.
+
+```vue
+<M3Search
+  v-model:query="query"
+  v-model:open="open"
+  label="Search messages"
+  :status="`${results.length} results`"
+  @submit="search"
+>
+  <template #results="{ close }">
+    <M3List>
+      <M3ListItem
+        v-for="item in results"
+        :key="item.id"
+        :headline="item.title"
+        interactive
+        @click="select(item); close()"
+      />
+    </M3List>
+  </template>
+</M3Search>
+```
+
+## Sources
+
+- [Material Search overview](https://m3.material.io/components/search/overview)
+- [Material Search specs](https://m3.material.io/components/search/specs)
+- [Material Search guidelines](https://m3.material.io/components/search/guidelines)
+- [Material Search accessibility](https://m3.material.io/components/search/accessibility)
+- [WAI-ARIA Combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+
+</Localized>
+
+<Localized locale="ru-RU">
+
+# Поиск
+
+Search объединяет постоянную строку входа и раскрытую область подсказок или результатов. Используйте его для большого набора объектов и ставьте рядом с искомым содержимым. [Material 3](https://m3.material.io/components/search/guidelines) рекомендует contained для новых интерфейсов; baseline divided остаётся доступен.
+
+## Руководство
+
+### Вид и расположение
+
+Contained сохраняет округлую заполненную строку после раскрытия. Divided отделяет заголовок от результатов линией. `layout="auto"` выбирает полный экран при ширине меньше 600 px и docked при большей. Оба раскрытых layout в этой веб-реализации модальные; docked затемняет фон. Фиксируйте layout, когда этого требует компоновка продукта.
+
+Контейнер результатов по умолчанию пуст. Передайте `M3List` или своё содержимое в `#results`. До ввода можно показывать историю, во время ввода — подсказки, после отправки — результаты. Запросы к серверу, фильтрация, сортировка, группы, пустое/ошибочное состояние и переход к результату принадлежат приложению.
+
+### Запрос, фокус и доступность
+
+Используйте `v-model:query` и `v-model:open`. Событие `submit` передаёт текущий запрос. После Enter текст остаётся видимым, а фокус переходит из поля в область результатов. Кнопка назад, Escape и затемнение docked запрашивают закрытие; фокус возвращается к инициатору. Стрелки вниз/вверх переводят фокус к действиям результатов и между ними. `Tab` идёт по элементам диалога.
+
+Локализованная `label` должна описывать содержимое поиска. `hint` — видимая подсказка, по умолчанию совпадающая с `label`. Если они различаются, доступное имя включает оба текста. Переведите `backLabel` и `clearLabel`. Обновляйте краткий локализованный `status` при изменении подсказок/результатов: polite live region объявит его без чтения всего списка. Дайте имена своим кнопкам с иконками. Богатому списку со ссылками и кнопками нужна семантика списка/ссылок/кнопок, а не неполный `listbox`.
+
+### Чего избегать
+
+- Не заменяйте Search небольшой статический список навигации.
+- Не помещайте больше двух trailing-действий в раскрытую строку; clear — одно из них.
+- Не позволяйте запоздалому ответу сервера открыть закрытый поиск или сфокусировать его поле.
+- Не считайте `type="search"` у M3TextField полноценным Search.
+
+## API
+
+| Экспорт | Назначение |
+| --- | --- |
+| `M3Search` | Строка входа и модальная раскрытая область. |
+| `M3SearchMethods`, `SearchResultsContext` | Открытые методы и типы свойств слота результатов. |
+
+| Свойство / событие | По умолчанию | Действие |
+| --- | --- | --- |
+| `query`, `update:query` | обязательны | Управляемый текст и его обновление. |
+| `open`, `update:open` | обязательны | Управляемое раскрытие и обновление от trigger/back/Escape/scrim. |
+| `label`, `status` | обязательны | Доступное имя и объявление результатов. |
+| `hint` | `label` | Видимая подсказка при пустом запросе. |
+| `appearance` | `contained` | `contained` или `divided`. |
+| `layout` | `auto` | `auto`, `full-screen` или `docked`. |
+| `backLabel`, `clearLabel` | английский текст | Доступные имена встроенных кнопок; переведите их. |
+| `submit` | — | Передаёт запрос по Enter. |
+| HTML-атрибуты | — | Передаются корню свёрнутого поиска. |
+
+| Слот | Назначение |
+| --- | --- |
+| `#leading` | Необязательное действие в начале свёрнутой строки; иначе в trigger есть декоративная лупа. |
+| `#trailing` | Действия в конце свёрнутой строки. |
+| `#actions` | Действия раскрытой строки после clear. |
+| `#results="{ query, close, submit }"` | Содержимое и действия результатов; при отсутствии используется default. |
+
+Template ref открывает `open()`, `close()` и `focus()`. Первые два посылают `update:open`; состояние остаётся у родителя.
+
+## Источники
+
+- [Обзор Material Search](https://m3.material.io/components/search/overview)
+- [Размеры и токены](https://m3.material.io/components/search/specs)
+- [Рекомендации](https://m3.material.io/components/search/guidelines)
+- [Доступность](https://m3.material.io/components/search/accessibility)
+
+</Localized>
diff --git a/m3-vue/storybook/components/M3Search.stories.ts b/m3-vue/storybook/components/M3Search.stories.ts
new file mode 100644
index 0000000..307c264
--- /dev/null
+++ b/m3-vue/storybook/components/M3Search.stories.ts
@@ -0,0 +1,52 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3Search } from '@/components/search'
+
+import SearchExample from '../examples/search/SearchExample.vue'
+
+const meta = {
+  title: 'Components/M3Search',
+  component: M3Search,
+  args: {
+    appearance: 'contained',
+    layout: 'auto',
+    query: '',
+    open: false,
+    label: 'Search your messages',
+    status: '',
+  },
+  argTypes: {
+    appearance: { control: 'select', options: ['contained', 'divided'] },
+    layout: { control: 'select', options: ['auto', 'full-screen', 'docked'] },
+  },
+  render: (args: Record<string, unknown>, { globals }) => ({
+    components: { SearchExample },
+    setup: () => ({ appearance: args.appearance, layout: args.layout, locale: globals.locale }),
+    template: '<SearchExample :appearance="appearance" :layout="layout" :locale="locale" />',
+  }),
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof M3Search>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const AdaptiveContained: Story = {}
+export const DockedContained: Story = { args: { layout: 'docked' } }
+export const FullScreenContained: Story = { args: { layout: 'full-screen' } }
+export const DockedDivided: Story = { args: { layout: 'docked', appearance: 'divided' } }
+export const FullScreenDivided: Story = { args: { layout: 'full-screen', appearance: 'divided' } }
+export const ProgrammaticOpen: Story = {
+  render: (args: Record<string, unknown>, { globals }) => ({
+    components: { SearchExample },
+    setup: () => ({ appearance: args.appearance, layout: args.layout, locale: globals.locale }),
+    template: '<SearchExample :appearance="appearance" :layout="layout" :locale="locale" external-trigger />',
+  }),
+}
+export const InitiallyOpen: Story = {
+  render: (args: Record<string, unknown>, { globals }) => ({
+    components: { SearchExample },
+    setup: () => ({ appearance: args.appearance, layout: args.layout, locale: globals.locale }),
+    template: '<SearchExample :appearance="appearance" :layout="layout" :locale="locale" initial-open />',
+  }),
+}
diff --git a/m3-vue/storybook/examples/search/SearchExample.vue b/m3-vue/storybook/examples/search/SearchExample.vue
new file mode 100644
index 0000000..083bd18
--- /dev/null
+++ b/m3-vue/storybook/examples/search/SearchExample.vue
@@ -0,0 +1,148 @@
+<template>
+    <main class="search-example">
+        <div class="search-example__content">
+            <header class="search-example__header">
+                <h1>{{ text.heading }}</h1>
+                <M3Button v-if="externalTrigger" @click="open = true">
+                    {{ text.open }}
+                </M3Button>
+            </header>
+            <M3Search
+                v-model:query="query"
+                v-model:open="open"
+                :appearance="appearance"
+                :layout="layout"
+                :label="text.hint"
+                :hint="text.hint"
+                :back-label="text.back"
+                :clear-label="text.clear"
+                :status="status"
+                @submit="submitted = true"
+                @update:query="submitted = false"
+            >
+                <template #actions>
+                    <M3IconButton :aria-label="text.example" @click="query = text.cards[0]">
+                        <M3Icon name="history" />
+                    </M3IconButton>
+                </template>
+                <template #results>
+                    <p class="search-example__section">
+                        {{ section }}
+                    </p>
+                    <M3List>
+                        <M3ListItem
+                            v-for="entry in entries"
+                            :key="entry"
+                            :headline="entry"
+                            interactive
+                            @click="choose(entry)"
+                        >
+                            <template #leading>
+                                <M3Icon :name="query ? 'mail' : 'history'" />
+                            </template>
+                        </M3ListItem>
+                    </M3List>
+                </template>
+            </M3Search>
+            <h2>{{ text.inbox }}</h2>
+            <div class="search-example__grid">
+                <article v-for="card in text.cards" :key="card">
+                    {{ card }}
+                </article>
+            </div>
+        </div>
+    </main>
+</template>
+
+<script lang="ts" setup>
+import type { PropType } from 'vue'
+import type {
+  SearchAppearance,
+  SearchLayout,
+} from '@modulify/m3-foundation/types/components/search'
+
+import { computed, ref } from 'vue'
+
+import { M3Button } from '@/components/button'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import { M3List, M3ListItem } from '@/components/list'
+import { M3Search } from '@/components/search'
+
+import { localize } from '../../i18n'
+
+const messages = {
+  'en-US': {
+    heading: 'Mail', hint: 'Search your messages', back: 'Back to mail', clear: 'Clear search', example: 'Use a recent query', open: 'Open search programmatically', recent: 'Recent searches', suggestions: 'Suggestions', results: 'Results', inbox: 'Inbox',
+    cards: ['Planning the next release', 'Notes from yesterday', 'Design review', 'Project status'],
+  },
+  'ru-RU': {
+    heading: 'Почта', hint: 'Поиск по сообщениям', back: 'Назад к почте', clear: 'Очистить поиск', example: 'Вставить недавний запрос', open: 'Открыть поиск программно', recent: 'Недавние запросы', suggestions: 'Подсказки', results: 'Результаты', inbox: 'Входящие',
+    cards: ['План следующего выпуска', 'Заметки за вчера', 'Обзор дизайна', 'Состояние проекта'],
+  },
+}
+
+const props = defineProps({
+  appearance: { type: String as PropType<SearchAppearance>, default: 'contained' },
+  layout: { type: String as PropType<SearchLayout>, default: 'auto' },
+  locale: { type: String, default: 'en-US' },
+  initialOpen: { type: Boolean, default: false },
+  externalTrigger: { type: Boolean, default: false },
+})
+
+const text = computed(() => localize(props.locale, messages))
+const query = ref('')
+const open = ref(props.initialOpen)
+const submitted = ref(false)
+const matching = computed(() => text.value.cards.filter(item => item.toLocaleLowerCase(props.locale).includes(query.value.toLocaleLowerCase(props.locale))))
+const entries = computed(() => query.value ? matching.value : text.value.cards.slice(0, 3))
+const section = computed(() => submitted.value ? text.value.results : query.value ? text.value.suggestions : text.value.recent)
+const status = computed(() => `${section.value}: ${entries.value.length}`)
+const choose = (value: string) => {
+  query.value = value
+  open.value = false
+}
+</script>
+
+<style scoped>
+.search-example {
+  min-block-size: 100vh;
+  padding: 24px;
+  background: var(--m3-sys-surface-container-low);
+}
+
+.search-example__content {
+  max-inline-size: 880px;
+  margin-inline: auto;
+}
+
+.search-example__header {
+  display: flex;
+  margin-block-end: 16px;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 16px;
+  justify-content: space-between;
+}
+
+.search-example__header h1 { margin: 0; }
+h2 { margin-block: 32px 16px; }
+
+.search-example__section {
+  margin: 8px 16px;
+  color: var(--m3-sys-on-surface-variant);
+}
+
+.search-example__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 16px;
+}
+
+.search-example__grid article {
+  min-block-size: 96px;
+  padding: 20px;
+  border-radius: 24px;
+  background: var(--m3-sys-surface-container);
+}
+</style>
diff --git a/m3-vue/tests/M3Search.e2e.ts b/m3-vue/tests/M3Search.e2e.ts
new file mode 100644
index 0000000..f43f015
--- /dev/null
+++ b/m3-vue/tests/M3Search.e2e.ts
@@ -0,0 +1,66 @@
+import { createApp, h, nextTick } from 'vue'
+import { page } from 'vitest/browser'
+import { ref } from 'vue'
+
+import { M3Search } from '@/components/search'
+
+const waitFor = async (assertion: () => void) => {
+  const startedAt = performance.now()
+
+  while (performance.now() - startedAt < 2000) {
+    try {
+      assertion()
+      return
+    } catch {
+      await new Promise(resolve => setTimeout(resolve, 16))
+    }
+  }
+
+  assertion()
+}
+
+test('adapts an open search without losing the query or overflowing the viewport', async () => {
+  await page.viewport(390, 760)
+  const query = ref('')
+  const open = ref(false)
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const app = createApp({
+    render: () => h(M3Search, {
+      query: query.value,
+      open: open.value,
+      label: 'Search messages',
+      status: 'Results',
+      'onUpdate:query': (value: string) => query.value = value,
+      'onUpdate:open': (value: boolean) => open.value = value,
+    }),
+  })
+  app.mount(mountPoint)
+
+  try {
+    (mountPoint.querySelector('.m3-search__trigger') as HTMLButtonElement).click()
+    await nextTick()
+    const input = document.querySelector('.m3-search__input') as HTMLInputElement
+    input.value = 'notes'
+    input.dispatchEvent(new Event('input', { bubbles: true }))
+    await nextTick()
+
+    const dialog = document.querySelector('.m3-search__view') as HTMLElement
+    expect(dialog.classList.contains('m3-search__view_full-screen')).toBe(true)
+    expect(getComputedStyle(document.querySelector('.m3-search__bar')!).visibility).toBe('hidden')
+    expect(dialog.offsetWidth).toBe(390)
+    expect(document.documentElement.scrollWidth).toBeLessThanOrEqual(390)
+
+    await page.viewport(900, 760)
+    await waitFor(() => expect(dialog.classList.contains('m3-search__view_docked')).toBe(true))
+    const docked = dialog.getBoundingClientRect()
+    expect(docked.width).toBeLessThanOrEqual(720)
+    expect(docked.left).toBeGreaterThanOrEqual(12)
+    expect(docked.right).toBeLessThanOrEqual(888)
+    expect(input.value).toBe('notes')
+    expect(document.activeElement).toBe(input)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
diff --git a/m3-vue/tests/M3Search.test.ts b/m3-vue/tests/M3Search.test.ts
new file mode 100644
index 0000000..581b208
--- /dev/null
+++ b/m3-vue/tests/M3Search.test.ts
@@ -0,0 +1,88 @@
+import { defineComponent } from 'vue'
+import { fireEvent } from '@testing-library/vue'
+import { h, nextTick, ref } from 'vue'
+import { render, screen } from '@testing-library/vue'
+
+import { M3Search } from '@/components/search'
+
+const mountSearch = (onSubmit = vi.fn()) => {
+  const query = ref('')
+  const open = ref(false)
+  render(defineComponent({
+    setup: () => () => h('div', [
+      h('button', 'Outside'),
+      h(M3Search, {
+        query: query.value,
+        open: open.value,
+        label: 'Search messages',
+        status: query.value ? '1 result' : '2 suggestions',
+        'onUpdate:query': (value: string) => query.value = value,
+        'onUpdate:open': (value: boolean) => open.value = value,
+        onSubmit,
+      }, {
+        results: () => h('div', [h('button', 'First result'), h('button', 'Second result')]),
+      }),
+    ]),
+  }))
+  return { open, onSubmit }
+}
+
+describe('m3-vue/search', () => {
+  test('opens, edits and submits without losing the query', async () => {
+    const { onSubmit } = mountSearch()
+    const trigger = screen.getByRole('button', { name: 'Search messages' })
+    trigger.focus()
+    await fireEvent.click(trigger)
+    await nextTick()
+
+    const dialog = screen.getByRole('dialog', { name: 'Search messages' })
+    const input = screen.getByRole('searchbox', { name: 'Search messages' }) as HTMLInputElement
+    expect(dialog.getAttribute('aria-modal')).toBe('true')
+    expect(document.activeElement).toBe(input)
+    expect(screen.getByRole('status').textContent).toBe('2 suggestions')
+
+    await fireEvent.update(input, 'plan')
+    expect(input.value).toBe('plan')
+    expect(screen.getByRole('status').textContent).toBe('1 result')
+    await fireEvent.submit(input.closest('form')!)
+    expect(onSubmit).toHaveBeenCalledWith('plan')
+    expect(input.value).toBe('plan')
+    expect(document.activeElement).toBe(dialog.querySelector('.m3-search__results'))
+  })
+
+  test('navigates results, clears and closes with focus restoration', async () => {
+    const { open } = mountSearch()
+    const trigger = screen.getByRole('button', { name: 'Search messages' })
+    trigger.focus()
+    await fireEvent.click(trigger)
+    await nextTick()
+    const input = screen.getByRole('searchbox', { name: 'Search messages' }) as HTMLInputElement
+
+    await fireEvent.keyDown(input, { key: 'ArrowDown' })
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'First result' }))
+    await fireEvent.keyDown(document.activeElement!, { key: 'ArrowDown' })
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Second result' }))
+
+    await fireEvent.update(input, 'draft')
+    await fireEvent.click(screen.getByRole('button', { name: 'Clear search' }))
+    expect(input.value).toBe('')
+    expect(document.activeElement).toBe(input)
+
+    await fireEvent.keyDown(document, { key: 'Escape' })
+    await nextTick()
+    await Promise.resolve()
+    expect(open.value).toBe(false)
+    expect(document.activeElement).toBe(trigger)
+  })
+
+  test('renders divided docked geometry when explicitly selected', async () => {
+    render(M3Search, {
+      props: {
+        query: '', open: true, label: 'Search messages', status: '',
+        appearance: 'divided', layout: 'docked',
+      },
+    })
+    await nextTick()
+    expect(document.querySelector('.m3-search__view_divided.m3-search__view_docked')).not.toBeNull()
+  })
+})

From eae334363226d95f4f35c56bb9a5bd2a661f3775 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Wed, 7 Oct 2026 21:37:38 +0400
Subject: [PATCH 04/20] test(m3-react): Adaptive viewport assertions were
 stabilized

---
 m3-react/tests/M3NavigationBar.e2e.tsx | 4 ++--
 m3-react/tests/M3Search.e2e.tsx        | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/m3-react/tests/M3NavigationBar.e2e.tsx b/m3-react/tests/M3NavigationBar.e2e.tsx
index 826d0d7..49222a0 100644
--- a/m3-react/tests/M3NavigationBar.e2e.tsx
+++ b/m3-react/tests/M3NavigationBar.e2e.tsx
@@ -351,7 +351,7 @@ test('can exclude bar from automatic navigation and open a hidden modal rail', a
 
   try {
     const nav = query<HTMLElement>('nav.m3-navigation')
-    expect(nav.classList.contains('m3-navigation_rail-hidden')).toBe(true)
+    await waitFor(() => expect(nav.classList.contains('m3-navigation_rail-hidden')).toBe(true))
     expect(nav.classList.contains('m3-navigation_bar')).toBe(false)
 
     view.rerender(navigation(true))
@@ -386,7 +386,7 @@ test('keeps the vertical bar when it is the allowed bar form', async () => {
 
   try {
     const nav = query<HTMLElement>('nav.m3-navigation')
-    expect(nav.classList.contains('m3-navigation_bar')).toBe(true)
+    await waitFor(() => expect(nav.classList.contains('m3-navigation_bar')).toBe(true))
     expect(nav.classList.contains('m3-navigation_bar-vertical')).toBe(true)
     expect(query<HTMLElement>('.m3-navigation-tab').classList.contains('m3-navigation-tab_in-bar')).toBe(true)
 
diff --git a/m3-react/tests/M3Search.e2e.tsx b/m3-react/tests/M3Search.e2e.tsx
index b2a1ae9..6ec8e8f 100644
--- a/m3-react/tests/M3Search.e2e.tsx
+++ b/m3-react/tests/M3Search.e2e.tsx
@@ -30,7 +30,7 @@ test('adapts an open search without losing the query or overflowing the viewport
     fireEvent.change(input, { target: { value: 'notes' } })
 
     const dialog = screen.getByRole('dialog', { name: 'Search messages' })
-    expect(dialog.classList.contains('m3-search__view_full-screen')).toBe(true)
+    await waitFor(() => expect(dialog.classList.contains('m3-search__view_full-screen')).toBe(true))
     expect(getComputedStyle(document.querySelector('.m3-search__bar')!).visibility).toBe('hidden')
     expect(dialog.offsetWidth).toBe(390)
     expect(document.documentElement.scrollWidth).toBeLessThanOrEqual(390)

From 41d59cd30a89979313b06c06ea065661bf009cdd Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Wed, 7 Oct 2026 21:37:53 +0400
Subject: [PATCH 05/20] test(m3-vue): Adaptive viewport assertions were
 stabilized

---
 m3-vue/tests/M3NavigationBar.e2e.ts | 2 +-
 m3-vue/tests/M3Search.e2e.ts        | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/m3-vue/tests/M3NavigationBar.e2e.ts b/m3-vue/tests/M3NavigationBar.e2e.ts
index e799e41..de57f0b 100644
--- a/m3-vue/tests/M3NavigationBar.e2e.ts
+++ b/m3-vue/tests/M3NavigationBar.e2e.ts
@@ -475,7 +475,7 @@ test('keeps the vertical bar when it is the allowed bar form', async () => {
 
   try {
     const nav = query<HTMLElement>('nav.m3-navigation')
-    expect(nav.classList.contains('m3-navigation_bar')).toBe(true)
+    await waitFor(() => expect(nav.classList.contains('m3-navigation_bar')).toBe(true))
     expect(nav.classList.contains('m3-navigation_bar-vertical')).toBe(true)
     expect(query<HTMLElement>('.m3-navigation-tab').classList.contains('m3-navigation-tab_in-bar')).toBe(true)
 
diff --git a/m3-vue/tests/M3Search.e2e.ts b/m3-vue/tests/M3Search.e2e.ts
index f43f015..34176e6 100644
--- a/m3-vue/tests/M3Search.e2e.ts
+++ b/m3-vue/tests/M3Search.e2e.ts
@@ -46,7 +46,7 @@ test('adapts an open search without losing the query or overflowing the viewport
     await nextTick()
 
     const dialog = document.querySelector('.m3-search__view') as HTMLElement
-    expect(dialog.classList.contains('m3-search__view_full-screen')).toBe(true)
+    await waitFor(() => expect(dialog.classList.contains('m3-search__view_full-screen')).toBe(true))
     expect(getComputedStyle(document.querySelector('.m3-search__bar')!).visibility).toBe('hidden')
     expect(dialog.offsetWidth).toBe(390)
     expect(document.documentElement.scrollWidth).toBeLessThanOrEqual(390)

From 613741d3a54b979dd5ca717821200ee7f01ae1da Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Thu, 8 Oct 2026 14:41:38 +0400
Subject: [PATCH 06/20] feat(m3-foundation): App bar styles and scroll
 primitives were added

---
 .../stylesheets/components/app-bar/index.scss | 295 ++++++++++++++++++
 .../assets/stylesheets/components/index.scss  |   1 +
 m3-foundation/lib/appBar.ts                   |  28 ++
 m3-foundation/tests/appBar.test.ts            |  23 ++
 m3-foundation/types/components/app-bar.d.ts   |  16 +
 m3-foundation/vite.config.ts                  |   1 +
 6 files changed, 364 insertions(+)
 create mode 100644 m3-foundation/assets/stylesheets/components/app-bar/index.scss
 create mode 100644 m3-foundation/lib/appBar.ts
 create mode 100644 m3-foundation/tests/appBar.test.ts
 create mode 100644 m3-foundation/types/components/app-bar.d.ts

diff --git a/m3-foundation/assets/stylesheets/components/app-bar/index.scss b/m3-foundation/assets/stylesheets/components/app-bar/index.scss
new file mode 100644
index 0000000..e8d2c6b
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/app-bar/index.scss
@@ -0,0 +1,295 @@
+@use '../../basics/motion' as m3-motion;
+@use '../../basics/typography' as m3-typography;
+
+.m3-app-bar {
+  display: grid;
+  box-sizing: border-box;
+  inline-size: 100%;
+  block-size: 64px;
+  grid-template-columns: 56px minmax(0, 1fr) auto;
+  grid-template-rows: minmax(0, 1fr);
+  align-items: center;
+  background: var(--m3-sys-surface);
+  color: var(--m3-sys-on-surface);
+  position: sticky;
+  inset-block-start: 0;
+  z-index: 10;
+  transition:
+    #{m3-motion.timing-standard(background-color, 'short4')},
+    #{m3-motion.timing-standard(block-size, 'medium2')},
+    #{m3-motion.timing-standard(transform, 'medium2')};
+
+  &_under {
+    background: var(--m3-sys-surface-container);
+  }
+
+  &_transparent#{&}_under {
+    background: transparent;
+  }
+
+  &_hidden {
+    transform: translateY(-100%);
+  }
+
+  &__leading,
+  &__trailing {
+    display: flex;
+    min-inline-size: 0;
+    align-items: center;
+  }
+
+  &__leading {
+    grid-column: 1;
+    grid-row: 1;
+    margin-inline-start: 4px;
+  }
+
+  &__trailing {
+    grid-column: 3;
+    grid-row: 1;
+    justify-content: flex-end;
+    margin-inline-end: 4px;
+  }
+
+  &__trailing > * {
+    flex: 0 0 auto;
+  }
+
+  &__leading  .m3-icon-button,
+  &__trailing .m3-icon-button {
+    inline-size: 48px;
+    block-size: 48px;
+  }
+
+  &__leading .m3-icon-button__content,
+  &__trailing .m3-icon-button__content {
+    padding: 12px;
+  }
+
+  &__leading .m3-icon-button:where(:not(.m3-icon-button_filled, .m3-icon-button_tonal)) {
+    --content-color: var(--m3-sys-on-surface);
+    --state-color: var(--m3-sys-on-surface);
+    --m3-ripple-color: var(--m3-sys-on-surface);
+  }
+
+  &__title {
+    display: flex;
+    min-inline-size: 0;
+    grid-column: 2;
+    grid-row: 1;
+    flex-direction: column;
+    justify-content: center;
+    overflow: hidden;
+  }
+
+  &__headline {
+    @include m3-typography.title-large;
+
+    margin: 0;
+    overflow-wrap: normal;
+  }
+
+  &__image {
+    display: flex;
+    min-block-size: 0;
+    align-items: center;
+  }
+
+  &_center &__image {
+    justify-content: center;
+  }
+
+  &__image img {
+    display: block;
+    max-inline-size: 100%;
+    max-block-size: 40px;
+    object-fit: contain;
+  }
+
+  &__subtitle {
+    @include m3-typography.label-medium;
+
+    margin: 0;
+    color: var(--m3-sys-on-surface-variant);
+  }
+
+  &__search {
+    min-inline-size: 0;
+    inline-size: min(100%, max(312px, 50%));
+    grid-column: 2;
+    grid-row: 1;
+  }
+
+  &__search .m3-search {
+    max-inline-size: none;
+  }
+
+  &__search .m3-search__bar {
+    background: var(--m3-sys-surface-container);
+  }
+
+  &_under &__search .m3-search__bar {
+    background: var(--m3-sys-surface-container-highest);
+  }
+
+  &_search {
+    column-gap: 8px;
+  }
+
+  &_search &__trailing {
+    gap: 4px;
+  }
+
+  &_search#{&}_center .m3-search__trigger {
+    justify-content: center;
+    text-align: center;
+  }
+
+  &_center &__title {
+    text-align: center;
+  }
+
+  &_small &__headline {
+    overflow: hidden;
+    text-overflow: clip;
+    white-space: nowrap;
+  }
+
+  &_small#{&}_center &__title {
+    justify-self: center;
+  }
+
+  &_small#{&}_center,
+  &_collapsed#{&}_center {
+    grid-template-columns: minmax(104px, 1fr) minmax(0, max-content) minmax(104px, 1fr);
+  }
+
+  &_medium,
+  &_medium-flexible,
+  &_large,
+  &_large-flexible {
+    grid-template-rows: 56px minmax(0, 1fr);
+  }
+
+  &_medium &__title,
+  &_medium-flexible &__title,
+  &_large &__title,
+  &_large-flexible &__title {
+    grid-column: 1 / -1;
+    grid-row: 2;
+    align-self: end;
+    padding-inline: 16px;
+    padding-block-end: 12px;
+  }
+
+  &_medium,
+  &_medium-flexible {
+    block-size: 112px;
+  }
+
+  &_medium &__headline {
+    @include m3-typography.headline-small;
+  }
+
+  &_large {
+    block-size: 152px;
+  }
+
+  &_large &__headline {
+    @include m3-typography.headline-medium;
+  }
+
+  &_medium-flexible &__headline {
+    @include m3-typography.headline-medium;
+  }
+
+  &_medium-flexible,
+  &_large-flexible {
+    block-size: var(--m3-app-bar-measured-height, auto);
+    grid-template-rows: 56px minmax(min-content, 1fr);
+  }
+
+  &_medium-flexible &__title,
+  &_large-flexible &__title {
+    overflow: visible;
+  }
+
+  &_medium-flexible &__subtitle {
+    @include m3-typography.label-large;
+  }
+
+  &_medium-flexible#{&}_has-subtitle {
+    min-block-size: 136px;
+  }
+
+  &_large-flexible {
+    min-block-size: 120px;
+  }
+
+  &_large-flexible &__headline {
+    @include m3-typography.display-small;
+  }
+
+  &_large-flexible &__subtitle {
+    @include m3-typography.title-medium;
+  }
+
+  &_large-flexible#{&}_has-subtitle {
+    min-block-size: 152px;
+  }
+
+  &_medium-flexible {
+    min-block-size: 112px;
+  }
+
+  &_medium &__title { padding-block-end: 24px; }
+  &_large  &__title { padding-block-end: 28px; }
+
+  &_medium-flexible &__headline,
+  &_large-flexible &__headline {
+    text-wrap: balance;
+  }
+
+  &_collapsed {
+    block-size: 64px;
+    min-block-size: 64px;
+    grid-template-rows: minmax(0, 1fr);
+  }
+
+  &_collapsed#{&}_has-subtitle {
+    min-block-size: 64px;
+  }
+
+  &_collapsed &__title {
+    grid-column: 2;
+    grid-row: 1;
+    align-self: center;
+    padding: 0;
+  }
+
+  &_collapsed &__subtitle {
+    display: none;
+  }
+
+  &_collapsed &__headline {
+    @include m3-typography.title-large;
+
+    display: block;
+    overflow: hidden;
+    text-overflow: clip;
+    white-space: nowrap;
+  }
+
+  &_collapsed#{&}_center &__title {
+    justify-self: center;
+  }
+
+  &_transparent#{&}_under &__leading  .m3-icon-button,
+  &_transparent#{&}_under &__trailing .m3-icon-button {
+    background: var(--m3-sys-surface-container);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+}
diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index 26d5d7e..f8b09aa 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -1,3 +1,4 @@
+@use 'app-bar';
 @use 'badge';
 @use 'button';
 @use 'card';
diff --git a/m3-foundation/lib/appBar.ts b/m3-foundation/lib/appBar.ts
new file mode 100644
index 0000000..14e4ced
--- /dev/null
+++ b/m3-foundation/lib/appBar.ts
@@ -0,0 +1,28 @@
+import type {
+  AppBarAppearance,
+  AppBarScroll,
+  AppBarScrollState,
+} from '../types/components/app-bar'
+
+export const getFlexibleAppBarHeight = (
+  appearance: AppBarAppearance,
+  subtitle: boolean,
+  contentHeight: number
+): number => {
+  const minimum = appearance === 'large-flexible'
+    ? subtitle ? 152 : 120
+    : subtitle ? 136 : 112
+
+  return Math.max(minimum, 56 + contentHeight)
+}
+
+export const getAppBarScrollState = (
+  previous: number,
+  current: number,
+  hidden: boolean,
+  behavior: AppBarScroll
+): AppBarScrollState => ({
+  under: current > 0,
+  hidden: behavior === 'hide' && current > 0 && (current > previous + 1 || hidden && current >= previous - 1),
+  collapsed: behavior === 'collapse' && current > 0,
+})
diff --git a/m3-foundation/tests/appBar.test.ts b/m3-foundation/tests/appBar.test.ts
new file mode 100644
index 0000000..26fb2ae
--- /dev/null
+++ b/m3-foundation/tests/appBar.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest'
+
+import { getAppBarScrollState, getFlexibleAppBarHeight } from '../lib/appBar'
+
+describe('getAppBarScrollState', () => {
+  it('separates scroll-under from hiding', () => {
+    expect(getAppBarScrollState(0, 20, false, 'pinned')).toEqual({ under: true, hidden: false, collapsed: false })
+    expect(getAppBarScrollState(20, 30, false, 'hide')).toEqual({ under: true, hidden: true, collapsed: false })
+    expect(getAppBarScrollState(30, 20, true, 'hide')).toEqual({ under: true, hidden: false, collapsed: false })
+    expect(getAppBarScrollState(20, 0, true, 'hide')).toEqual({ under: false, hidden: false, collapsed: false })
+  })
+
+  it('collapses flexible bars while the page is away from the top', () => {
+    expect(getAppBarScrollState(0, 1, false, 'collapse')).toEqual({ under: true, hidden: false, collapsed: true })
+    expect(getAppBarScrollState(30, 0, false, 'collapse')).toEqual({ under: false, hidden: false, collapsed: false })
+  })
+
+  it('lets multi-line flexible content grow past its nominal minimum', () => {
+    expect(getFlexibleAppBarHeight('medium-flexible', false, 48)).toBe(112)
+    expect(getFlexibleAppBarHeight('medium-flexible', true, 100)).toBe(156)
+    expect(getFlexibleAppBarHeight('large-flexible', true, 124)).toBe(180)
+  })
+})
diff --git a/m3-foundation/types/components/app-bar.d.ts b/m3-foundation/types/components/app-bar.d.ts
new file mode 100644
index 0000000..cff5760
--- /dev/null
+++ b/m3-foundation/types/components/app-bar.d.ts
@@ -0,0 +1,16 @@
+export type AppBarAppearance =
+  | 'search'
+  | 'small'
+  | 'medium'
+  | 'medium-flexible'
+  | 'large'
+  | 'large-flexible'
+
+export type AppBarAlignment = 'start' | 'center'
+export type AppBarScroll = 'pinned' | 'hide' | 'collapse' | 'transparent'
+
+export interface AppBarScrollState {
+  under: boolean;
+  hidden: boolean;
+  collapsed: boolean;
+}
diff --git a/m3-foundation/vite.config.ts b/m3-foundation/vite.config.ts
index 86dfb48..db65dd5 100644
--- a/m3-foundation/vite.config.ts
+++ b/m3-foundation/vite.config.ts
@@ -7,6 +7,7 @@ import { dependencies } from './package.json'
 
 const entries = {
   'lib/Scheduler': resolve(__dirname, 'lib/Scheduler.ts'),
+  'lib/appBar': resolve(__dirname, 'lib/appBar.ts'),
   'lib/calendar': resolve(__dirname, 'lib/calendar/index.ts'),
   'lib/dom': resolve(__dirname, 'lib/dom.ts'),
   'lib/motion': resolve(__dirname, 'lib/motion/index.ts'),

From 9418872ce026061c02e89262be41ba6f373f0c93 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Thu, 8 Oct 2026 14:41:58 +0400
Subject: [PATCH 07/20] feat(m3-react): App bar component and examples were
 added

---
 m3-react/src/components/app-bar/M3AppBar.tsx  | 146 ++++++++++++++++
 m3-react/src/components/app-bar/index.ts      |   2 +
 m3-react/src/components/index.ts              |   1 +
 m3-react/storybook/components/M3AppBar.mdx    | 156 ++++++++++++++++++
 .../storybook/components/M3AppBar.stories.tsx |  44 +++++
 .../examples/app-bar/AppBarExample.tsx        | 108 ++++++++++++
 m3-react/tests/M3AppBar.e2e.tsx               |  85 ++++++++++
 m3-react/tests/M3AppBar.test.tsx              |  79 +++++++++
 8 files changed, 621 insertions(+)
 create mode 100644 m3-react/src/components/app-bar/M3AppBar.tsx
 create mode 100644 m3-react/src/components/app-bar/index.ts
 create mode 100644 m3-react/storybook/components/M3AppBar.mdx
 create mode 100644 m3-react/storybook/components/M3AppBar.stories.tsx
 create mode 100644 m3-react/storybook/examples/app-bar/AppBarExample.tsx
 create mode 100644 m3-react/tests/M3AppBar.e2e.tsx
 create mode 100644 m3-react/tests/M3AppBar.test.tsx

diff --git a/m3-react/src/components/app-bar/M3AppBar.tsx b/m3-react/src/components/app-bar/M3AppBar.tsx
new file mode 100644
index 0000000..ed743cf
--- /dev/null
+++ b/m3-react/src/components/app-bar/M3AppBar.tsx
@@ -0,0 +1,146 @@
+import type {
+  AppBarAlignment,
+  AppBarAppearance,
+  AppBarScroll,
+  AppBarScrollState,
+} from '@modulify/m3-foundation/types/components/app-bar'
+import type { ComponentSetupContext } from '@/utils/component'
+import type { ElementReference } from '@modulify/m3-foundation/types/dom'
+import type { HTMLAttributes, ReactNode, Ref } from 'react'
+
+import {
+  getAppBarScrollState,
+  getFlexibleAppBarHeight,
+} from '@modulify/m3-foundation/lib/appBar'
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import defineComponent from '@/utils/component'
+import { defineSlot, distinct } from '@/utils/content'
+import { toClassName } from '@/utils/styling'
+import { useElementReference, useResizeObserver } from '@/hooks'
+
+export interface M3AppBarProps extends HTMLAttributes<HTMLElement> {
+  ref?: Ref<M3AppBarExposed>;
+  appearance?: AppBarAppearance;
+  alignment?: AppBarAlignment;
+  scroll?: AppBarScroll;
+  scrollTarget?: HTMLElement | Window | null;
+  headline?: ReactNode;
+  subtitle?: ReactNode;
+  headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+  tag?: 'header' | 'div';
+}
+
+export interface M3AppBarExposed extends ElementReference<HTMLElement> {}
+
+const Leading = defineSlot('M3AppBar.Leading')
+const Headline = defineSlot('M3AppBar.Headline')
+const Image = defineSlot('M3AppBar.Image')
+const Subtitle = defineSlot('M3AppBar.Subtitle')
+const Trailing = defineSlot('M3AppBar.Trailing')
+const Search = defineSlot('M3AppBar.Search')
+
+const EMPTY_SCROLL_STATE: AppBarScrollState = { under: false, hidden: false, collapsed: false }
+
+export default defineComponent(function M3AppBar({
+  ref: _ref,
+  appearance = 'small',
+  alignment = 'start',
+  scroll = 'pinned',
+  scrollTarget,
+  headline,
+  subtitle,
+  headingLevel = 1,
+  tag: Tag = 'header',
+  className = '',
+  children = [],
+  ...attrs
+}: M3AppBarProps, { expose }: ComponentSetupContext<M3AppBarExposed>) {
+  const root = useRef<HTMLElement | null>(null)
+  const title = useRef<HTMLDivElement | null>(null)
+  const [scrollState, setScrollState] = useState(EMPTY_SCROLL_STATE)
+  const [slots, content] = useMemo(() => distinct(children, {
+    leading: Leading,
+    headline: Headline,
+    image: Image,
+    subtitle: Subtitle,
+    trailing: Trailing,
+    search: Search,
+  }), [children])
+
+  expose(useElementReference(root))
+
+  useEffect(() => {
+    const target = scrollTarget ?? window
+    const position = () => target === window ? window.scrollY : (target as HTMLElement).scrollTop
+    const controller = new AbortController()
+    let previous = position()
+
+    const update = () => {
+      const current = position()
+      setScrollState(state => {
+        const next = getAppBarScrollState(previous, current, state.hidden, scroll)
+        return state.under === next.under && state.hidden === next.hidden && state.collapsed === next.collapsed
+          ? state
+          : next
+      })
+      previous = current
+    }
+
+    update()
+    target.addEventListener('scroll', update, { passive: true, signal: controller.signal })
+    return () => controller.abort('App bar scroll listener disposed')
+  }, [scroll, scrollTarget])
+
+  const isFlexible = appearance === 'medium-flexible' || appearance === 'large-flexible'
+  const isCollapsed = isFlexible && scrollState.collapsed
+  const heading = slots.headline ?? headline ?? content
+  const supporting = slots.subtitle ?? subtitle
+  const hasSubtitle = appearance !== 'search' && appearance !== 'medium' && appearance !== 'large'
+    && supporting !== undefined && supporting !== null
+  const HeadingTag = `h${headingLevel}` as const
+
+  const syncExpandedHeight = () => {
+    if (!isFlexible || isCollapsed || !root.current || !title.current) return
+    const height = getFlexibleAppBarHeight(appearance, hasSubtitle, title.current.scrollHeight)
+    root.current.style.setProperty('--m3-app-bar-measured-height', `${height}px`)
+  }
+
+  useResizeObserver(title, syncExpandedHeight)
+  useLayoutEffect(syncExpandedHeight, [appearance, hasSubtitle, isCollapsed])
+
+  return (
+    <Tag
+      ref={element => { root.current = element }}
+      className={toClassName([className, {
+        'm3-app-bar': true,
+        [`m3-app-bar_${appearance}`]: true,
+        [`m3-app-bar_${alignment}`]: true,
+        'm3-app-bar_has-subtitle': hasSubtitle,
+        'm3-app-bar_under': scrollState.under,
+        'm3-app-bar_hidden': scrollState.hidden,
+        'm3-app-bar_collapsed': isCollapsed,
+        'm3-app-bar_transparent': scroll === 'transparent',
+      }])}
+      {...attrs}
+    >
+      {slots.leading && <div className="m3-app-bar__leading">{slots.leading}</div>}
+      {appearance === 'search'
+        ? <div className="m3-app-bar__search">{slots.search ?? content}</div>
+        : <div ref={title} className="m3-app-bar__title">
+          {isFlexible && !isCollapsed && slots.image && <div className="m3-app-bar__image">{slots.image}</div>}
+          {heading != null && <HeadingTag className="m3-app-bar__headline">{heading}</HeadingTag>}
+          {hasSubtitle && <div className="m3-app-bar__subtitle">{supporting}</div>}
+        </div>}
+      {slots.trailing && <div className="m3-app-bar__trailing">{slots.trailing}</div>}
+    </Tag>
+  )
+}, {
+  slots: { Leading, Headline, Image, Subtitle, Trailing, Search },
+})
diff --git a/m3-react/src/components/app-bar/index.ts b/m3-react/src/components/app-bar/index.ts
new file mode 100644
index 0000000..aa1a4c8
--- /dev/null
+++ b/m3-react/src/components/app-bar/index.ts
@@ -0,0 +1,2 @@
+export { default as M3AppBar } from './M3AppBar'
+export type { M3AppBarExposed, M3AppBarProps } from './M3AppBar'
diff --git a/m3-react/src/components/index.ts b/m3-react/src/components/index.ts
index 58419af..05e3616 100644
--- a/m3-react/src/components/index.ts
+++ b/m3-react/src/components/index.ts
@@ -1,4 +1,5 @@
 export * from './adaptive'
+export * from './app-bar'
 export * from './badge'
 export * from './button'
 export * from './card'
diff --git a/m3-react/storybook/components/M3AppBar.mdx b/m3-react/storybook/components/M3AppBar.mdx
new file mode 100644
index 0000000..0c9d130
--- /dev/null
+++ b/m3-react/storybook/components/M3AppBar.mdx
@@ -0,0 +1,156 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import { Localized } from '../i18n'
+import * as M3AppBarStories from './M3AppBar.stories'
+
+<Meta of={M3AppBarStories} />
+
+<Localized locale="en-US">
+
+# App bar
+
+An app bar identifies the current page and provides navigation and one or two essential actions. This library implements all six variants documented in the current [Material App bars specification](https://m3.material.io/components/app-bars/specs). The current Material 3 Expressive set and the older baseline set have different recommendations:
+
+| Appearance | Material 3 Expressive | Use |
+| --- | --- | --- |
+| `search` | Yes | A prominent search entry point on a home page. |
+| `small` | Yes | Dense pages and the collapsed state of a flexible bar. Centered text is an alignment option, not a separate variant. |
+| `medium-flexible` | Yes | A larger title, optional subtitle, and optional collapse on scroll. |
+| `large-flexible` | Yes | The strongest title emphasis, optional subtitle, and optional collapse on scroll. |
+| `medium` | **No: baseline M3** | Existing designs that still need the former medium geometry. Material recommends medium flexible for new Expressive designs. |
+| `large` | **No: baseline M3** | Existing designs that still need the former large geometry. Material recommends large flexible for new Expressive designs. |
+
+## Guide
+
+### Content and actions
+
+Keep the headline brief and specific to the page. `small` keeps it on one line; flexible variants can grow with a second line and must not be deliberately truncated. If a translated headline cannot fit, revise the copy or select a flexible appearance. Subtitles belong to small and flexible variants. For a logo or custom headline, use the named headline child. Flexible bars can also show an image above the title through `M3AppBar.Image`; it disappears in the collapsed state. Provide a real page heading; adjust `headingLevel` if the page already contains an earlier heading. Center alignment moves only the headline and subtitle; leading and trailing actions stay at the app bar edges.
+
+Pass a leading Back or Menu button in `M3AppBar.Leading`, and up to two page actions in `M3AppBar.Trailing`. Name icon buttons by their action. A Menu button can control an external `M3Navigation` with `appearance="rail"`, `collapse="hidden"`, and `expansion="modal"`; the app bar does not own the navigation state. Use one filled or tonal action if it needs extra emphasis. Put larger action collections in a toolbar. [Material guidelines](https://m3.material.io/components/app-bars/guidelines).
+
+### Search and scrolling
+
+For `appearance="search"`, put the existing `M3Search` in `M3AppBar.Search` with `layout="full-screen"`. Search keeps ownership of its query, expanded view, focus, and results. The app bar positions its collapsed trigger and adapts its width: it fills the available space up to 312 px, then grows at 50% of that space. The hint should include “Search.” A logo in this variant should not open the expanded rail.
+
+`scroll="pinned"` keeps the bar visible and changes its container from surface to surface-container after scrolling. `hide` hides on forward scroll and reveals on reverse scroll. `collapse` reduces a flexible bar to the small layout until the scroll position returns to the top. `transparent` keeps controls visible over content, giving icon buttons their own filled surfaces. Pass `scrollTarget` when an element rather than `window` scrolls; use that same element to contain the sticky bar. A scroll mode is independent of the selected appearance, but `collapse` changes layout only for flexible appearances. The motion respects reduced-motion preferences.
+
+The app bar occupies the width of its containing layout. Place it in the page shell beside a rail, and provide the surrounding layout in the application. Use `tag="div"` if the page already has a banner landmark; a body-level `<header>` normally creates one. [WAI banner guidance](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html).
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `M3AppBar` | Six app bar appearances, content zones, and scroll response. |
+| `M3AppBarProps`, `M3AppBarExposed` | Public props and element reference. |
+
+| Prop | Default | Effect |
+| --- | --- | --- |
+| `appearance` | `small` | `search`, `small`, `medium`, `medium-flexible`, `large`, `large-flexible`. |
+| `alignment` | `start` | `start` or `center` for the headline/search hint. Centered baseline medium/large is outside the Expressive recommendation. |
+| `headline`, `subtitle` | — | Title content; subtitle is rendered for small/flexible appearances. Named children override these props. |
+| `headingLevel` | `1` | Native heading level from 1 to 6. |
+| `scroll` | `pinned` | `pinned`, `hide`, `collapse`, or `transparent`. |
+| `scrollTarget` | `window` | Scrollable `HTMLElement` or `Window` to observe. |
+| `tag` | `header` | Root `header` or `div` to fit page landmark structure. |
+| HTML attributes | — | Passed to the root element. |
+
+| Named child | Purpose |
+| --- | --- |
+| `M3AppBar.Leading` | Back, Menu, or appropriate leading control. |
+| `M3AppBar.Headline` | Custom headline content inside the semantic heading. |
+| `M3AppBar.Image` | Optional image above a flexible headline; hidden while collapsed. |
+| `M3AppBar.Subtitle` | Supporting text for small/flexible variants. |
+| `M3AppBar.Trailing` | Page actions, ordered in the supplied DOM sequence. |
+| `M3AppBar.Search` | Search trigger and view owner for the search variant. |
+
+The ref exposes `el`. Unslotted children act as the headline for ordinary appearances and as search content for `search`.
+
+```tsx
+<M3AppBar appearance="medium-flexible" headline="Library" subtitle="Recently added" scroll="collapse" scrollTarget={scroller}>
+  <M3AppBar.Leading>
+    <M3IconButton aria-label="Open navigation" onClick={() => setNavigationOpen(true)}>
+      <M3Icon name="menu" />
+    </M3IconButton>
+  </M3AppBar.Leading>
+  <M3AppBar.Trailing>
+    <M3IconButton aria-label="Favorites"><M3Icon name="favorite" /></M3IconButton>
+  </M3AppBar.Trailing>
+</M3AppBar>
+```
+
+## Sources
+
+- [Material App bars overview](https://m3.material.io/components/app-bars/overview)
+- [Specs](https://m3.material.io/components/app-bars/specs)
+- [Guidelines](https://m3.material.io/components/app-bars/guidelines)
+- [Accessibility](https://m3.material.io/components/app-bars/accessibility)
+
+</Localized>
+
+<Localized locale="ru-RU">
+
+# Верхняя панель приложения
+
+App bar показывает, какая страница открыта, и содержит навигацию и одно-два важнейших действия. Библиотека реализует все шесть вариантов из текущей [спецификации Material](https://m3.material.io/components/app-bars/specs). К актуальному Material 3 Expressive относятся не все:
+
+| Вид | Входит в M3 Expressive | Применение |
+| --- | --- | --- |
+| `search` | Да | Заметная точка входа в поиск на главной странице. |
+| `small` | Да | Плотная компоновка и свёрнутое состояние flexible. Центрирование заголовка — настройка, а не отдельный вид. |
+| `medium-flexible` | Да | Более крупный заголовок, подзаголовок и возможное сворачивание при прокрутке. |
+| `large-flexible` | Да | Максимальный акцент на заголовке, подзаголовок и возможное сворачивание. |
+| `medium` | **Нет: базовый M3** | Совместимость с прежней геометрией; для нового Expressive интерфейса Material рекомендует medium flexible. |
+| `large` | **Нет: базовый M3** | Совместимость с прежней геометрией; для нового Expressive интерфейса Material рекомендует large flexible. |
+
+## Руководство
+
+### Содержимое и действия
+
+Заголовок должен коротко описывать текущую страницу. В `small` он однострочный; flexible может вырасти для второй строки без намеренного усечения. Если перевод не помещается, пересмотрите формулировку или выберите flexible вид. Подзаголовок поддерживается в small и flexible. Для особой разметки заголовка используйте `M3AppBar.Headline`. Изображение над заголовком flexible передайте через `M3AppBar.Image`; при сворачивании оно скрывается. Сам заголовок остаётся настоящим heading; `headingLevel` позволяет согласовать его с иерархией страницы. При центрировании смещаются только заголовок и подзаголовок: ведущие и завершающие действия остаются у краёв панели.
+
+В `M3AppBar.Leading` разместите Back или Menu, в `M3AppBar.Trailing` — максимум два действия страницы. Дайте иконочным кнопкам названия по их действию. Menu может управлять внешним `M3Navigation` с `appearance="rail"`, `collapse="hidden"`, `expansion="modal"`; app bar не владеет состоянием навигации. Для акцента используйте одну filled/tonal кнопку. Большое число действий вынесите в toolbar. [Рекомендации Material](https://m3.material.io/components/app-bars/guidelines).
+
+### Поиск и прокрутка
+
+Для `appearance="search"` передайте существующий `M3Search` в `M3AppBar.Search` с `layout="full-screen"`. Search управляет запросом, раскрытым видом, фокусом и результатами; app bar только размещает свёрнутую строку. До ширины 312 px она занимает всё доступное место, затем растёт как 50% доступного места. В подсказке должно быть слово «Поиск». Логотип в этом виде не должен открывать раскрытый rail.
+
+`scroll="pinned"` оставляет панель на экране и после прокрутки меняет `surface` на `surface-container`. `hide` скрывает её при прокрутке вперёд и возвращает при обратной. `collapse` сворачивает flexible в small до возвращения страницы к началу. `transparent` оставляет действия поверх контента на собственных заполненных поверхностях. Если прокручивается элемент, а не `window`, передайте его через `scrollTarget` и поместите липкую панель в тот же контейнер. Режим `collapse` меняет layout только у flexible видов. При ограничении движения анимация отключается.
+
+Панель занимает ширину своего контейнера. Приложение размещает её в компоновке страницы рядом с rail. Если в документе уже есть landmark `banner`, используйте `tag="div"`: `<header>` на уровне страницы обычно создаёт такой landmark. [WAI о banner](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html).
+
+## API
+
+| Экспорт | Назначение |
+| --- | --- |
+| `M3AppBar` | Шесть вариантов панели, области содержимого и реакция на прокрутку. |
+| `M3AppBarProps`, `M3AppBarExposed` | Типы props и ссылки на элемент. |
+
+| Prop | Значение по умолчанию | Действие |
+| --- | --- | --- |
+| `appearance` | `small` | `search`, `small`, `medium`, `medium-flexible`, `large`, `large-flexible`. |
+| `alignment` | `start` | `start` или `center` для заголовка/подсказки. Центрирование baseline medium/large вне рекомендации Expressive. |
+| `headline`, `subtitle` | — | Текст заголовка и подзаголовка; последний рисуется только в small/flexible. Именованные элементы имеют приоритет. |
+| `headingLevel` | `1` | Уровень настоящего заголовка от 1 до 6. |
+| `scroll` | `pinned` | `pinned`, `hide`, `collapse` или `transparent`. |
+| `scrollTarget` | `window` | Прокручиваемый `HTMLElement` или `Window`. |
+| `tag` | `header` | Корневой `header` или `div` для структуры landmarks страницы. |
+| HTML-атрибуты | — | Передаются корневому элементу. |
+
+| Именованный элемент | Назначение |
+| --- | --- |
+| `M3AppBar.Leading` | Back, Menu или другое уместное ведущее действие. |
+| `M3AppBar.Headline` | Своя разметка внутри семантического заголовка. |
+| `M3AppBar.Image` | Изображение над заголовком flexible, скрываемое при сворачивании. |
+| `M3AppBar.Subtitle` | Контекст для small/flexible. |
+| `M3AppBar.Trailing` | Действия страницы в заданном порядке DOM. |
+| `M3AppBar.Search` | Поисковая строка и управляющий Search. |
+
+Ref предоставляет `el`. Дочерние элементы без имени становятся заголовком обычного варианта или содержимым поисковой области для `search`.
+
+## Источники
+
+- [Обзор Material App bars](https://m3.material.io/components/app-bars/overview)
+- [Спецификация](https://m3.material.io/components/app-bars/specs)
+- [Рекомендации](https://m3.material.io/components/app-bars/guidelines)
+- [Доступность](https://m3.material.io/components/app-bars/accessibility)
+
+</Localized>
diff --git a/m3-react/storybook/components/M3AppBar.stories.tsx b/m3-react/storybook/components/M3AppBar.stories.tsx
new file mode 100644
index 0000000..98233f3
--- /dev/null
+++ b/m3-react/storybook/components/M3AppBar.stories.tsx
@@ -0,0 +1,44 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { M3AppBar } from '@/components/app-bar'
+
+import AppBarExample from '../examples/app-bar/AppBarExample'
+
+const meta = {
+  title: 'Components/M3AppBar',
+  component: M3AppBar,
+  args: { appearance: 'small', alignment: 'start', scroll: 'pinned' },
+  argTypes: {
+    appearance: { control: 'select', options: ['search', 'small', 'medium', 'medium-flexible', 'large', 'large-flexible'] },
+    alignment: { control: 'select', options: ['start', 'center'] },
+    scroll: { control: 'select', options: ['pinned', 'hide', 'collapse', 'transparent'] },
+    scrollTarget: { control: false },
+    headline: { control: false },
+    subtitle: { control: false },
+    headingLevel: { control: false },
+  },
+  render: (args, { globals }) => (
+    <AppBarExample
+      appearance={args.appearance ?? 'small'}
+      scroll={args.scroll ?? 'pinned'}
+      centered={args.alignment === 'center'}
+      subtitle={args.appearance === 'small' || (args.appearance ?? '').includes('flexible')}
+      locale={globals.locale}
+    />
+  ),
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof M3AppBar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Search: Story = { args: { appearance: 'search' } }
+export const Small: Story = {}
+export const SmallCentered: Story = { args: { alignment: 'center' } }
+export const Medium: Story = { args: { appearance: 'medium' } }
+export const MediumFlexible: Story = { args: { appearance: 'medium-flexible', scroll: 'collapse' } }
+export const Large: Story = { args: { appearance: 'large' } }
+export const LargeFlexible: Story = { args: { appearance: 'large-flexible', scroll: 'collapse' } }
+export const HideOnScroll: Story = { args: { scroll: 'hide' } }
+export const TransparentOnScroll: Story = { args: { scroll: 'transparent' } }
diff --git a/m3-react/storybook/examples/app-bar/AppBarExample.tsx b/m3-react/storybook/examples/app-bar/AppBarExample.tsx
new file mode 100644
index 0000000..1b7c306
--- /dev/null
+++ b/m3-react/storybook/examples/app-bar/AppBarExample.tsx
@@ -0,0 +1,108 @@
+import type {
+  AppBarAppearance,
+  AppBarScroll,
+} from '@modulify/m3-foundation/types/components/app-bar'
+
+import { useState } from 'react'
+
+import { M3AppBar } from '@/components/app-bar'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import { M3Navigation, M3NavigationTab } from '@/components/navigation'
+import { M3Search } from '@/components/search'
+
+import { localize } from '../../i18n'
+
+const messages = {
+  'en-US': {
+    title: 'Your library', subtitle: 'Recently added', search: 'Search your library', menu: 'Open navigation',
+    back: 'Back to library', close: 'Clear search', favorite: 'Favorites', notifications: 'Notifications',
+    home: 'Home', library: 'Library', settings: 'Settings', section: 'Recent items',
+    cards: ['Reading list', 'Travel ideas', 'Project notes', 'Saved links', 'Garden plans', 'Music for later'],
+  },
+  'ru-RU': {
+    title: 'Библиотека', subtitle: 'Недавно добавлено', search: 'Поиск в библиотеке', menu: 'Открыть навигацию',
+    back: 'Назад к библиотеке', close: 'Очистить поиск', favorite: 'Избранное', notifications: 'Уведомления',
+    home: 'Главная', library: 'Библиотека', settings: 'Настройки', section: 'Недавние записи',
+    cards: ['Список для чтения', 'Идеи поездок', 'Заметки проекта', 'Сохранённые ссылки', 'Планы сада', 'Музыка на потом'],
+  },
+}
+
+interface AppBarExampleProps {
+  appearance: AppBarAppearance;
+  scroll: AppBarScroll;
+  centered?: boolean;
+  subtitle?: boolean;
+  locale: string;
+}
+
+export default function AppBarExample({ appearance, scroll, centered = false, subtitle = false, locale }: AppBarExampleProps) {
+  const text = localize(locale, messages)
+  const [scroller, setScroller] = useState<HTMLElement | null>(null)
+  const [navigationOpen, setNavigationOpen] = useState(false)
+  const [searchOpen, setSearchOpen] = useState(false)
+  const [query, setQuery] = useState('')
+  const results = text.cards.filter(card => card.toLocaleLowerCase(locale).includes(query.toLocaleLowerCase(locale)))
+
+  return (
+    <main ref={setScroller} style={{ blockSize: '100vh', overflowY: 'auto', background: 'var(--m3-sys-surface)' }}>
+      <M3AppBar
+        appearance={appearance}
+        alignment={centered ? 'center' : 'start'}
+        scroll={scroll}
+        scrollTarget={scroller}
+        headline={text.title}
+        subtitle={subtitle ? text.subtitle : undefined}
+      >
+        <M3AppBar.Leading>
+          <M3IconButton aria-label={text.menu} onClick={() => setNavigationOpen(true)}><M3Icon name="menu" /></M3IconButton>
+        </M3AppBar.Leading>
+        {appearance === 'search' && <M3AppBar.Search>
+          <M3Search
+            query={query}
+            open={searchOpen}
+            label={text.search}
+            status={`${results.length} results`}
+            hint={text.search}
+            backLabel={text.back}
+            clearLabel={text.close}
+            layout="full-screen"
+            onQueryChange={setQuery}
+            onOpenChange={setSearchOpen}
+          >
+            <M3Search.Results>
+              <div style={{ padding: 24 }}>{results.join(' · ')}</div>
+            </M3Search.Results>
+          </M3Search>
+        </M3AppBar.Search>}
+        <M3AppBar.Trailing>
+          <M3IconButton aria-label={text.favorite}><M3Icon name="favorite" /></M3IconButton>
+          <M3IconButton aria-label={text.notifications}><M3Icon name="notifications" /></M3IconButton>
+        </M3AppBar.Trailing>
+      </M3AppBar>
+
+      <M3Navigation
+        appearance="rail"
+        expansion="modal"
+        collapse="hidden"
+        expanded={navigationOpen}
+        onToggle={setNavigationOpen}
+      >
+        <M3NavigationTab label={text.home}><M3Icon name="home" /></M3NavigationTab>
+        <M3NavigationTab label={text.library} active><M3Icon name="book" /></M3NavigationTab>
+        <M3NavigationTab label={text.settings}><M3Icon name="settings" /></M3NavigationTab>
+      </M3Navigation>
+
+      <div style={{ padding: 24, maxWidth: 1100, marginInline: 'auto' }}>
+        <h2 style={{ marginBlock: '16px 24px' }}>{text.section}</h2>
+        <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))', gap: 16 }}>
+          {text.cards.concat(text.cards, text.cards).map((card, index) => (
+            <article key={`${card}-${index}`} style={{ minBlockSize: 120, padding: 24, borderRadius: 24, background: 'var(--m3-sys-surface-container)' }}>
+              {card}
+            </article>
+          ))}
+        </div>
+      </div>
+    </main>
+  )
+}
diff --git a/m3-react/tests/M3AppBar.e2e.tsx b/m3-react/tests/M3AppBar.e2e.tsx
new file mode 100644
index 0000000..9eac0bd
--- /dev/null
+++ b/m3-react/tests/M3AppBar.e2e.tsx
@@ -0,0 +1,85 @@
+import { act } from '@testing-library/react'
+import { page } from 'vitest/browser'
+import { render, waitFor } from '@testing-library/react'
+
+import { M3AppBar } from '@/components/app-bar'
+import { M3IconButton } from '@/components/icon-button'
+
+test('renders the six documented heights and grows flexible content without truncation', async () => {
+  await page.viewport(900, 800)
+
+  const cases = [
+    ['search', 64], ['small', 64], ['medium', 112],
+    ['medium-flexible', 112], ['large', 152], ['large-flexible', 120],
+  ] as const
+
+  for (const [appearance, height] of cases) {
+    const view = render(<M3AppBar appearance={appearance} headline="Library" />)
+    expect(view.container.querySelector('.m3-app-bar')!.getBoundingClientRect().height).toBe(height)
+    view.unmount()
+  }
+
+  const view = render(<M3AppBar appearance="large-flexible" headline="A long title that needs two lines across a compact window" subtitle="Additional context" />)
+  try {
+    await page.viewport(360, 800)
+    const bar = view.container.querySelector('.m3-app-bar')!
+    const headline = view.container.querySelector('.m3-app-bar__headline')!
+    expect(bar.getBoundingClientRect().height).toBeGreaterThanOrEqual(152)
+    expect(headline.scrollHeight).toBeLessThanOrEqual(headline.clientHeight)
+  } finally {
+    view.unmount()
+  }
+})
+
+test.each(['ltr', 'rtl'] as const)('centers a small title while keeping actions at the %s edges', direction => {
+  const view = render(<M3AppBar headline="Library" subtitle="Recent" alignment="center" dir={direction}>
+    <M3AppBar.Leading><M3IconButton aria-label="Back">←</M3IconButton></M3AppBar.Leading>
+    <M3AppBar.Trailing>
+      <M3IconButton aria-label="Favorites">★</M3IconButton>
+      <M3IconButton aria-label="Settings">⚙</M3IconButton>
+    </M3AppBar.Trailing>
+  </M3AppBar>)
+
+  try {
+    const bar = view.container.querySelector('.m3-app-bar')!.getBoundingClientRect()
+    const title = view.container.querySelector('.m3-app-bar__title')!.getBoundingClientRect()
+    const leading = view.container.querySelector('.m3-app-bar__leading .m3-icon-button')!.getBoundingClientRect()
+    const trailing = view.container.querySelector('.m3-app-bar__trailing .m3-icon-button:last-child')!.getBoundingClientRect()
+
+    expect(Math.abs((title.left + title.right) / 2 - (bar.left + bar.right) / 2)).toBeLessThan(1)
+    expect(direction === 'ltr' ? leading.left - bar.left : bar.right - leading.right).toBe(4)
+    expect(direction === 'ltr' ? bar.right - trailing.right : trailing.left - bar.left).toBe(4)
+    expect(leading.width).toBe(48)
+    expect(trailing.width).toBe(48)
+  } finally {
+    view.unmount()
+  }
+})
+
+test('collapses a flexible bar against its own scroll container and expands at the top', async () => {
+  await page.viewport(900, 800)
+  const scroller = document.createElement('main')
+  Object.assign(scroller.style, { height: '300px', overflowY: 'auto' })
+  document.body.append(scroller)
+  const view = render(<>
+    <M3AppBar appearance="medium-flexible" headline="Library" subtitle="Recent items" scroll="collapse" scrollTarget={scroller} />
+    <div style={{ height: 1000 }} />
+  </>, { container: scroller })
+
+  try {
+    const bar = scroller.querySelector<HTMLElement>('.m3-app-bar')!
+    expect(bar.getBoundingClientRect().height).toBe(136)
+    const transitions = new Set<string>()
+    bar.addEventListener('transitionrun', event => transitions.add(event.propertyName))
+    await act(async () => { scroller.scrollTop = 100 })
+    await waitFor(() => expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(true))
+    await waitFor(() => expect(transitions.has('height')).toBe(true))
+    await waitFor(() => expect(bar.getBoundingClientRect().height).toBe(64))
+    await act(async () => { scroller.scrollTop = 0 })
+    await waitFor(() => expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(false))
+    await waitFor(() => expect(bar.getBoundingClientRect().height).toBe(136))
+  } finally {
+    view.unmount()
+    scroller.remove()
+  }
+})
diff --git a/m3-react/tests/M3AppBar.test.tsx b/m3-react/tests/M3AppBar.test.tsx
new file mode 100644
index 0000000..74e9383
--- /dev/null
+++ b/m3-react/tests/M3AppBar.test.tsx
@@ -0,0 +1,79 @@
+import { fireEvent, render, screen } from '@testing-library/react'
+import { useState } from 'react'
+
+import { M3AppBar } from '@/components/app-bar'
+import { M3Search } from '@/components/search'
+
+const appearances = ['search', 'small', 'medium', 'medium-flexible', 'large', 'large-flexible'] as const
+
+describe('m3-react/app-bar', () => {
+  test.each(appearances)('renders %s with one appropriate title', appearance => {
+    const view = render(
+      <M3AppBar appearance={appearance} headline="Library" subtitle="Recent items">
+        <M3AppBar.Leading><button type="button">Menu</button></M3AppBar.Leading>
+        <M3AppBar.Trailing><button type="button">Favorite</button></M3AppBar.Trailing>
+      </M3AppBar>
+    )
+
+    const bar = view.container.querySelector('.m3-app-bar')!
+    expect(bar.classList.contains(`m3-app-bar_${appearance}`)).toBe(true)
+    expect(screen.getByRole('button', { name: 'Menu' })).not.toBeNull()
+    expect(screen.getByRole('button', { name: 'Favorite' })).not.toBeNull()
+    expect(screen.queryByRole('heading', { name: 'Library' }) !== null).toBe(appearance !== 'search')
+    expect(view.container.querySelector('.m3-app-bar__subtitle') !== null).toBe(
+      appearance === 'small' || appearance.includes('flexible')
+    )
+  })
+
+  test('tracks a supplied scroll root and re-expands flexible content at the top', () => {
+    const scroller = document.createElement('div')
+    const view = render(<M3AppBar appearance="medium-flexible" headline="Library" scroll="collapse" scrollTarget={scroller} />)
+    const bar = view.container.querySelector('.m3-app-bar')!
+
+    scroller.scrollTop = 40
+    fireEvent.scroll(scroller)
+    expect(bar.classList.contains('m3-app-bar_under')).toBe(true)
+    expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(true)
+
+    scroller.scrollTop = 0
+    fireEvent.scroll(scroller)
+    expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(false)
+    expect(bar.classList.contains('m3-app-bar_under')).toBe(false)
+  })
+
+  test('shows a flexible image until the bar collapses', () => {
+    const scroller = document.createElement('div')
+    const view = render(<M3AppBar appearance="large-flexible" headline="Library" scroll="collapse" scrollTarget={scroller}>
+      <M3AppBar.Image><img src="/library.svg" alt="" /></M3AppBar.Image>
+    </M3AppBar>)
+
+    expect(view.container.querySelector('.m3-app-bar__image img')).not.toBeNull()
+    scroller.scrollTop = 40
+    fireEvent.scroll(scroller)
+    expect(view.container.querySelector('.m3-app-bar__image')).toBeNull()
+  })
+
+  test('keeps one search view owner when composed with M3Search', () => {
+    const Example = () => {
+      const [open, setOpen] = useState(false)
+      const [query, setQuery] = useState('')
+      return <M3AppBar appearance="search">
+        <M3AppBar.Search>
+          <M3Search
+            query={query}
+            open={open}
+            label="Search library"
+            status=""
+            layout="full-screen"
+            onQueryChange={setQuery}
+            onOpenChange={setOpen}
+          />
+        </M3AppBar.Search>
+      </M3AppBar>
+    }
+
+    render(<Example />)
+    fireEvent.click(screen.getByRole('button', { name: 'Search library' }))
+    expect(screen.getAllByRole('dialog', { name: 'Search library' })).toHaveLength(1)
+  })
+})

From 3b2514e7dbd761e0ba31cd358397b43e60f9f543 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Thu, 8 Oct 2026 14:42:12 +0400
Subject: [PATCH 08/20] feat(m3-vue): App bar component and examples were added

Closes #26
---
 m3-vue/src/components/app-bar/M3AppBar.vue    | 181 ++++++++++++++++++
 m3-vue/src/components/app-bar/index.ts        |   3 +
 m3-vue/src/components/index.ts                |   1 +
 m3-vue/storybook/components/M3AppBar.mdx      | 156 +++++++++++++++
 .../storybook/components/M3AppBar.stories.ts  |  46 +++++
 .../examples/app-bar/AppBarExample.vue        | 156 +++++++++++++++
 m3-vue/tests/M3AppBar.e2e.ts                  | 119 ++++++++++++
 m3-vue/tests/M3AppBar.test.ts                 |  89 +++++++++
 8 files changed, 751 insertions(+)
 create mode 100644 m3-vue/src/components/app-bar/M3AppBar.vue
 create mode 100644 m3-vue/src/components/app-bar/index.ts
 create mode 100644 m3-vue/storybook/components/M3AppBar.mdx
 create mode 100644 m3-vue/storybook/components/M3AppBar.stories.ts
 create mode 100644 m3-vue/storybook/examples/app-bar/AppBarExample.vue
 create mode 100644 m3-vue/tests/M3AppBar.e2e.ts
 create mode 100644 m3-vue/tests/M3AppBar.test.ts

diff --git a/m3-vue/src/components/app-bar/M3AppBar.vue b/m3-vue/src/components/app-bar/M3AppBar.vue
new file mode 100644
index 0000000..6768ae9
--- /dev/null
+++ b/m3-vue/src/components/app-bar/M3AppBar.vue
@@ -0,0 +1,181 @@
+<template>
+    <component
+        :is="tag"
+        ref="root"
+        v-bind="$attrs"
+        :class="{
+            'm3-app-bar': true,
+            ['m3-app-bar_' + appearance]: true,
+            ['m3-app-bar_' + alignment]: true,
+            'm3-app-bar_has-subtitle': hasSubtitle,
+            'm3-app-bar_under': scrollState.under,
+            'm3-app-bar_hidden': scrollState.hidden,
+            'm3-app-bar_collapsed': isCollapsed,
+            'm3-app-bar_transparent': scroll === 'transparent',
+        }"
+    >
+        <div v-if="'leading' in $slots" class="m3-app-bar__leading">
+            <slot name="leading" />
+        </div>
+
+        <div v-if="appearance === 'search'" class="m3-app-bar__search">
+            <slot name="search">
+                <slot />
+            </slot>
+        </div>
+        <div v-else ref="title" class="m3-app-bar__title">
+            <div v-if="(appearance === 'medium-flexible' || appearance === 'large-flexible') && !isCollapsed && 'image' in $slots" class="m3-app-bar__image">
+                <slot name="image" />
+            </div>
+
+            <component :is="'h' + headingLevel" v-if="headline != null || 'headline' in $slots || 'default' in $slots" class="m3-app-bar__headline">
+                <slot name="headline">
+                    <slot>{{ headline }}</slot>
+                </slot>
+            </component>
+
+            <div v-if="hasSubtitle" class="m3-app-bar__subtitle">
+                <slot name="subtitle">
+                    {{ subtitle }}
+                </slot>
+            </div>
+        </div>
+
+        <div v-if="'trailing' in $slots" class="m3-app-bar__trailing">
+            <slot name="trailing" />
+        </div>
+    </component>
+</template>
+
+<script lang="ts" setup>
+import type {
+  AppBarAlignment,
+  AppBarAppearance,
+  AppBarScroll,
+  AppBarScrollState,
+} from '@modulify/m3-foundation/types/components/app-bar'
+import type { ElementReference } from '@modulify/m3-foundation/types/dom'
+import type { PropType } from 'vue'
+
+import { computed } from 'vue'
+import {
+  getAppBarScrollState,
+  getFlexibleAppBarHeight,
+} from '@modulify/m3-foundation/lib/appBar'
+import { nextTick } from 'vue'
+import {
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  useSlots,
+  watch,
+} from 'vue'
+
+import { useResizeObserver } from '@/composables/observer'
+
+defineOptions({ inheritAttrs: false })
+
+const props = defineProps({
+  appearance: {
+    type: String as PropType<AppBarAppearance>,
+    default: 'small',
+  },
+
+  alignment: {
+    type: String as PropType<AppBarAlignment>,
+    default: 'start',
+  },
+
+  scroll: {
+    type: String as PropType<AppBarScroll>,
+    default: 'pinned',
+  },
+
+  scrollTarget: {
+    type: Object as PropType<HTMLElement | Window | null>,
+    default: null,
+  },
+
+  headline: {
+    type: String,
+    default: undefined,
+  },
+
+  subtitle: {
+    type: String,
+    default: undefined,
+  },
+
+  headingLevel: {
+    type: Number as PropType<1 | 2 | 3 | 4 | 5 | 6>,
+    default: 1,
+  },
+
+  tag: {
+    type: String as PropType<'header' | 'div'>,
+    default: 'header',
+  },
+})
+
+const slots = useSlots()
+const root = ref<HTMLElement | null>(null)
+const title = ref<HTMLElement | null>(null)
+const scrollState = ref<AppBarScrollState>({ under: false, hidden: false, collapsed: false })
+const hasSubtitle = computed(() =>
+  props.appearance !== 'search' && props.appearance !== 'medium' && props.appearance !== 'large'
+  && (props.subtitle != null || 'subtitle' in slots)
+)
+const isCollapsed = computed(() =>
+  (props.appearance === 'medium-flexible' || props.appearance === 'large-flexible')
+  && scrollState.value.collapsed
+)
+
+const syncExpandedHeight = () => {
+  if (isCollapsed.value || !root.value || !title.value) return
+  if (props.appearance !== 'medium-flexible' && props.appearance !== 'large-flexible') return
+  const height = getFlexibleAppBarHeight(props.appearance, hasSubtitle.value, title.value.scrollHeight)
+  root.value.style.setProperty('--m3-app-bar-measured-height', `${height}px`)
+}
+
+const titleObserver = useResizeObserver(title, syncExpandedHeight)
+
+let listeners: AbortController | null = null
+
+const observeScroll = () => {
+  listeners?.abort('App bar scroll listener replaced')
+  const target = props.scrollTarget ?? window
+  const position = () => target === window ? window.scrollY : (target as HTMLElement).scrollTop
+  const controller = new AbortController()
+  let previous = position()
+
+  const update = () => {
+    const current = position()
+    scrollState.value = getAppBarScrollState(previous, current, scrollState.value.hidden, props.scroll)
+    previous = current
+  }
+
+  update()
+  target.addEventListener('scroll', update, { passive: true, signal: controller.signal })
+  listeners = controller
+}
+
+defineExpose({ get el () { return root.value } } satisfies ElementReference<HTMLElement>)
+
+onMounted(() => {
+  observeScroll()
+  titleObserver.observe()
+  syncExpandedHeight()
+})
+onBeforeUnmount(() => listeners?.abort('App bar scroll listener disposed'))
+watch([() => props.scroll, () => props.scrollTarget], observeScroll, { flush: 'post' })
+watch([() => props.appearance, hasSubtitle, isCollapsed, title], (_, __, onCleanup) => {
+  let active = true
+  onCleanup(() => { active = false })
+  void nextTick(() => {
+    if (!active) return
+    titleObserver.unobserve()
+    titleObserver.observe()
+    syncExpandedHeight()
+  })
+}, { flush: 'post' })
+</script>
diff --git a/m3-vue/src/components/app-bar/index.ts b/m3-vue/src/components/app-bar/index.ts
new file mode 100644
index 0000000..c22655f
--- /dev/null
+++ b/m3-vue/src/components/app-bar/index.ts
@@ -0,0 +1,3 @@
+import M3AppBar from './M3AppBar.vue'
+
+export { M3AppBar }
diff --git a/m3-vue/src/components/index.ts b/m3-vue/src/components/index.ts
index de0b141..6bf8f3e 100644
--- a/m3-vue/src/components/index.ts
+++ b/m3-vue/src/components/index.ts
@@ -1,4 +1,5 @@
 export * from './adaptive'
+export * from './app-bar'
 export * from './badge'
 export * from './button'
 export * from './card'
diff --git a/m3-vue/storybook/components/M3AppBar.mdx b/m3-vue/storybook/components/M3AppBar.mdx
new file mode 100644
index 0000000..b613ee6
--- /dev/null
+++ b/m3-vue/storybook/components/M3AppBar.mdx
@@ -0,0 +1,156 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import { Localized } from '../i18n'
+import * as M3AppBarStories from './M3AppBar.stories'
+
+<Meta of={M3AppBarStories} />
+
+<Localized locale="en-US">
+
+# App bar
+
+An app bar identifies the current page and provides navigation and one or two essential actions. This library implements all six variants documented in the current [Material App bars specification](https://m3.material.io/components/app-bars/specs). The current Material 3 Expressive set and the older baseline set have different recommendations:
+
+| Appearance | Material 3 Expressive | Use |
+| --- | --- | --- |
+| `search` | Yes | A prominent search entry point on a home page. |
+| `small` | Yes | Dense pages and the collapsed state of a flexible bar. Centered text is an alignment option, not a separate variant. |
+| `medium-flexible` | Yes | A larger title, optional subtitle, and optional collapse on scroll. |
+| `large-flexible` | Yes | The strongest title emphasis, optional subtitle, and optional collapse on scroll. |
+| `medium` | **No: baseline M3** | Existing designs that still need the former medium geometry. Material recommends medium flexible for new Expressive designs. |
+| `large` | **No: baseline M3** | Existing designs that still need the former large geometry. Material recommends large flexible for new Expressive designs. |
+
+## Guide
+
+### Content and actions
+
+Keep the headline brief and specific to the page. `small` keeps it on one line; flexible variants can grow with a second line and must not be deliberately truncated. If a translated headline cannot fit, revise the copy or select a flexible appearance. Subtitles belong to small and flexible variants. For a logo or custom headline, use the `#headline` slot. Flexible bars can also show an image above the title through `#image`; it disappears in the collapsed state. Provide a real page heading; adjust `headingLevel` if the page already contains an earlier heading. Center alignment moves only the headline and subtitle; leading and trailing actions stay at the app bar edges.
+
+Pass a leading Back or Menu button in `#leading`, and up to two page actions in `#trailing`. Name icon buttons by their action. A Menu button can control an external `M3Navigation` with `appearance="rail"`, `collapse="hidden"`, and `expansion="modal"`; the app bar does not own the navigation state. Use one filled or tonal action if it needs extra emphasis. Put larger action collections in a toolbar. [Material guidelines](https://m3.material.io/components/app-bars/guidelines).
+
+### Search and scrolling
+
+For `appearance="search"`, put the existing `M3Search` in `#search` with `layout="full-screen"`. Search keeps ownership of its query, expanded view, focus, and results. The app bar positions its collapsed trigger and adapts its width: it fills the available space up to 312 px, then grows at 50% of that space. The hint should include “Search.” A logo in this variant should not open the expanded rail.
+
+`scroll="pinned"` keeps the bar visible and changes its container from surface to surface-container after scrolling. `hide` hides on forward scroll and reveals on reverse scroll. `collapse` reduces a flexible bar to the small layout until the scroll position returns to the top. `transparent` keeps controls visible over content, giving icon buttons their own filled surfaces. Pass `scrollTarget` when an element rather than `window` scrolls; use that same element to contain the sticky bar. A scroll mode is independent of the selected appearance, but `collapse` changes layout only for flexible appearances. The motion respects reduced-motion preferences.
+
+The app bar occupies the width of its containing layout. Place it in the page shell beside a rail, and provide the surrounding layout in the application. Use `tag="div"` if the page already has a banner landmark; a body-level `<header>` normally creates one. [WAI banner guidance](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html).
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `M3AppBar` | Six app bar appearances, content zones, and scroll response. |
+| Vue props and exposed `el` | Public controls and element reference. |
+
+| Prop | Default | Effect |
+| --- | --- | --- |
+| `appearance` | `small` | `search`, `small`, `medium`, `medium-flexible`, `large`, `large-flexible`. |
+| `alignment` | `start` | `start` or `center` for the headline/search hint. Centered baseline medium/large is outside the Expressive recommendation. |
+| `headline`, `subtitle` | — | Title content; subtitle is rendered for small/flexible appearances. Named children override these props. |
+| `headingLevel` | `1` | Native heading level from 1 to 6. |
+| `scroll` | `pinned` | `pinned`, `hide`, `collapse`, or `transparent`. |
+| `scrollTarget` | `window` | Scrollable `HTMLElement` or `Window` to observe. |
+| `tag` | `header` | Root `header` or `div` to fit page landmark structure. |
+| HTML attributes | — | Passed to the root element. |
+
+| Named child | Purpose |
+| --- | --- |
+| `#leading` | Back, Menu, or appropriate leading control. |
+| `#headline` | Custom headline content inside the semantic heading. |
+| `#image` | Optional image above a flexible headline; hidden while collapsed. |
+| `#subtitle` | Supporting text for small/flexible variants. |
+| `#trailing` | Page actions, ordered in the supplied DOM sequence. |
+| `#search` | Search trigger and view owner for the search variant. |
+
+The ref exposes `el`. Unslotted children act as the headline for ordinary appearances and as search content for `search`.
+
+```vue
+<M3AppBar appearance="medium-flexible" headline="Library" subtitle="Recently added" scroll="collapse" :scroll-target="scroller">
+  <template #leading>
+    <M3IconButton aria-label="Open navigation" @click="navigationOpen = true">
+      <M3Icon name="menu" />
+    </M3IconButton>
+  </template>
+  <template #trailing>
+    <M3IconButton aria-label="Favorites"><M3Icon name="favorite" /></M3IconButton>
+  </template>
+</M3AppBar>
+```
+
+## Sources
+
+- [Material App bars overview](https://m3.material.io/components/app-bars/overview)
+- [Specs](https://m3.material.io/components/app-bars/specs)
+- [Guidelines](https://m3.material.io/components/app-bars/guidelines)
+- [Accessibility](https://m3.material.io/components/app-bars/accessibility)
+
+</Localized>
+
+<Localized locale="ru-RU">
+
+# Верхняя панель приложения
+
+App bar показывает, какая страница открыта, и содержит навигацию и одно-два важнейших действия. Библиотека реализует все шесть вариантов из текущей [спецификации Material](https://m3.material.io/components/app-bars/specs). К актуальному Material 3 Expressive относятся не все:
+
+| Вид | Входит в M3 Expressive | Применение |
+| --- | --- | --- |
+| `search` | Да | Заметная точка входа в поиск на главной странице. |
+| `small` | Да | Плотная компоновка и свёрнутое состояние flexible. Центрирование заголовка — настройка, а не отдельный вид. |
+| `medium-flexible` | Да | Более крупный заголовок, подзаголовок и возможное сворачивание при прокрутке. |
+| `large-flexible` | Да | Максимальный акцент на заголовке, подзаголовок и возможное сворачивание. |
+| `medium` | **Нет: базовый M3** | Совместимость с прежней геометрией; для нового Expressive интерфейса Material рекомендует medium flexible. |
+| `large` | **Нет: базовый M3** | Совместимость с прежней геометрией; для нового Expressive интерфейса Material рекомендует large flexible. |
+
+## Руководство
+
+### Содержимое и действия
+
+Заголовок должен коротко описывать текущую страницу. В `small` он однострочный; flexible может вырасти для второй строки без намеренного усечения. Если перевод не помещается, пересмотрите формулировку или выберите flexible вид. Подзаголовок поддерживается в small и flexible. Для особой разметки заголовка используйте `#headline`. Изображение над заголовком flexible передайте через `#image`; при сворачивании оно скрывается. Сам заголовок остаётся настоящим heading; `headingLevel` позволяет согласовать его с иерархией страницы. При центрировании смещаются только заголовок и подзаголовок: ведущие и завершающие действия остаются у краёв панели.
+
+В `#leading` разместите Back или Menu, в `#trailing` — максимум два действия страницы. Дайте иконочным кнопкам названия по их действию. Menu может управлять внешним `M3Navigation` с `appearance="rail"`, `collapse="hidden"`, `expansion="modal"`; app bar не владеет состоянием навигации. Для акцента используйте одну filled/tonal кнопку. Большое число действий вынесите в toolbar. [Рекомендации Material](https://m3.material.io/components/app-bars/guidelines).
+
+### Поиск и прокрутка
+
+Для `appearance="search"` передайте существующий `M3Search` в `#search` с `layout="full-screen"`. Search управляет запросом, раскрытым видом, фокусом и результатами; app bar только размещает свёрнутую строку. До ширины 312 px она занимает всё доступное место, затем растёт как 50% доступного места. В подсказке должно быть слово «Поиск». Логотип в этом виде не должен открывать раскрытый rail.
+
+`scroll="pinned"` оставляет панель на экране и после прокрутки меняет `surface` на `surface-container`. `hide` скрывает её при прокрутке вперёд и возвращает при обратной. `collapse` сворачивает flexible в small до возвращения страницы к началу. `transparent` оставляет действия поверх контента на собственных заполненных поверхностях. Если прокручивается элемент, а не `window`, передайте его через `scrollTarget` и поместите липкую панель в тот же контейнер. Режим `collapse` меняет layout только у flexible видов. При ограничении движения анимация отключается.
+
+Панель занимает ширину своего контейнера. Приложение размещает её в компоновке страницы рядом с rail. Если в документе уже есть landmark `banner`, используйте `tag="div"`: `<header>` на уровне страницы обычно создаёт такой landmark. [WAI о banner](https://www.w3.org/WAI/ARIA/apg/patterns/landmarks/examples/banner.html).
+
+## API
+
+| Экспорт | Назначение |
+| --- | --- |
+| `M3AppBar` | Шесть вариантов панели, области содержимого и реакция на прокрутку. |
+| Props Vue и `el` | Публичные настройки и ссылка на элемент. |
+
+| Prop | Значение по умолчанию | Действие |
+| --- | --- | --- |
+| `appearance` | `small` | `search`, `small`, `medium`, `medium-flexible`, `large`, `large-flexible`. |
+| `alignment` | `start` | `start` или `center` для заголовка/подсказки. Центрирование baseline medium/large вне рекомендации Expressive. |
+| `headline`, `subtitle` | — | Текст заголовка и подзаголовка; последний рисуется только в small/flexible. Именованные элементы имеют приоритет. |
+| `headingLevel` | `1` | Уровень настоящего заголовка от 1 до 6. |
+| `scroll` | `pinned` | `pinned`, `hide`, `collapse` или `transparent`. |
+| `scrollTarget` | `window` | Прокручиваемый `HTMLElement` или `Window`. |
+| `tag` | `header` | Корневой `header` или `div` для структуры landmarks страницы. |
+| HTML-атрибуты | — | Передаются корневому элементу. |
+
+| Именованный элемент | Назначение |
+| --- | --- |
+| `#leading` | Back, Menu или другое уместное ведущее действие. |
+| `#headline` | Своя разметка внутри семантического заголовка. |
+| `#image` | Изображение над заголовком flexible, скрываемое при сворачивании. |
+| `#subtitle` | Контекст для small/flexible. |
+| `#trailing` | Действия страницы в заданном порядке DOM. |
+| `#search` | Поисковая строка и управляющий Search. |
+
+Ref предоставляет `el`. Дочерние элементы без имени становятся заголовком обычного варианта или содержимым поисковой области для `search`.
+
+## Источники
+
+- [Обзор Material App bars](https://m3.material.io/components/app-bars/overview)
+- [Спецификация](https://m3.material.io/components/app-bars/specs)
+- [Рекомендации](https://m3.material.io/components/app-bars/guidelines)
+- [Доступность](https://m3.material.io/components/app-bars/accessibility)
+
+</Localized>
diff --git a/m3-vue/storybook/components/M3AppBar.stories.ts b/m3-vue/storybook/components/M3AppBar.stories.ts
new file mode 100644
index 0000000..5f083b6
--- /dev/null
+++ b/m3-vue/storybook/components/M3AppBar.stories.ts
@@ -0,0 +1,46 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3AppBar } from '@/components/app-bar'
+
+import AppBarExample from '../examples/app-bar/AppBarExample.vue'
+
+const meta = {
+  title: 'Components/M3AppBar',
+  component: M3AppBar,
+  args: { appearance: 'small', alignment: 'start', scroll: 'pinned' },
+  argTypes: {
+    appearance: { control: 'select', options: ['search', 'small', 'medium', 'medium-flexible', 'large', 'large-flexible'] },
+    alignment: { control: 'select', options: ['start', 'center'] },
+    scroll: { control: 'select', options: ['pinned', 'hide', 'collapse', 'transparent'] },
+    scrollTarget: { control: false },
+    headline: { control: false },
+    subtitle: { control: false },
+    headingLevel: { control: false },
+  },
+  render: (args: Record<string, unknown>, { globals }) => ({
+    components: { AppBarExample },
+    setup: () => ({
+      appearance: args.appearance,
+      scroll: args.scroll,
+      centered: args.alignment === 'center',
+      subtitle: args.appearance === 'small' || String(args.appearance).includes('flexible'),
+      locale: globals.locale,
+    }),
+    template: '<AppBarExample :appearance="appearance" :scroll="scroll" :centered="centered" :subtitle="subtitle" :locale="locale" />',
+  }),
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof M3AppBar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Search: Story = { args: { appearance: 'search' } }
+export const Small: Story = {}
+export const SmallCentered: Story = { args: { alignment: 'center' } }
+export const Medium: Story = { args: { appearance: 'medium' } }
+export const MediumFlexible: Story = { args: { appearance: 'medium-flexible', scroll: 'collapse' } }
+export const Large: Story = { args: { appearance: 'large' } }
+export const LargeFlexible: Story = { args: { appearance: 'large-flexible', scroll: 'collapse' } }
+export const HideOnScroll: Story = { args: { scroll: 'hide' } }
+export const TransparentOnScroll: Story = { args: { scroll: 'transparent' } }
diff --git a/m3-vue/storybook/examples/app-bar/AppBarExample.vue b/m3-vue/storybook/examples/app-bar/AppBarExample.vue
new file mode 100644
index 0000000..567c1ab
--- /dev/null
+++ b/m3-vue/storybook/examples/app-bar/AppBarExample.vue
@@ -0,0 +1,156 @@
+<template>
+    <main ref="scroller" class="app-bar-example">
+        <M3AppBar
+            :appearance="appearance"
+            :alignment="centered ? 'center' : 'start'"
+            :scroll="scroll"
+            :scroll-target="scroller"
+            :headline="text.title"
+            :subtitle="subtitle ? text.subtitle : undefined"
+        >
+            <template #leading>
+                <M3IconButton :aria-label="text.menu" @click="navigationOpen = true">
+                    <M3Icon name="menu" />
+                </M3IconButton>
+            </template>
+
+            <template v-if="appearance === 'search'" #search>
+                <M3Search
+                    v-model:query="query"
+                    v-model:open="searchOpen"
+                    :label="text.search"
+                    :status="`${results.length} results`"
+                    :hint="text.search"
+                    :back-label="text.back"
+                    :clear-label="text.close"
+                    layout="full-screen"
+                >
+                    <template #results>
+                        <div class="app-bar-example__results">
+                            {{ results.join(' · ') }}
+                        </div>
+                    </template>
+                </M3Search>
+            </template>
+
+            <template #trailing>
+                <M3IconButton :aria-label="text.favorite">
+                    <M3Icon name="favorite" />
+                </M3IconButton>
+                <M3IconButton :aria-label="text.notifications">
+                    <M3Icon name="notifications" />
+                </M3IconButton>
+            </template>
+        </M3AppBar>
+
+        <M3Navigation
+            v-model:expanded="navigationOpen"
+            appearance="rail"
+            expansion="modal"
+            collapse="hidden"
+        >
+            <M3NavigationTab :label="text.home">
+                <M3Icon name="home" />
+            </M3NavigationTab>
+            <M3NavigationTab :label="text.library" active>
+                <M3Icon name="book" />
+            </M3NavigationTab>
+            <M3NavigationTab :label="text.settings">
+                <M3Icon name="settings" />
+            </M3NavigationTab>
+        </M3Navigation>
+
+        <div class="app-bar-example__content">
+            <h2>{{ text.section }}</h2>
+            <div class="app-bar-example__grid">
+                <article v-for="(card, index) in cards" :key="`${card}-${index}`">
+                    {{ card }}
+                </article>
+            </div>
+        </div>
+    </main>
+</template>
+
+<script lang="ts" setup>
+import type {
+  AppBarAppearance,
+  AppBarScroll,
+} from '@modulify/m3-foundation/types/components/app-bar'
+import type { PropType } from 'vue'
+
+import { computed, ref } from 'vue'
+
+import { M3AppBar } from '@/components/app-bar'
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import { M3Navigation, M3NavigationTab } from '@/components/navigation'
+import { M3Search } from '@/components/search'
+
+import { localize } from '../../i18n'
+
+const messages = {
+  'en-US': {
+    title: 'Your library', subtitle: 'Recently added', search: 'Search your library', menu: 'Open navigation',
+    back: 'Back to library', close: 'Clear search', favorite: 'Favorites', notifications: 'Notifications',
+    home: 'Home', library: 'Library', settings: 'Settings', section: 'Recent items',
+    cards: ['Reading list', 'Travel ideas', 'Project notes', 'Saved links', 'Garden plans', 'Music for later'],
+  },
+  'ru-RU': {
+    title: 'Библиотека', subtitle: 'Недавно добавлено', search: 'Поиск в библиотеке', menu: 'Открыть навигацию',
+    back: 'Назад к библиотеке', close: 'Очистить поиск', favorite: 'Избранное', notifications: 'Уведомления',
+    home: 'Главная', library: 'Библиотека', settings: 'Настройки', section: 'Недавние записи',
+    cards: ['Список для чтения', 'Идеи поездок', 'Заметки проекта', 'Сохранённые ссылки', 'Планы сада', 'Музыка на потом'],
+  },
+}
+
+const props = defineProps({
+  appearance: { type: String as PropType<AppBarAppearance>, default: 'small' },
+  scroll: { type: String as PropType<AppBarScroll>, default: 'pinned' },
+  centered: { type: Boolean, default: false },
+  subtitle: { type: Boolean, default: false },
+  locale: { type: String, default: 'en-US' },
+})
+
+const text = computed(() => localize(props.locale, messages))
+const cards = computed(() => text.value.cards.concat(text.value.cards, text.value.cards))
+const results = computed(() => text.value.cards.filter(card => card.toLocaleLowerCase(props.locale).includes(query.value.toLocaleLowerCase(props.locale))))
+const scroller = ref<HTMLElement | null>(null)
+const navigationOpen = ref(false)
+const searchOpen = ref(false)
+const query = ref('')
+</script>
+
+<style scoped>
+.app-bar-example {
+  block-size: 100vh;
+  overflow-y: auto;
+  background: var(--m3-sys-surface);
+}
+
+.app-bar-example__content {
+  max-inline-size: 1100px;
+  padding: 24px;
+  margin-inline: auto;
+}
+
+.app-bar-example__content h2 {
+  margin-block: 16px 24px;
+}
+
+.app-bar-example__grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 16px;
+}
+
+.app-bar-example__grid article {
+  min-block-size: 120px;
+  padding: 24px;
+  border-radius: 24px;
+  background: var(--m3-sys-surface-container);
+}
+
+.app-bar-example__results {
+  padding: 24px;
+}
+</style>
diff --git a/m3-vue/tests/M3AppBar.e2e.ts b/m3-vue/tests/M3AppBar.e2e.ts
new file mode 100644
index 0000000..46410d0
--- /dev/null
+++ b/m3-vue/tests/M3AppBar.e2e.ts
@@ -0,0 +1,119 @@
+import { createApp, h, nextTick } from 'vue'
+import { page } from 'vitest/browser'
+
+import { M3AppBar } from '@/components/app-bar'
+import { M3IconButton } from '@/components/icon-button'
+
+const waitFor = async (assertion: () => void) => {
+  const startedAt = performance.now()
+  while (performance.now() - startedAt < 2000) {
+    try {
+      assertion()
+      return
+    } catch {
+      await new Promise(resolve => setTimeout(resolve, 16))
+    }
+  }
+  assertion()
+}
+
+test('renders the six documented heights and grows flexible content without truncation', async () => {
+  await page.viewport(900, 800)
+  const cases = [
+    ['search', 64], ['small', 64], ['medium', 112],
+    ['medium-flexible', 112], ['large', 152], ['large-flexible', 120],
+  ] as const
+
+  for (const [appearance, height] of cases) {
+    const mountPoint = document.createElement('div')
+    document.body.append(mountPoint)
+    const app = createApp(M3AppBar, { appearance, headline: 'Library' })
+    app.mount(mountPoint)
+    expect(mountPoint.querySelector('.m3-app-bar')!.getBoundingClientRect().height).toBe(height)
+    app.unmount()
+    mountPoint.remove()
+  }
+
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const app = createApp(M3AppBar, {
+    appearance: 'large-flexible',
+    headline: 'A long title that needs two lines across a compact window',
+    subtitle: 'Additional context',
+  })
+  app.mount(mountPoint)
+  try {
+    await page.viewport(360, 800)
+    const bar = mountPoint.querySelector('.m3-app-bar')!
+    const headline = mountPoint.querySelector('.m3-app-bar__headline')!
+    expect(bar.getBoundingClientRect().height).toBeGreaterThanOrEqual(152)
+    expect(headline.scrollHeight).toBeLessThanOrEqual(headline.clientHeight)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test.each(['ltr', 'rtl'] as const)('centers a small title while keeping actions at the %s edges', direction => {
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const app = createApp({
+    render: () => h(M3AppBar, { headline: 'Library', subtitle: 'Recent', alignment: 'center', dir: direction }, {
+      leading: () => h(M3IconButton, { 'aria-label': 'Back' }, () => '←'),
+      trailing: () => [
+        h(M3IconButton, { 'aria-label': 'Favorites' }, () => '★'),
+        h(M3IconButton, { 'aria-label': 'Settings' }, () => '⚙'),
+      ],
+    }),
+  })
+  app.mount(mountPoint)
+
+  try {
+    const bar = mountPoint.querySelector('.m3-app-bar')!.getBoundingClientRect()
+    const title = mountPoint.querySelector('.m3-app-bar__title')!.getBoundingClientRect()
+    const leading = mountPoint.querySelector('.m3-app-bar__leading .m3-icon-button')!.getBoundingClientRect()
+    const trailing = mountPoint.querySelector('.m3-app-bar__trailing .m3-icon-button:last-child')!.getBoundingClientRect()
+
+    expect(Math.abs((title.left + title.right) / 2 - (bar.left + bar.right) / 2)).toBeLessThan(1)
+    expect(direction === 'ltr' ? leading.left - bar.left : bar.right - leading.right).toBe(4)
+    expect(direction === 'ltr' ? bar.right - trailing.right : trailing.left - bar.left).toBe(4)
+    expect(leading.width).toBe(48)
+    expect(trailing.width).toBe(48)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test('collapses a flexible bar against its own scroll container and expands at the top', async () => {
+  await page.viewport(900, 800)
+  const scroller = document.createElement('main')
+  Object.assign(scroller.style, { height: '300px', overflowY: 'auto' })
+  document.body.append(scroller)
+  const app = createApp({
+    render: () => [
+      h(M3AppBar, { appearance: 'medium-flexible', headline: 'Library', subtitle: 'Recent items', scroll: 'collapse', scrollTarget: scroller }),
+      h('div', { style: { height: '1000px' } }),
+    ],
+  })
+  app.mount(scroller)
+
+  try {
+    const bar = scroller.querySelector<HTMLElement>('.m3-app-bar')!
+    expect(bar.getBoundingClientRect().height).toBe(136)
+    const transitions = new Set<string>()
+    bar.addEventListener('transitionrun', event => transitions.add(event.propertyName))
+    scroller.scrollTop = 100
+    await nextTick()
+    await waitFor(() => expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(true))
+    await waitFor(() => expect(transitions.has('height')).toBe(true))
+    await waitFor(() => expect(bar.getBoundingClientRect().height).toBe(64))
+    scroller.scrollTop = 0
+    await nextTick()
+    await waitFor(() => expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(false))
+    await waitFor(() => expect(bar.getBoundingClientRect().height).toBe(136))
+  } finally {
+    app.unmount()
+    scroller.remove()
+  }
+})
diff --git a/m3-vue/tests/M3AppBar.test.ts b/m3-vue/tests/M3AppBar.test.ts
new file mode 100644
index 0000000..ddaa621
--- /dev/null
+++ b/m3-vue/tests/M3AppBar.test.ts
@@ -0,0 +1,89 @@
+import { defineComponent } from 'vue'
+import { fireEvent } from '@testing-library/vue'
+import { h, nextTick, ref } from 'vue'
+import { render, screen } from '@testing-library/vue'
+
+import { M3AppBar } from '@/components/app-bar'
+import { M3Search } from '@/components/search'
+
+const appearances = ['search', 'small', 'medium', 'medium-flexible', 'large', 'large-flexible'] as const
+
+describe('m3-vue/app-bar', () => {
+  test.each(appearances)('renders %s with one appropriate title', appearance => {
+    const view = render(M3AppBar, {
+      props: { appearance, headline: 'Library', subtitle: 'Recent items' },
+      slots: {
+        leading: () => h('button', 'Menu'),
+        trailing: () => h('button', 'Favorite'),
+      },
+    })
+
+    const bar = view.container.querySelector('.m3-app-bar')!
+    expect(bar.classList.contains(`m3-app-bar_${appearance}`)).toBe(true)
+    expect(screen.getByRole('button', { name: 'Menu' })).not.toBeNull()
+    expect(screen.getByRole('button', { name: 'Favorite' })).not.toBeNull()
+    expect(screen.queryByRole('heading', { name: 'Library' }) !== null).toBe(appearance !== 'search')
+    expect(view.container.querySelector('.m3-app-bar__subtitle') !== null).toBe(
+      appearance === 'small' || appearance.includes('flexible')
+    )
+  })
+
+  test('tracks a supplied scroll root and re-expands flexible content at the top', async () => {
+    const scroller = document.createElement('div')
+    const view = render(M3AppBar, {
+      props: { appearance: 'medium-flexible', headline: 'Library', scroll: 'collapse', scrollTarget: scroller },
+    })
+    const bar = view.container.querySelector('.m3-app-bar')!
+
+    scroller.scrollTop = 40
+    await fireEvent.scroll(scroller)
+    await nextTick()
+    expect(bar.classList.contains('m3-app-bar_under')).toBe(true)
+    expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(true)
+
+    scroller.scrollTop = 0
+    await fireEvent.scroll(scroller)
+    await nextTick()
+    expect(bar.classList.contains('m3-app-bar_collapsed')).toBe(false)
+    expect(bar.classList.contains('m3-app-bar_under')).toBe(false)
+  })
+
+  test('shows a flexible image until the bar collapses', async () => {
+    const scroller = document.createElement('div')
+    const view = render(M3AppBar, {
+      props: { appearance: 'large-flexible', headline: 'Library', scroll: 'collapse', scrollTarget: scroller },
+      slots: { image: () => h('img', { src: '/library.svg', alt: '' }) },
+    })
+
+    expect(view.container.querySelector('.m3-app-bar__image img')).not.toBeNull()
+    scroller.scrollTop = 40
+    await fireEvent.scroll(scroller)
+    await nextTick()
+    expect(view.container.querySelector('.m3-app-bar__image')).toBeNull()
+  })
+
+  test('keeps one search view owner when composed with M3Search', async () => {
+    const Example = defineComponent({
+      setup () {
+        const open = ref(false)
+        const query = ref('')
+        return () => h(M3AppBar, { appearance: 'search' }, {
+          search: () => h(M3Search, {
+            query: query.value,
+            open: open.value,
+            label: 'Search library',
+            status: '',
+            layout: 'full-screen',
+            'onUpdate:query': (value: string) => query.value = value,
+            'onUpdate:open': (value: boolean) => open.value = value,
+          }),
+        })
+      },
+    })
+
+    render(Example)
+    await fireEvent.click(screen.getByRole('button', { name: 'Search library' }))
+    await nextTick()
+    expect(screen.getAllByRole('dialog', { name: 'Search library' })).toHaveLength(1)
+  })
+})

From 3f142de1c1729bde5871f7c428cc259c6f727173 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 9 Oct 2026 11:38:34 +0400
Subject: [PATCH 09/20] refactor(m3-foundation): Page layer levels were
 centralized

---
 .../assets/stylesheets/basics/layers.scss     | 20 +++++++++++++++++++
 .../stylesheets/components/app-bar/index.scss |  3 ++-
 .../stylesheets/components/dialog/index.scss  |  5 +++--
 .../components/navigation/index.scss          |  3 ++-
 .../components/plane-tooltip/index.scss       |  3 +--
 .../stylesheets/components/popper/index.scss  |  4 +++-
 .../components/rich-tooltip/index.scss        |  3 +--
 .../stylesheets/components/scrim/index.scss   |  3 ++-
 .../stylesheets/components/search/index.scss  |  3 ++-
 .../components/side-sheet/index.scss          |  3 ++-
 .../components/snackbar/index.scss            |  3 ++-
 11 files changed, 40 insertions(+), 13 deletions(-)
 create mode 100644 m3-foundation/assets/stylesheets/basics/layers.scss

diff --git a/m3-foundation/assets/stylesheets/basics/layers.scss b/m3-foundation/assets/stylesheets/basics/layers.scss
new file mode 100644
index 0000000..b5cb6e2
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/basics/layers.scss
@@ -0,0 +1,20 @@
+@use 'sass:map';
+
+// Page-level layers. Small z-index values inside a component remain local.
+$levels: (
+  'app-bar': 10,
+  'toolbar': 100,
+  'snackbar': 900,
+  'scrim': 1000,
+  'modal': 1001,
+  'popover': 1100,
+  'search': 1200,
+);
+
+@function level($name) {
+  @if not map.has-key($levels, $name) {
+    @error 'Unknown Material layer: #{$name}';
+  }
+
+  @return map.get($levels, $name);
+}
diff --git a/m3-foundation/assets/stylesheets/components/app-bar/index.scss b/m3-foundation/assets/stylesheets/components/app-bar/index.scss
index e8d2c6b..6dc9e1c 100644
--- a/m3-foundation/assets/stylesheets/components/app-bar/index.scss
+++ b/m3-foundation/assets/stylesheets/components/app-bar/index.scss
@@ -1,3 +1,4 @@
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/typography' as m3-typography;
 
@@ -13,7 +14,7 @@
   color: var(--m3-sys-on-surface);
   position: sticky;
   inset-block-start: 0;
-  z-index: 10;
+  z-index: m3-layers.level('app-bar');
   transition:
     #{m3-motion.timing-standard(background-color, 'short4')},
     #{m3-motion.timing-standard(block-size, 'medium2')},
diff --git a/m3-foundation/assets/stylesheets/components/dialog/index.scss b/m3-foundation/assets/stylesheets/components/dialog/index.scss
index e5eac5c..fc869bf 100644
--- a/m3-foundation/assets/stylesheets/components/dialog/index.scss
+++ b/m3-foundation/assets/stylesheets/components/dialog/index.scss
@@ -1,3 +1,4 @@
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/shape' as m3-shape;
 
@@ -7,7 +8,7 @@
   block-size: 100%;
   align-items: center;
   justify-content: center;
-  z-index: 1000;
+  z-index: m3-layers.level('modal');
   position: fixed;
   inset-inline-start: 0;
   inset-block-start: 0;
@@ -92,4 +93,4 @@
     justify-content: flex-end;
     gap: 8px;
   }
-}
\ No newline at end of file
+}
diff --git a/m3-foundation/assets/stylesheets/components/navigation/index.scss b/m3-foundation/assets/stylesheets/components/navigation/index.scss
index 13c2b15..fa9463e 100644
--- a/m3-foundation/assets/stylesheets/components/navigation/index.scss
+++ b/m3-foundation/assets/stylesheets/components/navigation/index.scss
@@ -1,4 +1,5 @@
 @use '../../basics/layout' as m3-layout;
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/shape' as m3-shape;
 @use '../../basics/typography' as m3-typography;
@@ -63,7 +64,7 @@
       m3-motion.timing-emphasized(padding),
       m3-motion.timing-emphasized(gap)
     ;
-    z-index: 1000;
+    z-index: m3-layers.level('modal');
   }
 
   &_rail {
diff --git a/m3-foundation/assets/stylesheets/components/plane-tooltip/index.scss b/m3-foundation/assets/stylesheets/components/plane-tooltip/index.scss
index 112df02..d596a33 100644
--- a/m3-foundation/assets/stylesheets/components/plane-tooltip/index.scss
+++ b/m3-foundation/assets/stylesheets/components/plane-tooltip/index.scss
@@ -8,5 +8,4 @@
   @include m3-shape.corner('extra-small');
   color: var(--m3-sys-inverse-on-surface);
   @include m3-typography.body-small;
-  z-index: 11;
-}
\ No newline at end of file
+}
diff --git a/m3-foundation/assets/stylesheets/components/popper/index.scss b/m3-foundation/assets/stylesheets/components/popper/index.scss
index 6592731..6ddf62e 100644
--- a/m3-foundation/assets/stylesheets/components/popper/index.scss
+++ b/m3-foundation/assets/stylesheets/components/popper/index.scss
@@ -1,10 +1,12 @@
-@use "../../basics/motion" as m3-motion;
+@use '../../basics/layers' as m3-layers;
+@use '../../basics/motion' as m3-motion;
 
 .m3-popper-positioner {
   position: absolute;
   top: 0;
   left: 0;
   pointer-events: none;
+  z-index: m3-layers.level('popover');
 }
 
 .m3-popper {
diff --git a/m3-foundation/assets/stylesheets/components/rich-tooltip/index.scss b/m3-foundation/assets/stylesheets/components/rich-tooltip/index.scss
index f6767b1..2a02cef 100644
--- a/m3-foundation/assets/stylesheets/components/rich-tooltip/index.scss
+++ b/m3-foundation/assets/stylesheets/components/rich-tooltip/index.scss
@@ -13,7 +13,6 @@
   background: var(--m3-sys-surface-container);
   box-shadow: var(--m3-elevation-2);
   color: var(--m3-sys-on-surface-variant);
-  z-index: 10;
 
   &__content {
     display: flex;
@@ -37,4 +36,4 @@
     align-self: stretch;
     gap: 8px;
   }
-}
\ No newline at end of file
+}
diff --git a/m3-foundation/assets/stylesheets/components/scrim/index.scss b/m3-foundation/assets/stylesheets/components/scrim/index.scss
index aedf614..516a100 100644
--- a/m3-foundation/assets/stylesheets/components/scrim/index.scss
+++ b/m3-foundation/assets/stylesheets/components/scrim/index.scss
@@ -1,3 +1,4 @@
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/palette' as *;
 
 .m3-scrim {
@@ -5,7 +6,7 @@
   inline-size: 100%;
   block-size: 100%;
   background: rgba($m3-palette-neutral-variant-20, 0.4);
-  z-index: 1000;
+  z-index: m3-layers.level('scrim');
   position: fixed;
   inset-inline-start: 0;
   inset-block-start: 0;
diff --git a/m3-foundation/assets/stylesheets/components/search/index.scss b/m3-foundation/assets/stylesheets/components/search/index.scss
index 3b7e026..a760f8d 100644
--- a/m3-foundation/assets/stylesheets/components/search/index.scss
+++ b/m3-foundation/assets/stylesheets/components/search/index.scss
@@ -1,3 +1,4 @@
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/typography' as m3-typography;
 
@@ -104,7 +105,7 @@
     pointer-events: none;
     position: fixed;
     inset: 0;
-    z-index: var(--m3-search-z-index, 1200);
+    z-index: var(--m3-search-z-index, #{m3-layers.level('search')});
   }
 
   &__scrim {
diff --git a/m3-foundation/assets/stylesheets/components/side-sheet/index.scss b/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
index abd821f..dc6b72a 100644
--- a/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
+++ b/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
@@ -1,3 +1,4 @@
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/shape' as m3-shape;
 @use '../../basics/typography' as m3-typography;
 
@@ -14,7 +15,7 @@
   position: fixed;
   inset-block-start: 0;
   right: 0;
-  z-index: 1000;
+  z-index: m3-layers.level('modal');
 
   background: var(--m3-sys-surface-container-low);
   color: var(--m3-sys-on-surface-variant);
diff --git a/m3-foundation/assets/stylesheets/components/snackbar/index.scss b/m3-foundation/assets/stylesheets/components/snackbar/index.scss
index 75c809b..5a7255a 100644
--- a/m3-foundation/assets/stylesheets/components/snackbar/index.scss
+++ b/m3-foundation/assets/stylesheets/components/snackbar/index.scss
@@ -1,4 +1,5 @@
 @use '../../basics/layout' as m3-layout;
+@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/typography' as m3-typography;
 
@@ -9,7 +10,7 @@
   position: fixed;
   inset-inline-start: var(--m3-snackbar-inset-inline-start);
   inset-block-end: var(--m3-snackbar-inset-block-end);
-  z-index: 900;
+  z-index: m3-layers.level('snackbar');
   max-inline-size: calc(100vw - var(--m3-snackbar-inset-inline-start) - 16px);
   pointer-events: none;
 

From 4f39a36c5fd9dad032dca5998796802fb258f666 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 9 Oct 2026 11:39:18 +0400
Subject: [PATCH 10/20] feat(m3-foundation): Toolbar styles and layout helpers
 were added

---
 .../assets/stylesheets/components/index.scss  |   3 +-
 .../stylesheets/components/menu/index.scss    |   2 +-
 .../stylesheets/components/toolbar/index.scss | 224 ++++++++++++++++++
 m3-foundation/lib/toolbar.ts                  |  26 ++
 m3-foundation/tests/toolbar.test.ts           |  20 ++
 m3-foundation/types/components/toolbar.d.ts   |  14 ++
 m3-foundation/vite.config.ts                  |   1 +
 7 files changed, 288 insertions(+), 2 deletions(-)
 create mode 100644 m3-foundation/assets/stylesheets/components/toolbar/index.scss
 create mode 100644 m3-foundation/lib/toolbar.ts
 create mode 100644 m3-foundation/tests/toolbar.test.ts
 create mode 100644 m3-foundation/types/components/toolbar.d.ts

diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index f8b09aa..35981a5 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -25,6 +25,7 @@
 @use 'side-sheet';
 @use 'snackbar';
 @use 'slider';
-@use 'switch';
 @use 'surface';
+@use 'switch';
 @use 'text-field';
+@use 'toolbar';
diff --git a/m3-foundation/assets/stylesheets/components/menu/index.scss b/m3-foundation/assets/stylesheets/components/menu/index.scss
index 6c9f188..8d9588c 100644
--- a/m3-foundation/assets/stylesheets/components/menu/index.scss
+++ b/m3-foundation/assets/stylesheets/components/menu/index.scss
@@ -12,7 +12,6 @@
   flex-direction: column;
   background: var(--m3-sys-surface-container);
   box-shadow: var(--m3-elevation-2);
-  z-index: 3;
 }
 
 .m3-menu-item {
@@ -86,5 +85,6 @@
     align-items: flex-start;
     flex: 1 0 0;
     color: var(--m3-sys-on-surface);
+    text-align: start;
   }
 }
diff --git a/m3-foundation/assets/stylesheets/components/toolbar/index.scss b/m3-foundation/assets/stylesheets/components/toolbar/index.scss
new file mode 100644
index 0000000..49022a4
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/toolbar/index.scss
@@ -0,0 +1,224 @@
+@use '../../basics/layers' as m3-layers;
+@use '../../basics/motion' as m3-motion;
+
+.m3-toolbar {
+  --m3-toolbar-container: var(--m3-sys-surface-container);
+  --m3-toolbar-content: var(--m3-sys-on-surface-variant);
+  --m3-toolbar-selected-container: var(--m3-sys-secondary-container);
+  --m3-toolbar-selected-content: var(--m3-sys-on-secondary-container);
+
+  display: flex;
+  box-sizing: border-box;
+  align-items: center;
+  z-index: m3-layers.level('toolbar');
+  position: fixed;
+  transition: m3-motion.timing-standard(transform, 'medium2');
+
+  &_vibrant {
+    --m3-toolbar-container: var(--m3-sys-primary-container);
+    --m3-toolbar-content: var(--m3-sys-on-primary-container);
+    --m3-toolbar-selected-container: var(--m3-sys-surface-container);
+    --m3-toolbar-selected-content: var(--m3-sys-on-surface);
+  }
+
+  &_docked {
+    inline-size: 100%;
+    min-block-size: calc(64px + env(safe-area-inset-bottom, 0px));
+    padding-block-end: env(safe-area-inset-bottom, 0px);
+    background: var(--m3-toolbar-container);
+    inset-inline: 0;
+    inset-block-end: 0;
+  }
+
+  &_docked#{&}_hidden {
+    transform: translateY(110%);
+  }
+
+  &_floating {
+    max-inline-size: calc(100vw - 32px);
+    gap: 8px;
+    inset-block-end: calc(16px + env(safe-area-inset-bottom, 0px));
+    inset-inline-start: 50%;
+    translate: -50% 0;
+  }
+
+  &_floating#{&}_hidden {
+    transform: translateY(calc(100% + 32px));
+  }
+
+  &_vertical {
+    max-inline-size: none;
+    max-block-size: calc(100vh - 48px);
+    flex-direction: column;
+    inset-block-end: auto;
+    inset-block-start: 50%;
+    inset-inline-start: auto;
+    inset-inline-end: 24px;
+    translate: 0 -50%;
+  }
+
+  &_vertical#{&}_side-start {
+    inset-inline-start: 24px;
+    inset-inline-end: auto;
+  }
+
+  &_vertical#{&}_hidden {
+    transform: translateX(calc(100% + 24px));
+  }
+
+  &_vertical#{&}_side-start#{&}_hidden {
+    transform: translateX(calc(-100% - 24px));
+  }
+
+  &_vertical#{&}_hidden:dir(rtl) {
+    transform: translateX(calc(-100% - 24px));
+  }
+
+  &_vertical#{&}_side-start#{&}_hidden:dir(rtl) {
+    transform: translateX(calc(100% + 24px));
+  }
+
+  &__container {
+    display: flex;
+    box-sizing: border-box;
+    min-inline-size: 0;
+    max-inline-size: var(--m3-toolbar-expanded-size, 100vw);
+    block-size: 64px;
+    padding-inline: 8px;
+    align-items: center;
+    background: var(--m3-toolbar-container);
+    border-radius: 9999px;
+    box-shadow: var(--m3-elevation-3);
+    overflow: hidden;
+    transition:
+      m3-motion.timing-standard(max-inline-size, 'medium2'),
+      m3-motion.timing-standard(max-block-size, 'medium2'),
+      m3-motion.timing-standard(padding, 'medium2'),
+      m3-motion.timing-standard(opacity, 'short4'),
+      m3-motion.timing-standard(transform, 'medium2');
+  }
+
+  &_docked &__container {
+    inline-size: 100%;
+    max-inline-size: none;
+    padding-inline: 16px;
+    border-radius: 0;
+    box-shadow: none;
+  }
+
+  &_vertical &__container {
+    inline-size: 64px;
+    block-size: auto;
+    max-block-size: var(--m3-toolbar-expanded-size, calc(100vh - 48px));
+    padding-block: 8px;
+    flex-direction: column;
+  }
+
+  &_collapsed &__container {
+    max-inline-size: 0;
+    padding-inline: 0;
+    opacity: 0;
+    transform: scale(0.8);
+    pointer-events: none;
+  }
+
+  &_vertical#{&}_collapsed &__container {
+    max-inline-size: 64px;
+    max-block-size: 0;
+    padding-block: 0;
+  }
+
+  &__actions {
+    display: flex;
+    min-inline-size: 0;
+    align-items: center;
+    gap: 4px;
+  }
+
+  &_floating &__actions {
+    inline-size: max-content;
+    flex: 0 0 auto;
+  }
+
+  &_docked &__actions {
+    inline-size: 100%;
+    justify-content: space-evenly;
+    gap: clamp(4px, 2vw, 32px);
+  }
+
+  &_vertical &__actions {
+    flex-direction: column;
+  }
+
+  &__custom {
+    display: flex;
+    min-inline-size: 0;
+    align-items: center;
+    gap: 4px;
+  }
+
+  &_vertical &__custom {
+    flex-direction: column;
+  }
+
+  &__action {
+    display: flex;
+    box-sizing: border-box;
+    inline-size: 48px;
+    block-size: 48px;
+    flex: 0 0 48px;
+    align-items: center;
+    justify-content: center;
+  }
+
+  &__action .m3-icon-button {
+    --content-color: var(--m3-toolbar-content);
+    --state-color: var(--m3-toolbar-content);
+    --m3-ripple-color: var(--m3-toolbar-content);
+  }
+
+  &__action .m3-icon-button_tonal,
+  &__action .m3-icon-button_toggleable.m3-icon-button_selected {
+    --background-color: var(--m3-toolbar-selected-container);
+    --content-color: var(--m3-toolbar-selected-content);
+    --state-color: var(--m3-toolbar-selected-content);
+    --m3-ripple-color: var(--m3-toolbar-selected-content);
+  }
+
+  &__fab {
+    display: flex;
+    flex: 0 0 auto;
+  }
+
+  &__menu {
+    inline-size: max-content;
+    min-inline-size: 200px;
+    max-inline-size: min(280px, calc(100vw - 32px));
+  }
+
+  &__menu .m3-menu-item__body {
+    display: block;
+    min-inline-size: 0;
+    flex: 1 1 auto;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  &_standard &__fab .m3-fab-button {
+    --background-color: var(--m3-sys-secondary-container);
+    --content-color: var(--m3-sys-on-secondary-container);
+  }
+
+  &_vibrant &__fab .m3-fab-button {
+    --background-color: var(--m3-sys-tertiary-container);
+    --content-color: var(--m3-sys-on-tertiary-container);
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    &,
+    &__container {
+      transition: none;
+    }
+  }
+}
diff --git a/m3-foundation/lib/toolbar.ts b/m3-foundation/lib/toolbar.ts
new file mode 100644
index 0000000..2daff7d
--- /dev/null
+++ b/m3-foundation/lib/toolbar.ts
@@ -0,0 +1,26 @@
+import type { ToolbarScroll } from '../types/components/toolbar'
+
+/** Number of 48px actions that fit while reserving a 48px overflow trigger. */
+export const getToolbarVisibleCount = (
+  available: number,
+  count: number,
+  occupied = 0,
+  gap = 4
+): number => {
+  const item = 48
+  const room = Math.max(0, available - occupied)
+  if (count * item + Math.max(0, count - 1) * gap <= room) return count
+  return Math.min(count - 1, Math.max(0, Math.floor((room - item) / (item + gap))))
+}
+
+export const getToolbarScrollState = (
+  previous: number,
+  current: number,
+  active: boolean,
+  scroll: ToolbarScroll
+): boolean => {
+  if (scroll === 'pinned' || current <= 0) return false
+  if (current > previous + 1) return true
+  if (current < previous - 1) return false
+  return active
+}
diff --git a/m3-foundation/tests/toolbar.test.ts b/m3-foundation/tests/toolbar.test.ts
new file mode 100644
index 0000000..36c1283
--- /dev/null
+++ b/m3-foundation/tests/toolbar.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, test } from 'vitest'
+
+import { getToolbarScrollState, getToolbarVisibleCount } from '../lib/toolbar'
+
+describe('toolbar layout', () => {
+  test('reserves overflow space only when all actions cannot fit', () => {
+    expect(getToolbarVisibleCount(256, 5)).toBe(5)
+    expect(getToolbarVisibleCount(200, 5)).toBe(2)
+    expect(getToolbarVisibleCount(48, 5)).toBe(0)
+    expect(getToolbarVisibleCount(260, 5, 100)).toBe(2)
+  })
+
+  test('retains scroll state until direction changes and resets at the top', () => {
+    expect(getToolbarScrollState(0, 20, false, 'hide')).toBe(true)
+    expect(getToolbarScrollState(20, 20, true, 'hide')).toBe(true)
+    expect(getToolbarScrollState(20, 10, true, 'hide')).toBe(false)
+    expect(getToolbarScrollState(20, 0, true, 'collapse')).toBe(false)
+    expect(getToolbarScrollState(0, 20, false, 'pinned')).toBe(false)
+  })
+})
diff --git a/m3-foundation/types/components/toolbar.d.ts b/m3-foundation/types/components/toolbar.d.ts
new file mode 100644
index 0000000..08199ee
--- /dev/null
+++ b/m3-foundation/types/components/toolbar.d.ts
@@ -0,0 +1,14 @@
+export type ToolbarVariant = 'docked' | 'floating'
+export type ToolbarOrientation = 'horizontal' | 'vertical'
+export type ToolbarColor = 'standard' | 'vibrant'
+export type ToolbarScroll = 'pinned' | 'hide' | 'collapse'
+export type ToolbarSide = 'start' | 'end'
+
+export interface ToolbarAction {
+  id: string;
+  label: string;
+  icon: string;
+  disabled?: boolean;
+  selected?: boolean;
+  onClick: () => void;
+}
diff --git a/m3-foundation/vite.config.ts b/m3-foundation/vite.config.ts
index db65dd5..fe288c4 100644
--- a/m3-foundation/vite.config.ts
+++ b/m3-foundation/vite.config.ts
@@ -27,6 +27,7 @@ const entries = {
   'lib/surface/descriptor': resolve(__dirname, 'lib/surface/descriptor.ts'),
   'lib/surface/orchestration': resolve(__dirname, 'lib/surface/orchestration.ts'),
   'lib/surface/style': resolve(__dirname, 'lib/surface/style.ts'),
+  'lib/toolbar': resolve(__dirname, 'lib/toolbar.ts'),
 }
 
 const externalPackages = Object.keys(dependencies)

From 85fad2b077aeb927abaa80de0f018d5f8fa398ca Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 9 Oct 2026 11:40:00 +0400
Subject: [PATCH 11/20] fix(m3-foundation): Search helper export was restored

---
 m3-foundation/vite.config.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/m3-foundation/vite.config.ts b/m3-foundation/vite.config.ts
index fe288c4..511c479 100644
--- a/m3-foundation/vite.config.ts
+++ b/m3-foundation/vite.config.ts
@@ -24,6 +24,7 @@ const entries = {
   'lib/popper/scheduling': resolve(__dirname, 'lib/popper/scheduling.ts'),
   'lib/predicates': resolve(__dirname, 'lib/predicates.ts'),
   'lib/scroll': resolve(__dirname, 'lib/scroll.ts'),
+  'lib/search': resolve(__dirname, 'lib/search.ts'),
   'lib/surface/descriptor': resolve(__dirname, 'lib/surface/descriptor.ts'),
   'lib/surface/orchestration': resolve(__dirname, 'lib/surface/orchestration.ts'),
   'lib/surface/style': resolve(__dirname, 'lib/surface/style.ts'),

From af5e2e4508494dd8730a696197d3790777442b4f Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 9 Oct 2026 11:40:36 +0400
Subject: [PATCH 12/20] feat(m3-react): Toolbar component and examples were
 added

---
 m3-react/src/components/index.ts              |   1 +
 m3-react/src/components/toolbar/M3Toolbar.tsx | 217 ++++++++++++++++++
 m3-react/src/components/toolbar/index.ts      |   2 +
 m3-react/storybook/components/M3Toolbar.mdx   | 157 +++++++++++++
 .../components/M3Toolbar.stories.tsx          |  54 +++++
 .../examples/toolbar/ToolbarExample.tsx       |  87 +++++++
 m3-react/tests/M3Toolbar.e2e.tsx              | 110 +++++++++
 m3-react/tests/M3Toolbar.test.tsx             |  87 +++++++
 8 files changed, 715 insertions(+)
 create mode 100644 m3-react/src/components/toolbar/M3Toolbar.tsx
 create mode 100644 m3-react/src/components/toolbar/index.ts
 create mode 100644 m3-react/storybook/components/M3Toolbar.mdx
 create mode 100644 m3-react/storybook/components/M3Toolbar.stories.tsx
 create mode 100644 m3-react/storybook/examples/toolbar/ToolbarExample.tsx
 create mode 100644 m3-react/tests/M3Toolbar.e2e.tsx
 create mode 100644 m3-react/tests/M3Toolbar.test.tsx

diff --git a/m3-react/src/components/index.ts b/m3-react/src/components/index.ts
index 05e3616..be2158e 100644
--- a/m3-react/src/components/index.ts
+++ b/m3-react/src/components/index.ts
@@ -27,3 +27,4 @@ export * from './slider'
 export * from './surface'
 export * from './switch'
 export * from './text-field'
+export * from './toolbar'
diff --git a/m3-react/src/components/toolbar/M3Toolbar.tsx b/m3-react/src/components/toolbar/M3Toolbar.tsx
new file mode 100644
index 0000000..ae6c146
--- /dev/null
+++ b/m3-react/src/components/toolbar/M3Toolbar.tsx
@@ -0,0 +1,217 @@
+import type { ComponentSetupContext } from '@/utils/component'
+import type { ElementReference } from '@modulify/m3-foundation/types/dom'
+import type { HTMLAttributes, Ref } from 'react'
+import type {
+  ToolbarAction,
+  ToolbarColor,
+  ToolbarOrientation,
+  ToolbarScroll,
+  ToolbarSide,
+  ToolbarVariant,
+} from '@modulify/m3-foundation/types/components/toolbar'
+
+import {
+  getToolbarScrollState,
+  getToolbarVisibleCount,
+} from '@modulify/m3-foundation/lib/toolbar'
+import {
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react'
+
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import { M3Menu, M3MenuItem } from '@/components/menu'
+
+import defineComponent from '@/utils/component'
+import { defineSlot, distinct } from '@/utils/content'
+import { toClassName } from '@/utils/styling'
+import { useElementReference, useResizeObserver } from '@/hooks'
+
+export interface M3ToolbarProps extends HTMLAttributes<HTMLDivElement> {
+  ref?: Ref<M3ToolbarExposed>;
+  label: string;
+  variant?: ToolbarVariant;
+  orientation?: ToolbarOrientation;
+  color?: ToolbarColor;
+  side?: ToolbarSide;
+  scroll?: ToolbarScroll;
+  scrollTarget?: HTMLElement | Window | null;
+  actions?: ToolbarAction[];
+  overflowLabel?: string;
+}
+
+export interface M3ToolbarExposed extends ElementReference<HTMLDivElement> {}
+
+const Fab = defineSlot('M3Toolbar.Fab')
+
+export default defineComponent(function M3Toolbar({
+  ref: _ref,
+  label,
+  variant = 'docked',
+  orientation = 'horizontal',
+  color = 'standard',
+  side = 'end',
+  scroll = 'pinned',
+  scrollTarget,
+  actions = [],
+  overflowLabel = 'More actions',
+  className = '',
+  children = [],
+  onKeyDown = () => {},
+  onFocusCapture = () => {},
+  ...attrs
+}: M3ToolbarProps, { expose }: ComponentSetupContext<M3ToolbarExposed>) {
+  const root = useRef<HTMLDivElement | null>(null)
+  const actionGroup = useRef<HTMLDivElement | null>(null)
+  const custom = useRef<HTMLDivElement | null>(null)
+  const overflow = useRef<HTMLButtonElement | null>(null)
+  const [overflowTarget, setOverflowTarget] = useState<HTMLButtonElement | null>(null)
+  const [visibleCount, setVisibleCount] = useState(actions.length)
+  const [scrollActive, setScrollActive] = useState(false)
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [slots, content] = useMemo(() => distinct(children, { fab: Fab }), [children])
+  const vertical = variant === 'floating' && orientation === 'vertical'
+  const hasFab = variant === 'floating' && !!slots.fab
+  const collapsed = scroll === 'collapse' && scrollActive && hasFab
+  const hidden = scroll === 'hide' && scrollActive
+  const shown = actions.slice(0, visibleCount)
+  const excess = actions.slice(visibleCount)
+
+  expose(useElementReference(root))
+
+  const updateMeasurements = () => {
+    const parent = root.current?.parentElement
+    if (!parent) return
+    const axis = vertical ? Math.min(parent.clientHeight || window.innerHeight, window.innerHeight) : parent.clientWidth || window.innerWidth
+    const outer = variant === 'docked' ? 0 : vertical ? 48 : 32
+    const padding = variant === 'docked' ? 32 : 16
+    const customSize = vertical
+      ? Math.max(custom.current?.scrollHeight ?? 0, custom.current?.offsetHeight ?? 0)
+      : Math.max(custom.current?.scrollWidth ?? 0, custom.current?.offsetWidth ?? 0)
+    const fabSize = hasFab ? 64 : 0
+    setVisibleCount(getToolbarVisibleCount(axis - outer - padding, actions.length, customSize + fabSize))
+    if (variant === 'floating' && actionGroup.current) {
+      const size = (vertical ? actionGroup.current.scrollHeight : actionGroup.current.scrollWidth) + padding
+      root.current?.style.setProperty('--m3-toolbar-expanded-size', `${size}px`)
+    }
+  }
+
+  useResizeObserver(() => [root.current?.parentElement ?? null, custom.current], updateMeasurements)
+  useLayoutEffect(updateMeasurements, [actions, variant, orientation, hasFab, visibleCount])
+
+  useEffect(() => {
+    const target = scrollTarget ?? window
+    const position = () => target === window ? window.scrollY : (target as HTMLElement).scrollTop
+    const controller = new AbortController()
+    let previous = position()
+
+    const update = () => {
+      const current = position()
+      setScrollActive(active => root.current?.contains(document.activeElement)
+        ? false
+        : getToolbarScrollState(previous, current, active, scroll))
+      previous = current
+    }
+
+    update()
+    target.addEventListener('scroll', update, { passive: true, signal: controller.signal })
+    return () => controller.abort('Toolbar scroll listener disposed')
+  }, [scroll, scrollTarget])
+
+  useEffect(() => {
+    if (excess.length === 0) setMenuOpen(false)
+  }, [excess.length])
+
+  return <div
+    ref={root}
+    role="toolbar"
+    aria-label={label}
+    aria-orientation={vertical ? 'vertical' : 'horizontal'}
+    className={toClassName([className, {
+      'm3-toolbar': true,
+      [`m3-toolbar_${variant}`]: true,
+      [`m3-toolbar_${color}`]: true,
+      'm3-toolbar_vertical': vertical,
+      'm3-toolbar_side-start': vertical && side === 'start',
+      'm3-toolbar_hidden': hidden,
+      'm3-toolbar_collapsed': collapsed,
+    }])}
+    {...attrs}
+    onFocusCapture={event => {
+      setScrollActive(false)
+      onFocusCapture(event)
+    }}
+    onKeyDown={event => {
+      const target = event.target as HTMLElement
+      if (target.matches('input, textarea, select, [contenteditable="true"]')) {
+        onKeyDown(event)
+        return
+      }
+
+      const first = vertical ? 'ArrowUp' : 'ArrowLeft'
+      const last = vertical ? 'ArrowDown' : 'ArrowRight'
+      if (event.key === first || event.key === last || event.key === 'Home' || event.key === 'End') {
+        const controls = [...(root.current?.querySelectorAll<HTMLElement>('button:not(:disabled), a[href], input:not(:disabled)') ?? [])]
+        const index = controls.indexOf(document.activeElement as HTMLElement)
+        if (index !== -1 && controls.length > 0) {
+          const rtl = !vertical && getComputedStyle(root.current!).direction === 'rtl'
+          const direction = event.key === first ? -1 : 1
+          const next = event.key === 'Home' ? 0 : event.key === 'End' ? controls.length - 1
+            : (index + direction * (rtl ? -1 : 1) + controls.length) % controls.length
+          controls[next]?.focus()
+          event.preventDefault()
+        }
+      }
+      onKeyDown(event)
+    }}
+  >
+    <div className="m3-toolbar__container" inert={collapsed}>
+      <div ref={actionGroup} className="m3-toolbar__actions">
+        {shown.map(action => <span key={action.id} className="m3-toolbar__action">
+          <M3IconButton
+            aria-label={action.label}
+            aria-pressed={action.selected}
+            appearance={action.selected ? 'tonal' : 'standard'}
+            disabled={action.disabled}
+            onClick={action.onClick}
+          >
+            <M3Icon name={action.icon} />
+          </M3IconButton>
+        </span>)}
+        {content && <div ref={custom} className="m3-toolbar__custom">{content}</div>}
+        {excess.length > 0 && <span className="m3-toolbar__action">
+          <M3IconButton
+            ref={instance => {
+              overflow.current = instance?.el ?? null
+              setOverflowTarget(current => current === overflow.current ? current : overflow.current)
+            }}
+            aria-label={overflowLabel}
+            aria-expanded={menuOpen}
+            aria-haspopup="menu"
+          >
+            <M3Icon name="more_vert" />
+          </M3IconButton>
+        </span>}
+      </div>
+    </div>
+    {hasFab && <div className="m3-toolbar__fab">{slots.fab}</div>}
+    {excess.length > 0 && <M3Menu className="m3-toolbar__menu" target={overflowTarget} shown={menuOpen} onToggle={setMenuOpen}>
+      {excess.map(action => <M3MenuItem
+        key={action.id}
+        selected={action.selected}
+        disabled={action.disabled}
+        onClick={() => {
+          if (!action.disabled) action.onClick()
+          setMenuOpen(false)
+        }}
+      >
+        <M3MenuItem.Leading><M3Icon name={action.icon} /></M3MenuItem.Leading>
+        {action.label}
+      </M3MenuItem>)}
+    </M3Menu>}
+  </div>
+}, { slots: { Fab } })
diff --git a/m3-react/src/components/toolbar/index.ts b/m3-react/src/components/toolbar/index.ts
new file mode 100644
index 0000000..78b347f
--- /dev/null
+++ b/m3-react/src/components/toolbar/index.ts
@@ -0,0 +1,2 @@
+export { default as M3Toolbar } from './M3Toolbar'
+export type { M3ToolbarExposed, M3ToolbarProps } from './M3Toolbar'
diff --git a/m3-react/storybook/components/M3Toolbar.mdx b/m3-react/storybook/components/M3Toolbar.mdx
new file mode 100644
index 0000000..3a5776d
--- /dev/null
+++ b/m3-react/storybook/components/M3Toolbar.mdx
@@ -0,0 +1,157 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import { Localized } from '../i18n'
+import * as M3ToolbarStories from './M3Toolbar.stories'
+
+<Meta of={M3ToolbarStories} />
+
+<Localized locale="en-US">
+
+# Toolbar
+
+Toolbars group actions related to the current page or content. `M3Toolbar` implements the two [Material 3 Expressive variants](https://m3.material.io/components/toolbars/overview): **docked** and **floating**. The former bottom app bar is a baseline variant that Material still lists but no longer recommends; use a docked toolbar for a new Expressive design.
+
+## Guide
+
+| Variant | Use | Placement |
+| --- | --- | --- |
+| `docked` | Actions shared across several pages | Full width at the bottom; do not show beside a bottom navigation bar. |
+| `floating`, horizontal | Actions for the current page or selection | Above content, at least 16 px from the window edge. A FAB may sit beside it. |
+| `floating`, vertical | Compact action group on a larger window | Along a side, at least 24 px from the edge; place it opposite a navigation rail. |
+
+Use `color="standard"` to keep attention on content and `vibrant` to emphasize controls or a temporary mode. Keep one prominent action. Put an emphasized action inside a docked toolbar; a FAB beside a floating toolbar is a separate slot. The toolbar does not create or manage that FAB. Both orientations support an accessible toolbar label. [Material guidelines](https://m3.material.io/components/toolbars/guidelines).
+
+### Actions and overflow
+
+Pass icon actions through `actions` for automatic overflow. Each action needs a stable `id`, a localized `label`, an icon name, and `onClick`; optional `disabled` and `selected` states follow it into the menu. The toolbar measures its containing element and keeps the last actions in the overflow menu when space runs out. Translate `overflowLabel` as well. Actions must remain understandable when shown as text in the menu.
+
+Use ordinary children for buttons, text fields, images, or other custom content. The toolbar lays them out, but only entries in `actions` participate in automatic overflow. Keep custom content small enough for the available space; manage its responsive presentation yourself. Avoid a vertical toolbar with wide controls and avoid too many unrelated control types. [Material flexibility and resizing](https://m3.material.io/components/toolbars/guidelines).
+
+### Scrolling and accessibility
+
+`scroll="pinned"` leaves the toolbar on screen. `hide` moves it offscreen while scrolling forward and restores it while scrolling back. On a floating toolbar with a `M3Toolbar.Fab` child, `collapse` keeps only that primary action visible while scrolling forward. It does not combine collapse with hide. Pass `scrollTarget` for a nested scroll area. Focusing the toolbar restores its controls. When reduced motion is requested, transitions stop.
+
+The root has `role="toolbar"`, an accessible label and orientation. Tab reaches native controls; the direction's arrow keys move among them, Home/End move to the ends, and arrow keys inside text fields keep their native behavior. Name every icon control. The toolbar has no click behavior of its own. [Material accessibility](https://m3.material.io/components/toolbars/accessibility).
+
+```tsx
+<M3Toolbar
+  label="Editing tools"
+  overflowLabel="More editing tools"
+  variant="floating"
+  color="vibrant"
+  scroll="collapse"
+  scrollTarget={editorScroller}
+  actions={[{ id: 'bold', label: 'Bold', icon: 'format_bold', selected: bold, onClick: toggleBold }]}
+>
+  <M3Toolbar.Fab>
+    <M3FabButton aria-label="Add section" onClick={addSection}><M3Icon name="add" /></M3FabButton>
+  </M3Toolbar.Fab>
+</M3Toolbar>
+```
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `M3Toolbar` | Container, layout, scroll response, and icon-action overflow. |
+| `M3ToolbarProps`, `M3ToolbarExposed` | Public React props and element reference. |
+| `ToolbarAction`, `ToolbarVariant`, `ToolbarOrientation`, `ToolbarColor`, `ToolbarScroll`, `ToolbarSide` | Shared foundation types. |
+
+| Prop | Default | Effect |
+| --- | --- | --- |
+| `label` | Required | Accessible name of this toolbar. |
+| `variant` | `docked` | `docked` or `floating`. |
+| `orientation` | `horizontal` | `vertical` applies to floating. |
+| `color` | `standard` | `standard` or `vibrant` container/action colors. |
+| `side` | `end` | `start` or `end` for vertical floating. |
+| `scroll` | `pinned` | `pinned`, `hide`, or `collapse` (floating with FAB). |
+| `scrollTarget` | `window` | Scrollable element or window to observe. |
+| `actions` | `[]` | Icon actions eligible for automatic overflow. |
+| `overflowLabel` | `More actions` | Accessible overflow trigger name; translate for the app locale. |
+| HTML attributes | — | Passed to the toolbar root. |
+
+`M3Toolbar.Fab` places a FAB beside the floating container. Unslotted children fill the custom-content area. The ref exposes `el`.
+
+## Sources
+
+- [Material overview](https://m3.material.io/components/toolbars/overview)
+- [Specs](https://m3.material.io/components/toolbars/specs)
+- [Guidelines](https://m3.material.io/components/toolbars/guidelines)
+- [Accessibility](https://m3.material.io/components/toolbars/accessibility)
+
+</Localized>
+
+<Localized locale="ru-RU">
+
+# Панель инструментов
+
+Toolbar объединяет действия текущей страницы или её содержимого. `M3Toolbar` реализует два варианта [Material 3 Expressive](https://m3.material.io/components/toolbars/overview): **docked** и **floating**. Прежний bottom app bar остался в baseline, но Material больше не рекомендует его; для нового Expressive-интерфейса используйте docked toolbar.
+
+## Руководство
+
+| Вариант | Когда использовать | Положение |
+| --- | --- | --- |
+| `docked` | Действия, общие для нескольких страниц | На всю ширину снизу; не показывать одновременно с нижним navigation bar. |
+| `floating`, горизонтальный | Действия текущей страницы или выделения | Поверх содержимого, не ближе 16 px к краю. Рядом возможен FAB. |
+| `floating`, вертикальный | Компактная группа действий на широком экране | У бокового края с отступом от 24 px; напротив navigation rail. |
+
+`color="standard"` сохраняет внимание на содержимом; `vibrant` выделяет контролы или временный режим. Делайте акцент на одном действии. В docked добавьте его внутрь панели; FAB рядом с floating передаётся отдельным слотом. Toolbar не управляет действием FAB. Каждому toolbar требуется доступное имя. [Рекомендации Material](https://m3.material.io/components/toolbars/guidelines).
+
+### Действия и overflow
+
+Передайте иконочные действия в `actions` для автоматического переноса в overflow. Каждому нужен стабильный `id`, локализованное `label`, имя иконки и `onClick`; `disabled` и `selected` сохраняются в меню. Toolbar измеряет родительский контейнер и переносит последние действия, когда места не хватает. Переведите и `overflowLabel`. Название действия должно быть понятным без иконки.
+
+Обычные children подходят для кнопок, текстовых полей, изображений и другого произвольного содержимого. Toolbar располагает их, но автоматически переносит в меню **только** элементы `actions`. Для пользовательского содержимого подберите собственную адаптивную компоновку. Избегайте широких элементов в вертикальной панели и множества несвязанных видов контролов. [Гибкость и адаптивность в спеке](https://m3.material.io/components/toolbars/guidelines).
+
+### Прокрутка и доступность
+
+`scroll="pinned"` оставляет toolbar на экране. `hide` уводит его при прокрутке вперёд и возвращает при обратной. Для floating с `M3Toolbar.Fab` режим `collapse` оставляет только главное действие. Скрытие и сворачивание не совмещаются. Для вложенной прокрутки укажите `scrollTarget`. При получении фокуса контролы возвращаются. При reduced motion переходы отключены.
+
+Корень имеет `role="toolbar"`, доступное имя и ориентацию. Tab проходит по обычным контролам, стрелки вдоль оси перемещают фокус, Home/End переводят его к краям. Стрелки внутри текстового поля сохраняют обычное поведение. Давайте названия иконочным кнопкам. Сам контейнер не обрабатывает нажатие. [Доступность Material](https://m3.material.io/components/toolbars/accessibility).
+
+```tsx
+<M3Toolbar
+  label="Инструменты редактирования"
+  overflowLabel="Другие инструменты"
+  variant="floating"
+  color="vibrant"
+  scroll="collapse"
+  scrollTarget={editorScroller}
+  actions={[{ id: 'bold', label: 'Полужирный', icon: 'format_bold', selected: bold, onClick: toggleBold }]}
+>
+  <M3Toolbar.Fab>
+    <M3FabButton aria-label="Добавить раздел" onClick={addSection}><M3Icon name="add" /></M3FabButton>
+  </M3Toolbar.Fab>
+</M3Toolbar>
+```
+
+## API
+
+| Экспорт | Назначение |
+| --- | --- |
+| `M3Toolbar` | Контейнер, компоновка, реакция на прокрутку и overflow иконочных действий. |
+| `M3ToolbarProps`, `M3ToolbarExposed` | Публичные React props и ссылка на элемент. |
+| `ToolbarAction`, `ToolbarVariant`, `ToolbarOrientation`, `ToolbarColor`, `ToolbarScroll`, `ToolbarSide` | Общие типы foundation. |
+
+| Prop | По умолчанию | Назначение |
+| --- | --- | --- |
+| `label` | Обязателен | Доступное имя toolbar. |
+| `variant` | `docked` | `docked` или `floating`. |
+| `orientation` | `horizontal` | `vertical` действует для floating. |
+| `color` | `standard` | Цветовая схема `standard` или `vibrant`. |
+| `side` | `end` | `start` или `end` для вертикального floating. |
+| `scroll` | `pinned` | `pinned`, `hide`, `collapse` (floating с FAB). |
+| `scrollTarget` | `window` | Наблюдаемое окно или прокручиваемый элемент. |
+| `actions` | `[]` | Иконочные действия с автоматическим overflow. |
+| `overflowLabel` | `More actions` | Имя кнопки меню; переведите его под язык приложения. |
+| HTML-атрибуты | — | Передаются корневому элементу. |
+
+`M3Toolbar.Fab` располагает FAB рядом с floating-контейнером. Обычные children попадают в область пользовательского содержимого. Ref предоставляет `el`.
+
+## Источники
+
+- [Обзор](https://m3.material.io/components/toolbars/overview)
+- [Спецификация](https://m3.material.io/components/toolbars/specs)
+- [Рекомендации](https://m3.material.io/components/toolbars/guidelines)
+- [Доступность](https://m3.material.io/components/toolbars/accessibility)
+
+</Localized>
diff --git a/m3-react/storybook/components/M3Toolbar.stories.tsx b/m3-react/storybook/components/M3Toolbar.stories.tsx
new file mode 100644
index 0000000..3239d31
--- /dev/null
+++ b/m3-react/storybook/components/M3Toolbar.stories.tsx
@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from '@storybook/react'
+
+import { M3Toolbar } from '@/components/toolbar'
+
+import ToolbarExample from '../examples/toolbar/ToolbarExample'
+
+const meta = {
+  title: 'Components/M3Toolbar',
+  component: M3Toolbar,
+  args: { label: 'Editing tools', variant: 'docked', orientation: 'horizontal', color: 'standard', side: 'end', scroll: 'pinned' },
+  argTypes: {
+    variant: { control: 'select', options: ['docked', 'floating'] },
+    orientation: { control: 'select', options: ['horizontal', 'vertical'] },
+    color: { control: 'select', options: ['standard', 'vibrant'] },
+    side: { control: 'select', options: ['start', 'end'] },
+    scroll: { control: 'select', options: ['pinned', 'hide', 'collapse'] },
+    actions: { control: false },
+    scrollTarget: { control: false },
+    overflowLabel: { control: false },
+  },
+  render: (args, { globals }) => <ToolbarExample
+    variant={args.variant ?? 'docked'}
+    orientation={args.orientation ?? 'horizontal'}
+    color={args.color ?? 'standard'}
+    side={args.side ?? 'end'}
+    scroll={args.scroll ?? 'pinned'}
+    locale={globals.locale}
+  />,
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof M3Toolbar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Docked: Story = {}
+export const DockedVibrant: Story = { args: { color: 'vibrant' } }
+export const Floating: Story = { args: { variant: 'floating' } }
+export const FloatingVibrant: Story = { args: { variant: 'floating', color: 'vibrant' } }
+export const VerticalFloating: Story = { args: { variant: 'floating', orientation: 'vertical' } }
+export const HideOnScroll: Story = { args: { variant: 'floating', scroll: 'hide' } }
+export const CollapseOnScroll: Story = { args: { variant: 'floating', scroll: 'collapse' } }
+export const NarrowOverflow: Story = {
+  args: { variant: 'floating' },
+  render: (args, { globals }) => <ToolbarExample
+    variant={args.variant ?? 'floating'}
+    orientation={args.orientation ?? 'horizontal'}
+    color={args.color ?? 'standard'}
+    side={args.side ?? 'end'}
+    scroll={args.scroll ?? 'pinned'}
+    locale={globals.locale}
+    narrow
+  />,
+}
diff --git a/m3-react/storybook/examples/toolbar/ToolbarExample.tsx b/m3-react/storybook/examples/toolbar/ToolbarExample.tsx
new file mode 100644
index 0000000..a78303e
--- /dev/null
+++ b/m3-react/storybook/examples/toolbar/ToolbarExample.tsx
@@ -0,0 +1,87 @@
+import type {
+  ToolbarColor,
+  ToolbarOrientation,
+  ToolbarScroll,
+  ToolbarSide,
+  ToolbarVariant,
+} from '@modulify/m3-foundation/types/components/toolbar'
+
+import { useState } from 'react'
+
+import { M3FabButton } from '@/components/fab-button'
+import { M3Icon } from '@/components/icon'
+import { M3Toolbar } from '@/components/toolbar'
+
+import { localize } from '../../i18n'
+
+const messages = {
+  'en-US': {
+    title: 'Document editor', hint: 'Scroll to see how the toolbar responds.', label: 'Editing tools', more: 'More editing tools',
+    actions: ['Bold', 'Italic', 'Underline', 'Insert link', 'Insert image', 'Align', 'Comment'],
+    cards: ['Outline', 'Introduction', 'Research notes', 'References', 'Draft', 'Review', 'Changes', 'Next steps'],
+    add: 'Add section', last: 'Last action',
+  },
+  'ru-RU': {
+    title: 'Редактор документа', hint: 'Прокрутите страницу, чтобы увидеть поведение панели.', label: 'Инструменты редактирования', more: 'Другие инструменты',
+    actions: ['Полужирный', 'Курсив', 'Подчеркнуть', 'Вставить ссылку', 'Вставить изображение', 'Выровнять', 'Комментировать'],
+    cards: ['Структура', 'Введение', 'Исследование', 'Источники', 'Черновик', 'Рецензия', 'Изменения', 'Следующие шаги'],
+    add: 'Добавить раздел', last: 'Последнее действие',
+  },
+}
+
+const icons = ['format_bold', 'format_italic', 'format_underlined', 'link', 'image', 'format_align_left', 'comment']
+
+interface Props {
+  variant: ToolbarVariant;
+  orientation: ToolbarOrientation;
+  color: ToolbarColor;
+  scroll: ToolbarScroll;
+  side: ToolbarSide;
+  locale: string;
+  narrow?: boolean;
+}
+
+export default function ToolbarExample({ variant, orientation, color, scroll, side, locale, narrow = false }: Props) {
+  const text = localize(locale, messages)
+  const [scroller, setScroller] = useState<HTMLElement | null>(null)
+  const [last, setLast] = useState('—')
+  const actions = text.actions.map((label, index) => ({
+    id: icons[index], label, icon: icons[index], selected: index === 0,
+    onClick: () => setLast(label),
+  }))
+
+  return <main
+    ref={setScroller}
+    lang={locale}
+    style={{ blockSize: '100vh', inlineSize: narrow ? 'min(320px, 100vw)' : '100%', marginInline: 'auto', overflowY: 'auto', background: 'var(--m3-sys-surface)', color: 'var(--m3-sys-on-surface)' }}
+  >
+    <div style={{ maxInlineSize: 1120, marginInline: 'auto', padding: 24, paddingBlockEnd: 160 }}>
+      <h1>{text.title}</h1>
+      <p>{text.hint} {text.last}: {last}</p>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 16 }}>
+        {[...text.cards, ...text.cards].map((card, index) => <article
+          key={`${card}-${index}`}
+          style={{ boxSizing: 'border-box', flex: '1 1 max-content', minInlineSize: 'min(180px, 100%)', maxInlineSize: 'min(360px, 100%)', minBlockSize: 150, padding: 24, borderRadius: 24, background: 'var(--m3-sys-surface-container)' }}
+        >
+          <h2 style={{ marginBlockStart: 0, fontSize: 22, lineHeight: '28px', overflowWrap: 'break-word' }}>{card}</h2>
+          <p>Material 3</p>
+        </article>)}
+      </div>
+    </div>
+    <M3Toolbar
+      label={text.label}
+      overflowLabel={text.more}
+      variant={variant}
+      orientation={orientation}
+      color={color}
+      side={side}
+      scroll={scroll}
+      scrollTarget={scroller}
+      actions={actions}
+    >
+      {variant === 'floating' && <M3Toolbar.Fab>
+        <M3FabButton aria-label={text.add} onClick={() => setLast(text.add)}><M3Icon name="add" /></M3FabButton>
+      </M3Toolbar.Fab>}
+    </M3Toolbar>
+  </main>
+}
diff --git a/m3-react/tests/M3Toolbar.e2e.tsx b/m3-react/tests/M3Toolbar.e2e.tsx
new file mode 100644
index 0000000..58604fa
--- /dev/null
+++ b/m3-react/tests/M3Toolbar.e2e.tsx
@@ -0,0 +1,110 @@
+import { act, fireEvent } from '@testing-library/react'
+import { page } from 'vitest/browser'
+import { render, screen, waitFor } from '@testing-library/react'
+
+import { M3FabButton } from '@/components/fab-button'
+import { M3Icon } from '@/components/icon'
+import { M3Toolbar } from '@/components/toolbar'
+
+const actions = ['Bold', 'Italic', 'Underline', 'Link', 'Image', 'Align'].map((label, index) => ({
+  id: String(index), label, icon: 'edit', onClick: vi.fn(),
+}))
+const overflowActions = actions.map((action, index) => index === 4 ? { ...action, label: 'Вставить изображение' } : action)
+
+test('keeps floating actions within the viewport and restores overflowed actions after resize', async () => {
+  await page.viewport(320, 700)
+  const view = render(<M3Toolbar label="Editing" variant="floating" actions={overflowActions} overflowLabel="More tools" />)
+
+  try {
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+    const container = toolbar.querySelector<HTMLElement>('.m3-toolbar__container')!
+    await waitFor(() => expect(screen.getByRole('button', { name: 'More tools' })).not.toBeNull())
+    const bounds = container.getBoundingClientRect()
+    expect(bounds.height).toBe(64)
+    expect(bounds.left).toBeGreaterThanOrEqual(16)
+    expect(bounds.right).toBeLessThanOrEqual(304)
+
+    fireEvent.click(screen.getByRole('button', { name: 'More tools' }))
+    const item = await screen.findByText('Вставить изображение')
+    const menu = item.closest<HTMLElement>('.m3-menu')!
+    await waitFor(() => {
+      const menuBounds = menu.getBoundingClientRect()
+      const toolbarBounds = toolbar.getBoundingClientRect()
+      expect(Math.min(menuBounds.bottom, toolbarBounds.bottom) - Math.max(menuBounds.top, toolbarBounds.top)).toBeGreaterThan(0)
+      const x = (Math.max(menuBounds.left, toolbarBounds.left) + Math.min(menuBounds.right, toolbarBounds.right)) / 2
+      const y = (Math.max(menuBounds.top, toolbarBounds.top) + Math.min(menuBounds.bottom, toolbarBounds.bottom)) / 2
+      expect(document.elementFromPoint(x, y)?.closest('.m3-menu')).toBe(menu)
+    })
+    const body = item.closest<HTMLElement>('.m3-menu-item__body')!
+    const textStarts = [...menu.querySelectorAll('.m3-menu-item__body')].map(element => {
+      const range = document.createRange()
+      range.selectNodeContents(element)
+      return range.getBoundingClientRect().left
+    })
+    expect(Math.max(...textStarts) - Math.min(...textStarts)).toBeLessThan(1)
+    expect(body.scrollWidth).toBeLessThanOrEqual(body.clientWidth)
+    expect(body.getBoundingClientRect().height).toBeLessThan(parseFloat(getComputedStyle(body).lineHeight) * 1.5)
+    fireEvent.click(item)
+    expect(actions[4].onClick).toHaveBeenCalledOnce()
+
+    await act(async () => { await page.viewport(900, 700) })
+    await waitFor(() => expect(screen.queryByRole('button', { name: 'More tools' })).toBeNull())
+    expect(screen.getByRole('button', { name: 'Вставить изображение' })).not.toBeNull()
+  } finally {
+    view.unmount()
+  }
+})
+
+test('restores the full floating width after collapsing to the FAB', async () => {
+  await page.viewport(900, 700)
+  const scroller = document.createElement('main')
+  Object.assign(scroller.style, { height: '300px', overflowY: 'auto' })
+  document.body.append(scroller)
+  const view = render(<>
+    <M3Toolbar label="Editing" variant="floating" scroll="collapse" scrollTarget={scroller} actions={actions}>
+      <button type="button">Custom action</button>
+      <M3Toolbar.Fab><M3FabButton aria-label="Add"><M3Icon name="add" /></M3FabButton></M3Toolbar.Fab>
+    </M3Toolbar>
+    <div style={{ height: 1000 }} />
+  </>, { container: scroller })
+
+  try {
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+    const container = toolbar.querySelector<HTMLElement>('.m3-toolbar__container')!
+    const expandedWidth = container.getBoundingClientRect().width
+    scroller.scrollTop = 100
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
+    scroller.scrollTop = 0
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(false))
+    await waitFor(() => expect(container.getBoundingClientRect().width).toBeCloseTo(expandedWidth, 0))
+  } finally {
+    view.unmount()
+    scroller.remove()
+  }
+})
+
+test('positions vertical floating toolbar at the logical end and collapses to FAB on scroll', async () => {
+  await page.viewport(900, 700)
+  const scroller = document.createElement('main')
+  Object.assign(scroller.style, { height: '300px', overflowY: 'auto' })
+  document.body.append(scroller)
+  const view = render(<>
+    <M3Toolbar label="Editing" variant="floating" orientation="vertical" scroll="collapse" scrollTarget={scroller} actions={actions.slice(0, 3)}>
+      <M3Toolbar.Fab><M3FabButton aria-label="Add"><M3Icon name="add" /></M3FabButton></M3Toolbar.Fab>
+    </M3Toolbar>
+    <div style={{ height: 1000 }} />
+  </>, { container: scroller })
+
+  try {
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+    expect(Math.round(900 - toolbar.getBoundingClientRect().right)).toBe(24)
+    scroller.scrollTop = 100
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
+    expect(screen.getByRole('button', { name: 'Add' })).not.toBeNull()
+    scroller.scrollTop = 0
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(false))
+  } finally {
+    view.unmount()
+    scroller.remove()
+  }
+})
diff --git a/m3-react/tests/M3Toolbar.test.tsx b/m3-react/tests/M3Toolbar.test.tsx
new file mode 100644
index 0000000..9b66eae
--- /dev/null
+++ b/m3-react/tests/M3Toolbar.test.tsx
@@ -0,0 +1,87 @@
+import {
+  fireEvent,
+  render,
+  screen,
+  waitFor,
+} from '@testing-library/react'
+
+import { M3Toolbar } from '@/components/toolbar'
+
+const actions = [
+  { id: 'bold', label: 'Bold', icon: 'format_bold', onClick: vi.fn() },
+  { id: 'italic', label: 'Italic', icon: 'format_italic', onClick: vi.fn() },
+  { id: 'underline', label: 'Underline', icon: 'format_underlined', onClick: vi.fn() },
+  { id: 'link', label: 'Link', icon: 'link', onClick: vi.fn() },
+  { id: 'image', label: 'Image', icon: 'image', onClick: vi.fn() },
+]
+
+describe('m3-react/toolbar', () => {
+  test('renders docked and vertical floating variants with accessible actions', () => {
+    const { rerender, container } = render(<M3Toolbar label="Editing" actions={actions}>
+      <M3Toolbar.Fab><button type="button">Add</button></M3Toolbar.Fab>
+    </M3Toolbar>)
+    expect(screen.getByRole('toolbar', { name: 'Editing' }).getAttribute('aria-orientation')).toBe('horizontal')
+    expect(screen.getByRole('button', { name: 'Bold' })).not.toBeNull()
+    expect(container.querySelector('.m3-toolbar_docked')).not.toBeNull()
+    expect(container.querySelector('.m3-toolbar__fab')).toBeNull()
+
+    rerender(<M3Toolbar label="Editing" variant="floating" orientation="vertical" color="vibrant" side="start" actions={actions}>
+      <M3Toolbar.Fab><button type="button">Add</button></M3Toolbar.Fab>
+    </M3Toolbar>)
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+    expect(toolbar.getAttribute('aria-orientation')).toBe('vertical')
+    expect(toolbar.classList.contains('m3-toolbar_side-start')).toBe(true)
+    expect(toolbar.classList.contains('m3-toolbar_vibrant')).toBe(true)
+    expect(container.querySelector('.m3-toolbar__fab')).not.toBeNull()
+  })
+
+  test('moves focus along the toolbar without stealing input arrows', () => {
+    render(<M3Toolbar label="Editing" actions={actions.slice(0, 2)}><input aria-label="Find" /></M3Toolbar>)
+    const bold = screen.getByRole('button', { name: 'Bold' })
+    bold.focus()
+    fireEvent.keyDown(bold, { key: 'ArrowRight' })
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Italic' }))
+
+    const input = screen.getByRole('textbox', { name: 'Find' })
+    input.focus()
+    fireEvent.keyDown(input, { key: 'ArrowRight' })
+    expect(document.activeElement).toBe(input)
+  })
+
+  test('moves excess actions into an accessible menu at a narrow width', async () => {
+    const width = window.innerWidth
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 200 })
+    try {
+      render(<M3Toolbar label="Editing" actions={actions} overflowLabel="More editing actions" />)
+      expect(screen.getByRole('button', { name: 'Bold' })).not.toBeNull()
+      expect(screen.queryByRole('button', { name: 'Underline' })).toBeNull()
+      fireEvent.click(screen.getByRole('button', { name: 'More editing actions' }))
+      const item = await screen.findByText('Underline')
+      fireEvent.click(item)
+      expect(actions[2].onClick).toHaveBeenCalledOnce()
+    } finally {
+      Object.defineProperty(window, 'innerWidth', { configurable: true, value: width })
+    }
+  })
+
+  test('hides or collapses on forward scroll and restores on reverse scroll', async () => {
+    const scroller = document.createElement('div')
+    const view = render(<M3Toolbar label="Editing" variant="floating" scroll="collapse" scrollTarget={scroller} actions={actions}>
+      <M3Toolbar.Fab><button type="button">Add</button></M3Toolbar.Fab>
+    </M3Toolbar>)
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+
+    scroller.scrollTop = 40
+    fireEvent.scroll(scroller)
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
+    expect(screen.getByRole('button', { name: 'Add' })).not.toBeNull()
+
+    scroller.scrollTop = 20
+    fireEvent.scroll(scroller)
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(false))
+    view.rerender(<M3Toolbar label="Editing" scroll="hide" scrollTarget={scroller} />)
+    scroller.scrollTop = 60
+    fireEvent.scroll(scroller)
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_hidden')).toBe(true))
+  })
+})

From 35c17104cde36e791817817de9f61a2b50f88811 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 9 Oct 2026 11:41:12 +0400
Subject: [PATCH 13/20] feat(m3-vue): Toolbar component and examples were added

---
 m3-vue/src/components/index.ts                |   1 +
 m3-vue/src/components/toolbar/M3Toolbar.vue   | 218 ++++++++++++++++++
 m3-vue/src/components/toolbar/index.ts        |   3 +
 m3-vue/storybook/components/M3Toolbar.mdx     | 157 +++++++++++++
 .../storybook/components/M3Toolbar.stories.ts |  47 ++++
 .../examples/toolbar/ToolbarExample.vue       | 104 +++++++++
 m3-vue/tests/M3Toolbar.e2e.ts                 | 133 +++++++++++
 m3-vue/tests/M3Toolbar.test.ts                |  82 +++++++
 8 files changed, 745 insertions(+)
 create mode 100644 m3-vue/src/components/toolbar/M3Toolbar.vue
 create mode 100644 m3-vue/src/components/toolbar/index.ts
 create mode 100644 m3-vue/storybook/components/M3Toolbar.mdx
 create mode 100644 m3-vue/storybook/components/M3Toolbar.stories.ts
 create mode 100644 m3-vue/storybook/examples/toolbar/ToolbarExample.vue
 create mode 100644 m3-vue/tests/M3Toolbar.e2e.ts
 create mode 100644 m3-vue/tests/M3Toolbar.test.ts

diff --git a/m3-vue/src/components/index.ts b/m3-vue/src/components/index.ts
index 6bf8f3e..795748b 100644
--- a/m3-vue/src/components/index.ts
+++ b/m3-vue/src/components/index.ts
@@ -28,3 +28,4 @@ export * from './slider'
 export * from './surface'
 export * from './switch'
 export * from './text-field'
+export * from './toolbar'
diff --git a/m3-vue/src/components/toolbar/M3Toolbar.vue b/m3-vue/src/components/toolbar/M3Toolbar.vue
new file mode 100644
index 0000000..ae2f1ed
--- /dev/null
+++ b/m3-vue/src/components/toolbar/M3Toolbar.vue
@@ -0,0 +1,218 @@
+<template>
+    <div
+        ref="root"
+        :aria-label="label"
+        :aria-orientation="vertical ? 'vertical' : 'horizontal'"
+        :class="{
+            'm3-toolbar': true,
+            ['m3-toolbar_' + variant]: true,
+            ['m3-toolbar_' + color]: true,
+            'm3-toolbar_vertical': vertical,
+            'm3-toolbar_side-start': vertical && side === 'start',
+            'm3-toolbar_hidden': hidden,
+            'm3-toolbar_collapsed': collapsed,
+        }"
+        role="toolbar"
+        v-bind="$attrs"
+        @focusin="scrollActive = false"
+        @keydown="onKeyDown"
+    >
+        <div :inert="collapsed" class="m3-toolbar__container">
+            <div ref="actionGroup" class="m3-toolbar__actions">
+                <span
+                    v-for="action in shown"
+                    :key="action.id"
+                    class="m3-toolbar__action"
+                >
+                    <M3IconButton
+                        :aria-label="action.label"
+                        :aria-pressed="action.selected"
+                        :appearance="action.selected ? 'tonal' : 'standard'"
+                        :disabled="action.disabled"
+                        @click="action.onClick"
+                    >
+                        <M3Icon :name="action.icon" />
+                    </M3IconButton>
+                </span>
+
+                <div ref="custom" class="m3-toolbar__custom">
+                    <slot />
+                </div>
+
+                <span v-if="excess.length" class="m3-toolbar__action">
+                    <M3IconButton
+                        ref="overflowButton"
+                        :aria-label="overflowLabel"
+                        :aria-expanded="menuOpen"
+                        aria-haspopup="menu"
+                    >
+                        <M3Icon name="more_vert" />
+                    </M3IconButton>
+                </span>
+            </div>
+        </div>
+
+        <div v-if="hasFab" class="m3-toolbar__fab">
+            <slot name="fab" />
+        </div>
+
+        <M3Menu
+            v-if="excess.length"
+            :target="() => overflowButton?.el ?? null"
+            :shown="menuOpen"
+            class="m3-toolbar__menu"
+            @update:shown="menuOpen = $event"
+        >
+            <M3MenuItem
+                v-for="action in excess"
+                :key="action.id"
+                :selected="action.selected"
+                :disabled="action.disabled"
+                @click="activateOverflow(action)"
+            >
+                <template #leading>
+                    <M3Icon :name="action.icon" />
+                </template>
+                {{ action.label }}
+            </M3MenuItem>
+        </M3Menu>
+    </div>
+</template>
+
+<script lang="ts" setup>
+import type { ElementReference } from '@modulify/m3-foundation/types/dom'
+import type { PropType } from 'vue'
+import type {
+  ToolbarAction,
+  ToolbarColor,
+  ToolbarOrientation,
+  ToolbarScroll,
+  ToolbarSide,
+  ToolbarVariant,
+} from '@modulify/m3-foundation/types/components/toolbar'
+
+import { computed } from 'vue'
+import {
+  getToolbarScrollState,
+  getToolbarVisibleCount,
+} from '@modulify/m3-foundation/lib/toolbar'
+import {
+  onMounted,
+  ref,
+  useSlots,
+  watch,
+} from 'vue'
+
+import { M3Icon } from '@/components/icon'
+import { M3IconButton } from '@/components/icon-button'
+import { M3Menu, M3MenuItem } from '@/components/menu'
+
+import { useResizeObserver } from '@/composables/observer'
+
+defineOptions({ inheritAttrs: false })
+
+const props = defineProps({
+  label: { type: String, required: true },
+  variant: { type: String as PropType<ToolbarVariant>, default: 'docked' },
+  orientation: { type: String as PropType<ToolbarOrientation>, default: 'horizontal' },
+  color: { type: String as PropType<ToolbarColor>, default: 'standard' },
+  side: { type: String as PropType<ToolbarSide>, default: 'end' },
+  scroll: { type: String as PropType<ToolbarScroll>, default: 'pinned' },
+  scrollTarget: { type: Object as PropType<HTMLElement | Window | null>, default: null },
+  actions: { type: Array as PropType<ToolbarAction[]>, default: (): ToolbarAction[] => [] },
+  overflowLabel: { type: String, default: 'More actions' },
+})
+
+const slots = useSlots()
+const root = ref<HTMLDivElement | null>(null)
+const actionGroup = ref<HTMLDivElement | null>(null)
+const custom = ref<HTMLDivElement | null>(null)
+const overflowButton = ref<InstanceType<typeof M3IconButton> | null>(null)
+const visibleCount = ref(props.actions.length)
+const scrollActive = ref(false)
+const menuOpen = ref(false)
+
+const vertical = computed(() => props.variant === 'floating' && props.orientation === 'vertical')
+const hasFab = computed(() => props.variant === 'floating' && 'fab' in slots)
+const collapsed = computed(() => props.scroll === 'collapse' && scrollActive.value && hasFab.value)
+const hidden = computed(() => props.scroll === 'hide' && scrollActive.value)
+const shown = computed(() => props.actions.slice(0, visibleCount.value))
+const excess = computed(() => props.actions.slice(visibleCount.value))
+
+defineExpose({
+  get el () { return root.value },
+} satisfies ElementReference<HTMLDivElement>)
+
+const updateMeasurements = () => {
+  const parent = root.value?.parentElement
+  if (!parent) return
+  const axis = vertical.value ? Math.min(parent.clientHeight || window.innerHeight, window.innerHeight) : parent.clientWidth || window.innerWidth
+  const outer = props.variant === 'docked' ? 0 : vertical.value ? 48 : 32
+  const padding = props.variant === 'docked' ? 32 : 16
+  const customSize = vertical.value
+    ? Math.max(custom.value?.scrollHeight ?? 0, custom.value?.offsetHeight ?? 0)
+    : Math.max(custom.value?.scrollWidth ?? 0, custom.value?.offsetWidth ?? 0)
+  const fabSize = hasFab.value ? 64 : 0
+  visibleCount.value = getToolbarVisibleCount(axis - outer - padding, props.actions.length, customSize + fabSize)
+  if (props.variant === 'floating' && actionGroup.value) {
+    const size = (vertical.value ? actionGroup.value.scrollHeight : actionGroup.value.scrollWidth) + padding
+    root.value?.style.setProperty('--m3-toolbar-expanded-size', `${size}px`)
+  }
+}
+
+const observer = useResizeObserver(() => [root.value?.parentElement ?? null, custom.value], updateMeasurements)
+
+onMounted(() => {
+  observer.observe()
+  updateMeasurements()
+})
+
+watch(() => [props.actions, props.variant, props.orientation], updateMeasurements, { deep: true, flush: 'post' })
+watch(visibleCount, updateMeasurements, { flush: 'post' })
+watch(excess, value => { if (!value.length) menuOpen.value = false })
+
+watch(() => [props.scroll, props.scrollTarget] as const, (_, __, onCleanup) => {
+  if (typeof window === 'undefined') return
+  const target = props.scrollTarget ?? window
+  const position = () => target === window ? window.scrollY : (target as HTMLElement).scrollTop
+  const controller = new AbortController()
+  let previous = position()
+
+  const update = () => {
+    const current = position()
+    scrollActive.value = root.value?.contains(document.activeElement)
+      ? false
+      : getToolbarScrollState(previous, current, scrollActive.value, props.scroll)
+    previous = current
+  }
+
+  update()
+  target.addEventListener('scroll', update, { passive: true, signal: controller.signal })
+  onCleanup(() => controller.abort('Toolbar scroll listener disposed'))
+}, { immediate: true })
+
+const activateOverflow = (action: ToolbarAction) => {
+  if (!action.disabled) action.onClick()
+  menuOpen.value = false
+}
+
+const onKeyDown = (event: KeyboardEvent) => {
+  const target = event.target as HTMLElement
+  if (target.matches('input, textarea, select, [contenteditable="true"]')) return
+
+  const first = vertical.value ? 'ArrowUp' : 'ArrowLeft'
+  const last = vertical.value ? 'ArrowDown' : 'ArrowRight'
+  if (![first, last, 'Home', 'End'].includes(event.key)) return
+
+  const controls = [...(root.value?.querySelectorAll<HTMLElement>('button:not(:disabled), a[href], input:not(:disabled)') ?? [])]
+  const index = controls.indexOf(document.activeElement as HTMLElement)
+  if (index === -1 || controls.length === 0) return
+
+  const rtl = !vertical.value && getComputedStyle(root.value!).direction === 'rtl'
+  const direction = event.key === first ? -1 : 1
+  const next = event.key === 'Home' ? 0 : event.key === 'End' ? controls.length - 1
+    : (index + direction * (rtl ? -1 : 1) + controls.length) % controls.length
+  controls[next]?.focus()
+  event.preventDefault()
+}
+</script>
diff --git a/m3-vue/src/components/toolbar/index.ts b/m3-vue/src/components/toolbar/index.ts
new file mode 100644
index 0000000..31ee413
--- /dev/null
+++ b/m3-vue/src/components/toolbar/index.ts
@@ -0,0 +1,3 @@
+import M3Toolbar from './M3Toolbar.vue'
+
+export { M3Toolbar }
diff --git a/m3-vue/storybook/components/M3Toolbar.mdx b/m3-vue/storybook/components/M3Toolbar.mdx
new file mode 100644
index 0000000..e54f004
--- /dev/null
+++ b/m3-vue/storybook/components/M3Toolbar.mdx
@@ -0,0 +1,157 @@
+import { Meta } from '@storybook/addon-docs/blocks'
+import { Localized } from '../i18n'
+import * as M3ToolbarStories from './M3Toolbar.stories'
+
+<Meta of={M3ToolbarStories} />
+
+<Localized locale="en-US">
+
+# Toolbar
+
+Toolbars group actions related to the current page or content. `M3Toolbar` implements the two [Material 3 Expressive variants](https://m3.material.io/components/toolbars/overview): **docked** and **floating**. The former bottom app bar is a baseline variant that Material still lists but no longer recommends; use a docked toolbar for a new Expressive design.
+
+## Guide
+
+| Variant | Use | Placement |
+| --- | --- | --- |
+| `docked` | Actions shared across several pages | Full width at the bottom; do not show beside a bottom navigation bar. |
+| `floating`, horizontal | Actions for the current page or selection | Above content, at least 16 px from the window edge. A FAB may sit beside it. |
+| `floating`, vertical | Compact action group on a larger window | Along a side, at least 24 px from the edge; place it opposite a navigation rail. |
+
+Use `color="standard"` to keep attention on content and `vibrant` to emphasize controls or a temporary mode. Keep one prominent action. Put an emphasized action inside a docked toolbar; a FAB beside a floating toolbar is a separate slot. The toolbar does not create or manage that FAB. Both orientations support an accessible toolbar label. [Material guidelines](https://m3.material.io/components/toolbars/guidelines).
+
+### Actions and overflow
+
+Pass icon actions through `actions` for automatic overflow. Each action needs a stable `id`, a localized `label`, an icon name, and `onClick`; optional `disabled` and `selected` states follow it into the menu. The toolbar measures its containing element and keeps the last actions in the overflow menu when space runs out. Translate `overflowLabel` as well. Actions must remain understandable when shown as text in the menu.
+
+Use the default slot for buttons, text fields, images, or other custom content. The toolbar lays them out, but only entries in `actions` participate in automatic overflow. Keep custom content small enough for the available space; manage its responsive presentation yourself. Avoid a vertical toolbar with wide controls and avoid too many unrelated control types. [Material flexibility and resizing](https://m3.material.io/components/toolbars/guidelines).
+
+### Scrolling and accessibility
+
+`scroll="pinned"` leaves the toolbar on screen. `hide` moves it offscreen while scrolling forward and restores it while scrolling back. On a floating toolbar with a `#fab` slot, `collapse` keeps only that primary action visible while scrolling forward. It does not combine collapse with hide. Pass `scrollTarget` for a nested scroll area. Focusing the toolbar restores its controls. When reduced motion is requested, transitions stop.
+
+The root has `role="toolbar"`, an accessible label and orientation. Tab reaches native controls; the direction's arrow keys move among them, Home/End move to the ends, and arrow keys inside text fields keep their native behavior. Name every icon control. The toolbar has no click behavior of its own. [Material accessibility](https://m3.material.io/components/toolbars/accessibility).
+
+```vue
+<M3Toolbar
+  label="Editing tools"
+  overflow-label="More editing tools"
+  variant="floating"
+  color="vibrant"
+  scroll="collapse"
+  :scroll-target="editorScroller"
+  :actions="[{ id: 'bold', label: 'Bold', icon: 'format_bold', selected: bold, onClick: toggleBold }]"
+>
+  <template #fab>
+    <M3FabButton aria-label="Add section" @click="addSection"><M3Icon name="add" /></M3FabButton>
+  </template>
+</M3Toolbar>
+```
+
+## API
+
+| Export | Purpose |
+| --- | --- |
+| `M3Toolbar` | Container, layout, scroll response, and icon-action overflow. |
+| Vue props and exposed `el` | Public component controls and element reference. |
+| `ToolbarAction`, `ToolbarVariant`, `ToolbarOrientation`, `ToolbarColor`, `ToolbarScroll`, `ToolbarSide` | Shared foundation types. |
+
+| Prop | Default | Effect |
+| --- | --- | --- |
+| `label` | Required | Accessible name of this toolbar. |
+| `variant` | `docked` | `docked` or `floating`. |
+| `orientation` | `horizontal` | `vertical` applies to floating. |
+| `color` | `standard` | `standard` or `vibrant` container/action colors. |
+| `side` | `end` | `start` or `end` for vertical floating. |
+| `scroll` | `pinned` | `pinned`, `hide`, or `collapse` (floating with FAB). |
+| `scrollTarget` | `window` | Scrollable element or window to observe. |
+| `actions` | `[]` | Icon actions eligible for automatic overflow. |
+| `overflowLabel` | `More actions` | Accessible overflow trigger name; translate for the app locale. |
+| HTML attributes | — | Passed to the toolbar root. |
+
+`#fab` places a FAB beside the floating container. The default slot fills the custom-content area. The component instance exposes `el`.
+
+## Sources
+
+- [Material overview](https://m3.material.io/components/toolbars/overview)
+- [Specs](https://m3.material.io/components/toolbars/specs)
+- [Guidelines](https://m3.material.io/components/toolbars/guidelines)
+- [Accessibility](https://m3.material.io/components/toolbars/accessibility)
+
+</Localized>
+
+<Localized locale="ru-RU">
+
+# Панель инструментов
+
+Toolbar объединяет действия текущей страницы или её содержимого. `M3Toolbar` реализует два варианта [Material 3 Expressive](https://m3.material.io/components/toolbars/overview): **docked** и **floating**. Прежний bottom app bar остался в baseline, но Material больше не рекомендует его; для нового Expressive-интерфейса используйте docked toolbar.
+
+## Руководство
+
+| Вариант | Когда использовать | Положение |
+| --- | --- | --- |
+| `docked` | Действия, общие для нескольких страниц | На всю ширину снизу; не показывать одновременно с нижним navigation bar. |
+| `floating`, горизонтальный | Действия текущей страницы или выделения | Поверх содержимого, не ближе 16 px к краю. Рядом возможен FAB. |
+| `floating`, вертикальный | Компактная группа действий на широком экране | У бокового края с отступом от 24 px; напротив navigation rail. |
+
+`color="standard"` сохраняет внимание на содержимом; `vibrant` выделяет контролы или временный режим. Делайте акцент на одном действии. В docked добавьте его внутрь панели; FAB рядом с floating передаётся отдельным слотом. Toolbar не управляет действием FAB. Каждому toolbar требуется доступное имя. [Рекомендации Material](https://m3.material.io/components/toolbars/guidelines).
+
+### Действия и overflow
+
+Передайте иконочные действия в `actions` для автоматического переноса в overflow. Каждому нужен стабильный `id`, локализованное `label`, имя иконки и `onClick`; `disabled` и `selected` сохраняются в меню. Toolbar измеряет родительский контейнер и переносит последние действия, когда места не хватает. Переведите и `overflowLabel`. Название действия должно быть понятным без иконки.
+
+Слот по умолчанию подходит для кнопок, текстовых полей, изображений и другого произвольного содержимого. Toolbar располагает их, но автоматически переносит в меню **только** элементы `actions`. Для пользовательского содержимого подберите собственную адаптивную компоновку. Избегайте широких элементов в вертикальной панели и множества несвязанных видов контролов. [Гибкость и адаптивность в спеке](https://m3.material.io/components/toolbars/guidelines).
+
+### Прокрутка и доступность
+
+`scroll="pinned"` оставляет toolbar на экране. `hide` уводит его при прокрутке вперёд и возвращает при обратной. Для floating с `#fab` режим `collapse` оставляет только главное действие. Скрытие и сворачивание не совмещаются. Для вложенной прокрутки укажите `scrollTarget`. При получении фокуса контролы возвращаются. При reduced motion переходы отключены.
+
+Корень имеет `role="toolbar"`, доступное имя и ориентацию. Tab проходит по обычным контролам, стрелки вдоль оси перемещают фокус, Home/End переводят его к краям. Стрелки внутри текстового поля сохраняют обычное поведение. Давайте названия иконочным кнопкам. Сам контейнер не обрабатывает нажатие. [Доступность Material](https://m3.material.io/components/toolbars/accessibility).
+
+```vue
+<M3Toolbar
+  label="Инструменты редактирования"
+  overflow-label="Другие инструменты"
+  variant="floating"
+  color="vibrant"
+  scroll="collapse"
+  :scroll-target="editorScroller"
+  :actions="[{ id: 'bold', label: 'Полужирный', icon: 'format_bold', selected: bold, onClick: toggleBold }]"
+>
+  <template #fab>
+    <M3FabButton aria-label="Добавить раздел" @click="addSection"><M3Icon name="add" /></M3FabButton>
+  </template>
+</M3Toolbar>
+```
+
+## API
+
+| Экспорт | Назначение |
+| --- | --- |
+| `M3Toolbar` | Контейнер, компоновка, реакция на прокрутку и overflow иконочных действий. |
+| Vue props и exposed `el` | Публичные настройки и ссылка на элемент. |
+| `ToolbarAction`, `ToolbarVariant`, `ToolbarOrientation`, `ToolbarColor`, `ToolbarScroll`, `ToolbarSide` | Общие типы foundation. |
+
+| Prop | По умолчанию | Назначение |
+| --- | --- | --- |
+| `label` | Обязателен | Доступное имя toolbar. |
+| `variant` | `docked` | `docked` или `floating`. |
+| `orientation` | `horizontal` | `vertical` действует для floating. |
+| `color` | `standard` | Цветовая схема `standard` или `vibrant`. |
+| `side` | `end` | `start` или `end` для вертикального floating. |
+| `scroll` | `pinned` | `pinned`, `hide`, `collapse` (floating с FAB). |
+| `scrollTarget` | `window` | Наблюдаемое окно или прокручиваемый элемент. |
+| `actions` | `[]` | Иконочные действия с автоматическим overflow. |
+| `overflowLabel` | `More actions` | Имя кнопки меню; переведите его под язык приложения. |
+| HTML-атрибуты | — | Передаются корневому элементу. |
+
+`#fab` располагает FAB рядом с floating-контейнером. Содержимое слота по умолчанию попадает в область пользовательского содержимого. Экземпляр компонента предоставляет `el`.
+
+## Источники
+
+- [Обзор](https://m3.material.io/components/toolbars/overview)
+- [Спецификация](https://m3.material.io/components/toolbars/specs)
+- [Рекомендации](https://m3.material.io/components/toolbars/guidelines)
+- [Доступность](https://m3.material.io/components/toolbars/accessibility)
+
+</Localized>
diff --git a/m3-vue/storybook/components/M3Toolbar.stories.ts b/m3-vue/storybook/components/M3Toolbar.stories.ts
new file mode 100644
index 0000000..dacb376
--- /dev/null
+++ b/m3-vue/storybook/components/M3Toolbar.stories.ts
@@ -0,0 +1,47 @@
+import type { Meta, StoryObj } from '@storybook/vue3'
+
+import { M3Toolbar } from '@/components/toolbar'
+
+import ToolbarExample from '../examples/toolbar/ToolbarExample.vue'
+
+const meta = {
+  title: 'Components/M3Toolbar',
+  component: M3Toolbar,
+  args: { label: 'Editing tools', variant: 'docked', orientation: 'horizontal', color: 'standard', side: 'end', scroll: 'pinned' },
+  argTypes: {
+    variant: { control: 'select', options: ['docked', 'floating'] },
+    orientation: { control: 'select', options: ['horizontal', 'vertical'] },
+    color: { control: 'select', options: ['standard', 'vibrant'] },
+    side: { control: 'select', options: ['start', 'end'] },
+    scroll: { control: 'select', options: ['pinned', 'hide', 'collapse'] },
+    actions: { control: false },
+    scrollTarget: { control: false },
+    overflowLabel: { control: false },
+  },
+  render: (args: Record<string, unknown>, { globals }) => ({
+    components: { ToolbarExample },
+    setup: () => ({ ...args, locale: globals.locale }),
+    template: '<ToolbarExample :variant="variant" :orientation="orientation" :color="color" :side="side" :scroll="scroll" :locale="locale" />',
+  }),
+  parameters: { layout: 'fullscreen' },
+} satisfies Meta<typeof M3Toolbar>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Docked: Story = {}
+export const DockedVibrant: Story = { args: { color: 'vibrant' } }
+export const Floating: Story = { args: { variant: 'floating' } }
+export const FloatingVibrant: Story = { args: { variant: 'floating', color: 'vibrant' } }
+export const VerticalFloating: Story = { args: { variant: 'floating', orientation: 'vertical' } }
+export const HideOnScroll: Story = { args: { variant: 'floating', scroll: 'hide' } }
+export const CollapseOnScroll: Story = { args: { variant: 'floating', scroll: 'collapse' } }
+export const NarrowOverflow: Story = {
+  args: { variant: 'floating' },
+  render: (args: Record<string, unknown>, { globals }) => ({
+    components: { ToolbarExample },
+    setup: () => ({ ...args, locale: globals.locale }),
+    template: '<ToolbarExample :variant="variant" :orientation="orientation" :color="color" :side="side" :scroll="scroll" :locale="locale" narrow />',
+  }),
+}
diff --git a/m3-vue/storybook/examples/toolbar/ToolbarExample.vue b/m3-vue/storybook/examples/toolbar/ToolbarExample.vue
new file mode 100644
index 0000000..9a6d183
--- /dev/null
+++ b/m3-vue/storybook/examples/toolbar/ToolbarExample.vue
@@ -0,0 +1,104 @@
+<template>
+    <main
+        ref="scroller"
+        :lang="locale"
+        :style="{
+            blockSize: '100vh',
+            inlineSize: narrow ? 'min(320px, 100vw)' : '100%',
+            marginInline: 'auto',
+            overflowY: 'auto',
+            background: 'var(--m3-sys-surface)',
+            color: 'var(--m3-sys-on-surface)',
+        }"
+    >
+        <div style="max-inline-size: 1120px; margin-inline: auto; padding: 24px; padding-block-end: 160px">
+            <h1>{{ text.title }}</h1>
+            <p>{{ text.hint }} {{ text.last }}: {{ last }}</p>
+            <div style="display: flex; flex-wrap: wrap; gap: 16px">
+                <article
+                    v-for="(card, index) in cards"
+                    :key="`${card}-${index}`"
+                    style="box-sizing: border-box; flex: 1 1 max-content; min-inline-size: min(180px, 100%); max-inline-size: min(360px, 100%); min-block-size: 150px; padding: 24px; border-radius: 24px; background: var(--m3-sys-surface-container)"
+                >
+                    <h2 style="margin-block-start: 0; font-size: 22px; line-height: 28px; overflow-wrap: break-word">
+                        {{ card }}
+                    </h2>
+                    <p>Material 3</p>
+                </article>
+            </div>
+        </div>
+
+        <M3Toolbar
+            :label="text.label"
+            :overflow-label="text.more"
+            :variant="variant"
+            :orientation="orientation"
+            :color="color"
+            :side="side"
+            :scroll="scroll"
+            :scroll-target="scroller"
+            :actions="actions"
+        >
+            <template v-if="variant === 'floating'" #fab>
+                <M3FabButton :aria-label="text.add" @click="last = text.add">
+                    <M3Icon name="add" />
+                </M3FabButton>
+            </template>
+        </M3Toolbar>
+    </main>
+</template>
+
+<script lang="ts" setup>
+import type { PropType } from 'vue'
+import type {
+  ToolbarColor,
+  ToolbarOrientation,
+  ToolbarScroll,
+  ToolbarSide,
+  ToolbarVariant,
+} from '@modulify/m3-foundation/types/components/toolbar'
+
+import { computed, ref } from 'vue'
+
+import { M3FabButton } from '@/components/fab-button'
+import { M3Icon } from '@/components/icon'
+import { M3Toolbar } from '@/components/toolbar'
+
+import { localize } from '../../i18n'
+
+const messages = {
+  'en-US': {
+    title: 'Document editor', hint: 'Scroll to see how the toolbar responds.', label: 'Editing tools', more: 'More editing tools',
+    actions: ['Bold', 'Italic', 'Underline', 'Insert link', 'Insert image', 'Align', 'Comment'],
+    cards: ['Outline', 'Introduction', 'Research notes', 'References', 'Draft', 'Review', 'Changes', 'Next steps'],
+    add: 'Add section', last: 'Last action',
+  },
+  'ru-RU': {
+    title: 'Редактор документа', hint: 'Прокрутите страницу, чтобы увидеть поведение панели.', label: 'Инструменты редактирования', more: 'Другие инструменты',
+    actions: ['Полужирный', 'Курсив', 'Подчеркнуть', 'Вставить ссылку', 'Вставить изображение', 'Выровнять', 'Комментировать'],
+    cards: ['Структура', 'Введение', 'Исследование', 'Источники', 'Черновик', 'Рецензия', 'Изменения', 'Следующие шаги'],
+    add: 'Добавить раздел', last: 'Последнее действие',
+  },
+}
+
+const icons = ['format_bold', 'format_italic', 'format_underlined', 'link', 'image', 'format_align_left', 'comment']
+
+const props = defineProps({
+  variant: { type: String as PropType<ToolbarVariant>, required: true },
+  orientation: { type: String as PropType<ToolbarOrientation>, required: true },
+  color: { type: String as PropType<ToolbarColor>, required: true },
+  side: { type: String as PropType<ToolbarSide>, required: true },
+  scroll: { type: String as PropType<ToolbarScroll>, required: true },
+  locale: { type: String, required: true },
+  narrow: { type: Boolean, default: false },
+})
+
+const scroller = ref<HTMLElement | null>(null)
+const last = ref('—')
+const text = computed(() => localize(props.locale, messages))
+const cards = computed(() => [...text.value.cards, ...text.value.cards])
+const actions = computed(() => text.value.actions.map((label, index) => ({
+  id: icons[index], label, icon: icons[index], selected: index === 0,
+  onClick: () => last.value = label,
+})))
+</script>
diff --git a/m3-vue/tests/M3Toolbar.e2e.ts b/m3-vue/tests/M3Toolbar.e2e.ts
new file mode 100644
index 0000000..89904a7
--- /dev/null
+++ b/m3-vue/tests/M3Toolbar.e2e.ts
@@ -0,0 +1,133 @@
+import { createApp, h, nextTick } from 'vue'
+import { page } from 'vitest/browser'
+
+import { M3FabButton } from '@/components/fab-button'
+import { M3Icon } from '@/components/icon'
+import { M3Toolbar } from '@/components/toolbar'
+
+const actions = ['Bold', 'Italic', 'Underline', 'Link', 'Image', 'Align'].map((label, index) => ({
+  id: String(index), label, icon: 'edit', onClick: vi.fn(),
+}))
+const overflowActions = actions.map((action, index) => index === 4 ? { ...action, label: 'Вставить изображение' } : action)
+
+const waitFor = async (assertion: () => void) => {
+  const startedAt = performance.now()
+  while (performance.now() - startedAt < 2000) {
+    try { assertion(); return } catch { await new Promise(resolve => setTimeout(resolve, 16)) }
+  }
+  assertion()
+}
+
+test('keeps floating actions within the viewport and restores overflowed actions after resize', async () => {
+  await page.viewport(320, 700)
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const app = createApp(M3Toolbar, { label: 'Editing', variant: 'floating', actions: overflowActions, overflowLabel: 'More tools' })
+  app.mount(mountPoint)
+
+  try {
+    const toolbar = mountPoint.querySelector<HTMLElement>('.m3-toolbar')!
+    const container = toolbar.querySelector<HTMLElement>('.m3-toolbar__container')!
+    await waitFor(() => expect(mountPoint.querySelector('[aria-label="More tools"]')).not.toBeNull())
+    const bounds = container.getBoundingClientRect()
+    expect(bounds.height).toBe(64)
+    expect(bounds.left).toBeGreaterThanOrEqual(16)
+    expect(bounds.right).toBeLessThanOrEqual(304)
+
+    const trigger = mountPoint.querySelector('[aria-label="More tools"]') as HTMLButtonElement
+    trigger.click()
+    await waitFor(() => expect([...document.querySelectorAll('.m3-menu-item')].some(item => item.textContent?.includes('Вставить изображение'))).toBe(true))
+    const item = [...document.querySelectorAll<HTMLElement>('.m3-menu-item')].find(element => element.textContent?.includes('Вставить изображение'))!
+    const menu = item.closest<HTMLElement>('.m3-menu')!
+    await waitFor(() => {
+      const menuBounds = menu.getBoundingClientRect()
+      const toolbarBounds = toolbar.getBoundingClientRect()
+      expect(Math.min(menuBounds.bottom, toolbarBounds.bottom) - Math.max(menuBounds.top, toolbarBounds.top)).toBeGreaterThan(0)
+      const x = (Math.max(menuBounds.left, toolbarBounds.left) + Math.min(menuBounds.right, toolbarBounds.right)) / 2
+      const y = (Math.max(menuBounds.top, toolbarBounds.top) + Math.min(menuBounds.bottom, toolbarBounds.bottom)) / 2
+      expect(document.elementFromPoint(x, y)?.closest('.m3-menu')).toBe(menu)
+    })
+    const body = item.querySelector<HTMLElement>('.m3-menu-item__body')!
+    const textStarts = [...menu.querySelectorAll('.m3-menu-item__body')].map(element => {
+      const range = document.createRange()
+      range.selectNodeContents(element)
+      return range.getBoundingClientRect().left
+    })
+    expect(Math.max(...textStarts) - Math.min(...textStarts)).toBeLessThan(1)
+    expect(body.scrollWidth).toBeLessThanOrEqual(body.clientWidth)
+    expect(body.getBoundingClientRect().height).toBeLessThan(parseFloat(getComputedStyle(body).lineHeight) * 1.5)
+    item.click()
+    expect(actions[4].onClick).toHaveBeenCalledOnce()
+
+    await page.viewport(900, 700)
+    await waitFor(() => expect(mountPoint.querySelector('[aria-label="More tools"]')).toBeNull())
+    expect(mountPoint.querySelector('[aria-label="Вставить изображение"]')).not.toBeNull()
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test('restores the full floating width after collapsing to the FAB', async () => {
+  await page.viewport(900, 700)
+  const scroller = document.createElement('main')
+  Object.assign(scroller.style, { height: '300px', overflowY: 'auto' })
+  document.body.append(scroller)
+  const app = createApp({
+    render: () => [
+      h(M3Toolbar, {
+        label: 'Editing', variant: 'floating', scroll: 'collapse', scrollTarget: scroller, actions,
+      }, {
+        default: () => h('button', 'Custom action'),
+        fab: () => h(M3FabButton, { 'aria-label': 'Add' }, () => h(M3Icon, { name: 'add' })),
+      }),
+      h('div', { style: { height: '1000px' } }),
+    ],
+  })
+  app.mount(scroller)
+
+  try {
+    const toolbar = scroller.querySelector<HTMLElement>('.m3-toolbar')!
+    const container = toolbar.querySelector<HTMLElement>('.m3-toolbar__container')!
+    const expandedWidth = container.getBoundingClientRect().width
+    scroller.scrollTop = 100
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
+    scroller.scrollTop = 0
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(false))
+    await waitFor(() => expect(container.getBoundingClientRect().width).toBeCloseTo(expandedWidth, 0))
+  } finally {
+    app.unmount()
+    scroller.remove()
+  }
+})
+
+test('positions vertical floating toolbar at the logical end and collapses to FAB on scroll', async () => {
+  await page.viewport(900, 700)
+  const scroller = document.createElement('main')
+  Object.assign(scroller.style, { height: '300px', overflowY: 'auto' })
+  document.body.append(scroller)
+  const app = createApp({
+    render: () => [
+      h(M3Toolbar, {
+        label: 'Editing', variant: 'floating', orientation: 'vertical', scroll: 'collapse', scrollTarget: scroller, actions: actions.slice(0, 3),
+      }, { fab: () => h(M3FabButton, { 'aria-label': 'Add' }, () => h(M3Icon, { name: 'add' })) }),
+      h('div', { style: { height: '1000px' } }),
+    ],
+  })
+  app.mount(scroller)
+
+  try {
+    const toolbar = scroller.querySelector<HTMLElement>('.m3-toolbar')!
+    expect(Math.round(900 - toolbar.getBoundingClientRect().right)).toBe(24)
+    scroller.scrollTop = 100
+    await nextTick()
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
+    expect(scroller.querySelector('[aria-label="Add"]')).not.toBeNull()
+    scroller.scrollTop = 0
+    await nextTick()
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(false))
+  } finally {
+    app.unmount()
+    scroller.remove()
+  }
+})
diff --git a/m3-vue/tests/M3Toolbar.test.ts b/m3-vue/tests/M3Toolbar.test.ts
new file mode 100644
index 0000000..0527bcb
--- /dev/null
+++ b/m3-vue/tests/M3Toolbar.test.ts
@@ -0,0 +1,82 @@
+import { fireEvent } from '@testing-library/vue'
+import { h, nextTick } from 'vue'
+import { render, screen, waitFor } from '@testing-library/vue'
+
+import { M3Toolbar } from '@/components/toolbar'
+
+const actions = [
+  { id: 'bold', label: 'Bold', icon: 'format_bold', onClick: vi.fn() },
+  { id: 'italic', label: 'Italic', icon: 'format_italic', onClick: vi.fn() },
+  { id: 'underline', label: 'Underline', icon: 'format_underlined', onClick: vi.fn() },
+  { id: 'link', label: 'Link', icon: 'link', onClick: vi.fn() },
+  { id: 'image', label: 'Image', icon: 'image', onClick: vi.fn() },
+]
+
+describe('m3-vue/toolbar', () => {
+  test('renders docked and vertical floating variants with accessible actions', async () => {
+    const view = render(M3Toolbar, { props: { label: 'Editing', actions }, slots: { fab: () => h('button', 'Add') } })
+    expect(screen.getByRole('toolbar', { name: 'Editing' }).getAttribute('aria-orientation')).toBe('horizontal')
+    expect(screen.getByRole('button', { name: 'Bold' })).not.toBeNull()
+    expect(view.container.querySelector('.m3-toolbar_docked')).not.toBeNull()
+    expect(view.container.querySelector('.m3-toolbar__fab')).toBeNull()
+
+    await view.rerender({ label: 'Editing', variant: 'floating', orientation: 'vertical', color: 'vibrant', side: 'start', actions })
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+    expect(toolbar.getAttribute('aria-orientation')).toBe('vertical')
+    expect(toolbar.classList.contains('m3-toolbar_side-start')).toBe(true)
+    expect(toolbar.classList.contains('m3-toolbar_vibrant')).toBe(true)
+    expect(view.container.querySelector('.m3-toolbar__fab')).not.toBeNull()
+  })
+
+  test('moves focus along the toolbar without stealing input arrows', async () => {
+    render(M3Toolbar, { props: { label: 'Editing', actions: actions.slice(0, 2) }, slots: { default: () => h('input', { 'aria-label': 'Find' }) } })
+    const bold = screen.getByRole('button', { name: 'Bold' })
+    bold.focus()
+    await fireEvent.keyDown(bold, { key: 'ArrowRight' })
+    expect(document.activeElement).toBe(screen.getByRole('button', { name: 'Italic' }))
+
+    const input = screen.getByRole('textbox', { name: 'Find' })
+    input.focus()
+    await fireEvent.keyDown(input, { key: 'ArrowRight' })
+    expect(document.activeElement).toBe(input)
+  })
+
+  test('moves excess actions into an accessible menu at a narrow width', async () => {
+    const width = window.innerWidth
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 200 })
+    try {
+      render(M3Toolbar, { props: { label: 'Editing', actions, overflowLabel: 'More editing actions' } })
+      await nextTick()
+      expect(screen.getByRole('button', { name: 'Bold' })).not.toBeNull()
+      expect(screen.queryByRole('button', { name: 'Underline' })).toBeNull()
+      await fireEvent.click(screen.getByRole('button', { name: 'More editing actions' }))
+      const item = await screen.findByText('Underline')
+      await fireEvent.click(item)
+      expect(actions[2].onClick).toHaveBeenCalledOnce()
+    } finally {
+      Object.defineProperty(window, 'innerWidth', { configurable: true, value: width })
+    }
+  })
+
+  test('hides or collapses on forward scroll and restores on reverse scroll', async () => {
+    const scroller = document.createElement('div')
+    const view = render(M3Toolbar, {
+      props: { label: 'Editing', variant: 'floating', scroll: 'collapse', scrollTarget: scroller, actions },
+      slots: { fab: () => h('button', 'Add') },
+    })
+    const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
+
+    scroller.scrollTop = 40
+    await fireEvent.scroll(scroller)
+    expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true)
+    expect(screen.getByRole('button', { name: 'Add' })).not.toBeNull()
+
+    scroller.scrollTop = 20
+    await fireEvent.scroll(scroller)
+    expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(false)
+    await view.rerender({ label: 'Editing', scroll: 'hide', scrollTarget: scroller })
+    scroller.scrollTop = 60
+    await fireEvent.scroll(scroller)
+    await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_hidden')).toBe(true))
+  })
+})

From 0c90dcff5abf4742b85cca220c460e7f46430c9d Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Fri, 9 Oct 2026 11:41:54 +0400
Subject: [PATCH 14/20] test: Toolbar package exports were validated

Closes #12
---
 scripts/check-packages.mjs | 29 ++++++++++++++++++++++++-----
 1 file changed, 24 insertions(+), 5 deletions(-)

diff --git a/scripts/check-packages.mjs b/scripts/check-packages.mjs
index 481ddd0..1002260 100644
--- a/scripts/check-packages.mjs
+++ b/scripts/check-packages.mjs
@@ -285,6 +285,8 @@ import { createRef } from 'react'
 import { ref } from 'vue'
 
 import { CalendarDay } from '@modulify/m3-foundation/lib/calendar'
+import { getToolbarVisibleCount } from '@modulify/m3-foundation/lib/toolbar'
+import type { ToolbarAction } from '@modulify/m3-foundation/types/components/toolbar'
 import type { ElementReference, Interactable } from '@modulify/m3-foundation/types/dom'
 import {
   durations,
@@ -312,6 +314,8 @@ import {
   type M3LinkExposed,
   type M3NavigationExposed,
   type M3SideSheetExposed,
+  M3Toolbar as ReactToolbar,
+  type M3ToolbarProps,
 } from '@modulify/m3-react/components'
 import {
   useAnimationFrame as useReactAnimationFrame,
@@ -331,7 +335,7 @@ import { useBreakpoint as useRootVueBreakpoint } from '@modulify/m3-vue'
 import { useMutationObserver as useRootVueMutationObserver } from '@modulify/m3-vue'
 import { useResizeObserver as useRootVueResizeObserver } from '@modulify/m3-vue'
 import { useTimeout as useRootVueTimeout } from '@modulify/m3-vue'
-import { M3Select, type M3SelectOption } from '@modulify/m3-vue/components'
+import { M3Select, M3Toolbar as VueToolbar, type M3SelectOption } from '@modulify/m3-vue/components'
 import {
   useAnimationFrame as useVueAnimationFrame,
   useBreakpoint as useVueBreakpoint,
@@ -349,6 +353,8 @@ const buttonProps: M3ButtonProps = { appearance: 'filled', ref: buttonRef }
 const duration: M3MotionDuration = 'medium2'
 const easingName: M3MotionEasing = 'standard'
 const options: M3SelectOption<number>[] = [{ value: 1, label: 'One' }]
+const toolbarActions: ToolbarAction[] = [{ id: 'save', label: 'Save', icon: 'save', onClick: () => {} }]
+const toolbarProps: M3ToolbarProps = { label: 'Editor actions', actions: toolbarActions }
 const reactObserverTarget = createRef<HTMLDivElement>()
 const reactMutationObserverTargets: Parameters<typeof useReactMutationObserver>[0] = [reactObserverTarget]
 const reactResizeObserverTargets: Parameters<typeof useReactResizeObserver>[0] = [reactObserverTarget]
@@ -363,6 +369,8 @@ void [
   CalendarDay,
   M3Button,
   M3Select,
+  ReactToolbar,
+  VueToolbar,
   RootM3Button,
   RootM3Select,
   buttonRef,
@@ -377,6 +385,9 @@ void [
   linkElement,
   navigationRef,
   options,
+  toolbarActions,
+  toolbarProps,
+  getToolbarVisibleCount,
   reactMutationObserverTargets,
   reactResizeObserverTargets,
   sideSheetRef,
@@ -420,6 +431,7 @@ import { access } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 
 import { CalendarDay } from '@modulify/m3-foundation/lib/calendar'
+import { getToolbarVisibleCount } from '@modulify/m3-foundation/lib/toolbar'
 import { durations, easing, timing } from '@modulify/m3-foundation/lib/motion'
 import { M3Button as RootM3Button } from '@modulify/m3-react'
 import { useAnimationFrame as useRootReactAnimationFrame } from '@modulify/m3-react'
@@ -431,7 +443,7 @@ import { useInteractable as useRootReactInteractable } from '@modulify/m3-react'
 import { useMutationObserver as useRootReactMutationObserver } from '@modulify/m3-react'
 import { useResizeObserver as useRootReactResizeObserver } from '@modulify/m3-react'
 import { useTimeout as useRootReactTimeout } from '@modulify/m3-react'
-import { M3Button } from '@modulify/m3-react/components'
+import { M3Button, M3Toolbar as ReactToolbar } from '@modulify/m3-react/components'
 import {
   useAnimationFrame as useReactAnimationFrame,
   useBreakpoint as useReactBreakpoint,
@@ -450,7 +462,7 @@ import { useBreakpoint as useRootVueBreakpoint } from '@modulify/m3-vue'
 import { useMutationObserver as useRootVueMutationObserver } from '@modulify/m3-vue'
 import { useResizeObserver as useRootVueResizeObserver } from '@modulify/m3-vue'
 import { useTimeout as useRootVueTimeout } from '@modulify/m3-vue'
-import { M3Select } from '@modulify/m3-vue/components'
+import { M3Select, M3Toolbar as VueToolbar } from '@modulify/m3-vue/components'
 import {
   useAnimationFrame as useVueAnimationFrame,
   useBreakpoint as useVueBreakpoint,
@@ -485,6 +497,9 @@ if (
   || !easing
   || !M3Button
   || !M3Select
+  || !ReactToolbar
+  || !VueToolbar
+  || getToolbarVisibleCount(200, 3) !== 3
   || !RootM3Button
   || !RootM3Select
   || !useReactAnimationFrame
@@ -524,6 +539,7 @@ if (
 `)
   writeFileSync(resolve(temporaryDirectory, 'consumer.cjs'), `
 const { CalendarDay } = require('@modulify/m3-foundation/lib/calendar')
+const { getToolbarVisibleCount } = require('@modulify/m3-foundation/lib/toolbar')
 const { durations, easing, timing } = require('@modulify/m3-foundation/lib/motion')
 const { M3Button: RootM3Button } = require('@modulify/m3-react')
 const { useAnimationFrame: useRootReactAnimationFrame } = require('@modulify/m3-react')
@@ -535,7 +551,7 @@ const { useInteractable: useRootReactInteractable } = require('@modulify/m3-reac
 const { useMutationObserver: useRootReactMutationObserver } = require('@modulify/m3-react')
 const { useResizeObserver: useRootReactResizeObserver } = require('@modulify/m3-react')
 const { useTimeout: useRootReactTimeout } = require('@modulify/m3-react')
-const { M3Button } = require('@modulify/m3-react/components')
+const { M3Button, M3Toolbar: ReactToolbar } = require('@modulify/m3-react/components')
 const {
   useAnimationFrame: useReactAnimationFrame,
   useBreakpoint: useReactBreakpoint,
@@ -554,7 +570,7 @@ const { useBreakpoint: useRootVueBreakpoint } = require('@modulify/m3-vue')
 const { useMutationObserver: useRootVueMutationObserver } = require('@modulify/m3-vue')
 const { useResizeObserver: useRootVueResizeObserver } = require('@modulify/m3-vue')
 const { useTimeout: useRootVueTimeout } = require('@modulify/m3-vue')
-const { M3Select } = require('@modulify/m3-vue/components')
+const { M3Select, M3Toolbar: VueToolbar } = require('@modulify/m3-vue/components')
 const {
   useAnimationFrame: useVueAnimationFrame,
   useBreakpoint: useVueBreakpoint,
@@ -570,6 +586,9 @@ if (
   || !easing
   || !M3Button
   || !M3Select
+  || !ReactToolbar
+  || !VueToolbar
+  || getToolbarVisibleCount(200, 3) !== 3
   || !RootM3Button
   || !RootM3Select
   || !useReactAnimationFrame

From 7a33555647fff3b173c3ad6f3029c4650ac1fd6f Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Mon, 19 Oct 2026 12:21:19 +0400
Subject: [PATCH 15/20] feat(m3-foundation)!: Shared UI layer management was
 added

Modal focus, popovers, floating content, and feedback now use isolated layer hosts and group levels.

BREAKING CHANGE: The layers.scss level names were replaced with floating, feedback, popover, and modal; --m3-search-z-index no longer controls the search overlay.
---
 .../assets/stylesheets/basics/layers.scss     |  13 +-
 .../stylesheets/components/app-bar/index.scss |   2 +-
 .../stylesheets/components/dialog/index.scss  |  18 ---
 .../assets/stylesheets/components/index.scss  |   1 +
 .../stylesheets/components/layer/index.scss   |  27 ++++
 .../components/navigation/index.scss          |   4 +-
 .../stylesheets/components/scrim/index.scss   |   4 +-
 .../stylesheets/components/search/index.scss  |   3 +-
 .../components/side-sheet/index.scss          |   3 +-
 .../components/snackbar/index.scss            |   2 +-
 .../stylesheets/components/surface/index.scss |   2 +
 .../stylesheets/components/toolbar/index.scss |   2 +-
 m3-foundation/lib/layers.ts                   | 146 ++++++++++++++++++
 m3-foundation/lib/modal.ts                    |  33 ++--
 m3-foundation/vite.config.ts                  |   1 +
 15 files changed, 208 insertions(+), 53 deletions(-)
 create mode 100644 m3-foundation/assets/stylesheets/components/layer/index.scss
 create mode 100644 m3-foundation/lib/layers.ts

diff --git a/m3-foundation/assets/stylesheets/basics/layers.scss b/m3-foundation/assets/stylesheets/basics/layers.scss
index b5cb6e2..58ee5f5 100644
--- a/m3-foundation/assets/stylesheets/basics/layers.scss
+++ b/m3-foundation/assets/stylesheets/basics/layers.scss
@@ -1,14 +1,11 @@
 @use 'sass:map';
 
-// Page-level layers. Small z-index values inside a component remain local.
+// UI groups repeat inside each isolated modal layer.
 $levels: (
-  'app-bar': 10,
-  'toolbar': 100,
-  'snackbar': 900,
-  'scrim': 1000,
-  'modal': 1001,
-  'popover': 1100,
-  'search': 1200,
+  'floating': 10,
+  'feedback': 50,
+  'popover': 100,
+  'modal': 1000,
 );
 
 @function level($name) {
diff --git a/m3-foundation/assets/stylesheets/components/app-bar/index.scss b/m3-foundation/assets/stylesheets/components/app-bar/index.scss
index 6dc9e1c..0902b6f 100644
--- a/m3-foundation/assets/stylesheets/components/app-bar/index.scss
+++ b/m3-foundation/assets/stylesheets/components/app-bar/index.scss
@@ -14,7 +14,7 @@
   color: var(--m3-sys-on-surface);
   position: sticky;
   inset-block-start: 0;
-  z-index: m3-layers.level('app-bar');
+  z-index: m3-layers.level('floating');
   transition:
     #{m3-motion.timing-standard(background-color, 'short4')},
     #{m3-motion.timing-standard(block-size, 'medium2')},
diff --git a/m3-foundation/assets/stylesheets/components/dialog/index.scss b/m3-foundation/assets/stylesheets/components/dialog/index.scss
index fc869bf..dcc45e2 100644
--- a/m3-foundation/assets/stylesheets/components/dialog/index.scss
+++ b/m3-foundation/assets/stylesheets/components/dialog/index.scss
@@ -1,24 +1,6 @@
-@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/shape' as m3-shape;
 
-.m3-dialog-container {
-  display: flex;
-  inline-size: 100%;
-  block-size: 100%;
-  align-items: center;
-  justify-content: center;
-  z-index: m3-layers.level('modal');
-  position: fixed;
-  inset-inline-start: 0;
-  inset-block-start: 0;
-
-  .m3-scrim {
-    position: absolute;
-    z-index: 0;
-  }
-}
-
 .m3-dialog-appear-enter {
   transform: translateY(-50%);
 }
diff --git a/m3-foundation/assets/stylesheets/components/index.scss b/m3-foundation/assets/stylesheets/components/index.scss
index 35981a5..33325da 100644
--- a/m3-foundation/assets/stylesheets/components/index.scss
+++ b/m3-foundation/assets/stylesheets/components/index.scss
@@ -9,6 +9,7 @@
 @use 'fab-button';
 @use 'icon';
 @use 'icon-button';
+@use 'layer';
 @use 'list';
 @use 'menu';
 @use 'navigation';
diff --git a/m3-foundation/assets/stylesheets/components/layer/index.scss b/m3-foundation/assets/stylesheets/components/layer/index.scss
new file mode 100644
index 0000000..4279d76
--- /dev/null
+++ b/m3-foundation/assets/stylesheets/components/layer/index.scss
@@ -0,0 +1,27 @@
+@use '../../basics/layers' as m3-layers;
+
+.m3-layer {
+  position: fixed;
+  inset: 0;
+  isolation: isolate;
+  z-index: m3-layers.level('floating');
+  pointer-events: none;
+
+  &[data-m3-layer='modal'] {
+    z-index: m3-layers.level('modal');
+  }
+
+  &__feedback {
+    position: fixed;
+    inset: 0;
+    z-index: m3-layers.level('feedback');
+    pointer-events: none;
+  }
+
+  &__popovers {
+    position: absolute;
+    inset: 0;
+    z-index: m3-layers.level('popover');
+    pointer-events: none;
+  }
+}
diff --git a/m3-foundation/assets/stylesheets/components/navigation/index.scss b/m3-foundation/assets/stylesheets/components/navigation/index.scss
index fa9463e..0664102 100644
--- a/m3-foundation/assets/stylesheets/components/navigation/index.scss
+++ b/m3-foundation/assets/stylesheets/components/navigation/index.scss
@@ -1,5 +1,4 @@
 @use '../../basics/layout' as m3-layout;
-@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/shape' as m3-shape;
 @use '../../basics/typography' as m3-typography;
@@ -52,6 +51,7 @@
   inset-inline-start: 0;
   inset-block-end: 0;
   overflow: hidden;
+  pointer-events: auto;
 
   @include m3-shape.reset-box-sizing;
 
@@ -64,7 +64,7 @@
       m3-motion.timing-emphasized(padding),
       m3-motion.timing-emphasized(gap)
     ;
-    z-index: m3-layers.level('modal');
+    z-index: 1;
   }
 
   &_rail {
diff --git a/m3-foundation/assets/stylesheets/components/scrim/index.scss b/m3-foundation/assets/stylesheets/components/scrim/index.scss
index 516a100..c8d4dc6 100644
--- a/m3-foundation/assets/stylesheets/components/scrim/index.scss
+++ b/m3-foundation/assets/stylesheets/components/scrim/index.scss
@@ -1,4 +1,3 @@
-@use '../../basics/layers' as m3-layers;
 @use '../../basics/palette' as *;
 
 .m3-scrim {
@@ -6,7 +5,8 @@
   inline-size: 100%;
   block-size: 100%;
   background: rgba($m3-palette-neutral-variant-20, 0.4);
-  z-index: m3-layers.level('scrim');
+  z-index: 0;
+  pointer-events: auto;
   position: fixed;
   inset-inline-start: 0;
   inset-block-start: 0;
diff --git a/m3-foundation/assets/stylesheets/components/search/index.scss b/m3-foundation/assets/stylesheets/components/search/index.scss
index a760f8d..5817eda 100644
--- a/m3-foundation/assets/stylesheets/components/search/index.scss
+++ b/m3-foundation/assets/stylesheets/components/search/index.scss
@@ -1,4 +1,3 @@
-@use '../../basics/layers' as m3-layers;
 @use '../../basics/motion' as m3-motion;
 @use '../../basics/typography' as m3-typography;
 
@@ -105,7 +104,7 @@
     pointer-events: none;
     position: fixed;
     inset: 0;
-    z-index: var(--m3-search-z-index, #{m3-layers.level('search')});
+    z-index: 1;
   }
 
   &__scrim {
diff --git a/m3-foundation/assets/stylesheets/components/side-sheet/index.scss b/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
index dc6b72a..0569ed9 100644
--- a/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
+++ b/m3-foundation/assets/stylesheets/components/side-sheet/index.scss
@@ -1,4 +1,3 @@
-@use '../../basics/layers' as m3-layers;
 @use '../../basics/shape' as m3-shape;
 @use '../../basics/typography' as m3-typography;
 
@@ -15,7 +14,7 @@
   position: fixed;
   inset-block-start: 0;
   right: 0;
-  z-index: m3-layers.level('modal');
+  z-index: 1;
 
   background: var(--m3-sys-surface-container-low);
   color: var(--m3-sys-on-surface-variant);
diff --git a/m3-foundation/assets/stylesheets/components/snackbar/index.scss b/m3-foundation/assets/stylesheets/components/snackbar/index.scss
index 5a7255a..b2ec3c0 100644
--- a/m3-foundation/assets/stylesheets/components/snackbar/index.scss
+++ b/m3-foundation/assets/stylesheets/components/snackbar/index.scss
@@ -10,7 +10,7 @@
   position: fixed;
   inset-inline-start: var(--m3-snackbar-inset-inline-start);
   inset-block-end: var(--m3-snackbar-inset-block-end);
-  z-index: m3-layers.level('snackbar');
+  z-index: m3-layers.level('feedback');
   max-inline-size: calc(100vw - var(--m3-snackbar-inset-inline-start) - 16px);
   pointer-events: none;
 
diff --git a/m3-foundation/assets/stylesheets/components/surface/index.scss b/m3-foundation/assets/stylesheets/components/surface/index.scss
index 5608cc7..b18c4c1 100644
--- a/m3-foundation/assets/stylesheets/components/surface/index.scss
+++ b/m3-foundation/assets/stylesheets/components/surface/index.scss
@@ -29,6 +29,7 @@ $m3-surface-on-surface-color: var(--m3-sys-on-surface, #{light.$m3-sys-light-on-
   &_modal {
     max-inline-size: 100vw;
     max-block-size: 100vh;
+    pointer-events: auto;
   }
 
   &_dim               { background-color: $m3-surface-dim-color; }
@@ -50,6 +51,7 @@ $m3-surface-on-surface-color: var(--m3-sys-on-surface, #{light.$m3-sys-light-on-
     position: fixed;
     inset: 0;
     background: color-mix(in srgb, var(--m3-sys-shadow, #{palette.$m3-palette-neutral-0}) 38%, transparent);
+    pointer-events: auto;
   }
 }
 
diff --git a/m3-foundation/assets/stylesheets/components/toolbar/index.scss b/m3-foundation/assets/stylesheets/components/toolbar/index.scss
index 49022a4..940aae1 100644
--- a/m3-foundation/assets/stylesheets/components/toolbar/index.scss
+++ b/m3-foundation/assets/stylesheets/components/toolbar/index.scss
@@ -10,7 +10,7 @@
   display: flex;
   box-sizing: border-box;
   align-items: center;
-  z-index: m3-layers.level('toolbar');
+  z-index: m3-layers.level('floating');
   position: fixed;
   transition: m3-motion.timing-standard(transform, 'medium2');
 
diff --git a/m3-foundation/lib/layers.ts b/m3-foundation/lib/layers.ts
new file mode 100644
index 0000000..7b62f59
--- /dev/null
+++ b/m3-foundation/lib/layers.ts
@@ -0,0 +1,146 @@
+interface ModalEntry {
+  host: HTMLElement;
+  onEscape: () => void;
+}
+
+interface PopoverEntry {
+  host: HTMLElement;
+  onEscape: () => void;
+}
+
+interface LayerManager {
+  modals: ModalEntry[];
+  popovers: PopoverEntry[];
+  listeners: AbortController;
+}
+
+const managers = new WeakMap<Document, LayerManager>()
+export const LAYER_DEACTIVATED_EVENT = 'm3-layer-deactivated'
+
+function managerFor(document: Document): LayerManager {
+  const existing = managers.get(document)
+  if (existing) return existing
+
+  const manager: LayerManager = {
+    modals: [],
+    popovers: [],
+    listeners: new AbortController(),
+  }
+
+  document.addEventListener('keydown', event => {
+    if (event.key !== 'Escape' || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return
+
+    const topModal = manager.modals.at(-1)
+    let topPopover: PopoverEntry | undefined
+    for (let index = manager.popovers.length - 1; index >= 0; index--) {
+      const entry = manager.popovers[index]
+      if (entry.host.isConnected
+        && (topModal ? topModal.host.contains(entry.host) : !entry.host.closest('[data-m3-layer="modal"]'))) {
+        topPopover = entry
+        break
+      }
+    }
+    const onEscape = topPopover?.onEscape ?? topModal?.onEscape
+    if (!onEscape) return
+
+    event.preventDefault()
+    event.stopPropagation()
+    onEscape()
+  }, { capture: true, signal: manager.listeners.signal })
+
+  managers.set(document, manager)
+  return manager
+}
+
+function disposeEmpty(document: Document, manager: LayerManager) {
+  if (manager.modals.length || manager.popovers.length) return
+  manager.listeners.abort('UI layer manager disposed')
+  managers.delete(document)
+}
+
+export function createLayerHost(document: Document): HTMLElement {
+  const host = document.createElement('div')
+  host.className = 'm3-layer'
+
+  const feedback = document.createElement('div')
+  feedback.className = 'm3-layer__feedback'
+  const popovers = document.createElement('div')
+  popovers.className = 'm3-layer__popovers'
+  host.append(feedback, popovers)
+
+  return host
+}
+
+export function mountLayerHost(host: HTMLElement, container: HTMLElement) {
+  container.append(host)
+}
+
+export function setLayerModal(host: HTMLElement, modal: boolean) {
+  host.dataset.m3Layer = modal ? 'modal' : 'base'
+}
+
+export function resolvePopoverContainer(target: Element | null, explicit?: string | HTMLElement): HTMLElement {
+  const document = target?.ownerDocument ?? (typeof explicit === 'string' || !explicit ? globalThis.document : explicit.ownerDocument)
+
+  if (explicit) {
+    return (typeof explicit === 'string' ? document.querySelector<HTMLElement>(explicit) : explicit) ?? document.body
+  }
+
+  const layer = target?.closest<HTMLElement>('[data-m3-layer="modal"]')
+  return layer?.querySelector<HTMLElement>(':scope > .m3-layer__popovers') ?? document.body
+}
+
+export function resolveFeedbackContainer(anchor: Element | null): HTMLElement | null {
+  return anchor?.closest<HTMLElement>('[data-m3-layer="modal"]')
+    ?.querySelector<HTMLElement>(':scope > .m3-layer__feedback') ?? null
+}
+
+export function mountPopoverHost(host: HTMLElement, target: Element | null, explicit?: string | HTMLElement) {
+  resolvePopoverContainer(target, explicit).append(host)
+}
+
+export function raisePopover(host: HTMLElement) {
+  const manager = managers.get(host.ownerDocument)
+  const index = manager?.popovers.findIndex(entry => entry.host === host) ?? -1
+  if (index < 0 || !manager) return
+
+  const [entry] = manager.popovers.splice(index, 1)
+  manager.popovers.push(entry)
+  host.parentElement?.append(host)
+}
+
+export function activateModalLayer(host: HTMLElement, onEscape: () => void, raise = true): () => void {
+  const document = host.ownerDocument
+  const manager = managerFor(document)
+  const entry: ModalEntry = { host, onEscape }
+
+  if (raise) host.parentElement?.append(host)
+  host.dataset.m3LayerActive = 'true'
+  manager.modals.push(entry)
+
+  return () => {
+    const index = manager.modals.indexOf(entry)
+    if (index >= 0) manager.modals.splice(index, 1)
+    delete host.dataset.m3LayerActive
+    host.dispatchEvent(new Event(LAYER_DEACTIVATED_EVENT))
+    disposeEmpty(document, manager)
+  }
+}
+
+export function activatePopover(host: HTMLElement, onEscape: () => void): () => void {
+  const document = host.ownerDocument
+  const manager = managerFor(document)
+  const entry: PopoverEntry = { host, onEscape }
+  const layer = host.closest<HTMLElement>('[data-m3-layer="modal"]')
+
+  host.parentElement?.append(host)
+  layer?.addEventListener(LAYER_DEACTIVATED_EVENT, onEscape)
+  manager.popovers.push(entry)
+
+  return () => {
+    const index = manager.popovers.indexOf(entry)
+    if (index >= 0) manager.popovers.splice(index, 1)
+    layer?.removeEventListener(LAYER_DEACTIVATED_EVENT, onEscape)
+    disposeEmpty(document, manager)
+  }
+}
diff --git a/m3-foundation/lib/modal.ts b/m3-foundation/lib/modal.ts
index 4942de1..5b54610 100644
--- a/m3-foundation/lib/modal.ts
+++ b/m3-foundation/lib/modal.ts
@@ -1,10 +1,14 @@
+import { activateModalLayer } from './layers'
+
 interface ModalFocusOptions {
   dialog: HTMLElement;
+  layer?: HTMLElement;
   exempt?: () => Array<HTMLElement | null>;
   onEscape: () => void;
 }
 
 interface ModalScope extends ModalFocusOptions {
+  focusRoot: HTMLElement;
   previousFocus: HTMLElement | null;
   addedTabIndex: boolean;
 }
@@ -46,7 +50,7 @@ function updateInert(document: Document, manager: ModalManager) {
   const scope = manager.scopes.at(-1)
   if (!scope) return
 
-  const allowed = [scope.dialog, ...(scope.exempt?.() ?? [])]
+  const allowed = [scope.focusRoot, ...(scope.exempt?.() ?? [])]
     .filter((element): element is HTMLElement => !!element && element.isConnected)
 
   const paths = new Set<HTMLElement>()
@@ -77,16 +81,9 @@ function registerModalListeners(document: Document, manager: ModalManager) {
     const scope = manager.scopes.at(-1)
     if (!scope) return
 
-    if (event.key === 'Escape') {
-      event.preventDefault()
-      event.stopPropagation()
-      scope.onEscape()
-      return
-    }
-
     if (event.key !== 'Tab') return
 
-    const items = focusableIn(scope.dialog)
+    const items = focusableIn(scope.focusRoot)
     const first = items[0]
     const last = items.at(-1)
     const active = document.activeElement
@@ -94,10 +91,10 @@ function registerModalListeners(document: Document, manager: ModalManager) {
     if (!first || !last) {
       event.preventDefault()
       scope.dialog.focus()
-    } else if (event.shiftKey && (active === first || !scope.dialog.contains(active))) {
+    } else if (event.shiftKey && (active === first || !scope.focusRoot.contains(active))) {
       event.preventDefault()
       last.focus()
-    } else if (!event.shiftKey && (active === last || !scope.dialog.contains(active))) {
+    } else if (!event.shiftKey && (active === last || !scope.focusRoot.contains(active))) {
       event.preventDefault()
       first.focus()
     }
@@ -105,7 +102,7 @@ function registerModalListeners(document: Document, manager: ModalManager) {
 
   document.addEventListener('focusin', event => {
     const scope = manager.scopes.at(-1)
-    if (scope && !scope.dialog.contains(event.target as Node)) focusFirst(scope.dialog)
+    if (scope && !scope.focusRoot.contains(event.target as Node)) focusFirst(scope.dialog)
   }, { capture: true, signal: manager.listeners.signal })
 }
 
@@ -128,9 +125,11 @@ function createManager(document: Document): ModalManager {
   return manager
 }
 
-function createScope({ dialog, exempt, onEscape }: ModalFocusOptions): ModalScope {
+function createScope({ dialog, layer, exempt, onEscape }: ModalFocusOptions): ModalScope {
   return {
     dialog,
+    layer,
+    focusRoot: layer ?? dialog,
     exempt,
     onEscape,
     previousFocus: dialog.ownerDocument.activeElement instanceof HTMLElement ? dialog.ownerDocument.activeElement : null,
@@ -139,10 +138,11 @@ function createScope({ dialog, exempt, onEscape }: ModalFocusOptions): ModalScop
 }
 
 /** Activate modal focus management and return an idempotent disposal function. */
-export function activateModalFocus({ dialog, exempt, onEscape }: ModalFocusOptions): () => void {
+export function activateModalFocus({ dialog, layer, exempt, onEscape }: ModalFocusOptions): () => void {
   const document = dialog.ownerDocument
   const manager = managers.get(document) ?? createManager(document)
-  const scope = createScope({ dialog, exempt, onEscape })
+  const scope = createScope({ dialog, layer, exempt, onEscape })
+  const deactivateLayer = activateModalLayer(scope.focusRoot, onEscape, Boolean(layer))
 
   if (scope.addedTabIndex) dialog.tabIndex = -1
   manager.scopes.push(scope)
@@ -160,6 +160,7 @@ export function activateModalFocus({ dialog, exempt, onEscape }: ModalFocusOptio
 
     const wasTop = index === manager.scopes.length - 1
     manager.scopes.splice(index, 1)
+    deactivateLayer()
     if (scope.addedTabIndex) dialog.removeAttribute('tabindex')
     updateInert(document, manager)
 
@@ -170,7 +171,7 @@ export function activateModalFocus({ dialog, exempt, onEscape }: ModalFocusOptio
       queueMicrotask(() => {
         if (manager.scopes.at(-1) !== nextTop) return
         const active = document.activeElement
-        if (active !== document.body && !dialog.contains(active)) return
+        if (active !== document.body && !scope.focusRoot.contains(active)) return
 
         if (scope.previousFocus?.isConnected && !scope.previousFocus.inert) {
           scope.previousFocus.focus()
diff --git a/m3-foundation/vite.config.ts b/m3-foundation/vite.config.ts
index 511c479..46a1c00 100644
--- a/m3-foundation/vite.config.ts
+++ b/m3-foundation/vite.config.ts
@@ -10,6 +10,7 @@ const entries = {
   'lib/appBar': resolve(__dirname, 'lib/appBar.ts'),
   'lib/calendar': resolve(__dirname, 'lib/calendar/index.ts'),
   'lib/dom': resolve(__dirname, 'lib/dom.ts'),
+  'lib/layers': resolve(__dirname, 'lib/layers.ts'),
   'lib/motion': resolve(__dirname, 'lib/motion/index.ts'),
   'lib/motion/values': resolve(__dirname, 'lib/motion/values.ts'),
   'lib/modal': resolve(__dirname, 'lib/modal.ts'),

From 781642ae6186c5457114b4c25b0b70ae82eb6995 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Mon, 19 Oct 2026 12:21:42 +0400
Subject: [PATCH 16/20] feat(m3-react)!: Components were moved into shared UI
 layers

Modal surfaces own their popovers and feedback. Layer stacking and dismissal are covered by Storybook examples and browser tests.

BREAKING CHANGE: M3Surface.zIndex was removed; modal stacking now follows layer activation order.
---
 m3-react/src/components/dialog/M3Dialog.tsx   |   2 -
 m3-react/src/components/menu/M3Menu.tsx       |   2 +-
 .../components/navigation/M3Navigation.tsx    |  18 +-
 m3-react/src/components/popper/M3Popper.tsx   |  34 ++-
 m3-react/src/components/popper/hooks.ts       |   2 +-
 m3-react/src/components/search/M3Search.tsx   |  20 +-
 .../src/components/side-sheet/M3SideSheet.tsx |   3 -
 .../components/snackbar/M3SnackbarHost.tsx    |  55 ++++-
 m3-react/src/components/surface/M3Surface.tsx |  24 +--
 .../orchestration/useSurfaceSideSheetMorph.ts |   2 -
 m3-react/src/hooks/index.ts                   |   1 +
 m3-react/src/hooks/useLayerHost.ts            |  25 +++
 m3-react/storybook/components/M3Surface.mdx   |  19 ++
 .../components/M3Surface.stories.tsx          |   5 +
 .../examples/surface/SurfaceLayerStack.tsx    |  83 ++++++++
 .../surface/SurfaceNestedDialogsChain.tsx     |   6 -
 .../surface/SurfaceSideSheetAlwaysModal.tsx   |   1 -
 .../SurfaceSideSheetDismissToRemove.tsx       |   1 -
 .../surface/SurfaceSideSheetModalToWindow.tsx |   1 -
 m3-react/tests/M3Layers.e2e.tsx               | 195 ++++++++++++++++++
 m3-react/tests/M3SurfaceFocus.e2e.tsx         |   2 +-
 21 files changed, 451 insertions(+), 50 deletions(-)
 create mode 100644 m3-react/src/hooks/useLayerHost.ts
 create mode 100644 m3-react/storybook/examples/surface/SurfaceLayerStack.tsx
 create mode 100644 m3-react/tests/M3Layers.e2e.tsx

diff --git a/m3-react/src/components/dialog/M3Dialog.tsx b/m3-react/src/components/dialog/M3Dialog.tsx
index bceec4d..e45afc4 100644
--- a/m3-react/src/components/dialog/M3Dialog.tsx
+++ b/m3-react/src/components/dialog/M3Dialog.tsx
@@ -37,7 +37,6 @@ const DIALOG_MAX_WIDTH = 560
 const DIALOG_ROUNDING = 28
 const DIALOG_ENTRY_OFFSET_PX = 24
 const DIALOG_ELEVATION = 0
-const DIALOG_Z_INDEX = 1000
 const DIALOG_TRANSITION_MS = durations.medium2
 const DIALOG_TRANSITION_TIMING = easing.standard
 
@@ -157,7 +156,6 @@ export default defineComponent(function M3Dialog({
       maxWidth={fullscreen ? '100vw' : DIALOG_MAX_WIDTH}
       maxHeight={fullscreen ? '100vh' : null}
       rounding={fullscreen ? 0 : DIALOG_ROUNDING}
-      zIndex={DIALOG_Z_INDEX}
       elevation={DIALOG_ELEVATION}
       style={dialogStyle}
       className={toClassName(['m3-dialog', className])}
diff --git a/m3-react/src/components/menu/M3Menu.tsx b/m3-react/src/components/menu/M3Menu.tsx
index 1abd6b8..84c52fc 100644
--- a/m3-react/src/components/menu/M3Menu.tsx
+++ b/m3-react/src/components/menu/M3Menu.tsx
@@ -23,7 +23,7 @@ export default defineComponent(function M3Menu({
   placement = 'bottom',
   strategy = 'absolute',
   boundary = 'clippingAncestors',
-  container = 'body',
+  container,
   offsetMainAxis = 0,
   offsetCrossAxis = 0,
   overflow = ['flip', 'shift', 'hide'],
diff --git a/m3-react/src/components/navigation/M3Navigation.tsx b/m3-react/src/components/navigation/M3Navigation.tsx
index 71a2c27..8af33ea 100644
--- a/m3-react/src/components/navigation/M3Navigation.tsx
+++ b/m3-react/src/components/navigation/M3Navigation.tsx
@@ -34,7 +34,12 @@ import M3NavigationAppearance from '@/components/navigation/M3NavigationAppearan
 import defineComponent from '@/utils/component'
 import { defineSlot, distinct } from '@/utils/content'
 import { toClassName } from '@/utils/styling'
-import { useBreakpoint, useRecord, useWatch } from '@/hooks'
+import {
+  useBreakpoint,
+  useLayerHost,
+  useRecord,
+  useWatch,
+} from '@/hooks'
 
 import M3NavigationSection from './M3NavigationSection'
 
@@ -119,6 +124,7 @@ export default defineComponent(function M3Navigation({
   const modalExpanded = isModalExpansion(appearanceBase, expanded, expansion, breakpoint.ge('large'))
   const modalActive = isExpandableAppearance(appearanceBase)
     && (isModalExpansion(appearanceBase, expanded, expansion, breakpoint.ge('large')) || state.transitioning)
+  const layerHost = useLayerHost(modalActive)
 
   const railHidden = isHiddenRail(appearanceBase, expanded, collapse)
   const railLeaving = isHiddenRail(appearanceBase, expanded, collapse) && state.transitioning
@@ -188,14 +194,16 @@ export default defineComponent(function M3Navigation({
 
   useLayoutEffect(() => {
     const dialog = modalDialog.current
-    if (!modalActive || !dialog) return
+    if (!modalActive || !dialog || !layerHost) return
 
     return activateModalFocus({
       dialog,
-      exempt: () => [scrim.current],
+      layer: layerHost,
       onEscape: () => handlers.onToggle(false),
     })
-  }, [modalActive])
+  }, [modalActive, layerHost])
+
+  if (!layerHost) return null
 
   return createPortal(
     <>
@@ -257,7 +265,7 @@ export default defineComponent(function M3Navigation({
         </nav>
       </div>
     </>,
-    document.body
+    layerHost
   )
 }, {
   slots: { Header, Subheader, Top },
diff --git a/m3-react/src/components/popper/M3Popper.tsx b/m3-react/src/components/popper/M3Popper.tsx
index 762b103..70aec26 100644
--- a/m3-react/src/components/popper/M3Popper.tsx
+++ b/m3-react/src/components/popper/M3Popper.tsx
@@ -2,6 +2,12 @@ import type { CloserEvent } from '@modulify/m3-foundation/types/components/poppe
 import type { ComponentSetupContext } from '@/utils/component'
 import type { M3PopperExposed, M3PopperProps } from './types'
 
+import {
+  activatePopover,
+  mountPopoverHost,
+  raisePopover,
+  resolvePopoverContainer,
+} from '@modulify/m3-foundation/lib/layers'
 import Scheduler from '@modulify/m3-foundation/lib/Scheduler'
 
 import { computePosition } from '@modulify/m3-foundation/lib/popper/floating'
@@ -9,6 +15,7 @@ import { createPortal } from 'react-dom'
 import {
   useCallback,
   useEffect,
+  useLayoutEffect,
   useMemo,
   useRef,
 } from 'react'
@@ -91,8 +98,11 @@ export default defineComponent(function M3Popper({
   useWatch(onDispose, onDispose => handlers.onDispose = onDispose)
 
   const targetRef = useRef(target)
+  const containerRef = useRef(container)
+  containerRef.current = container
   const positionerRef = useRef<HTMLDivElement | null>(null)
   const popperRef = useRef<HTMLDivElement | null>(null)
+  const portalHost = useMemo(() => typeof document === 'undefined' ? null : document.createElement('div'), [])
 
   const applyAnimationSide = useCallback((side: 'top' | 'bottom' | 'left' | 'right') => {
     if (!popperRef.current) {
@@ -248,6 +258,10 @@ export default defineComponent(function M3Popper({
     }
 
     state.hiding = false
+    if (portalHost) {
+      mountPopoverHost(portalHost, targetRef.current, containerRef.current)
+      raisePopover(portalHost)
+    }
     state.attached = true
 
     scheduler.showing.schedule(doShow, immediately ? 0 : state.showDelay)
@@ -332,6 +346,7 @@ export default defineComponent(function M3Popper({
     hide(true)
 
     state.attached = false
+    portalHost?.remove()
 
     handlers.onDispose()
   }, [])
@@ -368,6 +383,21 @@ export default defineComponent(function M3Popper({
     }
   })
 
+  useEffect(() => {
+    if (!state.attached || !portalHost) {
+      portalHost?.remove()
+      return
+    }
+
+    const destination = resolvePopoverContainer(targetRef.current, container)
+    if (portalHost.parentElement !== destination) destination.append(portalHost)
+  }, [state.attached, target, container, portalHost])
+
+  useLayoutEffect(() => {
+    if (!state.shown || !portalHost) return
+    return activatePopover(portalHost, () => hide(true))
+  }, [state.shown, portalHost])
+
   useWatch(disabled, disabled => {
     if (disabled) {
       dispose()
@@ -419,7 +449,7 @@ export default defineComponent(function M3Popper({
     }
   }, [])
 
-  return state.attached ? createPortal(
+  return state.attached && portalHost ? createPortal(
     <div
       ref={positionerRef}
       className="m3-popper-positioner"
@@ -436,6 +466,6 @@ export default defineComponent(function M3Popper({
         {children}
       </div>
     </div>,
-    (typeof container === 'string' ? document.querySelector(container) : container) ?? document.body
+    portalHost
   ) : null
 })
diff --git a/m3-react/src/components/popper/hooks.ts b/m3-react/src/components/popper/hooks.ts
index c9f0a89..78725cf 100644
--- a/m3-react/src/components/popper/hooks.ts
+++ b/m3-react/src/components/popper/hooks.ts
@@ -30,7 +30,7 @@ export const useAutoAdjust = (
     if (targetRef.current && popperRef.current) {
       stop = autoUpdate(targetRef.current, popperRef.current, adjust, {
         animationFrame: true,
-        elementResize: true,
+        elementResize: typeof ResizeObserver !== 'undefined',
       })
     }
   }, off]
diff --git a/m3-react/src/components/search/M3Search.tsx b/m3-react/src/components/search/M3Search.tsx
index 1213454..9ca6e42 100644
--- a/m3-react/src/components/search/M3Search.tsx
+++ b/m3-react/src/components/search/M3Search.tsx
@@ -37,7 +37,7 @@ import { M3IconButton } from '@/components/icon-button'
 import defineComponent from '@/utils/component'
 import { defineSlot, distinct } from '@/utils/content'
 import { toClassName } from '@/utils/styling'
-import { useBreakpoint, useId } from '@/hooks'
+import { useBreakpoint, useId, useLayerHost } from '@/hooks'
 
 export interface SearchResultsContext {
   query: string;
@@ -120,13 +120,14 @@ export default defineComponent(function M3Search({
   const dialog = useRef<HTMLDivElement | null>(null)
   const input = useRef<HTMLInputElement | null>(null)
   const results = useRef<HTMLDivElement | null>(null)
-  const scrim = useRef<HTMLDivElement | null>(null)
   const callbacks = useRef({ onOpenChange, onQueryChange, onSubmit })
   callbacks.current = { onOpenChange, onQueryChange, onSubmit }
 
   const [position, setPosition] = useState<SearchDockedPosition>({ left: 12, top: 12, width: 360 })
   const [anchor, setAnchor] = useState<SearchAnchorRect>({ left: 12, top: 12, width: 360 })
   const [viewport, setViewport] = useState<SearchViewport>({ width: 384, height: 640 })
+  const [overlayMounted, setOverlayMounted] = useState(open)
+  const layerHost = useLayerHost(open || overlayMounted)
   const parsed = useMemo(() => distinct(children, {
     slots: { leading: Leading, trailing: Trailing, actions: Actions, results: Results },
   }), [children])
@@ -172,15 +173,19 @@ export default defineComponent(function M3Search({
   }, [open, resolvedLayout])
 
   useLayoutEffect(() => {
-    if (!open || !dialog.current) return
+    if (!open || !dialog.current || !layerHost) return
 
     const deactivate = activateModalFocus({
       dialog: dialog.current,
-      exempt: () => [scrim.current],
+      layer: layerHost,
       onEscape: () => callbacks.current.onOpenChange(false),
     })
     input.current?.focus()
     return deactivate
+  }, [open, layerHost])
+
+  useLayoutEffect(() => {
+    if (open) setOverlayMounted(true)
   }, [open])
 
   const handleSubmit = (event: FormEvent<HTMLFormElement>) => {
@@ -235,7 +240,7 @@ export default defineComponent(function M3Search({
         </div>
       </div>
 
-      {typeof document !== 'undefined' ? createPortal(
+      {layerHost ? createPortal(
         <CSSTransition
           nodeRef={overlay}
           in={open}
@@ -243,10 +248,11 @@ export default defineComponent(function M3Search({
           classNames="m3-search"
           mountOnEnter
           unmountOnExit
+          onExited={() => setOverlayMounted(false)}
         >
           <div ref={overlay} className="m3-search__overlay" aria-hidden={!open}>
             {resolvedLayout === 'docked' ? (
-              <div ref={scrim} className="m3-search__scrim" onClick={close} />
+              <div className="m3-search__scrim" onClick={close} />
             ) : null}
             <div
               ref={dialog}
@@ -321,7 +327,7 @@ export default defineComponent(function M3Search({
             </div>
           </div>
         </CSSTransition>,
-        document.body
+        layerHost
       ) : null}
     </>
   )
diff --git a/m3-react/src/components/side-sheet/M3SideSheet.tsx b/m3-react/src/components/side-sheet/M3SideSheet.tsx
index d41fb5d..f614483 100644
--- a/m3-react/src/components/side-sheet/M3SideSheet.tsx
+++ b/m3-react/src/components/side-sheet/M3SideSheet.tsx
@@ -52,7 +52,6 @@ const DOCKED_WIDTH = 256
 const MODAL_MIN_WIDTH = 320
 const MODAL_MAX_WIDTH = 400
 const MODAL_RADIUS = 16
-const SIDE_SHEET_Z_INDEX = 1000
 const SIDE_SHEET_TRANSITION_MS = durations['extra-long2']
 
 export default defineComponent(function M3SideSheet({
@@ -78,7 +77,6 @@ export default defineComponent(function M3SideSheet({
   transitionTiming,
   overflow = 'hidden',
   role = 'dialog',
-  zIndex = SIDE_SHEET_Z_INDEX,
   className = '',
   style,
   children = [],
@@ -147,7 +145,6 @@ export default defineComponent(function M3SideSheet({
       transitionMs={transitionMs}
       transitionTiming={transitionTiming}
       overflow={overflow}
-      zIndex={zIndex}
       elevation={elevation}
       variant={variant}
       style={style}
diff --git a/m3-react/src/components/snackbar/M3SnackbarHost.tsx b/m3-react/src/components/snackbar/M3SnackbarHost.tsx
index 5d1db79..d4ae20c 100644
--- a/m3-react/src/components/snackbar/M3SnackbarHost.tsx
+++ b/m3-react/src/components/snackbar/M3SnackbarHost.tsx
@@ -7,8 +7,18 @@ import type {
 } from './types'
 import type { SnackbarResult } from '@modulify/m3-foundation/types/components/snackbar'
 
+import { createPortal } from 'react-dom'
 import { isElement, isHTMLElement } from '@modulify/m3-foundation/lib/predicates'
-import { useEffect, useRef, useState } from 'react'
+import {
+  LAYER_DEACTIVATED_EVENT,
+  resolveFeedbackContainer,
+} from '@modulify/m3-foundation/lib/layers'
+import {
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from 'react'
 
 import defineComponent from '@/utils/component'
 import { toClassName } from '@/utils/styling'
@@ -23,6 +33,7 @@ interface Entry {
 
   trigger: HTMLElement | null;
   nextFocus: HTMLElement | null;
+  feedbackTarget: HTMLElement | null;
 
   remaining: number | null;
   startedAt: number;
@@ -73,6 +84,8 @@ export default defineComponent(function M3SnackbarHost({
 }: M3SnackbarHostProps, { expose }: ComponentSetupContext<SnackbarHostMethods>) {
   const [display, setDisplay] = useState<Display | null>(null)
   const [announcement, setAnnouncement] = useState('')
+  const [feedbackTarget, setFeedbackTarget] = useState<HTMLElement | null>(null)
+  const anchor = useRef<HTMLSpanElement | null>(null)
   const root = useRef<HTMLDivElement | null>(null)
 
   const active = useRef<Entry | null>(null)
@@ -82,6 +95,7 @@ export default defineComponent(function M3SnackbarHost({
   const timerRunning = useRef(false)
   const paused = useRef({ hover: false, focus: false })
   const disposed = useRef(false)
+  const detachOwner = useRef<() => void>(() => {})
 
   const durationTimeout = useTimeout(() => {
     timerRunning.current = false
@@ -129,8 +143,27 @@ export default defineComponent(function M3SnackbarHost({
   }
 
   const begin = (entry: Entry) => {
+    if (entry.feedbackTarget && !entry.feedbackTarget.closest('[data-m3-layer-active="true"]')) {
+      entry.resolve('disposed')
+      const next = queue.current.shift()
+      if (next) begin(next)
+      else {
+        setDisplay(null)
+        setAnnouncement('')
+      }
+      return
+    }
+
     active.current = entry
     paused.current = { hover: false, focus: false }
+    detachOwner.current()
+    const layer = entry.feedbackTarget?.closest<HTMLElement>('.m3-layer')
+    if (layer) {
+      const onDeactivate = () => finish('disposed')
+      layer.addEventListener(LAYER_DEACTIVATED_EVENT, onDeactivate)
+      detachOwner.current = () => layer.removeEventListener(LAYER_DEACTIVATED_EVENT, onDeactivate)
+    }
+    setFeedbackTarget(entry.feedbackTarget?.isConnected ? entry.feedbackTarget : null)
     setDisplay({ entry, leaving: false })
     setAnnouncement(entry.options.message)
     if (entry.remaining !== null) {
@@ -145,6 +178,8 @@ export default defineComponent(function M3SnackbarHost({
     if (!entry) return
     stopTimer()
     active.current = null
+    detachOwner.current()
+    detachOwner.current = () => {}
     leaving.current = entry
     entry.resolve(result)
     setDisplay({ entry, leaving: true })
@@ -166,6 +201,7 @@ export default defineComponent(function M3SnackbarHost({
       resolve,
       trigger,
       nextFocus: getNextFocusable(trigger),
+      feedbackTarget: resolveFeedbackContainer(trigger) ?? resolveFeedbackContainer(anchor.current),
       remaining: duration,
       startedAt: 0,
     }
@@ -211,6 +247,15 @@ export default defineComponent(function M3SnackbarHost({
 
   expose({ show, replace, dismiss: () => finish('dismiss'), clear, focus })
 
+  useLayoutEffect(() => {
+    const update = () => setFeedbackTarget(resolveFeedbackContainer(anchor.current))
+    const layer = anchor.current?.closest('.m3-layer')
+    const observer = layer ? new MutationObserver(update) : null
+    if (layer) observer?.observe(layer, { attributes: true, attributeFilter: ['data-m3-layer'] })
+    update()
+    return () => observer?.disconnect()
+  }, [])
+
   useEffect(() => {
     disposed.current = false
     const onKeyDown = (event: KeyboardEvent) => {
@@ -224,6 +269,7 @@ export default defineComponent(function M3SnackbarHost({
     return () => {
       document.removeEventListener('keydown', onKeyDown)
       disposed.current = true
+      detachOwner.current()
       queueMicrotask(() => {
         if (!disposed.current) return
         stopTimer()
@@ -239,7 +285,7 @@ export default defineComponent(function M3SnackbarHost({
   const options = display?.entry.options
   const closable = options?.closable ?? Boolean(display?.entry.action || display?.entry.remaining === null)
 
-  return (
+  const host = (
     <div
       ref={root}
       className={toClassName(['m3-snackbar-host', className])}
@@ -271,4 +317,9 @@ export default defineComponent(function M3SnackbarHost({
       )}
     </div>
   )
+
+  return <>
+    <span ref={anchor} hidden />
+    {feedbackTarget ? createPortal(host, feedbackTarget) : host}
+  </>
 })
diff --git a/m3-react/src/components/surface/M3Surface.tsx b/m3-react/src/components/surface/M3Surface.tsx
index e8203ec..9290794 100644
--- a/m3-react/src/components/surface/M3Surface.tsx
+++ b/m3-react/src/components/surface/M3Surface.tsx
@@ -14,6 +14,7 @@ import { useTransition } from 'react-transition-state'
 
 import { toClassName } from '@/utils/styling'
 import { useId } from '@/hooks'
+import { useLayerHost } from '@/hooks'
 
 import { getModalAnchorStyle } from './shared'
 import M3SurfacePanel from './M3SurfacePanel'
@@ -34,7 +35,6 @@ export interface M3SurfaceProps extends Omit<M3SurfacePanelOptions, 'onToggle'>
   insetRight?: SurfaceLength;
   insetBottom?: SurfaceLength;
   insetLeft?: SurfaceLength;
-  zIndex?: number;
   onToggle?: (shown: boolean) => void;
   onDismiss?: () => void;
 }
@@ -52,7 +52,6 @@ const M3Surface: FC<M3SurfaceProps> = ({
   insetBottom = 0,
   insetLeft = 0,
   transitionMs = 220,
-  zIndex = 400,
   role,
   'aria-modal': ariaModal,
   className = '',
@@ -63,8 +62,8 @@ const M3Surface: FC<M3SurfaceProps> = ({
   ...panelProps
 }) => {
   const isModal = mode === 'modal'
+  const layerHost = useLayerHost(isModal && String(ariaModal) !== 'false', teleportTo, isModal)
   const panel = useRef<M3SurfacePanelExposed | null>(null)
-  const scrimElement = useRef<HTMLDivElement | null>(null)
   const dismiss = useRef<() => void>(() => {})
   dismiss.current = () => {
     onToggle(false)
@@ -73,14 +72,14 @@ const M3Surface: FC<M3SurfaceProps> = ({
 
   useLayoutEffect(() => {
     const dialog = panel.current?.el
-    if (!isModal || !shown || String(ariaModal) === 'false' || !dialog) return
+    if (!isModal || !shown || String(ariaModal) === 'false' || !dialog || !layerHost) return
 
     return activateModalFocus({
       dialog,
-      exempt: () => [scrimElement.current],
+      layer: layerHost,
       onEscape: () => dismiss.current(),
     })
-  }, [isModal, shown, ariaModal, teleportTo, panelProps.tag])
+  }, [isModal, shown, ariaModal, layerHost, panelProps.tag])
 
   const resolvedScrimShown = scrimShown ?? shown
   const [modalTransition, toggleModalTransition, endModalTransition] = useTransition({
@@ -115,7 +114,7 @@ const M3Surface: FC<M3SurfaceProps> = ({
       style={{
         ...anchorStyle,
         position: isModal ? 'fixed' : 'relative',
-        zIndex: isModal ? zIndex : undefined,
+        zIndex: isModal ? 1 : undefined,
         display: shown ? undefined : 'none',
         ...style,
       }}
@@ -133,11 +132,7 @@ const M3Surface: FC<M3SurfaceProps> = ({
     return surfaceNode
   }
 
-  const portalTarget = typeof document === 'undefined'
-    ? null
-    : (teleportTo === 'body' ? document.body : (document.querySelector(teleportTo) || document.body))
-
-  if (!portalTarget) {
+  if (!layerHost) {
     return null
   }
 
@@ -149,9 +144,8 @@ const M3Surface: FC<M3SurfaceProps> = ({
     <>
       {scrim && modalTransition.isMounted ? (
         <div
-          ref={scrimElement}
           style={{
-            zIndex: zIndex - 1,
+            zIndex: 0,
           }}
           className={toClassName(['m3-surface__scrim', {
             'm3-transition-fade-enter': modalTransition.status === 'preEnter' || modalTransition.status === 'entering',
@@ -164,7 +158,7 @@ const M3Surface: FC<M3SurfaceProps> = ({
       ) : null}
       {surfaceNode}
     </>,
-    portalTarget
+    layerHost
   )
 }
 
diff --git a/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts b/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
index d5a5360..edac051 100644
--- a/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
+++ b/m3-react/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
@@ -53,7 +53,6 @@ type UseSurfaceSideSheetMorphResult = {
     roundingTopRight: number;
     roundingBottomRight: number;
     transitionMs: number;
-    zIndex: number;
     variant: ModalRole;
     elevation: number;
     overflow: 'auto';
@@ -276,7 +275,6 @@ export function useSurfaceSideSheetMorph(): UseSurfaceSideSheetMorphResult {
       roundingTopRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topRight,
       roundingBottomRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.bottomRight,
       transitionMs: modalTransitionMs,
-      zIndex: 520,
       variant: modalRole,
       elevation: modalElevation,
       overflow: MODAL_SIDE_SHEET_DESCRIPTOR.overflow,
diff --git a/m3-react/src/hooks/index.ts b/m3-react/src/hooks/index.ts
index 19fa061..b88a932 100644
--- a/m3-react/src/hooks/index.ts
+++ b/m3-react/src/hooks/index.ts
@@ -8,6 +8,7 @@ export { default as useFallback } from './useFallback'
 export { default as useFocusable } from './useFocusable'
 export { default as useId } from './useId'
 export { default as useInteractable } from './useInteractable'
+export { default as useLayerHost } from './useLayerHost'
 export { default as useMutationObserver } from './useMutationObserver'
 export { default as useRecord } from './useRecord'
 export { default as useResizeObserver } from './useResizeObserver'
diff --git a/m3-react/src/hooks/useLayerHost.ts b/m3-react/src/hooks/useLayerHost.ts
new file mode 100644
index 0000000..ac477ad
--- /dev/null
+++ b/m3-react/src/hooks/useLayerHost.ts
@@ -0,0 +1,25 @@
+import {
+  createLayerHost,
+  mountLayerHost,
+  setLayerModal,
+} from '@modulify/m3-foundation/lib/layers'
+import { useLayoutEffect, useMemo } from 'react'
+
+export default function useLayerHost(modal: boolean, container: string = 'body', enabled = true): HTMLElement | null {
+  const host = useMemo(() => enabled && typeof document !== 'undefined'
+    ? createLayerHost(document)
+    : null, [enabled])
+
+  useLayoutEffect(() => {
+    if (!host) return
+    const target = document.querySelector<HTMLElement>(container) ?? document.body
+    mountLayerHost(host, target)
+    return () => host.remove()
+  }, [host, container])
+
+  useLayoutEffect(() => {
+    if (host) setLayerModal(host, modal)
+  }, [host, modal])
+
+  return host
+}
diff --git a/m3-react/storybook/components/M3Surface.mdx b/m3-react/storybook/components/M3Surface.mdx
index 58ca279..a6874c7 100644
--- a/m3-react/storybook/components/M3Surface.mdx
+++ b/m3-react/storybook/components/M3Surface.mdx
@@ -37,6 +37,14 @@ Use `variant` when the surface role is explicit. Use `auto` only when you intent
 
 The component does not prescribe content anatomy. Dialogs, side sheets, and custom orchestrated surfaces build that structure on top.
 
+### UI layers
+
+Each open modal surface owns one isolated layer: scrim and content at local levels `0` and `1`, snackbar at `50`, and popovers at `100`. The page uses `10` for floating UI and `100` for popovers; every modal layer uses `1000`. Modal layers share that value and follow opening order in the DOM. Search and modal navigation use the same stack. Escape closes the top popover before the top modal, and focus is confined to the top layer.
+
+Popovers choose their layer from the trigger. Keep a custom `container` inside the same layer when overriding the default portal. A snackbar follows the layer of the focused trigger when `show()` is called; a host mounted inside a modal also defaults to that modal. A later modal covers earlier snackbar content. `M3Surface` no longer accepts a numeric `zIndex`: open order determines the modal order.
+
+Closing a modal closes its popovers and disposes snackbar messages owned by that modal. The snackbar promise resolves to `disposed` in that case.
+
 ## Story guide
 
 - [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
@@ -51,6 +59,8 @@ The component does not prescribe content anatomy. Dialogs, side sheets, and cust
   Morphs a right-edge modal sheet into a centered dialog window while keeping one modal surface vocabulary.
 - [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
   Demonstrates layered modal surfaces, topmost scrim ownership, and per-layer enter/exit motion.
+- [Layer Stack](?path=/story/components-m3surface--layer-stack)
+  Lets you open a modal menu, snackbar, and another modal to inspect their order and Escape behavior.
 - [Workspace Modal Dialog](?path=/story/components-m3surface--workspace-modal-dialog)
   Shows a centered blocking decision surface in a realistic workspace scene without morph choreography.
 - [Inspector Side Sheet](?path=/story/components-m3surface--inspector-side-sheet)
@@ -131,6 +141,14 @@ The `Inspector Side Sheet` story shows this anatomy with the standard `m3-side-s
 
 `M3Surface` управляет переносом модального элемента, затемнением, позиционированием, скруглением, размерами и отступами при morph-переходах. Структуру содержимого задают построенные поверх него диалоги, side sheet и пользовательские поверхности.
 
+### Слои интерфейса
+
+Каждая открытая модальная поверхность владеет изолированным слоем: scrim и содержимое имеют локальные уровни `0` и `1`, snackbar — `50`, popover — `100`. На странице floating UI использует `10`, а popover — `100`; каждый модальный слой использует `1000`. Одинаковые значения у модальных слоёв сочетаются с DOM-порядком открытия. Search и модальная навигация входят в тот же стек. Escape сначала закрывает верхний popover, затем верхний модал; фокус остаётся в верхнем слое.
+
+Popover определяет владельца по кнопке вызова. При явном `container` размещайте его внутри того же слоя. Snackbar следует слою элемента в фокусе при вызове `show()`; host внутри модала по умолчанию принадлежит этому модалу. Позднее открытый модал перекрывает прежний snackbar. Числовой `zIndex` больше не является prop `M3Surface`: порядок модалов задаётся открытием.
+
+При закрытии модала его popover закрываются, а принадлежащие ему сообщения snackbar завершаются. Promise такого snackbar возвращает `disposed`.
+
 ## Примеры в Storybook
 
 - [Закреплённая панель в модальную](?path=/story/components-m3surface--side-sheet-docked-to-modal)
@@ -139,6 +157,7 @@ The `Inspector Side Sheet` story shows this anatomy with the standard `m3-side-s
 - [Всегда модальная панель](?path=/story/components-m3surface--side-sheet-always-modal-toggle)
 - [Модальная панель в окно](?path=/story/components-m3surface--side-sheet-modal-to-window)
 - [Цепочка вложенных диалогов](?path=/story/components-m3surface--nested-dialogs-chain)
+- [Стек слоёв](?path=/story/components-m3surface--layer-stack)
 - [Модальный диалог рабочего пространства](?path=/story/components-m3surface--workspace-modal-dialog)
 - [Панель инспектора](?path=/story/components-m3surface--inspector-side-sheet)
 
diff --git a/m3-react/storybook/components/M3Surface.stories.tsx b/m3-react/storybook/components/M3Surface.stories.tsx
index f4a16d3..6ec8057 100644
--- a/m3-react/storybook/components/M3Surface.stories.tsx
+++ b/m3-react/storybook/components/M3Surface.stories.tsx
@@ -6,6 +6,7 @@ import { M3Surface } from '@/components/surface'
 
 import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph'
 import SurfaceInspectorSheet from '../examples/surface/SurfaceInspectorSheet'
+import SurfaceLayerStack from '../examples/surface/SurfaceLayerStack'
 import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain'
 import SurfaceSideSheetAlwaysModal from '../examples/surface/SurfaceSideSheetAlwaysModal'
 import SurfaceSideSheetDismissToRemove from '../examples/surface/SurfaceSideSheetDismissToRemove'
@@ -50,6 +51,10 @@ export const NestedDialogsChain: Story = {
   render: (_args, { globals }) => <SurfaceNestedDialogsChain locale={globals.locale} />,
 }
 
+export const LayerStack: Story = {
+  render: (_args, { globals }) => <SurfaceLayerStack locale={globals.locale} />,
+}
+
 export const WorkspaceModalDialog: Story = {
   render: (_args, { globals }) => <SurfaceWorkspaceDialog locale={globals.locale} />,
 }
diff --git a/m3-react/storybook/examples/surface/SurfaceLayerStack.tsx b/m3-react/storybook/examples/surface/SurfaceLayerStack.tsx
new file mode 100644
index 0000000..14ad963
--- /dev/null
+++ b/m3-react/storybook/examples/surface/SurfaceLayerStack.tsx
@@ -0,0 +1,83 @@
+import type { FC } from 'react'
+import type { SnackbarHostMethods } from '@/components/snackbar'
+import type { StorybookLocale } from '../../i18n'
+
+import { useRef, useState } from 'react'
+
+import { M3Popper } from '@/components/popper'
+import { M3SnackbarHost } from '@/components/snackbar'
+import { M3Surface } from '@/components/surface'
+
+const copy = {
+  'en-US': {
+    title: 'UI layer stack',
+    description: 'Open the first dialog, then its menu, snackbar, and second dialog. Escape closes the top interaction first.',
+    open: 'Open first dialog',
+    first: 'First dialog',
+    second: 'Second dialog',
+    menu: 'Open menu',
+    menuAction: 'Menu action',
+    snackbar: 'Show snackbar',
+    snackbarMessage: 'Saved in the first dialog',
+    next: 'Open second dialog',
+    close: 'Close',
+  },
+  'ru-RU': {
+    title: 'Стек слоёв интерфейса',
+    description: 'Откройте первый диалог, затем его меню, snackbar и второй диалог. Escape закрывает верхнее взаимодействие первым.',
+    open: 'Открыть первый диалог',
+    first: 'Первый диалог',
+    second: 'Второй диалог',
+    menu: 'Открыть меню',
+    menuAction: 'Пункт меню',
+    snackbar: 'Показать snackbar',
+    snackbarMessage: 'Сохранено в первом диалоге',
+    next: 'Открыть второй диалог',
+    close: 'Закрыть',
+  },
+}
+
+const SurfaceLayerStack: FC<{ locale: StorybookLocale }> = ({ locale }) => {
+  const text = copy[locale]
+  const [first, setFirst] = useState(false)
+  const [second, setSecond] = useState(false)
+  const [menuTarget, setMenuTarget] = useState<HTMLButtonElement | null>(null)
+  const snackbar = useRef<SnackbarHostMethods | null>(null)
+
+  const closeFirst = () => {
+    setSecond(false)
+    setFirst(false)
+    snackbar.current?.dismiss()
+  }
+
+  const dialogStyle = { display: 'grid', alignContent: 'start', gap: 16, padding: 24 }
+
+  return <main style={{ minHeight: '100vh', padding: 32, background: 'var(--m3-sys-surface)' }}>
+    <h1>{text.title}</h1>
+    <p>{text.description}</p>
+    <button onClick={() => setFirst(true)}>{text.open}</button>
+    <M3SnackbarHost ref={snackbar} />
+
+    <M3Surface mode="modal" shown={first} anchor="center" width={360} height={280} rounding={28} variant="surface-container-high" onToggle={shown => { if (!shown) closeFirst() }}>
+      <div style={dialogStyle}>
+        <h2>{text.first}</h2>
+        <button ref={setMenuTarget}>{text.menu}</button>
+        <M3Popper target={menuTarget} detachTimeout={null} animated>
+          <button>{text.menuAction}</button>
+        </M3Popper>
+        <button onClick={() => { void snackbar.current?.show({ message: text.snackbarMessage, duration: null }) }}>{text.snackbar}</button>
+        <button onClick={() => setSecond(true)}>{text.next}</button>
+        <button onClick={closeFirst}>{text.close}</button>
+      </div>
+    </M3Surface>
+
+    <M3Surface mode="modal" shown={second} anchor="center" width={320} height={180} rounding={28} variant="surface-container-high" onToggle={setSecond}>
+      <div style={dialogStyle}>
+        <h2>{text.second}</h2>
+        <button onClick={() => setSecond(false)}>{text.close}</button>
+      </div>
+    </M3Surface>
+  </main>
+}
+
+export default SurfaceLayerStack
diff --git a/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx b/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
index 824071d..63d27d1 100644
--- a/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceNestedDialogsChain.tsx
@@ -20,8 +20,6 @@ import { localize } from '../../i18n'
 const DIALOG_TRANSITION_MS = durations.medium2
 const DIALOG_TRANSITION_EASING = easing.standard
 const DIALOG_ENTRY_OFFSET_PX = 24
-const DIALOG_Z_INDEX_BASE = 560
-const DIALOG_Z_INDEX_STEP = 40
 
 type NavTab = 'inbox' | 'boards' | 'archive' | 'lab'
 
@@ -86,8 +84,6 @@ const SurfaceNestedDialogsChain: FC<{ locale: StorybookLocale }> = ({ locale })
     return isTopDialog(level) ? 'modal' : 'standard'
   }
 
-  const dialogZIndex = (level: number) => DIALOG_Z_INDEX_BASE + (level * DIALOG_Z_INDEX_STEP)
-
   const dialogElevation = (level: number) => Math.min(5, 2 + level)
 
   const dialogInlineStyle = (level: number): CSSProperties => {
@@ -97,7 +93,6 @@ const SurfaceNestedDialogsChain: FC<{ locale: StorybookLocale }> = ({ locale })
       position: 'fixed',
       top: '50%',
       left: '50%',
-      zIndex: dialogZIndex(level),
       opacity: visible ? 1 : 0,
       transform: visible
         ? 'translate(-50%, -50%)'
@@ -302,7 +297,6 @@ const SurfaceNestedDialogsChain: FC<{ locale: StorybookLocale }> = ({ locale })
             rounding={dialog.rounding}
             transitionMs={DIALOG_TRANSITION_MS}
             transitionTiming={DIALOG_TRANSITION_EASING}
-            zIndex={dialogZIndex(level)}
             variant="surface-container-highest"
             elevation={dialogElevation(level)}
             overflow="visible"
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
index 121bd3a..510bdc6 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetAlwaysModal.tsx
@@ -304,7 +304,6 @@ const SurfaceSideSheetAlwaysModal: FC<{ locale: StorybookLocale }> = ({ locale }
                 roundingBottomRight={0}
                 transitionMs={PANEL_TRANSITION_MS}
                 transitionTiming={PANEL_TRANSITION_EASING}
-                zIndex={520}
                 variant="surface-container-high"
                 elevation={modalElevation}
                 overflow="auto"
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
index 944024f..9b6a355 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetDismissToRemove.tsx
@@ -406,7 +406,6 @@ const SurfaceSideSheetDismissToRemove: FC<{ locale: StorybookLocale }> = ({ loca
                 roundingBottomRight={0}
                 transitionMs={PANEL_TRANSITION_MS}
                 transitionTiming={PANEL_TRANSITION_EASING}
-                zIndex={520}
                 variant={modalRole}
                 elevation={modalElevation}
                 overflow="auto"
diff --git a/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx b/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
index c36df28..eba1d4a 100644
--- a/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
+++ b/m3-react/storybook/examples/surface/SurfaceSideSheetModalToWindow.tsx
@@ -433,7 +433,6 @@ const SurfaceSideSheetModalToWindow: FC<{ locale: StorybookLocale }> = ({ locale
                 roundingBottomRight={panelRoundingBottomRight}
                 transitionMs={panelTransitionMs}
                 transitionTiming={panelTransitionTiming}
-                zIndex={520}
                 variant={panelSurfaceRole}
                 elevation={panelElevation}
                 style={panelInlineStyle}
diff --git a/m3-react/tests/M3Layers.e2e.tsx b/m3-react/tests/M3Layers.e2e.tsx
new file mode 100644
index 0000000..3731600
--- /dev/null
+++ b/m3-react/tests/M3Layers.e2e.tsx
@@ -0,0 +1,195 @@
+import type { M3PopperExposed } from '@/components/popper'
+import type { SnackbarHostMethods } from '@/components/snackbar'
+
+import { act } from '@testing-library/react'
+import { createRef } from 'react'
+import { fireEvent, render } from '@testing-library/react'
+import { useState } from 'react'
+import { waitFor } from '@testing-library/react'
+
+import { M3Popper } from '@/components/popper'
+import { M3Search } from '@/components/search'
+import { M3SnackbarHost } from '@/components/snackbar'
+import { M3Surface } from '@/components/surface'
+
+test('a popover stays in its modal layer and handles Escape before the modal', async () => {
+  const onToggle = vi.fn()
+
+  function Scenario() {
+    const [target, setTarget] = useState<HTMLButtonElement | null>(null)
+
+    return <M3Surface mode="modal" shown onToggle={onToggle}>
+      <button ref={setTarget}>Open menu</button>
+      <M3Popper target={target} detachTimeout={null}>
+        <button>Menu action</button>
+      </M3Popper>
+    </M3Surface>
+  }
+
+  const view = render(<Scenario />)
+  try {
+    const trigger = document.querySelector<HTMLButtonElement>('.m3-surface button')!
+    fireEvent.click(trigger)
+    await waitFor(() => expect(document.querySelector('.m3-popper_shown')).not.toBeNull())
+
+    const layer = trigger.closest<HTMLElement>('.m3-layer')!
+    const popper = document.querySelector<HTMLElement>('.m3-popper_shown')!
+    expect(layer.querySelector('.m3-layer__popovers')!.contains(popper)).toBe(true)
+    expect(getComputedStyle(layer).zIndex).toBe('1000')
+    expect(getComputedStyle(layer.querySelector<HTMLElement>('.m3-layer__popovers')!).zIndex).toBe('100')
+    expect(popper.inert).toBe(false)
+
+    popper.querySelector<HTMLButtonElement>('button')!.focus()
+    act(() => document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true, bubbles: true, cancelable: true })))
+    expect(document.activeElement).toBe(trigger)
+
+    act(() => document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })))
+    await waitFor(() => expect(document.querySelector('.m3-popper_shown')).toBeNull())
+    expect(onToggle).not.toHaveBeenCalled()
+
+    act(() => document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })))
+    expect(onToggle).toHaveBeenCalledWith(false)
+  } finally {
+    view.unmount()
+  }
+})
+
+test('a snackbar opened from a modal belongs to that layer', async () => {
+  const host = createRef<SnackbarHostMethods>()
+  const scene = (shown: boolean) => <>
+    <M3SnackbarHost ref={host} />
+    <M3Surface mode="modal" shown={shown}><button>Notify</button></M3Surface>
+  </>
+  const view = render(scene(true))
+
+  try {
+    const trigger = document.querySelector<HTMLButtonElement>('.m3-surface button')!
+    trigger.focus()
+    let result: Promise<string> | undefined
+    await act(async () => { result = host.current?.show({ message: 'Layer notice', duration: null }) })
+
+    const layer = trigger.closest<HTMLElement>('.m3-layer')!
+    const feedback = layer.querySelector<HTMLElement>('.m3-layer__feedback')!
+    expect(feedback.querySelector('.m3-snackbar-host')).not.toBeNull()
+    expect(feedback.querySelector('.m3-snackbar')).not.toBeNull()
+    expect(getComputedStyle(feedback).zIndex).toBe('50')
+
+    const close = feedback.querySelector<HTMLButtonElement>('.m3-snackbar__close')!
+    close.focus()
+    expect(document.activeElement).toBe(close)
+
+    view.rerender(scene(false))
+    expect(await result).toBe('disposed')
+  } finally {
+    view.unmount()
+  }
+})
+
+test('a reopened modal moves above the previously opened modal', async () => {
+  const surfaces = (firstShown: boolean, secondShown: boolean) => <>
+    <M3Surface mode="modal" shown={firstShown}><button>First</button></M3Surface>
+    <M3Surface mode="modal" shown={secondShown}><button>Second</button></M3Surface>
+  </>
+
+  const view = render(surfaces(true, true))
+  try {
+    const first = [...document.querySelectorAll<HTMLButtonElement>('.m3-surface button')].find(button => button.textContent === 'First')!
+    const second = [...document.querySelectorAll<HTMLButtonElement>('.m3-surface button')].find(button => button.textContent === 'Second')!
+    const firstLayer = first.closest<HTMLElement>('.m3-layer')!
+    const secondLayer = second.closest<HTMLElement>('.m3-layer')!
+
+    expect(firstLayer.nextElementSibling).toBe(secondLayer)
+    expect(firstLayer.inert).toBe(true)
+    expect(document.activeElement).toBe(second)
+
+    view.rerender(surfaces(false, true))
+    view.rerender(surfaces(true, true))
+    await waitFor(() => expect(secondLayer.nextElementSibling).toBe(firstLayer))
+    expect(secondLayer.inert).toBe(true)
+    expect(firstLayer.inert).toBe(false)
+    expect(document.activeElement).toBe(first)
+  } finally {
+    view.unmount()
+  }
+})
+
+test('search and dialog follow activation order instead of component type', async () => {
+  const scene = (searchOpen: boolean, dialogShown: boolean) => <>
+    <M3Search query="" label="Search" status="" open={searchOpen} layout="docked" onQueryChange={() => {}} onOpenChange={() => {}} />
+    <M3Surface mode="modal" shown={dialogShown}><button>Dialog action</button></M3Surface>
+  </>
+
+  const view = render(scene(true, false))
+  try {
+    const search = document.querySelector<HTMLElement>('.m3-search__view')!
+    const searchLayer = search.closest<HTMLElement>('.m3-layer')!
+    view.rerender(scene(true, true))
+    const dialog = document.querySelector<HTMLElement>('.m3-surface')!
+    const dialogLayer = dialog.closest<HTMLElement>('.m3-layer')!
+    expect(searchLayer.nextElementSibling).toBe(dialogLayer)
+    expect(searchLayer.inert).toBe(true)
+
+    view.rerender(scene(false, true))
+    view.rerender(scene(true, true))
+    await waitFor(() => expect(dialogLayer.nextElementSibling).toBe(searchLayer))
+    expect(dialogLayer.inert).toBe(true)
+    expect(searchLayer.inert).toBe(false)
+  } finally {
+    view.unmount()
+  }
+})
+
+test('showing an already open popover raises it visually and for Escape', async () => {
+  const firstTarget = document.createElement('button')
+  const secondTarget = document.createElement('button')
+  document.body.append(firstTarget, secondTarget)
+  const first = createRef<M3PopperExposed>()
+  const second = createRef<M3PopperExposed>()
+  const view = render(<>
+    <M3Popper ref={first} target={firstTarget} targetTriggers={[]} detachTimeout={null}><button>First menu</button></M3Popper>
+    <M3Popper ref={second} target={secondTarget} targetTriggers={[]} detachTimeout={null}><button>Second menu</button></M3Popper>
+  </>)
+
+  try {
+    act(() => { first.current?.show(true); second.current?.show(true) })
+    await waitFor(() => expect(document.querySelectorAll('.m3-popper_shown').length).toBe(2))
+    const poppers = [...document.querySelectorAll<HTMLElement>('.m3-popper_shown')]
+    const firstHost = poppers.find(popper => popper.textContent === 'First menu')!.parentElement!.parentElement!
+    const secondHost = poppers.find(popper => popper.textContent === 'Second menu')!.parentElement!.parentElement!
+
+    act(() => first.current?.show(true))
+    expect(secondHost.nextElementSibling).toBe(firstHost)
+
+    act(() => document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true })))
+    await waitFor(() => expect(firstHost.querySelector('.m3-popper_shown')).toBeNull())
+    expect(secondHost.querySelector('.m3-popper_shown')).not.toBeNull()
+  } finally {
+    view.unmount()
+    firstTarget.remove()
+    secondTarget.remove()
+  }
+})
+
+test('a page popover becomes inert beneath a newly opened modal', async () => {
+  const target = document.createElement('button')
+  document.body.append(target)
+  const scene = (modalShown: boolean) => <>
+    <M3Popper target={target} overflow={[]} detachTimeout={null} shown><button>Page menu</button></M3Popper>
+    <M3Surface mode="modal" shown={modalShown}><button>Modal action</button></M3Surface>
+  </>
+  const view = render(scene(false))
+
+  try {
+    await waitFor(() => expect(document.querySelector('.m3-popper_shown')).not.toBeNull())
+    const popperHost = document.querySelector<HTMLElement>('.m3-popper_shown')!.parentElement!.parentElement!
+    expect(popperHost.parentElement).toBe(document.body)
+
+    view.rerender(scene(true))
+    await waitFor(() => expect(popperHost.inert).toBe(true))
+    const modalLayer = document.querySelector<HTMLElement>('.m3-layer[data-m3-layer="modal"]')!
+    expect(popperHost.nextElementSibling).toBe(modalLayer)
+  } finally {
+    view.unmount()
+    target.remove()
+  }
+})
diff --git a/m3-react/tests/M3SurfaceFocus.e2e.tsx b/m3-react/tests/M3SurfaceFocus.e2e.tsx
index 2246475..4f925db 100644
--- a/m3-react/tests/M3SurfaceFocus.e2e.tsx
+++ b/m3-react/tests/M3SurfaceFocus.e2e.tsx
@@ -80,7 +80,7 @@ test('closing a nested modal restores focus to the modal below it', async () =>
     view.rerender(surfaces(true))
     const upper = [...document.querySelectorAll<HTMLButtonElement>('.m3-surface button')].at(-1)!
     expect(document.activeElement).toBe(upper)
-    expect(lower.closest<HTMLElement>('.m3-surface')!.inert).toBe(true)
+    expect(lower.closest<HTMLElement>('.m3-layer')!.inert).toBe(true)
 
     document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }))
     expect(topToggle).toHaveBeenCalledWith(false)

From 37fda04269711436ff39c79d5b9753d3b2645de8 Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Mon, 19 Oct 2026 12:22:10 +0400
Subject: [PATCH 17/20] feat(m3-vue)!: Components were moved into shared UI
 layers

Modal surfaces own their popovers and feedback. Layer stacking and dismissal are covered by Storybook examples and browser tests.

BREAKING CHANGE: M3Surface.zIndex was removed; modal stacking now follows layer activation order.
---
 m3-vue/src/components/dialog/M3Dialog.vue     |   2 -
 m3-vue/src/components/menu/M3Menu.vue         |   2 +-
 .../components/navigation/M3Navigation.vue    |  10 +-
 m3-vue/src/components/popper/M3Popper.vue     |  30 +-
 m3-vue/src/components/popper/floating.ts      |   4 +-
 .../components/rich-tooltip/M3RichTooltip.vue |   2 +-
 m3-vue/src/components/search/M3Search.vue     |  19 +-
 .../src/components/side-sheet/M3SideSheet.vue |   2 -
 .../components/snackbar/M3SnackbarHost.vue    | 107 +++++---
 m3-vue/src/components/surface/M3Surface.vue   |  26 +-
 .../orchestration/useSurfaceSideSheetMorph.ts |   1 -
 m3-vue/src/composables/index.ts               |   1 +
 m3-vue/src/composables/layers.ts              |  33 +++
 m3-vue/storybook/components/M3Surface.mdx     |  19 ++
 .../storybook/components/M3Surface.stories.ts |   5 +
 .../examples/surface/SurfaceLayerStack.vue    | 130 +++++++++
 .../surface/SurfaceNestedDialogsChain.vue     |   8 -
 m3-vue/tests/M3Layers.e2e.ts                  | 257 ++++++++++++++++++
 m3-vue/tests/M3SurfaceFocus.e2e.ts            |   2 +-
 19 files changed, 580 insertions(+), 80 deletions(-)
 create mode 100644 m3-vue/src/composables/layers.ts
 create mode 100644 m3-vue/storybook/examples/surface/SurfaceLayerStack.vue
 create mode 100644 m3-vue/tests/M3Layers.e2e.ts

diff --git a/m3-vue/src/components/dialog/M3Dialog.vue b/m3-vue/src/components/dialog/M3Dialog.vue
index 2654c53..baa7819 100644
--- a/m3-vue/src/components/dialog/M3Dialog.vue
+++ b/m3-vue/src/components/dialog/M3Dialog.vue
@@ -15,7 +15,6 @@
         :max-width="fullscreen ? '100vw' : DIALOG_MAX_WIDTH"
         :max-height="fullscreen ? '100vh' : null"
         :rounding="fullscreen ? 0 : DIALOG_ROUNDING"
-        :z-index="DIALOG_Z_INDEX"
         :elevation="DIALOG_ELEVATION"
         :style="dialogStyle"
         tag="section"
@@ -78,7 +77,6 @@ const DIALOG_MAX_WIDTH = 560
 const DIALOG_ROUNDING = 28
 const DIALOG_ENTRY_OFFSET_PX = 24
 const DIALOG_ELEVATION = 0
-const DIALOG_Z_INDEX = 1000
 const DIALOG_TRANSITION_MS = durations.medium2
 const DIALOG_TRANSITION_TIMING = easing.standard
 
diff --git a/m3-vue/src/components/menu/M3Menu.vue b/m3-vue/src/components/menu/M3Menu.vue
index effef53..9b4ab07 100644
--- a/m3-vue/src/components/menu/M3Menu.vue
+++ b/m3-vue/src/components/menu/M3Menu.vue
@@ -80,7 +80,7 @@ defineProps({
   container: {
     type: null as unknown as PropType<string | HTMLElement>,
     validator: Or(isString, isHTMLElement) as (value: unknown) => boolean,
-    default: 'body',
+    default: undefined,
   },
 
   offsetMainAxis: {
diff --git a/m3-vue/src/components/navigation/M3Navigation.vue b/m3-vue/src/components/navigation/M3Navigation.vue
index a582c6e..714a7a0 100644
--- a/m3-vue/src/components/navigation/M3Navigation.vue
+++ b/m3-vue/src/components/navigation/M3Navigation.vue
@@ -1,5 +1,5 @@
 <template>
-    <Teleport to="body">
+    <Teleport v-if="layerReady" :to="layerHost">
         <Transition name="m3-transition-fade" @after-leave="transitioning = false">
             <div
                 v-show="modalExpanded"
@@ -82,6 +82,7 @@ import { resolveNavigationAppearance } from '@modulify/m3-foundation/lib/navigat
 import { useAttrs, watch } from 'vue'
 
 import { useBreakpoint } from '@/composables/breakpoint'
+import { useLayerHost } from '@/composables/layers'
 
 import M3NavigationSection from './M3NavigationSection.vue'
 
@@ -141,6 +142,7 @@ const modalDialog = ref<HTMLElement | null>(null)
 const modalExpanded = computed(() => isModalExpansion(appearanceBase.value, props.expanded, props.expansion, breakpoint.value.ge('large')))
 const modalActive = computed(() => isExpandableAppearance(appearanceBase.value)
   && (isModalExpansion(appearanceBase.value, props.expanded, props.expansion, breakpoint.value.ge('large')) || transitioning.value))
+const { host: layerHost, ready: layerReady } = useLayerHost(() => modalActive.value)
 const modalLabel = computed(() => typeof attrs['aria-label'] === 'string' ? attrs['aria-label'] : 'Navigation')
 
 const railHidden = computed(() => isHiddenRail(appearanceBase.value, props.expanded, props.collapse))
@@ -169,12 +171,12 @@ watch([appearanceBase, () => props.expanded], ([appearance, expanded], previous)
   if (isBarAppearance(appearance) && expanded) emit('update:expanded', false)
 }, { immediate: true })
 
-watch([modalDialog, modalActive], ([dialog, active], _, onCleanup) => {
-  if (!dialog || !active) return
+watch([modalDialog, modalActive, layerReady], ([dialog, active, ready], _, onCleanup) => {
+  if (!dialog || !active || !ready || !layerHost) return
 
   onCleanup(activateModalFocus({
     dialog,
-    exempt: () => [scrim.value],
+    layer: layerHost,
     onEscape: () => emit('update:expanded', false),
   }))
 }, { immediate: true, flush: 'post' })
diff --git a/m3-vue/src/components/popper/M3Popper.vue b/m3-vue/src/components/popper/M3Popper.vue
index c2d3468..bfe3197 100644
--- a/m3-vue/src/components/popper/M3Popper.vue
+++ b/m3-vue/src/components/popper/M3Popper.vue
@@ -1,7 +1,7 @@
 <template>
     <Teleport
-        v-if="state.attached"
-        :to="container"
+        v-if="state.attached && portalHost"
+        :to="portalHost"
     >
         <div
             ref="positioner"
@@ -36,7 +36,13 @@ import type {
   TriggerSchema,
 } from '@modulify/m3-foundation/types/components/popper'
 
+import { activatePopover } from '@modulify/m3-foundation/lib/layers'
 import { Listener } from '@modulify/m3-foundation/lib/popper'
+import {
+  mountPopoverHost,
+  raisePopover,
+  resolvePopoverContainer,
+} from '@modulify/m3-foundation/lib/layers'
 import Scheduler from '@modulify/m3-foundation/lib/Scheduler'
 
 import { computed } from 'vue'
@@ -115,7 +121,7 @@ const props = defineProps({
   container: {
     type: null as unknown as PropType<string | HTMLElement>,
     validator: Or(isString, isHTMLElement) as (value: unknown) => boolean,
-    default: 'body',
+    default: undefined,
   },
 
   offsetMainAxis: {
@@ -173,6 +179,7 @@ const emit = defineEmits([
 const target = computed(() => typeof props.target === 'function' ? props.target() : props.target?.value)
 const positioner = ref<HTMLElement | null>(null)
 const popper = ref<HTMLElement | null>(null)
+const portalHost = typeof document === 'undefined' ? null : document.createElement('div')
 
 const positioning = computed(() => ({
   placement: props.placement,
@@ -274,7 +281,10 @@ const globalTouchFrame = useAnimationFrame()
 const showingTimeout = useTimeout(() => state.showing = false, 0)
 const touchedTimeout = useTimeout(() => state.touched = false, 300)
 
-const detach = () => state.attached = false
+const detach = () => {
+  state.attached = false
+  portalHost?.remove()
+}
 
 const doShow = () => {
   detachScheduler.abort()
@@ -317,6 +327,10 @@ const show = (immediately = false) => {
   }
 
   state.hiding = false
+  if (portalHost) {
+    mountPopoverHost(portalHost, target.value ?? null, props.container)
+    raisePopover(portalHost)
+  }
   state.attached = true
 
   showingScheduler.schedule(doShow, immediately ? 0 : delay.value.show)
@@ -424,6 +438,14 @@ const dispose = () => {
 }
 
 watch(() => props.shown, shown => shown ? show() : hide())
+watch(() => state.shown, (shown, _, onCleanup) => {
+  if (shown && portalHost) onCleanup(activatePopover(portalHost, () => hide(true)))
+})
+watch([target, () => props.container], ([element, container]) => {
+  if (!state.attached || !portalHost) return
+  const destination = resolvePopoverContainer(element ?? null, container)
+  if (portalHost.parentElement !== destination) destination.append(portalHost)
+})
 watch(() => target.value, async (newTarget, oldTarget) => {
   if (newTarget !== oldTarget) {
     targetListener.target = newTarget
diff --git a/m3-vue/src/components/popper/floating.ts b/m3-vue/src/components/popper/floating.ts
index eeafa72..91bcb26 100644
--- a/m3-vue/src/components/popper/floating.ts
+++ b/m3-vue/src/components/popper/floating.ts
@@ -23,10 +23,10 @@ export const useAutoUpdate = (
       if (target.value && popper.value) {
         stop = autoUpdate(target.value, popper.value, adjust, {
           animationFrame: true,
-          elementResize: true,
+          elementResize: typeof ResizeObserver !== 'undefined',
         })
       }
     },
     autoAdjustOff,
   }
-}
\ No newline at end of file
+}
diff --git a/m3-vue/src/components/rich-tooltip/M3RichTooltip.vue b/m3-vue/src/components/rich-tooltip/M3RichTooltip.vue
index d0bab02..d021540 100644
--- a/m3-vue/src/components/rich-tooltip/M3RichTooltip.vue
+++ b/m3-vue/src/components/rich-tooltip/M3RichTooltip.vue
@@ -128,7 +128,7 @@ defineProps({
   container: {
     type: null as unknown as PropType<string | HTMLElement>,
     validator: Or(isString, isHTMLElement) as (value: unknown) => boolean,
-    default: 'body',
+    default: undefined,
   },
 
   offsetMainAxis: {
diff --git a/m3-vue/src/components/search/M3Search.vue b/m3-vue/src/components/search/M3Search.vue
index 5cfc046..3b79465 100644
--- a/m3-vue/src/components/search/M3Search.vue
+++ b/m3-vue/src/components/search/M3Search.vue
@@ -33,12 +33,11 @@
         </div>
     </div>
 
-    <Teleport to="body">
-        <Transition :duration="SEARCH_TRANSITION_MS" name="m3-search">
+    <Teleport v-if="layerReady" :to="layerHost">
+        <Transition :duration="SEARCH_TRANSITION_MS" name="m3-search" @after-leave="overlayMounted = false">
             <div v-if="open" class="m3-search__overlay">
                 <div
                     v-if="resolvedLayout === 'docked'"
-                    ref="scrim"
                     class="m3-search__scrim"
                     @click="close"
                 />
@@ -125,6 +124,7 @@ import { M3IconButton } from '@/components/icon-button'
 
 import { useBreakpoint } from '@/composables/breakpoint'
 import { useId } from '@/composables/id'
+import { useLayerHost } from '@/composables/layers'
 
 defineOptions({ inheritAttrs: false })
 
@@ -191,7 +191,8 @@ const bar = ref<HTMLElement | null>(null)
 const dialog = ref<HTMLElement | null>(null)
 const input = ref<HTMLInputElement | null>(null)
 const results = ref<HTMLElement | null>(null)
-const scrim = ref<HTMLElement | null>(null)
+const overlayMounted = ref(props.open)
+const { host: layerHost, ready: layerReady } = useLayerHost(() => props.open || overlayMounted.value)
 const position = ref<SearchDockedPosition>({ left: 12, top: 12, width: 360 })
 const anchor = ref<SearchAnchorRect>({ left: 12, top: 12, width: 360 })
 const viewport = ref<SearchViewport>({ width: 384, height: 640 })
@@ -213,6 +214,10 @@ const viewStyle = computed(() => ({
   '--m3-search-origin-offset-y': `${origin.value.offsetY}px`,
 }))
 
+watch(() => props.open, open => {
+  if (open) overlayMounted.value = true
+})
+
 const close = () => emit('update:open', false)
 const submit = () => {
   emit('submit', props.query)
@@ -283,11 +288,11 @@ watch([() => props.open, resolvedLayout, bar], ([open, layout], _, onCleanup) =>
   })
 }, { immediate: true, flush: 'post' })
 
-watch([() => props.open, dialog], ([open, element], _, onCleanup) => {
-  if (!open || !element) return
+watch([() => props.open, dialog, layerReady], ([open, element, ready], _, onCleanup) => {
+  if (!open || !element || !ready || !layerHost) return
   onCleanup(activateModalFocus({
     dialog: element,
-    exempt: () => [scrim.value],
+    layer: layerHost,
     onEscape: close,
   }))
   input.value?.focus()
diff --git a/m3-vue/src/components/side-sheet/M3SideSheet.vue b/m3-vue/src/components/side-sheet/M3SideSheet.vue
index b648359..d566915 100644
--- a/m3-vue/src/components/side-sheet/M3SideSheet.vue
+++ b/m3-vue/src/components/side-sheet/M3SideSheet.vue
@@ -9,7 +9,6 @@
         :width="docked ? 256 : undefined"
         :min-width="docked ? 256 : 320"
         :max-width="docked ? 256 : 400"
-        :z-index="DOCKED_Z_INDEX"
         :rounding-top-left="docked ? 0 : 16"
         :rounding-bottom-left="docked ? 0 : 16"
         :rounding-top-right="0"
@@ -78,7 +77,6 @@ import { useAnimationFrame } from '@/composables/animation'
 import { useId } from '@/composables/id'
 import { useTimeout } from '@/composables/timing'
 
-const DOCKED_Z_INDEX = 1000
 const SIDE_SHEET_TRANSITION_MS = durations['extra-long2']
 
 type TransitionState = 'idle' | 'pre-enter' | 'entering' | 'pre-exit' | 'exiting'
diff --git a/m3-vue/src/components/snackbar/M3SnackbarHost.vue b/m3-vue/src/components/snackbar/M3SnackbarHost.vue
index 567692b..0e9908d 100644
--- a/m3-vue/src/components/snackbar/M3SnackbarHost.vue
+++ b/m3-vue/src/components/snackbar/M3SnackbarHost.vue
@@ -1,32 +1,35 @@
 <template>
-    <div
-        ref="root"
-        class="m3-snackbar-host"
-        v-bind="$attrs"
-        @mouseenter="pause('hover')"
-        @mouseleave="resume('hover')"
-        @focusin="pause('focus')"
-        @focusout="onFocusOut"
-    >
-        <span class="m3-snackbar-host__announcement" role="status" aria-live="polite" aria-atomic="true">
-            {{ announcement }}
-        </span>
-        <M3Snackbar
-            v-if="display"
-            :message="display.entry.options.message"
-            :layout="display.entry.options.layout"
-            :closable="closable"
-            :close-label="display.entry.options.closeLabel"
-            :leaving="display.leaving"
-            :announce="false"
-            @action="finish('action')"
-            @dismiss="finish('dismiss')"
+    <span ref="anchor" hidden />
+    <Teleport :to="feedbackTarget ?? 'body'" :disabled="!feedbackTarget">
+        <div
+            ref="root"
+            class="m3-snackbar-host"
+            v-bind="$attrs"
+            @mouseenter="pause('hover')"
+            @mouseleave="resume('hover')"
+            @focusin="pause('focus')"
+            @focusout="onFocusOut"
         >
-            <template v-if="display.entry.action" #action="actionContext">
-                <RenderAction :render="display.entry.action" :context="actionContext" />
-            </template>
-        </M3Snackbar>
-    </div>
+            <span class="m3-snackbar-host__announcement" role="status" aria-live="polite" aria-atomic="true">
+                {{ announcement }}
+            </span>
+            <M3Snackbar
+                v-if="display"
+                :message="display.entry.options.message"
+                :layout="display.entry.options.layout"
+                :closable="closable"
+                :close-label="display.entry.options.closeLabel"
+                :leaving="display.leaving"
+                :announce="false"
+                @action="finish('action')"
+                @dismiss="finish('dismiss')"
+            >
+                <template v-if="display.entry.action" #action="actionContext">
+                    <RenderAction :render="display.entry.action" :context="actionContext" />
+                </template>
+            </M3Snackbar>
+        </div>
+    </Teleport>
 </template>
 
 <script lang="ts" setup>
@@ -41,12 +44,10 @@ import type { SnackbarResult } from '@modulify/m3-foundation/types/components/sn
 
 import { computed, defineComponent } from 'vue'
 import { isElement, isHTMLElement } from '@modulify/m3-foundation/lib/predicates'
-import {
-  onBeforeUnmount,
-  onMounted,
-  ref,
-  shallowRef,
-} from 'vue'
+import { LAYER_DEACTIVATED_EVENT } from '@modulify/m3-foundation/lib/layers'
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+import { resolveFeedbackContainer } from '@modulify/m3-foundation/lib/layers'
+import { shallowRef } from 'vue'
 
 import { useTimeout } from '@/composables/timing'
 
@@ -59,6 +60,7 @@ interface Entry {
 
   trigger: HTMLElement | null;
   nextFocus: HTMLElement | null;
+  feedbackTarget: HTMLElement | null;
 
   remaining: number | null;
   startedAt: number;
@@ -110,6 +112,9 @@ const RenderAction = defineComponent({
 })
 
 const root = ref<HTMLDivElement | null>(null)
+const anchor = ref<HTMLElement | null>(null)
+const feedbackTarget = ref<HTMLElement | null>(null)
+let layerObserver: MutationObserver | null = null
 const display = shallowRef<Display | null>(null)
 const announcement = ref('')
 
@@ -120,6 +125,7 @@ let leaving: Entry | null = null
 let timerRunning = false
 const paused = { hover: false, focus: false }
 let disposed = false
+let detachOwner = () => {}
 
 const durationTimeout = useTimeout(() => {
   timerRunning = false
@@ -176,9 +182,28 @@ const restoreFocus = (entry: Entry) => {
 }
 
 const begin = (entry: Entry) => {
+  if (entry.feedbackTarget && !entry.feedbackTarget.closest('[data-m3-layer-active="true"]')) {
+    entry.resolve('disposed')
+    const next = queue.shift()
+    if (next) begin(next)
+    else {
+      display.value = null
+      announcement.value = ''
+    }
+    return
+  }
+
   active = entry
   paused.hover = false
   paused.focus = false
+  detachOwner()
+  const layer = entry.feedbackTarget?.closest<HTMLElement>('.m3-layer')
+  if (layer) {
+    const onDeactivate = () => finish('disposed')
+    layer.addEventListener(LAYER_DEACTIVATED_EVENT, onDeactivate)
+    detachOwner = () => layer.removeEventListener(LAYER_DEACTIVATED_EVENT, onDeactivate)
+  }
+  feedbackTarget.value = entry.feedbackTarget?.isConnected ? entry.feedbackTarget : null
   display.value = { entry, leaving: false }
   announcement.value = entry.options.message
   if (entry.remaining !== null) {
@@ -193,6 +218,8 @@ const finish = (result: SnackbarResult) => {
   if (!entry) return
   stopTimer()
   active = null
+  detachOwner()
+  detachOwner = () => {}
   leaving = entry
   entry.resolve(result)
   display.value = { entry, leaving: true }
@@ -214,6 +241,7 @@ const makeEntry = (options: SnackbarOptions, resolve: Entry['resolve']): Entry =
     resolve,
     trigger,
     nextFocus: getNextFocusable(trigger),
+    feedbackTarget: resolveFeedbackContainer(trigger) ?? resolveFeedbackContainer(anchor.value),
     remaining: duration,
     startedAt: 0,
   }
@@ -272,8 +300,19 @@ const onKeyDown = (event: KeyboardEvent) => {
 const closable = computed(() => display.value?.entry.options.closable
   ?? Boolean(display.value?.entry.action || display.value?.entry.remaining === null))
 
-onMounted(() => document.addEventListener('keydown', onKeyDown))
+onMounted(() => {
+  document.addEventListener('keydown', onKeyDown)
+  const update = () => feedbackTarget.value = resolveFeedbackContainer(anchor.value)
+  const layer = anchor.value?.closest('.m3-layer')
+  if (layer) {
+    layerObserver = new MutationObserver(update)
+    layerObserver.observe(layer, { attributes: true, attributeFilter: ['data-m3-layer'] })
+  }
+  update()
+})
 onBeforeUnmount(() => {
+  layerObserver?.disconnect()
+  detachOwner()
   document.removeEventListener('keydown', onKeyDown)
   disposed = true
   stopTimer()
diff --git a/m3-vue/src/components/surface/M3Surface.vue b/m3-vue/src/components/surface/M3Surface.vue
index 9f81d40..23ccfb4 100644
--- a/m3-vue/src/components/surface/M3Surface.vue
+++ b/m3-vue/src/components/surface/M3Surface.vue
@@ -1,10 +1,9 @@
 <template>
-    <Teleport v-if="isModal" :to="teleportTo">
+    <Teleport v-if="isModal && layerReady" :to="layerHost">
         <Transition v-if="scrim" name="m3-transition-fade">
             <div
                 v-show="resolvedScrimShown"
-                ref="scrimElement"
-                :style="{ zIndex: zIndex - 1 }"
+                :style="{ zIndex: 0 }"
                 class="m3-surface__scrim"
                 @click="onScrimClick"
             />
@@ -41,7 +40,7 @@
     </Teleport>
 
     <M3SurfacePanel
-        v-else
+        v-else-if="!isModal"
         :id="_id"
         :tag="tag"
         :overflow="overflow"
@@ -88,6 +87,7 @@ import {
 import { activateModalFocus } from '@modulify/m3-foundation/lib/modal'
 
 import { useId } from '@/composables/id'
+import { useLayerHost } from '@/composables/layers'
 
 import { getModalAnchorStyle } from './shared'
 import M3SurfacePanel from './M3SurfacePanel.vue'
@@ -150,10 +150,6 @@ const props = defineProps({
     default: 0,
   },
 
-  zIndex: {
-    type: Number,
-    default: 400,
-  },
 })
 
 const emit = defineEmits([
@@ -163,7 +159,6 @@ const emit = defineEmits([
 
 const attrs = useAttrs()
 const modalPanel = ref<InstanceType<typeof M3SurfacePanel> | null>(null)
-const scrimElement = ref<HTMLElement | null>(null)
 
 const _id = useId('m3-surface', computed(() => props.id))
 
@@ -177,6 +172,11 @@ const surfaceAttrs = computed(() => {
     ...attrs,
   } : attrs
 })
+const { host: layerHost, ready: layerReady } = useLayerHost(
+  () => isModal.value && String(surfaceAttrs.value['aria-modal']) !== 'false',
+  () => props.teleportTo,
+  () => isModal.value
+)
 
 const surfaceClass = computed(() => ({
   ['m3-surface_modal']: isModal.value,
@@ -192,7 +192,7 @@ const surfaceStyle = computed(() => {
       left: toLength(props.insetLeft, '0px'),
     }),
     position: isModal.value ? 'fixed' : 'relative',
-    zIndex: isModal.value ? props.zIndex : undefined,
+    zIndex: isModal.value ? 1 : undefined,
     display: props.shown ? undefined : 'none',
   }
 })
@@ -202,13 +202,13 @@ function onScrimClick() {
   emit('dismiss')
 }
 
-watch([modalPanel, isModal, () => props.shown, () => surfaceAttrs.value['aria-modal'], () => props.tag], ([panel, modal, shown, ariaModal], _, onCleanup) => {
+watch([modalPanel, isModal, () => props.shown, () => surfaceAttrs.value['aria-modal'], () => props.tag, layerReady], ([panel, modal, shown, ariaModal, , ready], _, onCleanup) => {
   const dialog = panel?.el
-  if (!dialog || !modal || !shown || String(ariaModal) === 'false') return
+  if (!dialog || !modal || !shown || String(ariaModal) === 'false' || !ready || !layerHost) return
 
   onCleanup(activateModalFocus({
     dialog,
-    exempt: () => [scrimElement.value],
+    layer: layerHost,
     onEscape: onScrimClick,
   }))
 }, { immediate: true, flush: 'post' })
diff --git a/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts b/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
index 9392ebc..5ba9cba 100644
--- a/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
+++ b/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
@@ -236,7 +236,6 @@ export function useSurfaceSideSheetMorph() {
     roundingTopRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topRight,
     roundingBottomRight: MODAL_SIDE_SHEET_DESCRIPTOR.rounding.bottomRight,
     transitionMs: modalTransitionMs.value,
-    zIndex: 520,
     variant: modalRole.value,
     elevation: modalElevation.value,
     overflow: MODAL_SIDE_SHEET_DESCRIPTOR.overflow,
diff --git a/m3-vue/src/composables/index.ts b/m3-vue/src/composables/index.ts
index 8b51d2e..54521bf 100644
--- a/m3-vue/src/composables/index.ts
+++ b/m3-vue/src/composables/index.ts
@@ -2,5 +2,6 @@ export { useAnimationFrame } from './animation'
 export { m3Adaptive } from './adaptive'
 export { useBreakpoint } from './breakpoint'
 export { useId } from './id'
+export { useLayerHost } from './layers'
 export { useMutationObserver, useResizeObserver } from './observer'
 export { useTimeout } from './timing'
diff --git a/m3-vue/src/composables/layers.ts b/m3-vue/src/composables/layers.ts
new file mode 100644
index 0000000..228352f
--- /dev/null
+++ b/m3-vue/src/composables/layers.ts
@@ -0,0 +1,33 @@
+import { createLayerHost, mountLayerHost } from '@modulify/m3-foundation/lib/layers'
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+import { setLayerModal } from '@modulify/m3-foundation/lib/layers'
+import { watch } from 'vue'
+
+export function useLayerHost(modal: () => boolean, container: () => string = () => 'body', enabled: () => boolean = () => true) {
+  const host = typeof document === 'undefined' ? null : createLayerHost(document)
+  const ready = ref(Boolean(host) && enabled())
+
+  watch(modal, value => {
+    if (host) setLayerModal(host, value)
+  }, { immediate: true })
+
+  watch([container, enabled], ([value, active]) => {
+    if (!host || !active) {
+      host?.remove()
+      ready.value = false
+      return
+    }
+    mountLayerHost(host, document.querySelector<HTMLElement>(value) ?? document.body)
+    ready.value = true
+  }, { flush: 'post' })
+
+  onMounted(() => {
+    if (!host || !enabled()) return
+    mountLayerHost(host, document.querySelector<HTMLElement>(container()) ?? document.body)
+    ready.value = true
+  })
+
+  onBeforeUnmount(() => host?.remove())
+
+  return { host, ready }
+}
diff --git a/m3-vue/storybook/components/M3Surface.mdx b/m3-vue/storybook/components/M3Surface.mdx
index 58ca279..a6874c7 100644
--- a/m3-vue/storybook/components/M3Surface.mdx
+++ b/m3-vue/storybook/components/M3Surface.mdx
@@ -37,6 +37,14 @@ Use `variant` when the surface role is explicit. Use `auto` only when you intent
 
 The component does not prescribe content anatomy. Dialogs, side sheets, and custom orchestrated surfaces build that structure on top.
 
+### UI layers
+
+Each open modal surface owns one isolated layer: scrim and content at local levels `0` and `1`, snackbar at `50`, and popovers at `100`. The page uses `10` for floating UI and `100` for popovers; every modal layer uses `1000`. Modal layers share that value and follow opening order in the DOM. Search and modal navigation use the same stack. Escape closes the top popover before the top modal, and focus is confined to the top layer.
+
+Popovers choose their layer from the trigger. Keep a custom `container` inside the same layer when overriding the default portal. A snackbar follows the layer of the focused trigger when `show()` is called; a host mounted inside a modal also defaults to that modal. A later modal covers earlier snackbar content. `M3Surface` no longer accepts a numeric `zIndex`: open order determines the modal order.
+
+Closing a modal closes its popovers and disposes snackbar messages owned by that modal. The snackbar promise resolves to `disposed` in that case.
+
 ## Story guide
 
 - [Side Sheet Docked To Modal](?path=/story/components-m3surface--side-sheet-docked-to-modal)
@@ -51,6 +59,8 @@ The component does not prescribe content anatomy. Dialogs, side sheets, and cust
   Morphs a right-edge modal sheet into a centered dialog window while keeping one modal surface vocabulary.
 - [Nested Dialogs Chain](?path=/story/components-m3surface--nested-dialogs-chain)
   Demonstrates layered modal surfaces, topmost scrim ownership, and per-layer enter/exit motion.
+- [Layer Stack](?path=/story/components-m3surface--layer-stack)
+  Lets you open a modal menu, snackbar, and another modal to inspect their order and Escape behavior.
 - [Workspace Modal Dialog](?path=/story/components-m3surface--workspace-modal-dialog)
   Shows a centered blocking decision surface in a realistic workspace scene without morph choreography.
 - [Inspector Side Sheet](?path=/story/components-m3surface--inspector-side-sheet)
@@ -131,6 +141,14 @@ The `Inspector Side Sheet` story shows this anatomy with the standard `m3-side-s
 
 `M3Surface` управляет переносом модального элемента, затемнением, позиционированием, скруглением, размерами и отступами при morph-переходах. Структуру содержимого задают построенные поверх него диалоги, side sheet и пользовательские поверхности.
 
+### Слои интерфейса
+
+Каждая открытая модальная поверхность владеет изолированным слоем: scrim и содержимое имеют локальные уровни `0` и `1`, snackbar — `50`, popover — `100`. На странице floating UI использует `10`, а popover — `100`; каждый модальный слой использует `1000`. Одинаковые значения у модальных слоёв сочетаются с DOM-порядком открытия. Search и модальная навигация входят в тот же стек. Escape сначала закрывает верхний popover, затем верхний модал; фокус остаётся в верхнем слое.
+
+Popover определяет владельца по кнопке вызова. При явном `container` размещайте его внутри того же слоя. Snackbar следует слою элемента в фокусе при вызове `show()`; host внутри модала по умолчанию принадлежит этому модалу. Позднее открытый модал перекрывает прежний snackbar. Числовой `zIndex` больше не является prop `M3Surface`: порядок модалов задаётся открытием.
+
+При закрытии модала его popover закрываются, а принадлежащие ему сообщения snackbar завершаются. Promise такого snackbar возвращает `disposed`.
+
 ## Примеры в Storybook
 
 - [Закреплённая панель в модальную](?path=/story/components-m3surface--side-sheet-docked-to-modal)
@@ -139,6 +157,7 @@ The `Inspector Side Sheet` story shows this anatomy with the standard `m3-side-s
 - [Всегда модальная панель](?path=/story/components-m3surface--side-sheet-always-modal-toggle)
 - [Модальная панель в окно](?path=/story/components-m3surface--side-sheet-modal-to-window)
 - [Цепочка вложенных диалогов](?path=/story/components-m3surface--nested-dialogs-chain)
+- [Стек слоёв](?path=/story/components-m3surface--layer-stack)
 - [Модальный диалог рабочего пространства](?path=/story/components-m3surface--workspace-modal-dialog)
 - [Панель инспектора](?path=/story/components-m3surface--inspector-side-sheet)
 
diff --git a/m3-vue/storybook/components/M3Surface.stories.ts b/m3-vue/storybook/components/M3Surface.stories.ts
index d6f8c36..4dbd346 100644
--- a/m3-vue/storybook/components/M3Surface.stories.ts
+++ b/m3-vue/storybook/components/M3Surface.stories.ts
@@ -6,6 +6,7 @@ import M3Surface from '@/components/surface/M3Surface.vue'
 import { resolveStorybookLocale } from '../i18n'
 import SurfaceCardPageMorph from '../examples/surface/SurfaceCardPageMorph.vue'
 import SurfaceInspectorSheet from '../examples/surface/SurfaceInspectorSheet.vue'
+import SurfaceLayerStack from '../examples/surface/SurfaceLayerStack.vue'
 import SurfaceNestedDialogsChain from '../examples/surface/SurfaceNestedDialogsChain.vue'
 import SurfaceSideSheetAlwaysModal from '../examples/surface/SurfaceSideSheetAlwaysModal.vue'
 import SurfaceSideSheetDismissToRemove from '../examples/surface/SurfaceSideSheetDismissToRemove.vue'
@@ -56,6 +57,10 @@ export const NestedDialogsChain: Story = {
   render: (_args, { globals }) => localizedSurfaceStory(SurfaceNestedDialogsChain, globals.locale),
 }
 
+export const LayerStack: Story = {
+  render: (_args, { globals }) => localizedSurfaceStory(SurfaceLayerStack, globals.locale),
+}
+
 export const WorkspaceModalDialog: Story = {
   render: (_args, { globals }) => localizedSurfaceStory(SurfaceWorkspaceDialog, globals.locale),
 }
diff --git a/m3-vue/storybook/examples/surface/SurfaceLayerStack.vue b/m3-vue/storybook/examples/surface/SurfaceLayerStack.vue
new file mode 100644
index 0000000..df24a3b
--- /dev/null
+++ b/m3-vue/storybook/examples/surface/SurfaceLayerStack.vue
@@ -0,0 +1,130 @@
+<template>
+    <main class="surface-layer-stack">
+        <h1>{{ text.title }}</h1>
+        <p>{{ text.description }}</p>
+        <button @click="first = true">
+            {{ text.open }}
+        </button>
+        <M3SnackbarHost ref="snackbar" />
+
+        <M3Surface
+            :shown="first"
+            :width="360"
+            :height="280"
+            :rounding="28"
+            mode="modal"
+            anchor="center"
+            variant="surface-container-high"
+            @update:shown="value => { if (!value) closeFirst() }"
+        >
+            <div class="surface-layer-stack__dialog">
+                <h2>{{ text.first }}</h2>
+                <button ref="menuTarget">
+                    {{ text.menu }}
+                </button>
+                <M3Popper :target="() => menuTarget" :detach-timeout="null" animated>
+                    <button>{{ text.menuAction }}</button>
+                </M3Popper>
+                <button @click="showSnackbar">
+                    {{ text.snackbar }}
+                </button>
+                <button @click="second = true">
+                    {{ text.next }}
+                </button>
+                <button @click="closeFirst">
+                    {{ text.close }}
+                </button>
+            </div>
+        </M3Surface>
+
+        <M3Surface
+            v-model:shown="second"
+            :width="320"
+            :height="180"
+            :rounding="28"
+            mode="modal"
+            anchor="center"
+            variant="surface-container-high"
+        >
+            <div class="surface-layer-stack__dialog">
+                <h2>{{ text.second }}</h2>
+                <button @click="second = false">
+                    {{ text.close }}
+                </button>
+            </div>
+        </M3Surface>
+    </main>
+</template>
+
+<script setup lang="ts">
+import type { SnackbarHostMethods } from '@/components/snackbar'
+import type { StorybookLocale } from '../../i18n'
+
+import { computed, ref } from 'vue'
+
+import M3Popper from '@/components/popper/M3Popper.vue'
+import M3SnackbarHost from '@/components/snackbar/M3SnackbarHost.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
+
+const props = defineProps<{ locale: StorybookLocale }>()
+
+const copy = {
+  'en-US': {
+    title: 'UI layer stack',
+    description: 'Open the first dialog, then its menu, snackbar, and second dialog. Escape closes the top interaction first.',
+    open: 'Open first dialog',
+    first: 'First dialog',
+    second: 'Second dialog',
+    menu: 'Open menu',
+    menuAction: 'Menu action',
+    snackbar: 'Show snackbar',
+    snackbarMessage: 'Saved in the first dialog',
+    next: 'Open second dialog',
+    close: 'Close',
+  },
+  'ru-RU': {
+    title: 'Стек слоёв интерфейса',
+    description: 'Откройте первый диалог, затем его меню, snackbar и второй диалог. Escape закрывает верхнее взаимодействие первым.',
+    open: 'Открыть первый диалог',
+    first: 'Первый диалог',
+    second: 'Второй диалог',
+    menu: 'Открыть меню',
+    menuAction: 'Пункт меню',
+    snackbar: 'Показать snackbar',
+    snackbarMessage: 'Сохранено в первом диалоге',
+    next: 'Открыть второй диалог',
+    close: 'Закрыть',
+  },
+}
+
+const text = computed(() => copy[props.locale])
+const first = ref(false)
+const second = ref(false)
+const menuTarget = ref<HTMLButtonElement | null>(null)
+const snackbar = ref<SnackbarHostMethods | null>(null)
+
+const closeFirst = () => {
+  second.value = false
+  first.value = false
+  snackbar.value?.dismiss()
+}
+
+const showSnackbar = () => {
+  void snackbar.value?.show({ message: text.value.snackbarMessage, duration: null })
+}
+</script>
+
+<style scoped>
+.surface-layer-stack {
+  min-height: 100vh;
+  padding: 32px;
+  background: var(--m3-sys-surface);
+}
+
+.surface-layer-stack__dialog {
+  display: grid;
+  align-content: start;
+  gap: 16px;
+  padding: 24px;
+}
+</style>
diff --git a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
index 14d83dc..cebaa00 100644
--- a/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
+++ b/m3-vue/storybook/examples/surface/SurfaceNestedDialogsChain.vue
@@ -105,7 +105,6 @@
                 :inset-top="24"
                 :inset-bottom="24"
                 :rounding="dialog.rounding"
-                :z-index="dialogZIndex(level)"
                 :elevation="dialogElevation(level)"
                 :style="dialogInlineStyle(level)"
                 :class="[
@@ -176,8 +175,6 @@ import { localize } from '../../i18n'
 const DIALOG_TRANSITION_MS = durations.medium2
 const DIALOG_TRANSITION_EASING = easing.standard
 const DIALOG_ENTRY_OFFSET_PX = 24
-const DIALOG_Z_INDEX_BASE = 560
-const DIALOG_Z_INDEX_STEP = 40
 
 type DialogSpec = {
   id: string,
@@ -242,10 +239,6 @@ function dialogMode(level: number): 'standard' | 'modal' {
   return isTopDialog(level) ? 'modal' : 'standard'
 }
 
-function dialogZIndex(level: number) {
-  return DIALOG_Z_INDEX_BASE + (level * DIALOG_Z_INDEX_STEP)
-}
-
 function dialogElevation(level: number) {
   return Math.min(5, 2 + level)
 }
@@ -257,7 +250,6 @@ function dialogInlineStyle(level: number) {
     position: 'fixed',
     top: '50%',
     left: '50%',
-    zIndex: dialogZIndex(level),
     opacity: visible ? 1 : 0,
     transform: visible
       ? 'translate(-50%, -50%)'
diff --git a/m3-vue/tests/M3Layers.e2e.ts b/m3-vue/tests/M3Layers.e2e.ts
new file mode 100644
index 0000000..d254a02
--- /dev/null
+++ b/m3-vue/tests/M3Layers.e2e.ts
@@ -0,0 +1,257 @@
+import type { SnackbarHostMethods } from '@/components/snackbar'
+
+import {
+  createApp,
+  h,
+  nextTick,
+  ref,
+} from 'vue'
+
+import M3Popper from '@/components/popper/M3Popper.vue'
+import M3Search from '@/components/search/M3Search.vue'
+import M3SnackbarHost from '@/components/snackbar/M3SnackbarHost.vue'
+import M3Surface from '@/components/surface/M3Surface.vue'
+
+const waitFor = async (assertion: () => void) => {
+  const startedAt = performance.now()
+  while (performance.now() - startedAt < 2000) {
+    try {
+      assertion()
+      return
+    } catch {
+      await new Promise(resolve => setTimeout(resolve, 16))
+    }
+  }
+  assertion()
+}
+
+test('a popover stays in its modal layer and handles Escape before the modal', async () => {
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const target = ref<HTMLButtonElement | null>(null)
+  const shown = ref(true)
+  const app = createApp({
+    render: () => h(M3Surface, {
+      mode: 'modal',
+      shown: shown.value,
+      'onUpdate:shown': (value: boolean) => shown.value = value,
+    }, { default: () => [
+      h('button', { ref: target }, 'Open menu'),
+      h(M3Popper, { target: () => target.value, detachTimeout: null }, { default: () => h('button', 'Menu action') }),
+    ] }),
+  })
+  app.mount(mountPoint)
+
+  try {
+    const trigger = document.querySelector<HTMLButtonElement>('.m3-surface button')!
+    trigger.click()
+    await waitFor(() => expect(document.querySelector('.m3-popper_shown')).not.toBeNull())
+
+    const layer = trigger.closest<HTMLElement>('.m3-layer')!
+    const popper = document.querySelector<HTMLElement>('.m3-popper_shown')!
+    expect(layer.querySelector('.m3-layer__popovers')!.contains(popper)).toBe(true)
+    expect(getComputedStyle(layer).zIndex).toBe('1000')
+    expect(getComputedStyle(layer.querySelector<HTMLElement>('.m3-layer__popovers')!).zIndex).toBe('100')
+    expect(popper.inert).toBe(false)
+
+    popper.querySelector<HTMLButtonElement>('button')!.focus()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true, bubbles: true, cancelable: true }))
+    expect(document.activeElement).toBe(trigger)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }))
+    await waitFor(() => expect(document.querySelector('.m3-popper_shown')).toBeNull())
+    expect(shown.value).toBe(true)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }))
+    await nextTick()
+    expect(shown.value).toBe(false)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test('a snackbar opened from a modal belongs to that layer', async () => {
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const host = ref<SnackbarHostMethods | null>(null)
+  const shown = ref(true)
+  const app = createApp({
+    render: () => [
+      h(M3SnackbarHost, { ref: host }),
+      h(M3Surface, { mode: 'modal', shown: shown.value }, { default: () => h('button', 'Notify') }),
+    ],
+  })
+  app.mount(mountPoint)
+
+  try {
+    const trigger = document.querySelector<HTMLButtonElement>('.m3-surface button')!
+    await waitFor(() => expect(trigger.closest('.m3-layer')?.getAttribute('data-m3-layer-active')).toBe('true'))
+    trigger.focus()
+    const result = host.value?.show({ message: 'Layer notice', duration: null })
+    await nextTick()
+
+    const layer = trigger.closest<HTMLElement>('.m3-layer')!
+    const feedback = layer.querySelector<HTMLElement>('.m3-layer__feedback')!
+    expect(feedback.querySelector('.m3-snackbar-host')).not.toBeNull()
+    expect(feedback.querySelector('.m3-snackbar')).not.toBeNull()
+    expect(getComputedStyle(feedback).zIndex).toBe('50')
+
+    const close = feedback.querySelector<HTMLButtonElement>('.m3-snackbar__close')!
+    close.focus()
+    expect(document.activeElement).toBe(close)
+
+    shown.value = false
+    await nextTick()
+    expect(await result).toBe('disposed')
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test('a reopened modal moves above the previously opened modal', async () => {
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const firstShown = ref(true)
+  const secondShown = ref(true)
+  const app = createApp({
+    render: () => [
+      h(M3Surface, { mode: 'modal', shown: firstShown.value }, { default: () => h('button', 'First') }),
+      h(M3Surface, { mode: 'modal', shown: secondShown.value }, { default: () => h('button', 'Second') }),
+    ],
+  })
+  app.mount(mountPoint)
+
+  try {
+    const first = [...document.querySelectorAll<HTMLButtonElement>('.m3-surface button')].find(button => button.textContent === 'First')!
+    const second = [...document.querySelectorAll<HTMLButtonElement>('.m3-surface button')].find(button => button.textContent === 'Second')!
+    const firstLayer = first.closest<HTMLElement>('.m3-layer')!
+    const secondLayer = second.closest<HTMLElement>('.m3-layer')!
+
+    await waitFor(() => expect(firstLayer.nextElementSibling).toBe(secondLayer))
+    expect(firstLayer.inert).toBe(true)
+    expect(document.activeElement).toBe(second)
+
+    firstShown.value = false
+    await nextTick()
+    firstShown.value = true
+    await nextTick()
+    await waitFor(() => expect(secondLayer.nextElementSibling).toBe(firstLayer))
+    expect(secondLayer.inert).toBe(true)
+    expect(firstLayer.inert).toBe(false)
+    expect(document.activeElement).toBe(first)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test('search and dialog follow activation order instead of component type', async () => {
+  const mountPoint = document.createElement('div')
+  document.body.append(mountPoint)
+  const searchOpen = ref(true)
+  const dialogShown = ref(false)
+  const app = createApp({
+    render: () => [
+      h(M3Search, { query: '', label: 'Search', status: '', open: searchOpen.value, layout: 'docked' }),
+      h(M3Surface, { mode: 'modal', shown: dialogShown.value }, { default: () => h('button', 'Dialog action') }),
+    ],
+  })
+  app.mount(mountPoint)
+
+  try {
+    await waitFor(() => expect(document.querySelector('.m3-search__view')).not.toBeNull())
+    const search = document.querySelector<HTMLElement>('.m3-search__view')!
+    const searchLayer = search.closest<HTMLElement>('.m3-layer')!
+    dialogShown.value = true
+    await nextTick()
+    const dialog = document.querySelector<HTMLElement>('.m3-surface')!
+    const dialogLayer = dialog.closest<HTMLElement>('.m3-layer')!
+    await waitFor(() => expect(searchLayer.nextElementSibling).toBe(dialogLayer))
+    expect(searchLayer.inert).toBe(true)
+
+    searchOpen.value = false
+    await nextTick()
+    searchOpen.value = true
+    await nextTick()
+    await waitFor(() => expect(dialogLayer.nextElementSibling).toBe(searchLayer))
+    expect(dialogLayer.inert).toBe(true)
+    expect(searchLayer.inert).toBe(false)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+  }
+})
+
+test('showing an already open popover raises it visually and for Escape', async () => {
+  const firstTarget = document.createElement('button')
+  const secondTarget = document.createElement('button')
+  const mountPoint = document.createElement('div')
+  document.body.append(firstTarget, secondTarget, mountPoint)
+  const first = ref<{ show(immediately?: boolean): void } | null>(null)
+  const second = ref<{ show(immediately?: boolean): void } | null>(null)
+  const app = createApp({
+    render: () => [
+      h(M3Popper, { ref: first, target: () => firstTarget, targetTriggers: [], overflow: [], detachTimeout: null }, { default: () => h('button', 'First menu') }),
+      h(M3Popper, { ref: second, target: () => secondTarget, targetTriggers: [], overflow: [], detachTimeout: null }, { default: () => h('button', 'Second menu') }),
+    ],
+  })
+  app.mount(mountPoint)
+
+  try {
+    await nextTick()
+    expect(first.value).not.toBeNull()
+    expect(second.value).not.toBeNull()
+    first.value?.show(true)
+    second.value?.show(true)
+    await nextTick()
+    expect(document.querySelectorAll('.m3-popper-positioner').length).toBe(2)
+    await waitFor(() => expect(document.querySelectorAll('.m3-popper_shown').length).toBe(2))
+    const poppers = [...document.querySelectorAll<HTMLElement>('.m3-popper_shown')]
+    const firstHost = poppers.find(popper => popper.textContent === 'First menu')!.parentElement!.parentElement!
+    const secondHost = poppers.find(popper => popper.textContent === 'Second menu')!.parentElement!.parentElement!
+
+    first.value?.show(true)
+    expect(secondHost.nextElementSibling).toBe(firstHost)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }))
+    await waitFor(() => expect(firstHost.querySelector('.m3-popper_shown')).toBeNull())
+    expect(secondHost.querySelector('.m3-popper_shown')).not.toBeNull()
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+    firstTarget.remove()
+    secondTarget.remove()
+  }
+})
+
+test('a page popover becomes inert beneath a newly opened modal', async () => {
+  const target = document.createElement('button')
+  const mountPoint = document.createElement('div')
+  document.body.append(target, mountPoint)
+  const modalShown = ref(false)
+  const app = createApp({
+    render: () => [
+      h(M3Popper, { target: () => target, shown: true, overflow: [], detachTimeout: null }, { default: () => h('button', 'Page menu') }),
+      h(M3Surface, { mode: 'modal', shown: modalShown.value }, { default: () => h('button', 'Modal action') }),
+    ],
+  })
+  app.mount(mountPoint)
+
+  try {
+    await waitFor(() => expect(document.querySelector('.m3-popper_shown')).not.toBeNull())
+    const popperHost = document.querySelector<HTMLElement>('.m3-popper_shown')!.parentElement!.parentElement!
+    expect(popperHost.parentElement).toBe(document.body)
+
+    modalShown.value = true
+    await nextTick()
+    await waitFor(() => expect(popperHost.inert).toBe(true))
+    const modalLayer = document.querySelector<HTMLElement>('.m3-layer[data-m3-layer="modal"]')!
+    expect(popperHost.nextElementSibling).toBe(modalLayer)
+  } finally {
+    app.unmount()
+    mountPoint.remove()
+    target.remove()
+  }
+})
diff --git a/m3-vue/tests/M3SurfaceFocus.e2e.ts b/m3-vue/tests/M3SurfaceFocus.e2e.ts
index b7bfaa9..167d3ac 100644
--- a/m3-vue/tests/M3SurfaceFocus.e2e.ts
+++ b/m3-vue/tests/M3SurfaceFocus.e2e.ts
@@ -108,7 +108,7 @@ test('closing a nested modal restores focus to the modal below it', async () =>
     await nextTick()
     const upper = [...document.querySelectorAll<HTMLButtonElement>('.m3-surface button')].at(-1)!
     expect(document.activeElement).toBe(upper)
-    expect(lower.closest<HTMLElement>('.m3-surface')!.inert).toBe(true)
+    expect(lower.closest<HTMLElement>('.m3-layer')!.inert).toBe(true)
 
     document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true, cancelable: true }))
     await nextTick()

From 020c574e12072b6bf1819533d6600f00f51fd61d Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Mon, 19 Oct 2026 12:35:17 +0400
Subject: [PATCH 18/20] test(m3-react): Browser test startup was stabilized

The Toolbar width assertion now waits for fonts, and smoke tests prebundle validator assertions before opening Storybook stories.
---
 m3-react/tests/M3Toolbar.e2e.tsx | 1 +
 m3-react/vitest.config.smoke.ts  | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/m3-react/tests/M3Toolbar.e2e.tsx b/m3-react/tests/M3Toolbar.e2e.tsx
index 58604fa..2387fd2 100644
--- a/m3-react/tests/M3Toolbar.e2e.tsx
+++ b/m3-react/tests/M3Toolbar.e2e.tsx
@@ -71,6 +71,7 @@ test('restores the full floating width after collapsing to the FAB', async () =>
   try {
     const toolbar = screen.getByRole('toolbar', { name: 'Editing' })
     const container = toolbar.querySelector<HTMLElement>('.m3-toolbar__container')!
+    await document.fonts.ready
     const expandedWidth = container.getBoundingClientRect().width
     scroller.scrollTop = 100
     await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
diff --git a/m3-react/vitest.config.smoke.ts b/m3-react/vitest.config.smoke.ts
index b0efd40..2c90569 100644
--- a/m3-react/vitest.config.smoke.ts
+++ b/m3-react/vitest.config.smoke.ts
@@ -16,7 +16,7 @@ export default mergeConfig(common, defineConfig({
     'import.meta.env.VITEST_STORYBOOK': JSON.stringify('false'),
   },
   optimizeDeps: {
-    include: ['storybook/test'],
+    include: ['storybook/test', '@modulify/validator/assertions'],
   },
   test: {
     name: 'm3-react-smoke',

From dd9a42a3c141e9cb1ad1452b5acd5ec81778dbfe Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Mon, 19 Oct 2026 12:35:45 +0400
Subject: [PATCH 19/20] test(m3-vue): Browser test startup was stabilized

The Toolbar width assertion now waits for fonts, and smoke tests prebundle validator assertions before opening Storybook stories.
---
 m3-vue/tests/M3Toolbar.e2e.ts | 1 +
 m3-vue/vitest.config.smoke.ts | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/m3-vue/tests/M3Toolbar.e2e.ts b/m3-vue/tests/M3Toolbar.e2e.ts
index 89904a7..aceb100 100644
--- a/m3-vue/tests/M3Toolbar.e2e.ts
+++ b/m3-vue/tests/M3Toolbar.e2e.ts
@@ -89,6 +89,7 @@ test('restores the full floating width after collapsing to the FAB', async () =>
   try {
     const toolbar = scroller.querySelector<HTMLElement>('.m3-toolbar')!
     const container = toolbar.querySelector<HTMLElement>('.m3-toolbar__container')!
+    await document.fonts.ready
     const expandedWidth = container.getBoundingClientRect().width
     scroller.scrollTop = 100
     await waitFor(() => expect(toolbar.classList.contains('m3-toolbar_collapsed')).toBe(true))
diff --git a/m3-vue/vitest.config.smoke.ts b/m3-vue/vitest.config.smoke.ts
index 948b1e7..27c72bf 100644
--- a/m3-vue/vitest.config.smoke.ts
+++ b/m3-vue/vitest.config.smoke.ts
@@ -21,7 +21,7 @@ export default mergeConfig(viteConfig, defineConfig({
     'import.meta.env.VITEST_STORYBOOK': JSON.stringify('false'),
   },
   optimizeDeps: {
-    include: ['storybook/test'],
+    include: ['storybook/test', '@modulify/validator/assertions'],
   },
   resolve: {
     alias: [

From e6d99e3664b046e9a81b7193231ee79439eea8de Mon Sep 17 00:00:00 2001
From: Zaitsev Kirill <zaytsev.cmath10@gmail.com>
Date: Mon, 19 Oct 2026 13:05:29 +0400
Subject: [PATCH 20/20] test(m3-vue): Surface transition sampling was
 stabilized

---
 m3-vue/tests/M3Surface.e2e.ts | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/m3-vue/tests/M3Surface.e2e.ts b/m3-vue/tests/M3Surface.e2e.ts
index d284c0d..ce9e5e6 100644
--- a/m3-vue/tests/M3Surface.e2e.ts
+++ b/m3-vue/tests/M3Surface.e2e.ts
@@ -189,9 +189,6 @@ describe('m3-vue/surface e2e', () => {
     click('[data-testid="card-to-page"]')
     await nextTick()
 
-    await delay(120)
-    await capture('scenario-b-card-mid')
-
     const rectSeries = await collectRectSeries(overlayWrap, 380, 32)
     await delay(240)
     const afterRect = overlayWrap.getBoundingClientRect()