@raylang/elements 0.5.2 → 0.7.0

package/index.js

@@ -19,7 +19,7 @@ export { RayInput } from "./components/input/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";
-export { RayRadioGroup, RayRadio } from "./components/radio/radio.js";
+export { RayRadioGroup, RayRadio, RayRadioCard } from "./components/radio/radio.js";
 export { RaySearch } from "./components/search/search.js";
 export { RaySegmentedControl } from "./components/segmented-control/segmented-control.js";
 export { RaySelect } from "./components/select/select.js";
@@ -56,8 +56,10 @@ export { RayAlert } from "./components/alert/alert.js";
 export { RayEmptyState } from "./components/empty-state/empty-state.js";
 export { RayNotification, RayToaster, notify, updateNotification, hideNotification, clearNotifications, statusIcon } from "./components/notification/notification.js";
 export { RayProgress } from "./components/progress/progress.js";
+export { RayRingProgress } from "./components/ring-progress/ring-progress.js";
 export { RaySkeleton } from "./components/skeleton/skeleton.js";
 export { RaySpinner } from "./components/spinner/spinner.js";
+export { RayStepDots } from "./components/step-dots/step-dots.js";
 export { RayAppBar } from "./components/app-bar/app-bar.js";
 export { RayAppShell } from "./components/app-shell/app-shell.js";
 export { RayAspectRatio, parseRatio } from "./components/aspect-ratio/aspect-ratio.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.5.2.
+> 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.
 
 ray-elements is a design system of standard web components (custom elements
 with Shadow DOM, no dependencies): `<ray-button>`, `<ray-input>`,
@@ -75,7 +75,14 @@ reference of every component follows them.
   (`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.
+  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).
 - **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`.
@@ -292,7 +299,7 @@ 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`, default `sm`, reflects. Height, padding and font size.
+- `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).
@@ -354,7 +361,7 @@ Properties:
 - `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`, default `sm`, reflects. Width and height.
+- `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.
 
@@ -911,7 +918,7 @@ Vue `v-model`: `value` (updated on input).
 
 ### 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. An ARIA spinbutton.
+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
 
@@ -931,6 +938,7 @@ Properties:
 - `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.
@@ -1052,7 +1060,7 @@ for e in ui.events() {
 
 ### Radio group
 
-One choice among options: ray-radio elements inside a ray-radio-group, which is the form control.
+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
 
@@ -1082,11 +1090,11 @@ Events:
 
 Slots:
 
-- (default): ray-radio elements (may be wrapped in layout elements).
+- (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 of the group.
+- `readonly radios: RayRadio[]`: The radios (and radio cards) of the group.
 
 Vue `v-model`: `value` (updated on change).
 
@@ -1112,6 +1120,26 @@ 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.
@@ -1427,7 +1455,7 @@ Properties:
 
 - `value`: string, reflects. Its value (default: its href, else its label).
 - `label`: string. The label.
-- `icon`: string. An icon of the registry (or put one in the icon slot).
+- `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).
@@ -2313,7 +2341,7 @@ Properties:
 - `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`: string, default `quote`. Registry icon of the mark, or none. The icon slot replaces it.
+- `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).
@@ -2440,11 +2468,12 @@ 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. Sizes follow the font unless size; --ray-icon-size and --ray-icon-stroke tune the whole system.
+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`: string, reflects. Registered icon name (iconNames()); "none" draws nothing, a blank that keeps the alignment (a menu item without its check).
+- `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.
 - `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.
@@ -2454,6 +2483,10 @@ 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.
@@ -2616,7 +2649,7 @@ Properties:
 
 - `label`: string. The title of the event.
 - `time`: string. When ("2 h ago", a date).
-- `icon`: string. An icon of the registry in the bullet.
+- `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).
 
@@ -2649,7 +2682,7 @@ Properties:
 - `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`: string, reflects. A registered icon name, or none.
+- `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.
 
@@ -2701,7 +2734,7 @@ Properties:
 
 - `label`: string. Title.
 - `color`: string, reflects. Status color: tints the status icon (and a slotted icon's circle).
-- `icon`: string. Status icon from the registry (default: from the color); "none" for no icon.
+- `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.
@@ -2777,6 +2810,37 @@ Parts (`::part()`):
 - `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.
@@ -2824,6 +2888,32 @@ 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.
@@ -3447,7 +3537,11 @@ breakpoint:
 
 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`, `pipette`, `star`, `upload`, `paperclip`, `panel-left`, `settings`, `home`, `arrow-left`, `message-circle`
