Layout and styling

Every UI element accepts Props; specialized constructors add their own fields. Dimensions, offsets, radii, gaps, and padding are in points. Properties are optional unless the constructor’s type requires them. Children are the numeric entries of the property table.

Sizing and identity

Property	Meaning and default
`key`	Stable identity under the same parent for retained handlers and motion. Use a distinct key for each logical item; native inputs require one.
`w`, `h`	Explicit width/height; omitted dimensions use intrinsic layout. An unsized shader fills its stack without enlarging it.
`grow`	Nonnegative weight dividing spare space along a row/column’s main axis; default 0.
`gap`	Space between row/column children; default 0.
`pad`	Equal inset on all sides; default 0.
`center`	Center children across the row/column’s cross axis; default true. False starts them at the padding.
`align`	Placement inside an overlapping stack; defaults to center. Supports leading/trailing, top/bottom, and the four corners.
`scroll`	Enable native scrolling in an overflowing fixed-size row or column.

ui.row{ w = 260, pad = 12, gap = 8,
    ui.text{ text = "Status", grow = 1 },
    ui.text{ text = "Ready", color = "accent" },
}

`Align`

export type Align =
    "center"
    | "leading"
    | "trailing"
    | "top"
    | "bottom"
    | "topLeading"
    | "topTrailing"
    | "bottomLeading"
    | "bottomTrailing"

Colors and surfaces

A Color is a palette role ("accent", "surface", "foreground"), a role with alpha ("surface/0.8"), a "#RRGGBB" or "#RRGGBBAA" string, or a packed 0xRRGGBBAA number. 0 is transparent. Role alpha must be 0–1; unknown roles fail validation. Profiles and palettes lists palette configuration.

Property	Meaning and default
`fill`	Background color or tint. Omitted fill is transparent.
`border`, `borderWidth`	Edge color and stroke width in points.
`radius`	Rounded corners; also clips images.
`opacity`	Painted opacity; default 1.
`material`	Native background material; omitted means none. `glass` on a popout root uses Liquid Glass; `clear` draws no panel behind it.
`blurRadius`, `saturation`	Layer-material blur 0–64 points and saturation 0–3. Omitted blur uses the material; saturation defaults to 1.8. Does not alter root glass/popover system materials.
`shadow`, `shadowRadius`	Shadow color and blur radius in points.
`mask`	A shader/path shapes its parent stack; use one mask per stack. See shaders and effects.

`Color`

export type Color = string | number

`Material`

export type Material = "none" | "ultraThin" | "thin" | "regular" | "thick" | "ultraThick" | "bar" | "popover" | "glass" | "clear"

Palette roles include background, surface, elevatedSurface, highestSurface, foreground, secondaryForeground, mutedForeground, border, accent, accentForeground, success, warning, error, focus, shadow, scrim, and badge. Container roles are accentContainer, secondaryAccent, secondaryContainer, tertiaryAccent, and tertiaryContainer, each container with a …Foreground role. Named hue roles are red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown, and gray.

Pointer feedback and transforms

Property	Meaning
`hover`, `hoverScale`, `hoverOpacity`, `hoverMaterial`, `hoverAnimate`	Hover color/material or paint feedback. Unspecified values retain the element’s ordinary appearance.
`help`	Tooltip text.
`pressScale`, `pressOpacity`, `pressFill`, `pressAnimate`	Native mouse-down feedback; a transparent `pressFill = 0` explicitly replaces the base fill.
`dx`, `dy`, `scale`, `rotate`	Paint offsets in points, scale (default 1), and rotation in degrees. A 90-degree text rotation also takes rotated layout space.
`animate`, `appear`, `exit`, `enter`, `loop`, `trail`	Motion and identity transitions; see input and motion.
`onClick`, `onRightClick`, `onScroll`	Command strings or callbacks; see actions.
`onPress`, `onHover`, `hoverDelay`, `hoverGrace`	Boundary callbacks and dwell/grace in seconds; see native input.
`gesture`, `onGesture`, `gestureEvents`, `scrollMomentum`	Captured pointer/scroll gestures and scroll delivery; see gestures.
`focusable`, `focusRing`, `keys`, `onKey`, `onOutsidePress`	Declared keyboard input and island dismissal; see keyboard input.

