@raylang/elements 0.7.0 → 0.9.0

package/llms.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
@@ -275,6 +295,7 @@ Members whose name starts with `_` are internal.
 - [Date picker](https://elements.raylang.dev/components/date-picker.md): `<ray-date-picker>`, `<ray-calendar>` (Inputs). A date field with a calendar dropdown, and the calendar on its own.
 - [File upload](https://elements.raylang.dev/components/file-upload.md): `<ray-file-upload>` (Inputs). A drop zone to pick files: drag, click, keyboard or paste.
 - [Input](https://elements.raylang.dev/components/input.md): `<ray-input>` (Inputs). A text field with label, description and error (Mantine's TextInput).
+- [Mode input](https://elements.raylang.dev/components/mode-input.md): `<ray-mode-input>` (Inputs). 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.
 - [Number input](https://elements.raylang.dev/components/number-input.md): `<ray-number-input>` (Inputs). 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).
 - [Password input](https://elements.raylang.dev/components/password-input.md): `<ray-password-input>` (Inputs). A password field with a button that shows or hides what was typed (Mantine's PasswordInput).
 - [Path input](https://elements.raylang.dev/components/path-input.md): `<ray-path-input>` (Inputs). A field for a path on disk: a file to open, a folder, or where to save.
@@ -287,9 +308,10 @@ Members whose name starts with `_` are internal.
 - [Textarea](https://elements.raylang.dev/components/textarea.md): `<ray-textarea>` (Inputs). A multi-line text field that can grow with its content.
 - [Bottom nav](https://elements.raylang.dev/components/bottom-nav.md): `<ray-bottom-nav>`, `<ray-bottom-nav-item>` (Navigation). 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.
 - [Breadcrumbs](https://elements.raylang.dev/components/breadcrumbs.md): `<ray-breadcrumbs>`, `<ray-breadcrumb>` (Navigation). Where a page sits (Mantine's Breadcrumbs, the WAI-ARIA breadcrumb pattern): links in a labelled nav, the last one the current page.
+- [Document tabs](https://elements.raylang.dev/components/doc-tabs.md): `<ray-doc-tabs>`, `<ray-doc-tab>` (Navigation). 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.
 - [Nav link](https://elements.raylang.dev/components/nav-link.md): `<ray-nav-link>` (Navigation). A sidebar/navigation item: icon, label, description, badge, active state, and nested nav links that collapse under it.
 - [Pagination](https://elements.raylang.dev/components/pagination.md): `<ray-pagination>` (Navigation). Page navigation: previous/next, optional first/last, page numbers with ellipses; the number of items stays constant so it does not jump.
-- [Sidebar](https://elements.raylang.dev/components/sidebar.md): `<ray-sidebar>`, `<ray-sidebar-group>` (Navigation). 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.
+- [Sidebar](https://elements.raylang.dev/components/sidebar.md): `<ray-sidebar>`, `<ray-sidebar-group>` (Navigation). 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.
 - [Stepper](https://elements.raylang.dev/components/stepper.md): `<ray-stepper>`, `<ray-step>` (Navigation). A task in steps (Mantine's Stepper): a wizard, a checkout, an onboarding.
 - [Tabs](https://elements.raylang.dev/components/tabs.md): `<ray-tabs>`, `<ray-tab>`, `<ray-tab-panel>` (Navigation). Tabs and panels (WAI-ARIA tabs pattern): arrows, Home/End, automatic or manual activation.
 - [Command palette](https://elements.raylang.dev/components/command-palette.md): `<ray-command-palette>` (Overlays). Search and run actions from the keyboard (Mantine's Spotlight): fuzzy search, groups, shortcuts, ⌘K / Ctrl+K; combobox + listbox pattern in a modal dialog.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raylang/elements",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Web components for any app, with raylang extras (shadcn/ui + Mantine inspired)",
   "license": "Apache-2.0",
   "keywords": ["web-components", "custom-elements", "design-system", "ui", "raylang"],
@@ -84,6 +84,10 @@
       "types": "./ray-elements.d.ts",
       "default": "./components/input/input.js"
     },
+    "./mode-input": {
+      "types": "./ray-elements.d.ts",
+      "default": "./components/mode-input/mode-input.js"
+    },
     "./number-input": {
       "types": "./ray-elements.d.ts",
       "default": "./components/number-input/number-input.js"
@@ -132,6 +136,10 @@
       "types": "./ray-elements.d.ts",
       "default": "./components/breadcrumbs/breadcrumbs.js"
     },
+    "./doc-tabs": {
+      "types": "./ray-elements.d.ts",
+      "default": "./components/doc-tabs/doc-tabs.js"
+    },
     "./nav-link": {
       "types": "./ray-elements.d.ts",
       "default": "./components/nav-link/nav-link.js"

package/ray-elements.d.ts

@@ -229,6 +229,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;
@@ -246,6 +247,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) -----------------------------------------------------
 
@@ -488,8 +493,8 @@ export declare class RayCheckbox extends FieldControl {
   color: string | undefined;
   /** Box and font size. */
   size: "xs" | "sm" | "md" | "lg" | "xl";
-  /** Side of the label. */
-  labelPosition: "right" | "left";
+  /** Side of the label: start/end follow the writing direction; left/right are sides of the screen. */
+  labelPosition: "end" | "start" | "right" | "left";
 }
 
 // --- Checkbox group (checkbox-group)
@@ -806,6 +811,12 @@ export interface RayFileUploadEventMap extends HTMLElementEventMap {
 }
 
 // --- Input (input)
+/** A range of a field's text to mark (ray-input and ray-textarea highlight): offsets into the text, end excluded. */
+export type HighlightRange = { start: number; end: number; kind?: string; title?: string };
+/** A suggestion of a field's complete(): value is inserted; label (default: value) and detail are shown, description under them. */
+export type CompletionItem = { value: string; label?: string; detail?: string; description?: string };
+/** What complete() returns: the part of the text (offsets, to excluded) a suggestion replaces, and the suggestions. */
+export type CompletionResult = { from: number; to: number; items: CompletionItem[] };
 /** <ray-input> 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. */
 export declare class RayInput extends FieldControl {
   /** Current value. The value attribute is the initial value (restored on form reset). */
@@ -836,8 +847,59 @@ export declare class RayInput extends FieldControl {
   radius: "xs" | "sm" | "md" | "lg" | "xl" | "full" | undefined;
   /** Box style. */
   variant: "default" | "filled" | "unstyled";
+  /** 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. */
+  highlight: ((text: string) => HighlightRange[]) | 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). */
+  complete: ((text: string, caret: number) => CompletionResult | null | Promise<CompletionResult | null>) | null;
+  /** Accessible name of the suggestion list. */
+  suggestionsLabel: string;
   /** Selects the text. */
   select(): void;
+  /** Runs highlight again, when what it marks changed but the text did not. */
+  refreshHighlight(): void;
+  addEventListener<K extends keyof RayInputEventMap>(type: K, listener: (this: RayInput, ev: RayInputEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  removeEventListener<K extends keyof RayInputEventMap>(type: K, listener: (this: RayInput, ev: RayInputEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+export interface RayInputEventMap extends HTMLElementEventMap {
+  /** A suggestion was accepted (the text already has it). */
+  "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
+}
+
+// --- Mode input (mode-input)
+/** A mode of ray-mode-input: hint is the trigger's short text ("€"), attrs the attributes it sets on the field. */
+export type ModeOption = { value: string; label: string; icon?: string; hint?: string; description?: string; disabled?: boolean; attrs?: Record<string, string> };
+/** <ray-mode-input> 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. */
+export declare class RayModeInput extends RayInput {
+  /** The chosen mode's value (default: the first). Setting it applies that mode without ray-mode-change. */
+  mode: string | undefined;
+  /** The modes; when not set, the <option> children. */
+  options: ModeOption[] | undefined;
+  /** 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. */
+  display: "label" | "icon" | "both" | undefined;
+  /** The side of the field the trigger sits on. */
+  position: "start" | "end";
+  /** The trigger's accessible name, read with the current mode ("Mode: File"). */
+  menuLabel: string;
+  /** With a native host (a std/ui window with the bridge), the system's menu (no descriptions there). */
+  nativeMenu: boolean | undefined;
+  /** The modes in use. */
+  readonly modes: ModeOption[];
+  /** The chosen mode. */
+  readonly currentOption: ModeOption | null;
+  /** Chooses a mode as the user would (fires ray-mode-change). */
+  choose(value: string): void;
+  addEventListener<K extends keyof RayModeInputEventMap>(type: K, listener: (this: RayModeInput, ev: RayModeInputEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  removeEventListener<K extends keyof RayModeInputEventMap>(type: K, listener: (this: RayModeInput, ev: RayModeInputEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+export interface RayModeInputEventMap extends HTMLElementEventMap {
+  /** The user chose a mode (mode is already the new one); cancelable: preventDefault keeps the previous mode. */
+  "ray-mode-change": CustomEvent<{ mode: string; previous: string | null; option: ModeOption }>;
+  /** A suggestion was accepted (the text already has it). */
+  "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
 }
 
 // --- Number input (number-input)
@@ -896,6 +958,8 @@ export declare class RayPasswordInput extends RayInput {
 export interface RayPasswordInputEventMap extends HTMLElementEventMap {
   /** The user showed or hid the password. */
   "ray-visibility-change": CustomEvent<{ visible: boolean }>;
+  /** A suggestion was accepted (the text already has it). */
+  "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
 }
 
 // --- Path input (path-input)
@@ -925,6 +989,8 @@ export declare class RayPathInput extends RayInput {
 export interface RayPathInputEventMap extends HTMLElementEventMap {
   /** The system dialog failed. */
   "ray-error": CustomEvent<{ error: Error }>;
+  /** A suggestion was accepted (the text already has it). */
+  "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
 }
 
 // --- Radio group (radio)
@@ -1137,8 +1203,8 @@ export declare class RaySwitch extends RayCheckbox {
   description: string | undefined;
   /** Error text. */
   error: string | undefined;
-  /** Side of the label. */
-  labelPosition: "right" | "left";
+  /** Side of the label: start/end follow the writing direction; left/right are sides of the screen. */
+  labelPosition: "end" | "start" | "right" | "left";
   /** Track color when on. */
   color: string | undefined;
   /** Track size. */
@@ -1178,6 +1244,22 @@ export declare class RayTextarea extends FieldControl {
   size: "xs" | "sm" | "md" | "lg" | "xl";
   /** Box style. */
   variant: "default" | "filled" | "unstyled";
+  /** 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. */
+  highlight: ((text: string) => HighlightRange[]) | 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). */
+  complete: ((text: string, caret: number) => CompletionResult | null | Promise<CompletionResult | null>) | null;
+  /** Accessible name of the suggestion list. */
+  suggestionsLabel: string;
+  /** Runs highlight again, when what it marks changed but the text did not. */
+  refreshHighlight(): void;
+  addEventListener<K extends keyof RayTextareaEventMap>(type: K, listener: (this: RayTextarea, ev: RayTextareaEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  removeEventListener<K extends keyof RayTextareaEventMap>(type: K, listener: (this: RayTextarea, ev: RayTextareaEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+export interface RayTextareaEventMap extends HTMLElementEventMap {
+  /** A suggestion was accepted (the text already has it). */
+  "ray-complete": CustomEvent<{ item: CompletionItem; from: number; to: number }>;
 }
 
 // --- Bottom nav (bottom-nav)
@@ -1258,6 +1340,42 @@ export declare class RayBreadcrumb extends RayElement {
   current: boolean | undefined;
 }
 
+// --- Document tabs (doc-tabs)
+/** <ray-doc-tabs> 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. */
+export declare class RayDocTabs extends RayElement {
+  /** Value of the selected tab (default: the first). */
+  value: string | undefined;
+  /** The id of the shared panel: it gets role=tabpanel and aria-labelledby the selected tab; the tabs get aria-controls. */
+  panel: string | undefined;
+  /** Accessible name of the tab list ("Open requests"). */
+  label: string | undefined;
+  /** Tooltip of the ×. */
+  closeLabel: string;
+  /** What assistive technology hears after the name of a dirty tab. */
+  dirtyLabel: string;
+  /** Its tabs, in order. */
+  readonly tabs: RayDocTab[];
+  /** The shared panel, found by the panel id. */
+  readonly panelElement: HTMLElement | null;
+  addEventListener<K extends keyof RayDocTabsEventMap>(type: K, listener: (this: RayDocTabs, ev: RayDocTabsEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
+  removeEventListener<K extends keyof RayDocTabsEventMap>(type: K, listener: (this: RayDocTabs, ev: RayDocTabsEventMap[K]) => unknown, options?: boolean | EventListenerOptions): void;
+  removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
+}
+export interface RayDocTabsEventMap extends HTMLElementEventMap {
+  /** 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). */
+  "ray-request-close": CustomEvent<{ value: string; tab: RayDocTab; source: "button" | "middle" | "key" }>;
+}
+/** <ray-doc-tab> 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. */
+export declare class RayDocTab extends RayElement {
+  /** Identifies the document (ray-doc-tabs value). */
+  value: string | undefined;
+  /** Unsaved changes: a dot in place of the ×, which comes back under the pointer. */
+  dirty: boolean | undefined;
+  /** Cannot be closed: no ×, no middle click, no Delete. */
+  hideClose: boolean | undefined;
+}
+
 // --- Nav link (nav-link)
 /** <ray-nav-link> A link with href (aria-current=page when active), or a button that toggles its nested links. */
 export declare class RayNavLink extends RayElement {
@@ -1335,12 +1453,14 @@ export declare class RayPagination extends RayElement {
 // --- Sidebar (sidebar)
 /** <ray-sidebar> 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 }). */
 export declare class RaySidebar extends RayElement {
-  /** Wide screens: an icon rail instead of the full panel. */
+  /** Wide screens: collapsed as collapse says (an icon rail, or out of view). */
   collapsed: boolean | undefined;
+  /** What collapsed does on wide screens: icon, a rail of the nav links' icons; offcanvas, hidden entirely (no width, out of the tab order). */
+  collapse: "icon" | "offcanvas";
   /** Narrow screens: the drawer is shown (modal, focus trapped; Escape, backdrop click or a followed link close it). */
   open: boolean | undefined;
-  /** The edge it sits on. */
-  side: "left" | "right";
+  /** 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. */
+  side: "start" | "end" | "left" | "right";
   /** A panel against the edge, or a floating card with a margin. */
   variant: "sidebar" | "floating";
   /** Width when expanded (CSS length). Default 16rem. */
@@ -1351,6 +1471,16 @@ export declare class RaySidebar extends RayElement {
   breakpoint: string;
   /** Accessible name of its navigation. */
   label: string;
+  /** 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. */
+  resizable: boolean | undefined;
+  /** Narrowest width when resizing, in px. */
+  minWidth: number;
+  /** Widest width when resizing, in px. */
+  maxWidth: number;
+  /** A key: the resized width is saved in localStorage and restored. A later change of width wins. */
+  autosave: string | undefined;
+  /** Accessible name of the resize edge. */
+  resizeLabel: string;
   /** Collapses/expands on wide screens; opens/closes the drawer on narrow ones. */
   toggle(): void;
   /** Whether it is in drawer mode (at or below the breakpoint). */
@@ -1361,6 +1491,8 @@ export declare class RaySidebar extends RayElement {
   removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
 }
 export interface RaySidebarEventMap extends HTMLElementEventMap {
+  /** After a drag or a key resized it (resizable). */
+  "ray-resize": CustomEvent<{ width: number }>;
   /** After toggle(). */
   "ray-toggle": CustomEvent<{ collapsed: boolean; open: boolean; mobile: boolean }>;
   /** The drawer opened (narrow screens). */
@@ -1381,8 +1513,8 @@ export declare class RayStepper extends RayElement {
   active: number;
   /** Steps in a row above the content, or in a column beside it. */
   orientation: "horizontal" | "vertical";
-  /** Label beside the number, or under it (narrow screens, many steps). */
-  iconPosition: "left" | "top";
+  /** Label beside the number (after it in the reading direction), or under it (narrow screens, many steps). "left", its former name, still works. */
+  iconPosition: "start" | "top" | "left";
   /** Completed steps are buttons that go back to them. */
   allowStepSelect: boolean | undefined;
   /** With allow-step-select off, false lets the user jump to any step. */
@@ -1419,7 +1551,7 @@ export declare class RayStep extends RayElement {
 }
 
 // --- Tabs (tabs)
-/** <ray-tabs> Tabs and panels (WAI-ARIA tabs pattern): arrows, Home/End, automatic or manual activation. */
+/** <ray-tabs> 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. */
 export declare class RayTabs extends RayElement {
   /** Value of the active tab (default: the first enabled one). */
   value: string | undefined;
@@ -1429,6 +1561,8 @@ export declare class RayTabs extends RayElement {
   orientation: "horizontal" | "vertical";
   /** Active indicator color. */
   color: string | undefined;
+  /** Height, font size and padding of the tabs (xs for a compact bar). */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
   /** manual: arrows move focus, Enter/Space activates. */
   activation: "auto" | "manual";
   /** Tabs share the full width. */
@@ -1444,6 +1578,8 @@ export declare class RayTab extends RayElement {
   value: string | undefined;
   /** Cannot be activated. */
   disabled: boolean | undefined;
+  /** A small number after the label ("3", "99+"), lighter than a badge; part of the tab's accessible name. Empty: none. */
+  count: string | undefined;
 }
 /** <ray-tab-panel> Tabs and panels (WAI-ARIA tabs pattern): arrows, Home/End, automatic or manual activation. */
 export declare class RayTabPanel extends RayElement {
@@ -1452,8 +1588,8 @@ export declare class RayTabPanel extends RayElement {
 }
 
 // --- Command palette (command-palette)
-/** An action of ray-command-palette. */
-export type CommandAction = { 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. 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. */
+export type CommandAction = { 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 };
 /** How well an action matches a query (0 = not at all). */
 export declare function score(action: CommandAction, query: string): number;
 /** <ray-command-palette> Running an action fires ray-select and calls its onSelect. The best matches come first, grouped. */
@@ -1476,6 +1612,12 @@ export declare class RayCommandPalette extends RayElement {
   label: string;
   /** No keyboard hint at the bottom. */
   hideHint: boolean | undefined;
+  /** The keyboard hint's word for ↑↓. */
+  navigateLabel: string;
+  /** The keyboard hint's word for ↵. */
+  runLabel: string;
+  /** The keyboard hint's word for esc. */
+  closeLabel: string;
   /** 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. */
   nativeMenus: boolean | undefined;
   /** Blur of the page behind: px ("8"), a CSS length or "none". Default: --ray-overlay-blur ([overlay] blur in tokens.toml). */
@@ -1558,8 +1700,8 @@ export declare class RayDrawer extends RayElement {
   label: string | undefined;
   /** A line under the title (the drawer's accessible description). */
   description: string | undefined;
-  /** The edge it slides from. */
-  position: "right" | "left" | "top" | "bottom";
+  /** The edge it slides from: start/end follow the writing direction; left/right are sides of the screen. */
+  position: "end" | "start" | "right" | "left" | "top" | "bottom";
   /** Width (left/right) or height (top/bottom): xs…xl, full, or any CSS length. */
   size: "xs" | "sm" | "md" | "lg" | "xl" | "full" | (string & {});
   /** No backdrop nor scroll lock: the page stays interactive (a side panel). */
@@ -1597,7 +1739,7 @@ export interface RayDrawerEventMap extends HTMLElementEventMap {
 export declare class RayMenu extends Floating {
   /** Shown. */
   open: boolean | undefined;
-  /** Preferred side and alignment. */
+  /** 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). */
   placement: "bottom-start" | "bottom" | "bottom-end" | "top-start" | "top" | "top-end" | "right-start" | "left-start";
   /** Opens on right click (contextmenu) over the trigger area, at the pointer. */
   context: boolean | undefined;
@@ -1625,6 +1767,8 @@ export declare class RayMenu extends Floating {
 export interface RayMenuEventMap extends HTMLElementEventMap {
   /** An item was chosen; detail: { value, item }. */
   "ray-select": CustomEvent<{ value: string; item: RayMenuItem }>;
+  /** 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-request-open": CustomEvent<{ event: Event }>;
   /** After it opened. */
   "ray-open": CustomEvent<unknown>;
   /** After it closed. */
@@ -1638,6 +1782,14 @@ export declare class RayMenuItem extends RayElement {
   disabled: boolean | undefined;
   /** Text and hover color (e.g. red for destructive actions). */
   color: string | undefined;
+  /** 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. */
+  type: "item" | "checkbox" | "radio";
+  /** Checked (checkbox and radio items). Already updated when ray-select fires. */
+  checked: boolean | undefined;
+  /** The group of a radio item: one checked per name in the menu. */
+  name: string | undefined;
+  /** Whether type is checkbox or radio. */
+  readonly checkable: boolean;
 }
 /** <ray-menu-label> A section caption inside the menu. */
 export declare class RayMenuLabel extends RayElement {
@@ -1651,7 +1803,7 @@ export declare class RayMenuDivider extends RayElement {
 export declare class RayPopover extends Floating {
   /** Shown. */
   open: boolean | undefined;
-  /** Preferred side and alignment. */
+  /** 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). */
   placement: "bottom" | "bottom-start" | "bottom-end" | "top" | "top-start" | "top-end" | "left" | "left-start" | "left-end" | "right" | "right-start" | "right-end";
   /** Gap to the trigger in px. */
   offset: number;
@@ -1688,7 +1840,7 @@ export interface RayPopoverEventMap extends HTMLElementEventMap {
 export declare class RayTooltip extends Floating {
   /** Tooltip text. */
   label: string | undefined;
-  /** Preferred side. */
+  /** Preferred side; -start/-end follow the writing direction. */
   placement: "top" | "bottom" | "left" | "right" | "top-start" | "top-end" | "bottom-start" | "bottom-end";
   /** ms before showing. */
   openDelay: number;
@@ -1717,8 +1869,8 @@ export declare class RayAccordion extends RayElement {
   multiple: boolean | undefined;
   /** Visual style. */
   variant: "default" | "contained" | "separated" | "filled";
-  /** Side of the chevron. */
-  chevronPosition: "right" | "left";
+  /** Side of the chevron: start/end follow the writing direction; left/right are sides of the screen. */
+  chevronPosition: "end" | "start" | "right" | "left";
   /** The items. */
   readonly items: RayAccordionItem[];
   /** The open values as an array, whatever the mode. */
@@ -1885,7 +2037,7 @@ export declare class RayCarousel extends RayElement {
 export declare function setHighlighter(fn: ((code: string, lang: string) => string | Node | null | undefined | Promise<string | Node | null | undefined>) | null): void;
 /** The built-in highlighter: tokens of type keyword, string, number, comment, function, type, tag, attr, punctuation or text. */
 export declare function tokenize(code: string, lang?: string): [type: string, text: string][];
-/** <ray-code> 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. */
+/** <ray-code> 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. */
 export declare class RayCode extends RayElement {
   /** The code, from script (the most convenient in React and Vue). Wins over the content. */
   code: string | undefined;
@@ -1899,6 +2051,8 @@ export declare class RayCode extends RayElement {
   highlight: string | undefined;
   /** Wraps long lines instead of scrolling sideways. */
   wrap: boolean | undefined;
+  /** 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. */
+  verbatim: boolean | undefined;
   /** Height before it scrolls: px as a number, or a CSS length. A taller block gets a "Show all N lines" button. */
   maxHeight: string | undefined;
   /** Shown whole, past max-height. */
@@ -1938,6 +2092,8 @@ export declare class RayIcon extends RayElement {
   name: IconName | undefined;
   /** 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. */
   filled: boolean | undefined;
+  /** 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. */
+  mirror: boolean | undefined;
   /** xs…xl or any CSS length. Default: 1em. */
   size: string | undefined;
   /** Accessible name; without it the icon is decorative (hidden from screen readers). */
@@ -2063,8 +2219,8 @@ export interface RayTableEventMap extends HTMLElementEventMap {
 export declare class RayTimeline extends RayElement {
   /** Index of the last reached item (-1: none). */
   active: number;
-  /** Side of the line. */
-  align: "left" | "right";
+  /** Side of the line: start/end follow the writing direction; left/right are sides of the screen. */
+  align: "start" | "end" | "left" | "right";
   /** Bullet size: px as a number or a CSS length (default 20px). */
   bulletSize: string | undefined;
   /** Line width in px (default 2). */
@@ -2170,8 +2326,8 @@ export interface RayNotificationEventMap extends HTMLElementEventMap {
 }
 /** <ray-toaster> 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. */
 export declare class RayToaster extends RayElement {
-  /** Corner of the stack. */
-  position: "bottom-right" | "bottom-left" | "bottom-center" | "top-right" | "top-left" | "top-center";
+  /** Corner of the stack: -start/-end follow the writing direction; -left/-right are sides of the screen. */
+  position: "bottom-end" | "bottom-start" | "bottom-center" | "top-end" | "top-start" | "top-center" | "bottom-right" | "bottom-left" | "top-right" | "top-left";
   /** Maximum kept; the oldest go first. */
   limit: number;
   /** Toasts shown in the collapsed stack (the rest wait, hidden). */
@@ -2430,9 +2586,9 @@ export declare class RayScrollArea extends RayElement {
   label: string | undefined;
   /** The scrolling element (scrollTop, scrollTo…). */
   readonly viewport: HTMLElement;
-  /** Scrolls to the top (left). */
+  /** Scrolls to the start: the top, or the left when horizontal (the right right to left). */
   scrollToStart(options?: { behavior?: ScrollBehavior }): void;
-  /** Scrolls to the bottom (right when horizontal). */
+  /** Scrolls to the end: the bottom, or the right when horizontal (the left right to left). */
   scrollToEnd(options?: { behavior?: ScrollBehavior }): void;
   addEventListener<K extends keyof RayScrollAreaEventMap>(type: K, listener: (this: RayScrollArea, ev: RayScrollAreaEventMap[K]) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
@@ -2440,8 +2596,8 @@ export declare class RayScrollArea extends RayElement {
   removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
 }
 export interface RayScrollAreaEventMap extends HTMLElementEventMap {
-  /** The end came within threshold (once per arrival). */
-  "ray-reach-end": CustomEvent<{ edge: "bottom" | "right" }>;
+  /** The end came within threshold (once per arrival): the bottom, or the right when horizontal (the left right to left). */
+  "ray-reach-end": CustomEvent<{ edge: "bottom" | "right" | "left" }>;
 }
 
 // --- Separator (separator)
@@ -2451,8 +2607,8 @@ export declare class RaySeparator extends RayElement {
   orientation: "horizontal" | "vertical";
   /** Text in the middle of a horizontal rule. */
   label: string | undefined;
-  /** Where the label sits. */
-  labelPosition: "left" | "center" | "right";
+  /** Where the label sits: start/end follow the writing direction; left/right are sides of the screen. */
+  labelPosition: "start" | "center" | "end" | "left" | "right";
   /** Thickness (1–5px). */
   size: "xs" | "sm" | "md" | "lg" | "xl";
   /** Line style. */
@@ -2474,7 +2630,7 @@ export declare class RaySplit extends RayElement {
   collapsed: boolean | undefined;
   /** The divider cannot be moved. */
   disabled: boolean | undefined;
-  /** A key: the size is saved in localStorage and restored. */
+  /** A key: the size and the collapsed state are saved in localStorage and restored (a saved state wins over the collapsed attribute). */
   autosave: string | undefined;
   /** The start pane's size in px. */
   readonly size: number;
@@ -2550,6 +2706,7 @@ declare global {
     "ray-calendar": RayCalendar;
     "ray-file-upload": RayFileUpload;
     "ray-input": RayInput;
+    "ray-mode-input": RayModeInput;
     "ray-number-input": RayNumberInput;
     "ray-password-input": RayPasswordInput;
     "ray-path-input": RayPathInput;
@@ -2566,6 +2723,8 @@ declare global {
     "ray-bottom-nav-item": RayBottomNavItem;
     "ray-breadcrumbs": RayBreadcrumbs;
     "ray-breadcrumb": RayBreadcrumb;
+    "ray-doc-tabs": RayDocTabs;
+    "ray-doc-tab": RayDocTab;
     "ray-nav-link": RayNavLink;
     "ray-pagination": RayPagination;
     "ray-sidebar": RaySidebar;