moonframe-components — скилл для Claude Code
Скилл moonframe-components для Claude Code с каталогом готовых элементов интерфейса Moonframe. Перед созданием или изменением UI он помогает найти подходящий компонент и узнать его параметры.
MIT ★ 124 обновлён 2026-11-16
npx skills add moonframehq/moonframe --skill moonframe-components -a claude-codeЧто делает moonframe-components
Скилл описывает элементы ui.* и компоненты Moonframe: где их применять, какие параметры они принимают, какие классы оформляют и как их вызывать. Каталог помогает выбрать готовый компонент вместо написания нового, а также показывает, как собрать интерфейс из нескольких компонентов.
Материал охватывает панели, боковые меню, диалоги, меню и страницы настроек. В нём также описаны списки, разделяемые области и работа с изображениями. ui.image принимает файлы из папок приложения или кэша Moonframe, но не URL: изображение по ссылке сначала должен загрузить провайдер.
Какие задачи решает
- найти готовый компонент для панели Moonframe
- узнать параметры элемента
ui.* - собрать интерфейс из существующих компонентов
- проверить, какие классы оформляет компонент
Примеры запросов агенту
- Найди готовые компоненты Moonframe для боковой панели и перечисли их параметры.
- Какой элемент Moonframe использовать для длинного списка файлов?
- Проверь каталог компонентов и подскажи, как вывести изображение из файла приложения.
Как установить moonframe-components
1Через Skills CLI (Vercel)
npx skills add moonframehq/moonframe --skill moonframe-components -a claude-code2Вручную: положить файлы
~/.claude/skills/moonframe-components/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/moonframe-components/
1Через Skills CLI (Vercel)
npx skills add moonframehq/moonframe --skill moonframe-components -a codex2Вручную: положить файлы
.agents/skills/moonframe-components/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add moonframehq/moonframe --skill moonframe-components -a cursor2Вручную: положить файлы
.cursor/skills/moonframe-components/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install moonframehq/moonframe .claude/skills/moonframe-components2Вручную: положить файлы
.github/skills/moonframe-components/SKILL.md1Через Skills CLI (Vercel)
npx skills add moonframehq/moonframe --skill moonframe-components -a gemini-cli2Командой платформы
gemini skills install https://github.com/moonframehq/moonframe --path .claude/skills/moonframe-componentsВручную: положить файлы
.devin/skills/moonframe-components/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Claude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о moonframe-components
Как установить moonframe-components в Claude Code?
Выполни npx skills add moonframehq/moonframe --skill moonframe-components -a claude-code. Файл скилла находится по пути ~/.claude/skills/moonframe-components/SKILL.md.
Что делает moonframe-components?
Скилл служит каталогом готового UI Moonframe. Он описывает элементы и компоненты, их параметры, стилизуемые классы и способы вызова.
Можно ли передать URL в ui.image?
Нет. ui.image загружает файл из папок приложения или кэша Moonframe; изображение по URL должен сначала скачать провайдер.
Исходный текст
SKILL.md · MIT
---
name: moonframe-components
description: The full catalogue of ready-made UI in Moonframe, every host element (`ui.*`) and every component (`use "name"`), with when to use each, its props, the classes it styles, and how to call it. Read it before building or changing any UI in Moonframe (a mod, a panel, a sidebar, a dialog, a menu, a status bar item, a settings page), to pick an existing piece instead of writing a new one. Generated by `just components`; pairs with the moonframe skill.
---
<!-- Generated by `just components` from app/components and
crates/moonframe-core/src/catalogue/elements.md. Do not edit by hand. -->
# Moonframe components
Everything a mod can draw. Prefer, in order: a component that fits, a
component with a `class` and a `style.luau` rule, a composition of
components, and only then new `ui.*` code. See the moonframe skill for
how mods, styles and providers work.
## Host elements
The `ui.*` functions the host draws itself. Components are built from these.
Text-like elements take their main value positionally: `ui.text "hi"`,
`ui.button { "Save", msg = "save" }`.
### Layout
| Element | Use it for | Keys (besides children) |
| --- | --- | --- |
| `ui.row { ... }`, `ui.column { ... }` | any box of children; with `msg`/`command` the whole box is clickable (rows, tabs, tiles); `drag = true` makes it a title bar that moves the window | frame keys, `align`, `justify`, `wrap`, `selected`, `drag`, `key` (names it among its siblings: with a `transition` rule it grows in as it appears and shrinks away as it goes; with `rise` it fills its box and comes up from below it whole, once the one it replaces has sunk away), `msg`/`to`, `command` or `window` (a mod opened in a window of its own), pointer keys, extras |
| `ui.panel { ... }` | a titled section with header actions over a body | frame keys, `title`, `actions = { elements }` |
| `ui.hsplit { ... }`, `ui.vsplit { ... }` | areas the user resizes by dragging; children must be `ui.pane` | `id` |
| `ui.pane { ... }` | one side of a split; slides in and out when `visible` changes; `lazy = true` starts what it mounts only once it first shows, and keeps it asleep (not run, not drawn) while hidden | `size`, `min`, `max`, `fixed`, `visible`, `lazy`, `gap`, `padding`, `surface`, `scroll` |
| `ui.list { count = n, row_height = 24, row = function(i) ... end }` | long lists of same-height rows (files, logs, results): only the rows that show are built and drawn, so any length costs a screenful; it scrolls itself and takes the space it is given | `id` (two lists in one mod need two), `count`, `row_height`, `row` (builds row `i`, from 1; called again as it scrolls, so keep it cheap), frame keys |
| `ui.region "name"` | the slot mods fill by naming it in `region` (shell only) | `name`, `direction`, `gap`, `justify` |
| `ui.mount "name"` | one mod's view, by name | `mod` |
| `ui.divider()` | a line across the parent's axis | |
| `ui.spacer()` | take the free space, to push what follows to the far end | |
### Namespaced mods and providers
Embedding apps can select miniapps outside `app_dir` with `Moonframe::root`
and `entry`, or `entry_handle().add_entry(namespace, id, path)` at runtime.
Roots set policy without scanning. An entry holds `main.luau` and/or
`provider/provider.toml`: mount `ui.mount "mshub:notes"` (or give it an `id`
for independent instance state), read `app["mshub:notes"]`, send to
`"provider:mshub:notes"`, and subscribe to `"provider/mshub:notes"`.
Saved mod/instance state includes the namespace. Namespace and id each use
1–48 of `a-z 0-9 - _`; `app provider topic demo component shell parent` are
reserved namespaces. `remove_entry` / `remove_root` unload them without
erasing saved state. An entry's own `components/<name>.luau` come first for
its `use` (and only its), and its `style.luau` (`style { rules = { ... } }`)
styles only what it draws. `entry_embedded::<E>(namespace, id)` ships one in
the binary; `moonframe::check_entry` reports its problems.
An element given a key it does not take, a wrong token or an unknown icon
draws a warning sign in its place and is reported to the host as a
`ViewDiagnostic` (path, key, value, line, suggestion). `padding` and `gap`
take `none`, `small`, `normal` or `large` on an element; pixels go in
`style`. Check a miniapp with data (ship a `sample.json` with what its
provider publishes) so branches that only draw with data are checked too.
`moonframe::schema()` lists every element and its keys as data.
Prefer sandboxed Wasm for end-user providers. The host registers namespaced
JSON capabilities with `capability` / `capability_async`; a guest declares them
in `provider.toml` and calls `moonframe_provider::host_call` from the Rust SDK.
`RootPolicy::default()` accepts only prebuilt Wasm (no Cargo crate) and disables
process/socket kinds. Native providers are compiled into the host and bind by
the full entry name. Entry files reload live, failed replacement mods or Wasm
builds retain the old revision, and `on_entry_status` reports progress/errors.
Stateful entry providers survive clean restarts. See `docs/wasm-providers.md`
for the API, limits, caller identity and build policies.
### Content
| Element | Use it for | Keys |
| --- | --- | --- |
| `ui.text "..."` | any text; a bare string child is plain text | `text`, `tone`, `size`, `weight` (`light` `normal` `medium` `semibold` `bold`), `truncate` (one line), `lines` (at most N lines), `wrap = false` (keep lines whole, for code that scrolls sideways), `syntax` (color it as code in this language, a line at a time), extras |
| `ui.icon "name"` | a bundled icon at the text's size and color; `spin = true` turns it (loaders). Lucide glyphs (git: `git-branch` `git-commit-horizontal` `git-merge` `git-pull-request` `git-pull-request-draft` `git-pull-request-closed` `git-compare` `circle-dot`), agent logos `agent-claude` `agent-codex` `agent-gemini` `agent-cursor` `agent-copilot` `agent-opencode` `agent-amp` `agent-droid` `agent-kiro` `agent-qwen` `agent-grok`, brands `brand-github` `brand-gitlab` `brand-anthropic` `brand-openai` `brand-mistral` `brand-ollama`; the full list is `IconName` in types/moonframe.d.luau | `name`, `tone`, `size`, `spin`, extras |
| `ui.image "avatar.png"` | a picture from a file inside the app's folders or `~/.cache/moonframe/images` (relative to the mod, `~/`, or absolute; no URLs: a provider downloads into that cache); `radius` rounds it into an avatar | `src`, `width`, `height`, `fit` (`contain` `cover` `fill` `scale-down` `none`), `zoom` (screen pixels per picture pixel, 1 is 100 %: a viewer that fills its parent unless sized) panned to `center = { x, y }` (fractions of the picture), `overlay = { elements }` drawn over the picture wherever it lands (their `area` is in fractions of the picture: a crop frame, spots), `measure` (sent with the picture's `width`, `height`, `box_width`, `box_height` and the `fit` zoom when they change), extras |
| `ui.badge "..."` | a small pill: counts, tags, states | `text`, `tone`, extras |
| `ui.terminal { id = "main" }` | a live shell that fills its space | `id`, `cwd`, `engine` (`alacritty`, `ghostty`), `exit` (sent once, with `exited = true` added, as the shell exits; without it Enter starts another) |
| `ui.browser { id = "docs", url = "https://..." }` | a web page in a native view that fills its space (macOS, Windows; Linux offers the system browser); drive it with `command = "browser-back"` (`-forward`, `-reload`, `-stop`) and `browser = "<id>"` on a control | `id`, `url` (http, https, file), `zoom`, `navigate` (sent with `url`, `title`, `loading`, `back`, `forward` added) and `loading` (with `loading`, `url`); a `ui.input { browser = "<id>" }` is its address bar |
| `ui.markdown "# Notes"` | a markdown document drawn by the host (headings, emphasis, lists, task lists, tables, quotes, `> [!NOTE]` alerts, footnotes, frontmatter, highlighted code with a copy button; LaTeX in a build with `math`), up to 1 MiB; links send `link` instead of opening, a `#heading` link scrolls there, a `[label](cite:source)` link draws a source chip, and pictures show only with `images`, never from the web; styled by `markdown`, `markdown-code`, `markdown-quote`, `markdown-alert`, `markdown-find` and `markdown-find-current` rules | `text`, `link` (sent with `url` added), `to`, `grow`, `scroll`, `width`, `height`, `max_width`, `lines` (at most N lines, for a preview), `images`, `image` (a click on a picture on its own line, with `src` and `alt`), `outline` (sent with `headings`: `level`, `text`, `at`, `slug`), `section` (sent with `heading`, the index being read), `reveal = { at, seq }` (scrolls there when it changes), `find`, `find_index`, `found` (sent with `count`), `stream` (fade in what is added), `scrolled` (with `scroll`: sent as the reader scrolls, with `fraction`, 0 at the top to 1 at the end), `scroll_at = { fraction, seq }` (with `scroll`: scrolls there when it changes, without sending `scrolled`) |
| `ui.paths { paths = { { points = { 0, 8, 40, 8, 40, 30 }, arrow = "end", radius = 6 } } }` | lines the view places in pixels from its top-left corner: arrows between dependent bars, connectors in a diagram; without `width` and `height` it fills its parent, so it floats over what it links (`float = "fill"` on a wrapper) | `paths` (each `points` flat x, y pairs, `color`, `stroke`, `dashed`, `radius` rounds its corners, `arrow` `end` `start` `both`), `width`, `height` |
| `ui.map { pins = { { lat = 37.79, lon = -122.40, label = "1" } } }` | a street map from a tile provider with numbered pins and routes over it; drag pans, the wheel, a pinch, a two-finger double tap, a double click and its buttons zoom, and two fingers turn it (it settles on north within a few degrees); without `center`/`zoom` it frames the pins and routes. With `glide`, a new `center`, `zoom` or `bearing` eases the map there. Tiles come only from the listed providers, cached under the cache folder; the provider's credit shows in the corner. Built with the `map` feature (the starter and sealed apps using it have it; elsewhere it marks its spot) | `provider` (`openstreetmap`, the default, and `carto-light` `carto-dark` `carto-voyager` `esri-streets` need no key; `stadia-smooth` `stadia-smooth-dark` `maptiler-streets` `mapbox-streets` `thunderforest-transport` need `key`), `center = { lat, lon }`, `zoom`, `bearing` (the compass direction up the box, degrees clockwise from north; a new one turns the map where it stands, so feed `move`'s back in and a compass shown while it is not 0 sets it to 0 on a click), `pins` (each `lat`, `lon`, `label` up to 3 characters or `icon`, `color`, `shape` `dot` `disc` `balloon`, `selected`, `pulse` (a halo breathes out of it: where the user is), `msg`), `routes` (each `points` flat lat, lon pairs drawn as they are, or `via` stops and `mode` `walk` `bike` `car` routed along streets by routing.openstreetmap.de; `color`, `stroke`, `dashed`; the style's `color` otherwise), `routed` (sent with `route`, `seconds`, `meters` once a `via` route is found), `move` (sent with `lat`, `lon`, `zoom`, `bearing` after the user moves it, as they go), `select` (sent with `pin`, its index, on a click), `to`, `width`, `height`, `grow` |
| `ui.video { source = "camera", white = 4095 }` | live frames from another process, from a ring in shared memory, in a 16-bit colour-managed native view that fills its space (macOS, the `video` feature); nothing draws over it, so `guides` draws crop frames and lines in the picture. `source`, `id`, `zoom`, `center`, `filter` (`auto` `nearest` `linear`), `color` (`srgb` `display-p3` `rec709` `rec2020` `linear-srgb` `linear-p3` `none`), `extended`, `black`, `white`, `gain`, `gamma`, `guides`, `probe`, `stats`, `probed`, `width`, `height`. Most apps want `video-viewer`; see `docs/video.md` |
| `ui.view { name = "chart", id = "sales", props = {...} }` | a view the app writes in Rust and registers by `name` (apps on the Moonframe library; the starter registers none): what Luau can't draw, such as an editor or a canvas. Kept by mod and `id`, it gets `props` again when they change, and sends this mod's `update` messages of its own | `name`, `id`, `props`, `class`, `style` |
### Controls
`ui.revision_timeline { entries = { { id = "r1", day = "Today", label = "10:30" } }, selected = "r1", select = "pick" }`
is a native, right-aligned Time Machine ruler. Nearby ticks smoothly magnify like the Dock.
Entries are ordered top to bottom; adjacent equal `day`s form groups. Clicking selects a revision;
after focusing it, Up/Down choose revisions, Shift-Up/Down jump days, and Home/End reach either end.
The wheel scrolls long histories. `select` receives `revision` (stable id), `index` (one-based),
`day` and `label`. Also takes `id`, `to`, `width` (240), `height` (420), `grow`, `disabled`,
`class`, `style`, `state`. Up to 10000 unique ids. Style with `revision-timeline` (`color` is
the selected tick); respects `animation_speed`, including 0. Use `revision-timeline` for a gallery demo.
The same element supports compact chat rails: `side = "left"`, `dates = false`,
`labels = "hover"`, `preview = true`. Entries need only `id` and `label`; optional `day`
groups revisions, and `summary` adds up to three lines to the preview card.
`labels` is `all` (day groups and active label), `active` (hover or selection), `hover`, or `none`.
`width` includes room for labels/cards; `tick_width` (default 12, 1–128 px) controls the rail itself.
Also configurable: `tick_height` (2, 0.5–16 px), `spacing` (9, 4–64 px),
`magnification` (4.5, 1–10; 1 disables it), `radius` (4.5, 1–20 neighbours), and
`spread` (1.8, 0–5; 0 keeps centers fixed). `side` defaults to `right`, `dates` to true,
and `preview` to false. Preview cards are noninteractive and stay inside the component's box.
| Element | Use it for | Keys |
| --- | --- | --- |
| `ui.button { "Label", ... }` | an action with a label and/or an icon (`icon` alone is an icon-only button) | `label`, `icon`, `variant`, `small`, `disabled`, `msg`/`to` or `command`, extras |
| `ui.item { "Label", ... }` | a plain selectable list row | `label`, `detail`, `badge`, `selected`, `msg`/`to` or `command`, extras |
| `ui.input { id = "title", value = state.title, change = "type" }` | a text field the host edits (`multiline` for a text area); what the user typed stays across renders, `value` replaces it when the mod passes a new one. A writing field with `prose` (markdown styled as typed), `dim = "sentence"` or `"paragraph"` (focus mode: the rest fades) and `typewriter` (the caret's line stays in the middle), as `prose-editor` draws it. A code editor with `code = "luau"` (any language: colored as typed, with line numbers; read only with `disabled`, not dimmed) | `id`, `value`, `placeholder`, `change` (each edit, with `value` and `caret`, the bytes before the caret), `select` (selection movement, also with `value`, `caret` and `selected`, the bytes selected), `submit` (Enter, or ⌘↩ when multiline), `blur` (with `value`, as it loses focus: save a title edited in place), `keys`, `capture` (every chord pressed, with `keys` added, instead of editing: records a shortcut), `to`, `multiline`, `rows`, `max_rows` (grows with its lines up to it), `focus`, `disabled`, `mono`, `width`, `grow`, `browser`, `prose`, `dim`, `typewriter`, `code`, `line` (a code editor's caret goes there), `scrolled` (multiline: sent as the text scrolls, with `fraction`, 0 at the top to 1 with the last line at the bottom), `scroll_at = { fraction, seq }` (multiline: scrolls there when it changes, without sending `scrolled`); a source and its `ui.markdown` preview follow each other with the two |
### Overlays
| Element | Use it for | Keys |
| --- | --- | --- |
| `ui.popover { ..., content = el }` | content floating beside its anchor (the children): dropdowns, context menus, sheets from a status bar; `side` is `top`, `bottom`, `left` or `right` (it opens on the other side when that one has no room in the window), and `align` (`start`, `end`) the anchor's edge it lines up with; `anchor_clicks = true` keeps the anchor clickable while open (a field with suggestions under it) instead of a click on it sending `dismiss` | `open`, `dismiss`, `to`, `side`, `align`, `gap`, `width`, `content`, `keys`, `anchor_clicks` |
| `ui.overlay { ..., content = el }` | content over the whole window: dialogs and palettes (`center`, `top`), sheets (`left`, `right`, `bottom`), toasts (`top-end`, `bottom-end`, ...) | `open`, `dismiss`, `to`, `place`, `backdrop`, `width`, `height`, `keys`, `content` |
**Keys** (`overlay`, `popover`): `keys = { escape = msg, enter = msg, up = msg,
down = msg, ["secondary-k"] = msg }` while it is open and topmost; nothing
else sees those keys. Escape sends `dismiss` unless `keys` names `escape`.
`to = "mod"` sends `dismiss` and `keys` messages to another mod. A click
goes to the innermost clickable element only.
Names are modifiers (`ctrl`, `alt`, `shift`, `cmd`, `secondary` = cmd on
macOS, ctrl elsewhere) then a key, joined by `-`.
### Shared keys
- **Scroll to a child** (`row`, `column`): with `scroll` enabled,
`scroll_to = 12` reveals direct child 12 (one-based) when the index
changes. It scrolls only as far as needed and leaves wheel scrolling
free between changes. Set it to nil to reset the request.
- **Frame keys** (`row`, `column`, `panel`): `grow`, `width`, `height`,
`gap`, `padding`, `surface`, `border`, `scroll` (`true` along its axis, or `"x"`, `"y"`, `"both"`: code that scrolls sideways), `follow = true` (with `scroll`:
while at its end, stay there as the content grows, as a chat or log
does), `shrink = false` (keep
the content's size instead of being squeezed), `self_align` (`start`,
`center`, `end`, `stretch`: e.g. keep a capsule at its own width inside a
column, which otherwise stretches it), `hug = true` (keep its own width in
a column, and follow a row's `align`: the usual choice for pills, badges
and dots), `max_width`, `max_height`,
`float` (out of the flow, over the parent: pinned to an edge or corner,
`float = "top-right"` (`top-left`, `bottom-left`, `bottom-right`, `top`,
`bottom`, `left`, `right`, `fill`), set in from it,
`float = { at = "top-right", inset = 4 }`, or at pixel offsets,
`float = { top = -4, right = -4 }`, negative overhanging: a count bubble
on an icon's corner), `area` (out of the flow at fractions of the parent,
`area = { left = 0.1, top = 0.2, width = 0.5, height = 0.3 }`: a crop
frame, a marker on a track). `grow` with a `width` or `height` grows from that size.
- **Pointer keys** (`row`, `column`): `pointer = <msg>` is sent as a button
goes down on it, as the pointer moves while held (anywhere in the
window), and as it comes up, with `phase` (`down` `move` `up`), `x`, `y`
(fractions of the box as it was at the press), `dx`, `dy` (pixels since
the press), `width`, `height`, `button`, `clicks` and the keys held
(`shift` `alt` `ctrl` `cmd` `secondary`) added. `hover = true` also
sends `hover` moves and `leave`. `range = { min, max, step, value, speed,
axis }` adds the `value` a drag sets: where the pointer is between `min`
and `max` (a slider), or `value` plus pixels times `speed` (a number
scrubbed by its label). `wheel = <msg>` gets scrolls and pinches (`dx`,
`dy`, `zoom`, `x`, `y`). On a Mac trackpad, `rotate = <msg>` gets two fingers
turning (`angle` in degrees clockwise since the last message, `phase`
`start` `move` `end`), `smart_zoom = <msg>` a two-finger double tap,
`swipe = <msg>` a finished swipe (`direction` `back` `forward` `up` `down`)
and `force = <msg>` a force click (`pressure`), each with `x`, `y`;
`drop = <msg>` gets files dropped from other
apps (`paths`), which that mod's `ui.image` may then show; `cursor` sets the pointer's
shape (`crosshair`, `grab`, `grabbing`, `ew-resize`, `ns-resize`,
`nwse-resize`, `nesw-resize`, `move`, `pointer`, `text`, `not-allowed`).
- **Drag and drop** (`row`, `column`): `carry = <data>` lets the user drag
it (a card, a row, a calendar event); a box of its size, the `carry`
rule, follows the pointer while it dims, and a click still clicks.
`accept = <msg>` on another row or column is sent as it moves over it
(`phase = "over"`), off it (`"leave"`) and is dropped on it (`"drop"`),
with `carry` (the data), `from` (the mod that drew it), and `x`, `y`
(fractions of the target's box: before or after a row's middle) added.
The innermost target takes the drop; nothing follows a drop, so clear
what `over` showed then. Other entered targets hear `leave` when the
drag ends, including cancellation. Not with `pointer` or `drag`.
- **Children:** `false` and `nil` children are skipped, wherever they are.
- **Look keys** (every element but splits): `class = "a b"`,
`style = { ... }`, and `state = "open"`: a state of the view's own naming,
which `:open` rules match (`[".drawer:open"] = { width = 280 }`). With a
`transition` in its rules, a change of state eases colors, opacity,
width and height from one state's look to the next.
- **Actions:** `msg = <data>` calls the drawing mod's `update` (`to = "name"`
for another mod or `"provider:<name>"`); `command = "..."` runs an app
command instead: `quit`, `reload`, `toggle-theme`, `minimize`, `maximize`,
`close-window`. A browser command (`browser-back`, `browser-forward`,
`browser-reload`, `browser-stop`, `browser-open`) also takes
`browser = "<id>"`. To run a command from `update`, without a click, send
`{ to = "app:command", msg = "minimize" }`.
- **Files:** `{ to = "app:pick", msg = { kind = "open", types = { "tif" },
multiple = true, reply = "opened" } }` opens the system's panel (`kind`
`open`, `folder` or `save` with `name` and `folder`); the answer comes
back to the mod as `reply` with `paths` (`path` for a save) or
`cancelled = true`. Picked files may then show in that mod's `ui.image`.
- **Text edits:** `{ to = "app:edit", msg = { field = "notes", wrap = {
"**", "**" } } }` edits the mod's `ui.input` with that `id` around its
selection, keeping undo and focus: `wrap` puts the two around it (or
takes them off), `lines = "- "` starts each selected line with it (or
takes it off), `insert = "@Sam ", back = 3` replaces the selection and
the 3 bytes before it. A completion can add `at = <caret offset>` and
`expect = "@sa"`: it applies only with an empty selection there and that
exact preceding text (`back` must equal its byte length). The field then
sends its `change`. A toolbar button sends directly (`to = "app:edit"`);
editing restores focus in the field's own window.
- **Keys anywhere:** `mod { keys = { ["secondary-1"] = "histogram" } }`
sends its message when the key is pressed and nothing nearer (an open
overlay, a terminal) took it, to every mod and every mounted copy of
one (a tab's) that takes it. While a text field has focus it keeps all
its keys, so mods hear none.
- **Window:** the shell's `mod { window = { titlebar = "hidden",
traffic_lights = { x, y } } }` draws the layout under the title bar (at
startup only); `app.window` tells views the `platform`, `titlebar`,
`maximized`, `fullscreen` and `active`, so a title bar knows whether to
draw window buttons or leave room for traffic lights. The main window
reopens where and as large as it last was, kept within the screen;
`window = { remember = false }` opens it at its `size`, centered, instead.
- **A mod's own window** takes `titlebar = "hidden"` and `traffic_lights`
in its `window` too, beside `size` and `min_size`, with `drag = true` on
what moves it. While open, the mod and its instances read that window's
state as `app.window`; closing it restores the main window's state.
The mod's view is shared wherever it is mounted.
`window = "<mod>"` on a row or column opens that
mod in a window of its own; from `update`, send `{ to = "app:window",
msg = { open = "<mod>", send = <msg> } }` to open it on a page (`send`
reaches its `update` first) or `{ close = "<mod>" }` to close it. The
mod sizes it with `mod { window = { size = { width, height }, min_size
= { width, height } } }`.
- **Extras** (`row`, `column`, `button`, `item`, `text`, `icon`, `image`,
`badge`):
- `tooltip = "text"` shows under the pointer, styled by the `tooltip` rule.
The rule's `transition` eases it in (`fade`, `slide` rises it a little,
`slide-fade`), and its delay (`"fade fast 400ms"`, or `delay`) is how
long the pointer rests before it shows (500ms without one).
- `context = <data>` is sent on a right-click, to open a context menu
(to `to = "mod"` if given).
- `copy = "text"` puts the text on the clipboard when clicked.
- **`ui.memo(key, deps, build)`** returns what `build()` returned the last
time this view asked for `key` with the same `deps` (a list, compared with
`==`), or calls it now: for a costly part of a view that depends on a few
values. A table counts as the same while it is the same table, even if
changed inside.
- **Words in the user's language:** `ui.t("inbox-unread", { count = n })`
is the message of that ID in the app's `locales/<language>/*.ftl`
(Fluent), in the language the user prefers, English when it lacks one,
and the ID itself when English does too. `ui.number(1234.5, { decimals =
2 })` and `ui.date(seconds, { style = "short", time = true })` write
numbers and dates the language's way; `ui.locale()` names it.
- **Views run only when needed:** a view runs again when its state or props
change (any message to its `update`), when a key of `app` it read
changes, or on a reload; otherwise its last tree is kept. Read `app.x`
where you use it rather than copying all of `app`; going through all of
`app` (`for k, v in app`) runs it on any change.
- **`selected = true`** on a row or column matches `:selected` rules, like an
item: tabs, segments, chosen tiles.
### Style keys
`background`, `gradient` (`"180deg, #ffa53a, #ff6200"`), `color`, `border`, `border_color`, `radius`, `padding`, `gap`,
`margin`, `shadow`, `size`, `weight` (`light` to `bold`, `semibold` between `medium` and `bold`), `font` (`sans`, `mono`), `case`
(`upper`, `lower`, on text), `opacity`, `width` and `height` (under the
element's own; on containers),
`transition` (a second duration is its delay: `"fade 150ms 40ms"`), `delay`
(replaces the transition's delay, set inline per item to stagger a list),
`clip = true` (hide what overflows the box). Selectors: a part (`row`, `item`, `list`, `popover`, `overlay`, `overlay-backdrop`, `tooltip`, `image`, `markdown`, `markdown-code`, `markdown-quote`, `markdown-alert`, `markdown-find`, `markdown-find-current`, ...),
a class (`.tab`), and a state: `:hover`, `:selected`, `:focus`,
`:disabled`, or one the view names with `state = "..."` (`.drawer:open`).
## Components
Call one with `local name = use "name"`, then `name { ... }` wherever an element goes. Its classes can be restyled in `style.luau`.
| Component | Category | Use it for |
| --- | --- | --- |
| [`agent-run`](#agent-run) | Agents | Show what an agent started through `app.acp` is doing or did, with Stop and the answers to its permission questions. For the Send feedback dialog, which lists runs with this, use `feedback`; for a chat transcript use `chat-message`. |
| [`feedback`](#feedback) | Agents | Let the user ask for a change to the app itself, from inside it, and follow what the agent does (`app.acp`). For one run on its own use `agent-run`; for a plain form use `dialog`; for chatting with an agent use `composer`. |
| [`accordion`](#accordion) | Containers | A stack of foldable sections of the same kind: a merge request's checks, files and activity, or groups of settings. The mod decides whether opening one closes the others. For one foldable block use `collapsible`; for sidebar groups use `sidebar-section`; for switching between views use `tabs`. |
| [`card`](#card) | Containers | A titled box around related content inside a panel or page; for a whole sidebar section use `ui.panel`, for a plain heading use `section`. |
| [`collapsible`](#collapsible) | Containers | One foldable block of content, such as "No agent yet" or advanced options. For several of them stacked use `accordion`; for a titled sidebar group with a count and actions use `sidebar-section`; for a plain heading use `section`. |
| [`dashboard-card`](#dashboard-card) | Containers | Each block of a dashboard or overview (a chart, a list of things waiting, a table). For a titled box inside a page use `card`; for a sidebar panel use `ui.panel`; for a tiled pane with controls use `pane-frame`. |
| [`section`](#section) | Containers | A small muted heading over a group of content inside a panel or settings page. |
| [`swap-view`](#swap-view) | Containers | The body under a view switcher (`pill-tabs`, `segmented`, `tabs`) whose content is replaced, such as a list's header and rows per filter. Give `width` so the pages can be measured while they move. For panels that open and close use `side-panels`; for items joining a list give the rows a `key` and a transition instead. |
| [`browser`](#browser) | Content | A web page in a pane, with browser chrome. Keep the page's `navigate` messages in state and pass the latest as `page`; the address bar navigates on its own. For a bare page without a bar use `ui.browser`. |
| [`chat-markdown`](#chat-markdown) | Content | A chat answer in markdown, including one still streaming in (pass `cursor` while it grows) or citing its sources with `[label](cite:source)` chips. For a whole document, a note or a README use `markdown` (drawn by the host, with links the mod handles); for a file to edit use `markdown-editor`; for plain text use `ui.text`; for a file's source use `code-view`; for ordered steps alone use `numbered-list`. |
| [`image-viewer`](#image-viewer) | Content | Looking at a picture closely: a scan, a photo, a screenshot, a render, with tools drawn over it (a crop frame, picked spots). The m...
© moonframehq · MIT · moonframehq/moonframe