@raylang/elements 0.0.0-stage → 0.4.0

package/core/raylang.js

@@ -0,0 +1,167 @@
+// The page's half of the ray-elements native bridge for std/ui windows (raylang);
+// the program's half is the raylang module elements/bridge.
+//
+//   import { enableRaylang } from "ray-elements/core/raylang.js";
+//   await enableRaylang();   // the host, or null in a browser
+//
+// It detects window.ray, asks the program what it offers ("hello") and
+// installs a host (core/host.js), so the components that use one get the
+// system dialogs. Requests travel through window.ray.request as JSON objects
+// tagged "ray-elements", which bridge.handle answers and the app's own protocol
+// never sees. In a browser, or when the program does not answer (its loop
+// does not call bridge.handle), it resolves to null and nothing changes.
+
+import { setHost, HostFile } from "./host.js";
+import { chartTheme, onChartThemeChange } from "./charts.js";
+import { getTheme } from "./core.js";
+import { parseColor, toHex } from "./color.js";
+
+/** The version of the protocol this page speaks. */
+export const PROTOCOL = 1;
+
+let enabling = null;
+
+// The width macOS keeps for the window buttons at the start of the title bar.
+const MAC_BUTTONS = 78;
+
+/**
+ * Installs the raylang host once the program answers. `timeout` (ms) is how
+ * long to wait for that answer; `ray` replaces window.ray (tests).
+ * `windowColors` (default true) keeps the window's background in the
+ * theme's background color, so a resize or a reopen never shows the other
+ * theme. The title bar is tinted too only when the window has its own bar
+ * (not full_content) and the theme is light or dark: with "system" it stays
+ * the system's, so the page keeps following the system.
+ */
+export function enableRaylang({ timeout = 2000, ray = globalThis.ray, windowColors = true } = {}) {
+  if (ray !== globalThis.ray) return connect(ray, timeout, windowColors);
+  enabling ??= connect(ray, timeout, windowColors);
+  return enabling;
+}
+
+async function connect(ray, timeout, windowColors) {
+  if (typeof ray?.request !== "function") return null;
+  const call = (op, args = {}) => request(ray, op, args);
+  let hello;
+  try {
+    hello = await within(call("hello"), timeout);
+  } catch {
+    return null;
+  }
+  const ops = new Set(hello?.ops ?? []);
+  // Context menus: the choice comes back as a "ray-elements:menu" event pushed by
+  // the program ({ id, index }); a dismissed menu sends nothing, so opening
+  // the next one settles the previous with null.
+  let popups = 0;
+  let pending = null;
+  document.addEventListener("ray-elements:menu", (e) => {
+    if (pending && e.detail?.id === pending.id) {
+      pending.resolve(e.detail.index);
+      pending = null;
+    }
+  });
+  const host = {
+    name: "raylang",
+    platform: hello.platform ?? "",
+    version: hello.version ?? "",
+    can: (op) => ops.has(op),
+    async pickFiles({ title = "", multiple = false, directory = "", filters = [] } = {}) {
+      const picked = await call("pick_files", { title, multiple, directory, filters });
+      return (picked ?? []).map((f) => new HostFile(f));
+    },
+    async pickPath({ mode = "open", title = "", directory = "", suggested = "", filters = [] } = {}) {
+      return (await call("pick_path", { mode, title, directory, suggested, filters })) ?? null;
+    },
+    menuItems() {
+      return call("menu_items");
+    },
+    runMenu(tag) {
+      return call("run_menu", { tag });
+    },
+    async popupMenu(items) {
+      pending?.resolve(null);
+      const id = ++popups;
+      const chosen = new Promise((resolve) => { pending = { id, resolve }; });
+      try {
+        await call("popup_menu", { id, items });
+      } catch (e) {
+        if (pending?.id === id) pending = null;
+        throw e;
+      }
+      return chosen;
+    },
+    setEdited(edited) {
+      return call("set_edited", { edited: Boolean(edited) });
+    },
+    setWindowColors({ background = "", titlebar } = {}) {
+      return call("window_colors", titlebar === undefined ? { background } : { background, titlebar });
+    },
+    async confirm({ title = "Are you sure?", message = "", confirmLabel = "Confirm", cancelLabel = "Cancel", style = "" } = {}) {
+      return Boolean(await call("confirm", { title, message, confirmLabel, cancelLabel, style }));
+    },
+  };
+  // Under a transparent title bar (a full_content window): what to reserve.
+  const height = Number(ray.titlebar_height) || 0;
+  host.titlebar = height > 0 ? { height, inset: host.platform === "macos" ? MAC_BUTTONS : 0 } : null;
+  const root = document.documentElement;
+  if (host.titlebar) {
+    root.style.setProperty("--ray-titlebar-height", `${height}px`);
+    root.style.setProperty("--ray-titlebar-inset", `${host.titlebar.inset}px`);
+    root.setAttribute("data-ray-titlebar", "");
+  }
+  setHost(host);
+  root.setAttribute("data-ray-host", "raylang");
+  if (windowColors && ops.has("window_colors")) {
+    // A title bar color also sets the window's appearance (macOS picks light
+    // or dark by its luminance), which the page's prefers-color-scheme
+    // follows, and in a full_content window it brings back the opaque bar.
+    // So the bar is tinted only in a window with its own bar and a chosen
+    // theme (light or dark), and given back to the system once after that.
+    let tinted = false;
+    const paint = (theme) => {
+      const background = hex(theme.background);
+      if (!background) return;
+      const colors = { background };
+      if (!host.titlebar) {
+        if (getTheme() !== "system") {
+          colors.titlebar = background;
+          tinted = true;
+        } else if (tinted) {
+          colors.titlebar = "";
+          tinted = false;
+        }
+      }
+      host.setWindowColors(colors).catch(() => {});
+    };
+    paint(chartTheme());
+    onChartThemeChange(paint);
+  }
+  return host;
+}
+
+// "#rrggbb" of a CSS color, "" when it cannot be read.
+function hex(color) {
+  if (/^#[0-9a-f]{6}$/i.test(color ?? "")) return color.toLowerCase();
+  try {
+    const rgb = parseColor(String(color ?? ""));
+    return rgb ? toHex(rgb).slice(0, 7).toLowerCase() : "";
+  } catch {
+    return "";
+  }
+}
+
+async function request(ray, op, args) {
+  const answer = await ray.request({ "ray-elements": PROTOCOL, op, ...args });
+  if (!answer || typeof answer !== "object" || !("ok" in answer)) {
+    throw new Error(`ray-elements bridge: unexpected answer to '${op}'`);
+  }
+  if (!answer.ok) throw new Error(`ray-elements bridge: ${answer.error}`);
+  return answer.value;
+}
+
+function within(promise, ms) {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => reject(new Error("ray-elements bridge: no answer")), ms);
+    promise.then((v) => { clearTimeout(t); resolve(v); }, (e) => { clearTimeout(t); reject(e); });
+  });
+}

