@qxuken/kui 0.1.0-alpha.41 → 0.1.0-alpha.43

package/howto.md

@@ -278,6 +278,23 @@ gap, to keep it apart.
 [ADR 0035](docs/adr/0035-a-rounded-background-is-joined-by-meeting.md) ·
 [alpha.22 `### Added`](CHANGELOG.md#010-alpha22-2026-09-28)
 
+### How do I set inline code in monospace inside a paragraph?
+
+Give the span a face of its own: `<span family="mono">cargo test</span>`,
+`Span::new("cargo test").mono()` in Rust, `{ "cargo test", family = "mono" }`
+in Lua, `.flags = KUI_SPAN_FAMILY, .family = KUI_FONT_MONO` on a C
+`KuiSpan` (`.font` for a registered font, which wins). Any family name the
+text's `family` takes works, and `size` gives a span its own size — a
+larger first word, a smaller footnote mark — with the line as tall as its
+tallest span. The paragraph still shapes as one flow, and its carets, hit
+tests and selection are measured in the face each glyph is drawn in, so a
+byte position means the same thing on either side of the change. Add a
+`bg` and a `bgRadius` for the usual wash; it is the span's own height,
+not the line's.
+
+[`text` element](props.md#elements) ·
+[`text.rs`](../examples/rust/widgets/text.rs)
+
 ### How do I list the installed fonts, the monospaced ones first?
 
 `ctx.systemFonts()` (Rust `Core::system_fonts()`, C `kui_system_fonts`)
@@ -558,6 +575,51 @@ message.
 [ADR 0019](docs/adr/0019-a-theme-derived-from-appearance-and-accent.md) ·
 [alpha.10](CHANGELOG.md#010-alpha10-2026-09-09)
 
+### How do I show the blurred desktop through my sidebar, like a Mac app?
+
+Ask the launcher for the effect — `kui_native::app("Notes")
+.backdrop(Backdrop::Blur)`, or `backdrop: 'blur'` in Node's window options
+— and paint the regions that should show it with alpha:
+`bg(t.raised.with_alpha(0.5))` on the sidebar, an opaque `bg` on the page
+beside it. kui puts the effect behind the whole window and knows nothing of
+sidebars; what you paint decides where it shows. `Blur` is a live blur of
+what is behind the window (macOS vibrancy, Windows 11's Acrylic, KDE's
+compositor blur), `Tinted` the desktop's colour, steady (Mica, macOS's
+window-background material), `Transparent` the desktop as it is. Then read
+what the window got, every frame, from `ui.env().window.backdrop` (Node
+`env().window.backdrop`): where the OS has no effect — GNOME, Windows 10 —
+it reads `Tinted`, the wallpaper kui reads, blurs once and draws under the
+frame, or `Opaque` where no wallpaper could be read; paint the sidebar
+opaque then. Hyprland, SwayFX and picom blur translucent windows
+themselves: ask for `Transparent` there. Glyphs are grayscale under a
+backdrop; `KUI_BACKDROP_EMULATE=1` shows the wallpaper path on Windows and Linux
+(macOS reads no wallpaper, so the window there is `Opaque`).
+
+[`window.backdrop` row](props.md#env) ·
+[`backdrop.rs`](../examples/rust/features/backdrop.rs)
+
+In C, `KuiRunConfig.backdrop` asks (`KUI_BACKDROP_BLUR`) and
+`kui_ctx_backdrop(ctx)` in the view reads what the window got.
+
+### How do I frost a toolbar over content that scrolls under it?
+
+Give the toolbar a `backdropBlur` and a translucent `bg`:
+`NodeSpec::row().backdrop_blur(16.0).bg(Color::WHITE.with_alpha(0.25))`
+in Rust, `backdropBlur: 16` in JSX, `backdrop_blur` in Lua, Odin and C's
+`KuiSpec`. What blurs is everything painted before the node — the page,
+the rows scrolling under it, the window's backdrop where there is one —
+inside the node's rounded box and its clip, by the radius in logical px
+(CSS's `backdrop-filter: blur()`). The node's own `bg`, border and
+children lie on top, so an opaque `bg` hides the blur, and a
+`backdrop-blur-hidden` warning says so. Float the toolbar over the
+scroller, after it in the tree, so the scroller paints first. It costs a
+copy and three small passes per blurred node on a frame that has one, and
+nothing on a frame that does not; a renderer of your own that cannot read
+back its frame draws the node unblurred.
+
+[`backdropBlur` row](props.md#container-props) ·
+[`backdrop_blur.rs`](../examples/rust/features/backdrop_blur.rs)
+
 ## Interaction, focus and reading
 
 ### How do I open a popup, and when is a modal enough?
@@ -734,6 +796,27 @@ the same palette from the keyboard and types the same way.
 [ADR 0030](docs/adr/0030-the-standard-menus-the-runner-keeps.md) ·
 [examples/rust/widgets/menu_bar.rs](../examples/rust/widgets/menu_bar.rs)
 
+### How do I put a submenu in a menu — "Move to ▸", "Sort by ▸"?
+
+Give the row `items`: `MenuItem::submenu("Move to", rows)` in Rust,
+`{ label: 'Move to', items: [...] }` in Node and Lua. The row draws a
+chevron and opens its rows beside it when the pointer rests on it, it is
+clicked, or Enter or the Right arrow is pressed; Left or Escape closes
+it, and Escape again closes the menu. It nests, in a context menu and in
+a menu bar, drawn or the platform's. A row inside is chosen like any
+row: one `{kind:"menu", role, item}` with its own `id`, on the node the
+menu is about. A host that shows menus itself reports one with
+`Core::activate_menu_path(&[1, 0])` (Node `activateMenuPath`, C
+`kui_activate_menu_path` with a path of `size_t`s). In C a row's
+`submenu` / `submenu_count` nest the same `KuiMenuItem`s, and
+`KUI_MENU_ITEM_SUBMENU` in a row's flags says it has rows, read with
+`kui_menu_item_path`. An
+`accel` in the portable spelling (`"mod+shift+n"`) is drawn the
+platform's way, and the menu widens to its longest row.
+
+[ADR 0018](docs/adr/0018-a-menu-bar-the-app-declares.md) ·
+[`tests/submenu.rs`](../crates/kui-core/tests/submenu.rs)
+
 ### How do I take files dropped from the Finder?
 
 Declare `onDrop` (Rust and Lua `on_drop`, C `KuiSpec.on_drop`) on the box

package/index.d.ts

@@ -730,6 +730,10 @@ export interface OpenMenuItem {
    *  own, or its role's default (`⌘C` on a `copy` row that declared none);
    *  null where there is neither. */
   accel: string | null;
+  /** The rows of the submenu this row opens, read the same way; absent on
+   *  a row that opens none. A row with them is never chosen itself: report
+   *  a row inside with `activateMenuPath`. */
+  items?: OpenMenuItem[];
 }
 
 /** The menu a window has open (`Ctx.menu()`): where it opened, the node it
@@ -925,6 +929,12 @@ export type WarningCode =
    *  after every width is. The ratio sizes a fit height from the width, or a
    *  fit width from a fixed height. */
   | 'aspect-ignored'
+  /** A `backdropBlur` under an opaque `bg` of the node's own: the background
+   *  paints over the whole blur, so nothing of it shows and the copy and the
+   *  passes are spent for nothing. Give the `bg` some transparency
+   *  (`#ffffff40`) — frosted glass is a translucent fill over a blur (backlog
+   *  F129). */
+  | 'backdrop-blur-hidden'
   /** A text node sits more than four levels below the `line` row above it,
    *  which is as far as a text's place remembers its ancestors — so `textHit` /
    *  `caretRect` asked by that row's key cannot find the run, and a press
@@ -1369,6 +1379,8 @@ export interface NodeInfo {
   /** `0xRRGGBBAA`. */
   borderColor: number;
   opacity: number;
+  /** Its `backdropBlur` radius in px, 0 for none (backlog F129). */
+  backdropBlur: number;
   /** A scroller's offset; `null` for a node that does not scroll. */
   scroll: { x: number; y: number } | null;
   /** Every handler it declared with the payload it would post: `click`,
@@ -1647,8 +1659,19 @@ export interface WindowEnv {
    *  draws over our content — the macOS traffic lights under custom chrome.
    *  Keep out of it. Null means the OS draws nothing over us. */
   nativeControls: Rect | null;
+  /** What is behind the window's transparent pixels, as the runner got it:
+   *  `'opaque'` (the default), `'transparent'` (the desktop as it is),
+   *  `'blur'` (a live blur of what is behind the window) or `'tinted'`
+   *  (the desktop's colour, steady). Less where the platform has less — a
+   *  blur asked of GNOME reads `'tinted'`, the wallpaper kui draws, or
+   *  `'opaque'` — so a view paints its translucent regions opaque when
+   *  this is `'opaque'`. */
+  backdrop: Backdrop;
 }
 
+/** What is behind a window's transparent pixels (`WindowEnv.backdrop`). */
+export type Backdrop = 'opaque' | 'transparent' | 'blur' | 'tinted';
+
 /** A box in logical px: position and size. */
 export interface Rect {
   x: number;
@@ -1689,6 +1712,8 @@ export interface EnvInput {
     /** `x` and `y` default to the window origin; a zero-sized rect and null
      *  both mean "nothing is drawn over us". */
     nativeControls?: Partial<Rect> | null;
+    /** What a runner would report behind the window's transparent pixels. */
+    backdrop?: Backdrop;
   };
   /** What a driver with a device would report; see `AudioEnv`. */
   audio?: {
@@ -1828,6 +1853,15 @@ export interface WindowOptions {
   maxWidth?: number;
   maxHeight?: number;
   chrome?: 'native' | 'custom' | 'borderless';
+  /** What shows through the window where a frame paints nothing or paints
+   *  with alpha (the launcher's `backdrop`), by effect: `'opaque'` (the
+   *  default), `'transparent'` (the desktop as it is), `'blur'` (macOS
+   *  vibrancy, Windows 11 Acrylic, KDE's compositor blur) or `'tinted'`
+   *  (Windows 11 Mica, macOS's window-background material, the wallpaper
+   *  kui draws where the OS has neither). Paint the regions that should
+   *  show it with alpha and the rest opaque; `env().window.backdrop` says
+   *  what the platform gave, which is less where it has less. */
+  backdrop?: Backdrop;
   /** How outline glyphs are antialiased: `'auto'` (the default) is LCD
    *  subpixel coverage where the GPU blends per channel and grayscale
    *  otherwise. `KUI_TEXT_AA=gray|subpixel` in the environment still
@@ -1890,6 +1924,8 @@ export type DoorCell = { is: string } | { as: string } | { no: string };
 export interface Door {
   rust: string;
   c: DoorCell;
+  /** The Odin binding's (packages/odin), pinned by its generator. */
+  odin: DoorCell;
   node: DoorCell;
   lua: DoorCell;
   doc: string;
@@ -3278,6 +3314,12 @@ export declare class Ctx {
    * takes. False for a row that is not there.
    */
   activateMenuBarItem(menu: number, item: number): boolean
+  /**
+   * `activateMenuBarItem` for a row inside a submenu of menu
+   * `menu`, by its path through the rows' `items`. False for a
+   * row that is not there or that opens a submenu.
+   */
+  activateMenuBarPath(menu: number, path: Array<number>): boolean
   /**
    * Tells the core this host can show the platform's definition
    * panel. The standard Look Up row is then offered where it
@@ -3293,6 +3335,13 @@ export declare class Ctx {
    * stays open and nothing is posted.
    */
   activateMenuItem(index: number): boolean
+  /**
+   * `activateMenuItem` for a row inside a submenu, by its path
+   * through the rows' `items`: `[2, 0]` is the first row of the
+   * third row's submenu. False where `activateMenuItem` is, and
+   * for a row that opens a submenu, which is never chosen.
+   */
+  activateMenuPath(path: Array<number>): boolean
   /** Closes whatever menu is open; true when there was one. */
   closeMenu(): boolean
   /**
@@ -3479,7 +3528,7 @@ export declare class KuiWindow {
   /**
    * Options: `{width, height, minWidth, minHeight, maxWidth, maxHeight,
    * chrome: "native" | "custom" | "borderless", textAa: "auto" | "gray"
-   * | "subpixel", frameLatency, system, icon}`. The min/max pairs bound what the user can
+   * | "subpixel", frameLatency, system, icon, backdrop}`. The min/max pairs bound what the user can
    * resize the window to; either half may stand alone. `system` pins part of `env.system` over what the OS
    * says, for the life of the window — `{motion: 'reduced'}` is what a
    * user who asked for less motion would get, on a machine whose owner
@@ -4462,6 +4511,12 @@ export declare class KuiWindow {
    * takes. False for a row that is not there.
    */
   activateMenuBarItem(menu: number, item: number): boolean
+  /**
+   * `activateMenuBarItem` for a row inside a submenu of menu
+   * `menu`, by its path through the rows' `items`. False for a
+   * row that is not there or that opens a submenu.
+   */
+  activateMenuBarPath(menu: number, path: Array<number>): boolean
   /**
    * Tells the core this host can show the platform's definition
    * panel. The standard Look Up row is then offered where it
@@ -4477,6 +4532,13 @@ export declare class KuiWindow {
    * stays open and nothing is posted.
    */
   activateMenuItem(index: number): boolean
+  /**
+   * `activateMenuItem` for a row inside a submenu, by its path
+   * through the rows' `items`: `[2, 0]` is the first row of the
+   * third row's submenu. False where `activateMenuItem` is, and
+   * for a row that opens a submenu, which is never chosen.
+   */
+  activateMenuPath(path: Array<number>): boolean
   /** Closes whatever menu is open; true when there was one. */
   closeMenu(): boolean
   /**

package/index.js

@@ -52,8 +52,12 @@ export function withEffects(model, ...effects) {
 
 // A frame crosses the boundary one way: JS encodes the tree into one
 // Float64Array + string table and the addon lowers it zero-copy. One encoder
-// serves every context — its buffers are consumed synchronously.
+// serves every context — its buffers are consumed synchronously. Measuring
+// has one of its own: a `<devtoolsTab>`'s function child is called in the
+// middle of an encode, and a `measureText` there reset the frame's buffers
+// under it ("binary frame must start with the root op").
 const encoder = createEncoder(native.protocol());
+const measurer = createEncoder(native.protocol());
 
 // A prop name the schema does not know has no wire id, so it never crosses:
 // the encoder is the only side that can see it, and it reports what it
@@ -206,7 +210,7 @@ KuiWindow.prototype.setView = function setView(tree, window) {
 // it draws. A style name the schema does not know is reported like a
 // view's would be.
 function measureText(content, style, maxWidth) {
-  const { stream, strings, unknown, unknownTokens } = encoder.encodeText(content, style, this[TOKENS]);
+  const { stream, strings, unknown, unknownTokens } = measurer.encodeText(content, style, this[TOKENS]);
   const m = this.measureTextBinary(stream, strings, maxWidth);
   reportUnknown(this, unknown, unknownTokens);
   return m;
@@ -1040,8 +1044,8 @@ runWindowed[PACE] = pacer;
  * is opened as a user who asked for less motion would see it.
  */
 export function windowOptions(opts = {}) {
-  const { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon } = opts;
-  return { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon };
+  const { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon, backdrop } = opts;
+  return { width, height, minWidth, minHeight, maxWidth, maxHeight, chrome, textAa, frameLatency, system, icon, backdrop };
 }
 
 /**

package/jsx-runtime.d.ts

@@ -219,6 +219,11 @@ export interface MenuItemInput {
    *  A declaration kui can parse is rewritten into the platform's own
    *  spelling, so `'mod+s'` reads as `⌘S` on macOS and `Ctrl+S` elsewhere. */
   accel?: string;
+  /** The rows of a submenu: the row draws a chevron and opens them beside
+   *  itself — on hover, a click, Enter or the Right arrow; Left or Escape
+   *  closes it — and is never chosen itself. A chosen row inside posts its
+   *  own `menu` event, on the node the menu is about. */
+  items?: MenuItemInput[];
 }
 
 /** One menu of the application menu bar (the `<menuBar menu={…}/>`
@@ -257,6 +262,8 @@ export interface GeneratedSpecProps {
   animate?: boolean;
   /** Width over height — `16/9`, `1` for a square — CSS's `aspect-ratio`. It sizes the axis left `fit`: a fit height is the final width over the ratio (so `width: grow` and a ratio is a box that keeps its shape as the window resizes), and a fit width under a fixed height is that height times it. With both axes declared, or a fit width under a `grow` or percent height, it has nothing it can set and warns. The derived axis is neither shrunk nor fitted to the children, which overflow it; `minHeight: 'fit'` floors it at them. On an image it wins over the pixels' own aspect. */
   aspectRatio?: LengthProp;
+  /** Blur what was drawn beneath the node, inside its rounded box, by this radius in logical px — CSS's `backdrop-filter: blur()`, the radius its standard deviation (backlog F129). What blurs is everything painted before the node: its ancestors' backgrounds, the siblings under it, content scrolling beneath it, the window's `backdrop` where the window has one. The node's own `bg`, border and children paint over the blur, so a translucent `bg` (`#ffffff40`) makes frosted glass and an opaque one hides it. Clipped as the node is, faded by its `opacity`; 0 is none. The GPU renderer reads back only the box (and a margin of three radii around it) and blurs it at reduced resolution, so it costs a copy and three small passes per blurred node on a frame that has one and nothing on a frame that does not. A renderer that cannot read back what it drew — a host's own, or anything older — leaves the node over an unblurred backdrop; the display list carries it as a `backdrop` quad (`KUI_QUAD_BACKDROP` in C) either way. */
+  backdropBlur?: LengthProp;
   /** Background fill. */
   bg?: ColorProp;
   /** How far a spring overshoots its target: 0 glides in with none, 0.5 bounces visibly, and values past 0.9 are held there (a spring at 1 would never settle). It replaces a spring `easing`'s own bounce (`smooth` 0, `snappy` 0.15, `spring` 0.25, `bouncy` 0.5), and on a timed easing makes the transition a spring — so `transition` plus `bounce` is a spring of that length and bounce. */
@@ -599,6 +606,18 @@ export interface SpanProps extends Keyed {
    *  A selection over rows, or over a paragraph's wrapped lines, is one
    *  outline. Nested spans inherit; 0 (the default) is square. */
   bgRadius?: number;
+  /** The span's own face: `sans`, `serif`, `mono` or an installed family's
+   *  name, as the text's `family` takes — inline code in `mono` inside a
+   *  sans paragraph. Carets, hits and selection are measured in the face
+   *  the glyphs are drawn in. Nested spans inherit. */
+  family?: string;
+  /** A registered font handle (`addFont` / `addSystemFont`), the span's
+   *  face; wins over `family`. Nested spans inherit. */
+  font?: string;
+  /** The span's own size, logical px: its line height scales with it at
+   *  the paragraph's ratio, and a line is as tall as its tallest span.
+   *  Nested spans inherit. */
+  size?: number;
   children?: KuiNode;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qxuken/kui",
-  "version": "0.1.0-alpha.41",
+  "version": "0.1.0-alpha.43",
   "description": "kui for Node: JSX views lowered into the kui IR, Elm-style messages as data",
   "license": "MIT",
   "repository": {