@@ -164,7 +221,7 @@ describe('m3-react/popper e2e', () => {
)
unmount = mounted.unmount
- const popper = await waitForPopper()
+ const { positioner, popper } = await waitForPopper()
vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
@@ -175,9 +232,10 @@ describe('m3-react/popper e2e', () => {
let bottomX = 0
let bottomY = 0
await waitFor(() => {
- const point = parseTransform(popper)
+ const point = parseTransform(positioner)
bottomX = point.x
bottomY = point.y
+ expectAnimationSide(popper, 'bottom')
})
mounted.rerender(
@@ -189,6 +247,7 @@ describe('m3-react/popper e2e', () => {
overflow={[]}
offsetMainAxis={0}
offsetCrossAxis={0}
+ animated={true}
detachTimeout={null}
>
@@ -197,14 +256,11 @@ describe('m3-react/popper e2e', () => {
)
- await act(async () => {
- await popperRef.current?.adjust()
- })
-
await waitFor(() => {
- const point = parseTransform(popper)
+ const point = parseTransform(positioner)
expect(point.x).toBeGreaterThan(bottomX)
expect(point.y).not.toBe(bottomY)
+ expectAnimationSide(popper, 'right')
})
})
@@ -223,6 +279,7 @@ describe('m3-react/popper e2e', () => {
overflow={[]}
offsetMainAxis={0}
offsetCrossAxis={0}
+ animated={true}
detachTimeout={null}
>
@@ -232,7 +289,7 @@ describe('m3-react/popper e2e', () => {
)
unmount = mounted.unmount
- const popper = await waitForPopper()
+ const { positioner, popper } = await waitForPopper()
vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
@@ -242,7 +299,7 @@ describe('m3-react/popper e2e', () => {
let y0 = 0
await waitFor(() => {
- y0 = parseTransform(popper).y
+ y0 = parseTransform(positioner).y
})
mounted.rerender(
@@ -254,6 +311,38 @@ describe('m3-react/popper e2e', () => {
overflow={[]}
offsetMainAxis={10}
offsetCrossAxis={0}
+ animated={true}
+ detachTimeout={null}
+ >
+
+ Popper content
+
+
+ )
+
+ await waitFor(() => {
+ const y1 = parseTransform(positioner).y
+ expect(Math.round(Math.abs(y1 - y0))).toBe(10)
+ expectAnimationSide(popper, 'top')
+ })
+ })
+
+ test('updates animation direction after flip when bottom placement has no space', async () => {
+ target = document.createElement('button')
+ document.body.append(target)
+
+ const popperRef = createRef
()
+
+ const mounted = render(
+
@@ -261,14 +350,55 @@ describe('m3-react/popper e2e', () => {
)
+ unmount = mounted.unmount
+
+ const { popper } = await waitForPopper()
+ const y = window.innerHeight - 12
+ vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, y, 40, 20))
await act(async () => {
await popperRef.current?.adjust()
})
await waitFor(() => {
- const y1 = parseTransform(popper).y
- expect(Math.round(Math.abs(y1 - y0))).toBe(10)
+ expectAnimationSide(popper, 'top')
+ })
+ })
+
+ test('applies animation vectors for left placement', async () => {
+ target = document.createElement('button')
+ document.body.append(target)
+
+ const popperRef = createRef()
+
+ const mounted = render(
+
+
+ Popper content
+
+
+ )
+ unmount = mounted.unmount
+
+ const { popper } = await waitForPopper()
+ vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(100, 50, 40, 20))
+
+ await act(async () => {
+ await popperRef.current?.adjust()
+ })
+
+ await waitFor(() => {
+ expectAnimationSide(popper, 'left')
})
})
})
diff --git a/m3-react/tests/M3Popper.test.tsx b/m3-react/tests/M3Popper.test.tsx
index 1eba043..2fc1ca7 100644
--- a/m3-react/tests/M3Popper.test.tsx
+++ b/m3-react/tests/M3Popper.test.tsx
@@ -22,10 +22,14 @@ const rect = (x: number, y: number, width: number, height: number): DOMRect => (
const waitForPopper = async () => {
await waitFor(() => {
+ expect(document.body.querySelector('.m3-popper-positioner')).not.toBeNull()
expect(document.body.querySelector('.m3-popper')).not.toBeNull()
})
- return document.body.querySelector('.m3-popper') as HTMLElement
+ return {
+ positioner: document.body.querySelector('.m3-popper-positioner') as HTMLElement,
+ popper: document.body.querySelector('.m3-popper') as HTMLElement,
+ }
}
describe('m3-react/popper', () => {
@@ -79,7 +83,7 @@ describe('m3-react/popper', () => {
fireEvent.focus(target)
- const popper = await waitForPopper()
+ const { popper } = await waitForPopper()
await waitFor(() => {
expect(popper.classList.contains('m3-popper_shown')).toBe(true)
})
@@ -107,7 +111,7 @@ describe('m3-react/popper', () => {
)
unmount = mounted.unmount
- const popper = await waitForPopper()
+ const { popper } = await waitForPopper()
await waitFor(() => {
expect(popper.classList.contains('m3-popper_shown')).toBe(true)
})
@@ -142,7 +146,10 @@ describe('m3-react/popper', () => {
)
unmount = mounted.unmount
- const popper = await waitForPopper()
+ const {
+ popper,
+ positioner,
+ } = await waitForPopper()
vi.spyOn(target, 'getBoundingClientRect').mockReturnValue(rect(-10000, -10000, 40, 20))
@@ -151,7 +158,7 @@ describe('m3-react/popper', () => {
})
await waitFor(() => {
- expect(popper.style.position).toBe('absolute')
+ expect(positioner.style.position).toBe('absolute')
expect(popper.classList.contains('m3-popper_shown')).toBe(false)
})
})
diff --git a/m3-react/tests/M3SideSheet.test.tsx b/m3-react/tests/M3SideSheet.test.tsx
new file mode 100644
index 0000000..7840a6b
--- /dev/null
+++ b/m3-react/tests/M3SideSheet.test.tsx
@@ -0,0 +1,101 @@
+import {
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react'
+
+import { M3Icon } from '@/components/icon'
+import { M3SideSheet } from '@/components/side-sheet'
+
+vi.mock('@/components/scroll-rail', () => ({
+ M3ScrollRail: () => ,
+}))
+
+describe('m3-react/side-sheet', () => {
+ test('renders dialog and default aria-labelledby', () => {
+ render(
+
+
+ Panel title
+
+
+ Panel content
+
+ )
+
+ const dialog = screen.getByRole('dialog')
+ const labelId = dialog.getAttribute('aria-labelledby') as string
+
+ expect(screen.getByText('Panel content')).not.toBeNull()
+ expect(document.getElementById(labelId)?.textContent?.trim()).toBe('Panel title')
+ })
+
+ test('keeps title in header and footer outside scroll content', () => {
+ render(
+
+
+ Panel title
+
+
+ Panel content
+
+
+ Footer actions
+
+
+ )
+
+ const title = screen.getByText('Panel title')
+ const content = screen.getByText('Panel content')
+ const footer = screen.getByText('Footer actions')
+
+ expect(title.closest('.m3-side-sheet__header')).not.toBeNull()
+ expect(title.closest('.m3-side-sheet__content')).toBeNull()
+ expect(content.closest('.m3-side-sheet__content')).not.toBeNull()
+ expect(footer.closest('.m3-side-sheet__footer')).not.toBeNull()
+ expect(footer.closest('.m3-side-sheet__content')).toBeNull()
+ })
+
+ test('emits close request on scrim click when not docked', async () => {
+ const onToggle = vi.fn()
+
+ render(
+
+
+ Panel title
+
+
+ )
+
+ await waitFor(() => {
+ expect(document.body.querySelector('.m3-surface__scrim')).not.toBeNull()
+ })
+
+ const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
+
+ fireEvent.click(scrim)
+
+ expect(onToggle).toHaveBeenCalledWith(false)
+ })
+
+ test('emits close request on close button click', () => {
+ const onToggle = vi.fn()
+
+ render(
+
+
+ Panel title
+
+
+
+
+
+
+ )
+
+ fireEvent.click(screen.getByRole('button'))
+
+ expect(onToggle).toHaveBeenCalledWith(false)
+ })
+})
diff --git a/m3-react/tests/M3Surface.test.tsx b/m3-react/tests/M3Surface.test.tsx
new file mode 100644
index 0000000..f888596
--- /dev/null
+++ b/m3-react/tests/M3Surface.test.tsx
@@ -0,0 +1,112 @@
+import {
+ fireEvent,
+ render,
+ screen,
+} from '@testing-library/react'
+
+import { M3Surface } from '@/components/surface'
+
+describe('m3-react/surface', () => {
+ test('applies deterministic default contract', () => {
+ render(
+
+ Surface body
+
+ )
+
+ const surface = screen.getByRole('region')
+
+ expect(surface.classList.contains('m3-surface')).toBe(true)
+ expect(surface.style.width).toBe('100%')
+ expect(surface.style.height).toBe('100%')
+ expect(surface.style.margin).toBe('')
+ expect(surface.style.padding).toBe('')
+ expect(surface.style.borderTopLeftRadius).toBe('0px')
+ expect(surface.style.borderTopRightRadius).toBe('0px')
+ expect(surface.style.borderBottomRightRadius).toBe('0px')
+ expect(surface.style.borderBottomLeftRadius).toBe('0px')
+ expect(surface.style.boxSizing).toBe('')
+ })
+
+ test('supports global and per-corner rounding overrides', () => {
+ render(
+
+ )
+
+ const surface = screen.getByRole('region')
+
+ expect(surface.style.borderTopLeftRadius).toBe('4px')
+ expect(surface.style.borderTopRightRadius).toBe('16px')
+ expect(surface.style.borderBottomRightRadius).toBe('24px')
+ expect(surface.style.borderBottomLeftRadius).toBe('16px')
+ })
+
+ test('emits close request and dismiss on scrim click in modal mode', () => {
+ const onToggle = vi.fn()
+ const onDismiss = vi.fn()
+
+ render(
+
+ Modal body
+
+ )
+
+ const scrim = document.body.querySelector('.m3-surface__scrim') as HTMLElement
+
+ fireEvent.click(scrim)
+
+ expect(onToggle).toHaveBeenCalledWith(false)
+ expect(onDismiss).toHaveBeenCalledTimes(1)
+ })
+
+ test('anchors modal surface to center with fixed positioning', () => {
+ render(
+
+ )
+
+ const surface = screen.getByRole('dialog')
+
+ expect(surface.style.position).toBe('fixed')
+ expect(surface.style.top).toBe('50%')
+ expect(surface.style.left).toBe('50%')
+ expect(surface.style.transform).toContain('translate(-50%, -50%)')
+ expect(surface.style.width).toBe('320px')
+ expect(surface.style.height).toBe('240px')
+ })
+
+ test('maps auto role from elevation and allows explicit variant override', () => {
+ const { rerender } = render(
+
+ )
+
+ let surface = screen.getByRole('region')
+
+ expect(surface.classList.contains('m3-surface_container-high')).toBe(true)
+
+ rerender(
+
+ )
+
+ surface = screen.getByRole('region')
+
+ expect(surface.classList.contains('m3-surface_bright')).toBe(true)
+ expect(surface.classList.contains('m3-surface_container-high')).toBe(false)
+ })
+})
diff --git a/m3-react/tests/M3SurfacePanel.test.tsx b/m3-react/tests/M3SurfacePanel.test.tsx
new file mode 100644
index 0000000..04d5b92
--- /dev/null
+++ b/m3-react/tests/M3SurfacePanel.test.tsx
@@ -0,0 +1,61 @@
+import {
+ render,
+ screen,
+} from '@testing-library/react'
+
+import { M3SurfacePanel } from '@/components/surface'
+
+describe('m3-react/surface-panel', () => {
+ test('renders deterministic static panel contract without implicit landmark role', () => {
+ render(
+
+ Surface body
+
+ )
+
+ const surface = screen.getByText('Surface body').closest('.m3-surface') as HTMLElement
+
+ expect(surface).not.toBeNull()
+ expect(surface.getAttribute('role')).toBeNull()
+ expect(surface.style.width).toBe('100%')
+ expect(surface.style.height).toBe('100%')
+ expect(surface.style.borderTopLeftRadius).toBe('0px')
+ expect(surface.style.borderBottomLeftRadius).toBe('0px')
+ })
+
+ test('supports global and per-corner rounding overrides', () => {
+ render(
+
+ )
+
+ const surface = document.querySelector('.m3-surface') as HTMLElement
+
+ expect(surface.style.borderTopLeftRadius).toBe('4px')
+ expect(surface.style.borderTopRightRadius).toBe('16px')
+ expect(surface.style.borderBottomRightRadius).toBe('24px')
+ expect(surface.style.borderBottomLeftRadius).toBe('16px')
+ })
+
+ test('maps auto variant from elevation and allows explicit variant override', () => {
+ const { rerender } = render(
+
+ )
+
+ let surface = document.querySelector('.m3-surface') as HTMLElement
+
+ expect(surface.classList.contains('m3-surface_container-high')).toBe(true)
+
+ rerender(
+
+ )
+
+ surface = document.querySelector('.m3-surface') as HTMLElement
+
+ expect(surface.classList.contains('m3-surface_bright')).toBe(true)
+ expect(surface.classList.contains('m3-surface_container-high')).toBe(false)
+ })
+})
diff --git a/m3-react/vitest.config.e2e.ts b/m3-react/vitest.config.e2e.ts
index 7e60021..ce0869c 100644
--- a/m3-react/vitest.config.e2e.ts
+++ b/m3-react/vitest.config.e2e.ts
@@ -19,6 +19,7 @@ export default mergeConfig(viteConfig, defineConfig({
test: {
name: 'm3-react-e2e',
globals: true,
+ attachmentsDir: join(__artifacts, 'playwright', 'attachments'),
include: [
'tests/**/*.e2e.tsx',
],
diff --git a/m3-react/vitest.config.ts b/m3-react/vitest.config.ts
index be1257b..12e14df 100644
--- a/m3-react/vitest.config.ts
+++ b/m3-react/vitest.config.ts
@@ -1,14 +1,21 @@
import {
- defineConfig,
- mergeConfig,
+ defineConfig,
+ mergeConfig,
} from 'vitest/config'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
import viteConfig from './vite.config'
+const __parent = fileURLToPath(new URL('../', import.meta.url))
+const __artifacts = join(__parent, 'artifacts', 'm3-react')
+
export default mergeConfig(viteConfig, defineConfig({
- test: {
- name: 'm3-react',
- globals: true,
- environment: 'jsdom',
- },
+ test: {
+ name: 'm3-react',
+ globals: true,
+ environment: 'jsdom',
+ attachmentsDir: join(__artifacts, 'vitest', 'attachments'),
+ },
}))
diff --git a/m3-vue/eslint.config.js b/m3-vue/eslint.config.js
index de9716d..d1083e4 100644
--- a/m3-vue/eslint.config.js
+++ b/m3-vue/eslint.config.js
@@ -161,5 +161,19 @@ export default [
'max-lines-per-function': 'off',
},
},
+ {
+ files: [
+ '**/*.e2e.ts',
+ '**/*.e2e.tsx',
+ '**/*.e2e.test.ts',
+ '**/*.e2e.test.tsx',
+ '**/*.smote.ts',
+ '**/*.smoke.ts',
+ ],
+ rules: {
+ 'max-lines': 'off',
+ 'max-lines-per-function': 'off',
+ },
+ },
{ ignores: ['dist/*'] },
]
diff --git a/m3-vue/package.json b/m3-vue/package.json
index 94c7355..d5d62da 100644
--- a/m3-vue/package.json
+++ b/m3-vue/package.json
@@ -70,6 +70,7 @@
"eslint-plugin-vue": "^10.8.0",
"flag-icons": "^7.5.0",
"globals": "^17.3.0",
+ "highlight.js": "^11.11.1",
"jsdom": "^28.1.0",
"playwright": "^1.55.0",
"react": "^18.3.1",
diff --git a/m3-vue/src/components/dialog/M3Dialog.vue b/m3-vue/src/components/dialog/M3Dialog.vue
index 85225a5..91a938f 100644
--- a/m3-vue/src/components/dialog/M3Dialog.vue
+++ b/m3-vue/src/components/dialog/M3Dialog.vue
@@ -1,58 +1,87 @@
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
+
+const dialogMounted = ref(props.opened)
+const dialogVisible = ref(false)
+let enterFrame: number | null = null
+let leaveTimer: number | null = null
+
+const dialogStyle = computed(() => ({
+ opacity: dialogVisible.value ? 1 : 0,
+ transform: props.fullscreen
+ ? 'translate3d(0, 0, 0)'
+ : (dialogVisible.value
+ ? 'translate(-50%, -50%)'
+ : `translate(-50%, calc(-50% + ${DIALOG_ENTRY_OFFSET_PX}px))`),
+ transition: `opacity ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_TIMING}, transform ${DIALOG_TRANSITION_MS}ms ${DIALOG_TRANSITION_TIMING}`,
+ pointerEvents: dialogVisible.value ? 'auto' : 'none',
+}))
+
+const clearAnimationHandles = () => {
+ if (enterFrame !== null) {
+ window.cancelAnimationFrame(enterFrame)
+ enterFrame = null
+ }
+
+ if (leaveTimer !== null) {
+ window.clearTimeout(leaveTimer)
+ leaveTimer = null
+ }
+}
+
+watch(() => props.opened, async (opened) => {
+ clearAnimationHandles()
+
+ if (opened) {
+ dialogMounted.value = true
+ dialogVisible.value = false
+ await nextTick()
+
+ enterFrame = window.requestAnimationFrame(() => {
+ enterFrame = null
+ dialogVisible.value = true
+ })
+
+ return
+ }
+
+ dialogVisible.value = false
+
+ if (!dialogMounted.value) {
+ return
+ }
+
+ leaveTimer = window.setTimeout(() => {
+ leaveTimer = null
+ dialogMounted.value = false
+ }, DIALOG_TRANSITION_MS)
+}, {
+ immediate: true,
+})
+
+onBeforeUnmount(() => {
+ clearAnimationHandles()
+})
+
diff --git a/m3-vue/src/components/menu/M3Menu.vue b/m3-vue/src/components/menu/M3Menu.vue
index 4e4d1db..62b0df5 100644
--- a/m3-vue/src/components/menu/M3Menu.vue
+++ b/m3-vue/src/components/menu/M3Menu.vue
@@ -12,6 +12,7 @@
:offset-cross-axis="offsetCrossAxis"
:delay="delay"
:disabled="disabled"
+ animated
:detach-timeout="detachTimeout"
v-bind="$attrs"
class="m3-menu"
@@ -133,4 +134,4 @@ defineEmits([
'hidden',
'update:shown',
])
-
\ No newline at end of file
+
diff --git a/m3-vue/src/components/popper/M3Popper.vue b/m3-vue/src/components/popper/M3Popper.vue
index edd7e70..77189a5 100644
--- a/m3-vue/src/components/popper/M3Popper.vue
+++ b/m3-vue/src/components/popper/M3Popper.vue
@@ -4,15 +4,21 @@
:to="container"
>
@@ -155,6 +161,11 @@ const props = defineProps({
default: false,
},
+ animated: {
+ type: Boolean,
+ default: false,
+ },
+
detachTimeout: {
type: null as unknown as PropType,
validator: Or(isNull, isNumeric),
@@ -174,6 +185,7 @@ const emit = defineEmits([
])
const target = computed(() => typeof props.target === 'function' ? props.target() : props.target?.value)
+const positioner = ref(null)
const popper = ref(null)
const positioning = computed(() => ({
@@ -197,21 +209,75 @@ const state = reactive({
const delay = computed(() => normalizeDelay(props.delay))
+const animationBySide = {
+ top: {
+ originX: 'center',
+ originY: 'bottom',
+ enterX: '0px',
+ enterY: '-2px',
+ scaleX: '0.995',
+ scaleY: '0.72',
+ },
+ bottom: {
+ originX: 'center',
+ originY: 'top',
+ enterX: '0px',
+ enterY: '2px',
+ scaleX: '0.995',
+ scaleY: '0.72',
+ },
+ left: {
+ originX: 'right',
+ originY: 'center',
+ enterX: '-2px',
+ enterY: '0px',
+ scaleX: '0.72',
+ scaleY: '0.995',
+ },
+ right: {
+ originX: 'left',
+ originY: 'center',
+ enterX: '2px',
+ enterY: '0px',
+ scaleX: '0.72',
+ scaleY: '0.995',
+ },
+} as const
+
+const applyAnimationSide = (side: 'top' | 'bottom' | 'left' | 'right') => {
+ const style = popper.value?.style
+ if (!style) {
+ return
+ }
+
+ const preset = animationBySide[side]
+ style.setProperty('--m3-popper-origin-x', preset.originX)
+ style.setProperty('--m3-popper-origin-y', preset.originY)
+ style.setProperty('--m3-popper-enter-x', preset.enterX)
+ style.setProperty('--m3-popper-enter-y', preset.enterY)
+ style.setProperty('--m3-popper-scale-x-hidden', preset.scaleX)
+ style.setProperty('--m3-popper-scale-y-hidden', preset.scaleY)
+}
+
const adjust = async () => {
- if (target.value && popper.value && !state.disposed) {
- await computePosition(popper.value, target.value, {
+ if (target.value && positioner.value && !state.disposed) {
+ const result = await computePosition(positioner.value, target.value, {
...positioning.value,
onReferenceHidden: hide,
})
+
+ if (props.animated) {
+ applyAnimationSide(result.side)
+ }
}
}
-const contains = (el: Element | null): boolean => popper.value?.contains(el) ?? false
+const contains = (el: Element | null): boolean => positioner.value?.contains(el) ?? false
const {
autoAdjustOn,
autoAdjustOff,
-} = useAutoUpdate(target, popper, adjust)
+} = useAutoUpdate(target, positioner, adjust)
const showingScheduler = new Scheduler()
const detachScheduler = new Scheduler()
@@ -332,8 +398,8 @@ const initialize = (disposed = false): void => {
targetListener.start(target.value, props.targetTriggers)
}
- if (popper.value) {
- popperListener.start(popper.value, props.popperTriggers)
+ if (positioner.value) {
+ popperListener.start(positioner.value, props.popperTriggers)
}
} else {
state.disposed = true
@@ -400,6 +466,17 @@ watch(() => props.disabled, disabled => {
}
})
+watch(() => props.animated, animated => {
+ if (!animated && popper.value) {
+ popper.value.style.removeProperty('--m3-popper-origin-x')
+ popper.value.style.removeProperty('--m3-popper-origin-y')
+ popper.value.style.removeProperty('--m3-popper-enter-x')
+ popper.value.style.removeProperty('--m3-popper-enter-y')
+ popper.value.style.removeProperty('--m3-popper-scale-x-hidden')
+ popper.value.style.removeProperty('--m3-popper-scale-y-hidden')
+ }
+})
+
onMounted(() => {
globalEvents.on('click', onGlobalClick)
globalEvents.on('mousedown', onGlobalMousedown)
@@ -425,4 +502,4 @@ onBeforeUnmount(() => {
dispose()
})
-
\ No newline at end of file
+
diff --git a/m3-vue/src/components/side-sheet/M3SideSheet.vue b/m3-vue/src/components/side-sheet/M3SideSheet.vue
index f90d023..9df30e7 100644
--- a/m3-vue/src/components/side-sheet/M3SideSheet.vue
+++ b/m3-vue/src/components/side-sheet/M3SideSheet.vue
@@ -1,71 +1,75 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+
+
+
+
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
+const surfaceMounted = ref(props.shown)
+const transitionState = ref
('idle')
+let transitionTimeout: number | null = null
+
+const surfaceClass = computed(() => ({
+ 'm3-side-sheet': true,
+ 'm3-side-sheet_docked': props.docked,
+ 'm3-transition-slide-right-enter': transitionState.value === 'pre-enter' || transitionState.value === 'entering',
+ 'm3-transition-slide-right-enter-active': transitionState.value === 'entering',
+ 'm3-transition-slide-right-leave-active': transitionState.value === 'pre-exit' || transitionState.value === 'exiting',
+ 'm3-transition-slide-right-leave-to': transitionState.value === 'exiting',
+}))
+
+const headerClass = computed(() => ({
+ 'm3-side-sheet__header': true,
+ 'm3-side-sheet__header_has-leading-affordance': 'affordance' in slots,
+}))
+
+const surfaceScrimShown = computed(() => !props.docked && props.shown && transitionState.value !== 'pre-enter')
+
+const surfaceAttrs = computed(() => ({
+ ...attrs,
+ ...('aria-label' in attrs || 'aria-labelledby' in attrs ? {} : {
+ 'aria-labelledby': _id.value + '-title',
+ }),
+ ...('aria-modal' in attrs || !props.docked ? {} : {
+ 'aria-modal': 'false',
+ }),
+}))
+
+function clearTransitionTimer() {
+ if (transitionTimeout === null) {
+ return
+ }
+
+ clearTimeout(transitionTimeout)
+ transitionTimeout = null
+}
+
+async function enterSurface() {
+ clearTransitionTimer()
+ surfaceMounted.value = true
+ transitionState.value = 'pre-enter'
+
+ await nextTick()
+ await new Promise(resolve => requestAnimationFrame(() => resolve()))
+
+ transitionState.value = 'entering'
+ transitionTimeout = window.setTimeout(() => {
+ transitionState.value = 'idle'
+ transitionTimeout = null
+ }, SIDE_SHEET_TRANSITION_MS)
+}
+
+async function leaveSurface() {
+ if (!surfaceMounted.value) {
+ transitionState.value = 'idle'
+ return
+ }
+
+ clearTransitionTimer()
+ transitionState.value = 'pre-exit'
+
+ await nextTick()
+ await new Promise(resolve => requestAnimationFrame(() => resolve()))
+
+ transitionState.value = 'exiting'
+ transitionTimeout = window.setTimeout(() => {
+ surfaceMounted.value = false
+ transitionState.value = 'idle'
+ transitionTimeout = null
+ }, SIDE_SHEET_TRANSITION_MS)
+}
+
+watch(() => props.shown, (shown) => {
+ void (shown ? enterSurface() : leaveSurface())
+}, {
+ immediate: true,
+})
+
+onBeforeUnmount(() => {
+ clearTransitionTimer()
+})
+
diff --git a/m3-vue/src/components/surface/M3Surface.vue b/m3-vue/src/components/surface/M3Surface.vue
new file mode 100644
index 0000000..4b3c76b
--- /dev/null
+++ b/m3-vue/src/components/surface/M3Surface.vue
@@ -0,0 +1,202 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/m3-vue/src/components/surface/M3SurfacePanel.vue b/m3-vue/src/components/surface/M3SurfacePanel.vue
new file mode 100644
index 0000000..05036e7
--- /dev/null
+++ b/m3-vue/src/components/surface/M3SurfacePanel.vue
@@ -0,0 +1,52 @@
+
+
+
+
+
+
+
diff --git a/m3-vue/src/components/surface/index.ts b/m3-vue/src/components/surface/index.ts
new file mode 100644
index 0000000..5db01f7
--- /dev/null
+++ b/m3-vue/src/components/surface/index.ts
@@ -0,0 +1,2 @@
+export { default as M3SurfacePanel } from './M3SurfacePanel.vue'
+export { default as M3Surface } from './M3Surface.vue'
diff --git a/m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts b/m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
new file mode 100644
index 0000000..13a850b
--- /dev/null
+++ b/m3-vue/src/components/surface/orchestration/useSurfaceCardPageMorph.ts
@@ -0,0 +1,201 @@
+/* eslint-disable max-lines-per-function */
+import {
+ computed,
+ onBeforeUnmount,
+ nextTick,
+ onMounted,
+ ref,
+} from 'vue'
+
+import {
+ measureContainerRect,
+ measureRelativeRect,
+ raf,
+ toMotionStyle,
+ type SurfaceMotionRect,
+ wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
+
+export function useSurfaceCardPageMorph(transitionMs: number) {
+ const expanded = ref(false)
+ const busy = ref(false)
+ const backgroundCollapsed = ref(false)
+ const originHeight = ref(220)
+ const canvas = ref(null)
+ const originSlot = ref(null)
+ let observer: ResizeObserver | null = null
+ const syncFrame = ref(null)
+ const motion = ref({
+ top: 16,
+ left: 16,
+ width: 320,
+ height: 220,
+ })
+
+ const overlayStyle = computed(() => toMotionStyle(motion.value))
+
+ function measureOrigin() {
+ return measureRelativeRect(canvas.value, originSlot.value)
+ }
+
+ function measureExpanded() {
+ return measureContainerRect(canvas.value)
+ }
+
+ function syncMotionToLayout() {
+ const origin = measureOrigin()
+
+ if (origin) {
+ originHeight.value = origin.height
+ }
+
+ if (expanded.value) {
+ const full = measureExpanded()
+
+ if (full) {
+ motion.value = full
+ }
+
+ return
+ }
+
+ if (!origin || backgroundCollapsed.value) {
+ return
+ }
+
+ motion.value = origin
+ }
+
+ function scheduleSyncMotion() {
+ if (syncFrame.value !== null) {
+ cancelAnimationFrame(syncFrame.value)
+ }
+
+ syncFrame.value = requestAnimationFrame(() => {
+ syncFrame.value = null
+ syncMotionToLayout()
+ })
+ }
+
+ async function initMotion() {
+ await nextTick()
+ await raf()
+
+ const origin = measureOrigin()
+ if (!origin) {
+ return
+ }
+
+ motion.value = origin
+ originHeight.value = origin.height
+ }
+
+ async function expandCard() {
+ backgroundCollapsed.value = false
+
+ const origin = measureOrigin()
+ if (origin) {
+ motion.value = origin
+ originHeight.value = origin.height
+ }
+
+ expanded.value = true
+ await nextTick()
+ await raf()
+
+ const full = measureExpanded()
+ if (!full) {
+ return
+ }
+
+ motion.value = full
+ await wait(transitionMs)
+ backgroundCollapsed.value = true
+ }
+
+ async function collapseCard() {
+ if (backgroundCollapsed.value) {
+ backgroundCollapsed.value = false
+ await nextTick()
+ await raf()
+ }
+
+ const full = measureExpanded()
+ if (full) {
+ motion.value = full
+ }
+
+ const origin = measureOrigin()
+ if (origin) {
+ originHeight.value = origin.height
+ }
+
+ expanded.value = false
+ await nextTick()
+ await raf()
+
+ if (!origin) {
+ return
+ }
+
+ motion.value = origin
+ await wait(transitionMs)
+ }
+
+ async function toggleCardMode() {
+ if (busy.value) {
+ return
+ }
+
+ busy.value = true
+
+ if (expanded.value) {
+ await collapseCard()
+ busy.value = false
+ return
+ }
+
+ await expandCard()
+ busy.value = false
+ }
+
+ onMounted(() => {
+ initMotion()
+
+ if (typeof ResizeObserver === 'undefined') {
+ return
+ }
+
+ observer = new ResizeObserver(() => {
+ scheduleSyncMotion()
+ })
+
+ if (canvas.value && observer) {
+ observer.observe(canvas.value)
+ }
+
+ if (originSlot.value && observer) {
+ observer.observe(originSlot.value)
+ }
+ })
+
+ onBeforeUnmount(() => {
+ observer?.disconnect()
+
+ if (syncFrame.value !== null) {
+ cancelAnimationFrame(syncFrame.value)
+ syncFrame.value = null
+ }
+ })
+
+ return {
+ expanded,
+ busy,
+ backgroundCollapsed,
+ originHeight,
+ overlayStyle,
+ canvas,
+ originSlot,
+ toggleCardMode,
+ }
+}
diff --git a/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts b/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
new file mode 100644
index 0000000..e4f72cb
--- /dev/null
+++ b/m3-vue/src/components/surface/orchestration/useSurfaceSideSheetMorph.ts
@@ -0,0 +1,266 @@
+/* eslint-disable max-lines-per-function */
+import {
+ computed,
+ nextTick,
+ onBeforeUnmount,
+ onMounted,
+ ref,
+} from 'vue'
+
+import { getSurfaceStateDescriptor } from '@modulify/m3-foundation/lib/surface/descriptor'
+import { m3MotionDurations } from '@modulify/m3-foundation/lib/motion'
+
+import {
+ raf,
+ wait,
+} from '@modulify/m3-foundation/lib/surface/orchestration'
+
+const SIDE_SHEET_WIDTH_MIN = 280
+const SIDE_SHEET_WIDTH_MAX = 360
+const SIDE_SHEET_WIDTH_RATIO = 32
+
+const MODAL_INSET_TOP = 0
+const MODAL_INSET_BOTTOM = 0
+const MODAL_INSET_END = 0
+const PANEL_TRANSITION_MS = m3MotionDurations.medium2
+const DOCKED_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('docked_side_sheet')
+const MODAL_SIDE_SHEET_DESCRIPTOR = getSurfaceStateDescriptor('modal_side_sheet')
+const DOCKED_HOST_WIDTH = `clamp(${SIDE_SHEET_WIDTH_MIN}px, ${SIDE_SHEET_WIDTH_RATIO}%, ${SIDE_SHEET_WIDTH_MAX}px)`
+
+export function useSurfaceSideSheetMorph() {
+ type SurfaceGeometry = {
+ width: number;
+ insetTop: number;
+ insetRight: number;
+ insetBottom: number;
+ }
+
+ const sideSheetModal = ref(false)
+ const sideSheetWidth = ref(SIDE_SHEET_WIDTH_MIN)
+ const dockedHostExpanded = ref(true)
+ const dockedPanelShown = ref(true)
+ const dockedPanelHidden = ref(false)
+ const modalShown = ref(false)
+ const modalScrimShown = ref(false)
+ const modalWidth = ref(sideSheetWidth.value)
+ const modalInsetTop = ref(MODAL_INSET_TOP)
+ const modalInsetRight = ref(MODAL_INSET_END)
+ const modalInsetBottom = ref(MODAL_INSET_BOTTOM)
+ const modalRadiusLeft = ref(DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft)
+ const modalElevation = ref(DOCKED_SIDE_SHEET_DESCRIPTOR.elevation)
+ const modalRole = ref<'surface-container-low' | 'surface-container-high'>(DOCKED_SIDE_SHEET_DESCRIPTOR.variant)
+ const modalTransitionMs = ref(PANEL_TRANSITION_MS)
+ const transitioning = ref(false)
+ const lastDockedGeometry = ref(null)
+ const dockedHost = ref(null)
+ const layoutRoot = ref(null)
+
+ function measureDockedGeometry() {
+ const host = dockedHost.value
+ if (!host) {
+ return null
+ }
+
+ const rect = host.getBoundingClientRect()
+ const width = Math.round(rect.width)
+
+ if (width > 0) {
+ sideSheetWidth.value = width
+ }
+
+ return {
+ width: width > 0 ? width : sideSheetWidth.value,
+ insetTop: Math.round(rect.top),
+ insetRight: Math.round(window.innerWidth - rect.right),
+ insetBottom: Math.round(window.innerHeight - rect.bottom),
+ }
+ }
+
+ function measureDockedPanelGeometry(): SurfaceGeometry | null {
+ const panel = dockedHost.value?.querySelector('[data-panel-mode="docked"]') as HTMLElement | null
+ if (!panel) {
+ return null
+ }
+
+ const rect = panel.getBoundingClientRect()
+ const geometry = {
+ width: Math.round(rect.width),
+ insetTop: Math.round(rect.top),
+ insetRight: Math.round(window.innerWidth - rect.right),
+ insetBottom: Math.round(window.innerHeight - rect.bottom),
+ }
+
+ sideSheetWidth.value = geometry.width
+ lastDockedGeometry.value = geometry
+
+ return geometry
+ }
+
+ async function syncDockedGeometry() {
+ await nextTick()
+ await raf()
+
+ const docked = measureDockedPanelGeometry() ?? measureDockedGeometry()
+ if (!docked || sideSheetModal.value) {
+ return
+ }
+
+ modalWidth.value = docked.width
+ modalInsetTop.value = docked.insetTop
+ modalInsetRight.value = docked.insetRight
+ modalInsetBottom.value = docked.insetBottom
+ }
+
+ async function switchDockedToModal() {
+ const docked = measureDockedPanelGeometry() ?? measureDockedGeometry()
+ if (!docked) {
+ return
+ }
+
+ modalTransitionMs.value = PANEL_TRANSITION_MS
+ modalWidth.value = docked.width
+ modalInsetTop.value = docked.insetTop
+ modalInsetRight.value = docked.insetRight
+ modalInsetBottom.value = docked.insetBottom
+ modalRadiusLeft.value = DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+ modalElevation.value = DOCKED_SIDE_SHEET_DESCRIPTOR.elevation
+ modalRole.value = DOCKED_SIDE_SHEET_DESCRIPTOR.variant
+ dockedPanelShown.value = true
+ dockedPanelHidden.value = true
+ modalShown.value = true
+
+ await nextTick()
+ await raf()
+
+ modalScrimShown.value = MODAL_SIDE_SHEET_DESCRIPTOR.scrim
+ dockedHostExpanded.value = false
+ sideSheetModal.value = true
+ modalWidth.value = docked.width
+ modalInsetTop.value = MODAL_INSET_TOP
+ modalInsetRight.value = MODAL_INSET_END
+ modalInsetBottom.value = MODAL_INSET_BOTTOM
+ modalRadiusLeft.value = MODAL_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+ modalElevation.value = MODAL_SIDE_SHEET_DESCRIPTOR.elevation
+ modalRole.value = MODAL_SIDE_SHEET_DESCRIPTOR.variant
+
+ await wait(PANEL_TRANSITION_MS)
+
+ dockedPanelShown.value = false
+ }
+
+ async function switchModalToDocked() {
+ dockedHostExpanded.value = true
+ dockedPanelShown.value = true
+ dockedPanelHidden.value = true
+
+ await nextTick()
+ await raf()
+
+ const dockedTarget = lastDockedGeometry.value ?? measureDockedPanelGeometry() ?? measureDockedGeometry()
+ if (!dockedTarget) {
+ return
+ }
+
+ modalTransitionMs.value = PANEL_TRANSITION_MS
+ modalScrimShown.value = false
+ modalElevation.value = DOCKED_SIDE_SHEET_DESCRIPTOR.elevation
+ modalRole.value = DOCKED_SIDE_SHEET_DESCRIPTOR.variant
+ modalRadiusLeft.value = DOCKED_SIDE_SHEET_DESCRIPTOR.rounding.topLeft
+ modalWidth.value = dockedTarget.width
+ modalInsetTop.value = dockedTarget.insetTop
+ modalInsetRight.value = dockedTarget.insetRight
+ modalInsetBottom.value = dockedTarget.insetBottom
+
+ await wait(PANEL_TRANSITION_MS)
+
+ sideSheetModal.value = false
+ modalShown.value = false
+ dockedPanelHidden.value = false
+ }
+
+ async function toggleSideSheetMode() {
+ if (transitioning.value) {
+ return
+ }
+
+ transitioning.value = true
+
+ if (!sideSheetModal.value) {
+ await switchDockedToModal()
+ transitioning.value = false
+ return
+ }
+
+ await switchModalToDocked()
+ transitioning.value = false
+ }
+
+ async function closeModalFromPanel() {
+ if (!sideSheetModal.value || transitioning.value) {
+ return
+ }
+
+ transitioning.value = true
+ await switchModalToDocked()
+ transitioning.value = false
+ }
+
+ async function onResize() {
+ if (dockedHostExpanded.value) {
+ await syncDockedGeometry()
+ }
+ }
+
+ onMounted(async () => {
+ await syncDockedGeometry()
+ window.addEventListener('resize', onResize, { passive: true })
+ })
+
+ onBeforeUnmount(() => {
+ window.removeEventListener('resize', onResize)
+ })
+
+ const dockedHostStyle = computed(() => ({
+ width: dockedHostExpanded.value ? DOCKED_HOST_WIDTH : '0px',
+ }))
+
+ const dockedPanelStyle = computed(() => ({
+ visibility: dockedPanelHidden.value ? 'hidden' : 'visible',
+ }))
+
+ const modalPanelProps = computed(() => ({
+ shown: true as const,
+ scrimShown: modalScrimShown.value,
+ anchor: MODAL_SIDE_SHEET_DESCRIPTOR.anchor,
+ fillWidth: MODAL_SIDE_SHEET_DESCRIPTOR.fillWidth,
+ fillHeight: MODAL_SIDE_SHEET_DESCRIPTOR.fillHeight,
+ width: modalWidth.value,
+ insetTop: modalInsetTop.value,
+ insetRight: modalInsetRight.value,
+ insetBottom: modalInsetBottom.value,
+ roundingTopLeft: modalRadiusLeft.value,
+ roundingBottomLeft: modalRadiusLeft.value,
+ 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,
+ }))
+
+ return {
+ sideSheetModal,
+ sideSheetWidth,
+ transitioning,
+ modalShown,
+ dockedPanelShown,
+ dockedHost,
+ layoutRoot,
+ dockedHostStyle,
+ dockedPanelStyle,
+ modalPanelProps,
+ toggleSideSheetMode,
+ closeModalFromPanel,
+ }
+}
diff --git a/m3-vue/src/components/surface/shared.ts b/m3-vue/src/components/surface/shared.ts
new file mode 100644
index 0000000..60919fd
--- /dev/null
+++ b/m3-vue/src/components/surface/shared.ts
@@ -0,0 +1,163 @@
+import type {
+ CSSProperties,
+ PropType,
+} from 'vue'
+import type {
+ Length as SurfaceLength,
+ Variant as SurfaceVariant,
+} from '@modulify/m3-foundation/types/components/surface'
+
+import {
+ DEFAULT_SURFACE_TRANSITION_TIMING,
+ getSurfacePanelClassRecord,
+ getSurfacePanelStyle as getFoundationSurfacePanelStyle,
+} from '@modulify/m3-foundation/lib/surface/style'
+
+export {
+ getModalAnchorStyle,
+ getResolvedVariant,
+ getSurfaceTransition,
+ getVariantClassName,
+ isDefined,
+ toLength,
+} from '@modulify/m3-foundation/lib/surface/style'
+import {
+ isId,
+ isUndefined,
+ Or,
+} from '@modulify/m3-foundation/lib/predicates'
+
+export const surfacePanelProps = {
+ id: {
+ type: null as unknown as PropType,
+ validator: Or(isId, isUndefined),
+ default: undefined,
+ },
+
+ tag: {
+ type: String,
+ default: 'section',
+ },
+
+ elevation: {
+ type: Number,
+ default: 0,
+ validator: (value: number) => Number.isInteger(value) && value >= 0 && value <= 5,
+ },
+
+ variant: {
+ type: String as PropType,
+ default: 'auto',
+ },
+
+ fillWidth: {
+ type: Boolean,
+ default: true,
+ },
+
+ fillHeight: {
+ type: Boolean,
+ default: true,
+ },
+
+ width: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ height: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ minWidth: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ maxWidth: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ minHeight: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ maxHeight: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ rounding: {
+ type: null as unknown as PropType,
+ default: 0,
+ },
+
+ roundingTopLeft: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ roundingTopRight: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ roundingBottomRight: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ roundingBottomLeft: {
+ type: null as unknown as PropType,
+ default: null,
+ },
+
+ transitionMs: {
+ type: Number,
+ default: 220,
+ },
+
+ transitionTiming: {
+ type: String,
+ default: DEFAULT_SURFACE_TRANSITION_TIMING,
+ },
+
+ overflow: {
+ type: String,
+ default: 'visible',
+ },
+} as const
+
+export function getSurfacePanelClass(elevation: number, variant: SurfaceVariant) {
+ return getSurfacePanelClassRecord(elevation, variant)
+}
+
+type SurfacePanelStyleInput = {
+ fillWidth: boolean,
+ fillHeight: boolean,
+ width: SurfaceLength | null,
+ height: SurfaceLength | null,
+ minWidth: SurfaceLength | null,
+ maxWidth: SurfaceLength | null,
+ minHeight: SurfaceLength | null,
+ maxHeight: SurfaceLength | null,
+ rounding: SurfaceLength,
+ roundingTopLeft: SurfaceLength | null,
+ roundingTopRight: SurfaceLength | null,
+ roundingBottomRight: SurfaceLength | null,
+ roundingBottomLeft: SurfaceLength | null,
+ transitionMs: number,
+ transitionTiming: string,
+ overflow: CSSProperties['overflow'],
+ style?: CSSProperties,
+}
+
+export const getSurfacePanelStyle = (
+ options: SurfacePanelStyleInput
+): CSSProperties => getFoundationSurfacePanelStyle({
+ ...options,
+ style: options.style as object | undefined,
+}) as CSSProperties
diff --git a/m3-vue/src/index.ts b/m3-vue/src/index.ts
index 43ff0f8..b8ad7e4 100644
--- a/m3-vue/src/index.ts
+++ b/m3-vue/src/index.ts
@@ -78,6 +78,11 @@ export {
M3SideSheet,
} from '@/components/side-sheet'
+export {
+ M3Surface,
+ M3SurfacePanel,
+} from '@/components/surface'
+
export {
M3Slider,
} from '@/components/slider'
@@ -89,4 +94,4 @@ export {
export {
M3TextField,
M3TextFieldSupportText,
-} from '@/components/text-field'
\ No newline at end of file
+} from '@/components/text-field'
diff --git a/m3-vue/storybook/components/Inline.ts b/m3-vue/storybook/components/Inline.ts
index 3593786..734fc4c 100644
--- a/m3-vue/storybook/components/Inline.ts
+++ b/m3-vue/storybook/components/Inline.ts
@@ -5,28 +5,53 @@ import { v4 } from 'uuid'
import { createApp, h } from 'vue'
+const normalizeIdSegment = (value: string): string => {
+ return value.replace(/[^a-zA-Z0-9_-]/g, '')
+}
+
+const buildInlineIdPrefix = (reactId: string, uuid: string): string => {
+ return `m3-inline-${normalizeIdSegment(reactId)}-${normalizeIdSegment(uuid)}-`
+}
+
+const mountInlineApp = ({ appIdPrefix, children, is, props, root }) => {
+ const id = v4()
+
+ const app = createApp({
+ mounted () {
+ if (children) {
+ ReactDOM.render(
+ React.createElement(React.Fragment, {}, children),
+ document.getElementById(id)
+ )
+ }
+ },
+
+ render: () => h(is, props),
+ })
+
+ app.config.idPrefix = appIdPrefix
+ app.mount(root)
+
+ return () => app.unmount()
+}
+
export default ({ is, children, tag, ...props }) => {
const ref = React.useRef(null)
+ const reactId = React.useId()
+ const uuidRef = React.useRef(v4())
+ const appIdPrefix = React.useMemo(
+ () => buildInlineIdPrefix(reactId, uuidRef.current),
+ [reactId]
+ )
React.useEffect(() => {
- const id = v4()
-
- const app = createApp({
- mounted () {
- if (children) {
- ReactDOM.render(
- React.createElement(React.Fragment, {}, children),
- document.getElementById(id)
- )
- }
- },
-
- render: () => h(is, props),
+ return mountInlineApp({
+ appIdPrefix,
+ children,
+ is,
+ props,
+ root: ref.current,
})
-
- app.mount(ref.current)
-
- return () => app.unmount()
})
return React.createElement(tag ?? 'div', {
diff --git a/m3-vue/storybook/components/M3Button.mdx b/m3-vue/storybook/components/M3Button.mdx
index 13c6818..c3b4276 100644
--- a/m3-vue/storybook/components/M3Button.mdx
+++ b/m3-vue/storybook/components/M3Button.mdx
@@ -7,7 +7,31 @@ import * as M3ButtonStories from './M3Button.stories'
# Buttons
-Common buttons prompt most actions in a UI
+Buttons communicate available actions and establish hierarchy on a surface. Material 3 distinguishes buttons primarily by emphasis, not by feature set.
+
+## API
+
+### When to use
+
+Use `M3Button` for explicit actions such as save, submit, share, or continue. Prefer buttons over links when the result changes UI state or triggers an in-app operation.
+
+### Appearances
+
+- `filled` for the primary action in a region
+- `elevated` when the action should stand out on low-emphasis surfaces
+- `tonal` for prominent but secondary emphasis
+- `outlined` for lower-emphasis alternatives
+- `text` for lightweight supporting actions
+
+### Icons and labels
+
+Leading icons help scanning when the metaphor is widely understood. Keep the text label explicit even when an icon is present, so the action remains readable without relying on symbol recognition alone.
+
+## Accessibility semantics
+
+- Use a clear text label for action buttons.
+- For icon-only actions, provide `aria-label`.
+- Keep disabled actions unavailable through the `disabled` state.
@@ -24,3 +48,34 @@ Common buttons prompt most actions in a UI
+
+## Story guide
+
+- [With Text Only](?path=/story/components-m3button--with-text-only)
+- [With Leading Icon](?path=/story/components-m3button--with-leading-icon)
+- [Appearance Matrix](?path=/story/components-m3button--appearance-matrix)
+- [Disabled States](?path=/story/components-m3button--disabled-states)
+
+## Usage guidance
+
+### Keep hierarchy local
+
+Each region should usually have one highest-emphasis action. If everything is filled, users lose the sense of priority that Material 3 buttons are designed to communicate.
+
+### Disable carefully
+
+Use `disabled` only when the action is genuinely unavailable. If the action is available but risky, keep it enabled and explain the consequence instead of hiding the path forward.
+
+## Code example
+
+```html
+
+ Edit
+
+```
+
+## Resources
+
+- [M3 Buttons overview](https://m3.material.io/components/buttons/overview)
+- [M3 Buttons guidelines](https://m3.material.io/components/buttons/guidelines)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Button.stories.ts b/m3-vue/storybook/components/M3Button.stories.ts
index cc290fc..369f569 100644
--- a/m3-vue/storybook/components/M3Button.stories.ts
+++ b/m3-vue/storybook/components/M3Button.stories.ts
@@ -68,3 +68,71 @@ export const WithLeadingIcon: Story = {
`,
}),
}
+
+export const AppearanceMatrix: Story = {
+ // eslint-disable-next-line max-lines-per-function
+ render: () => ({
+ components: {
+ M3Button,
+ M3Icon,
+ },
+
+ setup () {
+ return {
+ appearances: values.appearances,
+ }
+ },
+
+ template: `
+
+
+
+ Share
+
+
+
+
+
+
+ Share
+
+
+
+
+ Share
+
+
+ `,
+ }),
+}
diff --git a/m3-vue/storybook/components/M3Card.mdx b/m3-vue/storybook/components/M3Card.mdx
index a458dad..9cc6882 100644
--- a/m3-vue/storybook/components/M3Card.mdx
+++ b/m3-vue/storybook/components/M3Card.mdx
@@ -10,9 +10,32 @@ import { defineComponent, h } from 'vue'
# Cards
-Cards display content and actions about a single subject
+Cards group related content and actions into a single container. In Material 3 they work best when they stay focused on one subject, one decision, or one compact summary.
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## API
+
+### When to use
+
+Use `M3Card` when content should feel grouped but still remain embedded in the page flow. If the interaction becomes blocking or needs a scrim, move to `M3Dialog` or `M3Surface`.
+
+### Anatomy
+
+Typical card structure in this workspace includes:
+
+- media or leading visual
+- heading and optional subheading
+- supporting content
+- optional trailing or footer actions
+
+### Appearances
+
+Material 3 cards rely on tone and outline treatment to signal emphasis. This implementation exposes `filled`, `elevated`, and `outlined`, which cover the main hierarchy levels from the official card guidance.
+
+## Accessibility semantics
+
+- Use non-interactive cards as plain content containers.
+- For interactive cards, expose actions with semantic controls (`button` / `link`).
+- Keep a clear heading hierarchy inside cards for screen reader navigation.
h('div', { style: { display: 'flex', flexWrap: 'wrap', gap: '16px' } }, [
@@ -20,3 +43,46 @@ Cards display content and actions about a single subject
h(LiveMusic2),
]),
})} />
+
+## Story guide
+
+- [Landscape](?path=/story/components-m3card--landscape)
+- [Landscape Without Media](?path=/story/components-m3card--landscape-without-media)
+- [Portrait](?path=/story/components-m3card--portrait)
+- [Appearance Matrix](?path=/story/components-m3card--appearance-matrix)
+
+## Usage guidance
+
+### Keep cards focused
+
+Avoid turning a card into a mini page. Once it needs long forms, deep navigation, or persistent editing controls, a larger surface usually communicates the task more clearly.
+
+### Separate container click from inner actions
+
+If the whole card is interactive, nested actions should remain semantically distinct and visually predictable. Competing click targets inside one card quickly become ambiguous.
+
+## Code example
+
+```html
+
+
+ 
+
+
+
+ Title
+
+
+
+ Subhead
+
+
+ Supporting text
+
+```
+
+## Resources
+
+- [M3 Cards overview](https://m3.material.io/components/cards/overview)
+- [M3 Cards guidelines](https://m3.material.io/components/cards/guidelines)
+- [WAI-ARIA APG: Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
diff --git a/m3-vue/storybook/components/M3Card.stories.ts b/m3-vue/storybook/components/M3Card.stories.ts
index f6c009b..7084269 100644
--- a/m3-vue/storybook/components/M3Card.stories.ts
+++ b/m3-vue/storybook/components/M3Card.stories.ts
@@ -132,3 +132,39 @@ export const Portrait: Story = {
`,
}),
}
+
+export const AppearanceMatrix: Story = {
+ // eslint-disable-next-line max-lines-per-function
+ render: () => ({
+ components: {
+ M3Card,
+ },
+
+ setup () {
+ return {
+ appearances: ['filled', 'elevated', 'outlined'],
+ }
+ },
+
+ template: `
+
+
+
+ {{ appearance }}
+
+
+
+ Card emphasis
+
+
+ Supporting text for the current card style.
+
+
+ `,
+ }),
+}
diff --git a/m3-vue/storybook/components/M3Checkbox.mdx b/m3-vue/storybook/components/M3Checkbox.mdx
index 459511e..5199ab7 100644
--- a/m3-vue/storybook/components/M3Checkbox.mdx
+++ b/m3-vue/storybook/components/M3Checkbox.mdx
@@ -7,11 +7,31 @@ import * as M3CheckboxStories from './M3Checkbox.stories'
# Checkboxes
-Checkboxes let users select one or more items from a list, or turn an item on or off
+Checkboxes let users select one or more options independently. They also support parent-child selection patterns where a parent reflects the aggregate state of subordinate items.
-[Design Kit (Figma)](https://www.figma.com/community/file/1035203688168086460)
+## API
-[Guidelines](https://m3.material.io/components/checkbox/guidelines)
+### When to use
+
+Use `M3Checkbox` when multiple items can be selected at the same time, or when a single option behaves like a boolean choice inside a form. If the user must pick exactly one option, prefer radios instead.
+
+### Selection model
+
+This implementation supports both simple boolean selection and array-backed multi-select models. It also supports `indeterminate` for aggregate parent rows, which matches the Material 3 guidance for nested selection patterns.
+
+### Nested selection
+
+In nested lists, the parent checkbox should summarize descendant state:
+
+- checked when all descendants are selected
+- indeterminate when some descendants are selected
+- unchecked when none are selected
+
+## Accessibility semantics
+
+- Every checkbox needs a visible text label.
+- Group related checkboxes under a shared group label (`fieldset/legend` or `aria-labelledby`).
+- Use indeterminate state only for partial parent-selection states.
### Regular list
@@ -42,3 +62,24 @@ Checkboxes let users select one or more items from a list, or turn an item on or
value: 'monthly',
}],
}]} />
+
+## Story guide
+
+- [Standard](?path=/story/components-m3checkbox--standard)
+- [Nested Selection](?path=/story/components-m3checkbox--nested-selection)
+
+## Usage guidance
+
+### Keep labels explicit
+
+Checkbox labels should describe the resulting state, not the control itself. "Email receipts" is clearer than "Enable."
+
+### Use indeterminate only as summary state
+
+Do not present `indeterminate` as a user-selectable third state. It should only communicate partial selection across descendants.
+
+## Resources
+
+- [M3 Checkbox overview](https://m3.material.io/components/checkbox/overview)
+- [M3 Checkbox guidelines](https://m3.material.io/components/checkbox/guidelines)
+- [WAI-ARIA APG: Checkbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/)
diff --git a/m3-vue/storybook/components/M3Checkbox.stories.ts b/m3-vue/storybook/components/M3Checkbox.stories.ts
index 30febee..d30f3b7 100644
--- a/m3-vue/storybook/components/M3Checkbox.stories.ts
+++ b/m3-vue/storybook/components/M3Checkbox.stories.ts
@@ -1,6 +1,7 @@
import type { Meta, StoryObj } from '@storybook/vue3'
import { M3Checkbox } from '@/components/checkbox'
+import CheckboxList from '../examples/checkbox/CheckboxList.vue'
import { ref } from 'vue'
import useId from '@/composables/id'
@@ -48,3 +49,30 @@ export default meta
type Story = StoryObj
export const Standard: Story = {}
+
+export const NestedSelection: Story = {
+ render: () => ({
+ components: {
+ CheckboxList,
+ },
+
+ template: `
+
+ `,
+ }),
+}
diff --git a/m3-vue/storybook/components/M3Dialog.mdx b/m3-vue/storybook/components/M3Dialog.mdx
index c7b63f8..8601237 100644
--- a/m3-vue/storybook/components/M3Dialog.mdx
+++ b/m3-vue/storybook/components/M3Dialog.mdx
@@ -5,8 +5,100 @@ import DialogConfirmation from '../examples/dialog/DialogConfirmation.vue'
# Dialogs
+Dialogs communicate important information and block the underlying interface until the user responds.
+
+## API
+
+### When to use
+
+Use `M3Dialog` for short, interruptive decisions that need an explicit user choice before the page can continue. In Material 3 terms this maps best to confirmation, acknowledgement, and blocking task flows rather than to long-form editing or navigation.
+
+### Structure
+
+`M3Dialog` keeps the same content anatomy across React and Vue:
+
+- `icon` slot for a leading visual cue
+- `header` slot for the title area
+- default slot for supporting text or compact form controls
+- `footer` slot for high-signal actions
+
+The component now renders on top of `M3Surface`, so dialog presentation and motion are aligned with the same modal surface vocabulary used by side sheets and orchestration stories.
+
+### Behavior in this implementation
+
+- Non-fullscreen dialogs open as centered modal surfaces with a scrim.
+- Fullscreen dialogs remove the scrim and expand to the viewport.
+- The surface enters with a short fade plus a slight upward settle, matching the modal choreography used in the nested-surface stories.
+- Dialog content stays mounted briefly during exit so the leave animation can finish before unmount.
+
+## Accessibility semantics
+
+- Set `role="dialog"` (or `alertdialog` for urgent confirmations).
+- Provide `aria-modal="true"` for modal flows.
+- Connect title and description with `aria-labelledby` and `aria-describedby`.
+- Keep focus inside the dialog while it is opened.
+- Keep action labels explicit and outcome-oriented.
+