package/core/scroll.js

@@ -0,0 +1,58 @@
+// Which element scrolls the page an element sits on, and the direction of
+// its scrolling: for the bars that hide while scrolling down and come back
+// on the way up (ray-app-bar, ray-bottom-nav).
+
+/**
+ * The scroller of `el`: `target` (an element or a selector) when given,
+ * else the content of the ray-app-shell or ray-scroll-area around it, else
+ * the window.
+ * @param {Element} el
+ * @param {Element | string | null | undefined} target
+ * @returns {Element | Window}
+ */
+export function scrollerOf(el, target) {
+  if (target instanceof Element) return target;
+  if (typeof target === "string" && target) {
+    const found = document.querySelector(target);
+    if (found) return found.viewport ?? found.scroller ?? found;
+  }
+  for (let n = el; n; n = n.parentElement ?? n.getRootNode()?.host) {
+    if (n.localName === "ray-app-shell" && n.scroller) return n.scroller;
+    if (n.localName === "ray-scroll-area" && n !== el && n.viewport) return n.viewport;
+  }
+  return window;
+}
+
+/**
+ * Calls `cb({ y, direction })` as `scroller` scrolls, once per frame;
+ * direction is "down" or "up" past `tolerance` px, else unchanged.
+ * Returns a function that stops listening.
+ * @param {Element | Window} scroller
+ * @param {(state: { y: number, direction: "up" | "down" }) => void} cb
+ */
+export function watchScroll(scroller, cb, { tolerance = 8 } = {}) {
+  const top = () => (scroller === window ? window.scrollY : /** @type {Element} */ (scroller).scrollTop);
+  let last = top();
+  let direction = "up";
+  let frame = 0;
+  const run = () => {
+    frame = 0;
+    const y = Math.max(0, top());
+    if (Math.abs(y - last) >= tolerance) {
+      direction = y > last ? "down" : "up";
+      last = y;
+    }
+    if (y <= 0) { direction = "up"; last = 0; }
+    cb({ y, direction });
+  };
+  const onScroll = () => {
+    // A hidden page runs no frames: no need to wait for one.
+    if (document.visibilityState === "hidden") return run();
+    if (!frame) frame = requestAnimationFrame(run);
+  };
+  scroller.addEventListener("scroll", onScroll, { passive: true });
+  return () => {
+    scroller.removeEventListener("scroll", onScroll);
+    cancelAnimationFrame(frame);
+  };
+}

