@raylang/elements 0.0.0-stage → 0.4.0

package/components/app-bar/app-bar.js

@@ -0,0 +1,168 @@
+// <ray-app-bar>: the top bar of a phone screen (Material's top app bar, the
+// iOS navigation bar): a back or menu button, the title (and a subtitle),
+// actions, and an optional row under it (tabs, a search field).
+//
+// scroll-behavior="elevate" (default) draws its border and shadow once the content
+// scrolls; scroll-behavior="hide" also slides it away while scrolling down and back
+// on the way up. It follows the scroller of its ray-app-shell, else
+// `scroll-target`, else the window. Clear of the notch (safe-area inset).
+
+import { RayElement, css, define } from "../../core/core.js";
+import { scrollerOf, watchScroll } from "../../core/scroll.js";
+
+const styles = css`
+  :host {
+    --_h: 3.5rem;
+    --_bg: var(--ray-background);
+    --_fg: var(--ray-foreground);
+    --_muted: var(--ray-muted-foreground);
+    display: grid;
+    grid-template-rows: 1fr;
+    position: relative;
+    z-index: 2;
+    transition: grid-template-rows var(--ray-duration-base) var(--ray-easing-standard), translate var(--ray-duration-base) var(--ray-easing-standard);
+  }
+  /* Hidden above a scroller (in a shell): its row closes, the content takes
+     the room. Over the window (sticky): it slides up. */
+  :host([data-concealed="flow"]) { grid-template-rows: 0fr; clip-path: inset(0); }
+  :host([data-concealed="over"]) { translate: 0 -100%; }
+  :host([hidden]) { display: none; }
+  :host([sticky]) { position: sticky; top: 0; }
+  :host([variant="filled"]) { --_bg: var(--ray-primary-filled); --_fg: var(--ray-primary-contrast); --_muted: color-mix(in srgb, var(--ray-primary-contrast) 75%, transparent); }
+  :host([variant="transparent"]) { --_bg: transparent; }
+  :host([size="sm"]) { --_h: 3rem; }
+  :host([size="lg"]) { --_h: 4rem; }
+  /* The row that closes (no padding, no border: it can reach 0). */
+  .fold { min-height: 0; }
+  .bar {
+    box-sizing: border-box;
+    padding-top: env(safe-area-inset-top, 0px);
+    color: var(--_fg);
+    background: var(--_bg);
+    border-bottom: 1px solid transparent;
+    transition: border-color var(--ray-duration-fast), box-shadow var(--ray-duration-fast), background-color var(--ray-duration-fast);
+  }
+  :host([data-elevated]) .bar { border-bottom-color: var(--ray-border); box-shadow: var(--ray-shadow-sm); }
+  :host([data-elevated][variant="transparent"]) .bar { background: var(--ray-background); }
+  :host([variant="filled"][data-elevated]) .bar { border-bottom-color: transparent; }
+  .row {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    align-items: center;
+    gap: var(--ray-space-1);
+    min-height: var(--_h);
+    padding-inline: max(var(--ray-space-2), env(safe-area-inset-left, 0px)) max(var(--ray-space-2), env(safe-area-inset-right, 0px));
+  }
+  :host([center]) .row { grid-template-columns: minmax(0, 1fr) auto minmax(0, 1fr); }
+  .start, .end { display: flex; align-items: center; gap: var(--ray-space-1); }
+  .end { justify-content: flex-end; }
+  .title { display: grid; min-width: 0; padding-inline: var(--ray-space-2); }
+  :host([center]) .title { text-align: center; }
+  .label {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    font-size: var(--ray-font-size-lg);
+    font-weight: var(--ray-font-weight-bold, 700);
+    line-height: 1.25;
+  }
+  :host([size="sm"]) .label { font-size: var(--ray-font-size-md); }
+  .description { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: var(--ray-font-size-xs); color: var(--_muted); }
+  .label:empty, .description:empty { display: none; }
+  .bottom { padding: 0 var(--ray-space-2) var(--ray-space-2); }
+  .bottom:not([data-filled]), .start:not([data-filled]) { display: none; }
+  :host([center]) .start:not([data-filled]) { display: flex; }
+  @media (prefers-reduced-motion: reduce) { :host { transition: none; } }
+`;
+
+export class RayAppBar extends RayElement {
+  static properties = {
+    label: { type: String },
+    description: { type: String },
+    center: { type: Boolean, reflect: true },
+    variant: { type: String, reflect: true, default: "default" },
+    size: { type: String, reflect: true, default: "md" },
+    // Not `scroll`: that would hide the element's scroll() method.
+    scrollBehavior: { type: String, attribute: "scroll-behavior", reflect: true, default: "elevate" },
+    sticky: { type: Boolean, reflect: true },
+    scrollTarget: { type: String, attribute: "scroll-target" },
+  };
+  static styles = [styles];
+  static template = `
+    <div class="fold"><div class="bar" part="bar">
+      <div class="row">
+        <div class="start" part="start"><slot name="start"></slot></div>
+        <div class="title" part="title"><span class="label"></span><span class="description"></span><slot></slot></div>
+        <div class="end" part="end"><slot name="end"></slot></div>
+      </div>
+      <div class="bottom" part="bottom"><slot name="bottom"></slot></div>
+    </div></div>`;
+
+  #stop = null;
+  #lock = 0;
+
+  constructor() {
+    super();
+    for (const name of ["start", "bottom"]) {
+      const slot = this.$(`slot[name="${name}"]`);
+      slot.addEventListener("slotchange", () => slot.parentElement.toggleAttribute("data-filled", slot.assignedNodes().length > 0));
+    }
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    for (const name of ["start", "bottom"]) {
+      const slot = this.$(`slot[name="${name}"]`);
+      slot.parentElement.toggleAttribute("data-filled", slot.assignedNodes().length > 0);
+    }
+    // The shell (or the target) may upgrade after the bar: watch once settled.
+    queueMicrotask(() => this._watch());
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#stop?.();
+    this.#stop = null;
+  }
+
+  /** Whether scroll-behavior="hide" has slid it away. */
+  get concealed() {
+    return this.hasAttribute("data-concealed");
+  }
+
+  update(changed) {
+    this.$(".label").textContent = this.label ?? "";
+    this.$(".description").textContent = this.description ?? "";
+    if (changed.has("scrollBehavior") || changed.has("scrollTarget")) this._watch();
+  }
+
+  _watch() {
+    this.#stop?.();
+    this.#stop = null;
+    this.removeAttribute("data-concealed");
+    this.toggleAttribute("data-elevated", false);
+    if (!this.isConnected || this.scrollBehavior === "none") return;
+    const scroller = scrollerOf(this, this.scrollTarget);
+    // In a shell the bar sits above the scroller: hiding gives its room to
+    // the content. Over the window it slides away.
+    const inFlow = scroller !== window;
+    this.#stop = watchScroll(scroller, ({ y, direction }) => {
+      this.toggleAttribute("data-elevated", y > 0);
+      if (this.scrollBehavior !== "hide") return;
+      if (y <= 0) this.removeAttribute("data-concealed");
+      else this._conceal(direction === "down" && y > this.offsetHeight + 8, inFlow);
+    });
+  }
+
+  _conceal(on, inFlow = true) {
+    if (on === this.concealed) return;
+    // Closing its row resizes the scroller, which can move the scroll
+    // position (at the end of the content): ignore that for a moment.
+    if (performance.now() < this.#lock) return;
+    this.#lock = performance.now() + 400;
+    if (on) this.setAttribute("data-concealed", inFlow ? "flow" : "over");
+    else this.removeAttribute("data-concealed");
+  }
+}
+
+define("ray-app-bar", RayAppBar);

