@raylang/elements 0.5.1 → 0.6.0

package/components/number-input/number-input.js

@@ -2,7 +2,8 @@
 // buttons (hold to repeat), the arrow keys (Shift: ×10), min/max/step,
 // a fixed number of decimals, a prefix and a suffix ("$", " kg") and a
 // thousands separator in the shown text. The value is a number (or empty);
-// the form gets its plain digits.
+// the form gets its plain digits. format="duration": the value is seconds,
+// shown and typed as m:ss (h:mm:ss from an hour).
 //
 // An ARIA spinbutton: aria-valuenow/min/max/valuetext on the text field.
 
@@ -60,6 +61,36 @@ export function formatNumber(n, { decimals, thousands = "", decimal = "." } = {}
   return frac !== undefined ? `${int}${decimal}${frac}` : int;
 }
 
+/** Seconds as m:ss, or h:mm:ss with `hours` (or from an hour); "" if not a number. */
+export function formatDuration(seconds, { hours = false } = {}) {
+  if (!Number.isFinite(seconds)) return "";
+  const sign = seconds < 0 ? "-" : "";
+  const t = Math.round(Math.abs(seconds));
+  const h = Math.floor(t / 3600);
+  const m = Math.floor((t % 3600) / 60);
+  const ss = String(t % 60).padStart(2, "0");
+  return hours || h > 0 ? `${sign}${h}:${String(m).padStart(2, "0")}:${ss}` : `${sign}${m}:${ss}`;
+}
+
+/** Seconds from "m:ss", "h:mm:ss" or a plain number of seconds ("3:", "3:0" while typing); NaN if none. */
+export function parseDuration(text) {
+  const m = String(text ?? "").replace(/\s+/g, "").match(/^(-?)(\d*)(?::(\d*))?(?::(\d*))?$/);
+  if (!m || (m[2] === "" && !m[3])) return NaN;
+  const parts = [m[2], m[3], m[4]].filter((p) => p !== undefined).map((p) => Number(p || 0));
+  const seconds = parts.reduce((total, p) => total * 60 + p, 0);
+  return m[1] ? -seconds : seconds;
+}
+
+/** "3 minutes, 15 seconds" in `lang` (Intl), for aria-valuetext. */
+export function durationText(seconds, lang) {
+  const t = Math.round(Math.abs(seconds));
+  const units = [["hour", Math.floor(t / 3600)], ["minute", Math.floor((t % 3600) / 60)], ["second", t % 60]];
+  const said = units.filter(([, n], i) => n > 0 || (t === 0 && i === 2));
+  const words = said.map(([unit, n]) => new Intl.NumberFormat(lang, { style: "unit", unit, unitDisplay: "long" }).format(n));
+  const text = new Intl.ListFormat(lang, { style: "long", type: "unit" }).format(words);
+  return seconds < 0 ? `-${text}` : text;
+}
+
 export class RayNumberInput extends FieldControl {
   /** Enter submits the form (core/form.js). */
   static implicitSubmission = true;
@@ -78,6 +109,7 @@ export class RayNumberInput extends FieldControl {
     placeholder: { type: String },
     hideControls: { type: Boolean, reflect: true, attribute: "hide-controls" },
     clamp: { type: String, default: "blur" },
+    format: { type: String, reflect: true, default: "number" },
     readonly: { type: Boolean, reflect: true },
   };
   static styles = [sizeStyles, radiusStyles, fieldStyles, boxStyles, styles];
@@ -135,6 +167,8 @@ export class RayNumberInput extends FieldControl {
   update() {
     const c = this.control;
     c.readOnly = Boolean(this.readonly);
+    // The number pad has no ":".
+    c.inputMode = this._duration ? "text" : "decimal";
     if (this.placeholder !== undefined) c.placeholder = this.placeholder;
     if (!this.#typing) this._paint();
     this.syncField();
@@ -162,10 +196,15 @@ export class RayNumberInput extends FieldControl {
     let v = n;
     if (this.min !== undefined && this.min !== null && v < this.min) v = this.min;
     if (this.max !== undefined && this.max !== null && v > this.max) v = this.max;
-    return this.decimals !== undefined && this.decimals !== null ? Number(v.toFixed(this.decimals)) : v;
+    return this.decimals !== undefined && this.decimals !== null && !this._duration ? Number(v.toFixed(this.decimals)) : v;
+  }
+
+  get _duration() {
+    return this.format === "duration";
   }
 
   _parse(text) {
+    if (this._duration) return parseDuration(text);
     let s = String(text ?? "");
     if (this.prefix) s = s.split(this.prefix).join("");
     if (this.suffix) s = s.split(this.suffix).join("");
@@ -184,10 +223,16 @@ export class RayNumberInput extends FieldControl {
     }
   }
 
-  // The shown text: prefix, separators, decimals, suffix.
+  // The shown text: prefix, separators, decimals, suffix; or m:ss.
   _text() {
-    if (this.value === undefined || this.value === null || !Number.isFinite(this.value)) return "";
-    const num = formatNumber(this.value, { decimals: this.decimals, thousands: this.thousandsSeparator || "", decimal: this.decimalSeparator || "." });
+    return this._show(this.value);
+  }
+
+  _show(n) {
+    if (n === undefined || n === null || !Number.isFinite(n)) return "";
+    // h:mm:ss when the range reaches an hour, so the width does not jump.
+    if (this._duration) return formatDuration(n, { hours: Math.abs(this.max ?? 0) >= 3600 || Math.abs(this.min ?? 0) >= 3600 });
+    const num = formatNumber(n, { decimals: this.decimals, thousands: this.thousandsSeparator || "", decimal: this.decimalSeparator || "." });
     return `${this.prefix ?? ""}${num}${this.suffix ?? ""}`;
   }
 
@@ -206,7 +251,8 @@ export class RayNumberInput extends FieldControl {
     set("aria-valuenow", this.value);
     set("aria-valuemin", this.min);
     set("aria-valuemax", this.max);
-    if (this.prefix || this.suffix || this.thousandsSeparator) set("aria-valuetext", this._text() || undefined);
+    if (this._duration) set("aria-valuetext", Number.isFinite(this.value) ? durationText(this.value, this.closest("[lang]")?.lang || undefined) : undefined);
+    else if (this.prefix || this.suffix || this.thousandsSeparator) set("aria-valuetext", this._text() || undefined);
     else c.removeAttribute("aria-valuetext");
   }
 
@@ -225,8 +271,8 @@ export class RayNumberInput extends FieldControl {
     const c = this.control;
     let msg = "";
     if (this.required && (this.value === undefined || this.value === null)) msg = "Please enter a number.";
-    else if (this.value !== undefined && this.min !== undefined && this.value < this.min) msg = `The minimum is ${this.min}.`;
-    else if (this.value !== undefined && this.max !== undefined && this.value > this.max) msg = `The maximum is ${this.max}.`;
+    else if (this.value !== undefined && this.min !== undefined && this.value < this.min) msg = `The minimum is ${this._show(this.min)}.`;
+    else if (this.value !== undefined && this.max !== undefined && this.value > this.max) msg = `The maximum is ${this._show(this.max)}.`;
     if (msg) this.internals.setValidity(this.value === undefined ? { valueMissing: true } : this.value < (this.min ?? -Infinity) ? { rangeUnderflow: true } : { rangeOverflow: true }, msg, c);
     else this.internals.setValidity({});
   }

package/components/radio/radio.js

@@ -3,12 +3,17 @@
 // Native radios cannot group across shadow roots, so the group owns the
 // state: it is the form control (value submitted under `name`), keeps one
 // radio checked, and moves focus and selection with the arrow keys (roving
-// tabindex), like native radios.
+// tabindex), like native radios. <ray-radio-card> is a radio drawn as a
+// card (a title, a detail, an icon), for choices that need more than a line:
+// plans, presets, shipping methods. Both can share a group.
 
 import { RayElement, css, define } from "../../core/core.js";
 import { applyColor, sizeStyles } from "../../core/styles.js";
 import { FormControl, fieldStyles } from "../../core/form.js";
 
+/** The elements a group owns: radios and radio cards. */
+const RADIOS = "ray-radio, ray-radio-card";
+
 const groupStyles = css`
   :host { --_rs: 1.25rem; }
   :host([size="xs"]) { --_rs: 1rem; }
@@ -53,7 +58,7 @@ export class RayRadioGroup extends FormControl {
     this.internals.role = "radiogroup";
     this.addEventListener("keydown", (e) => this._keydown(e));
     this.addEventListener("click", (e) => {
-      const radio = e.target.closest?.("ray-radio");
+      const radio = e.target.closest?.(RADIOS);
       if (radio && this.radios.includes(radio)) this._choose(radio, true);
     });
   }
@@ -67,9 +72,9 @@ export class RayRadioGroup extends FormControl {
     }
   }
 
-  /** The radios of this group (direct or nested, not in a nested group). */
+  /** The radios (and radio cards) of this group (direct or nested, not in a nested group). */
   get radios() {
-    return [...this.querySelectorAll("ray-radio")].filter((r) => r.closest("ray-radio-group") === this);
+    return [...this.querySelectorAll(RADIOS)].filter((r) => r.closest("ray-radio-group") === this);
   }
 
   update() {
@@ -129,7 +134,7 @@ export class RayRadioGroup extends FormControl {
 
   _keydown(e) {
     const radios = this.radios.filter((r) => !r.disabled);
-    const i = radios.indexOf(e.target.closest?.("ray-radio"));
+    const i = radios.indexOf(e.target.closest?.(RADIOS));
     if (i < 0) return;
     let next = null;
     if (e.key === "ArrowDown" || e.key === "ArrowRight") next = radios[(i + 1) % radios.length];
@@ -217,11 +222,28 @@ export class RayRadio extends RayElement {
     this._groupDisabled = false;
   }
 
-  /** Whether this radio is the group's choice (read-only: set the group's value). */
+  /** Whether this radio is the group's choice. Setting it sets the group's
+   * value, like `checked` on a native radio (no events). */
   get checked() {
     return this._checked;
   }
 
+  set checked(on) {
+    on = Boolean(on);
+    const group = this.closest("ray-radio-group");
+    if (!group) {
+      this._setChecked(on);
+      return;
+    }
+    if (on) {
+      group.value = this.value;
+      for (const r of group.radios) r._setChecked(r === this);
+    } else if (this._checked) {
+      group.value = undefined;
+      this._setChecked(false);
+    }
+  }
+
   _setChecked(on) {
     this._checked = on;
     this.toggleAttribute("data-checked", on);
@@ -249,5 +271,63 @@ export class RayRadio extends RayElement {
   }
 }
 
+const cardStyles = css`
+  :host { --_s: var(--_rs, 1.125rem); }
+  .root {
+    align-items: flex-start;
+    gap: var(--ray-space-3);
+    height: 100%;
+    box-sizing: border-box;
+    padding: var(--ray-space-3) var(--ray-space-4);
+    background: var(--ray-background);
+    border: 1px solid var(--ray-border);
+    border-radius: var(--ray-radius-default);
+    transition: background-color var(--ray-duration-fast) var(--ray-easing-standard), border-color var(--ray-duration-fast) var(--ray-easing-standard);
+  }
+  :host(:not([data-disabled])) .root:hover { background: var(--ray-default-hover); }
+  :host([data-checked]) .root, :host([data-checked]) .root:hover {
+    background: var(--_light, var(--ray-primary-light));
+    border-color: var(--_filled, var(--ray-primary-filled));
+  }
+  :host(:focus-visible) .root { outline: var(--ray-focus-ring-width) solid var(--ray-ring); outline-offset: var(--ray-focus-ring-offset); }
+  :host(:focus-visible) .indicator { outline: none; }
+  :host([data-disabled]) .root { background: var(--ray-muted); opacity: 0.6; }
+  .body { flex: 1; min-width: 0; min-height: 0; }
+  .label { font-weight: var(--ray-font-weight-semibold); }
+  .icon { display: inline-flex; flex: none; color: var(--_filled, var(--ray-primary-filled)); font-size: 1.25rem; line-height: 1; }
+  .extra { margin-top: var(--ray-space-2); font-size: var(--ray-font-size-sm); }
+  :host([hide-indicator]) .indicator { display: none; }
+`;
+
+export class RayRadioCard extends RayRadio {
+  static properties = {
+    ...RayRadio.properties,
+    hideIndicator: { type: Boolean, reflect: true, attribute: "hide-indicator" },
+  };
+  static styles = [radioStyles, cardStyles];
+  static template = `
+    <div class="root" part="root">
+      <span class="icon" part="icon" hidden><slot name="icon"></slot></span>
+      <span class="body">
+        <span class="label" part="label"><span class="label-text"></span></span>
+        <span class="description" part="description" hidden></span>
+        <span class="extra" hidden><slot></slot></span>
+      </span>
+      <span class="indicator" part="indicator"><span class="dot"></span></span>
+    </div>`;
+
+  constructor() {
+    super();
+    // The icon and the extra content take room only when given.
+    for (const slot of this.shadowRoot.querySelectorAll("slot")) {
+      slot.addEventListener("slotchange", () => {
+        const given = slot.assignedNodes().some((n) => n.nodeType === Node.ELEMENT_NODE || n.textContent.trim());
+        slot.parentElement.hidden = !given;
+      });
+    }
+  }
+}
+
 define("ray-radio-group", RayRadioGroup);
 define("ray-radio", RayRadio);
+define("ray-radio-card", RayRadioCard);

package/components/ring-progress/ring-progress.js

@@ -0,0 +1,127 @@
+// <ray-ring-progress>: progress as a ring (Mantine's RingProgress), with
+// room in the middle for content (a countdown's clock, a percentage).
+//
+// The arc is a stroke-dasharray on a circle with pathLength=100, drawn from
+// 12 o'clock clockwise; r is a CSS length (half the box minus half the
+// stroke), so any size and thickness need no viewBox arithmetic.
+
+import { RayElement, css, define } from "../../core/core.js";
+import { applyColor } from "../../core/styles.js";
+
+const SIZES = { xs: "3rem", sm: "5rem", md: "7.5rem", lg: "10rem", xl: "12.5rem" };
+
+const styles = css`
+  :host {
+    --_d: 7.5rem;
+    --_t: calc(var(--_d) / 10);
+    position: relative;
+    display: inline-grid;
+    /* One cell of exactly the diameter: the svg's intrinsic 300×150 must not size it. */
+    grid-template: minmax(0, 1fr) / minmax(0, 1fr);
+    vertical-align: middle;
+    width: var(--_d);
+    height: var(--_d);
+    flex: none;
+  }
+  svg {
+    grid-area: 1 / 1;
+    width: 100%;
+    height: 100%;
+    overflow: visible;
+    transform: rotate(-90deg);
+  }
+  circle {
+    cx: 50%;
+    cy: 50%;
+    r: calc(50% - var(--_t) / 2);
+    fill: none;
+    stroke-width: var(--_t);
+  }
+  .track { stroke: var(--ray-muted); }
+  .bar {
+    stroke: var(--_filled);
+    stroke-dasharray: var(--_pct, 0) 100;
+    transition: stroke-dasharray var(--ray-duration-slow) var(--ray-easing-standard);
+  }
+  :host([round-caps]) .bar { stroke-linecap: round; }
+  /* A round cap draws a dot at 0. */
+  .bar[data-empty] { visibility: hidden; }
+  svg[data-indeterminate] { animation: ray-ring-spin 1.2s linear infinite; }
+  svg[data-indeterminate] .bar { transition: none; }
+  @keyframes ray-ring-spin { from { transform: rotate(-90deg); } to { transform: rotate(270deg); } }
+  .center {
+    grid-area: 1 / 1;
+    display: grid;
+    place-items: center;
+    padding: calc(var(--_t) * 1.5);
+    min-width: 0;
+    text-align: center;
+    font-size: max(var(--ray-font-size-xs), calc(var(--_d) * 0.16));
+    font-variant-numeric: tabular-nums;
+    line-height: 1.1;
+  }
+  .value { font-weight: var(--ray-font-weight-semibold); }
+  .value:empty { display: none; }
+`;
+
+export class RayRingProgress extends RayElement {
+  static properties = {
+    value: { type: Number },
+    max: { type: Number, default: 100 },
+    color: { type: String, reflect: true },
+    size: { type: String, reflect: true, default: "md" },
+    thickness: { type: String, reflect: true },
+    roundCaps: { type: Boolean, reflect: true, attribute: "round-caps" },
+    showValue: { type: Boolean, reflect: true, attribute: "show-value" },
+    label: { type: String },
+  };
+  static styles = [styles];
+  static template = `<svg aria-hidden="true"><circle class="track" part="track" pathLength="100"></circle><circle class="bar" part="bar" pathLength="100"></circle></svg><div class="center" part="center"><slot></slot><span class="value" aria-hidden="true"></span></div>`;
+
+  constructor() {
+    super();
+    this.internals = this.attachInternals();
+    this.internals.role = "progressbar";
+  }
+
+  update() {
+    const svg = this.$("svg");
+    const bar = this.$(".bar");
+    applyColor(svg, this.color);
+    // size: xs…xl or a length; thickness: a length (a bare number is px).
+    const d = SIZES[this.size] ?? this.size ?? "";
+    if (d) this.style.setProperty("--_d", d);
+    else this.style.removeProperty("--_d");
+    const t = this.thickness ? (/^\d*\.?\d+$/.test(this.thickness) ? `${this.thickness}px` : this.thickness) : "";
+    if (t) this.style.setProperty("--_t", t);
+    else this.style.removeProperty("--_t");
+
+    const max = this.max > 0 ? this.max : 100;
+    const indeterminate = this.value === undefined || this.value === null || Number.isNaN(this.value);
+    svg.toggleAttribute("data-indeterminate", indeterminate);
+    const pct = indeterminate ? 0 : Math.min(100, Math.max(0, (this.value / max) * 100));
+    // Indeterminate: a quarter arc that spins.
+    bar.style.setProperty("--_pct", String(indeterminate ? 25 : pct));
+    bar.toggleAttribute("data-empty", !indeterminate && pct === 0);
+    // The percentage in the middle only when the app puts nothing there.
+    const empty = this.$("slot").assignedNodes().every((n) => n.nodeType === Node.TEXT_NODE && !n.textContent.trim());
+    this.$(".value").textContent = this.showValue && !indeterminate && empty ? `${Math.round(pct)}%` : "";
+
+    const i = this.internals;
+    i.ariaValueMin = "0";
+    i.ariaValueMax = String(max);
+    i.ariaValueNow = indeterminate ? null : String(this.value);
+    i.ariaValueText = indeterminate ? null : `${Math.round(pct)}%`;
+    i.ariaLabel = this.label || this.getAttribute("aria-label") || "Progress";
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (!this._wired) {
+      this._wired = true;
+      this.$("slot").addEventListener("slotchange", () => this.requestUpdate());
+    }
+  }
+}
+
+define("ray-ring-progress", RayRingProgress);

package/components/step-dots/step-dots.js

@@ -0,0 +1,86 @@
+// <ray-step-dots>: a row of dots, one per step: done (filled), the current
+// one (a filled pill), the rest (empty). A compact progress for rounds,
+// onboarding pages or a quiz. Not interactive: the carousel's dots are
+// buttons, these are a progressbar.
+
+import { RayElement, css, define } from "../../core/core.js";
+import { applyColor } from "../../core/styles.js";
+
+const styles = css`
+  :host {
+    --_dot: 0.5rem;
+    display: block;
+  }
+  :host([size="xs"]) { --_dot: 0.3125rem; }
+  :host([size="md"]) { --_dot: 0.625rem; }
+  :host([size="lg"]) { --_dot: 0.75rem; }
+  :host([size="xl"]) { --_dot: 1rem; }
+  .dots {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: var(--_justify, center);
+    gap: calc(var(--_dot) * 0.75);
+  }
+  :host([align="start"]) { --_justify: flex-start; }
+  :host([align="end"]) { --_justify: flex-end; }
+  .dot {
+    flex: none;
+    width: var(--_dot);
+    height: var(--_dot);
+    box-sizing: border-box;
+    border-radius: var(--ray-radius-full);
+    border: 1.5px solid color-mix(in srgb, var(--ray-foreground) 28%, transparent);
+    transition: width var(--ray-duration-base) var(--ray-easing-standard), background-color var(--ray-duration-base) var(--ray-easing-standard), border-color var(--ray-duration-base) var(--ray-easing-standard);
+  }
+  .dot[data-state="done"] { background: var(--_filled); border-color: var(--_filled); }
+  .dot[data-state="current"] { width: calc(var(--_dot) * 2.5); background: var(--_filled); border-color: var(--_filled); }
+`;
+
+export class RayStepDots extends RayElement {
+  static properties = {
+    count: { type: Number, default: 0 },
+    value: { type: Number, default: 0 },
+    color: { type: String, reflect: true },
+    size: { type: String, reflect: true, default: "sm" },
+    align: { type: String, reflect: true, default: "center" },
+    label: { type: String },
+  };
+  static styles = [styles];
+  static template = `<div class="dots" part="dots" aria-hidden="true"></div>`;
+
+  constructor() {
+    super();
+    this.internals = this.attachInternals();
+    this.internals.role = "progressbar";
+  }
+
+  update() {
+    applyColor(this, this.color);
+    const count = Math.max(0, Math.floor(this.count || 0));
+    // value: the current step, 0-based; count (or more) is all done.
+    const value = Math.min(count, Math.max(0, Math.floor(this.value || 0)));
+    const box = this.$(".dots");
+    while (box.children.length < count) {
+      const dot = document.createElement("span");
+      dot.className = "dot";
+      dot.setAttribute("part", "dot");
+      box.append(dot);
+    }
+    while (box.children.length > count) box.lastElementChild.remove();
+    [...box.children].forEach((dot, i) => {
+      dot.dataset.state = i < value ? "done" : i === value ? "current" : "todo";
+    });
+
+    const noun = this.label || "Step";
+    const done = count > 0 && value >= count;
+    const i = this.internals;
+    i.ariaLabel = this.label || this.getAttribute("aria-label") || "Steps";
+    i.ariaValueMin = "0";
+    i.ariaValueMax = String(count);
+    i.ariaValueNow = String(value);
+    i.ariaValueText = count === 0 ? null : done ? `${count} of ${count}, done` : `${noun} ${value + 1} of ${count}`;
+  }
+}
+
+define("ray-step-dots", RayStepDots);