@raylang/elements 0.7.0 → 0.9.0

package/index.js

@@ -16,6 +16,7 @@ export { RayCombobox } from "./components/combobox/combobox.js";
 export { RayDatePicker, RayCalendar } from "./components/date-picker/date-picker.js";
 export { RayFileUpload, parseSize, matchesAccept, describeAccept } from "./components/file-upload/file-upload.js";
 export { RayInput } from "./components/input/input.js";
+export { RayModeInput } from "./components/mode-input/mode-input.js";
 export { RayNumberInput, parseNumber, formatNumber } from "./components/number-input/number-input.js";
 export { RayPasswordInput } from "./components/password-input/password-input.js";
 export { RayPathInput, dirName, baseName } from "./components/path-input/path-input.js";
@@ -28,6 +29,7 @@ export { RaySwitch } from "./components/switch/switch.js";
 export { RayTextarea } from "./components/textarea/textarea.js";
 export { RayBottomNav, RayBottomNavItem } from "./components/bottom-nav/bottom-nav.js";
 export { RayBreadcrumbs, RayBreadcrumb } from "./components/breadcrumbs/breadcrumbs.js";
+export { RayDocTabs, RayDocTab } from "./components/doc-tabs/doc-tabs.js";
 export { RayNavLink } from "./components/nav-link/nav-link.js";
 export { RayPagination, paginationRange } from "./components/pagination/pagination.js";
 export { RaySidebar, RaySidebarGroup } from "./components/sidebar/sidebar.js";

package/llms-full.txt

@@ -1,6 +1,6 @@
 # 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.7.0.
+> 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>`,
@@ -82,7 +82,10 @@ reference of every component follows them.
   `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).
+  (`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`.
@@ -164,6 +167,21 @@ green a check, red an error, yellow a warning, others info).
 - 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
@@ -238,7 +256,9 @@ fn run() -> Result<int, string> {
 
 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,
+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
@@ -463,7 +483,7 @@ Properties:
 - `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`): `right` | `left`, default `right`, reflects. Side of the label.
+- `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`.
 
@@ -877,6 +897,9 @@ Properties:
 - `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):
 
@@ -894,6 +917,7 @@ Attributes (forwarded to the inner element):
 
 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).
 
@@ -909,13 +933,66 @@ Parts (`::part()`):
 - `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.
@@ -989,7 +1066,7 @@ Properties:
 - `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`.
+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:
 
@@ -1016,7 +1093,7 @@ Properties:
 - `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`.
+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:
 
@@ -1334,7 +1411,7 @@ Properties:
 - `label`: string. Label text (or the content).
 - `description`: string. Help text.
 - `error`: string. Error text.
-- `labelPosition` (attribute `label-position`): `right` | `left`, default `right`, reflects. Side of the label.
+- `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.
@@ -1383,6 +1460,9 @@ Properties:
 - `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`.
 
@@ -1396,6 +1476,7 @@ Attributes (forwarded to the inner element):
 
 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.
 
@@ -1403,6 +1484,14 @@ 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).
 
@@ -1525,6 +1614,66 @@ Parts (`::part()`):
 - `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.
@@ -1622,7 +1771,7 @@ Exports (from `@raylang/elements/pagination` and `@raylang/elements`):
 
 ### Sidebar
 
-The side navigation of an app shell: header, content and footer; on wide screens it collapses to an icon rail, below a breakpoint it becomes an off-canvas drawer. toggle() does the right thing for the screen.
+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
 
@@ -1632,17 +1781,24 @@ Put ray-sidebar-group + ray-nav-link (with an icon in slot=left) inside. Collaps
 
 Properties:
 
-- `collapsed`: boolean, reflects. Wide screens: an icon rail instead of the full panel.
+- `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`: `left` | `right`, default `left`, reflects. The edge it sits on.
+- `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).
@@ -1659,6 +1815,7 @@ Parts (`::part()`):
 - `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:
@@ -1697,7 +1854,7 @@ 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`): `left` | `top`, default `left`, reflects. Label beside the number, or under it (narrow screens, many steps).
+- `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.
@@ -1757,12 +1914,15 @@ 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.
 
@@ -1776,7 +1936,7 @@ Slots:
 
 Parts (`::part()`):
 
