@raylang/elements 0.0.0-stage → 0.4.0

package/core/floating.js

@@ -0,0 +1,195 @@
+// Base class of trigger + floating panel components (popover, menu, tooltip).
+//
+// The panel is a [popover] element in the shadow root, so it renders in the
+// top layer (above dialogs, never clipped by overflow). It is a manual
+// popover with light dismiss done in core/dismiss.js (Escape, outside
+// clicks, one open at a time): closing is always ours, so it can animate
+// out. The trigger is the element slotted into slot="trigger".
+
+import { RayElement, css } from "./core.js";
+import { place, autoUpdate } from "./position.js";
+import { dismissable } from "./dismiss.js";
+import { play, POP_OUT } from "./motion.js";
+
+export const floatingStyles = css`
+  :host { display: inline-block; }
+  .panel {
+    box-sizing: border-box;
+    max-width: calc(100vw - 16px);
+    max-height: calc(100vh - 16px);
+    overflow: auto;
+    padding: 0;
+    margin: 0;
+    color: var(--ray-popover-foreground);
+    background: var(--ray-popover);
+    border: 1px solid var(--ray-border);
+    border-radius: var(--ray-radius-default);
+    box-shadow: var(--ray-shadow-md);
+  }
+  .panel:popover-open { animation: ray-pop-in var(--ray-duration-fast) var(--ray-easing-out); }
+  @keyframes ray-pop-in { from { opacity: 0; transform: scale(0.97); } }
+`;
+
+export class Floating extends RayElement {
+  static properties = {
+    open: { type: Boolean, reflect: true },
+    placement: { type: String, reflect: true, default: "bottom" },
+    offset: { type: Number, default: 8 },
+  };
+  /** popover attribute of the panel ("manual": closing is handled here). */
+  static popoverMode = "manual";
+  /** Close on Escape and outside clicks (tooltips: false). */
+  static lightDismiss = true;
+  /** aria-haspopup set on the trigger (null = none). */
+  static haspopup = "dialog";
+  /** The slot holding the trigger. */
+  static triggerSlot = 'slot[name="trigger"]';
+
+  #wired = false;
+  #synced = false;
+  #trigger = null;
+  #stopTracking = null;
+  #closedAt = undefined;
+  #undismiss = null;
+  #exit = null;
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (this.#wired) return;
+    this.#wired = true;
+    this.panel = this.$(".panel");
+    this.panel.setAttribute("popover", /** @type {typeof Floating} */ (this.constructor).popoverMode);
+    this.panel.addEventListener("toggle", (e) => this._onToggle(e));
+    // `toggle` is async: by then focus has already left a hidden panel.
+    this.panel.addEventListener("beforetoggle", (e) => {
+      if (e.newState === "closed") this.focusWasInside = this.contains(document.activeElement) && !this.trigger?.contains(document.activeElement);
+    });
+    const slot = this.$(/** @type {typeof Floating} */ (this.constructor).triggerSlot);
+    slot?.addEventListener("slotchange", () => this._wireTrigger());
+    this._wireTrigger();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#stopTracking?.();
+    this.#undismiss?.();
+    this.#undismiss = null;
+  }
+
+  /** The element slotted as trigger, if any. */
+  get trigger() {
+    return this.$(/** @type {typeof Floating} */ (this.constructor).triggerSlot)?.assignedElements()[0] ?? null;
+  }
+
+  _wireTrigger() {
+    const t = this.trigger;
+    if (t === this.#trigger) return;
+    this.#trigger = t;
+    if (!t) return;
+    const hp = this.popupKind();
+    if (hp) {
+      t.setAttribute("aria-haspopup", hp);
+      t.setAttribute("aria-expanded", String(Boolean(this.open)));
+    }
+    this.wireTrigger(t);
+  }
+
+  /** aria-haspopup of the trigger for this instance (null: not a popup trigger). */
+  popupKind() {
+    return /** @type {typeof Floating} */ (this.constructor).haspopup;
+  }
+
+  /** Subclasses attach their trigger listeners here. */
+  wireTrigger(_trigger) {}
+
+  /** The rectangle the panel is placed against (default: the trigger). */
+  anchorRect() {
+    return (this.trigger ?? this).getBoundingClientRect();
+  }
+
+  show() { this.open = true; }
+  hide() { this.open = false; }
+  toggle() { this.open = !this.open; }
+
+  update(changed) {
+    if (changed.has("open") || !this.#synced) {
+      this.#synced = true;
+      const isOpen = this.panel.matches(":popover-open");
+      if (this.open) {
+        // Reopened while animating out: stay open.
+        this.#exit?.cancel();
+        this.#exit = null;
+        this.panel.style.pointerEvents = "";
+        if (!isOpen) this.panel.showPopover();
+        this._dismissable();
+      } else if (isOpen && !this.#exit) {
+        this._closePanel();
+      }
+    }
+    if (this.open) this.reposition();
+  }
+
+  _dismissable() {
+    const ctor = /** @type {typeof Floating} */ (this.constructor);
+    if (this.#undismiss || !ctor.lightDismiss || ctor.popoverMode !== "manual") return;
+    this.#undismiss = dismissable({ panel: this.panel, owner: this, trigger: this.trigger, close: () => { this.open = false; } });
+  }
+
+  /** The keyframes the panel leaves with (subclasses may change them). */
+  exitKeyframes() {
+    return POP_OUT;
+  }
+
+  // Animate out, then really hide (unless reopened meanwhile).
+  async _closePanel() {
+    this.#undismiss?.();
+    this.#undismiss = null;
+    const exit = play(this.panel, this.exitKeyframes(), { speed: "fast" });
+    this.#exit = exit;
+    // Leaving: no more clicks on it (focus stays where it is until hidden).
+    this.panel.style.pointerEvents = "none";
+    await exit.finished;
+    this.panel.style.pointerEvents = "";
+    if (this.#exit !== exit) return;
+    this.#exit = null;
+    if (!this.open && this.panel.matches(":popover-open")) this.panel.hidePopover();
+    exit.cancel();
+  }
+
+  reposition() {
+    if (!this.panel.matches(":popover-open")) return;
+    place(this.anchorRect(), this.panel, { placement: this.placement || "bottom", offset: this.offset ?? 8, ...this.placeOptions() });
+  }
+
+  /** Extra place() options for subclasses (e.g. matchWidth). */
+  placeOptions() { return {}; }
+
+  _onToggle(e) {
+    const opening = e.newState === "open";
+    if (this.popupKind()) this.#trigger?.setAttribute("aria-expanded", String(opening));
+    if (opening) {
+      this.reposition();
+      const anchor = this.trigger ?? this;
+      this.#stopTracking = autoUpdate(anchor, this.panel, () => this.reposition());
+    } else {
+      this.#stopTracking?.();
+      this.#stopTracking = null;
+      this.#closedAt = performance.now();
+    }
+    // Light dismiss and Escape close the panel behind our back: sync `open`.
+    if (Boolean(this.open) !== opening) this.commitProperty("open", opening);
+    this.emit(opening ? "ray-open" : "ray-close");
+    this.toggled(opening);
+  }
+
+  /** Hook after the panel opened/closed. */
+  toggled(_open) {}
+
+  /**
+   * Whether a click on the trigger should be ignored because the same
+   * pointer gesture just light-dismissed the panel (it would reopen it).
+   */
+  justClosed() {
+    return this.#closedAt !== undefined && performance.now() - this.#closedAt < 250;
+  }
+}

package/core/focus.js

@@ -0,0 +1,70 @@
+// Focus helpers that see through shadow roots and slots (the flat tree), so
+// components made of other components can find what is focusable.
+
+const FOCUSABLE = [
+  "a[href]",
+  "area[href]",
+  "button:not([disabled])",
+  "input:not([disabled]):not([type=hidden])",
+  "select:not([disabled])",
+  "textarea:not([disabled])",
+  "iframe",
+  "audio[controls]",
+  "video[controls]",
+  "summary",
+  "[contenteditable]:not([contenteditable=false])",
+  "[tabindex]",
+].join(",");
+
+function visible(el) {
+  if (typeof el.checkVisibility === "function") return el.checkVisibility({ visibilityProperty: true });
+  return el.getClientRects().length > 0;
+}
+
+/**
+ * Tabbable elements under `root` (an element or a shadow root), in tree
+ * order, descending into open shadow roots and slotted content.
+ * @returns {HTMLElement[]}
+ */
+export function tabbables(root, { lightOnly = false } = {}) {
+  const out = [];
+  const walk = (node) => {
+    for (const child of childrenOf(node)) {
+      if (!(child instanceof HTMLElement)) continue;
+      if (child.matches(FOCUSABLE) && child.tabIndex >= 0 && !child.hasAttribute("inert") && visible(child)) {
+        out.push(child);
+      }
+      if (child.hasAttribute("inert")) continue;
+      walk(child);
+    }
+  };
+  if (lightOnly) {
+    // Only the root's own (slotted) content, not its shadow root.
+    for (const child of root.children) {
+      if (!(child instanceof HTMLElement) || child.hasAttribute("inert")) continue;
+      if (child.matches(FOCUSABLE) && child.tabIndex >= 0 && visible(child)) out.push(child);
+      walk(child);
+    }
+  } else {
+    walk(root);
+  }
+  return out;
+}
+
+function childrenOf(node) {
+  if (node instanceof HTMLSlotElement) return node.assignedElements({ flatten: true });
+  if (node instanceof Element && node.shadowRoot) return [...node.shadowRoot.children];
+  return [...node.children];
+}
+
+/**
+ * Focuses the first [autofocus] or tabbable element; returns whether
+ * something got focus. `lightOnly`: look only at a host's own content.
+ */
+export function focusFirst(root, { lightOnly = false } = {}) {
+  const auto = root.querySelector?.("[autofocus]");
+  const target = auto ?? tabbables(root, { lightOnly })[0];
+  if (!target) return false;
+  target.focus({ preventScroll: true });
+  return true;
+}

package/core/form.js

@@ -0,0 +1,235 @@
+// Form-associated base classes.
+//
+// FormControl: a custom element that takes part in <form> like a native
+// control (value submitted under `name`, constraint validation, reset,
+// disabled by <fieldset>), through ElementInternals.
+//
+// FieldControl: a FormControl around one native control in its shadow root,
+// with Mantine's input wrapper — label, description, error and the required
+// asterisk — wired with ids and ARIA *inside* the shadow root, so the
+// accessible name works (a <label for> outside cannot reach into it).
+
+import { RayElement, css } from "./core.js";
+
+export class FormControl extends RayElement {
+  static formAssociated = true;
+  static delegatesFocus = true;
+
+  #fieldsetDisabled = false;
+
+  constructor() {
+    super();
+    this.internals = this.attachInternals();
+  }
+
+  /** The <form> this control belongs to. */
+  get form() { return this.internals.form; }
+  get validity() { return this.internals.validity; }
+  get validationMessage() { return this.internals.validationMessage; }
+  get willValidate() { return this.internals.willValidate; }
+  checkValidity() { return this.internals.checkValidity(); }
+  reportValidity() { return this.internals.reportValidity(); }
+
+  /** Disabled by its own attribute or by a disabled <fieldset>. */
+  get effectivelyDisabled() {
+    return Boolean(this.disabled) || this.#fieldsetDisabled === true;
+  }
+
+  formDisabledCallback(disabled) {
+    this.#fieldsetDisabled = disabled;
+    this.requestUpdate();
+  }
+
+  /** Re-dispatches a non-composed event (e.g. `change`) from the host. */
+  forward(event) {
+    this.dispatchEvent(new Event(event.type, { bubbles: true, cancelable: event.cancelable }));
+  }
+}
+
+/** The field wrapper around a control: label, description, box, error. */
+export const fieldStyles = css`
+  :host {
+    display: flex;
+    flex-direction: column;
+    font-size: var(--_fs);
+  }
+  /* description-position="below": after the control, with the error (the DOM
+     order and aria-describedby stay the same). */
+  :host([description-position="below"]) .description { order: 1; margin: var(--ray-space-1) 0 0; }
+  :host([description-position="below"]) .error { order: 2; }
+  .label {
+    display: inline-block;
+    align-self: flex-start;
+    margin-bottom: var(--ray-space-1);
+    font-size: var(--_fs);
+    font-weight: var(--ray-font-weight-medium);
+    color: var(--ray-foreground);
+    cursor: default;
+  }
+  .required { color: var(--ray-destructive); }
+  .description {
+    margin: calc(var(--ray-space-1) * -0.5) 0 var(--ray-space-1);
+    font-size: calc(var(--_fs) - 0.125rem);
+    line-height: var(--ray-line-height-sm);
+    color: var(--ray-muted-foreground);
+  }
+  .error {
+    margin-top: var(--ray-space-1);
+    font-size: calc(var(--_fs) - 0.125rem);
+    line-height: var(--ray-line-height-sm);
+    color: var(--ray-destructive);
+  }
+  [hidden] { display: none !important; }
+`;
+
+/** A text-like control box: input, textarea, select. */
+export const boxStyles = css`
+  .box {
+    position: relative;
+    display: flex;
+    align-items: center;
+    min-height: var(--_h);
+    color: var(--ray-foreground);
+    background: var(--ray-background);
+    border: 1px solid var(--ray-input);
+    border-radius: var(--_r);
+    border-start-start-radius: var(--ray-group-radius-ss, var(--_r));
+    border-start-end-radius: var(--ray-group-radius-se, var(--_r));
+    border-end-start-radius: var(--ray-group-radius-es, var(--_r));
+    border-end-end-radius: var(--ray-group-radius-ee, var(--_r));
+    transition: border-color var(--ray-duration-fast) var(--ray-easing-standard);
+  }
+  :host([variant="filled"]) .box { background: var(--ray-muted); border-color: transparent; }
+  :host([variant="unstyled"]) .box { background: transparent; border-color: transparent; }
+  .box:focus-within {
+    border-color: var(--ray-primary);
+    outline: var(--ray-focus-ring-width) solid var(--ray-ring);
+    outline-offset: -1px;
+  }
+  :host([variant="unstyled"]) .box:focus-within { outline: none; }
+  .box[data-invalid] { border-color: var(--ray-destructive); }
+  .box[data-invalid]:focus-within { outline-color: color-mix(in srgb, var(--ray-destructive) 45%, transparent); }
+  .box[data-disabled] { background: var(--ray-muted); color: var(--ray-muted-foreground); cursor: not-allowed; opacity: 0.75; }
+  .control {
+    flex: 1;
+    min-width: 0;
+    height: 100%;
+    min-height: calc(var(--_h) - 2px);
+    margin: 0;
+    padding: 0 calc(var(--_px) * 0.66);
+    font: inherit;
+    font-size: var(--_fs);
+    color: inherit;
+    background: transparent;
+    border: 0;
+    outline: none;
+  }
+  .control::placeholder { color: var(--ray-muted-foreground); opacity: 0.8; }
+  .control:disabled { cursor: not-allowed; }
+  .section {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    justify-content: center;
+    min-width: var(--_h);
+    height: calc(var(--_h) - 2px);
+    color: var(--ray-muted-foreground);
+  }
+  .section:not([data-filled]) { display: none; }
+  .section[data-filled] + .control, .control:has(+ .section[data-filled]) { padding-inline: 0; }
+`;
+
+/**
+ * Markup of a field around `control`, whose element must carry
+ * id="control" and class="control". Sections are slots "left" and "right".
+ */
+export function fieldTemplate(control, { sections = true } = {}) {
+  const left = sections ? `<span class="section" part="left-section"><slot name="left"></slot></span>` : "";
+  const right = sections ? `<span class="section" part="right-section"><slot name="right"></slot></span>` : "";
+  return `
+    <label class="label" part="label" for="control" hidden><span class="label-text"></span><span class="required" aria-hidden="true" hidden> *</span></label>
+    <div class="description" part="description" id="description" hidden></div>
+    <div class="box" part="wrapper">${left}${control}${right}</div>
+    <div class="error" part="error" id="error" hidden></div>`;
+}
+
+/**
+ * A FormControl around one native control (#control in the shadow root).
+ * Subclasses declare the field properties with FieldControl.fieldProperties.
+ */
+export class FieldControl extends FormControl {
+  #wired = false;
+
+  static fieldProperties = {
+    name: { type: String, reflect: true },
+    label: { type: String },
+    description: { type: String },
+    error: { type: String },
+    required: { type: Boolean, reflect: true },
+    disabled: { type: Boolean, reflect: true },
+    size: { type: String, reflect: true, default: "sm" },
+    radius: { type: String, reflect: true },
+    variant: { type: String, reflect: true, default: "default" },
+    descriptionPosition: { type: String, reflect: true, default: "above" },
+  };
+
+  constructor() {
+    super();
+    /** The native control in the shadow root. */
+    this.control = this.$("#control");
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (!this.#wired) {
+      this.#wired = true;
+      for (const side of ["left", "right"]) {
+        const slot = this.$(`slot[name="${side}"]`);
+        slot?.addEventListener("slotchange", () => {
+          slot.parentElement.toggleAttribute("data-filled", slot.assignedNodes().length > 0);
+        });
+      }
+      this.wire?.();
+    }
+  }
+
+  /** Label, description, error, ARIA and validity. Call from update(). */
+  syncField() {
+    const label = this.$(".label");
+    label.hidden = !this.label;
+    this.$(".label-text").textContent = this.label ?? "";
+    this.$(".required").hidden = !this.required;
+
+    const desc = this.$("#description");
+    desc.hidden = !this.description;
+    desc.textContent = this.description ?? "";
+    const err = this.$("#error");
+    err.hidden = !this.error;
+    err.textContent = this.error ?? "";
+
+    const c = this.control;
+    const described = [this.description ? "description" : "", this.error ? "error" : ""].filter(Boolean).join(" ");
+    if (described) c.setAttribute("aria-describedby", described);
+    else c.removeAttribute("aria-describedby");
+    if (this.error) c.setAttribute("aria-invalid", "true");
+    else c.removeAttribute("aria-invalid");
+    // Without a visible label, the host's aria-label names the control.
+    const aria = this.getAttribute("aria-label");
+    if (!this.label && aria) c.setAttribute("aria-label", aria);
+    else c.removeAttribute("aria-label");
+
+    c.required = Boolean(this.required);
+    c.disabled = this.effectivelyDisabled;
+    const box = this.$(".box");
+    box?.toggleAttribute("data-invalid", Boolean(this.error));
+    box?.toggleAttribute("data-disabled", this.effectivelyDisabled);
+    this.syncValidity();
+  }
+
+  /** Mirrors the native control's validity into the form. */
+  syncValidity() {
+    const c = this.control;
+    if (c.validity.valid) this.internals.setValidity({});
+    else this.internals.setValidity(c.validity, c.validationMessage, c);
+  }
+}