# ray-elements

> Web components (custom elements, Shadow DOM, no dependencies) for any web app: plain HTML, React, Vue or a raylang app. npm: `@raylang/elements`, `@raylang/react`, `@raylang/vue`; raylang: the `elements` package. This file describes version 0.9.0.

ray-elements is a design system of standard web components (custom elements
with Shadow DOM, no dependencies): `<ray-button>`, `<ray-input>`,
`<ray-dialog>`… They work in plain HTML, React, Vue, a browser or any webview,
and get extras in a raylang app (a native bridge to the program). The rules
below are what this library does differently from what you may assume; the
reference of every component follows them.

## Load it

```html
<link rel="stylesheet" href="node_modules/@raylang/elements/tokens.css">  <!-- required: the components read the tokens -->
<link rel="stylesheet" href="node_modules/@raylang/elements/base.css">    <!-- optional: font, colors and margins of the document -->
<script type="module">
  import "@raylang/elements";          // registers EVERY <ray-*> element and exports the whole API
</script>
```

- The bare name (`"@raylang/elements"`) resolves with a bundler (Vite,
  esbuild…) and in a raylang app (raylang serves the package with an import
  map). A plain page without either imports the files:
  `import { notify } from "./node_modules/@raylang/elements/index.js";`
  (everything), `./node_modules/@raylang/elements/components/<name>/<name>.js`
  (one component), `./node_modules/@raylang/elements/core.js` (the API), or
  declares an import map:
  `<script type="importmap">{ "imports": { "@raylang/elements": "./node_modules/@raylang/elements/index.js" } }</script>`.

- `npm install @raylang/elements` (React: also `@raylang/react`; Vue: also
  `@raylang/vue`). With a bundler: `import "@raylang/elements/tokens.css";`.
- Only some components: `import "@raylang/elements/button";` — one entry per
  component directory (the "Import" line of each component below). Each brings
  what it uses. `import { notify } from "@raylang/elements/notification";` gets
  a component's exports with it.
- The API without registering any element: `import { setTheme } from
  "@raylang/elements/core";`. Note that `import { RayButton } from
  "@raylang/elements"` loads everything (that entry registers every element).
- Avoid a flash of unstyled tags: `<style>:not(:defined) { visibility: hidden; }</style>`.

## Rules

- **Attributes are kebab-case, properties camelCase**: `full-width` /
  `fullWidth`. Boolean attributes are present or absent (`disabled`, never
  `disabled="false"`). Properties marked "property only" have no attribute:
  set them from JS (arrays, objects, functions). The exception is `checked`
  and `value` on form controls: their attribute is the initial state (see
  Forms).
- **Shared vocabulary**: `size` = `xs` | `sm` | `md` | `lg` | `xl` (default
  `sm`); `radius` = `xs`…`xl` | `full`; `color` = a palette color (`blue`,
  `red`, `teal`, `gray`…) or any CSS color, default the primary; `variant` per
  component (button: `filled`, `light`, `outline`, `subtle`, `default`,
  `transparent`, `gradient`, `raised`). Use only the values the reference lists.
- **Slots have exact names**: an icon in a button goes in `slot="left"` or
  `slot="right"` (not `start`/`end`, not `prefix`): `<ray-button><ray-icon
  slot="left" name="plus"></ray-icon>Add</ray-button>`. Content without a
  `slot` goes to the default slot. Check the slot list of the component.
- **Never hard-code colors, spacing, radii or shadows** in your own CSS: use
  the tokens (`var(--ray-background)`, `var(--ray-foreground)`,
  `var(--ray-border)`, `var(--ray-space-md)`, `var(--ray-radius-default)`,
  `var(--ray-shadow-sm)`). They follow light and dark themes; literal colors do
  not. Prefer the semantic tokens over the palette (`--ray-blue-6`).
- **Style components from outside** with `color`/`variant`/`size`/`radius`,
  the tokens (custom properties pierce the shadow root) and `::part()` (the
  parts each lists). Do not reach into their
  `shadowRoot` or depend on its markup.
- **Layout components exist**: `ray-stack` (vertical), `ray-group`
  (horizontal), `ray-grid`, `ray-container`, `ray-center`, `ray-card`
  (a heading of your own in its `header` slot), `ray-app-shell`. Their
  `gap`/`padding` take `xs`…`xl`.
- **Icons**: `<ray-icon name="settings"></ray-icon>`, from the registry (a
  small set, listed in the reference: there is no `save` or `trash`); decorative unless it has `label`. An icon-only button is
  `<ray-icon-button label="Settings"><ray-icon name="settings"></ray-icon></ray-icon-button>`
  (`label` is required: it is the accessible name). Add or replace icons with
  `setIcons({ inbox: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">…</svg>' })`
  (the style of the built-in set: 24×24, a 2px `currentColor` stroke) from
  your own code, never from user input. `filled` draws an icon's filled
  version for a state (`<ray-icon name="star" filled>` when it is a favorite);
  `"name:filled"` in `setIcons` adds one. An icon the set lacks (`trash`,
  `save`): register it from Lucide, the same grid and stroke —
  `import { Trash2 } from "lucide-static"; setIcons({ trash: Trash2 })` (or
  its SVG pasted in, without a bundler); never draw your own paths. To change
  one control's icon (only the chips' ×), register its role
  (`setIcons({ "ui.remove": … })`, roles listed in the reference). Under
  `dir="rtl"` the roles that point along the text (`ui.next`…) mirror by
  themselves; an icon of yours that points (back, send) takes `mirror`
  (`<ray-icon name="arrow-left" mirror>`).
- **Overlays are in the top layer**: `ray-dialog` is a native modal
  `<dialog>`; popovers, menus, tooltips and notifications are `[popover]`
  elements. Never fight them with `z-index` or `overflow`.

## An app's frame

```html
<ray-app-shell>
  <ray-app-bar slot="header" label="Files" description="No folder chosen">
    <ray-button slot="end" variant="default" size="xs">Commands</ray-button>
    <ray-theme-toggle slot="end"></ray-theme-toggle>
  </ray-app-bar>
  <ray-sidebar slot="navbar" label="Workspace">
    <ray-nav-link label="Files" href="#files" active><ray-icon slot="left" name="folder"></ray-icon></ray-nav-link>
    <ray-nav-link label="Settings" href="#settings"><ray-icon slot="left" name="settings"></ray-icon></ray-nav-link>
  </ray-sidebar>
  <main>…</main>
</ray-app-shell>
```

`ray-app-bar` is the header on the desktop too (its `label` is the title;
several elements may share the `end` slot). On narrow screens the sidebar
becomes a drawer and the shell switches to a phone layout by itself.

## Forms

- Inputs are **form-associated**: inside a `<form>` they submit under `name`,
  validate (`required`, `pattern`, `min`…), reset with it and follow a
  disabled `<fieldset>`. Read values with `new FormData(form)` or the
  element's `.value` / `.checked`.
- The `value` / `checked` **attributes are the initial value**; the
  properties hold the current one. Set `el.value = …` to change it.
- Fields take `label`, `description` and `error` (the error text also marks it
  invalid): do not wrap them in your own `<label>`.
- Enter in a `ray-input` submits its form, as in a native field; a submit
  button is `<ray-button type="submit">`.