+`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
 
@@ -3508,12 +3602,14 @@ export declare function getCustomPrimary(el?: Element): string | null;
 
 // --- icons -------------------------------------------------------------------
 
-/** Replaces or adds icons (SVG markup or an SVGElement); repaints every component. */
+/** 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). */
-export declare function getIcon(name: string): string;
-/** The registered icon names. */
-export declare function iconNames(): string[];
+/** 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 ------------------------------------------------------------
 

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.5.2.
+> 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.
 
 ray-elements is a design system of standard web components (custom elements
 with Shadow DOM, no dependencies): `<ray-button>`, `<ray-input>`,
@@ -75,7 +75,14 @@ reference of every component follows them.
   (`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.
+  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).
 - **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`.
@@ -268,10 +275,10 @@ 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).
-- [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.
+- [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.
-- [Radio group](https://elements.raylang.dev/components/radio.md): `<ray-radio-group>`, `<ray-radio>` (Inputs). One choice among options: ray-radio elements inside a ray-radio-group, which is the form control.
+- [Radio group](https://elements.raylang.dev/components/radio.md): `<ray-radio-group>`, `<ray-radio>`, `<ray-radio-card>` (Inputs). One choice among options: ray-radio (or ray-radio-card) elements inside a ray-radio-group, which is the form control.
 - [Search](https://elements.raylang.dev/components/search.md): `<ray-search>` (Inputs). A search box: icon, clear button, an optional shortcut that focuses it, and a debounced ray-search event.
 - [Segmented control](https://elements.raylang.dev/components/segmented-control.md): `<ray-segmented-control>` (Inputs). One choice among a few, as a segmented row with a sliding indicator.
 - [Select](https://elements.raylang.dev/components/select.md): `<ray-select>` (Inputs). A select with its own dropdown (keyboard, typeahead, groups); options from child <option> elements or the data property.
@@ -308,8 +315,10 @@ Members whose name starts with `_` are internal.
 - [Empty state](https://elements.raylang.dev/components/empty-state.md): `<ray-empty-state>` (Feedback). What a list, table or pane shows when it is empty: icon, title, text and the action that fills it.
 - [Notification](https://elements.raylang.dev/components/notification.md): `<ray-notification>`, `<ray-toaster>` (Feedback). Toasts: notify(), updateNotification(), hideNotification(), clearNotifications(); shown in a ray-toaster (a polite live region in the top layer).
 - [Progress](https://elements.raylang.dev/components/progress.md): `<ray-progress>` (Feedback). A determinate or (without value) indeterminate progress bar, announced as a progressbar.
+- [Ring progress](https://elements.raylang.dev/components/ring-progress.md): `<ray-ring-progress>` (Feedback). Progress as a ring (Mantine's RingProgress), with content in the middle: a countdown, a goal, an upload.
 - [Skeleton](https://elements.raylang.dev/components/skeleton.md): `<ray-skeleton>` (Feedback). A placeholder while content loads: a shimmering block, a circle or text lines; with loaded it shows its content.
 - [Spinner](https://elements.raylang.dev/components/spinner.md): `<ray-spinner>` (Feedback). An indeterminate loading indicator, announced as a status.
+- [Step dots](https://elements.raylang.dev/components/step-dots.md): `<ray-step-dots>` (Feedback). A row of dots, one per step: done, current, to do.
 - [App bar](https://elements.raylang.dev/components/app-bar.md): `<ray-app-bar>` (Layout). 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.
 - [App shell](https://elements.raylang.dev/components/app-shell.md): `<ray-app-shell>` (Layout). 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.
 - [Aspect ratio](https://elements.raylang.dev/components/aspect-ratio.md): `<ray-aspect-ratio>` (Layout). A box with a fixed width/height ratio; its image, video or iframe fills it.
@@ -327,7 +336,11 @@ Members whose name starts with `_` are internal.
 
 ## Icons
 
-`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`, `pipette`, `star`, `upload`, `paperclip`, `panel-left`, `settings`, `home`, `arrow-left`, `message-circle`
+`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)
 
 ## Reference
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raylang/elements",
-  "version": "0.5.2",
+  "version": "0.7.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"],
@@ -244,6 +244,10 @@
       "types": "./ray-elements.d.ts",
       "default": "./components/progress/progress.js"
     },
+    "./ring-progress": {
+      "types": "./ray-elements.d.ts",
+      "default": "./components/ring-progress/ring-progress.js"
+    },
     "./skeleton": {
       "types": "./ray-elements.d.ts",
       "default": "./components/skeleton/skeleton.js"
@@ -252,6 +256,10 @@
       "types": "./ray-elements.d.ts",
       "default": "./components/spinner/spinner.js"
     },
