diff --git a/docs/api-migrations.md b/docs/api-migrations.md
index 99d09a3b..6363e688 100644
--- a/docs/api-migrations.md
+++ b/docs/api-migrations.md
@@ -1,5 +1,104 @@
# LUI API migration guide
+### Shared typed slot appearance
+
+`menu_item`, dropdown surfaces and items, toolbar controls and toolbar text
+accept one optional `~style:Slot_style.t` argument. Their ordinary constructors
+accept the same value. The individual appearance arguments added earlier in
+this PR, including their signal twins, have been removed from constructors.
+Pre-existing constructor properties are unchanged.
+
+Build appearance once with `Slot_style.make`: `font_size`, `font_weight`,
+`font_family`, `font_style`, `line_height`, `letter_spacing`, `text_decoration`,
+`white_space`, `text_overflow`, `overflow`, `hover_background`, `hover_foreground`,
+`focus_within_background`, `focus_within_border`, `focus_shadow`, `shadow`,
+`collision_padding`, `cursor`, `user_select`, `disabled_opacity`,
+`pressed_opacity`, `hover_opacity` and `max_height_viewport`. Typed signal twins
+are centralized in this builder only. Inside a style, current signal values win
+over static values and updates retain the node. Sources are borrowed; reactive
+derivations are created and owned at each mount through the PPX's style-scoping
+adapter. Omitted properties, an empty style and an omitted style preserve defaults.
+`Slot_style.scoped` is the PPX adapter; views should use `reactive` rather than
+calling this adapter directly.
+
+`Slot_style.merge base override` is right-biased per property, including signal
+bindings: an overridden base binding is not installed. A style may only contain
+properties admitted by its target's existing wire kind. Reactive projections
+are deferred per property, so merging does not evaluate a replaced projection.
+The PPX passes the property's wire identifier to `Slot_style.scoped`; its
+callback must produce exactly that one property's binding.
+Unsupported properties are rejected before any style bindings are installed;
+for example, collision
+padding belongs on a dropdown surface, not a toolbar button.
+
+```ocaml
+let menu =
+ let surface_style = Slot_style.make ~shadow:"0 4px 6px black"
+ ~collision_padding:5. ~font_size:"14px" ~line_height:"20px" ~overflow:`auto () in
+ menu_trigger ~text:"Actions" ~label:"Actions"
+ (dropdown_menu ~style:surface_style
+ [dropdown_menu_item ~text:"Open" []])
+
+let actions selected = toolbar ~label:"Actions"
+ [toolbar_button ~text:"Copy"
+ ~style:(Slot_style.make ~font_size:"12px" ~line_height:"16px"
+ ~hover_foreground:(reactive (fun active ->
+ if active then "primary" else "foreground") selected) ()) []]
+```
+
+Restricted slot capabilities are unchanged: ordinary views cannot become toolbar
+or dropdown slots through post-mount decorators. Use the typed constructors and
+their existing reactive/scoped adapters instead. JSON adapters and view-contract
+metadata keep the same flat static appearance keys, including ordinary and
+toolbar buttons with text or icons. These keys are decoded through the shared
+style builder. No wire properties, admission rules, defaults or events changed.
+Web and SDL/native draw these existing appearance
+channels; Apple and Android retain native control/menu styling where their
+renderers do not consume them, as described below for menu items.
+
+Move ordinary-view post-mount styling into a typed style rather than erasing
+or casting its restricted capability:
+
+```ocaml
+dropdown_menu
+ [ dropdown_menu_item ~text:"Open"
+ ~style:(Slot_style.make ~font_size:"0.875rem"
+ ~line_height:"1.42857" ~hover_background:"muted"
+ ~focus_shadow:"inset 0 0 0 2px blue" ()) [] ]
+```
+
+These are wire-level properties, not a promise of identical native menu
+styling on every renderer:
+
+- Web applies the typography and interaction properties to menu-item DOM
+ nodes through its text styles and appearance channels.
+- SDL/native applies them through its common text and appearance renderer
+ (`platform/native/lui_paint`), independently of OS-native menus.
+- Apple SwiftUI native menus keep platform menu-label typography.
+ `LUINativeMenuActions.itemLabel(for:)` builds a native `Label`/`Text` without applying
+ the item's typography or hover/focus overrides.
+- Android Material menu rows keep their native typography and state chrome.
+ `LuiMenuItem` derives text style from Material/style classes rather than
+ the item's typography properties, and neither it nor `luiChrome` consumes
+ the hover/focus overrides.
+
+The new menu-label typography and interaction overrides are currently drawn
+by Web and SDL/native only. Apple and Android still receive the properties;
+applications must not rely on them changing native menu labels there.
+
+Web's default menu highlight honors each authored appearance channel
+independently. A foreground-only hover override preserves the default
+highlight background; a focus-background-only override wins on keyboard
+focus without requiring a hover background. An authored focus background
+keeps the item's normal foreground unless an
+active foreground channel overrides it, rather than assuming an inverted
+highlight background:
+
+```ocaml
+dropdown_menu_item ~text:"Open" ~style:(Slot_style.make ~hover_foreground:"red" ()) []
+dropdown_menu_item ~text:"Save" ~style:(Slot_style.make ~focus_within_background:"muted" ()) []
+```
+
### Apple row intrinsic text priority
Non-growing `text`, `heading`, and `paragraph` children in Apple rows now
@@ -478,8 +577,8 @@ split ~sizing:(reactive (fun value -> Fraction value) fraction)
```
Omitting sizing now emits **Fraction 0.5**, including on Apple, which requires
-exactly one sizing mode. Reactive mode changes remove the previous sizing
-property. `motion` groups the former `resize_duration`, `resize_easing`, and
+exactly one sizing mode. Reactive mode changes remove only the opposite sizing
+property; publishing an unchanged sizing value emits no patches. `motion` groups the former `resize_duration`, `resize_easing`, and
`resize_origin`. Omitted motion retains instant resizing (duration 0, implicit
standard easing, no origin). Positive duration emits the chosen easing and
optional origin. Non-positive duration means instant resizing: duration is
diff --git a/platform/web/src/lui.css b/platform/web/src/lui.css
index c7d8f977..05cf1ad1 100644
--- a/platform/web/src/lui.css
+++ b/platform/web/src/lui.css
@@ -2599,33 +2599,40 @@ body {
border-color: var(--lui-focus-within-border, var(--lui-current-hover-border, revert-layer));
}
- /* Default menu highlight is the Base UI inverted row. An authored
- hover-background stays in the inline style and keeps the ordinary
- fallback text color, so a custom light highlight does not turn white. */
+ /* Default menu highlight is the Base UI inverted row. Each authored
+ appearance channel overrides its own fallback independently. */
.lui-menu-item:is([data-highlighted], :focus-visible):not(:disabled, [data-disabled], [aria-disabled="true"], [style*="--lui-hover-bg"]) {
- background-color: var(--lui-foreground);
- color: var(--lui-background);
+ background-color: var(--lui-current-focus-within-bg, var(--lui-foreground));
+ color: var(--lui-current-hover-fg, var(--lui-background));
}
@media (hover: hover) {
.lui-menu-item:hover:not(:disabled, [data-disabled], [aria-disabled="true"], [style*="--lui-hover-bg"]) {
- background-color: var(--lui-foreground);
- color: var(--lui-background);
+ background-color: var(--lui-current-focus-within-bg, var(--lui-foreground));
+ color: var(--lui-current-hover-fg, var(--lui-background));
}
}
.lui-menu-item[data-variant="destructive"]:is([data-highlighted], :focus-visible):not(:disabled, [data-disabled], [aria-disabled="true"], [style*="--lui-hover-bg"]) {
- background-color: var(--color-destructive);
- color: var(--color-destructive-foreground);
+ background-color: var(--lui-current-focus-within-bg, var(--color-destructive));
+ color: var(--lui-current-hover-fg, var(--color-destructive-foreground));
}
@media (hover: hover) {
.lui-menu-item[data-variant="destructive"]:hover:not(:disabled, [data-disabled], [aria-disabled="true"], [style*="--lui-hover-bg"]) {
- background-color: var(--color-destructive);
- color: var(--color-destructive-foreground);
+ background-color: var(--lui-current-focus-within-bg, var(--color-destructive));
+ color: var(--lui-current-hover-fg, var(--color-destructive-foreground));
}
}
+ .lui-menu-item:focus-within[style*="--lui-focus-within-bg"]:not(:disabled, [data-disabled], [aria-disabled="true"]) {
+ color: var(--lui-current-hover-fg, inherit);
+ }
+
+ .lui-menu-item[data-variant="destructive"]:focus-within[style*="--lui-focus-within-bg"]:not(:disabled, [data-disabled], [aria-disabled="true"]) {
+ color: var(--lui-current-hover-fg, var(--color-destructive));
+ }
+
}
/* The typed line-clamp property owns the block formatting contract. */
diff --git a/platform/web/test/appearance.e2e.mjs b/platform/web/test/appearance.e2e.mjs
index 3897a21f..832407f8 100644
--- a/platform/web/test/appearance.e2e.mjs
+++ b/platform/web/test/appearance.e2e.mjs
@@ -183,6 +183,98 @@ test("explicit base appearance composes with hover, press, selection and disable
assert.equal((await read()).opacity, '0.9')
})
+test("menu hover channels override their defaults independently", async () => {
+ await page.goto(`${origin}/platform/web/test/fixtures/appearance-regression.html`)
+ await page.mouse.move(1250, 850)
+ const variants = await page.evaluate(() => window.probe.menuItems)
+ for (const items of Object.values(variants)) {
+ const baseline = page.locator(`#lui-node-${items.baseline}`)
+ const ordinaryInk = await baseline.evaluate(el => getComputedStyle(el).color)
+ await baseline.hover()
+ const defaultHighlight = await baseline.evaluate(el => getComputedStyle(el).backgroundColor)
+ const background = page.locator(`#lui-node-${items.hoverBg}`)
+ await background.hover()
+ assert.deepEqual(await background.evaluate(el => ({
+ background: getComputedStyle(el).backgroundColor,
+ color: getComputedStyle(el).color,
+ })), { background: "rgb(18, 52, 86)", color: ordinaryInk })
+ const foreground = page.locator(`#lui-node-${items.hoverFg}`)
+ await foreground.hover()
+ assert.deepEqual(await foreground.evaluate(el => ({
+ background: getComputedStyle(el).backgroundColor,
+ color: getComputedStyle(el).color,
+ })), { background: defaultHighlight, color: "rgb(18, 52, 86)" })
+ await page.evaluate(id => {
+ window.probe.unset(id, "hover-foreground")
+ window.probe.flush()
+ }, items.hoverFg)
+ assert.notEqual(await foreground.evaluate(el => getComputedStyle(el).color), "rgb(18, 52, 86)")
+ }
+})
+
+test("menu focus channels override their defaults independently", async () => {
+ await page.goto(`${origin}/platform/web/test/fixtures/appearance-regression.html`)
+ await page.mouse.move(1250, 850)
+ await page.keyboard.press("Tab")
+ const variants = await page.evaluate(() => window.probe.menuItems)
+ for (const items of Object.values(variants)) {
+ const baseline = page.locator(`#lui-node-${items.baseline}`)
+ await baseline.focus()
+ const defaultHighlight = await baseline.evaluate(el => getComputedStyle(el).backgroundColor)
+ const background = page.locator(`#lui-node-${items.focusBg}`)
+ await background.focus()
+ assert.equal(await background.evaluate(el => el.matches(":focus-visible")), true)
+ assert.equal(await background.evaluate(el => getComputedStyle(el).backgroundColor), "rgb(18, 52, 86)")
+ await page.evaluate(id => {
+ window.probe.unset(id, "focus-within-background")
+ window.probe.flush()
+ }, items.focusBg)
+ assert.equal(await background.evaluate(el => getComputedStyle(el).backgroundColor), defaultHighlight)
+ const border = page.locator(`#lui-node-${items.focusBorder}`)
+ await border.focus()
+ assert.equal(await border.evaluate(el => getComputedStyle(el).borderTopColor), "rgb(18, 52, 86)")
+ const shadow = page.locator(`#lui-node-${items.focusShadow}`)
+ await shadow.focus()
+ assert.match(await shadow.evaluate(el => getComputedStyle(el).boxShadow), /^rgb\(18, 52, 86\) 0px 0px 0px 2px$/)
+ }
+})
+
+for (const theme of ["light", "dark"]) {
+ test(`authored menu focus backgrounds keep normal label ink in ${theme}`, async () => {
+ await page.goto(`${origin}/platform/web/test/fixtures/appearance-regression.html`)
+ await page.evaluate(theme => { document.documentElement.dataset.kbTheme = theme }, theme)
+ await page.mouse.move(1250, 850)
+ await page.keyboard.press("Tab")
+ const variants = await page.evaluate(() => window.probe.menuItems)
+ for (const items of Object.values(variants)) {
+ const item = page.locator(`#lui-node-${items.focusBg}`)
+ const label = item.locator(".lui-menu-item-label")
+ const normalInk = await label.evaluate(el => getComputedStyle(el).color)
+ await page.evaluate(id => {
+ window.probe.set(id, "focus-within-background", "muted")
+ window.probe.flush()
+ }, items.focusBg)
+ await item.focus()
+ assert.equal(await item.evaluate(el => el.matches(":focus-visible")), true)
+ assert.equal(await label.evaluate(el => getComputedStyle(el).color), normalInk)
+ assert.equal(await item.evaluate(el => getComputedStyle(el).backgroundColor),
+ theme === "light" ? "oklch(0.97 0 0)" : "oklch(0.269 0 0)")
+ }
+ })
+}
+
+test("disabled menu items ignore authored hover channels", async () => {
+ await page.goto(`${origin}/platform/web/test/fixtures/appearance-regression.html`)
+ await page.mouse.move(1250, 850)
+ const variants = await page.evaluate(() => window.probe.menuItems)
+ for (const items of Object.values(variants)) {
+ const item = page.locator(`#lui-node-${items.disabled}`)
+ const ordinaryInk = await item.evaluate(el => getComputedStyle(el).color)
+ await item.hover({ force: true })
+ assert.equal(await item.evaluate(el => getComputedStyle(el).color), ordinaryInk)
+ }
+})
+
test('retained button content preserves owned slots and intrinsic spacing', async () => {
await page.goto(`${origin}/platform/web/test/fixtures/button-content-regression.html`)
await page.getByRole('button', {name: 'Audit retained content', exact: true}).click()
diff --git a/platform/web/test/fixtures/appearance-regression.html b/platform/web/test/fixtures/appearance-regression.html
index ad233661..7134aa5a 100644
--- a/platform/web/test/fixtures/appearance-regression.html
+++ b/platform/web/test/fixtures/appearance-regression.html
@@ -17,6 +17,7 @@
body { margin: 24px; font: 16px system-ui }
#host { max-width: 720px }
#host .lui-button { transition: none }
+#host .lui-menu-item { transition: none }