-- `list`: The tab list.
+- `list`: The tab list (it scrolls sideways when the tabs do not fit).
 - `panels`: The panel area.
 
 Methods and properties:
@@ -1792,11 +1952,16 @@ 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`: Badge or count.
+- `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)
 
@@ -1825,6 +1990,9 @@ Properties:
 - `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).
 
@@ -1855,7 +2023,7 @@ Exports (from `@raylang/elements/command-palette` and `@raylang/elements`):
 
 Types:
 
-- `{ id?: string; label: string; description?: string; group?: string; keywords?: string | string[]; shortcut?: string; icon?: string | Node; disabled?: boolean; native?: boolean; tag?: string; onSelect?: (action: CommandAction) => void }`: An action of ray-command-palette.
+- `{ 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
 
@@ -1969,7 +2137,7 @@ 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`: `right` | `left` | `top` | `bottom`, default `right`, reflects. The edge it slides from.
+- `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.
@@ -2013,7 +2181,7 @@ Import: `import "@raylang/elements/menu";` · Category: Overlays
 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.
+- `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.
@@ -2023,6 +2191,7 @@ 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.
 
@@ -2053,6 +2222,9 @@ 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:
 
@@ -2060,6 +2232,14 @@ Slots:
 - `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.
@@ -2082,7 +2262,16 @@ With `native` and [the native bridge](https://elements.raylang.dev/raylang.html#
 </ray-menu>
 ```
 
-Labels, nested menus, icons and colors are the page menu's only. A dismissed native menu fires nothing.
+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
 
@@ -2097,7 +2286,7 @@ Positioned in JS (flip + shift to stay in the viewport). JS: show(), hide(), tog
 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.
+- `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.
@@ -2138,7 +2327,7 @@ Import: `import "@raylang/elements/tooltip";` · Category: Overlays
 Properties:
 
 - `label`: string. Tooltip text.
-- `placement`: `top` | `bottom` | `left` | `right` | `top-start` | `top-end` | `bottom-start` | `bottom-end`, default `top`, reflects. Preferred side.
+- `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.
@@ -2174,7 +2363,7 @@ 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`): `right` | `left`, default `right`, reflects. Side of the chevron.
+- `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:
 
@@ -2415,7 +2604,7 @@ 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. 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.
+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:
 
@@ -2425,6 +2614,7 @@ Properties:
 - `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.
@@ -2474,6 +2664,7 @@ 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.
@@ -2629,7 +2820,7 @@ A list (role="list") of ray-timeline-item.
 Properties:
 
 - `active`: number, default `-1`, reflects. Index of the last reached item (-1: none).
-- `align`: `left` | `right`, default `left`, reflects. Side of the line.
+- `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).
@@ -2760,7 +2951,7 @@ Created by notify() when missing; add one yourself to choose its position. A sta
 
 Properties:
 
-- `position`: `bottom-right` | `bottom-left` | `bottom-center` | `top-right` | `top-left` | `top-center`, default `bottom-right`, reflects. Corner of the stack.
+- `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.
@@ -3177,7 +3368,7 @@ Properties:
 
 Events:
 
-- `ray-reach-end` (detail `{ edge: "bottom" | "right" }`): The end came within threshold (once per arrival).
+- `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:
 
@@ -3191,8 +3382,8 @@ Parts (`::part()`):
 Methods and properties:
 
 - `readonly viewport: HTMLElement`: The scrolling element (scrollTop, scrollTo…).
-- `scrollToStart(options?: { behavior?: ScrollBehavior }): void`: Scrolls to the top (left).
-- `scrollToEnd(options?: { behavior?: ScrollBehavior }): void`: Scrolls to the bottom (right when horizontal).
+- `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
 
@@ -3206,7 +3397,7 @@ 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`): `left` | `center` | `right`, default `center`, reflects. Where the label sits.
+- `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.
 
@@ -3233,7 +3424,7 @@ Properties:
 - `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 is saved in localStorage and restored.
+- `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:
 
@@ -3777,6 +3968,7 @@ 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;
@@ -3794,6 +3986,10 @@ export declare function autoUpdate(anchor: Element | object, floating: HTMLEleme
 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) -----------------------------------------------------