Popouts, desktop resources, and workspace targets

Property	Meaning
`popout`	Shorthand for opening the widget’s `popout(ctx)` when no explicit click action is present. Equivalent to `onClick = ui.popout`.
`bridge`	On a popout root, stretches its background toward the opening bar item. Clicks there still reach the bar. In a clear popout only drawn/actionable elements catch the pointer.
`attach`	On a popout root, places the panel flush with its bar instead of leaving the usual gap.
`open`, `close`	Explicit opening/closing seconds for shader progress; see shader timing.
`accepts`, `onDrop`, `onDropHover`, `dragItems`, `onDragOut`	Resource drop/drag declarations; see resources and desktop services.
`target`, `menu`, `preview`, `drag`, `drop`	Managed window/workspace interaction metadata for bar items. Targets use IDs from `ctx.data.bar`. `menu` enables the native target menu, `preview` enables window previews, `drag` starts managed-item dragging, and `drop` publishes a managed-window destination. Shift-click a bar target moves the focused window there. These are separate from Resource dragging.

Pointer hit testing follows drawn/actionable shapes: shader transparent pixels pass through, path outlines define their targets, and stack masks constrain hits. Transparent island windows still require a live click-through check on the target macOS system; cached island hit rectangles conservatively include rounded corners and path holes.

Complete common properties

`Props`

export type Props = {
    accepts: { ResourceKind }?,
    onDrop: ((ctx: Context, event: DropEvent) -> ())?,
    onDropHover: ((ctx: Context, event: DropHoverEvent) -> ())?,
    dragItems: { Resource }?,
    onDragOut: ((ctx: Context, event: DragOutEvent) -> ())?,
    appear: Presence?,
    exit: Presence?,
    key: string?,
    rotate: number?,
    loop: { dx: { number }?, dy: { number }?, rotate: { number }?, paused: boolean? }?,
    trail: boolean?,
    w: number?,
    h: number?,
    grow: number?,
    gap: number?,
    pad: number?,
    center: boolean?,
    fill: Color?,
    material: Material?,
    blurRadius: number?,
    saturation: number?,
    bridge: boolean?,
    attach: boolean?,
    open: number?,
    close: number?,
    enter: Enter?,
    mask: boolean?,
    border: Color?,
    borderWidth: number?,
    radius: number?,
    opacity: number?,
    hover: Color?,
    hoverScale: number?,
    hoverOpacity: number?,
    help: string?,
    animate: Animate?,
    hoverAnimate: (Motion | number)?,
    hoverMaterial: Material?,
    onClick: Click?,
    onRightClick: Click?,
    onScroll: Click?,
    onPress: InputHandler?,
    pressScale: number?,
    pressOpacity: number?,
    pressFill: Color?,
    pressAnimate: Animate?,
    onHover: InputHandler?,
    hoverDelay: number?,
    hoverGrace: number?,
    gesture: Gesture?,
    onGesture: InputHandler?,
    gestureEvents: ("boundary" | "all")?,
    scrollMomentum: ("consume" | "deliver")?,
    focusable: boolean?,
    focusRing: boolean?,
    keys: { string }?,
    onKey: InputHandler?,
    onOutsidePress: InputHandler?,
    popout: boolean?,
    align: Align?,
    dx: number?,
    dy: number?,
    scale: number?,
    shadow: Color?,
    shadowRadius: number?,
    target: string?,
    menu: boolean?,
    preview: boolean?,
    drag: boolean?,
    drop: boolean?,
    scroll: boolean?,
    [number]: Element,
}

Fields: accepts, onDrop, onDropHover, dragItems, onDragOut, appear, exit, key, rotate, loop, trail, w, h, grow, gap, pad, center, fill, material, blurRadius, saturation, bridge, attach, open, close, enter, mask, border, borderWidth, radius, opacity, hover, hoverScale, hoverOpacity, help, animate, hoverAnimate, hoverMaterial, onClick, onRightClick, onScroll, onPress, pressScale, pressOpacity, pressFill, pressAnimate, onHover, hoverDelay, hoverGrace, gesture, onGesture, gestureEvents, scrollMomentum, focusable, focusRing, keys, onKey, onOutsidePress, popout, align, dx, dy, scale, shadow, shadowRadius, target, menu, preview, drag, drop, scroll