dymokomi/luce-ui
Source of release 0.19.5
0.19.5 / README.md
# luce-ui
A UI framework written in Luce Base, consumed through ordinary Base structs or
Luce objects. Controls implement `Widget`; an `Application` owns the native event
loop, layout, input routing and presentation. The package uses standard `gpu` and
`window`: Metal on ARM64 macOS and Vulkan on Windows x64. Linux supports the
portable tests and font backend; native window presentation is still pending.
A Luce application uses public imports and normal construction:
```luce
from luce_ui.ui import Application, Button, Text, VStack
pub func main(arguments: list[str]) -> int!:
let button = Button("Continue")
let content = VStack([Text("Hello Luce"), button], padding = 24.0)
let app = Application(content, title = "Hello")
app.run()
return 0
```
Declare `[dependencies] luce_ui = "../luce-ui"` in the consumer's `luce.toml`.
The separate `luce-demos` project connects a button to a counter and runs the UI.
No application loop, generated Base sources or platform framework declarations
are needed in a consumer.
When an application crashes, it does not just disappear: luce-ui starts it again to show
the crash report in a window of its own, with Copy, Reopen and Quit, and
`app.on_crash(callback)` gives it a chance to save its work first. See "Crash reports and
the crash window" in API.md.
Read [API.md](docs/API.md) for ownership, callbacks, custom widgets and layout;
[DESIGN.md](docs/DESIGN.md) describes the framework contracts.
Build the sibling `luce-base` and `luce` repositories (main; `python3
../luce-base/tools/checkout_main.py . ../luce` checks out what is missing). Then run:
```sh
luc test
```
That runs every module's `test` blocks and four test programs: `tests/ownership` (a Base
consumer) and `tests/controls` (Luce custom widgets) everywhere, and on a macOS desktop
`tests/pixels` (Metal pixels, clipping, resize and expired viewport references) and
`tests/crash_relaunch` (a program that traps is started again to show its crash window) and
`tests/crash_quiet` (with `LUCE_CRASH_WINDOW=0`, a trap in the run loop or on a worker
thread ends the process and starts nothing); without a desktop those are skipped.
Test binaries and compiler scratch files are temporary. A specifically requested
consumer binary can be built with `python3 tools/build.py ENTRY -o OUTPUT`.
This is an early framework with native antialiased fonts, multiline editing, lists,
menus, toolbars, bordered panes, resizable splits, code folding, shared actions and
inherited themes. Paragraph shaping,
accessibility, general scrolling containers and a broad widget catalog remain
future work. MIT or Apache-2.0, at your option.
## Windows x64
Build sibling `luce-base` and `luce` checkouts with `python tools/build_windows.py` in each compiler repository. Run `luc test` in this repository.
For real windows and rendering, install the Vulkan SDK and start a fresh terminal with `VULKAN_SDK` set. The sibling `luce-demos` UI and sphere applications exercise Win32/Vulkan presentation. CPU tests run in hosted Windows CI; GPU smoke tests require an interactive desktop and Vulkan hardware.
Typography is shared explicitly: `let font = Font()`, then
`Button("Save", font = font)` and `TextEditor(source, font = font)`. `Font` loads an
installed monospace family (`family = "Menlo"`, for example); omitting the family
selects Menlo on macOS, Consolas on Windows, and the fontconfig monospace family
on Linux. All text controls use the same 12-point default (`ui.default_font_size`).
Font metrics also drive editor hit testing, caret positions and line spacing;
leading is one third of the font size.
Stacks use an 8-point gap (`ui.default_spacing`), and dialogs use that gap with
12-point padding (`ui.default_padding`). Buttons, fields, menus, tab bars and
section headings size themselves from the font. Explicit font sizes and layout
spacing remain logical points.
The UI owns a bounded cache of grayscale text runs. Standard `fonts` owns native
font resources; standard `gpu` uploads coverage and draws it through the selected
Metal or Vulkan backend. Rendering follows the window backing scale instead of
stretching a low-resolution font. Linux font loading needs Cairo/FreeType and an
installed monospace font (`libcairo2-dev fonts-dejavu-core` on Debian/Ubuntu).
Linux window/GPU presentation remains a separate, unimplemented backend.
This first font API loads installed families, not arbitrary font files. Text is
laid out on the editor's scalar grid; paragraph shaping, bidi, grapheme-aware
editing, color emoji, and a font picker remain future work. Windows substitutes
a replacement glyph for supplementary-plane scalars in this initial GDI adapter.
## Compact application composition
`Toolbar([Menu("File", [save]), Spacer(), Button(action = save)])` presents the
same `Action` through two controls. Register it with `Application.set_actions`
for window shortcuts. `Shortcut(Key.s, primary = true)` uses Ctrl or Command;
matching repeated key-down events do not invoke an action repeatedly.
`Application(content, theme = Theme())` supplies inherited semantic colors and
metrics. `Theme(control_lines = 2.0)` gives controls more vertical room. The default
is one font line with one character cell of horizontal inset. A subtree can use
`layout().set_theme(...)`, then `inherit_theme()` to return to its parent's theme.
Typography remains explicit: pass one shared `Font` through your view components.
To follow the system's light or dark setting (what CSS calls `prefers-color-scheme`),
read `app.appearance()` (`Appearance.light` or `.dark`, also before `run`) and pick a
theme, then connect `app.on_appearance(callback)`: the loop calls it with the new
value when the user switches, and the callback can call `set_theme`. Release or
`disconnect` the connection to stop. The default `Theme()` is dark; a light palette is
the application's to define.
See [composition contracts](docs/DESIGN.md), [the API](docs/API.md), and
[text change/highlight contracts](docs/TEXT-EDITOR.md). The separate
[luced editor](https://github.com/dymokomi/luced) composes named Luce views from
these Base controls; its entry point contains no geometry or signal wiring.
`SplitView(Pane(sidebar), SplitView(Pane(editor), Pane(output), axis=Axis.vertical))`
builds a bordered workspace with draggable dividers. Children supply minimum and
maximum sizes, and splits can nest. Generic `TextEditor.set_folds` accepts ranges
from a language service; Luce syntax knowledge stays in luced. See the
[pane API](docs/API.md#panes-and-split-views) and
[folding contracts](docs/TEXT-EDITOR.md#folding-and-viewport-bounds).
Context menus decorate any widget: `ContextMenu(content, actions, font=font)`.
`CommandPalette(actions, font=font)` supplies command search, and `TextPrompt`
supplies file-name entry or confirmation. Both mount as popup children and reuse
the framework's focus restoration, text input and window clipping. Panes use
`Theme.active_border` to indicate descendant focus; `Theme.gutter` styles the
folding margin independently. See the [popup API](docs/API.md#context-menus-command-search-and-prompts).
Layout tracks hover independently of focus and capture, exposing `is_hovered`,
`contains_pointer` and local `pointer_position` to every widget. Menus switch
between sibling titles during an open session. Panes, controls, list rows and
editor gutters use inherited hover colors. Popup shadows are sharp translucent
rectangles with configurable offset and opacity. See the
[hover API](docs/API.md#hover-and-menu-sessions).
Pane headers join directly to their frames:
```luce
let files = ListView([ListItem("src", icon = IconKind.folder)], font = font)
let header = PaneHeader("FILES", icon = IconKind.folder_open, detail = "project", font = font)
let sidebar = Pane(files, header = header)
```
The header shares the border's normal, hover and focus colors, with a vector
icon and 1.5 character cells of leading inset. `Theme.header_inset_cells`
adjusts this spacing. Reusable `Icon` widgets, pane icons and list symbols use
the same vector shapes through standard `gpu`; they scale with the shared font.
Portable tests cover header layout, resizing, font changes and icon-bearing
lists. Native Metal readback verifies frame colors and icon pixels.
`DStack` supplies a dynamic workspace of tabbed panels:
```luce
let files = Panel("FILES", explorer, icon = IconKind.folder, closable = false)
let source = Panel("main.luc", editor, icon = IconKind.code)
let workspace = DStack([files, source], font = font)
workspace.move(source, files, DockPosition.right)
```
Every group has a trailing `+` menu listing the application's panels
(`set_catalog`) and Split Right/Down. Applications make a picked panel in
response to `on_add`; `set_close_handler` can refuse closing an unsaved document. Header
dragging moves tabs: dropped on a tab strip they stack, on a pane's edge they
split it, and anywhere else they float in their own window over the panes. A
floating window moves by its title, resizes by its border, closes by its `×`, and
docks again when its title is let go over a tab strip or pane edge or pressed
twice. `float(panel)` floats a docked panel or adds a new one floating.
The source detaches visually while dragging: neighbors expand and a floating
caption follows the pointer. Drop previews use that expanded layout and respect
minimum sizes. Escape restores the original layout. Nested dividers resize live,
and empty branches collapse. Text, actions, pane headers and dividers select
semantic system cursors through the standard window API. Panels retain their
content, focus targets and identity across these operations. See the
[dynamic workspace API](docs/API.md#dynamic-workspaces) and [design](docs/DSTACK.md).