- As with native controls: an invalid field (`required` and empty, a wrong
  `type="email"`…) blocks the submit and the browser shows its message; an
  unchecked `ray-checkbox`/`ray-switch` and a `ray-select` with nothing chosen
  are left out of `FormData` (a select's `placeholder` shows meanwhile).

## Events

- A value change is a plain `input` (while typing) and `change` event: read
  `event.target.value`.
- Everything else is a `ray-*` custom event (bubbles, composed) with its data
  in `event.detail`: `ray-select` on a menu (`detail.value`), `ray-close` on a
  dialog (`detail.returnValue`), `ray-request-close` (cancelable). The
  reference lists each component's events and their `detail`.

## Dialogs and notifications

```html
<ray-dialog id="d" label="Rename">
  <ray-input label="Name" name="name"></ray-input>
  <ray-button slot="footer" variant="default" data-dialog-close>Cancel</ray-button>
  <ray-button slot="footer" data-dialog-close="ok">Save</ray-button>
</ray-dialog>
```

`d.show()` or the `open` attribute opens it; any slotted element with
`data-dialog-close` closes it (its value becomes `returnValue`); the close
button, Escape and the backdrop close it with `returnValue` `""` (after a
cancelable `ray-request-close`).
`await confirmDialog({ label, message, confirmLabel, cancelLabel, color: "red" })`
asks a yes/no question (every option is optional: "Are you sure?",
"Confirm", "Cancel"); `notify({ title, message, color })` shows a
notification (`message` is plain text; a `color` adds a status icon:
green a check, red an error, yellow a warning, others info).

## Theme

- The theme follows the system. Force it on the page or any subtree with
  `data-theme="light"` | `"dark"`; change the primary color with
  `data-primary="violet"` (a palette color).
- From JS: `setTheme("light" | "dark" | "system")`, `setPrimary("violet")`,
  `definePrimary("#7c3aed")` (any brand color: builds the ten shades and
  checks contrast), `onThemeChange(cb)`. `<ray-theme-toggle>` is the switch.
- App-wide defaults for a component: `configure({ defaults: { "ray-button":
  { variant: "light" } } })`.

## Right to left

- `dir="rtl"` on `<html>` (with its `lang`) or a subtree mirrors the
  components: layout, the icons that point along the text, arrow keys
  (ArrowLeft is forward), sliders, carousels, splits and floating panels
  (`bottom-start` lines up with the right edge). Nothing to configure.
- For a side, write `start`/`end` (they follow the direction):
  `label-position="start"`, `<ray-drawer position="start">`,
  `<ray-sidebar side="end">`, `<ray-toaster position="top-start">`.
  `left`/`right` are sides of the screen whatever the direction; use them
  only when the side is meant (a map's legend).
- Your own CSS: logical properties (`margin-inline-start`, `inset-inline-end`,
  `text-align: start`), never `left`/`right`; an icon of yours that points
  (back, send) takes `mirror`.

## React and Vue

```tsx
import "@raylang/elements/tokens.css";
import { RayInput, RayMenu, RayMenuItem, RayButton } from "@raylang/react";

<RayInput label="Name" value={name} onInput={(e) => setName(e.currentTarget.value)} />
<RayMenu onRaySelect={(e) => run(e.detail.value)}>
  <RayButton slot="trigger">Actions</RayButton>
  <RayMenuItem value="rename">Rename</RayMenuItem>
</RayMenu>
```

```vue
<!-- main.ts: import RayElements from "@raylang/vue"; app.use(RayElements) -->
<RayInput v-model="name" label="Name" required />
<RayDialog v-model="open" label="Confirm" @ray-close="onClose">…</RayDialog>
```

- The wrapper of `<ray-tag-name>` is `RayTagName`. React events are `on` +
  PascalCase of the event (`onRaySelect`, `onChange`); props are set as DOM
  properties. Vue has `v-model` where the reference lists a model (`value`,
  `checked` or `open`).
- A wrapper registers only its own element: a plain `<ray-*>` tag in JSX
  needs its import (`import "@raylang/elements/badge"`).

## In a raylang app

`ray add elements` brings the raylang package `elements`: it serves
`@raylang/elements` to the app's pages by its npm name, with no npm and no
build step. The page:

```html
<link rel="stylesheet" href="/node_modules/@raylang/elements/tokens.css">
<script type="module">
  import { enableRaylang } from "@raylang/elements";
  const host = await enableRaylang();   // the native host, or null in a browser
</script>
```

The program serves the page and answers the bridge before its own events:

```ray
import std/ui;
import elements/bridge;

fn main() -> int {
    match (run()) {
        Result.Ok(code) => code,
        Result.Err(e) => {
            eprint(e);
            1
        },
    }
}

fn run() -> Result<int, string> {
    ui.mount_embed_at("", "assets")?;   // the page: assets/index.html, ray.toml [native] embed = ["assets"]
    ui.open_with("App", "ray://app/index.html", ui.options(800, 600))?;
    while (true) {
        let e = ui.next_event()?;
        if (bridge.handle(e)) {
            continue;   // a ray-elements request, already answered
        }
        if (e.kind == "closed") {
            return Result.Ok(0);
        }
        // the app's own events: e.kind == "message" (window.ray.send), e.tag…
    }
}
```

With the bridge: `<ray-file-upload native>` and `<ray-path-input>` use the
system file dialogs and give real paths, `confirmDialog()` asks with the
system dialog, `<ray-menu native>` opens a native context menu (fill
items that depend on the click in its `ray-request-open`, not in your own
`contextmenu` listener),
`<ray-command-palette native-menus>` runs the app's menu bar
(`bridge.menu`, `bridge.route`), `ray-app-shell` becomes the title bar of a
`full_content` window, and `trackEdits(form)` shows the unsaved mark. The
components that use it have an "In a raylang app" section. Without the
bridge every component keeps its web behavior.

## Check your markup

The package checks markup against this version:
`npx ray-elements check src/` (with npm), or
`node node_modules/@raylang/elements/check/cli.js check assets/` (a raylang
app). It reports unknown elements, attributes, slots and `ray-*` events,
invalid values, unregistered icons and literal colors, with the line and a
suggestion, and exits with 1 on an error. Run it after writing a page and fix
what it reports; `--format json` gives the diagnostics as JSON.

## Your own components

Extend `RayElement`, `FormControl`, `FieldControl` or `Floating` (or any
component class) from `@raylang/elements/core`; see the Extending guide.
Members whose name starts with `_` are internal.

## Components

### Base classes

Properties the components inherit from the base classes (each component lists which it extends):

FieldControl (extends FormControl):

- `name`: string. Form field name.
- `label`: string. Visible label (also the accessible name).
- `description`: string. Help text.
- `error`: string. Error text; marks the field invalid.
- `required`: boolean, reflects. Required for form submission.
- `disabled`: boolean, reflects. Not interactive nor submitted.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`, reflects. Corner radius.
- `variant`: `default` | `filled` | `unstyled`, default `default`, reflects. Box style.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. Description before or after the control.

Floating (extends RayElement):

- `open`: boolean, reflects. Shown.
- `placement`: string, default `bottom`, reflects. Preferred side and alignment.
- `offset`: number, default `8`. Gap to the anchor in px.

### Button

A button, or a link styled as one with href. Submits or resets its form with type.

Import: `import "@raylang/elements/button";` · Category: Buttons

#### `<ray-button>` (RayButton, extends RayElement)

Properties:

- `variant`: `filled` | `light` | `outline` | `subtle` | `default` | `transparent` | `gradient` | `raised`, default `filled`, reflects. Visual style. raised: a physical key on a darker edge that sinks when pressed (mouse, touch or keyboard).
- `gradient`: string, reflects. With variant=gradient: "from to [deg]", palette colors or CSS colors ("teal blue 90"). Default: the --ray-gradient-* tokens.
- `color`: string. A palette color (blue, red…) or any CSS color. Default: the primary color.
- `size`: `"xs" | "sm" | "md" | "lg" | "xl" | (string & {})`, default `sm`, reflects. Height, padding and font size: xs…xl or any CSS length (the padding and the font follow).
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius. Default: --ray-radius-default.
- `type`: `button` | `submit` | `reset`, default `button`. submit/reset act on the enclosing form.
- `disabled`: boolean. Not interactive (also when inside a disabled fieldset).
- `loading`: boolean. Shows a spinner over the content and blocks clicks.
- `fullWidth` (attribute `full-width`): boolean. Takes the whole width of its container.
- `href`: string. Renders a link instead of a button.
- `target`: string. Link target, with href.
- `name`: string. With type=submit: submitted as name=value.
- `value`: string. With type=submit: the submitted value.

Slots:

- (default): The label.
- `left`: Icon or content before the label.
- `right`: Icon or content after the label.

Parts (`::part()`):

- `button`: The inner <button> or <a>.
- `label`: The label wrapper.

Methods and properties:

- `readonly form: HTMLFormElement | null`: The form a submit/reset button acts on.

### Button group

Buttons joined into one control: inner corners squared, borders overlapped. Works with ray-button, ray-icon-button, menus with a button trigger and fields (ray-input, ray-select, ray-search).

Import: `import "@raylang/elements/button-group";` · Category: Buttons

#### `<ray-button-group>` (RayButtonGroup, extends RayElement)

role=group; give it a label. The corners come from the --ray-group-radius-* custom properties, which your own components can read too.

Properties:

- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. Direction of the group.
- `fullWidth` (attribute `full-width`): boolean, reflects. Fills its container; the children share the width.
- `label`: string. Accessible name (aria-label).

Slots:

- (default): The buttons, fields or menus to join.

### Icon button

A square button for an icon (Mantine's ActionIcon). Always give it a label.

Import: `import "@raylang/elements/icon-button";` · Category: Buttons

#### `<ray-icon-button>` (RayIconButton, extends RayButton)

Same properties as ray-button; variant defaults to subtle.

Properties:

- `label`: string, reflects. Accessible name and tooltip (required: the button has no text).
- `variant`: `filled` | `light` | `outline` | `subtle` | `default` | `transparent` | `gradient` | `raised`, default `subtle`, reflects. Visual style.
- `gradient`: string, reflects. With variant=gradient: "from to [deg]", palette colors or CSS colors ("teal blue 90"). Default: the --ray-gradient-* tokens.
- `color`: string. A palette color or any CSS color.
- `size`: `"xs" | "sm" | "md" | "lg" | "xl" | (string & {})`, default `sm`, reflects. Width and height: xs…xl or any CSS length ("5.5rem": a big main action, round with radius=full); the icon scales with it.
- `disabled`: boolean. Not interactive.
- `loading`: boolean. Shows a spinner instead of the icon.

Also the properties of RayButton (`<ray-button>`): `radius`, `type`, `fullWidth`, `href`, `target`, `name`, `value`.

Slots:

- (default): The icon (an inline <svg> is sized to the button).

Parts (`::part()`):

- `button`: The inner button.

### Toggle

A two-state button (aria-pressed): bold in a toolbar, mute, favorite. The variant is how "on" looks; "off" is always neutral, so the states differ by more than color. Has everything ray-button has and joins a ray-button-group.

Import: `import "@raylang/elements/toggle";` · Category: Buttons

#### `<ray-toggle>` (RayToggle, extends RayButton)

Click, Enter or Space flips pressed and fires change. In a form it is submitted like a checkbox: value (default "on") under name while pressed; reset restores the initial pressed attribute.

Properties:

- `pressed`: boolean, reflects. On.
- `variant`: `subtle` | `outline` | `light` | `filled` | `raised`, default `subtle`, reflects. Look of "on": subtle (tint), outline (colored border + tint), light (muted → tint), filled (surface → solid color), raised (a key that latches down, lit). ray-button's default, transparent and gradient are left out: no distinct on state, or only a color change.
- `square`: boolean, reflects. Square, for an icon alone (give it a label).
- `label`: string, reflects. Accessible name and tooltip, for icon-only toggles.

Also the properties of RayButton (`<ray-button>`): `gradient`, `color`, `size`, `radius`, `type`, `disabled`, `loading`, `fullWidth`, `href`, `target`, `name`, `value`.

Events:

- `change`: The user flipped it (read `pressed`).

Slots:

- (default): Text or an icon.

### Toggle group

ray-toggle elements with one shared value: type="single" (at most one on: alignment, view mode) or "multiple" (bold / italic / underline). Joined like a button group, or spaced; arrow keys move between toggles; submitted with its form.

Import: `import "@raylang/elements/toggle-group";` · Category: Buttons

#### `<ray-toggle-group>` (RayToggleGroup, extends RayButtonGroup)

Each toggle's value (else its text) is its key. variant, color, size, radius and square reach the toggles that do not set their own. One tab stop (the selected toggle); arrows, Home and End move; Space/Enter flips.

Properties:

- `type`: `single` | `multiple`, default `single`, reflects. single: choosing one turns the others off; multiple: each toggle is independent.
- `value`: `string | string[] | undefined`. The selected key (single) or keys (multiple: an array, or a comma-separated attribute).
- `name`: string, reflects. Form field name: the value (multiple: one entry per key).
- `required`: boolean, reflects. Needs a value; with single the selected toggle cannot be turned off.
- `disabled`: boolean, reflects. Disables every toggle.
- `spaced`: boolean, reflects. Toggles apart, each with its own corners (default: joined).
- `variant`: `subtle` | `outline` | `light` | `filled` | `raised`, reflects. Variant of the toggles.
- `color`: string, reflects. Color of the toggles' on state.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, reflects. Size of the toggles.
- `radius`: string, reflects. Corner radius of the toggles.
- `square`: boolean, reflects. Square toggles, for icons.

Also the properties of RayButtonGroup (`<ray-button-group>`): `orientation`, `fullWidth`, `label`.

Events:

- `change`: The user changed the selection (read `value` or `values`; the toggles' own change events stop at the group).

Slots:

- (default): ray-toggle elements.

Methods and properties:

- `values: string[]`: The selected keys as a list, in any mode.
- `readonly toggles: RayToggle[]`: The toggles of this group.

### Checkbox

A checkbox with label, description and error. Submits value when checked.

Import: `import "@raylang/elements/checkbox";` · Category: Inputs

#### `<ray-checkbox>` (RayCheckbox, extends FieldControl)

Properties:

- `checked` (attribute `checked`: the initial value only): boolean. Current state. The checked attribute is the initial state (restored on reset).
- `indeterminate`: boolean, reflects. Mixed state; cleared on the next user change.
- `value`: string, default `on`, reflects. Submitted value when checked.
- `name`: string. Form field name.
- `label`: string. Label text (or put the label in the content).
- `description`: string. Help text.
- `error`: string. Error text.
- `required`: boolean. Must be checked to submit.
- `disabled`: boolean. Not interactive nor submitted.
- `variant`: `filled` | `outline`, default `filled`, reflects. Checked look: filled box, or colored border and mark.
- `color`: string. A palette color or any CSS color for the checked state.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Box and font size.
- `labelPosition` (attribute `label-position`): `end` | `start` | `right` | `left`, default `end`, reflects. Side of the label: start/end follow the writing direction; left/right are sides of the screen.

Also the properties of FieldControl: `radius`, `descriptionPosition`.

Events:

- `change`: When the user toggles it.

Slots:

- (default): Label content.

Parts (`::part()`):

- `input`: The native checkbox (transparent, on top of the indicator).
- `indicator`: The drawn box.
- `label`: The label.

Vue `v-model`: `checked` (updated on change).

### Checkbox group

Several choices among options (Mantine's Checkbox.Group): a label, description and error around ray-checkbox elements; the value is the array of the checked ones. max caps how many; required asks for one.

Import: `import "@raylang/elements/checkbox-group";` · Category: Inputs

#### `<ray-checkbox-group>` (RayCheckboxGroup, extends FormControl)

The group is the form control: one entry per checked value under name (like checkboxes sharing a name); the checkboxes inside lose their own name. It stops their change events and fires its own. role="group" named by its label.

Properties:

- `value` (attribute `value`: the initial value only): `string[]`. The checked values. The value attribute: "a,b".
- `name`: string, reflects. Form field name.
- `label`: string. Group label (also its accessible name).
- `description`: string. Help text.
- `error`: string. Error text.
- `required`: boolean, reflects. At least one must be checked.
- `disabled`: boolean, reflects. Disables every checkbox.
- `max`: number. At most this many: the others are disabled once reached; the label shows the count.
- `orientation`: `vertical` | `horizontal`, default `vertical`, reflects. Layout of the checkboxes.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, reflects. Size of the checkboxes that set none.
- `color`: string, reflects. Color of the checkboxes that set none.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the checkboxes or after them.

Events:

- `change`: The user checked or unchecked one (read value).
- `input`: Same moment as change.

Slots:

- (default): ray-checkbox elements (also nested in other markup).

Methods and properties:

- `readonly checkboxes: HTMLElement[]`: The checkboxes of this group.

Vue `v-model`: `value` (updated on change).

### Color picker

Pick a color: an inline picker (saturation area, hue, opacity, swatches) and a text field with the picker in a dropdown and an eyedropper. Pointer and keyboard; form-associated; hex, rgb or hsl, with or without alpha.

Import: `import "@raylang/elements/color-picker";` · Category: Inputs

#### `<ray-color-picker>` (RayColorPicker, extends FormControl)

Keyboard: arrows move the area's thumb (saturation, brightness) or a slider's; Shift for 10× steps; Home/End on the sliders. The alpha slider shows when format has alpha.

Properties:

- `value`: string. The color, written in format. Any color is accepted and rewritten in format. The value attribute is the initial value (restored on form reset).
- `format`: `ColorFormat`, default `hex`, reflects. How value is written: hex, hexa, rgb, rgba, hsl or hsla. Formats ending in a show the opacity slider.
- `swatches`: `string | string[]`. Preset colors below the picker: an array, or a comma-separated list in the attribute (commas inside rgb()/hsl() are kept).
- `swatchesPerRow` (attribute `swatches-per-row`): number, default `7`. Swatches in each row.
- `swatchesOnly` (attribute `swatches-only`): boolean, reflects. Only the swatches: no area nor sliders.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `md`, reflects. Width of the picker and size of its thumbs.
- `fullWidth` (attribute `full-width`): boolean, reflects. Takes the width of its container.
- `name`: string, reflects. Form field name.
- `disabled`: boolean, reflects. Not interactive.
- `label`: string. Accessible name of the whole picker.

Events:

- `input`: The color moved (every step of a drag).
- `change`: The color settled: pointer released, a key pressed or a swatch chosen (read value).

Parts (`::part()`):

- `saturation`: The saturation/brightness area.
- `hue`: The hue slider.
- `alpha`: The opacity slider.
- `preview`: The current color.
- `swatches`: The swatches' grid.

Methods and properties:

- `readonly rgba: Rgba`: The current color as channels and alpha (0…1).

Vue `v-model`: `value` (updated on input).

#### `<ray-color-input>` (RayColorInput, extends FieldControl)

Type any CSS color (it becomes the value as soon as it is valid; invalid text goes back to the value on blur), or open the picker with a click or ArrowDown. The eyedropper shows only where the browser has the EyeDropper API.

Properties:

- `value`: string. The color, written in format. The value attribute is the initial value (restored on form reset).
- `format`: `ColorFormat`, default `hex`, reflects. How value is written: hex, hexa, rgb, rgba, hsl or hsla.
- `swatches`: `string | string[]`. Preset colors in the dropdown (an array, or a comma-separated list).
- `swatchesPerRow` (attribute `swatches-per-row`): number, default `7`. Swatches in each row.
- `placeholder`: string. Shown while empty.
- `hideEyedropper` (attribute `hide-eyedropper`): boolean, reflects. Hides the eyedropper button.
- `open`: boolean, reflects. The dropdown is shown.
- `name`: string, reflects. Form field name.
- `label`: string. Label above the field.
- `description`: string. Help text.
- `error`: string. Error message; marks the field invalid.
- `required`: boolean, reflects. Must have a color.
- `disabled`: boolean, reflects. Not interactive.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Field height and font size.
- `radius`: string, reflects. Corner radius: xs…xl or a CSS length.
- `variant`: `default` | `filled` | `unstyled`, default `default`, reflects. Visual style of the field.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. Where the description goes.

Events:

- `input`: The color changed (typing a valid color, or moving the picker).
- `change`: The color settled (picker released, a swatch, the eyedropper, or the field left with a new color).
- `ray-open`: The dropdown opened.
- `ray-close`: The dropdown closed.

Parts (`::part()`):

- `input`: The text field.
- `preview`: The swatch of the current color.
- `eyedropper`: The eyedropper button.
- `dropdown`: The dropdown with the picker.

Methods and properties:

- `readonly picker: RayColorPicker`: The ray-color-picker in the dropdown.
- `toggle(force?: boolean): void`: Opens or closes the dropdown.

Vue `v-model`: `value` (updated on input).

Exports (from `@raylang/elements/color-picker` and `@raylang/elements`):

- `function parseColorValue(input: string | null | undefined): Rgba | null`: A color string (hex with 3/4/6/8 digits, rgb(a), hsl(a), or any CSS color) as channels and alpha, or null.
- `function formatColor(color: Rgba, format?: ColorFormat): string`: Channels and alpha as a string in a format (default hex).

Types:

- `"hex" | "hexa" | "rgb" | "rgba" | "hsl" | "hsla"`: How a color value is written.
- `{ r: number; g: number; b: number; a: number }`: sRGB channels and alpha, all 0…1.

### Combobox (also Multi select)

A select you can type in, an autocomplete (Mantine's searchable Select, MultiSelect and TagsInput): typing filters the options; multiple keeps chips; creatable adds new values; clearable, max-values, groups, a result limit.

Import: `import "@raylang/elements/combobox";` · Category: Inputs

#### `<ray-combobox>` (RayCombobox, extends FieldControl)

The WAI-ARIA combobox pattern (a text field with a listbox popup; the active option is aria-activedescendant). Arrows move, Enter picks, Escape closes (then clears with clearable), Backspace in an empty field removes the last chip. The form gets one entry per value.

Properties:

- `value` (attribute `value`: the initial value only): `string | string[]`. The chosen value; an array with multiple. The value attribute: "a,b" with multiple.
- `data` (property only): `Array<string | { value: string; label?: string; disabled?: boolean; group?: string }>`. Options instead of child <option>/<optgroup> elements.
- `multiple`: boolean, reflects. Several values, shown as chips.
- `placeholder`: string. Shown while empty.
- `creatable`: boolean. What was typed can be added when no option matches it ("+ Create …"); fires ray-create.
- `clearable`: boolean. A button that clears the value.
- `maxValues` (attribute `max-values`): number. With multiple: at most this many.
- `limit`: number. At most this many options shown (large lists: keep typing).
- `nothingFound` (attribute `nothing-found`): string, default `No matches`. Shown when nothing matches.
- `open`: boolean, reflects. The dropdown is shown.

Also the properties of FieldControl: `name`, `label`, `description`, `error`, `required`, `disabled`, `size`, `radius`, `variant`, `descriptionPosition`.

Events:

- `change`: The value changed (read value).
- `input`: Same moment as change.
- `ray-create` (detail `{ value: string }`): A new value was created from the typed text.
- `ray-open`: The dropdown opened.
- `ray-close`: The dropdown closed.

Slots:

- (default): <option> and <optgroup> elements.

Parts (`::part()`):

- `input`: The text field.
- `chips`: The chips container.
- `chip`: A chip.
- `clear`: The clear button.
- `dropdown`: The listbox.
- `option`: An option.

Methods and properties:

- `readonly values: string[]`: The value as an array (with or without multiple).
- `toggle(force?: boolean): void`: Opens or closes the dropdown.

Vue `v-model`: `value` (updated on change).

### Date picker

A date field with a calendar dropdown, and the calendar on its own. Keyboard grid navigation, min/max, locale-aware. Form-associated.

Import: `import "@raylang/elements/date-picker";` · Category: Inputs

#### `<ray-date-picker>` (RayDatePicker, extends FieldControl)

Values are ISO dates ("2026-10-06"), submitted as such. ArrowDown on the field opens the calendar; Escape closes it.

Properties:

- `value`: string. The chosen date, ISO "YYYY-MM-DD" ("" for none). The value attribute is the initial value (restored on form reset).
- `min`: string. Earliest selectable date (ISO). Earlier days are disabled; an earlier value is invalid (rangeUnderflow).
- `max`: string. Latest selectable date (ISO).
- `placeholder`: string, default `Pick a date`. Shown while no date is chosen.
- `format`: `short` | `medium` | `long` | `full`, default `medium`. How the date is displayed (Intl dateStyle).
- `locale`: string. Locale for names and formats. Default: the nearest lang attribute, else the browser's.
- `firstDay` (attribute `first-day`): number. First day of the week, 0 (Sunday) to 6. Default: the locale's.
- `clearable`: boolean, reflects. Shows a button that clears the date.
- `open`: boolean, reflects. The calendar dropdown is shown.
- `name`: string, reflects. Form field name.
- `label`: string. Visible label (also the accessible name).
- `description`: string. Help text.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the control (help first) or after it, with the error (fields in a row stay aligned).
- `error`: string. Error text.
- `required`: boolean. Required for form submission.
- `disabled`: boolean. Not interactive nor submitted.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height and font size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius.
- `variant`: `default` | `filled` | `unstyled`, default `default`, reflects. Box style.

Events:

- `input`: When the date changes (picked or cleared).
- `change`: When the date changes (picked or cleared).
- `ray-open`: The calendar opened.
- `ray-close`: The calendar closed.

Parts (`::part()`):

- `trigger`: The button showing the date.
- `clear`: The clear button.
- `dropdown`: The calendar panel (a popover in the top layer).
- `calendar`: The <ray-calendar> in the dropdown (its day, caption, nav and grid parts are exported).
- `input`: The hidden native <input type=date> that holds the value (the model).
- `wrapper`: The box.

Methods and properties:

- `toggle(force?: boolean): void`: Opens or closes the calendar.
- `readonly displayValue: string`: The chosen date as displayed ("" when none).

Vue `v-model`: `value` (updated on change).

#### `<ray-calendar>` (RayCalendar, extends RayElement)

WAI-ARIA grid: arrows move by day and week, Home/End to the week's ends, PageUp/PageDown by month (with Shift, by year), Enter/Space select.

Properties:

- `value`: string. The selected date, ISO "YYYY-MM-DD".
- `min`: string. Earliest selectable date (ISO).
- `max`: string. Latest selectable date (ISO).
- `locale`: string. Locale for month and weekday names. Default: the nearest lang attribute, else the browser's.
- `firstDay` (attribute `first-day`): number. First day of the week, 0 (Sunday) to 6. Default: the locale's.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Day cell size and font size.

Events:

- `change`: A day was selected (read `value`).

Parts (`::part()`):

- `header`: The row with the month and the navigation buttons.
- `caption`: The month and year.
- `nav`: The previous/next month buttons.
- `grid`: The day grid (role=grid).
- `day`: Each day button ([aria-selected], [aria-current=date], [aria-disabled], [data-outside]).

Methods and properties:

- `focusDay(): void`: Focuses the day the keyboard is on (the selected day, else today).
- `readonly focusedDate: string`: The day the keyboard is on (ISO).

Vue `v-model`: `value` (updated on change).

### File upload

A drop zone to pick files: drag, click, keyboard or paste. Checks type, size and count as files arrive, lists them as ray-attachment rows (thumbnails, remove) and submits them with its form.

Import: `import "@raylang/elements/file-upload";` · Category: Inputs

#### `<ray-file-upload>` (RayFileUpload, extends FormControl)

A drag that can only be refused turns the zone red before the drop; refused files fire ray-reject and are explained under the zone. Without multiple a new file replaces the current one. Uploading is the app's: attachmentFor(file) gives the row whose progress/status/error to set.

Properties:

- `name`: string, reflects. Form field name: every file is submitted under it.
- `label`: string. Label above the zone.
- `description`: string. Help text under the label.
- `error`: string. Error text (replaces the explanation of refused files).
- `required`: boolean, reflects. The form needs at least one file.
- `disabled`: boolean, reflects. No picking, dropping or removing.
- `accept`: string, reflects. Accepted types, as in <input type=file>: ".pdf,.png", "image/*", "application/json".
- `multiple`: boolean, reflects. Several files (else one, replaced by the next).
- `maxSize` (attribute `max-size`): `string | number`. Largest file: bytes or a size like "10 MB", "512 KB".
- `maxFiles` (attribute `max-files`): number. With multiple: the most files kept.
- `hint`: string. Small text in the zone. Default: from accept, max-size and max-files ("PNG or PDF · up to 10 MB each · max. 5 files").
- `dropLabel` (attribute `drop-label`): string, default `Drag files here`. Title of the zone, before "or browse".
- `browseLabel` (attribute `browse-label`): string, default `browse`. The link-styled word (the button text in compact).
- `activeLabel` (attribute `active-label`): string, default `Drop to add files`. Title while files are dragged over it.
- `tapLabel` (attribute `tap-label`): string, default `Choose files`. Title on touch screens (no hover), where dragging files is rare.
- `variant`: `default` | `compact`, default `default`, reflects. default: a tall centered zone; compact: one row with a Browse button.
- `list`: `rows` | `cards` | `none`, default `rows`, reflects. How chosen files show: full-width rows, thumbnail cards, or not at all (render your own on change).
- `native`: boolean, reflects. With a native host (ray-elements/core/raylang.js in a std/ui window), browsing opens the system dialog and gives paths (see `paths`); drop and paste still give Files.
- `color`: string, reflects. Accent of hover, drag and the browse link (default: primary).

Events:

- `change`: Files were added or removed (read `files`, and `lastChange` for which).
- `ray-reject` (detail `{ rejected: FileRejection[] }`): Some files were refused (type, size or count).
- `ray-error` (detail `{ error: Error }`): The native dialog failed (with `native`).

Slots:

- `icon`: Replaces the upload icon.

Parts (`::part()`):

- `dropzone`: The zone (a button).
- `icon`: The icon tile.
- `hint`: The small text in the zone.
- `files`: The list of chosen files.
- `label`: The label.
- `error`: The error text.

Methods and properties:

- `files: (File | HostFile)[]`: The chosen files (assign to replace them, without events).
- `readonly paths: string[]`: The paths of the files chosen with the native dialog (`native`), in order; they are also what the form submits for them.
- `readonly lastChange: FileUploadChange | null`: What the last change event changed: the files added and removed. null before the first one, and after assigning files.
- `open(): void`: Opens the system file picker.
- `addFiles(files: Iterable<File>): { accepted: File[]; rejected: FileRejection[] }`: Adds files as if dropped (checks them, fires the events).
- `removeFile(file: File): boolean`: Removes a file (fires change).
- `clear(): void`: Removes every file (fires change).
- `attachmentFor(file: File): RayAttachment | null`: The row of a file, to show its upload progress, status or error.

Exports (from `@raylang/elements/file-upload` and `@raylang/elements`):

- `function parseSize(value: string | number | null | undefined): number`: Bytes from a number or a size like "10 MB" (NaN if neither).
- `function matchesAccept(file: { name: string; type: string }, accept: string | null | undefined): boolean`: Whether a file passes an accept list.
- `function describeAccept(accept: string | null | undefined): string`: A short human list of an accept value ("PNG, JPG or PDF").

Types:

- `{ added: (File | HostFile)[]; removed: (File | HostFile)[] }`: The files a change added and removed.
- `{ file: File; reason: "type" | "size" | "count"; message: string }`: A refused file and why.

#### In a raylang app

In a `std/ui` window with [the native bridge](https://elements.raylang.dev/raylang.html#using-the-bridge), `native` makes browsing open the system's file dialog, with the `accept` types as its filter. The files it gives are paths on the user's disk, not bytes: they list like any other file (name, size, type) and the program reads them.

```html
<form id="import">
  <ray-file-upload name="photos" native multiple accept="image/*" label="Photos"></ray-file-upload>
</form>
```

```js
upload.addEventListener("change", () => {
  window.ray.send("import:" + JSON.stringify(upload.paths));   // ["/Users/ada/Pictures/a.jpg", …]
});
```

The form submits those paths under `name`. Dropped and pasted files are still `File` objects (`upload.files` holds both; a chosen one is a `HostFile` with a `path`). Without the bridge, or in a browser, `native` changes nothing.

### Input

A text field with label, description and error (Mantine's TextInput). Form-associated.

Import: `import "@raylang/elements/input";` · Category: Inputs

#### `<ray-input>` (RayInput, extends FieldControl)

Also forwards placeholder, autocomplete, inputmode, pattern, min, max, step, minlength, maxlength, spellcheck, autocapitalize, enterkeyhint and list to the inner input. Enter submits its form as a native field does: through the first submit button (ray-button type="submit" included; nothing when it is disabled), or, without one, only when the form has a single text field.

Properties:

- `value`: string. Current value. The value attribute is the initial value (restored on form reset).
- `type`: `text` | `email` | `password` | `search` | `number` | `url` | `tel`, default `text`, reflects. Input type.
- `name`: string, reflects. Form field name.
- `label`: string. Visible label (also the accessible name).
- `description`: string. Help text under the label.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the control (help first) or after it, with the error (fields in a row stay aligned).
- `error`: string. Error text; marks the field invalid (display only — does not block submit).
- `placeholder`: string. Placeholder text.
- `required`: boolean. Required for form submission; shows an asterisk.
- `disabled`: boolean. Not editable nor submitted.
- `readonly`: boolean. Not editable, still submitted.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height and font size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius.
- `variant`: `default` | `filled` | `unstyled`, default `default`, reflects. Box style.
- `highlight` (property only): `((text: string) => HighlightRange[]) | null`. Marks ranges of the text, painted behind it: called with the text on every change (typed or set), it returns { start, end, kind?, title? } offsets. kind "error" is red with a wavy underline; any other kind is styled with ::part(highlight-<kind>); title is the tooltip over the range. Ranges must not overlap.
- `complete` (property only): `((text: string, caret: number) => CompletionResult | null | Promise<CompletionResult | null>) | null`. Inline suggestions: called as the user types (and on Ctrl+Space) with the text and the caret, it returns the part of the text a suggestion would replace and the suggestions ({ from, to, items }), or null for none. A list opens under that part (ArrowUp/Down, Enter or Tab to accept, Escape to close); the chosen item's value replaces from–to as an undoable edit, then ray-complete fires. The field becomes a combobox (aria-autocomplete, aria-expanded, aria-activedescendant).
- `suggestionsLabel` (attribute `suggestions-label`): string, default `Suggestions`. Accessible name of the suggestion list.

Attributes (forwarded to the inner element):

- `autocomplete`: Forwarded to the inner input.
- `inputmode`: Virtual keyboard hint.
- `pattern`: Validation pattern (regular expression).
- `min`: Minimum (number/date types).
- `max`: Maximum (number/date types).
- `step`: Step (number types).
- `minlength`: Minimum length.
- `maxlength`: Maximum length.
- `autocapitalize`: Mobile auto-capitalization.
- `enterkeyhint`: Label of the Enter key on virtual keyboards.
- `list`: Id of a <datalist> with suggestions.

Events:

- `ray-complete` (detail `{ item: CompletionItem; from: number; to: number }`): A suggestion was accepted (the text already has it).
- `input`: On every edit (value already updated).
- `change`: When an edit is committed (blur, Enter).

Slots:

- `left`: Section before the text (icon).
- `right`: Section after the text (icon, button).

Parts (`::part()`):

- `input`: The inner <input>.
- `wrapper`: The box around the input and sections.
- `label`: The label.
- `description`: The description.
- `error`: The error message.
- `suggestions`: The suggestion list (a listbox in the top layer).
- `suggestion`: Each suggestion ([aria-selected] when active).
- `highlight`: Each marked range (also highlight-<kind> for a range with a kind).
- `text-layer`: The layer behind the text that holds the marks.

Methods and properties:

- `select(): void`: Selects the text.
- `refreshHighlight(): void`: Runs highlight again, when what it marks changed but the text did not.

Vue `v-model`: `value` (updated on input).

Types:

- `{ start: number; end: number; kind?: string; title?: string }`: A range of a field's text to mark (ray-input and ray-textarea highlight): offsets into the text, end excluded.
- `{ value: string; label?: string; detail?: string; description?: string }`: A suggestion of a field's complete(): value is inserted; label (default: value) and detail are shown, description under them.
- `{ from: number; to: number; items: CompletionItem[] }`: What complete() returns: the part of the text (offsets, to excluded) a suggestion replaces, and the suggestions.

### Mode input

A text field with a menu of modes on one side: choosing a mode applies its attributes to the field (type, placeholder, inputmode, pattern…), so one control says what a value is and the value — a file path or text, an amount in € or $, a search by name or ID. Everything else is ray-input.

Import: `import "@raylang/elements/mode-input";` · Category: Inputs

#### `<ray-mode-input>` (RayModeInput, extends RayInput)

Declare the modes as <option> children (label, data-icon, data-hint, data-description, disabled, and data-set-<attribute> for each attribute the mode sets on the field) or with the options property. A mode's attributes replace the field's own while it is chosen and give them back after. The menu is a ray-menu of radio items in the field's shadow root; Alt+ArrowDown opens it from the field, and the trigger keeps the caret in the field.

Properties:

- `mode`: string, reflects. The chosen mode's value (default: the first). Setting it applies that mode without ray-mode-change.
- `options` (property only): `ModeOption[]`. The modes; when not set, the <option> children.
- `display`: `label` | `icon` | `both`, reflects. What the trigger shows: the mode's hint or label, its icon, or both. Default: the icon when the mode has one, else the label.
- `position`: `start` | `end`, default `start`, reflects. The side of the field the trigger sits on.
- `menuLabel` (attribute `menu-label`): string, default `Mode`. The trigger's accessible name, read with the current mode ("Mode: File").
- `nativeMenu` (attribute `native-menu`): boolean, reflects. With a native host (a std/ui window with the bridge), the system's menu (no descriptions there).

Also the properties of RayInput (`<ray-input>`): `value`, `type`, `name`, `label`, `description`, `descriptionPosition`, `error`, `placeholder`, `required`, `disabled`, `readonly`, `size`, `radius`, `variant`, `highlight`, `complete`, `suggestionsLabel`.

Events:

- `ray-mode-change` (detail `{ mode: string; previous: string | null; option: ModeOption }`): The user chose a mode (mode is already the new one); cancelable: preventDefault keeps the previous mode.

Parts (`::part()`):

- `trigger`: The button that opens the menu.
- `trigger-icon`: The current mode's icon in the trigger.
- `trigger-label`: The current mode's hint or label in the trigger.
- `menu`: The ray-menu of modes.

Methods and properties:

- `readonly modes: ModeOption[]`: The modes in use.
- `readonly currentOption: ModeOption | null`: The chosen mode.
- `choose(value: string): void`: Chooses a mode as the user would (fires ray-mode-change).

Types:

- `{ value: string; label: string; icon?: string; hint?: string; description?: string; disabled?: boolean; attrs?: Record<string, string> }`: A mode of ray-mode-input: hint is the trigger's short text ("€"), attrs the attributes it sets on the field.

### Number input

A number field (Mantine's NumberInput): + and − buttons (hold to repeat), arrow keys, min, max and step, fixed decimals, a prefix and a suffix, a thousands separator, or a duration (m:ss). An ARIA spinbutton.

Import: `import "@raylang/elements/number-input";` · Category: Inputs

#### `<ray-number-input>` (RayNumberInput, extends FieldControl)

Arrow Up/Down step (Shift: ×10), Page Up/Down ×10, Home/End go to min/max. The value is a number (undefined when empty); the form gets its plain digits; min and max are checked (rangeUnderflow, rangeOverflow). Enter submits its form, as in ray-input.

Properties:

- `value`: number. The number (undefined when empty).
- `min`: number. Minimum.
- `max`: number. Maximum.
- `step`: number, default `1`. What + and − add.
- `decimals`: number. Fixed decimals (2: 3 shows as 3.00).
- `prefix`: `string | null`. Shown before the number ("$").
- `suffix`: string. Shown after the number (" kg", "%").
- `thousandsSeparator` (attribute `thousands-separator`): string. Groups thousands in the shown text (",", ".", " ").
- `decimalSeparator` (attribute `decimal-separator`): string, default `.`. The decimal mark shown and typed ("," in many locales).
- `clamp`: `blur` | `strict` | `none`, default `blur`. When out-of-range input is clamped: on blur, while typing, or never (then it is invalid).
- `format`: `number` | `duration`, default `number`, reflects. duration: the value is seconds, shown and typed as m:ss (h:mm:ss when min or max reaches an hour; a plain number is seconds); aria-valuetext says "3 minutes, 15 seconds" in the page's language. decimals, prefix, suffix and the separators do not apply.
- `hideControls` (attribute `hide-controls`): boolean, reflects. No + and − buttons (the keys still step).
- `placeholder`: string. Shown while empty.
- `readonly`: boolean, reflects. Not editable, still submitted.

Also the properties of FieldControl: `name`, `label`, `description`, `error`, `required`, `disabled`, `size`, `radius`, `variant`, `descriptionPosition`.

Events:

- `input`: On every change of the value (typing, keys, buttons).
- `change`: When the value is committed (blur, a step).

Slots:

- `left`: Left section (an icon).
- `right`: Right section.

Parts (`::part()`):

- `input`: The text field.
- `controls`: The + and − column.
- `increment`: The + button.
- `decrement`: The − button.

Methods and properties:

- `stepBy(steps: number): void`: Adds steps (negative: subtracts), clamped; fires input and change.

Vue `v-model`: `value` (updated on input).

Exports (from `@raylang/elements/number-input` and `@raylang/elements`):

- `function parseNumber(text: string, options?: { decimal?: string; thousands?: string }): number`: The number in a text with separators, prefix or suffix (NaN if none).
- `function formatNumber(n: number, options?: { decimals?: number; thousands?: string; decimal?: string }): string`: A number as text with fixed decimals and separators.

### Password input

A password field with a button that shows or hides what was typed (Mantine's PasswordInput). Everything else is ray-input: label, description, error, sizes, validation, forms.

Import: `import "@raylang/elements/password-input";` · Category: Inputs

#### `<ray-password-input>` (RayPasswordInput, extends RayInput)

autocomplete defaults to current-password: use new-password on sign-up and change forms. The toggle keeps the focus and the caret in the field.

Properties:

- `visible`: boolean, reflects. The password is shown as text.
- `showLabel` (attribute `show-label`): string, default `Show password`. Accessible name of the toggle while hidden.
- `hideLabel` (attribute `hide-label`): string, default `Hide password`. Accessible name of the toggle while shown.

Also the properties of RayInput (`<ray-input>`): `value`, `type`, `name`, `label`, `description`, `descriptionPosition`, `error`, `placeholder`, `required`, `disabled`, `readonly`, `size`, `radius`, `variant`, `highlight`, `complete`, `suggestionsLabel`.

Events:

- `ray-visibility-change` (detail `{ visible: boolean }`): The user showed or hid the password.

Parts (`::part()`):

- `toggle`: The show/hide button.

### Path input (also File path, Folder picker)

A field for a path on disk: a file to open, a folder, or where to save. In a std/ui window (with ray-elements/core/raylang.js) a Browse… button opens the system dialog; in a browser it is a plain text field. Everything else is ray-input.

Import: `import "@raylang/elements/path-input";` · Category: Inputs

#### `<ray-path-input>` (RayPathInput, extends RayInput)

Browse… shows only with a native host that offers pick_path (see core/host.js); the dialog starts in the folder of the current path. The path can always be typed or pasted.

Properties:

- `mode`: `open` | `folder` | `save`, default `open`, reflects. What the dialog chooses: an existing file, a folder, or a file to save (the current name is suggested).
- `accept`: string, reflects. File types the dialog offers, as in <input type=file>: ".json,.toml", "image/*" (ignored for folders).
- `browseLabel` (attribute `browse-label`): string, default `Browse…`. Text of the button.
- `dialogTitle` (attribute `dialog-title`): string. Title of the system dialog (default: the label).

Also the properties of RayInput (`<ray-input>`): `value`, `type`, `name`, `label`, `description`, `descriptionPosition`, `error`, `placeholder`, `required`, `disabled`, `readonly`, `size`, `radius`, `variant`, `highlight`, `complete`, `suggestionsLabel`.

Events:

- `change`: The path changed: typed and committed, or chosen in the dialog.
- `ray-error` (detail `{ error: Error }`): The system dialog failed.

Parts (`::part()`):

- `browse`: The Browse… button.

Methods and properties:

- `readonly canBrowse: boolean`: Whether Browse… is available (a native host offers pick_path).
- `browse(): Promise<string | null>`: Opens the system dialog; resolves to the chosen path (also set as value, with input and change), or null.

Exports (from `@raylang/elements/path-input` and `@raylang/elements`):

- `function dirName(path: string): string`: The folder part of a path ("" when it has none), with / or \ separators.
- `function baseName(path: string): string`: The last part of a path.

#### In a raylang app

Browse… shows only in a `std/ui` window with [the native bridge](https://elements.raylang.dev/raylang.html#using-the-bridge). It opens the system's dialog for the `mode`, starting in the folder of the current path (`save` also suggests the current file name). The chosen path fills the field and fires `input` and `change`; the program gets it with the form like any other field.

```html
<ray-path-input name="workspace" label="Workspace" mode="folder"></ray-path-input>
<ray-path-input name="export" label="Export to" mode="save" accept=".csv"></ray-path-input>
```

```ray
// The program's side: ui.events() through bridge.handle, then the form arrives as usual.
for e in ui.events() {
    if (bridge.handle(e)) {
        continue;
    }
    if (e.kind == "message" && e.tag.starts_with("settings:")) {
        save_settings(e.tag.substring(9, e.tag.len()))?;
    }
}
```

### Radio group

One choice among options: ray-radio (or ray-radio-card) elements inside a ray-radio-group, which is the form control.

Import: `import "@raylang/elements/radio";` · Category: Inputs

#### `<ray-radio-group>` (RayRadioGroup, extends FormControl)

Arrow keys move the selection, Tab enters and leaves the group.

Properties:

- `value`: string. Value of the checked radio. Initial: the value attribute, or a radio with the checked attribute.
- `name`: string. Form field name.
- `label`: string. Group label (also its accessible name).
- `description`: string. Help text.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the control (help first) or after it, with the error (fields in a row stay aligned).
- `error`: string. Error text.
- `required`: boolean. A choice is needed to submit.
- `disabled`: boolean. Disables every radio.
- `orientation`: `vertical` | `horizontal`, default `vertical`, reflects. Layout of the radios.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Size of every radio.
- `color`: string. Checked color of every radio.
- `variant`: `filled` | `outline`, default `filled`, reflects. Checked look of every radio: filled circle, or colored ring and dot.

Events:

- `input`: When the user picks a radio.
- `change`: When the user picks a radio.

Slots:

- (default): ray-radio or ray-radio-card elements (may be wrapped in layout elements: a ray-grid of cards).

Methods and properties:

- `readonly radios: RayRadio[]`: The radios (and radio cards) of the group.

Vue `v-model`: `value` (updated on change).

#### `<ray-radio>` (RayRadio, extends RayElement)

Properties:

- `value`: string, reflects. Value given to the group when chosen.
- `checked` (attribute `checked`: the initial value only): boolean. Whether this radio is the group's value; setting it sets the group's value. The checked attribute marks the group's initial value (when the group has no value attribute).
- `label`: string. Label text (or the content).
- `description`: string. Help text under the label.
- `disabled`: boolean. Cannot be chosen.
- `color`: string. Overrides the group color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`. Overrides the group size.
- `variant`: `filled` | `outline`, reflects. Overrides the group variant.

Slots:

- (default): Label content.

Parts (`::part()`):

- `indicator`: The circle.
- `label`: The label.

#### `<ray-radio-card>` (RayRadioCard, extends RayRadio)

A radio drawn as a card: a title (label), a detail (description), an icon, more content; checked, it takes the color's border and light background. Inside a ray-radio-group like a ray-radio (arrow keys, the form, required, disabled); put the cards in a ray-grid for columns.

Properties:

- `hideIndicator` (attribute `hide-indicator`): boolean, reflects. No radio circle: the card's border and background alone show the choice.

Also the properties of RayRadio (`<ray-radio>`): `value`, `checked`, `label`, `description`, `disabled`, `color`, `size`, `variant`.

Slots:

- (default): More content under the description.
- `icon`: An icon before the title.

Parts (`::part()`):

- `root`: The card.
- `icon`: Around the icon slot.

### Search

A search box: icon, clear button, an optional shortcut that focuses it, and a debounced ray-search event. A RayInput, so it has a label and takes part in forms.

Import: `import "@raylang/elements/search";` · Category: Inputs

#### `<ray-search>` (RaySearch, extends FieldControl)

Escape clears it (when it has text); Enter fires ray-search at once. JS: clear(), focus().

Properties:

- `value`: string. Current text.
- `placeholder`: string, default `Search…`. Placeholder text.
- `shortcut`: string. Keyboard shortcut that focuses it ("mod+k", "/"; mod = ⌘ on macOS, Ctrl elsewhere). Shown as a hint while empty.
- `debounce`: number, default `200`. Milliseconds of quiet typing before ray-search fires (0: on every keystroke).
- `name`: string, reflects. Form field name.
- `label`: string. Visible label (also the accessible name). Without it, use aria-label.
- `disabled`: boolean. Not editable nor submitted.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height and font size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius.
- `variant`: `default` | `filled` | `unstyled`, default `filled`, reflects. Box style.

Also the properties of FieldControl: `description`, `error`, `required`, `descriptionPosition`.

Events:

- `input`: On every edit (value already updated).
- `ray-search` (detail `{ value: string }`): After `debounce` ms without typing, on Enter, and when cleared.

Parts (`::part()`):

- `input`: The inner <input type=search>.
- `icon`: The search icon.
- `clear`: The clear button.
- `shortcut`: The shortcut hint.
- `wrapper`: The box.

Methods and properties:

- `clear(): void`: Empties the box (fires input and ray-search).

Vue `v-model`: `value` (updated on input).

### Segmented control

One choice among a few, as a segmented row with a sliding indicator. Options from child <option> elements or data. Form-associated.

Import: `import "@raylang/elements/segmented-control";` · Category: Inputs

#### `<ray-segmented-control>` (RaySegmentedControl, extends FormControl)

Properties:

- `value`: string. Selected value (default: the first enabled option).
- `data` (property only): `Array<string | { value: string; label?: string; disabled?: boolean }>`. Options as strings or { value, label, disabled }.
- `name`: string. Form field name.
- `color`: string, reflects. Indicator color (default: a raised neutral segment).
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height and font size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius.
- `fullWidth` (attribute `full-width`): boolean. Takes the whole width.
- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. Direction.
- `disabled`: boolean. Not interactive nor submitted.

Events:

- `input`: The user picked another option.
- `change`: The user picked another option.

Slots:

- (default): <option> elements.

Parts (`::part()`):

- `root`: The row.
- `indicator`: The sliding highlight.
- `control`: Each option button.

Methods and properties:

- `readonly items: Array<{ value: string; label: string; disabled: boolean }>`: The options, from data or the child options.

Vue `v-model`: `value` (updated on change).

### Select

A select with its own dropdown (keyboard, typeahead, groups); options from child <option> elements or the data property. Form-associated.

Import: `import "@raylang/elements/select";` · Category: Inputs

#### `<ray-select>` (RaySelect, extends FieldControl)

Properties:

- `value`: string. Selected value.
- `data` (property only): `Array<string | { value: string; label?: string; disabled?: boolean }>`. Options as strings or { value, label, disabled } (instead of child options).
- `placeholder`: string. Shown while nothing is selected (with required, blocks submit).
- `open`: boolean, reflects. The dropdown is shown.
- `name`: string. Form field name.
- `label`: string. Visible label.
- `description`: string. Help text.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the control (help first) or after it, with the error (fields in a row stay aligned).
- `error`: string. Error text.
- `required`: boolean. Required for form submission.
- `disabled`: boolean. Not interactive nor submitted.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height and font size.
- `variant`: `default` | `filled` | `unstyled`, default `default`, reflects. Box style.

Also the properties of FieldControl: `radius`.

Events:

- `input`: When the selection changes.
- `change`: When the selection changes.
- `ray-open`: The dropdown opened.
- `ray-close`: The dropdown closed.

Slots:

- (default): <option> and <optgroup> elements.

Parts (`::part()`):

- `trigger`: The combobox button showing the selected option.
- `dropdown`: The listbox panel (a popover in the top layer).
- `option`: Each option in the dropdown ([aria-selected], [data-active], [aria-disabled]).
- `select`: The hidden native <select> that holds the value (the model).
- `wrapper`: The box.

Methods and properties:

- `readonly options: HTMLOptionsCollection`: The options of the model select.
- `toggle(force?: boolean): void`: Opens or closes the dropdown.

Vue `v-model`: `value` (updated on change).

### Slider

A native range input (keyboard, touch and screen readers as usual) with label, value display and marks. Form-associated.

Import: `import "@raylang/elements/slider";` · Category: Inputs

#### `<ray-slider>` (RaySlider, extends FieldControl)

Properties:

- `value`: number. Current value. The value attribute is the initial one (restored on reset).
- `min`: number, default `0`. Minimum.
- `max`: number, default `100`. Maximum.
- `step`: number, default `1`. Step.
- `name`: string. Form field name.
- `label`: string. Visible label.
- `description`: string. Help text.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the control (help first) or after it, with the error (fields in a row stay aligned).
- `error`: string. Error text.
- `disabled`: boolean. Not interactive nor submitted.
- `color`: string, reflects. Track and thumb color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Track and thumb size.
- `showValue` (attribute `show-value`): boolean, reflects. Shows the value next to the label.
- `unit`: string. Appended to the shown value and its spoken text (%, px, ms…).
- `marks` (property only): `Array<number | { value: number; label?: string }>`. Labeled ticks under the track.

Also the properties of FieldControl: `required`, `radius`, `variant`.

Events:

- `input`: While dragging.
- `change`: When released.

Parts (`::part()`):

- `input`: The native range input.

Vue `v-model`: `value` (updated on input).

### Switch

An on/off toggle with the same API as Checkbox, announced as a switch.

Import: `import "@raylang/elements/switch";` · Category: Inputs

#### `<ray-switch>` (RaySwitch, extends RayCheckbox)

Same properties and events as ray-checkbox (indeterminate does not apply).

Properties:

- `checked` (attribute `checked`: the initial value only): boolean. Current state. The checked attribute is the initial state.
- `value`: string, default `on`. Submitted value when on.
- `name`: string. Form field name.
- `label`: string. Label text (or the content).
- `description`: string. Help text.
- `error`: string. Error text.
- `labelPosition` (attribute `label-position`): `end` | `start` | `right` | `left`, default `end`, reflects. Side of the label: start/end follow the writing direction; left/right are sides of the screen.
- `color`: string. Track color when on.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Track size.
- `disabled`: boolean. Not interactive nor submitted.

Also the properties of RayCheckbox (`<ray-checkbox>`): `indeterminate`, `required`, `variant`.
Also the properties of FieldControl: `radius`, `descriptionPosition`.

Events:

- `change`: When the user toggles it.

Slots:

- (default): Label content.

Parts (`::part()`):

- `track`: The track.
- `thumb`: The thumb.

Vue `v-model`: `checked` (updated on change).

### Textarea

A multi-line text field that can grow with its content. Form-associated.

Import: `import "@raylang/elements/textarea";` · Category: Inputs

#### `<ray-textarea>` (RayTextarea, extends FieldControl)

Also forwards placeholder, autocomplete, minlength, maxlength, spellcheck and wrap. Initial value: the value attribute or the element's text.

Properties:

- `value`: string. Current value.
- `rows`: number, default `3`. Visible rows (minimum when autosize).
- `autosize`: boolean. Grows with the content.
- `maxRows` (attribute `max-rows`): number. With autosize: stop growing and scroll after this many rows.
- `name`: string. Form field name.
- `label`: string. Visible label.
- `description`: string. Help text.
- `descriptionPosition` (attribute `description-position`): `above` | `below`, default `above`, reflects. The description before the control (help first) or after it, with the error (fields in a row stay aligned).
- `error`: string. Error text.
- `required`: boolean. Required for form submission.
- `disabled`: boolean. Not editable nor submitted.
- `readonly`: boolean. Not editable, still submitted.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Font size.
- `variant`: `default` | `filled` | `unstyled`, default `default`, reflects. Box style.
- `highlight` (property only): `((text: string) => HighlightRange[]) | null`. Marks ranges of the text, painted behind it: called with the text on every change (typed or set), it returns { start, end, kind?, title? } offsets. kind "error" is red with a wavy underline; any other kind is styled with ::part(highlight-<kind>); title is the tooltip over the range. Ranges must not overlap.
- `complete` (property only): `((text: string, caret: number) => CompletionResult | null | Promise<CompletionResult | null>) | null`. Inline suggestions: called as the user types (and on Ctrl+Space) with the text and the caret, it returns the part of the text a suggestion would replace and the suggestions ({ from, to, items }), or null for none. A list opens under that part (ArrowUp/Down, Enter or Tab to accept, Escape to close); the chosen item's value replaces from–to as an undoable edit, then ray-complete fires. The field becomes a combobox (aria-autocomplete, aria-expanded, aria-activedescendant).
- `suggestionsLabel` (attribute `suggestions-label`): string, default `Suggestions`. Accessible name of the suggestion list.

Also the properties of FieldControl: `radius`.

Attributes (forwarded to the inner element):

- `placeholder`: Placeholder text.
- `autocomplete`: Forwarded to the inner textarea.
- `minlength`: Minimum length.
- `maxlength`: Maximum length.
- `wrap`: soft or hard.

Events:

- `ray-complete` (detail `{ item: CompletionItem; from: number; to: number }`): A suggestion was accepted (the text already has it).
- `input`: On every edit.
- `change`: When an edit is committed.

Parts (`::part()`):

- `textarea`: The inner <textarea>.
- `wrapper`: The box.
- `suggestions`: The suggestion list (a listbox in the top layer).
- `suggestion`: Each suggestion ([aria-selected] when active).
- `highlight`: Each marked range (also highlight-<kind> for a range with a kind).
- `text-layer`: The layer behind the text that holds the marks.

Methods and properties:

- `refreshHighlight(): void`: Runs highlight again, when what it marks changed but the text did not.

Vue `v-model`: `value` (updated on input).

### Bottom nav

The bottom navigation of a phone app (Material's navigation bar, the iOS tab bar): three to five destinations with an icon, a label and a badge, the current one marked by a pill. Links or a value; an action button in the middle; hides on scroll.

Import: `import "@raylang/elements/bottom-nav";` · Category: Navigation

#### `<ray-bottom-nav>` (RayBottomNav, extends RayElement)

With href items it marks the link to this page (aria-current="page"); without, it is a control (value, change). Clear of the home indicator (safe-area inset). In a ray-app-shell, put it in the bottom slot.

Properties:

- `value`: string, reflects. The current destination (an item's value, else its href, else its label).
- `label`: string, default `Main`. Accessible name of the navigation.
- `labels`: `always` | `active` | `never`, default `always`, reflects. Which labels show (the others stay for assistive technology).
- `indicator`: `pill` | `line` | `none`, default `pill`, reflects. How the current destination is marked besides its color.
- `color`: string, reflects. A palette color or any CSS color for the current item and the action (default: primary).
- `variant`: `default` | `floating`, default `default`, reflects. default: a bar across the bottom; floating: a rounded bar off the edges.
- `hideOnScroll` (attribute `hide-on-scroll`): boolean, reflects. Slides away while the content scrolls down, back on the way up.
- `fixed`: boolean, reflects. Pinned to the bottom of the window (outside a shell).
- `scrollTarget` (attribute `scroll-target`): string. A selector of the element whose scrolling it follows (default: its shell's, else the window).

Events:

- `change`: The user picked another destination (read value).
- `ray-select` (detail `{ value: string }`): An action item was pressed.

Slots:

- (default): ray-bottom-nav-item elements (3 to 5).

Parts (`::part()`):

- `nav`: The <nav>.

Methods and properties:

- `readonly items: RayBottomNavItem[]`: The items, in order.

Vue `v-model`: `value` (updated on change).

#### `<ray-bottom-nav-item>` (RayBottomNavItem, extends RayElement)

A link with href, else a button. The badge is read with the label ("Messages, 3").

Properties:

- `value`: string, reflects. Its value (default: its href, else its label).
- `label`: string. The label.
- `icon`: `IconName`. An icon of the registry, drawn filled on the current item when it has a filled version (or put one in the icon slot: yours, as it is).
- `href`: string, reflects. Makes it a link.
- `badge`: string. A count or a short text on the icon.
- `dot`: boolean, reflects. A dot on the icon (something new).
- `active`: boolean, reflects. Set by the bar: the current destination.
- `disabled`: boolean, reflects. Not interactive.
- `action`: boolean, reflects. A raised round button ("New"): it fires ray-select on the bar, it is not a destination.

Slots:

- `icon`: A custom icon (a ray-icon, an svg, an avatar).

Parts (`::part()`):

- `item`: The link or button.
- `indicator`: The pill behind the icon.
- `badge`: The badge.
- `label`: The label.

### Breadcrumbs

Where a page sits (Mantine's Breadcrumbs, the WAI-ARIA breadcrumb pattern): links in a labelled nav, the last one the current page. Any separator or a chevron; a long path collapses into an expandable "…".

Import: `import "@raylang/elements/breadcrumbs";` · Category: Navigation

#### `<ray-breadcrumbs>` (RayBreadcrumbs, extends RayElement)

A <nav aria-label="Breadcrumb"> around a list. The last crumb is the current page (aria-current="page") unless one says current.

Properties:

- `separator`: string, default `/`. Text between crumbs ("/", "›", "·") or "chevron" (an icon).
- `maxItems` (attribute `max-items`): number. Longer paths show the first crumb, "…" (a button that expands them) and the last max-items − 1.
- `label`: string, default `Breadcrumb`. Accessible name of the nav.
- `size`: `xs` | `sm` | `md` | `lg`, default `sm`, reflects. Font size.

Slots:

- (default): ray-breadcrumb elements.

Parts (`::part()`):

- `nav`: The <nav>.
- `list`: The <ol>.

Methods and properties:

- `readonly items: RayBreadcrumb[]`: The crumbs, in order.
- `expand(): void`: Shows every crumb of a collapsed path.

#### `<ray-breadcrumb>` (RayBreadcrumb, extends RayElement)

A link with href (text without, or when current).

Properties:

- `href`: string, reflects. Where it leads.
- `current`: boolean, reflects. This crumb is the current page (default: the last).

Slots:

- (default): The text.
- `icon`: An icon before the text.

Parts (`::part()`):

- `link`: The link (or the text of the current page).
- `separator`: The separator before it.
- `more`: The "…" button of a collapsed path.

### Document tabs

The tabs of open documents (an editor's, a browser's): closable, with an unsaved mark, all over one shared panel; WAI-ARIA tabs with arrows, Home/End and Delete to close. The app closes them: ray-request-close asks.

Import: `import "@raylang/elements/doc-tabs";` · Category: Navigation

#### `<ray-doc-tabs>` (RayDocTabs, extends RayElement)

Unlike ray-tabs, a tab has no panel of its own: they all control the element named by panel, whose content the app fills for the selected one. Closing is the app's: the ×, a middle click or Delete/Backspace fire ray-request-close, and the app removes the tab (after asking about unsaved changes, if it must). When the selected tab is removed, the one at its place is selected (change) and, if the closed tab had the focus, focused. More tabs than width: the bar scrolls sideways, fades the edge that hides tabs (data-overflow-start / data-overflow-end on the host), scrolls with a vertical wheel and keeps the selected tab in view.

Properties:

- `value`: string. Value of the selected tab (default: the first).
- `panel`: string. The id of the shared panel: it gets role=tabpanel and aria-labelledby the selected tab; the tabs get aria-controls.
- `label`: string. Accessible name of the tab list ("Open requests").
- `closeLabel` (attribute `close-label`): string, default `Close`. Tooltip of the ×.
- `dirtyLabel` (attribute `dirty-label`): string, default `Unsaved changes`. What assistive technology hears after the name of a dirty tab.

Events:

- `change`: The selected tab changed: a click, the arrow keys, or the selected tab removed.
- `ray-request-close` (detail `{ value: string; tab: RayDocTab; source: "button" | "middle" | "key" }`): The × was clicked, the tab middle-clicked, or Delete/Backspace pressed on it: remove the tab to close it (not fired for hide-close tabs).

Slots:

- (default): ray-doc-tab elements.
- `end`: After the tabs, outside the scrolling list: a new-tab button.

Parts (`::part()`):

- `list`: The tab list (it scrolls sideways when the tabs do not fit).
- `end`: The end slot's box.

Methods and properties:

- `readonly tabs: RayDocTab[]`: Its tabs, in order.
- `readonly panelElement: HTMLElement | null`: The shared panel, found by the panel id.

#### `<ray-doc-tab>` (RayDocTab, extends RayElement)

A document's tab: an icon or tag (slot left), its name (cut with an ellipsis; give the full one in title), and the × or the unsaved dot.

Properties:

- `value`: string, reflects. Identifies the document (ray-doc-tabs value).
- `dirty`: boolean, reflects. Unsaved changes: a dot in place of the ×, which comes back under the pointer.
- `hideClose` (attribute `hide-close`): boolean, reflects. Cannot be closed: no ×, no middle click, no Delete.

Slots:

- (default): The document's name.
- `left`: An icon or a tag (a file type, an HTTP method).

Parts (`::part()`):

- `label`: The name.
- `left-section`: The left slot's box.
- `close`: The × (pointer only: it is not focusable).
- `dot`: The unsaved mark.

### Nav link

A sidebar/navigation item: icon, label, description, badge, active state, and nested nav links that collapse under it.

Import: `import "@raylang/elements/nav-link";` · Category: Navigation

#### `<ray-nav-link>` (RayNavLink, extends RayElement)

A link with href (aria-current=page when active), or a button that toggles its nested links.

Properties:

- `label`: string. Text.
- `description`: string. Second line.
- `href`: string, reflects. Makes it a link (ignored when it has nested links).
- `active`: boolean, reflects. The current page or section.
- `opened`: boolean, reflects. Nested links are shown.
- `disabled`: boolean, reflects. Not interactive.
- `variant`: `light` | `filled` | `subtle`, default `light`, reflects. Style of the active state.
- `color`: string, reflects. Active color.
- `iconOnly` (attribute `icon-only`): boolean, reflects. Only the icon (left section), centered; the label becomes its accessible name and tooltip. A collapsed ray-sidebar sets it.

Events:

- `ray-toggle` (detail `{ opened: boolean }`): Nested links were shown or hidden.

Slots:

- (default): Nested ray-nav-link elements.
- `left`: Icon.
- `right`: Badge or count.

Parts (`::part()`):

- `link`: The inner <a> or <button>.
- `children`: The nested links.

Methods and properties:

- `readonly links: RayNavLink[]`: The nested nav links.

Vue `v-model`: `opened` (updated on ray-toggle).

### Pagination

Page navigation: previous/next, optional first/last, page numbers with ellipses; the number of items stays constant so it does not jump.

Import: `import "@raylang/elements/pagination";` · Category: Navigation

#### `<ray-pagination>` (RayPagination, extends RayElement)

JS: setPage(n), next(), previous(), first(), last(); page (clamped value).

Properties:

- `total`: number, default `1`. Number of pages.
- `value`: number, default `1`. Current page (1-based).
- `siblings`: number, default `1`. Pages shown on each side of the current one.
- `boundaries`: number, default `1`. Pages always shown at the start and the end.
- `withEdges` (attribute `with-edges`): boolean, reflects. Adds first/last page buttons.
- `hideControls` (attribute `hide-controls`): boolean, reflects. Hides the previous/next (and first/last) buttons.
- `color`: string, reflects. Color of the current page: a palette color or any CSS color. Default: the primary color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Item size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius of the items.
- `disabled`: boolean, reflects. Not interactive.
- `label`: string, default `Pagination`. Accessible name of the navigation landmark.

Events:

- `change`: The user went to another page (read `value`).

Parts (`::part()`):

- `root`: The <nav> landmark.
- `list`: The list of items.
- `item`: Every button (pages and controls).
- `active`: The current page button.
- `control`: Previous/next/first/last buttons.
- `dots`: An ellipsis.

Methods and properties:

- `readonly page: number`: The current page clamped to 1…total.
- `setPage(page: number): void`: Goes to a page (fires change).
- `next(): void`: Next page.
- `previous(): void`: Previous page.
- `first(): void`: First page.
- `last(): void`: Last page.

Vue `v-model`: `value` (updated on change).

Exports (from `@raylang/elements/pagination` and `@raylang/elements`):

- `function paginationRange(total: number, value: number, siblings?: number, boundaries?: number): Array<number | "dots">`: The items a pagination shows for a page (numbers and "dots").

### Sidebar

The side navigation of an app shell: header, content and footer; on wide screens it collapses to an icon rail (or out of view), below a breakpoint it becomes an off-canvas drawer. toggle() does the right thing for the screen. It is for navigation, a list of places with icons; for content such as a tree of documents, a panel that hides and resizes, put your own element in the start pane of a ray-split (min, max, autosave, collapsed).

Import: `import "@raylang/elements/sidebar";` · Category: Navigation

#### `<ray-sidebar>` (RaySidebar, extends RayElement)

Put ray-sidebar-group + ray-nav-link (with an icon in slot=left) inside. Collapsed, nav links show only their icon (the label becomes the tooltip) and the host has the collapsed attribute, so your own header/footer content can hide with CSS (ray-sidebar[collapsed] .brand-name { display: none }).

Properties:

- `collapsed`: boolean, reflects. Wide screens: collapsed as collapse says (an icon rail, or out of view).
- `collapse`: `icon` | `offcanvas`, default `icon`, reflects. What collapsed does on wide screens: icon, a rail of the nav links' icons; offcanvas, hidden entirely (no width, out of the tab order).
- `open`: boolean, reflects. Narrow screens: the drawer is shown (modal, focus trapped; Escape, backdrop click or a followed link close it).
- `side`: `start` | `end` | `left` | `right`, default `start`, reflects. The edge it sits on (its border faces the content, its narrow-screen drawer slides from there): start/end follow the writing direction; left/right are sides of the screen.
- `variant`: `sidebar` | `floating`, default `sidebar`, reflects. A panel against the edge, or a floating card with a margin.
- `width`: string. Width when expanded (CSS length). Default 16rem.
- `collapsedWidth` (attribute `collapsed-width`): string. Width of the icon rail. Default 3.5rem.
- `breakpoint`: string, default `48em`. At this viewport width and below, it becomes a drawer.
- `label`: string, default `Sidebar`. Accessible name of its navigation.
- `resizable`: boolean, reflects. Wide screens, expanded: its inner edge drags (or, focused, arrow-keys; Shift is faster, Home/End go to the limits) the width between min-width and max-width.
- `minWidth` (attribute `min-width`): number, default `192`. Narrowest width when resizing, in px.
- `maxWidth` (attribute `max-width`): number, default `480`. Widest width when resizing, in px.
- `autosave`: string. A key: the resized width is saved in localStorage and restored. A later change of width wins.
- `resizeLabel` (attribute `resize-label`): string, default `Resize sidebar`. Accessible name of the resize edge.

Events:

- `ray-resize` (detail `{ width: number }`): After a drag or a key resized it (resizable).
- `ray-toggle` (detail `{ collapsed: boolean; open: boolean; mobile: boolean }`): After toggle().
- `ray-open`: The drawer opened (narrow screens).
- `ray-close`: The drawer closed (narrow screens).

Slots:

- (default): The navigation: ray-sidebar-group and ray-nav-link elements.
- `header`: Top area (brand, workspace switcher).
- `footer`: Bottom area (user, settings).

Parts (`::part()`):

- `panel`: The panel (in the drawer on narrow screens).
- `header`: The header area.
- `content`: The scrolling <nav>.
- `footer`: The footer area.
- `resizer`: The resize edge (a separator), shown when resizable.
- `drawer`: The <dialog> used on narrow screens.

Methods and properties:

- `toggle(): void`: Collapses/expands on wide screens; opens/closes the drawer on narrow ones.
- `readonly mobile: boolean`: Whether it is in drawer mode (at or below the breakpoint).

#### `<ray-sidebar-group>` (RaySidebarGroup, extends RayElement)

A titled section of nav links; the title fades out (keeping its height) when the sidebar collapses.

Properties:

- `label`: string. Section title.

Slots:

- (default): ray-nav-link elements.

Parts (`::part()`):

- `label`: The title.
- `items`: The links container.

### Stepper

A task in steps (Mantine's Stepper): a wizard, a checkout, an onboarding. Numbers or icons, labels, connectors, the content of the active step; loading and error states; completed steps can be revisited.

Import: `import "@raylang/elements/stepper";` · Category: Navigation

#### `<ray-stepper>` (RayStepper, extends RayElement)

The steps are a labelled list; the active one has aria-current="step" and each reads "Step 2 of 4: Shipping, completed". Only the active step's content shows; past the last step, the completed slot.

Properties:

- `active`: number, default `0`, reflects. Index of the active step (steps.length: completed).
- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. Steps in a row above the content, or in a column beside it.
- `iconPosition` (attribute `icon-position`): `start` | `top` | `left`, default `start`, reflects. Label beside the number (after it in the reading direction), or under it (narrow screens, many steps). "left", its former name, still works.
- `allowStepSelect` (attribute `allow-step-select`): boolean, reflects. Completed steps are buttons that go back to them.
- `linear`: boolean, default `true`. With allow-step-select off, false lets the user jump to any step.
- `size`: `sm` | `md` | `lg`, default `md`, reflects. Size of the numbers.
- `color`: string, reflects. A palette color or any CSS color for active and completed steps (default: primary).
- `label`: string, default `Progress`. Accessible name of the list of steps.

Events:

- `change`: active changed by the user (a step clicked, next(), prev()).

Slots:

- (default): ray-step elements.
- `completed`: Shown once every step is done.

Parts (`::part()`):

- `steps`: The list of steps.
- `step`: A step (also step-done, step-active, step-todo).
- `indicator`: A step's number or icon.
- `label`: A step's label.
- `description`: A step's description.
- `connector`: The line between steps.
- `content`: The content area.

Methods and properties:

- `readonly steps: RayStep[]`: The steps, in order.
- `next(): void`: To the next step (past the last: completed).
- `prev(): void`: To the previous step.

Vue `v-model`: `active` (updated on change).

#### `<ray-step>` (RayStep, extends RayElement)

A step: its header is drawn by the stepper, its content shows while it is active.

Properties:

- `label`: string. The label.
- `description`: string. A line under the label.
- `icon`: string. An icon instead of the number.
- `completedIcon` (attribute `completed-icon`): string. The icon once done (default: check).
- `loading`: boolean, reflects. A spinner instead of the number.
- `error`: string. An error message: red step, the message as its description.
- `disabled`: boolean, reflects. Cannot be selected.

Slots:

- (default): The content shown while it is active.

### Tabs

Tabs and panels (WAI-ARIA tabs pattern): arrows, Home/End, automatic or manual activation.

Import: `import "@raylang/elements/tabs";` · Category: Navigation

#### `<ray-tabs>` (RayTabs, extends RayElement)

More tabs than width: the list scrolls sideways, fades the edge that hides tabs, scrolls with a vertical wheel and keeps the selected tab in view. The host then carries data-overflow-start and data-overflow-end (following the writing direction), to style it further.

Properties:

- `value`: string. Value of the active tab (default: the first enabled one).
- `variant`: `default` | `outline` | `pills`, default `default`, reflects. Tab style.
- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. Tab list direction (and arrow keys).
- `color`: string, reflects. Active indicator color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height, font size and padding of the tabs (xs for a compact bar).
- `activation`: `auto` | `manual`, default `auto`. manual: arrows move focus, Enter/Space activates.
- `grow`: boolean, reflects. Tabs share the full width.

Events:

- `change`: The user activated another tab.

Slots:

- (default): ray-tab and ray-tab-panel elements (tabs move to the tab list on their own).

Parts (`::part()`):

- `list`: The tab list (it scrolls sideways when the tabs do not fit).
- `panels`: The panel area.

Methods and properties:

- `readonly tabs: RayTab[]`: The tabs.
- `readonly panels: RayTabPanel[]`: The panels.

Vue `v-model`: `value` (updated on change).

#### `<ray-tab>` (RayTab, extends RayElement)

Properties:

- `value`: string, reflects. Matches a ray-tab-panel's value.
- `disabled`: boolean, reflects. Cannot be activated.
- `count`: string, reflects. A small number after the label ("3", "99+"), lighter than a badge; part of the tab's accessible name. Empty: none.

Slots:

- `left`: Icon.
- `right`: A badge or other content after the label (for a plain number, count is lighter).

Parts (`::part()`):

- `count`: The count.

#### `<ray-tab-panel>` (RayTabPanel, extends RayElement)

Properties:

- `value`: string, reflects. Matches a ray-tab's value.

### Command palette

Search and run actions from the keyboard (Mantine's Spotlight): fuzzy search, groups, shortcuts, ⌘K / Ctrl+K; combobox + listbox pattern in a modal dialog.

Import: `import "@raylang/elements/command-palette";` · Category: Overlays

#### `<ray-command-palette>` (RayCommandPalette, extends RayElement)

Running an action fires ray-select and calls its onSelect. The best matches come first, grouped.

Properties:

- `open`: boolean, reflects. Shown.
- `actions` (property only): `CommandAction[]`. The actions.
- `query`: string. The search text.
- `placeholder`: string, default `Search commands…`. Placeholder of the search field.
- `hotkey`: string, default `mod+k`. Toggle shortcut (mod = ⌘ on macOS, Ctrl elsewhere); empty to disable.
- `limit`: number, default `50`. Maximum results.
- `emptyLabel` (attribute `empty-label`): string, default `Nothing found`. Text without results.
- `label`: string, default `Command palette`. Accessible name.
- `hideHint` (attribute `hide-hint`): boolean, reflects. No keyboard hint at the bottom.
- `navigateLabel` (attribute `navigate-label`): string, default `navigate`. The keyboard hint's word for ↑↓.
- `runLabel` (attribute `run-label`): string, default `run`. The keyboard hint's word for ↵.
- `closeLabel` (attribute `close-label`): string, default `close`. The keyboard hint's word for esc.
- `nativeMenus` (attribute `native-menus`): boolean, reflects. With a native host (ray-elements/core/raylang.js in a std/ui window, menus declared with elements/bridge), also lists the app's menu bar, grouped by menu with its shortcuts; running one gives the program the menu's own event.
- `overlayBlur` (attribute `overlay-blur`): string. Blur of the page behind: px ("8"), a CSS length or "none". Default: --ray-overlay-blur ([overlay] blur in tokens.toml).

Events:

- `ray-select` (detail `{ action: CommandAction }`): An action was run.
- `ray-open`: After it opened.
- `ray-close`: After it closed.

Parts (`::part()`):

- `dialog`: The dialog.
- `input`: The search field.
- `option`: Each result.

Methods and properties:

- `show(): void`: Opens it.
- `hide(): void`: Closes it.
- `toggle(): void`: Opens or closes it.
- `readonly results: CommandAction[]`: The actions matching the query, in display order.

Vue `v-model`: `open` (updated on ray-open, ray-close).

Exports (from `@raylang/elements/command-palette` and `@raylang/elements`):

- `function score(action: CommandAction, query: string): number`: How well an action matches a query (0 = not at all).

Types:

- `{ id?: string; label: string; description?: string; group?: string; keywords?: string | string[]; shortcut?: string; icon?: string | Node; prefix?: string | Node; disabled?: boolean; native?: boolean; tag?: string; onSelect?: (action: CommandAction) => void }`: An action of ray-command-palette. icon is a 1.25rem square (a registered icon name, text or a Node); prefix is content of any width before the label (text or a Node, e.g. a ray-badge with an HTTP method), not searched.

#### In a raylang app

With `native-menus` and [the native bridge](https://elements.raylang.dev/raylang.html#using-the-bridge), the palette also lists the app's menu bar: every item, grouped by its menu, with its shortcut, the disabled ones greyed out. Running one gives the program the same `"menu"` event as choosing it in the menu bar, so the program handles it in one place.

```ray
let n = bridge.system();
bridge.menu(n, "File", [ui.item("new", "New window", "cmd+n"), ui.item("open", "Open…", "cmd+o")])?;
for raw in ui.events() {
    let e = match (bridge.route(n, raw)) {
        Option.Some(e) => e,
        Option.None => continue,
    };
    if (e.kind == "menu" && e.tag == "new") {
        new_window()?;
    }
}
```

```html
<ray-command-palette native-menus></ray-command-palette>
```

Declare the menus with `bridge.menu` (and change them with `bridge.replace_menu` and `bridge.set_menu_item`) so the palette knows them.

### Dialog (also Modal)

ray-elements's modal, on the native <dialog>: top layer, the rest of the page inert, focus trapped and restored, stackable. Title, description, header, body and footer; preset or free sizes. Also exports confirmDialog().

Import: `import "@raylang/elements/dialog";` · Category: Overlays

#### `<ray-dialog>` (RayDialog, extends RayElement)

Any slotted element with data-dialog-close closes it (its value becomes returnValue). JS: show(), close(returnValue), confirmDialog({ label, message, confirmLabel, cancelLabel, color, native }) -> Promise<boolean>; with a native host (ray-elements/core/raylang.js in a std/ui window) it asks with the system dialog unless native is false.

Properties:

- `open`: boolean, reflects. Shown as a modal.
- `label`: string. Heading (also the dialog's accessible name).
- `description`: string. A line under the title (the dialog's accessible description).
- `size`: `"xs" | "sm" | "md" | "lg" | "xl" | "full" | (string & {})`, default `md`, reflects. Width: xs…xl, full (the whole window), or any CSS length; a percentage is of the window (70% = 70vw, at least 40rem). Never wider than the window.
- `height`: string, reflects. Fixed height (the body scrolls): any CSS length; a percentage is of the window (70% = 70dvh, at least 30rem). Never taller than the window. Default: as tall as the content, up to the window.
- `radius`: string, reflects. Corner radius: xs…xl, none, or a CSS length. Default: lg.
- `position`: `center` | `top`, default `center`, reflects. Vertical placement.
- `persistent`: boolean, reflects. Escape and backdrop clicks do not close it (the × still does; hide it with hide-close). To allow only one of them, cancel ray-request-close by its source.
- `hideClose` (attribute `hide-close`): boolean, reflects. No close button in the header.
- `overlayBlur` (attribute `overlay-blur`): string. Blur of the page behind: px ("8"), a CSS length or "none". Default: --ray-overlay-blur ([overlay] blur in tokens.toml).

Events:

- `ray-open`: After it opened.
- `ray-close` (detail `{ returnValue: string }`): After it closed; detail: { returnValue }.
- `ray-request-close` (detail `{ source: "escape" | "backdrop" | "button" }`): Escape, backdrop or close button; cancelable (preventDefault keeps it open). detail: { source }.

Slots:

- (default): Body.
- `header`: Extra header content, next to the title.
- `footer`: Actions, aligned to the end.

Parts (`::part()`):

- `dialog`: The native <dialog>.
- `title`: The heading.
- `description`: The line under the heading.
- `header`: The header: title, description, the header slot and the close button.
- `body`: The scrollable body.
- `footer`: The footer.
- `close`: The close button.

Methods and properties:

- `show(): void`: Opens it.
- `close(returnValue?: string): void`: Closes it with an optional return value.
- `returnValue: string`: The value it was closed with.

Vue `v-model`: `open` (updated on ray-open, ray-close).

Exports (from `@raylang/elements/dialog` and `@raylang/elements`):

- `function confirmDialog(options?: ConfirmOptions): Promise<boolean>`: A confirmation dialog; resolves true when confirmed. With a native host, the system dialog (native: false keeps the ray-dialog).

Types:

- `{ label?: string; message?: string; confirmLabel?: string; cancelLabel?: string; color?: string; native?: boolean }`: Options of confirmDialog().

#### In a raylang app

With [the native bridge](https://elements.raylang.dev/raylang.html#using-the-bridge), `confirmDialog()` asks with the system's modal dialog instead of a `ray-dialog`, with the same answer. A red confirmation (a destructive action) gets the warning style. `native: false` keeps the page's dialog, for a question that needs more than a sentence.

```js
if (await confirmDialog({ label: "Delete 3 builds?", message: "This cannot be undone.", confirmLabel: "Delete", color: "red" })) {
  window.ray.send("delete:" + ids.join(","));
}
```

`ray-dialog` itself is always the page's: a form, a settings panel or a wizard stay in the page.

### Drawer

A panel sliding in from an edge: a RayDialog (focus, Escape, persistent, data-dialog-close, returnValue) with another look; modeless for side panels that keep the page interactive.

Import: `import "@raylang/elements/drawer";` · Category: Overlays

#### `<ray-drawer>` (RayDrawer, extends RayElement)

Any slotted element with data-dialog-close closes it. JS: show(), close(returnValue).

Properties:

- `open`: boolean, reflects. Shown.
- `label`: string. Heading (also the accessible name).
- `description`: string. A line under the title (the drawer's accessible description).
- `position`: `end` | `start` | `right` | `left` | `top` | `bottom`, default `end`, reflects. The edge it slides from: start/end follow the writing direction; left/right are sides of the screen.
- `size`: `"xs" | "sm" | "md" | "lg" | "xl" | "full" | (string & {})`, default `md`, reflects. Width (left/right) or height (top/bottom): xs…xl, full, or any CSS length.
- `modeless`: boolean, reflects. No backdrop nor scroll lock: the page stays interactive (a side panel).
- `floating`: boolean, reflects. Detached from the edge, with rounded corners.
- `persistent`: boolean, reflects. Escape and backdrop clicks do not close it.
- `hideClose` (attribute `hide-close`): boolean, reflects. No close button in the header.
- `overlayBlur` (attribute `overlay-blur`): string. Blur of the page behind: px ("8"), a CSS length or "none". Default: --ray-overlay-blur ([overlay] blur in tokens.toml).

Events:

- `ray-open`: After it opened.
- `ray-close` (detail `{ returnValue: string }`): After it closed; detail: { returnValue }.
- `ray-request-close` (detail `{ source: "escape" | "backdrop" | "button" }`): Escape, backdrop or close button; cancelable.

Slots:

- (default): Body (scrolls).
- `header`: Extra header content.
- `footer`: Actions, at the bottom.

Parts (`::part()`):

- `drawer`: The native <dialog>.
- `body`: The body.

Methods and properties:

- `show(): void`: Opens it.
- `close(returnValue?: string): void`: Closes it with an optional return value.
- `returnValue: string`: The value it was closed with.

Vue `v-model`: `open` (updated on ray-open, ray-close).

### Menu

A dropdown menu (menu button pattern: arrows, Home/End, typeahead, Enter, Escape) or, with context, a context menu at the pointer.

Import: `import "@raylang/elements/menu";` · Category: Overlays

#### `<ray-menu>` (RayMenu, extends Floating)

Properties:

- `open`: boolean, reflects. Shown.
- `placement`: `bottom-start` | `bottom` | `bottom-end` | `top-start` | `top` | `top-end` | `right-start` | `left-start`, default `bottom-start`, reflects. Preferred side and alignment: top/bottom/left/right are sides of the screen; on top and bottom, -start/-end follow the writing direction (right to left, "bottom-start" lines up the right edges).
- `context`: boolean, reflects. Opens on right click (contextmenu) over the trigger area, at the pointer.
- `keepOpen` (attribute `keep-open`): boolean, reflects. Choosing an item does not close the menu.
- `native`: boolean, reflects. With a native host (ray-elements/core/raylang.js in a std/ui window), opens as the system's context menu at the pointer: items and dividers, same ray-select.

Also the properties of Floating: `offset`.

Events:

- `ray-select` (detail `{ value: string; item: RayMenuItem }`): An item was chosen; detail: { value, item }.
- `ray-request-open` (detail `{ event: Event }`): Its trigger is about to open it (click, Arrow keys, right click), before the items are read, native menu included: fill items that depend on what was clicked here. Cancelable (preventDefault keeps it closed). Not fired by show() or open = true. detail: { event }.
- `ray-open`: After it opened.
- `ray-close`: After it closed.

Slots:

- `trigger`: The button that opens it, or the area for a context menu.
- (default): ray-menu-item, ray-menu-label and ray-menu-divider elements.

Parts (`::part()`):

- `dropdown`: The panel.

Methods and properties:

- `popupNative(): Promise<RayMenuItem | null>`: Opens the items as the system's context menu (needs a native host); resolves to the chosen item, or null.
- `show(): void`: Opens it.
- `hide(): void`: Closes it.
- `toggle(): void`: Opens or closes it.
- `readonly trigger: Element | null`: The trigger element.
- `readonly items: RayMenuItem[]`: The items of this menu.

Vue `v-model`: `open` (updated on ray-open, ray-close).

#### `<ray-menu-item>` (RayMenuItem, extends RayElement)

Properties:

- `value`: string, reflects. Reported in ray-select (default: the text).
- `disabled`: boolean, reflects. Skipped by the keyboard, cannot be chosen.
- `color`: string, reflects. Text and hover color (e.g. red for destructive actions).
- `type`: `item` | `checkbox` | `radio`, default `item`, reflects. checkbox: choosing it toggles checked (menuitemcheckbox); radio: choosing it checks it and unchecks the radio items of the menu with the same name (menuitemradio). Both show a check mark when checked, in the native menu too.
- `checked`: boolean, reflects. Checked (checkbox and radio items). Already updated when ray-select fires.
- `name`: string, reflects. The group of a radio item: one checked per name in the menu.

Slots:

- (default): Label.
- `left`: Icon.
- `right`: Shortcut or badge.

Parts (`::part()`):

- `mark`: The check mark of a checkbox or radio item.

Methods and properties:

- `readonly checkable: boolean`: Whether type is checkbox or radio.

#### `<ray-menu-label>` (RayMenuLabel, extends RayElement)

A section caption inside the menu.

#### `<ray-menu-divider>` (RayMenuDivider, extends RayElement)

A separator between groups of items.

#### In a raylang app

With `native` and [the native bridge](https://elements.raylang.dev/raylang.html#using-the-bridge), the menu opens as the system's context menu at the pointer: its items and dividers, disabled ones greyed out. The choice fires the same `ray-select`, so the same code handles both.

```html
<ray-menu native context>
  <div slot="trigger" class="file-row">report.csv</div>
  <ray-menu-item value="open">Open</ray-menu-item>
  <ray-menu-item value="reveal">Show in Finder</ray-menu-item>
  <ray-menu-divider></ray-menu-divider>
  <ray-menu-item value="delete" color="red">Delete</ray-menu-item>
</ray-menu>
```

Checkbox and radio items show their check mark there too. Labels, nested menus, icons and colors are the page menu's only. A dismissed native menu fires nothing.

The native menu reads its items the moment it opens, so items that depend on what was clicked go in `ray-request-open`, which comes first (a `contextmenu` listener of your own on the trigger may run after the menu's):

```js
menu.addEventListener("ray-request-open", (e) => {
  const row = e.detail.event.target.closest(".file-row");
  menu.replaceChildren(menu.querySelector("[slot=trigger]"), ...itemsFor(row));
});
```

### Popover

A floating panel anchored to a trigger, in the top layer; closes on Escape and outside clicks.

Import: `import "@raylang/elements/popover";` · Category: Overlays

#### `<ray-popover>` (RayPopover, extends Floating)

Positioned in JS (flip + shift to stay in the viewport). JS: show(), hide(), toggle().

Properties:

- `open`: boolean, reflects. Shown.
- `placement`: `bottom` | `bottom-start` | `bottom-end` | `top` | `top-start` | `top-end` | `left` | `left-start` | `left-end` | `right` | `right-start` | `right-end`, default `bottom`, reflects. Preferred side and alignment: top/bottom/left/right are sides of the screen; on top and bottom, -start/-end follow the writing direction (right to left, "bottom-start" lines up the right edges).
- `offset`: number, default `8`. Gap to the trigger in px.
- `width`: string. Panel width (px number or CSS length). Default: its content.
- `matchWidth` (attribute `match-width`): boolean. At least as wide as the trigger.
- `padding`: `0` | `xs` | `sm` | `md` | `lg`, default `md`, reflects. Panel padding.
- `trapFocus` (attribute `trap-focus`): boolean. Moves focus into the panel when opened and keeps Tab inside it.

Events:

- `ray-open`: After it opened.
- `ray-close`: After it closed (also by Escape or an outside click).

Slots:

- `trigger`: The element that toggles it (gets aria-haspopup and aria-expanded).
- (default): Panel content.

Parts (`::part()`):

- `dropdown`: The panel.

Methods and properties:

- `show(): void`: Opens it.
- `hide(): void`: Closes it.
- `toggle(): void`: Opens or closes it.
- `readonly trigger: Element | null`: The trigger element.

Vue `v-model`: `open` (updated on ray-open, ray-close).

### Tooltip

A short hint on hover and focus of its child; the label also becomes the child's accessible description.

Import: `import "@raylang/elements/tooltip";` · Category: Overlays

#### `<ray-tooltip>` (RayTooltip, extends Floating)

Properties:

- `label`: string. Tooltip text.
- `placement`: `top` | `bottom` | `left` | `right` | `top-start` | `top-end` | `bottom-start` | `bottom-end`, default `top`, reflects. Preferred side; -start/-end follow the writing direction.
- `openDelay` (attribute `open-delay`): number, default `300`. ms before showing.
- `closeDelay` (attribute `close-delay`): number, default `0`. ms before hiding.
- `color`: string. A palette color or any CSS color. Default: inverted foreground/background.
- `disabled`: boolean. Never shows.

Also the properties of Floating: `open`, `offset`.

Slots:

- (default): The element the tooltip describes (one element).

Parts (`::part()`):

- `tooltip`: The tooltip box.

Methods and properties:

- `show(): void`: Opens it.
- `hide(): void`: Closes it.
- `toggle(): void`: Opens or closes it.
- `readonly trigger: Element | null`: The trigger element.

### Accordion

Collapsible sections (WAI-ARIA accordion pattern); one open at a time, or several with multiple.

Import: `import "@raylang/elements/accordion";` · Category: Data display

#### `<ray-accordion>` (RayAccordion, extends RayElement)

Properties:

- `value`: `string | string[] | undefined`. Open item's value; with multiple, an array (attribute: comma-separated).
- `multiple`: boolean, reflects. Several items may be open.
- `variant`: `default` | `contained` | `separated` | `filled`, default `default`, reflects. Visual style.
- `chevronPosition` (attribute `chevron-position`): `end` | `start` | `right` | `left`, default `end`, reflects. Side of the chevron: start/end follow the writing direction; left/right are sides of the screen.

Events:

- `change`: The user opened or closed an item.

Slots:

- (default): ray-accordion-item elements.

Methods and properties:

- `readonly items: RayAccordionItem[]`: The items.
- `readonly openValues: string[]`: The open values as an array, whatever the mode.

Vue `v-model`: `value` (updated on change).

#### `<ray-accordion-item>` (RayAccordionItem, extends RayElement)

Properties:

- `value`: string, reflects. Identifies the item in the accordion's value.
- `label`: string. Header text (or slot=label).
- `description`: string. A secondary line under the label, in the header.
- `disabled`: boolean, reflects. Cannot be toggled.
- `headingLevel` (attribute `heading-level`): number, default `3`. aria-level of the header.

Slots:

- (default): Panel content.
- `label`: Rich header content.
- `left`: Icon before the label.

Parts (`::part()`):

- `control`: The header button.
- `description`: The secondary line under the label.
- `panel`: The collapsible region.

Methods and properties:

- `readonly open: boolean`: Whether this item is expanded.

### Attachment

A file in a composer, upload list or chat: thumbnail or type icon, name, size, upload progress, error, remove and download.

Import: `import "@raylang/elements/attachment";` · Category: Data display

#### `<ray-attachment>` (RayAttachment, extends RayElement)

Assign a File to `file` to fill name, size, type and an image thumbnail. Removing it (× button) fires a cancelable ray-remove and then removes the element.

Properties:

- `name`: string, reflects. File name (ellipsized; full name in the tooltip).
- `size`: number. Size in bytes, shown as "12 KB", "3.4 MB".
- `type`: string, reflects. MIME type: picks the icon (image or file) and, with the name, the extension badge.
- `src`: string. Thumbnail URL for images (falls back to the icon if it fails to load).
- `href`: string, reflects. Makes the name a download link.
- `progress`: number. Upload progress 0–100: a thin bar and "Uploading… 45%". Unset: done.
- `status`: `uploading` | `done` | `error`, reflects. Explicit state. Default: "uploading" while progress is set, else "done".
- `error`: string. Error text shown with status="error" (default "Upload failed").
- `removable`: boolean, reflects. Shows a remove (×) button.
- `removeLabel` (attribute `remove-label`): string, default `Remove {name}`. Accessible label of the remove button; {name} is replaced by the file name.
- `variant`: `row` | `card`, default `row`, reflects. row: a compact chip; card: the thumbnail on top.
- `disabled`: boolean, reflects. Dimmed, not removable, the name is not a link.

Events:

- `ray-remove` (detail `{ name: string; file: File | null }`): The remove button was pressed; cancelable (preventDefault keeps the element).

Parts (`::part()`):

- `item`: The box.
- `thumbnail`: The thumbnail or icon box.
- `badge`: The extension badge (PDF, PNG…).
- `name`: The file name (a link with href).
- `meta`: Size, upload state or error.
- `progress`: The upload progress bar.
- `remove`: The remove button.

Methods and properties:

- `file: File | null`: The File shown (fills name, size, type and a thumbnail for images).
- `readonly state: "uploading" | "done" | "error"`: The effective status.

#### `<ray-attachments>` (RayAttachments, extends RayElement)

A wrapping row of ray-attachment elements.

Slots:

- (default): ray-attachment elements.

### Avatar

An image, the initials of a name, or a placeholder icon.

Import: `import "@raylang/elements/avatar";` · Category: Data display

#### `<ray-avatar>` (RayAvatar, extends RayElement)

Properties:

- `src`: string, reflects. Image URL; falls back to initials if it fails to load.
- `alt`: string, reflects. Accessible name (default: name).
- `name`: string, reflects. Person or entity name; its initials are shown without an image.
- `color`: string. A palette color or any CSS color.
- `variant`: `light` | `filled` | `outline` | `default`, default `light`, reflects. Style of the initials/placeholder.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `md`, reflects. Diameter.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius. Default: full.

Slots:

- (default): Custom content (e.g. an icon) instead of initials.

Parts (`::part()`):

- `avatar`: The box.
- `image`: The <img>.

Exports (from `@raylang/elements/avatar` and `@raylang/elements`):

- `function initials(name: string): string`: Up to two initials of a name: "Ada Lovelace" -> "AL".

### Badge

A short status label.

Import: `import "@raylang/elements/badge";` · Category: Data display

#### `<ray-badge>` (RayBadge, extends RayElement)

Properties:

- `variant`: `light` | `filled` | `outline` | `dot` | `default` | `gradient`, default `light`, reflects. Visual style.
- `gradient`: string, reflects. With variant=gradient: "from to [deg]", palette colors or CSS colors ("teal blue 90"). Default: the --ray-gradient-* tokens.
- `color`: string. A palette color or any CSS color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Height and font size.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius. Default: full.
- `normalCase` (attribute `normal-case`): boolean. Keeps the text as written instead of uppercase.

Slots:

- (default): The text.

Parts (`::part()`):

- `badge`: The badge box.

### Blockquote

A quotation set apart from the text (Mantine's Blockquote): a colored edge, a quote mark on it and the attribution below. A real <blockquote> inside, with the source's URL as its cite.

Import: `import "@raylang/elements/blockquote";` · Category: Data display

#### `<ray-blockquote>` (RayBlockquote, extends RayElement)

Paragraphs in it are spaced and the last one has no bottom margin. The attribution is text (cite) or rich content (slot="cite": an avatar, a name, a role).

Properties:

- `cite`: string. Who said it, shown below the quote ("— Grace Hopper").
- `href`: string. URL of the source: the inner blockquote's cite attribute.
- `color`: string, reflects. A palette color or any CSS color, for the edge, the mark and the tint. Default: the primary.
- `variant`: `light` | `outline` | `filled`, default `light`, reflects. light: tinted background; outline: border and edge only; filled: solid color (a pull quote).
- `icon`: `IconName`, default `quote`. Registry icon of the mark, or none. The icon slot replaces it.
- `size`: `sm` | `md` | `lg`, default `md`, reflects. Text size (lg for a pull quote).
- `padding`: string, reflects. Inner spacing: xs…xl (the spacing scale), px as a number, or a CSS length. Default: md.
- `hideEdge` (attribute `hide-edge`): boolean, reflects. No colored edge on the start side (the tint, border and mark stay).
- `radius`: string, reflects. Corner radius: xs…xl, none, or a CSS length. Default: md.

Slots:

- (default): The quotation (text or paragraphs).
- `cite`: Rich attribution, instead of cite.
- `icon`: A custom mark, instead of icon.

Parts (`::part()`):

- `quote`: The <blockquote>.
- `icon`: The disc with the mark.
- `cite`: The attribution (a <figcaption>).

### Carousel

Slides in a scroll-snap viewport: native swipe and scrolling, previous/next controls, indicators, keyboard, loop and autoplay with a pause button.

Import: `import "@raylang/elements/carousel";` · Category: Data display

#### `<ray-carousel>` (RayCarousel, extends RayElement)

Any child is a slide. With several slides in view, positions are the snap points the viewport can reach. ArrowLeft/Right (Up/Down when vertical), Home and End move it.

Properties:

- `index`: number, default `0`. Current position (0-based). Setting it scrolls there.
- `label`: string, default `Carousel`. Accessible name of the carousel region.
- `slideSize` (attribute `slide-size`): string. Size of each slide along the scroll axis ("100%" by default; "50%", "18rem"…).
- `slideGap` (attribute `slide-gap`): string. Space between slides (default var(--ray-space-4)).
- `align`: `start` | `center`, default `start`, reflects. Where a slide snaps in the viewport.
- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. Scroll axis (vertical needs a height; 20rem by default).
- `loop`: boolean, reflects. next() on the last position goes to the first, prev() on the first to the last.
- `autoplay`: number, default `0`. Milliseconds between automatic moves (0: off). Pauses on hover, focus and when the page is hidden; starts paused with reduced motion. Shows a pause/play button.
- `hideControls` (attribute `hide-controls`): boolean, reflects. No previous/next buttons.
- `hideIndicators` (attribute `hide-indicators`): boolean, reflects. No indicator dots.

Events:

- `change`: The current position changed (read `index`) by the user or a method (controls, indicators, keyboard, swipe, scroll, next/prev/goTo, autoplay) — not when `index` is set by code.

Slots:

- (default): The slides.

Parts (`::part()`):

- `viewport`: The scrolling viewport.
- `previous`: The previous button.
- `next`: The next button.
- `indicators`: The row of indicator dots.
- `indicator`: Each indicator dot ([aria-current] on the active one).
- `play`: The pause/play button (with autoplay).

Methods and properties:

- `next(): void`: Goes to the next position.
- `prev(): void`: Goes to the previous position.
- `goTo(index: number, options?: { instant?: boolean }): void`: Scrolls to a position (smoothly unless instant or reduced motion).
- `readonly count: number`: Number of positions.
- `readonly slides: Element[]`: The slide elements.

### Code

A block of source code: header with file name and language, copy button, line numbers, highlighted lines, diff lines, wrapping and a "show more" height. A small built-in highlighter, or any library through setHighlighter(), painted with the --ray-code-* tokens.

Import: `import "@raylang/elements/code";` · Category: Data display

#### `<ray-code>` (RayCode, extends RayElement)

The code comes from the code property, a <script type="text/plain"> child (raw text: anything but a closing script tag), a <template> child (parsed as HTML: the easiest for markup, but a < that is not a tag, as in Promise<void>, breaks it), or the element's text; common indentation and blank edges are removed (not with verbatim). Built-in languages: js/ts (jsx, tsx), json, html/xml/svg/vue, css, shell, ray and diff; others show as plain text. Library classes painted with the tokens: Prism's .token.*, highlight.js's .hljs-*, and Shiki's css-variables theme.

Properties:

- `code` (property only): string. The code, from script (the most convenient in React and Vue). Wins over the content.
- `language`: string, reflects. The language: js, ts, jsx, tsx, json, html, xml, svg, vue, css, sh, ray, diff… (also shown in the header). Not lang: that is the human language of the text.
- `filename`: string. A file name or title in the header; also the scroll region's accessible name.
- `lineNumbers` (attribute `line-numbers`): boolean, reflects. Numbers each line (not copied, not selectable).
- `highlight`: string. Lines to highlight: "3, 5-7".
- `wrap`: boolean, reflects. Wraps long lines instead of scrolling sideways.
- `verbatim`: boolean, reflects. Shows and copies the text exactly as given: no common indentation or blank first and last lines removed. For data (a response body, a log) rather than code written in the page.
- `maxHeight` (attribute `max-height`): string. Height before it scrolls: px as a number, or a CSS length. A taller block gets a "Show all N lines" button.
- `expanded`: boolean, reflects. Shown whole, past max-height.
- `hideCopy` (attribute `hide-copy`): boolean, reflects. No copy button.
- `hideHeader` (attribute `hide-header`): boolean, reflects. No header bar (the copy button floats in the corner).
- `size`: `xs` | `sm` | `md`, default `sm`, reflects. Font size.
- `radius`: string, reflects. Corner radius: xs…xl, none, or a CSS length. Default: md.
- `copyLabel` (attribute `copy-label`): string, default `Copy code`. Accessible name of the copy button.
- `copiedLabel` (attribute `copied-label`): string, default `Copied`. Shown and announced after copying.

Events:

- `ray-copy` (detail `{ code: string }`): The code was copied.

Slots:

- (default): The code: text, a <template> or a <script type="text/plain">.

Parts (`::part()`):

- `frame`: The box.
- `header`: The bar with the file name, the language and the copy button.
- `copy`: The copy button.
- `scroller`: The scroll box (focusable, to scroll with the keyboard).
- `code`: The <code> with one .line per line.

Methods and properties:

- `readonly source: string`: The code shown (dedented), whatever its source.
- `copy(): Promise<boolean>`: Copies the code; resolves to true when it worked.

Exports (from `@raylang/elements/code` and `@raylang/elements`):

- `function setHighlighter(fn: ((code: string, lang: string) => string | Node | null | undefined | Promise<string | Node | null | undefined>) | null): void`: Hands every ray-code to a highlighter that returns HTML (Prism, highlight.js, Shiki…); null/undefined falls back to the built-in one. The HTML is inserted as is: pass only a trusted highlighter. null restores the built-in one.
- `function tokenize(code: string, lang?: string): [type: string, text: string][]`: The built-in highlighter: tokens of type keyword, string, number, comment, function, type, tag, attr, punctuation or text.

### Icon

An icon of the registry: the whole set (the components' too) changes with setIcons().

Import: `import "@raylang/elements/icon";` · Category: Data display

#### `<ray-icon>` (RayIcon, extends RayElement)

setIcons({ name: '<svg…>' }) replaces or adds icons (SVG markup or an SVGElement, drawn with currentColor); iconNames() lists them. An icon may have a filled version for a state (filled; "<name>:filled" in setIcons; iconNames({ filled: true }) lists them). The components draw roles ("ui.close", "ui.remove", "ui.expand"…; iconAliases()), each its glyph until the app registers the role: setIcons({ "ui.remove": … }) changes only the chips' ×. Sizes follow the font unless size; --ray-icon-size and --ray-icon-stroke tune the whole system.

Properties:

- `name`: `IconName`, reflects. Registered icon name (iconNames()); "none" draws nothing, a blank that keeps the alignment (a menu item without its check).
- `filled`: boolean, reflects. The filled version, for a state (active, selected, favorite, unread); the outline icon when there is none. Built in: user, info, circle-check, alert-triangle, circle-x, folder, bell, star, settings, home, message-circle.
- `mirror`: boolean, reflects. Mirrored in a right-to-left context (dir="rtl"), for an icon that points along the text: back, forward, send, undo. The roles that do (ui.next, ui.previous, ui.first, ui.last, ui.disclosure, ui.separator) mirror by themselves.
- `size`: string, reflects. xs…xl or any CSS length. Default: 1em.
- `label`: string. Accessible name; without it the icon is decorative (hidden from screen readers).
- `color`: string, reflects. A palette color or any CSS color. Default: the text color.
- `stroke`: number. Stroke width for stroke icons (default: --ray-icon-stroke, 2).

Parts (`::part()`):

- `icon`: The icon box.

Types:

- `"close" | "check" | "minus" | "plus" | "chevron-down" | "chevron-up" | "chevron-right" | "chevron-left" | "chevrons-left" | "chevrons-right" | "search" | "arrow-up-right" | "arrow-down-right" | "sun" | "moon" | "monitor" | "user" | "info" | "circle-check" | "alert-triangle" | "circle-x" | "menu" | "more-horizontal" | "file" | "folder" | "pause" | "play" | "terminal" | "calendar" | "image" | "download" | "eye" | "eye-off" | "bell" | "copy" | "quote" | "pipette" | "star" | "upload" | "paperclip" | "panel-left" | "settings" | "home" | "arrow-left" | "message-circle" | "none" | (string & {})`: An icon name: one of the default set, or any name an app registers with setIcons().

### Indicator

A dot or a small label on the edge of any element (Mantine's Indicator): "New" on an avatar, an unread count on a bell, an online dot. Nine positions, an inward offset, palette or CSS colors, a border and a live pulse.

Import: `import "@raylang/elements/indicator";` · Category: Data display

#### `<ray-indicator>` (RayIndicator, extends RayElement)

Wraps its content as tight as it is (fit-content). The label is part of the element's text for assistive technology; a dot has none: describe it on the content (aria-label="Grace, online").

Properties:

- `label`: string. Text in the indicator (a word or a count). Empty: a dot.
- `position`: `top-start` | `top-center` | `top-end` | `middle-start` | `middle-center` | `middle-end` | `bottom-start` | `bottom-center` | `bottom-end`, default `top-end`, reflects. Which point of the content's box it sits on.
- `offset`: `string | number`. Moves it inward from that point: px as a number, or a CSS length. Use it on round content (an avatar), so it sits on the curve.
- `color`: string, reflects. A palette color or any CSS color. Default: the primary.
- `size`: `string | number`. Diameter of the dot (and minimum height of a label): px as a number, or a CSS length. Default: 10px.
- `radius`: string, reflects. Corner radius: xs…xl, none, or a CSS length. Default: round.
- `max`: number. A numeric label above it shows as max+ (99+).
- `inline`: boolean, reflects. inline-block, to sit within a line of text.
- `withBorder` (attribute `with-border`): boolean, reflects. A ring in the background color, to separate it from the content.
- `processing`: boolean, reflects. A pulse around it (live, recording, syncing).
- `disabled`: boolean, reflects. Hides the indicator (the content stays).

Slots:

- (default): The element the indicator sits on.

Parts (`::part()`):

- `indicator`: The dot or label.

### Kbd

A keyboard key: a raised keycap, or a flat chip (filled or outline) for hints in menus and buttons.

Import: `import "@raylang/elements/kbd";` · Category: Data display

#### `<ray-kbd>` (RayKbd, extends RayElement)

Properties:

- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Font size.
- `variant`: `default` | `filled` | `outline`, default `default`, reflects. default: raised keycap; filled: flat muted chip; outline: flat with a border.

Slots:

- (default): The key name.

Parts (`::part()`):

- `kbd`: The inner <kbd>.

### Stat

A metric tile: label, value, change against a previous period, note.

Import: `import "@raylang/elements/stat";` · Category: Data display

#### `<ray-stat>` (RayStat, extends RayElement)

Properties:

- `label`: string. What is measured.
- `value`: string. The figure, already formatted.
- `diff`: number. Change (positive is shown as good, in green; see inverse).
- `diffUnit` (attribute `diff-unit`): string, default `%`. Unit of diff.
- `note`: string. A line under the value (compared to…).
- `inverse`: boolean, reflects. Lower is better (errors, latency): negative diffs are green.
- `plain`: boolean, reflects. Without the card around.

Slots:

- `icon`: Icon next to the label.
- (default): Extra content (e.g. a ray-progress).

### Table

A data table from columns and data: sorting (aria-sort), row selection, clickable rows, sticky header, striped, empty state. Plain HTML tables: the .ray-table class of base.css.

Import: `import "@raylang/elements/table";` · Category: Data display

#### `<ray-table>` (RayTable, extends RayElement)

Cells are text (render may return a DOM node; strings are never parsed as HTML). The scroll height comes from --ray-table-max-height.

Properties:

- `columns` (property only): `TableColumn[]`. Columns: key, label, width, align, sortable, render(row, index), sort(a, b).
- `data` (property only): `any[]`. Rows (objects).
- `rowKey` (attribute `row-key`): string, default `id`. Field that identifies a row (selection).
- `selectable`: boolean, reflects. A checkbox per row and a select-all checkbox.
- `selection` (property only): `unknown[]`. Keys of the selected rows.
- `sort` (property only): `TableSort | null`. Current sort; set it, or let header clicks change it.
- `manualSort` (attribute `manual-sort`): boolean. Do not sort here: listen to ray-sort and pass sorted data.
- `clickableRows` (attribute `clickable-rows`): boolean, reflects. Rows are focusable and fire ray-row-click (Enter too; arrows move between rows).
- `striped`: boolean, reflects. Alternate row background.
- `withBorder` (attribute `with-border`): boolean, reflects. Border around the table.
- `withColumnBorders` (attribute `with-column-borders`): boolean, reflects. Borders between columns.
- `stickyHeader` (attribute `sticky-header`): boolean, reflects. The header stays visible while scrolling (with --ray-table-max-height).
- `noHover` (attribute `no-hover`): boolean, reflects. No row highlight on hover.
- `density`: `xs` | `sm` | `md` | `lg`, default `sm`, reflects. Cell padding.
- `label`: string. Caption (also the table's accessible name).
- `emptyLabel` (attribute `empty-label`): string, default `No data`. Text without rows (or put a ray-empty-state in slot=empty).

Events:

- `ray-sort` (detail `{ key: string; direction: "asc" | "desc" | null }`): A header changed the sort.
- `ray-selection-change` (detail `{ selection: unknown[] }`): The selection changed.
- `ray-row-click` (detail `{ row: any; index: number }`): A row was clicked or activated with Enter (clickable-rows).

Slots:

- `empty`: Shown instead of the empty text when there are no rows.

Parts (`::part()`):

- `table`: The <table>.
- `scroll`: The scroll container.

Methods and properties:

- `readonly rows: any[]`: The rows in display order.

Types:

- `{ key: string; label?: string; width?: number | string; align?: "left" | "center" | "right"; sortable?: boolean; render?: (row: any, index: number) => string | number | Node | null | undefined; sort?: (a: any, b: any) => number }`: A column of ray-table.
- `{ key: string; direction: "asc" | "desc" }`: The sort state of ray-table.

### Timeline

Events in order along a line (Mantine's Timeline): activity, history, a deploy's stages. Items up to active are reached (filled bullet, colored line); a bullet is a dot, an icon or an avatar.

Import: `import "@raylang/elements/timeline";` · Category: Data display

#### `<ray-timeline>` (RayTimeline, extends RayElement)

A list (role="list") of ray-timeline-item.

Properties:

- `active`: number, default `-1`, reflects. Index of the last reached item (-1: none).
- `align`: `start` | `end` | `left` | `right`, default `start`, reflects. Side of the line: start/end follow the writing direction; left/right are sides of the screen.
- `bulletSize` (attribute `bullet-size`): string. Bullet size: px as a number or a CSS length (default 20px).
- `lineWidth` (attribute `line-width`): number. Line width in px (default 2).
- `color`: string, reflects. A palette color or any CSS color for what is reached (default: primary).
- `reverseActive` (attribute `reverse-active`): boolean, reflects. Counts active from the end (the latest event at the top).

Slots:

- (default): ray-timeline-item elements.

Methods and properties:

- `readonly items: RayTimelineItem[]`: The items, in order.

#### `<ray-timeline-item>` (RayTimelineItem, extends RayElement)

Properties:

- `label`: string. The title of the event.
- `time`: string. When ("2 h ago", a date).
- `icon`: `IconName`. An icon of the registry in the bullet.
- `color`: string, reflects. Its own color (a failed step in red).
- `lineVariant` (attribute `line-variant`): `solid` | `dashed` | `dotted`, default `solid`, reflects. The line to the next item (dashed: not happened yet).

Slots:

- (default): Details under the title.
- `bullet`: A custom bullet (an avatar, an image).

Parts (`::part()`):

- `bullet`: The bullet.
- `line`: The line to the next item.
- `body`: Title, details and time.
- `title`: The title.
- `time`: The time.

### Alert

An inline message: title, text, an icon of the registry, the color variants and an optional close button.

Import: `import "@raylang/elements/alert";` · Category: Feedback

#### `<ray-alert>` (RayAlert, extends RayElement)

Announced as an alert. The icon follows the color (info, circle-check, alert-triangle, circle-x) unless icon or slot=icon.

Properties:

- `label`: string. Title.
- `color`: string, reflects. A palette color or any CSS color.
- `variant`: `light` | `filled` | `outline` | `default` | `transparent`, default `light`, reflects. Visual style.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl`. Corner radius.
- `icon`: `IconName`, reflects. A registered icon name, or none.
- `closable`: boolean, reflects. A close button; closing hides the alert (cancel ray-close to keep it).
- `closeLabel` (attribute `close-label`): string, default `Dismiss`. Accessible name of the close button.

Events:

- `ray-close`: The close button was pressed; cancelable.

Slots:

- (default): Text.
- `icon`: A custom icon.

Parts (`::part()`):

- `alert`: The box.
- `close`: The close button.

### Empty state

What a list, table or pane shows when it is empty: icon, title, text and the action that fills it.

Import: `import "@raylang/elements/empty-state";` · Category: Feedback

#### `<ray-empty-state>` (RayEmptyState, extends RayElement)

Properties:

- `label`: string. Title.
- `compact`: boolean, reflects. Less padding.
- `withBorder` (attribute `with-border`): boolean, reflects. Dashed border.

Slots:

- (default): Text.
- `icon`: Icon, shown in a circle.
- `actions`: Buttons.

### Notification

Toasts: notify(), updateNotification(), hideNotification(), clearNotifications(); shown in a ray-toaster (a polite live region in the top layer). ray-notification is usable on its own.

Import: `import "@raylang/elements/notification";` · Category: Feedback

#### `<ray-notification>` (RayNotification, extends RayElement)

notify({ id, title, message, color, icon, loading, autoClose (ms, default 4000; false = stays), closable, withBorder, onClose }) returns its id. A color adds a status icon in that color: green/teal a check, red/pink an error, yellow/orange a warning, others info. The status icon and the loader are 1.5rem with a 1.5 stroke; set --ray-notification-icon-size and --ray-notification-icon-stroke to change them.

Properties:

- `label`: string. Title.
- `color`: string, reflects. Status color: tints the status icon (and a slotted icon's circle).
- `icon`: `IconName`. Status icon from the registry (default: from the color); "none" for no icon.
- `loading`: boolean, reflects. Shows a spinner (notify() does not auto-close it).
- `hideClose` (attribute `hide-close`): boolean, reflects. No close button.
- `withBorder` (attribute `with-border`): boolean, reflects. Draws a border.
- `actionLabel` (attribute `action-label`): string. Text of an action button (e.g. "Undo"); pressing it fires ray-action.

Events:

- `ray-close`: The close button was pressed.
- `ray-action`: The action button was pressed (notify() runs action.onClick and closes it).

Slots:

- (default): Message.
- `icon`: Your own icon, in a colored circle (replaces the status icon).

Parts (`::part()`):

- `status-icon`: The status icon.

#### `<ray-toaster>` (RayToaster, extends RayElement)

Created by notify() when missing; add one yourself to choose its position. A stack (newest in front, older ones peeking behind) that spreads into a list on hover or keyboard focus; on touch screens a tap expands it, a tap outside collapses it, and a sideways swipe dismisses a toast. Auto-close pauses while expanded. Full width on phones.

Properties:

- `position`: `bottom-end` | `bottom-start` | `bottom-center` | `top-end` | `top-start` | `top-center` | `bottom-right` | `bottom-left` | `top-right` | `top-left`, default `bottom-end`, reflects. Corner of the stack: -start/-end follow the writing direction; -left/-right are sides of the screen.
- `limit`: number, default `5`. Maximum kept; the oldest go first.
- `visible`: number, default `3`. Toasts shown in the collapsed stack (the rest wait, hidden).
- `expand`: boolean, reflects. Always expanded: a list instead of a stack.
- `gap`: number, default `12`. Pixels between toasts when expanded.

Methods and properties:

- `expanded: boolean`: Whether the stack is spread out (set it to expand or collapse it).
- `layout(): void`: Places the toasts again (done automatically on changes).
- `raise(): void`: Brings the stack above everything else in the top layer.

Exports (from `@raylang/elements/notification` and `@raylang/elements`):

- `function notify(options?: NotifyOptions): string`: Shows a notification; returns its id.
- `function updateNotification(id: string, options?: NotifyOptions): boolean`: Changes a shown notification and restarts its auto-close.
- `function hideNotification(id: string): boolean`: Removes a notification.
- `function clearNotifications(): void`: Removes every notification.
- `function statusIcon(color: string): string`: The status icon a color gets: circle-check, circle-x, alert-triangle or info.

Types:

- `{ id?: string; title?: string; message?: string; color?: string; icon?: string; loading?: boolean; autoClose?: number | false; closable?: boolean; withBorder?: boolean; action?: { label: string; onClick?: () => void }; onClose?: () => void }`: Options of notify() and updateNotification().

### Progress

A determinate or (without value) indeterminate progress bar, announced as a progressbar.

Import: `import "@raylang/elements/progress";` · Category: Feedback

#### `<ray-progress>` (RayProgress, extends RayElement)

Properties:

- `value`: number. Progress, from 0 to max. Unset: indeterminate.
- `max`: number, default `100`. The value of a full bar.
- `color`: string, reflects. A palette color or any CSS color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `md`, reflects. Bar height.
- `radius`: `xs` | `sm` | `md` | `lg` | `xl` | `full`. Corner radius. Default: full.
- `striped`: boolean, reflects. Diagonal stripes.
- `animated`: boolean, reflects. Moving stripes (with striped).
- `showValue` (attribute `show-value`): boolean, reflects. Shows the percentage: inside the bar on lg and xl, beside it on smaller sizes.
- `label`: string. Accessible name (default: Progress).

Parts (`::part()`):

- `track`: The background track.
- `bar`: The filled bar.
- `value`: The percentage beside the bar (show-value on xs, sm, md).

### Ring progress

Progress as a ring (Mantine's RingProgress), with content in the middle: a countdown, a goal, an upload. Announced as a progressbar.

Import: `import "@raylang/elements/ring-progress";` · Category: Feedback

#### `<ray-ring-progress>` (RayRingProgress, extends RayElement)

The arc starts at 12 o'clock and runs clockwise; a countdown is a value that goes down. Without value it spins (indeterminate). The middle holds the default slot (a clock), or the percentage with show-value.

Properties:

- `value`: number. Progress, from 0 to max. Unset: indeterminate (a spinning arc).
- `max`: number, default `100`. The value of a full ring.
- `color`: string, reflects. A palette color or any CSS color. Default: the primary color.
- `size`: `"xs" | "sm" | "md" | "lg" | "xl" | (string & {})`, default `md`, reflects. Diameter: xs…xl (3, 5, 7.5, 10, 12.5rem) or any CSS length.
- `thickness`: string, reflects. Width of the ring: a CSS length (a bare number is px). Default: a tenth of the diameter.
- `roundCaps` (attribute `round-caps`): boolean, reflects. Rounded ends of the arc.
- `showValue` (attribute `show-value`): boolean, reflects. Shows the percentage in the middle (when the default slot is empty).
- `label`: string. Accessible name (default: Progress).

Slots:

- (default): The middle of the ring (a clock, a figure, an icon); its font scales with size.

Parts (`::part()`):

- `track`: The background circle.
- `bar`: The arc.
- `center`: The middle, around the default slot.

### Skeleton

A placeholder while content loads: a shimmering block, a circle or text lines; with loaded it shows its content.

Import: `import "@raylang/elements/skeleton";` · Category: Feedback

#### `<ray-skeleton>` (RaySkeleton, extends RayElement)

aria-busy="true" on the host while loading; the placeholder is aria-hidden.

Properties:

- `width`: string. Width (CSS length, a number is px). Default: 100% (a circle: 2.5rem).
- `height`: string. Height of a block or of each line (CSS length, a number is px). Default: 1rem.
- `circle`: boolean, reflects. A circle (avatar placeholder): its diameter is width, else height.
- `lines`: number, reflects. Number of text lines (the last one is shorter).
- `radius`: string, reflects. Corner radius: xs…xl, full or a CSS length. Default: sm.
- `animation`: `shimmer` | `pulse` | `none`, default `shimmer`, reflects. The loading effect (always none with reduced motion).
- `loaded`: boolean, reflects. Shows the slotted content instead of the placeholder.

Slots:

- (default): The real content, shown with loaded.

Parts (`::part()`):

- `skeleton`: The placeholder container.
- `bone`: Each block or line.

### Spinner

An indeterminate loading indicator, announced as a status.

Import: `import "@raylang/elements/spinner";` · Category: Feedback

#### `<ray-spinner>` (RaySpinner, extends RayElement)

Properties:

- `color`: string. A palette color or any CSS color. Default: the primary color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `md`, reflects. Diameter.
- `label`: string, default `Loading`. Text read by screen readers.

Parts (`::part()`):

- `spinner`: The ring.

### Step dots

A row of dots, one per step: done, current, to do. A compact progress for rounds, onboarding pages or a quiz; announced as a progressbar ("Round 4 of 12").

Import: `import "@raylang/elements/step-dots";` · Category: Feedback

#### `<ray-step-dots>` (RayStepDots, extends RayElement)

Dots before value are done (filled), the one at value is current (a filled pill), the rest are to do (empty). Not interactive: for steps the user picks, use ray-stepper (or the dots of ray-carousel). Many dots wrap onto more lines.

Properties:

- `count`: number, default `0`. Number of steps (dots).
- `value`: number, default `0`. The current step, 0-based; count means every step is done.
- `color`: string, reflects. A palette color or any CSS color for done and current dots. Default: the primary color.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Size of a dot.
- `align`: `start` | `center` | `end`, default `center`, reflects. Where the row sits in its width.
- `label`: string. What a step is called: "Round" is announced "Round 4 of 12" and names the element. Default: Step (named Steps). In another language, use value-text.
- `valueText` (attribute `value-text`): string. The announced text, {step} (the current one, from 1) and {count} replaced, numbers in the page's language: value-text="Asalto {step} de {count}". Default: "<label> {step} of {count}".
- `doneText` (attribute `done-text`): string. The announced text once every step is done (value = count), with {count}. Default: value-text, else "{count} of {count}, done".

Parts (`::part()`):

- `dots`: The row.
- `dot`: Each dot ([data-state] done, current or todo).

### App bar

The top bar of a phone screen (Material's top app bar, the iOS navigation bar): back or menu, a title and subtitle, actions, and an optional row under it. It elevates once the content scrolls, or hides while scrolling down.

Import: `import "@raylang/elements/app-bar";` · Category: Layout

#### `<ray-app-bar>` (RayAppBar, extends RayElement)

It follows the scroller of its ray-app-shell, else scroll-target, else the window; clear of the notch (safe-area inset). The title is plain text: put a heading in the default slot when the page needs one.

Properties:

- `label`: string. The title.
- `description`: string. A line under the title.
- `center`: boolean, reflects. The title centered (iOS).
- `variant`: `default` | `filled` | `transparent`, default `default`, reflects. default: the page background; filled: the primary color; transparent: until it elevates.
- `size`: `sm` | `md` | `lg`, default `md`, reflects. Height: 48, 56 or 64 px.
- `scrollBehavior` (attribute `scroll-behavior`): `elevate` | `hide` | `none`, default `elevate`, reflects. While the content scrolls: elevate (border and shadow), hide (also slides away going down, back going up), none.
- `sticky`: boolean, reflects. Sticks to the top of the window (outside a shell).
- `scrollTarget` (attribute `scroll-target`): string. A selector of the element whose scrolling it follows (default: its shell's, else the window).

Slots:

- (default): Title content after the label (a heading, a select).
- `start`: Before the title: back or menu button.
- `end`: Actions.
- `bottom`: A row under the bar: tabs, a search field.

Parts (`::part()`):

- `bar`: The bar.
- `start`: The start area.
- `title`: The title area.
- `end`: The actions area.
- `bottom`: The row under the bar.

Methods and properties:

- `readonly concealed: boolean`: Whether scroll-behavior="hide" has slid it away.

### App shell

The frame of an app (Mantine's AppShell): header, navbar, main, aside and footer on wide screens; on phones one column with a bottom bar. The main content scrolls, the bars stay.

Import: `import "@raylang/elements/app-shell";` · Category: Layout

#### `<ray-app-shell>` (RayAppShell, extends RayElement)

The layout follows the shell's own width (a phone-sized frame shows the phone layout). Below breakpoint the navbar and the aside take no room (a ray-sidebar there still opens as its drawer) and the bottom slot shows. It fills the window's height (100dvh) unless sized. In a std/ui full_content window (ray-elements/core/raylang.js) the header becomes the title bar: room for the window buttons, and it drags the window; with layout="alt" or no header, the navbar and main start below it.

Properties:

- `layout`: `default` | `alt`, default `default`, reflects. default: the header across the top; alt: the navbar full height, the header beside it.
- `breakpoint`: string, default `48em`. Width (px, em or rem) below which it takes the phone layout.
- `padding`: string, reflects. Padding of the main area: xs…xl, a number (px) or a CSS length.

Events:

- `ray-breakpoint` (detail `{ mobile: boolean }`): It switched between the wide and the phone layout.

Slots:

- (default): The main content (it scrolls).
- `header`: Top bar: a ray-app-bar or a header of your own.
- `navbar`: Side navigation (a ray-sidebar). Wide screens only.
- `aside`: A panel on the other side (details, an inspector). Wide screens only.
- `footer`: Under the main content.
- `bottom`: Phones only: a ray-bottom-nav.

Parts (`::part()`):

- `shell`: The grid.
- `header`: The header area.
- `navbar`: The navbar area.
- `main`: The scrolling main area.
- `aside`: The aside area.
- `footer`: The footer area.
- `bottom`: The bottom bar area.

Methods and properties:

- `readonly scroller: HTMLElement`: The element that scrolls the main content.
- `readonly mobile: boolean`: Whether it is in the phone layout.

#### In a raylang app

In a `std/ui` window opened as `full_content` (the page under a transparent title bar, macOS), with [the native bridge](https://elements.raylang.dev/raylang.html#using-the-bridge), the header becomes the title bar: at least as tall, with room for the window buttons, and dragging it moves the window (buttons in it stay buttons). With `layout="alt"` or without a header, the navbar and the main content start below the title bar.

```ray
var o = ui.options(1100, 720);
o.kind = "full_content";
let h = ui.open_with("Builds", "ray://app/index.html", o)?;
```

The bridge also keeps the window's background and title bar in the theme's background, so switching to dark, resizing or reopening never flashes the other theme.

### Aspect ratio

A box with a fixed width/height ratio; its image, video or iframe fills it.

Import: `import "@raylang/elements/aspect-ratio";` · Category: Layout

#### `<ray-aspect-ratio>` (RayAspectRatio, extends RayElement)

Properties:

- `ratio`: string, default `16/9`, reflects. Width/height: "16/9", "4:3", "1" or a number.
- `fit`: `cover` | `contain`, default `cover`, reflects. How the media fills the box (object-fit).
- `radius`: string, reflects. Corner radius: xs…xl, full or a CSS length.

Slots:

- (default): The media (img, video, iframe or any element); it fills the box.

Exports (from `@raylang/elements/aspect-ratio` and `@raylang/elements`):

- `function parseRatio(value: string | number): string | null`: A ratio ("16/9", "4:3", 1.5) as a CSS aspect-ratio value, or null.

### Card

A surface for grouped content, with optional media, header and footer.

Import: `import "@raylang/elements/card";` · Category: Layout

#### `<ray-card>` (RayCard, extends RayElement)

Properties:

- `padding`: `0` | `xs` | `sm` | `md` | `lg` | `xl`, default `md`, reflects. Inner spacing (named space scale).
- `radius`: `xs` | `sm` | `md` | `lg` | `xl`. Corner radius. Default: --ray-radius-default.
- `shadow`: `xs` | `sm` | `md` | `lg` | `xl`. Elevation.
- `withBorder` (attribute `with-border`): boolean. Draws a border.
- `variant`: `default` | `filled` | `outline`, default `default`, reflects. default: card surface; filled: muted surface; outline: border without fill.

Slots:

- (default): The body.
- `media`: Full-bleed image or media at the top.
- `header`: Header content.
- `footer`: Footer content (actions).

Parts (`::part()`):

- `card`: The surface.
- `header`: The header area.
- `body`: The body area.
- `footer`: The footer area.

### Center

Its content centered on both axes (Mantine's Center): empty states, loaders, a sign-in card.

Import: `import "@raylang/elements/center";` · Category: Layout

#### `<ray-center>` (RayCenter, extends RayElement)

It fills its parent's width; give it a height (or a flex or grid parent that stretches it) to center vertically.

Properties:

- `inline`: boolean, reflects. As wide as its content (inline-flex): an icon beside text.

Slots:

- (default): The content.

### Container

Its content centered, up to a maximum width, with side padding (Mantine's Container): the column of a page.

Import: `import "@raylang/elements/container";` · Category: Layout

#### `<ray-container>` (RayContainer, extends RayElement)

Properties:

- `size`: string, default `md`, reflects. Maximum width: xs 540px, sm 720px, md 960px, lg 1140px, xl 1320px, or any CSS length.
- `padding`: string, default `md`, reflects. Side padding: xs…xl, a number (px) or a CSS length.
- `fluid`: boolean, reflects. No maximum width: the whole width, still padded.

Slots:

- (default): The content.

Exports (from `@raylang/elements/container` and `@raylang/elements`):

- `const CONTAINER_SIZES: { xs: string; sm: string; md: string; lg: string; xl: string }`: The maximum widths of size.

### Grid

A responsive grid: a column count per width (cols="1 sm:2 lg:4") measured on the grid itself, or as many columns of a minimum width as fit. Children span columns with data-span.

Import: `import "@raylang/elements/grid";` · Category: Layout

#### `<ray-grid>` (RayGrid, extends RayElement)

The widths are the grid's own (container queries: xs 36em, sm 48em, md 62em, lg 75em, xl 88em), so a grid in a narrow column or a phone frame drops to fewer columns. It needs a width from its parent: in a flex row give it one or let it grow. A child spans with data-span="2"…"12" or "full".

Properties:

- `cols`: string, default `1`, reflects. Columns: a count, then counts from a width up ("1 sm:2 lg:4").
- `minColWidth` (attribute `min-col-width`): string. Instead of cols: as many columns of at least this width as fit ("14rem", 220).
- `gap`: string, default `md`, reflects. Space between cells: xs…xl, a number (px) or a CSS length.
- `rowGap` (attribute `row-gap`): string. Space between rows when it differs from gap.
- `align`: `stretch` | `start` | `center` | `end`, default `stretch`, reflects. Vertical alignment of the cells in a row.

Slots:

- (default): The cells (data-span="2" or "full" to span).

Parts (`::part()`):

- `grid`: The grid element.

Exports (from `@raylang/elements/grid` and `@raylang/elements`):

- `function parseCols(value: string | number | undefined): { base?: number; xs?: number; sm?: number; md?: number; lg?: number; xl?: number }`: "1 sm:2 lg:4" as counts per width.
- `const BREAKPOINTS: { xs: string; sm: string; md: string; lg: string; xl: string }`: The widths of cols (36em, 48em, 62em, 75em, 88em).

### Group

Its children in a row (Mantine's Group): spaced by the space scale, centered, wrapping when they do not fit. Toolbars, form actions, chips.

Import: `import "@raylang/elements/group";` · Category: Layout

#### `<ray-group>` (RayGroup, extends RayElement)

A flex row on the host: the children are laid out directly, no wrapper.

Properties:

- `gap`: string, default `md`, reflects. Space between children: xs…xl (the space scale), a number (px) or any CSS length.
- `align`: `center` | `start` | `end` | `stretch` | `baseline`, default `center`, reflects. Cross-axis alignment.
- `justify`: `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`, default `start`, reflects. Main-axis distribution: space-between for a title on one side and actions on the other.
- `nowrap`: boolean, reflects. Keeps the children on one line.
- `grow`: boolean, reflects. The children share the width equally.

Slots:

- (default): The children.

### Scroll area

A box that scrolls its content with the native scrolling and a thin themed scrollbar (Mantine's ScrollArea). Edge shadows tell there is more; ray-reach-end fires at the end (load the next page).

Import: `import "@raylang/elements/scroll-area";` · Category: Layout

#### `<ray-scroll-area>` (RayScrollArea, extends RayElement)

Give it a size: height, max-height, CSS, or a flex/grid parent. The scrolling box is focusable (keyboard scrolling); name it with label when it holds a region of its own.

Properties:

- `height`: string. Height (CSS length).
- `maxHeight` (attribute `max-height`): string. Maximum height: it grows with its content up to this, then scrolls.
- `orientation`: `vertical` | `horizontal` | `both`, default `vertical`, reflects. Which ways it scrolls.
- `type`: `auto` | `hover` | `never`, default `auto`, reflects. The scrollbar: auto (when it scrolls), hover (while hovered or scrolling), never (still scrolls).
- `noShadows` (attribute `no-shadows`): boolean, reflects. No edge shadows.
- `threshold`: number, default `48`. Distance from the end (px) at which ray-reach-end fires.
- `label`: string. Accessible name: makes the scrolling box a named region.

Events:

- `ray-reach-end` (detail `{ edge: "bottom" | "right" | "left" }`): The end came within threshold (once per arrival): the bottom, or the right when horizontal (the left right to left).

Slots:

- (default): The content.

Parts (`::part()`):

- `viewport`: The scrolling box.
- `shadow`: The edge shadows.

Methods and properties:

- `readonly viewport: HTMLElement`: The scrolling element (scrollTop, scrollTo…).
- `scrollToStart(options?: { behavior?: ScrollBehavior }): void`: Scrolls to the start: the top, or the left when horizontal (the right right to left).
- `scrollToEnd(options?: { behavior?: ScrollBehavior }): void`: Scrolls to the end: the bottom, or the right when horizontal (the left right to left).

### Separator

A horizontal or vertical rule, optionally labeled (Mantine's Divider).

Import: `import "@raylang/elements/separator";` · Category: Layout

#### `<ray-separator>` (RaySeparator, extends RayElement)

Properties:

- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. Direction of the rule.
- `label`: string, reflects. Text in the middle of a horizontal rule.
- `labelPosition` (attribute `label-position`): `start` | `center` | `end` | `left` | `right`, default `center`, reflects. Where the label sits: start/end follow the writing direction; left/right are sides of the screen.
- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `xs`, reflects. Thickness (1–5px).
- `variant`: `solid` | `dashed` | `dotted`, default `solid`, reflects. Line style.

Parts (`::part()`):

- `line`: The rule without label.
- `label`: The labeled rule.

### Split

Two panes with a draggable, keyboard-accessible divider (window splitter pattern); the size can be remembered.

Import: `import "@raylang/elements/split";` · Category: Layout

#### `<ray-split>` (RaySplit, extends RayElement)

Divider keys: arrows move it (Shift: faster), Home/End go to min/max, Enter or double click collapse the start pane.

Properties:

- `orientation`: `horizontal` | `vertical`, default `horizontal`, reflects. horizontal: side by side; vertical: stacked.
- `position`: string, default `50%`. Initial size of the start pane: px (280) or any CSS length (30%, 20rem).
- `min`: number, default `0`. Minimum size of the start pane in px.
- `max`: number. Maximum size of the start pane in px.
- `collapsed`: boolean, reflects. The start pane is hidden.
- `disabled`: boolean, reflects. The divider cannot be moved.
- `autosave`: string. A key: the size and the collapsed state are saved in localStorage and restored (a saved state wins over the collapsed attribute).

Events:

- `ray-resize` (detail `{ size: number; collapsed: boolean }`): After a drag, a key or a collapse.

Slots:

- `start`: The sized pane (sidebar).
- `end`: The pane that takes the rest.

Parts (`::part()`):

- `divider`: The separator.
- `start`: The start pane.
- `end`: The end pane.

Methods and properties:

- `readonly size: number`: The start pane's size in px.
- `toggle(): void`: Collapses or restores the start pane.

### Stack

Its children in a column, spaced by the space scale (Mantine's Stack): forms, panels, anything stacked.

Import: `import "@raylang/elements/stack";` · Category: Layout

#### `<ray-stack>` (RayStack, extends RayElement)

A flex column on the host: the children are laid out directly, no wrapper.

Properties:

- `gap`: string, default `md`, reflects. Space between children: xs…xl (the space scale), a number (px) or any CSS length.
- `align`: `stretch` | `start` | `center` | `end` | `baseline`, default `stretch`, reflects. Cross-axis alignment: stretch fills the width.
- `justify`: `start` | `center` | `end` | `space-between` | `space-around` | `space-evenly`, default `start`, reflects. Main-axis distribution (with a height to distribute).

Slots:

- (default): The children.

Exports (from `@raylang/elements/stack` and `@raylang/elements`):

- `function applyFlex(el: HTMLElement, options: { gap?: string; align?: string; justify?: string }, alignDefault: string): void`: Gap, align and justify of a stack or group onto an element's custom properties (for a layout component of your own).

### Status bar

The bar at the bottom of an app window: items on the left and on the right; items with action are buttons.

Import: `import "@raylang/elements/statusbar";` · Category: Layout

#### `<ray-statusbar>` (RayStatusbar, extends RayElement)

Properties:

- `variant`: `default` | `accent`, default `default`, reflects. accent: the primary color (e.g. while debugging).

Slots:

- (default): Items on the left.
- `right`: Items on the right.

#### `<ray-statusbar-item>` (RayStatusbarItem, extends RayElement)

Properties:

- `action`: boolean, reflects. A button (listen to click).
- `color`: string, reflects. Text color (red for errors…).
- `label`: string. Accessible name and tooltip (for icon-only or terse items).

Slots:

- (default): Text.
- `icon`: Icon.

### Theme toggle

Icon button that cycles the document theme: system, light, dark.

Import: `import "@raylang/elements/theme-toggle";` · Category: Theme

#### `<ray-theme-toggle>` (RayThemeToggle, extends RayElement)

Properties:

- `size`: `xs` | `sm` | `md` | `lg` | `xl`, default `sm`, reflects. Control height.

Events:

- `ray-theme-change` (detail `{ theme: "light" | "dark" | "system"; resolved: "light" | "dark"; primary: string | null }`): Fired on the document root by setTheme(); detail: { theme, resolved, primary }.

Parts (`::part()`):

- `button`: The inner button.

## Tokens

Use them as `var(--ray-…)` in your own CSS. Values are resolved; the semantic ones change with the theme (light / dark).

- Palette: `--ray-<color>-0` (lightest) … `--ray-<color>-9` (darkest), colors `dark`, `gray`, `red`, `pink`, `violet`, `indigo`, `blue`, `cyan`, `teal`, `green`, `yellow`, `orange`. The same in both themes.
- Per color and for `primary`: `--ray-<color>-<variant>`, variants `filled`, `filled-hover`, `light`, `light-hover`, `light-color`, `outline`, `outline-hover`, `contrast`; theme-aware.
- Primary: `--ray-primary-0` … `-9` and its variants, aliases of the primary color (`blue`; `data-primary` or `setPrimary()` changes it).

base:

- `--ray-white`: #ffffff
- `--ray-black`: #000000

semantic:

- `--ray-background`: #ffffff / #141414
- `--ray-foreground`: #212529 / #f1f3f5
- `--ray-card`: #ffffff / #1f1f1f
- `--ray-card-foreground`: #212529 / #f1f3f5
- `--ray-popover`: #ffffff / #1f1f1f
- `--ray-popover-foreground`: #212529 / #f1f3f5
- `--ray-primary`: #1971c2
- `--ray-primary-hover`: #1864ab
- `--ray-primary-foreground`: #ffffff
- `--ray-secondary`: #f1f3f5 / #2e2e2e
- `--ray-secondary-hover`: #e9ecef / #3b3b3b
- `--ray-secondary-foreground`: #212529 / #f1f3f5
- `--ray-default`: #ffffff / color-mix(in srgb, #ffffff 3%, transparent)
- `--ray-default-hover`: #f1f3f5 / color-mix(in srgb, #ffffff 7%, transparent)
- `--ray-raised`: #ffffff / #424242
- `--ray-muted`: #f8f9fa / #2e2e2e
- `--ray-muted-foreground`: color-mix(in srgb, #495057 50%, #868e96) / color-mix(in srgb, #b8b8b8 75%, #828282)
- `--ray-accent`: #f1f3f5 / #2e2e2e
- `--ray-accent-foreground`: #212529 / #f1f3f5
- `--ray-destructive`: #c92a2a
- `--ray-destructive-hover`: color-mix(in srgb, #c92a2a 85%, #000000)
- `--ray-destructive-foreground`: #ffffff
- `--ray-success`: color-mix(in srgb, #2b8a3e 80%, #000000) / #51cf66
- `--ray-warning`: color-mix(in srgb, #e67700 62%, #000000) / #fcc419
- `--ray-info`: color-mix(in srgb, #0b7285 90%, #000000) / #3bc9db
- `--ray-border`: #dee2e6 / #2e2e2e
- `--ray-input`: #ced4da / #3b3b3b
- `--ray-ring`: color-mix(in srgb, #228be6 55%, transparent) / color-mix(in srgb, #4dabf7 60%, transparent)
- `--ray-overlay`: color-mix(in srgb, #000000 10%, transparent) / color-mix(in srgb, #000000 50%, transparent)
- `--ray-overlay-border`: color-mix(in srgb, #000000 16%, transparent) / color-mix(in srgb, #ffffff 14%, transparent)
- `--ray-selection`: color-mix(in srgb, #228be6 22%, transparent) / color-mix(in srgb, #4dabf7 30%, transparent)

chart:

- `--ray-chart-1`: #228be6 / #339af0
- `--ray-chart-2`: #e8590c / #fd7e14
- `--ray-chart-3`: #099268 / #20c997
- `--ray-chart-4`: #7950f2 / #845ef7
- `--ray-chart-5`: #e64980 / #f06595
- `--ray-chart-6`: color-mix(in srgb, #e67700 70%, #2b8a3e) / #fcc419
- `--ray-chart-7`: #0b7285 / #22b8cf
- `--ray-chart-8`: #868e96
- `--ray-chart-grid`: #e9ecef / #2e2e2e
- `--ray-chart-axis`: color-mix(in srgb, #495057 50%, #868e96)
- `--ray-chart-text`: #212529
- `--ray-chart-tooltip`: #ffffff
- `--ray-chart-tooltip-text`: #212529
- `--ray-chart-tooltip-border`: #dee2e6

code:

- `--ray-code-background`: #f8f9fa / #19191a
- `--ray-code-text`: #212529
- `--ray-code-tag`: color-mix(in srgb, #2b8a3e 80%, #000000)
- `--ray-code-attr`: #5f3dc4
- `--ray-code-string`: #1864ab
- `--ray-code-keyword`: #a61e4d
- `--ray-code-number`: color-mix(in srgb, #d9480f 78%, #000000)
- `--ray-code-comment`: color-mix(in srgb, #495057 50%, #868e96)
- `--ray-code-punctuation`: color-mix(in srgb, #495057 50%, #868e96)
- `--ray-code-function`: #364fc7
- `--ray-code-type`: color-mix(in srgb, #087f5b 90%, #000000)
- `--ray-code-added`: color-mix(in srgb, #2b8a3e 80%, #000000)
- `--ray-code-removed`: color-mix(in srgb, #c92a2a 90%, #000000)

font:

- `--ray-font-sans`: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
- `--ray-font-mono`: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace

font-size:

- `--ray-font-size-xs`: 0.75rem
- `--ray-font-size-sm`: 0.875rem
- `--ray-font-size-md`: 1rem
- `--ray-font-size-lg`: 1.125rem
- `--ray-font-size-xl`: 1.25rem
- `--ray-font-size-2xl`: 1.5rem
- `--ray-font-size-3xl`: 1.875rem
- `--ray-font-size-4xl`: 2.25rem

line-height:

- `--ray-line-height-tight`: 1.25
- `--ray-line-height-heading`: 1.3
- `--ray-line-height-xs`: 1.4
- `--ray-line-height-sm`: 1.45
- `--ray-line-height-md`: 1.55
- `--ray-line-height-lg`: 1.6
- `--ray-line-height-xl`: 1.65

font-weight:

- `--ray-font-weight-regular`: 400
- `--ray-font-weight-medium`: 500
- `--ray-font-weight-semibold`: 600
- `--ray-font-weight-bold`: 700

space:

- `--ray-space-0`: 0
- `--ray-space-1`: 0.25rem
- `--ray-space-2`: 0.5rem
- `--ray-space-3`: 0.75rem
- `--ray-space-4`: 1rem
- `--ray-space-5`: 1.25rem
- `--ray-space-6`: 1.5rem
- `--ray-space-8`: 2rem
- `--ray-space-10`: 2.5rem
- `--ray-space-12`: 3rem
- `--ray-space-16`: 4rem
- `--ray-space-xs`: 0.625rem
- `--ray-space-sm`: 0.75rem
- `--ray-space-md`: 1rem
- `--ray-space-lg`: 1.25rem
- `--ray-space-xl`: 2rem

radius:

- `--ray-radius-xs`: 0.125rem
- `--ray-radius-sm`: 0.25rem
- `--ray-radius-md`: 0.5rem
- `--ray-radius-lg`: 1rem
- `--ray-radius-xl`: 2rem
- `--ray-radius-full`: 9999px
- `--ray-radius-default`: 0.5rem

control-height:

- `--ray-control-height-xs`: 1.875rem
- `--ray-control-height-sm`: 2.25rem
- `--ray-control-height-md`: 2.625rem
- `--ray-control-height-lg`: 3.125rem
- `--ray-control-height-xl`: 3.75rem

shadow:

- `--ray-shadow-xs`: 0 1px 3px color-mix(in srgb, #000000 5%, transparent), 0 1px 2px color-mix(in srgb, #000000 10%, transparent)
- `--ray-shadow-sm`: 0 1px 3px color-mix(in srgb, #000000 5%, transparent), 0 10px 15px -5px color-mix(in srgb, #000000 5%, transparent), 0 7px 7px -5px color-mix(in srgb, #000000 4%, transparent)
- `--ray-shadow-md`: 0 1px 3px color-mix(in srgb, #000000 5%, transparent), 0 20px 25px -5px color-mix(in srgb, #000000 5%, transparent), 0 10px 10px -5px color-mix(in srgb, #000000 4%, transparent)
- `--ray-shadow-lg`: 0 1px 3px color-mix(in srgb, #000000 5%, transparent), 0 28px 23px -7px color-mix(in srgb, #000000 5%, transparent), 0 12px 12px -7px color-mix(in srgb, #000000 4%, transparent)
- `--ray-shadow-xl`: 0 1px 3px color-mix(in srgb, #000000 5%, transparent), 0 36px 28px -7px color-mix(in srgb, #000000 5%, transparent), 0 17px 17px -7px color-mix(in srgb, #000000 4%, transparent)

gradient:

- `--ray-gradient-from`: #3b5bdb
- `--ray-gradient-to`: #6741d9
- `--ray-gradient-deg`: 45deg

overlay:

- `--ray-overlay-blur`: 4px

focus:

- `--ray-focus-ring-width`: 2px
- `--ray-focus-ring-offset`: 2px

duration:

- `--ray-duration-fast`: 120ms
- `--ray-duration-base`: 200ms
- `--ray-duration-slow`: 300ms

easing:

- `--ray-easing-standard`: cubic-bezier(0.2, 0, 0, 1)
- `--ray-easing-in`: cubic-bezier(0.3, 0, 1, 1)
- `--ray-easing-out`: cubic-bezier(0, 0, 0, 1)

z:

- `--ray-z-base`: 0
- `--ray-z-sticky`: 200
- `--ray-z-dropdown`: 300
- `--ray-z-overlay`: 400
- `--ray-z-modal`: 500
- `--ray-z-popover`: 600
- `--ray-z-toast`: 700
- `--ray-z-tooltip`: 800

breakpoint:

- `breakpoint-xs` (tokens.json only): 36em
- `breakpoint-sm` (tokens.json only): 48em
- `breakpoint-md` (tokens.json only): 62em
- `breakpoint-lg` (tokens.json only): 75em
- `breakpoint-xl` (tokens.json only): 88em

## Icons

The names `<ray-icon name>` and `setIcons()` know (more with `setIcons`):

`close`, `check`, `minus`, `plus`, `chevron-down`, `chevron-up`, `chevron-right`, `chevron-left`, `chevrons-left`, `chevrons-right`, `search`, `arrow-up-right`, `arrow-down-right`, `sun`, `moon`, `monitor`, `user`, `info`, `circle-check`, `alert-triangle`, `circle-x`, `menu`, `more-horizontal`, `file`, `folder`, `pause`, `play`, `terminal`, `calendar`, `image`, `download`, `eye`, `eye-off`, `bell`, `copy`, `quote`, `pipette`, `star`, `upload`, `paperclip`, `panel-left`, `settings`, `home`, `arrow-left`, `message-circle`

With a filled version (`<ray-icon name="star" filled>`; the others draw their outline): `user`, `info`, `circle-check`, `alert-triangle`, `circle-x`, `folder`, `bell`, `star`, `settings`, `home`, `message-circle`

The roles the components draw, each with its default glyph; `setIcons({ "ui.remove": … })` changes one role only, `setIcons({ close: … })` every role that uses the glyph: `ui.close` (close), `ui.clear` (close), `ui.remove` (close), `ui.expand` (chevron-down), `ui.disclosure` (chevron-right), `ui.previous` (chevron-left), `ui.next` (chevron-right), `ui.first` (chevrons-left), `ui.last` (chevrons-right), `ui.separator` (chevron-right), `ui.increment` (chevron-up), `ui.decrement` (chevron-down), `ui.sort` (chevron-up), `ui.checked` (check), `ui.indeterminate` (minus), `ui.copy` (copy), `ui.copied` (check), `ui.show-password` (eye), `ui.hide-password` (eye-off), `ui.play` (play), `ui.pause` (pause), `ui.search` (search), `ui.calendar` (calendar), `ui.eyedropper` (pipette), `ui.upload` (upload), `ui.avatar` (user), `ui.theme-light` (sun), `ui.theme-dark` (moon), `ui.theme-system` (monitor), `ui.trend-up` (arrow-up-right), `ui.trend-down` (arrow-down-right), `ui.trend-flat` (minus)

## Core API

What `@raylang/elements/core` (and `@raylang/elements`) exports besides the components: theme, icons, the native host, the base classes for your own components.

```ts
// Types of the ray-elements core runtime and extension API (core.js, form.js,
// floating.js, styles.js, position.js, focus.js, icons.js, host.js, raylang.js). Hand-written;
// the component declarations are generated after them into ray-elements.d.ts.

export declare const PREFIX: string;
export declare const THEME_EVENT: "ray-theme-change";

export type Theme = "light" | "dark" | "system";
export interface ThemeDetail {
  theme: Theme;
  resolved: "light" | "dark";
  primary: string | null;
}

// --- styles and registration -------------------------------------------------

/** A constructable stylesheet from CSS text, shared by every user of the same text. */
export declare function css(strings: TemplateStringsArray | string, ...values: unknown[]): CSSStyleSheet;
/** The base sheet every component adopts first. */
export declare const hostStyles: CSSStyleSheet;
/** Registers a custom element unless the tag is already taken. */
export declare function define(tag: string, cls: CustomElementConstructor): void;
/** A document-unique id with the given stem. */
export declare function uid(stem?: string): string;

/**
 * App-wide settings. `defaults` apply, per tag, to elements connected afterwards,
 * for the properties their markup and code leave unset.
 */
export declare function configure(options?: { defaults?: Record<string, Record<string, unknown>> }): void;
/** The defaults configure() set for a tag. */
export declare function getDefaults(tag: string): Record<string, unknown>;

// --- theme -------------------------------------------------------------------

export declare function getTheme(el?: Element): Theme;
export declare function resolvedTheme(el?: Element): "light" | "dark";
export declare function setTheme(theme: Theme, options?: { el?: Element; persist?: boolean }): void;
export declare function getPrimary(el?: Element): string | null;
export declare function setPrimary(color: string | null, options?: { el?: Element; persist?: boolean }): void;
export declare function onThemeChange(cb: (detail: ThemeDetail) => void): () => void;
/**
 * Makes any CSS color the primary (data-primary="custom"): ten OKLCH shades,
 * white or black text by contrast; warns below WCAG AA.
 */
export declare function definePrimary(
  color: string,
  options?: { el?: Element; persist?: boolean },
): { shades: string[]; filled: string; contrast: "white" | "black"; ratio: number; aa: boolean };
/** The color last given to definePrimary() for an element, as "#rrggbb" (null if none). */
export declare function getCustomPrimary(el?: Element): string | null;

// --- icons -------------------------------------------------------------------

/** Replaces or adds icons (SVG markup or an SVGElement); repaints every component. "<name>:filled" is an icon's filled version. */
export declare function setIcons(icons: Record<string, string | SVGElement>): void;
/** The SVG markup of a registered icon ("" if unknown); with filled, its filled version (the outline one without it). */
export declare function getIcon(name: string, options?: { filled?: boolean }): string;
/** The registered icon names; with filled, those that have a filled version. */
export declare function iconNames(options?: { filled?: boolean }): string[];
/** The roles the components draw ("ui.close", "ui.remove", "ui.expand"…) and the glyph each one uses unless the app registers the role. */
export declare function iconAliases(): Record<string, string>;

// --- base classes ------------------------------------------------------------

export interface PropertyOptions {
  type?: StringConstructor | NumberConstructor | BooleanConstructor;
  reflect?: boolean;
  attribute?: string | false;
  default?: unknown;
}

/**
 * Base class of ray-elements components. Members whose name starts with `_` or `#`
 * are internal: do not use them, and do not name your own members with `_`.
 */
export declare class RayElement extends HTMLElement {
  static properties: Record<string, PropertyOptions>;
  static styles: CSSStyleSheet[];
  static template: string;
  static delegatesFocus: boolean;
  /** Adds stylesheets to this component and its subclasses, live instances included. */
  static extendStyles(...sheets: CSSStyleSheet[]): void;
  connectedCallback(): void;
  disconnectedCallback(): void;
  attributeChangedCallback(attr: string, old: string | null, value: string | null): void;
  /** Schedules update() for the next microtask. */
  requestUpdate(): void;
  /** Protected: called after property changes with their previous values. */
  protected update(changed: Map<string, unknown>): void;
  /** Protected: sets a declared property without reflecting it (state changed by the user). */
  commitProperty(name: string, value: unknown): boolean;
  /** Protected: whether a declared property has its own value (not the default). */
  hasValue(name: string): boolean;
  /** Protected: fills [data-ray-icon] placeholders from the icon registry. */
  paintIcons(root?: ParentNode): void;
  /** Dispatches a bubbling, composed CustomEvent; false if a listener canceled it. */
  emit<T = unknown>(type: string, detail?: T, options?: { cancelable?: boolean }): boolean;
  /** querySelector inside the shadow root. */
  $<E extends Element = HTMLElement>(selector: string): E | null;
}

/** A form-associated ray-elements element (ElementInternals). */
export declare class FormControl extends RayElement {
  static formAssociated: true;
  readonly internals: ElementInternals;
  readonly form: HTMLFormElement | null;
  readonly validity: ValidityState;
  readonly validationMessage: string;
  readonly willValidate: boolean;
  /** Disabled by its own attribute or by a disabled <fieldset>. */
  readonly effectivelyDisabled: boolean;
  checkValidity(): boolean;
  reportValidity(): boolean;
  /** Protected: re-dispatches a non-composed event (e.g. change) from the host. */
  forward(event: Event): void;
  formDisabledCallback(disabled: boolean): void;
}

/**
 * A FormControl around one native control (#control in the shadow root),
 * with label, description, error, required and their ARIA.
 */
export declare class FieldControl extends FormControl {
  /** Spread into `static properties`: name, label, description, error, required, disabled, size, radius, variant. */
  static fieldProperties: Record<string, PropertyOptions>;
  /** The native control in the shadow root. */
  readonly control: HTMLInputElement & HTMLTextAreaElement & HTMLSelectElement;
  name: string | undefined;
  label: string | undefined;
  description: string | undefined;
  error: string | undefined;
  required: boolean | undefined;
  disabled: boolean | undefined;
  size: string;
  radius: string | undefined;
  variant: string;
  descriptionPosition: string;
  /** Protected hook: attach listeners once, on first connection. */
  wire?(): void;
  /** Protected: label, description, error, ARIA and validity (call from update). */
  syncField(): void;
  /** Protected: mirrors the native control's validity into the form. */
  syncValidity(): void;
}
/** The field wrapper markup around `control` (an element with id="control" class="control"). */
export declare function fieldTemplate(control: string, options?: { sections?: boolean }): string;
export declare const fieldStyles: CSSStyleSheet;
export declare const boxStyles: CSSStyleSheet;

/** Base of trigger + floating panel components (Popover API, anchored placement). */
export declare class Floating extends RayElement {
  /** popover attribute of the panel: "manual" (default; light dismiss and exit animation done by Floating) or "auto" (the browser's, no exit animation). */
  static popoverMode: "auto" | "manual";
  /** Close on Escape and outside presses (default true; tooltips: false). */
  static lightDismiss: boolean;
  /** aria-haspopup of the trigger (null: none). */
  static haspopup: string | null;
  /** Selector of the slot holding the trigger. */
  static triggerSlot: string;
  open: boolean | undefined;
  placement: string;
  offset: number;
  /** The [popover] panel in the shadow root (set on connection). */
  panel: HTMLElement;
  readonly trigger: Element | null;
  /** Whether focus was inside the panel when it started closing. */
  focusWasInside: boolean | undefined;
  show(): void;
  hide(): void;
  toggle(): void;
  /** Places the panel again (scroll and resize already do it). */
  reposition(): void;
  /** Protected hooks. */
  wireTrigger(trigger: Element): void;
  anchorRect(): { left: number; top: number; right: number; bottom: number; width: number; height: number };
  placeOptions(): PlaceOptions;
  popupKind(): string | null;
  toggled(open: boolean): void;
  /** Keyframes the panel leaves with (default: fade + scale 0.97). */
  exitKeyframes(): Keyframe[];
  /** Whether the same pointer gesture just light-dismissed the panel. */
  justClosed(): boolean;
}
export declare const floatingStyles: CSSStyleSheet;

// --- shared styles -----------------------------------------------------------

export declare const COLORS: string[];
export declare const VARIANT_TOKENS: string[];
/** Points an element's --_<variant> properties at a palette color, any CSS color, or the primary. */
export declare function applyColor(el: HTMLElement, color: string | undefined): void;
/** A spacing value as CSS: xs…xl as its --ray-space token, a bare number as px, else a CSS length; null when empty. */
export declare function spaceValue(value: string | number | undefined): string | null;
/** :host size scale: --_h, --_fs, --_px, --_gap by [size]. */
export declare const sizeStyles: CSSStyleSheet;
/** :host radius: --_r by [radius]. */
export declare const radiusStyles: CSSStyleSheet;
/** [data-variant] backgrounds/colors from the --_<variant> properties. */
export declare const variantStyles: CSSStyleSheet;
/** The backdrop of modal overlays: --ray-overlay and --ray-overlay-blur on dialog::backdrop. */
export declare const overlayStyles: CSSStyleSheet;
// --- motion and light dismiss ------------------------------------------------

/** A duration token in ms ("fast" | "base" | "slow"). */
export declare function duration(el: Element, name?: "fast" | "base" | "slow"): number;
/** False with reduced motion, a zero duration token or a hidden page. */
export declare function motionAllowed(el: Element, name?: "fast" | "base" | "slow"): boolean;
/** Plays keyframes (fill: forwards); resolves at once when motion is not allowed. Call cancel() after hiding. */
export declare function play(el: Element, keyframes: Keyframe[], options?: { speed?: "fast" | "base" | "slow"; ease?: "standard" | "in" | "out"; pseudoElement?: string }): { finished: Promise<void>; cancel(): void };
/** Waits for several play() results. */
export declare function playAll(list: Array<{ finished: Promise<void>; cancel(): void }>): { finished: Promise<void>; cancel(): void };
/** Fades and folds an element to zero height. */
export declare function collapseOut(el: Element, options?: { speed?: "fast" | "base" | "slow" }): { finished: Promise<void>; cancel(): void };
/** The default exit of floating panels. */
export declare const POP_OUT: Keyframe[];
/** Registers an open manual panel for Escape / outside-press dismissal; returns the unregister function. */
export declare function dismissable(entry: { panel: Element; owner: Element; trigger?: Element | null; close: (reason: "outside" | "escape" | "replaced") => void }): () => void;

/** Sets --ray-overlay-blur on an element: a number (px), a CSS length or "none"; empty removes it. */
export declare function applyOverlayBlur(el: HTMLElement, value: string | number | null | undefined): void;
/** A ring spinner: <span class="loader">. */
export declare const loaderStyles: CSSStyleSheet;
/** .sr-only: hidden but announced. */
export declare const srOnlyStyles: CSSStyleSheet;

// --- positioning and focus ---------------------------------------------------

export interface PlaceOptions {
  /** side[-align]: top|bottom|left|right, -start|-end; on top/bottom, -start/-end follow the writing direction. */
  placement?: string;
  offset?: number;
  padding?: number;
  flip?: boolean;
  matchWidth?: boolean;
}
export declare function place(
  anchor: { left: number; top: number; right: number; bottom: number; width: number; height: number },
  floating: HTMLElement,
  options?: PlaceOptions,
): string;
export declare function pointRect(x: number, y: number): DOMRectReadOnly;
export declare function autoUpdate(anchor: Element | object, floating: HTMLElement, update: () => void): () => void;
/** Tabbable elements under root, through shadow roots and slots. */
export declare function tabbables(root: Element | ShadowRoot, options?: { lightOnly?: boolean }): HTMLElement[];
/** Focuses the first [autofocus] or tabbable element; whether something got focus. */
export declare function focusFirst(root: Element | ShadowRoot, options?: { lightOnly?: boolean }): boolean;
/** Whether the element lays out right to left (dir="rtl" on it or an ancestor). */
export declare function isRtl(el: Element): boolean;
/** An arrow key as the reading direction sees it: right to left, ArrowLeft comes back as "ArrowRight" and the reverse. */
export declare function inlineKey(key: string, el: Element): string;

// --- charts (core/charts.js) -----------------------------------------------------

/** Number of series colors (--ray-chart-1 … --ray-chart-8). */
export declare const CHART_SERIES: number;
/** The chart tokens resolved to concrete colors for the theme of an element. */
export interface ChartTheme {
  scheme: "light" | "dark";
  /** Series colors, in order (#rrggbb). */
  series: string[];
  background: string;
  grid: string;
  axis: string;
  text: string;
  tooltip: { background: string; text: string; border: string };
  font: { family: string; size: number };
}
export declare function chartTheme(el?: Element): ChartTheme;
/** Calls cb with the new chart theme whenever the theme changes; returns a stop function. */
export declare function onChartThemeChange(cb: (theme: ChartTheme) => void, el?: Element): () => void;
/** A color with an alpha, as rgba(): withAlpha("#1c7ed6", 0.2). */
export declare function withAlpha(color: string, alpha: number): string;

// --- scrolling ---------------------------------------------------------------

/** The scroller of an element: `target`, else the content of its ray-app-shell or ray-scroll-area, else the window. */
export declare function scrollerOf(el: Element, target?: Element | string | null): Element | Window;
/** Calls cb with the scroll position and direction ("down" | "up") once per frame; returns a stop function. */
export declare function watchScroll(scroller: Element | Window, cb: (state: { y: number; direction: "up" | "down" }) => void, options?: { tolerance?: number }): () => void;

// --- native host (core/host.js, core/raylang.js) -----------------------------

/** A file a native host chose: a path on disk, with the File fields components read. */
export declare class HostFile {
  constructor(init: { path: string; name?: string; size?: number; type?: string; lastModified?: number });
  readonly path: string;
  readonly name: string;
  readonly size: number;
  readonly type: string;
  readonly lastModified: number;
}
export interface FileFilter {
  name: string;
  extensions: string[];
}
/** What the program around the page can do natively; components use it when it is there. */
export interface Host {
  name: string;
  can(op: "pick_files" | "pick_path" | "confirm" | "menu_items" | "run_menu" | "popup_menu" | "window_colors" | "set_edited" | (string & {})): boolean;
  pickFiles?(options?: { title?: string; multiple?: boolean; directory?: string; filters?: FileFilter[] }): Promise<HostFile[]>;
  pickPath?(options?: { mode?: "open" | "folder" | "save"; title?: string; directory?: string; suggested?: string; filters?: FileFilter[] }): Promise<string | null>;
  menuItems?(): Promise<HostMenuItem[]>;
  runMenu?(tag: string): Promise<true>;
  popupMenu?(items: { title?: string; enabled?: boolean; checked?: boolean; separator?: boolean }[]): Promise<number | null>;
  setEdited?(edited: boolean): Promise<true>;
  setWindowColors?(colors: { background?: string; titlebar?: string }): Promise<true>;
  /** Set when the page runs under a transparent title bar (px). */
  titlebar?: { height: number; inset: number } | null;
  confirm?(options?: { title?: string; message?: string; confirmLabel?: string; cancelLabel?: string; style?: "" | "info" | "warning" | "error" }): Promise<boolean>;
}
/** An item of the app's native menu bar, as a host lists it. */
export interface HostMenuItem {
  menu: string;
  tag: string;
  title: string;
  /** A chord such as "cmd+shift+s" (cmd: ⌘ on macOS, Ctrl elsewhere); "" for none. */
  shortcut: string;
  enabled: boolean;
  checked: boolean;
}
export declare function setHost(host: Host | null): void;
export declare function getHost(): Host | null;
export declare function hostCan(op: string): boolean;
/** Calls cb whenever the host changes; returns the unsubscribe function. */
export declare function onHostChange(cb: (host: Host | null) => void): () => void;
/** The title bar the page runs under ({ height, inset } px), or null. */
export declare function titlebar(): { height: number; inset: number } | null;
/** Makes el drag the window under a host's title bar (data-ray-drag); returns the undo function. */
export declare function dragRegion(el: Element): () => void;
export interface EditTracker {
  readonly dirty: boolean;
  /** Takes the current values as saved. */
  clean(): void;
  check(): void;
  stop(): void;
}
/** Follows whether a form has unsaved changes; with a host, the window shows it. */
export declare function trackEdits(form: HTMLFormElement, options?: { onChange?: (dirty: boolean) => void }): EditTracker;
/** The MIME type of a file name, from its extension ("" when unknown). */
export declare function typeOfName(name: string): string;
/** The file dialog filters of an accept list ([] = any file); `name` defaults to the extensions. */
export declare function acceptFilters(accept: string | null | undefined, name?: string): FileFilter[];
/** The extensions of a MIME type or pattern ("image/*"). */
export declare function extensionsOfType(type: string): string[];

/** The version of the ray-elements bridge protocol the page speaks. */
export declare const PROTOCOL: number;
export interface RaylangHost extends Host {
  name: "raylang";
  platform: string;
  version: string;
}
/**
 * In a std/ui window whose program calls elements/bridge's handle(), installs the
 * raylang host; null in a browser or when the program does not answer in `timeout` ms.
 */
export declare function enableRaylang(options?: { timeout?: number; ray?: unknown; windowColors?: boolean }): Promise<RaylangHost | null>;
```