Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 101 additions & 2 deletions docs/api-migrations.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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
Expand Down
29 changes: 18 additions & 11 deletions platform/web/src/lui.css
Original file line number Diff line number Diff line change
Expand Up @@ -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. */
Expand Down
92 changes: 92 additions & 0 deletions platform/web/test/appearance.e2e.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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()
Expand Down
20 changes: 19 additions & 1 deletion platform/web/test/fixtures/appearance-regression.html
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
</style>
<main id="host"></main>
<nav aria-label="Appearance test controls">
Expand Down Expand Up @@ -146,6 +147,23 @@
"pressed-background": "#778899", "pressed-opacity": 0.7,
"selected-background": "#998877", "disabled-opacity": 0.4,
})
const menuItems = {}
for (const variant of ["normal", "destructive"]) {
const parent = create("row", root, { gap: 4 })
const item = (name, props = {}) => create("menu-item", parent, {
text: name, width: 88, height: 32,
...(variant === "destructive" ? { variant } : {}), ...props,
})
menuItems[variant] = {
baseline: item("Default"),
hoverBg: item("Hover bg", { "hover-background": "#123456" }),
hoverFg: item("Hover fg", { "hover-foreground": "#123456" }),
focusBg: item("Focus bg", { "focus-within-background": "#123456" }),
focusBorder: item("Focus border", { "focus-within-border": "#123456" }),
focusShadow: item("Focus shadow", { "focus-shadow": "0 0 0 2px #123456" }),
disabled: item("Disabled", { "hover-foreground": "#123456", enabled: false }),
}
}
document.querySelector("#select").onclick = () => { set(explicit, "selected", true); flush() }
document.querySelector("#disable").onclick = () => {
set(explicit, "selected", false); set(explicit, "enabled", false); flush()
Expand All @@ -159,7 +177,7 @@
Web.mount(renderer, root, host)

window.probe = {
typography, positioned, interactive, explicit,
typography, positioned, interactive, explicit, menuItems,
set, unset, flush,
}
</script>
4 changes: 3 additions & 1 deletion platform/web/test/fixtures/point-menu-regression.html
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,9 @@
set(menu, "x", x)
set(menu, "y", y)
create("menu-item", menu, { text: "Point alpha", "press-enabled": true, selected: true })
const beta = create("menu-item", menu, { text: "Point beta", "press-enabled": true })
const beta = create("menu-item", menu, {
text: "Point beta", "press-enabled": true, "hover-foreground": "#123456",
})
handlers.set(beta, () => activations.push("beta"))
handlers.set(menu, () => { drop(menu); menu = null })
flush()
Expand Down
26 changes: 26 additions & 0 deletions platform/web/test/point-menu.e2e.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,32 @@ const openPositioner = () =>
has: page.locator(".lui-dropdown-menu[data-open]"),
})

for (const theme of ["light", "dark"]) {
test(`keyboard highlighting applies authored menu foreground in ${theme}`, async () => {
await page.goto(`${origin}/platform/web/test/fixtures/point-menu-regression.html`)
await page.evaluate(theme => { document.documentElement.dataset.kbTheme = theme }, theme)
await page.mouse.move(1100, 800)
await page.evaluate(() => window.audit.openPointMenu())
const alpha = page.getByRole("menuitem", { name: "Point alpha", exact: true })
const beta = page.getByRole("menuitem", { name: "Point beta", exact: true })
await alpha.focus()
await page.keyboard.press("Home")
assert.equal(await alpha.evaluate(el => el.hasAttribute("data-highlighted")), true)
const ordinaryInk = await beta.locator(".lui-menu-item-label").evaluate(el => getComputedStyle(el).color)
await page.keyboard.press("ArrowDown")
assert.equal(await beta.evaluate(el => el.hasAttribute("data-highlighted")), true)
assert.equal(await beta.evaluate(el => el.matches(":hover")), false)
assert.equal(await beta.evaluate(el => el.style.getPropertyValue("--lui-hover-bg")), "")
assert.equal(await beta.locator(".lui-menu-item-label").evaluate(el => getComputedStyle(el).color), "rgb(18, 52, 86)")
await page.keyboard.press("ArrowUp")
assert.equal(await beta.evaluate(el => el.hasAttribute("data-highlighted")), false)
assert.equal(await beta.locator(".lui-menu-item-label").evaluate(el => getComputedStyle(el).color), ordinaryInk)
await page.keyboard.press("ArrowDown")
assert.equal(await beta.locator(".lui-menu-item-label").evaluate(el => getComputedStyle(el).color), "rgb(18, 52, 86)")
assert.deepEqual(await page.evaluate(() => window.audit.activations), [])
})
}

test("a closing dropdown leaves the accessibility tree before its exit animation finishes", async () => {
await page.goto(`${origin}/platform/web/test/fixtures/point-menu-regression.html`)
await page.evaluate(() => window.audit.openPointMenu())
Expand Down
2 changes: 1 addition & 1 deletion platform/web/test/tailwind.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -312,7 +312,7 @@ test("menus use the Base UI popup and transition contract", async () => {
assert.match(css, /\.lui-menu-item\[data-highlighted\]/)
assert.match(
css,
/\.lui-menu-item:is\(\[data-highlighted\],:focus-visible\):not\([^)]*\)\{[^}]*background-color:var\(--lui-foreground\)/,
/\.lui-menu-item:is\(\[data-highlighted\],:focus-visible\):not\([^)]*\)\{[^}]*background-color:var\(--lui-current-focus-within-bg,var\(--lui-foreground\)\)/,
)
assert.match(css, /\.lui-menu-item\[data-submenu-trigger\]/)
assert.match(css, /\.lui-menu-item\[data-variant=destructive\]/)
Expand Down
Loading
Loading