package/components/app-shell/app-shell.js

@@ -0,0 +1,198 @@
+// <ray-app-shell>: the frame of an app (Mantine's AppShell): header,
+// navbar, main, aside, footer, and a bottom bar for phones.
+//
+// Wide: the header across the top (or beside the navbar with
+// layout="alt"), the navbar and the aside on the sides of the main content.
+// Narrow (below `breakpoint`, the shell's own width): one column, header,
+// main, footer and the `bottom` slot (a ray-bottom-nav); the navbar and the
+// aside take no room (a ray-sidebar there still opens as a drawer).
+//
+// The main content scrolls, the bars stay: `scroller` is the element that
+// scrolls (ray-app-bar and ray-bottom-nav find it on their own).
+//
+// Under a transparent title bar (a std/ui full_content window with
+// core/raylang.js; see titlebar() in core/host.js) the header is the title
+// bar: it is at least as tall, leaves room for the window buttons and drags
+// the window. With layout="alt", or without a header, the navbar and the
+// main content start below the title bar instead.
+
+import { RayElement, css, define } from "../../core/core.js";
+import { spaceValue } from "../../core/styles.js";
+import { titlebar, dragRegion, onHostChange } from "../../core/host.js";
+
+const styles = css`
+  :host {
+    display: block;
+    height: 100dvh;
+    min-height: 0;
+    color: var(--ray-foreground);
+    background: var(--ray-background);
+  }
+  :host([hidden]) { display: none; }
+  .shell {
+    display: grid;
+    height: 100%;
+    grid-template-columns: auto minmax(0, 1fr) auto;
+    grid-template-rows: auto minmax(0, 1fr) auto auto;
+    grid-template-areas:
+      "header header header"
+      "navbar main aside"
+      "footer footer footer"
+      "bottom bottom bottom";
+  }
+  :host([layout="alt"]) .shell {
+    grid-template-areas:
+      "navbar header aside"
+      "navbar main aside"
+      "navbar footer aside"
+      "bottom bottom bottom";
+  }
+  .header { grid-area: header; min-width: 0; }
+  .navbar { grid-area: navbar; display: flex; min-height: 0; }
+  .aside { grid-area: aside; display: flex; min-height: 0; }
+  .footer { grid-area: footer; min-width: 0; }
+  .bottom { grid-area: bottom; min-width: 0; display: none; }
+  .main {
+    grid-area: main;
+    position: relative;
+    min-width: 0;
+    min-height: 0;
+    overflow: auto;
+    overscroll-behavior: contain;
+    padding: var(--_p, 0);
+  }
+  .header:not([data-filled]), .footer:not([data-filled]), .navbar:not([data-filled]), .aside:not([data-filled]) { display: none; }
+
+  /* Narrow: one column; the side panels take no room but stay rendered
+     (a sidebar's drawer is a top-layer dialog inside them). */
+  :host([data-mobile]) .shell {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas: "header" "main" "footer" "bottom";
+  }
+  :host([data-mobile]) .navbar, :host([data-mobile]) .aside {
+    position: absolute;
+    width: 0;
+    height: 0;
+    overflow: hidden;
+  }
+  :host([data-mobile]) .bottom[data-filled] { display: block; }
+
+  /* Under a transparent title bar (data-titlebar, from the host). */
+  :host([data-titlebar]) .header { min-height: var(--ray-titlebar-height, 0px); }
+  :host([data-titlebar]:not([layout="alt"])) .header,
+  :host([data-titlebar][data-mobile]) .header { padding-inline-start: var(--ray-titlebar-inset, 0px); }
+  :host([data-titlebar][layout="alt"]:not([data-mobile])) .navbar,
+  :host([data-titlebar][data-no-header]) .navbar,
+  :host([data-titlebar][data-no-header]) .aside { padding-top: var(--ray-titlebar-height, 0px); }
+  :host([data-titlebar][data-no-header]) .main { padding-top: calc(var(--_p, 0px) + var(--ray-titlebar-height, 0px)); }
+`;
+
+/** A CSS length in px, against the element's font size for em/rem. */
+function toPx(value, el) {
+  const m = String(value ?? "").trim().match(/^(\d+(?:\.\d+)?)(px|em|rem)?$/);
+  if (!m) return 768;
+  const n = Number(m[1]);
+  if (m[2] === "rem") return n * parseFloat(getComputedStyle(document.documentElement).fontSize || "16");
+  if (m[2] === "em") return n * parseFloat(getComputedStyle(el).fontSize || "16");
+  return n;
+}
+
+export class RayAppShell extends RayElement {
+  static properties = {
+    layout: { type: String, reflect: true, default: "default" },
+    breakpoint: { type: String, default: "48em" },
+    padding: { type: String, reflect: true },
+  };
+  static styles = [styles];
+  static template = `
+    <div class="shell" part="shell">
+      <div class="header" part="header"><slot name="header"></slot></div>
+      <div class="navbar" part="navbar"><slot name="navbar"></slot></div>
+      <div class="main" part="main"><slot></slot></div>
+      <div class="aside" part="aside"><slot name="aside"></slot></div>
+      <div class="footer" part="footer"><slot name="footer"></slot></div>
+      <div class="bottom" part="bottom"><slot name="bottom"></slot></div>
+    </div>`;
+
+  #ro = null;
+  #syncs = [];
+  #stopHost = null;
+  /** @type {Map<Element, () => void>} */
+  #drags = new Map();
+
+  constructor() {
+    super();
+    for (const name of ["header", "navbar", "aside", "footer", "bottom"]) {
+      const slot = this.$(`slot[name="${name}"]`);
+      const sync = () => {
+        slot.parentElement.toggleAttribute("data-filled", slot.assignedNodes().length > 0);
+        if (name === "header") this.#chrome();
+      };
+      slot.addEventListener("slotchange", sync);
+      this.#syncs.push(sync);
+    }
+  }
+
+  // The title bar: the shell's attributes, and the header elements as drag handles.
+  #chrome() {
+    const bar = this.isConnected && titlebar();
+    this.toggleAttribute("data-titlebar", Boolean(bar));
+    const header = this.$('slot[name="header"]').assignedElements();
+    this.toggleAttribute("data-no-header", header.length === 0);
+    for (const [el, undo] of this.#drags) {
+      if (!bar || !header.includes(el)) {
+        undo();
+        this.#drags.delete(el);
+      }
+    }
+    if (bar) for (const el of header) if (!this.#drags.has(el)) this.#drags.set(el, dragRegion(el));
+  }
+
+  /** The element that scrolls the main content. */
+  get scroller() {
+    return this.$(".main");
+  }
+
+  /** Whether the shell is in its narrow (phone) layout. */
+  get mobile() {
+    return this.hasAttribute("data-mobile");
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    for (const sync of this.#syncs) sync();
+    // The layout follows the shell's own width: right in a phone-sized
+    // frame as in a full window. Measured at once too (the observer reports
+    // before the next paint, and never in a page that is not rendered).
+    this.#ro = new ResizeObserver(() => this._measure());
+    this.#ro.observe(this);
+    this._measure();
+    this.#stopHost ??= onHostChange(() => this.#chrome());
+    this.#chrome();
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.#ro?.disconnect();
+    this.#ro = null;
+    this.#stopHost?.();
+    this.#stopHost = null;
+    this.#chrome();
+  }
+
+  update(changed) {
+    const p = spaceValue(this.padding);
+    if (p) this.style.setProperty("--_p", p);
+    else this.style.removeProperty("--_p");
+    if (changed.has("breakpoint")) this._measure();
+  }
+
+  _measure() {
+    const mobile = this.getBoundingClientRect().width < toPx(this.breakpoint, this);
+    if (mobile === this.mobile) return;
+    this.toggleAttribute("data-mobile", mobile);
+    this.emit("ray-breakpoint", { mobile });
+  }
+}
+
+define("ray-app-shell", RayAppShell);

package/components/aspect-ratio/aspect-ratio.js

@@ -0,0 +1,59 @@
+// <ray-aspect-ratio>: a box with a fixed width/height ratio; its media
+// (img, video, iframe, any element) fills it.
+
+import { RayElement, css, define } from "../../core/core.js";
+
+const RADII = ["xs", "sm", "md", "lg", "xl", "full"];
+
+const styles = css`
+  /* Defaults set on the host: an ancestor's private --_r (a card's or a
+     button's radius) would otherwise inherit into it. */
+  :host {
+    --_ratio: 16 / 9;
+    --_r: 0;
+    display: block;
+    position: relative;
+    overflow: hidden;
+    aspect-ratio: var(--_ratio);
+    border-radius: var(--_r);
+  }
+  :host([hidden]) { display: none; }
+  ::slotted(*) {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+  :host([fit="contain"]) ::slotted(*) { object-fit: contain; }
+`;
+
+/** "16/9", "16:9", "1.5", 2 -> a CSS aspect-ratio value ("16 / 9"); null if invalid. */
+export function parseRatio(value) {
+  const s = String(value ?? "").trim();
+  const m = s.match(/^(\d+(?:\.\d+)?)\s*[/:]\s*(\d+(?:\.\d+)?)$/);
+  if (m && Number(m[2]) > 0) return `${Number(m[1])} / ${Number(m[2])}`;
+  const n = Number(s);
+  return s && Number.isFinite(n) && n > 0 ? String(n) : null;
+}
+
+export class RayAspectRatio extends RayElement {
+  static properties = {
+    ratio: { type: String, reflect: true, default: "16/9" },
+    fit: { type: String, reflect: true, default: "cover" },
+    radius: { type: String, reflect: true },
+  };
+  static styles = [styles];
+  static template = `<slot></slot>`;
+
+  update() {
+    const r = parseRatio(this.ratio);
+    if (r) this.style.setProperty("--_ratio", r);
+    else this.style.removeProperty("--_ratio");
+    const rad = this.radius;
+    if (rad) this.style.setProperty("--_r", RADII.includes(rad) ? `var(--ray-radius-${rad})` : rad);
+    else this.style.removeProperty("--_r");
+  }
+}
+
+define("ray-aspect-ratio", RayAspectRatio);