package/core/styles.js

@@ -0,0 +1,211 @@
+// Shared component styles: sizes, radius, color variants and the loader.
+// Components add the sheets they need to their `static styles`.
+
+import { css } from "./core.js";
+
+/** Palette colors of tokens.toml; anything else given as `color` is used as a raw CSS color. */
+export const COLORS = ["dark", "gray", "red", "pink", "violet", "indigo", "blue", "cyan", "teal", "green", "yellow", "orange", "custom"];
+
+/** Named steps of the space scale (--ray-space-*). */
+const SPACES = ["xs", "sm", "md", "lg", "xl"];
+
+/**
+ * A spacing value as CSS: a named step ("md") as its token, a bare number
+ * as px (0 included), anything else as a CSS length ("1.5rem", "5%").
+ * @param {string | number | undefined} value
+ * @returns {string | null} null when empty
+ */
+export function spaceValue(value) {
+  const s = String(value ?? "").trim();
+  if (!s) return null;
+  if (SPACES.includes(s)) return `var(--ray-space-${s})`;
+  return /^-?\d+(\.\d+)?$/.test(s) ? `${s}px` : s;
+}
+
+/** Variant tokens generated per color (tokens.toml [variants.*]). */
+export const VARIANT_TOKENS = ["filled", "filled-hover", "light", "light-hover", "light-color", "outline", "outline-hover", "contrast"];
+
+/**
+ * Points the private --_<variant> custom properties of `el` at a color:
+ * a palette name, a raw CSS color, or the primary color when empty.
+ * @param {HTMLElement} el
+ * @param {string | undefined} color
+ */
+export function applyColor(el, color) {
+  if (!color || COLORS.includes(color) || color === "primary") {
+    const base = !color || color === "primary" ? "--ray-primary" : `--ray-${color}`;
+    for (const v of VARIANT_TOKENS) el.style.setProperty(`--_${v}`, `var(${base}-${v})`);
+    return;
+  }
+  // A raw CSS color: derive the variants the way the tokens do.
+  const mix = (pct, other = "transparent") => `color-mix(in srgb, ${color} ${pct}, ${other})`;
+  const values = {
+    "filled": color,
+    "filled-hover": mix("85%", "black"),
+    "light": mix("12%"),
+    "light-hover": mix("18%"),
+    "light-color": color,
+    "outline": color,
+    "outline-hover": mix("6%"),
+    "contrast": "white",
+  };
+  for (const v of VARIANT_TOKENS) el.style.setProperty(`--_${v}`, values[v]);
+}
+
+/**
+ * The gradient of variant="gradient" on `el`, from a "from to [deg]" spec:
+ * palette colors (their filled shade) or any CSS colors ("teal blue 90",
+ * "#7c3aed #db2777"). Empty: the --ray-gradient-* tokens.
+ * @param {HTMLElement} el
+ * @param {string | undefined} spec
+ */
+export function applyGradient(el, spec) {
+  const parts = String(spec ?? "").trim().split(/\s+/).filter(Boolean);
+  const color = (c) => (COLORS.includes(c) ? `var(--ray-${c}-filled)` : c);
+  if (parts[0]) el.style.setProperty("--_gradient-from", color(parts[0]));
+  else el.style.removeProperty("--_gradient-from");
+  if (parts[1]) el.style.setProperty("--_gradient-to", color(parts[1]));
+  else el.style.removeProperty("--_gradient-to");
+  if (parts[2]) el.style.setProperty("--_gradient-deg", /^-?\d+(\.\d+)?$/.test(parts[2]) ? `${parts[2]}deg` : parts[2]);
+  else el.style.removeProperty("--_gradient-deg");
+}
+
+/**
+ * Size scale on the host: --_h (control height), --_fs (font size),
+ * --_px (horizontal padding), --_gap. Default `sm`, like Mantine.
+ */
+export const sizeStyles = css`
+  :host {
+    --_h: var(--ray-control-height-sm);
+    --_fs: var(--ray-font-size-sm);
+    --_px: 1.125rem;
+    --_gap: var(--ray-space-2);
+  }
+  :host([size="xs"]) { --_h: var(--ray-control-height-xs); --_fs: var(--ray-font-size-xs); --_px: 0.875rem; --_gap: var(--ray-space-1); }
+  :host([size="md"]) { --_h: var(--ray-control-height-md); --_fs: var(--ray-font-size-md); --_px: 1.375rem; }
+  :host([size="lg"]) { --_h: var(--ray-control-height-lg); --_fs: var(--ray-font-size-lg); --_px: 1.625rem; --_gap: var(--ray-space-3); }
+  :host([size="xl"]) { --_h: var(--ray-control-height-xl); --_fs: var(--ray-font-size-xl); --_px: 2rem; --_gap: var(--ray-space-3); }
+`;
+
+/** Radius on the host: --_r. Default: the system-wide --ray-radius-default. */
+export const radiusStyles = css`
+  :host { --_r: var(--ray-radius-default); }
+  :host([radius="xs"]) { --_r: var(--ray-radius-xs); }
+  :host([radius="sm"]) { --_r: var(--ray-radius-sm); }
+  :host([radius="md"]) { --_r: var(--ray-radius-md); }
+  :host([radius="lg"]) { --_r: var(--ray-radius-lg); }
+  :host([radius="xl"]) { --_r: var(--ray-radius-xl); }
+  :host([radius="full"]) { --_r: var(--ray-radius-full); }
+`;
+
+/**
+ * Color variants for an element carrying data-variant and the --_<variant>
+ * properties of applyColor(): filled, light, outline, subtle, default,
+ * transparent, and gradient (applyGradient / --ray-gradient-*).
+ */
+export const variantStyles = css`
+  [data-variant] {
+    border: 1px solid transparent;
+    transition:
+      background-color var(--ray-duration-fast) var(--ray-easing-standard),
+      border-color var(--ray-duration-fast) var(--ray-easing-standard),
+      color var(--ray-duration-fast) var(--ray-easing-standard);
+  }
+  [data-variant="filled"] { background: var(--_filled); color: var(--_contrast); }
+  [data-variant="light"] { background: var(--_light); color: var(--_light-color); }
+  [data-variant="outline"] { background: transparent; color: var(--_outline); border-color: var(--_outline); }
+  [data-variant="subtle"] { background: transparent; color: var(--_light-color); }
+  [data-variant="transparent"] { background: transparent; color: var(--_light-color); }
+  [data-variant="default"] { background: var(--ray-default); color: var(--ray-foreground); border-color: var(--ray-border); }
+  [data-variant="gradient"] {
+    background: linear-gradient(
+      var(--_gradient-deg, var(--ray-gradient-deg)),
+      var(--_gradient-from, var(--ray-gradient-from)),
+      var(--_gradient-to, var(--ray-gradient-to))
+    );
+    color: var(--ray-white);
+  }
+
+  [data-interactive]:not([data-disabled])[data-variant="filled"]:hover { background: var(--_filled-hover); }
+  [data-interactive]:not([data-disabled])[data-variant="light"]:hover { background: var(--_light-hover); }
+  [data-interactive]:not([data-disabled])[data-variant="outline"]:hover { background: var(--_outline-hover); }
+  [data-interactive]:not([data-disabled])[data-variant="subtle"]:hover { background: var(--_light); }
+  [data-interactive]:not([data-disabled])[data-variant="default"]:hover { background: var(--ray-default-hover); }
+  [data-interactive]:not([data-disabled])[data-variant="gradient"]:hover { filter: brightness(0.92); }
+
+  [data-interactive][data-disabled] {
+    background: var(--ray-muted);
+    color: var(--ray-muted-foreground);
+    border-color: var(--ray-border);
+    cursor: not-allowed;
+  }
+  [data-interactive][data-disabled][data-variant="subtle"],
+  [data-interactive][data-disabled][data-variant="transparent"] {
+    background: transparent;
+    border-color: transparent;
+  }
+`;
+
+/** A ring spinner: <span class="loader"></span>, sized by --_loader (default 1em). */
+export const loaderStyles = css`
+  .loader {
+    display: inline-block;
+    flex: none;
+    width: var(--_loader, 1em);
+    height: var(--_loader, 1em);
+    border: max(2px, calc(var(--_loader, 1em) / 8)) solid currentColor;
+    border-right-color: transparent;
+    border-radius: 50%;
+    animation: ray-spin 0.75s linear infinite;
+  }
+  @keyframes ray-spin { to { transform: rotate(360deg); } }
+  @media (prefers-reduced-motion: reduce) {
+    .loader { animation-duration: 1.5s !important; }
+  }
+`;
+
+/** Visually hidden but available to assistive technology. */
+export const srOnlyStyles = css`
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0 0 0 0);
+    white-space: nowrap;
+    border: 0;
+  }
+`;
+
+/**
+ * The backdrop of modal overlays (dialog, drawer, command palette): the
+ * --ray-overlay color and, when --ray-overlay-blur is set (tokens default:
+ * [overlay] blur), the page behind blurred. ::backdrop inherits from its
+ * dialog, so both follow the element, its subtree or :root.
+ */
+export const overlayStyles = css`
+  dialog::backdrop {
+    background: var(--ray-overlay);
+    -webkit-backdrop-filter: blur(var(--ray-overlay-blur, 0px));
+    backdrop-filter: blur(var(--ray-overlay-blur, 0px));
+  }
+  @media (prefers-reduced-transparency: reduce) {
+    dialog::backdrop { -webkit-backdrop-filter: none; backdrop-filter: none; }
+  }
+`;
+
+/**
+ * The overlay-blur attribute of an overlay: a number (px), a CSS length, or
+ * "none"/"0" to turn the blur off. Unset: the inherited --ray-overlay-blur.
+ */
+export function applyOverlayBlur(el, value) {
+  if (value === undefined || value === null || value === "") {
+    el.style.removeProperty("--ray-overlay-blur");
+    return;
+  }
+  const v = String(value).trim();
+  const css = v === "none" ? "0px" : /^\d+(\.\d+)?$/.test(v) ? `${v}px` : v;
+  el.style.setProperty("--ray-overlay-blur", css);
+}