+    "./step-dots": {
+      "types": "./ray-elements.d.ts",
+      "default": "./components/step-dots/step-dots.js"
+    },
     "./app-bar": {
       "types": "./ray-elements.d.ts",
       "default": "./components/app-bar/app-bar.js"

package/ray-elements.d.ts

@@ -54,12 +54,14 @@ export declare function getCustomPrimary(el?: Element): string | null;
 
 // --- icons -------------------------------------------------------------------
 
-/** Replaces or adds icons (SVG markup or an SVGElement); repaints every component. */
+/** 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). */
-export declare function getIcon(name: string): string;
-/** The registered icon names. */
-export declare function iconNames(): string[];
+/** 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 ------------------------------------------------------------
 
@@ -361,8 +363,8 @@ export declare class RayButton extends RayElement {
   gradient: string | undefined;
   /** A palette color (blue, red…) or any CSS color. Default: the primary color. */
   color: string | undefined;
-  /** Height, padding and font size. */
-  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Height, padding and font size: xs…xl or any CSS length (the padding and the font follow). */
+  size: "xs" | "sm" | "md" | "lg" | "xl" | (string & {});
   /** Corner radius. Default: --ray-radius-default. */
   radius: "xs" | "sm" | "md" | "lg" | "xl" | "full" | undefined;
   /** submit/reset act on the enclosing form. */
@@ -407,8 +409,8 @@ export declare class RayIconButton extends RayButton {
   gradient: string | undefined;
   /** A palette color or any CSS color. */
   color: string | undefined;
-  /** Width and height. */
-  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Width and height: xs…xl or any CSS length ("5.5rem": a big main action, round with radius=full); the icon scales with it. */
+  size: "xs" | "sm" | "md" | "lg" | "xl" | (string & {});
   /** Not interactive. */
   disabled: boolean | undefined;
   /** Shows a spinner instead of the icon. */
@@ -865,6 +867,8 @@ export declare class RayNumberInput extends FieldControl {
   decimalSeparator: string;
   /** When out-of-range input is clamped: on blur, while typing, or never (then it is invalid). */
   clamp: "blur" | "strict" | "none";
+  /** 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. */
+  format: "number" | "duration";
   /** No + and − buttons (the keys still step). */
   hideControls: boolean | undefined;
   /** Shown while empty. */
@@ -950,10 +954,10 @@ export declare class RayRadioGroup extends FormControl {
   color: string | undefined;
   /** Checked look of every radio: filled circle, or colored ring and dot. */
   variant: "filled" | "outline";
-  /** The radios of the group. */
+  /** The radios (and radio cards) of the group. */
   readonly radios: RayRadio[];
 }
-/** <ray-radio> One choice among options: ray-radio elements inside a ray-radio-group, which is the form control. */
+/** <ray-radio> One choice among options: ray-radio (or ray-radio-card) elements inside a ray-radio-group, which is the form control. */
 export declare class RayRadio extends RayElement {
   /** Value given to the group when chosen. */
   value: string | undefined;
@@ -972,6 +976,11 @@ export declare class RayRadio extends RayElement {
   /** Overrides the group variant. */
   variant: "filled" | "outline" | undefined;
 }
+/** <ray-radio-card> 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. */
+export declare class RayRadioCard extends RayRadio {
+  /** No radio circle: the card's border and background alone show the choice. */
+  hideIndicator: boolean | undefined;
+}
 
 // --- Search (search)
 /** <ray-search> Escape clears it (when it has text); Enter fires ray-search at once. JS: clear(), focus(). */
@@ -1209,8 +1218,8 @@ export declare class RayBottomNavItem extends RayElement {
   value: string | undefined;
   /** The label. */
   label: string | undefined;
-  /** An icon of the registry (or put one in the icon slot). */
-  icon: string | undefined;
+  /** 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). */
+  icon: IconName | undefined;
   /** Makes it a link. */
   href: string | undefined;
   /** A count or a short text on the icon. */
@@ -1825,7 +1834,7 @@ export declare class RayBlockquote extends RayElement {
   /** light: tinted background; outline: border and edge only; filled: solid color (a pull quote). */
   variant: "light" | "outline" | "filled";
   /** Registry icon of the mark, or none. The icon slot replaces it. */
-  icon: string;
+  icon: IconName;
   /** Text size (lg for a pull quote). */
   size: "sm" | "md" | "lg";
   /** Inner spacing: xs…xl (the spacing scale), px as a number, or a CSS length. Default: md. */
@@ -1921,10 +1930,14 @@ export interface RayCodeEventMap extends HTMLElementEventMap {
 }
 
 // --- Icon (icon)
-/** <ray-icon> setIcons({ name: '<svg…>' }) replaces or adds icons (SVG markup or an SVGElement, drawn with currentColor); iconNames() lists them. Sizes follow the font unless size; --ray-icon-size and --ray-icon-stroke tune the whole system. */
+/** An icon name: one of the default set, or any name an app registers with setIcons(). */
+export type IconName = "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 & {});
+/** <ray-icon> 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. */
 export declare class RayIcon extends RayElement {
   /** Registered icon name (iconNames()); "none" draws nothing, a blank that keeps the alignment (a menu item without its check). */
-  name: string | undefined;
+  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;
   /** xs…xl or any CSS length. Default: 1em. */
   size: string | undefined;
   /** Accessible name; without it the icon is decorative (hidden from screen readers). */
@@ -2070,7 +2083,7 @@ export declare class RayTimelineItem extends RayElement {
   /** When ("2 h ago", a date). */
   time: string | undefined;
   /** An icon of the registry in the bullet. */
-  icon: string | undefined;
+  icon: IconName | undefined;
   /** Its own color (a failed step in red). */
   color: string | undefined;
   /** The line to the next item (dashed: not happened yet). */
@@ -2089,7 +2102,7 @@ export declare class RayAlert extends RayElement {
   /** Corner radius. */
   radius: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
   /** A registered icon name, or none. */
-  icon: string | undefined;
+  icon: IconName | undefined;
   /** A close button; closing hides the alert (cancel ray-close to keep it). */
   closable: boolean | undefined;
   /** Accessible name of the close button. */
@@ -2135,7 +2148,7 @@ export declare class RayNotification extends RayElement {
   /** Status color: tints the status icon (and a slotted icon's circle). */
   color: string | undefined;
   /** Status icon from the registry (default: from the color); "none" for no icon. */
-  icon: string | undefined;
+  icon: IconName | undefined;
   /** Shows a spinner (notify() does not auto-close it). */
   loading: boolean | undefined;
   /** No close button. */
@@ -2198,6 +2211,27 @@ export declare class RayProgress extends RayElement {
   label: string | undefined;
 }
 
+// --- Ring progress (ring-progress)
+/** <ray-ring-progress> 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. */
+export declare class RayRingProgress extends RayElement {
+  /** Progress, from 0 to max. Unset: indeterminate (a spinning arc). */
+  value: number | undefined;
+  /** The value of a full ring. */
+  max: number;
+  /** A palette color or any CSS color. Default: the primary color. */
+  color: string | undefined;
+  /** Diameter: xs…xl (3, 5, 7.5, 10, 12.5rem) or any CSS length. */
+  size: "xs" | "sm" | "md" | "lg" | "xl" | (string & {});
+  /** Width of the ring: a CSS length (a bare number is px). Default: a tenth of the diameter. */
+  thickness: string | undefined;
+  /** Rounded ends of the arc. */
+  roundCaps: boolean | undefined;
+  /** Shows the percentage in the middle (when the default slot is empty). */
+  showValue: boolean | undefined;
+  /** Accessible name (default: Progress). */
+  label: string | undefined;
+}
+
 // --- Skeleton (skeleton)
 /** <ray-skeleton> aria-busy="true" on the host while loading; the placeholder is aria-hidden. */
 export declare class RaySkeleton extends RayElement {
@@ -2228,6 +2262,27 @@ export declare class RaySpinner extends RayElement {
   label: string;
 }
 
+// --- Step dots (step-dots)
+/** <ray-step-dots> 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. */
+export declare class RayStepDots extends RayElement {
+  /** Number of steps (dots). */
+  count: number;
+  /** The current step, 0-based; count means every step is done. */
+  value: number;
+  /** A palette color or any CSS color for done and current dots. Default: the primary color. */
+  color: string | undefined;
+  /** Size of a dot. */
+  size: "xs" | "sm" | "md" | "lg" | "xl";
+  /** Where the row sits in its width. */
+  align: "start" | "center" | "end";
+  /** 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. */
+  label: string | undefined;
+  /** 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}". */
+  valueText: string | undefined;
+  /** The announced text once every step is done (value = count), with {count}. Default: value-text, else "{count} of {count}, done". */
+  doneText: string | undefined;
+}
+
 // --- App bar (app-bar)
 /** <ray-app-bar> 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. */
 export declare class RayAppBar extends RayElement {
@@ -2500,6 +2555,7 @@ declare global {
     "ray-path-input": RayPathInput;
     "ray-radio-group": RayRadioGroup;
     "ray-radio": RayRadio;
+    "ray-radio-card": RayRadioCard;
     "ray-search": RaySearch;
     "ray-segmented-control": RaySegmentedControl;
     "ray-select": RaySelect;
@@ -2549,8 +2605,10 @@ declare global {
     "ray-notification": RayNotification;
     "ray-toaster": RayToaster;
     "ray-progress": RayProgress;
+    "ray-ring-progress": RayRingProgress;
     "ray-skeleton": RaySkeleton;
     "ray-spinner": RaySpinner;
+    "ray-step-dots": RayStepDots;
     "ray-app-bar": RayAppBar;
     "ray-app-shell": RayAppShell;
     "ray-aspect-ratio": RayAspectRatio;