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 }