package/core.js

@@ -0,0 +1,16 @@
+// Generated by ray-elements tools. Do not edit.
+// The API of @raylang/elements without the components: importing it registers no element.
+
+export * from "./core/core.js";
+export { FormControl, FieldControl, fieldTemplate, fieldStyles, boxStyles } from "./core/form.js";
+export { Floating, floatingStyles } from "./core/floating.js";
+export { COLORS, VARIANT_TOKENS, applyColor, spaceValue, sizeStyles, radiusStyles, variantStyles, loaderStyles, srOnlyStyles, overlayStyles, applyOverlayBlur } from "./core/styles.js";
+export { place, pointRect, autoUpdate } from "./core/position.js";
+export { scrollerOf, watchScroll } from "./core/scroll.js";
+export { tabbables, focusFirst } from "./core/focus.js";
+export { duration, motionAllowed, play, playAll, collapseOut, POP_OUT } from "./core/motion.js";
+export { dismissable } from "./core/dismiss.js";
+export { matchesHotkey, formatHotkey } from "./core/hotkey.js";
+export { CHART_SERIES, chartTheme, onChartThemeChange, withAlpha } from "./core/charts.js";
+export { setHost, getHost, hostCan, onHostChange, HostFile, typeOfName, extensionsOfType, acceptFilters, titlebar, dragRegion, trackEdits } from "./core/host.js";
+export { enableRaylang, PROTOCOL } from "./core/raylang.js";