@relements/core 0.1.0

package/src/behaviors/tabs.js

@@ -0,0 +1,171 @@
+/**
+ * enhanceTabs
+ * -----------
+ * Wires the ARIA tabs pattern over server-rendered markup.
+ *
+ *   <div class="re-tabs" data-re-tabs>
+ *     <div role="tablist" aria-label="Settings">
+ *       <button role="tab" id="t-1" aria-controls="p-1" aria-selected="true">…</button>
+ *       <button role="tab" id="t-2" aria-controls="p-2" aria-selected="false" tabindex="-1">…</button>
+ *     </div>
+ *     <section role="tabpanel" id="p-1" aria-labelledby="t-1">…</section>
+ *     <section role="tabpanel" id="p-2" aria-labelledby="t-2" hidden>…</section>
+ *   </div>
+ *
+ * Keyboard:
+ *   ArrowLeft / ArrowRight — move focus across tabs (roving tabindex)
+ *   Home / End             — jump to first / last
+ *   Enter / Space          — activate focused tab (manual activation)
+ *
+ * Dispatches `re-change` (bubbles, cancelable) on the host `[data-re-tabs]`
+ * with `detail = { tabId, panelId }` whenever the selected tab changes.
+ *
+ *   import { enhanceTabs } from "@relements/core/behaviors/tabs";
+ *   const c = enhanceTabs(document);
+ *   c.destroy();
+ */
+
+/** @typedef {{ destroy: () => void }} Controller */
+
+/**
+ * @param {Document | Element | ShadowRoot} [root=document]
+ * @returns {Controller}
+ */
+export function enhanceTabs(root = document) {
+  if (root == null) {
+    throw new TypeError("enhanceTabs: root must be a Document, Element, or ShadowRoot");
+  }
+
+  /** @type {Array<{ host: Element; cleanup: () => void }>} */
+  const hosts = [];
+
+  // Include the root itself when it carries the marker (e.g. a custom element host).
+  if (root instanceof Element && /** @type {Element} */ (root).matches?.("[data-re-tabs]")) {
+    const cleanup = wireOne(/** @type {HTMLElement} */ (root));
+    hosts.push({ host: root, cleanup });
+  }
+
+  /** @type {NodeListOf<Element>} */
+  const tabsList = root.querySelectorAll("[data-re-tabs]");
+  tabsList.forEach((host) => {
+    const cleanup = wireOne(/** @type {HTMLElement} */ (host));
+    hosts.push({ host, cleanup });
+  });
+
+  return {
+    destroy() {
+      while (hosts.length) {
+        const entry = hosts.pop();
+        entry?.cleanup();
+      }
+    },
+  };
+}
+
+/**
+ * @param {HTMLElement} host
+ * @returns {() => void}
+ */
+function wireOne(host) {
+  const tablist = host.querySelector('[role="tablist"]');
+  if (!tablist) return () => {};
+  /** @type {HTMLElement[]} */
+  const tabs = Array.from(tablist.querySelectorAll('[role="tab"]'));
+  if (tabs.length === 0) return () => {};
+
+  // Ensure roving tabindex matches aria-selected.
+  const syncRoving = () => {
+    for (const t of tabs) {
+      t.tabIndex = t.getAttribute("aria-selected") === "true" ? 0 : -1;
+    }
+  };
+  syncRoving();
+
+  /**
+   * @param {HTMLElement} tab
+   * @param {{ focus?: boolean }} [opts]
+   */
+  const select = (tab, opts = {}) => {
+    if (tab.getAttribute("aria-selected") === "true") {
+      if (opts.focus) tab.focus();
+      return;
+    }
+    const panelId = tab.getAttribute("aria-controls");
+    const cancelled = !host.dispatchEvent(
+      new CustomEvent("re-change", {
+        bubbles: true,
+        cancelable: true,
+        detail: { tabId: tab.id, panelId },
+      }),
+    );
+    if (cancelled) return;
+
+    for (const t of tabs) {
+      const isMe = t === tab;
+      t.setAttribute("aria-selected", isMe ? "true" : "false");
+      t.tabIndex = isMe ? 0 : -1;
+      const pid = t.getAttribute("aria-controls");
+      if (pid) {
+        const panel = host.querySelector(`#${cssEscape(pid)}`);
+        if (panel) /** @type {HTMLElement} */ (panel).hidden = !isMe;
+      }
+    }
+    if (opts.focus) tab.focus();
+  };
+
+  /** @param {Event} event */
+  const onClick = (event) => {
+    const t = /** @type {Element | null} */ (event.target);
+    const tab = t?.closest('[role="tab"]');
+    if (tab && tabs.includes(/** @type {HTMLElement} */ (tab))) {
+      select(/** @type {HTMLElement} */ (tab), { focus: true });
+    }
+  };
+
+  /** @param {KeyboardEvent} event */
+  const onKey = (event) => {
+    const current = document.activeElement;
+    if (!current || !tabs.includes(/** @type {HTMLElement} */ (current))) return;
+    const idx = tabs.indexOf(/** @type {HTMLElement} */ (current));
+    if (idx === -1) return;
+    let nextIdx = idx;
+    switch (event.key) {
+      case "ArrowRight":
+        nextIdx = (idx + 1) % tabs.length;
+        break;
+      case "ArrowLeft":
+        nextIdx = (idx - 1 + tabs.length) % tabs.length;
+        break;
+      case "Home":
+        nextIdx = 0;
+        break;
+      case "End":
+        nextIdx = tabs.length - 1;
+        break;
+      case "Enter":
+      case " ":
+      case "Spacebar":
+        event.preventDefault();
+        select(/** @type {HTMLElement} */ (current), { focus: true });
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+    tabs[nextIdx].focus();
+    select(tabs[nextIdx]);
+  };
+
+  tablist.addEventListener("click", onClick);
+  tablist.addEventListener("keydown", /** @type {EventListener} */ (onKey));
+
+  return () => {
+    tablist.removeEventListener("click", onClick);
+    tablist.removeEventListener("keydown", /** @type {EventListener} */ (onKey));
+  };
+}
+
+/** @param {string} value */
+function cssEscape(value) {
+  return typeof CSS !== "undefined" && CSS.escape ? CSS.escape(value) : value;
+}

package/src/behaviors/toast.js

@@ -0,0 +1,97 @@
+/**
+ * Toast helpers.
+ *
+ *   <div class="re-toast-region" data-re-toast-region role="region" aria-label="Notifications">
+ *     <ul class="re-toast-list" aria-live="polite" aria-relevant="additions"></ul>
+ *   </div>
+ *
+ *   import { showToast } from "@relements/core/behaviors/toast";
+ *   showToast("Saved", { tone: "success" });
+ *   showToast("Network error", { tone: "danger", duration: 8000 });
+ *
+ * If no `[data-re-toast-region]` exists, one is created and appended to
+ * `document.body` on first call.
+ */
+
+/**
+ * @typedef {object} ToastOptions
+ * @property {"default"|"success"|"warning"|"danger"} [tone="default"]
+ * @property {number} [duration=4000]  Auto-dismiss in ms. Pass 0 to disable.
+ * @property {Document|Element} [root]  Override the host to search for a region in.
+ */
+
+/**
+ * @param {string} message
+ * @param {ToastOptions} [options]
+ * @returns {{ dismiss: () => void; element: HTMLDivElement }}
+ */
+export function showToast(message, options = {}) {
+  const { tone = "default", duration = 4000, root = document } = options;
+
+  const list = ensureRegion(root).querySelector(".re-toast-list");
+  if (!list) {
+    throw new Error("showToast: toast region missing a `.re-toast-list`");
+  }
+
+  const item = document.createElement("div");
+  item.className = "re-toast";
+  if (tone !== "default") item.dataset.tone = tone;
+  item.setAttribute("role", tone === "danger" ? "alert" : "status");
+
+  const body = document.createElement("div");
+  body.className = "re-toast__body";
+  body.textContent = message;
+  item.appendChild(body);
+
+  const dismissBtn = document.createElement("button");
+  dismissBtn.type = "button";
+  dismissBtn.className = "re-toast__dismiss";
+  dismissBtn.setAttribute("aria-label", "Dismiss notification");
+  dismissBtn.textContent = "×";
+  item.appendChild(dismissBtn);
+
+  list.appendChild(item);
+
+  /** @type {ReturnType<typeof setTimeout> | undefined} */
+  let timer;
+  const dismiss = () => {
+    if (timer != null) {
+      clearTimeout(timer);
+      timer = undefined;
+    }
+    item.dispatchEvent(new CustomEvent("re-toast-dismiss", { bubbles: true }));
+    item.remove();
+  };
+
+  dismissBtn.addEventListener("click", dismiss);
+
+  if (duration > 0) {
+    timer = setTimeout(dismiss, duration);
+  }
+
+  return { dismiss, element: item };
+}
+
+/**
+ * @param {Document|Element} root
+ * @returns {HTMLElement}
+ */
+function ensureRegion(root) {
+  const scope =
+    root instanceof Document ? root : /** @type {Element} */ (root.ownerDocument ?? document);
+  /** @type {HTMLElement | null} */
+  let region = /** @type {HTMLElement | null} */ (scope.querySelector("[data-re-toast-region]"));
+  if (region) return region;
+  region = scope.createElement("div");
+  region.className = "re-toast-region";
+  region.setAttribute("role", "region");
+  region.setAttribute("aria-label", "Notifications");
+  region.dataset.reToastRegion = "";
+  const list = scope.createElement("div");
+  list.className = "re-toast-list";
+  list.setAttribute("aria-live", "polite");
+  list.setAttribute("aria-relevant", "additions");
+  region.appendChild(list);
+  scope.body.appendChild(region);
+  return region;
+}

package/src/components/button.css

@@ -0,0 +1,141 @@
+/**
+ * Relements button.
+ *
+ * Applies to <button>, <a class="re-button">, and <input type="submit|button|reset">.
+ * Native semantics stay intact — this is purely styling on top of the host element.
+ *
+ * Variants (data-variant):
+ *   primary    — accent fill, white text. Default if data-variant absent.
+ *   secondary  — outlined neutral
+ *   ghost      — transparent, neutral text, no border
+ *   danger     — danger fill
+ *
+ * Sizes (data-size):
+ *   sm, md (default), lg
+ *
+ * States:
+ *   :disabled, :hover, :active, :focus-visible, [aria-disabled="true"]
+ */
+
+@layer re.components {
+  .re-button {
+    /* token-bound layout */
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: var(--re-space-2);
+    box-sizing: border-box;
+
+    /* default = primary md */
+    block-size: var(--re-control-height-md);
+    padding-inline: var(--re-space-4);
+    padding-block: 0;
+
+    /* type */
+    font: inherit;
+    font-weight: var(--re-font-weight-medium);
+    font-size: var(--re-size-text-md);
+    line-height: 1;
+    text-align: center;
+    text-decoration: none;
+    white-space: nowrap;
+    user-select: none;
+
+    /* surface */
+    color: var(--re-color-text-on-accent);
+    background-color: var(--re-color-accent-600);
+    border: var(--re-border-width) solid transparent;
+    border-radius: var(--re-radius-md);
+    cursor: pointer;
+
+    transition:
+      background-color var(--re-duration-fast) var(--re-easing-standard),
+      color var(--re-duration-fast) var(--re-easing-standard),
+      border-color var(--re-duration-fast) var(--re-easing-standard),
+      box-shadow var(--re-duration-fast) var(--re-easing-standard);
+  }
+
+  /* Make link-as-button visually identical and behave on tap. */
+  a.re-button {
+    -webkit-tap-highlight-color: transparent;
+  }
+
+  .re-button:hover {
+    background-color: var(--re-color-accent-700);
+  }
+
+  .re-button:active {
+    background-color: var(--re-color-accent-800);
+  }
+
+  .re-button:focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+  }
+
+  /* ---- Disabled (native + aria) ---------------------------------------- */
+  .re-button:disabled,
+  .re-button[aria-disabled="true"] {
+    cursor: not-allowed;
+    opacity: 0.55;
+    pointer-events: none;
+  }
+  /* Allow aria-disabled link buttons to keep keyboard focus. */
+  a.re-button[aria-disabled="true"] {
+    pointer-events: none;
+  }
+
+  /* ---- Variants -------------------------------------------------------- */
+  .re-button[data-variant="secondary"] {
+    color: var(--re-color-text);
+    background-color: var(--re-color-bg);
+    border-color: var(--re-color-border-strong);
+  }
+  .re-button[data-variant="secondary"]:hover {
+    background-color: var(--re-color-bg-subtle);
+  }
+  .re-button[data-variant="secondary"]:active {
+    background-color: var(--re-color-bg-muted);
+  }
+
+  .re-button[data-variant="ghost"] {
+    color: var(--re-color-text);
+    background-color: transparent;
+    border-color: transparent;
+  }
+  .re-button[data-variant="ghost"]:hover {
+    background-color: var(--re-color-bg-subtle);
+  }
+  .re-button[data-variant="ghost"]:active {
+    background-color: var(--re-color-bg-muted);
+  }
+
+  .re-button[data-variant="danger"] {
+    color: var(--re-color-text-on-accent);
+    background-color: var(--re-color-danger-600);
+  }
+  .re-button[data-variant="danger"]:hover {
+    background-color: var(--re-color-danger-700);
+  }
+  .re-button[data-variant="danger"]:active {
+    background-color: var(--re-color-danger-700);
+    filter: brightness(0.95);
+  }
+
+  /* ---- Sizes ----------------------------------------------------------- */
+  .re-button[data-size="sm"] {
+    block-size: var(--re-control-height-sm);
+    padding-inline: var(--re-space-3);
+    font-size: var(--re-size-text-sm);
+  }
+  .re-button[data-size="lg"] {
+    block-size: var(--re-control-height-lg);
+    padding-inline: var(--re-space-5);
+    font-size: var(--re-size-text-lg);
+  }
+
+  /* ---- Full-width modifier -------------------------------------------- */
+  .re-button[data-full-width] {
+    inline-size: 100%;
+  }
+}

package/src/components/dialog.css

@@ -0,0 +1,106 @@
+/**
+ * Relements dialog.
+ *
+ * Styled native <dialog>. The browser owns showModal/show/close, focus
+ * trap, backdrop, and Escape-to-dismiss. This stylesheet supplies
+ * surface, header/body/footer slots, and the backdrop look.
+ *
+ *   <dialog class="re-dialog">
+ *     <header class="re-dialog__header">
+ *       <h2 class="re-dialog__title">…</h2>
+ *       <button class="re-dialog__close" aria-label="Close">×</button>
+ *     </header>
+ *     <div class="re-dialog__body">…</div>
+ *     <footer class="re-dialog__footer">…</footer>
+ *   </dialog>
+ */
+
+@layer re.components {
+  /* Restore the native hide-when-closed behaviour.
+     CSS layers beat the UA stylesheet, so display:flex without this
+     override makes ALL .re-dialog elements visible at all times. */
+  .re-dialog:not([open]) {
+    display: none;
+  }
+
+  .re-dialog {
+    box-sizing: border-box;
+    border: var(--re-border-default);
+    border-radius: var(--re-radius-lg);
+    background-color: var(--re-color-surface);
+    color: var(--re-color-text);
+    padding: 0;
+    inline-size: min(90vw, 32rem);
+    max-block-size: min(85vh, 40rem);
+    box-shadow: var(--re-shadow-lg);
+    overflow: hidden;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* Backdrop owned by the browser; tint with tokens. */
+  .re-dialog::backdrop {
+    background-color: rgb(0 0 0 / 0.4);
+    backdrop-filter: blur(2px);
+  }
+
+  .re-dialog:focus-visible {
+    outline: none;
+  }
+
+  .re-dialog__header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--re-space-3);
+    padding: var(--re-space-4);
+    border-block-end: var(--re-border-default);
+  }
+
+  .re-dialog__title {
+    margin: 0;
+    font-size: var(--re-size-text-lg);
+    font-weight: var(--re-font-weight-semibold);
+    line-height: var(--re-line-height-tight);
+    color: var(--re-color-text);
+  }
+
+  .re-dialog__close {
+    appearance: none;
+    background: transparent;
+    border: 0;
+    cursor: pointer;
+    padding: var(--re-space-1) var(--re-space-2);
+    border-radius: var(--re-radius-md);
+    color: var(--re-color-text-muted);
+    font: inherit;
+    font-size: var(--re-size-text-xl);
+    line-height: 1;
+    transition: background-color var(--re-duration-fast) var(--re-easing-standard);
+  }
+
+  .re-dialog__close:hover {
+    background-color: var(--re-color-bg-subtle);
+    color: var(--re-color-text);
+  }
+
+  .re-dialog__close:focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+  }
+
+  .re-dialog__body {
+    padding: var(--re-space-4);
+    overflow-y: auto;
+    line-height: var(--re-line-height-normal);
+  }
+
+  .re-dialog__footer {
+    display: flex;
+    justify-content: flex-end;
+    gap: var(--re-space-3);
+    padding: var(--re-space-4);
+    border-block-start: var(--re-border-default);
+    background-color: var(--re-color-bg-subtle);
+  }
+}

package/src/components/disclosure.css

@@ -0,0 +1,83 @@
+/**
+ * Relements disclosure.
+ *
+ * Styled native <details>/<summary>. Toggle behavior, keyboard, and
+ * accessibility are owned by the browser; this stylesheet supplies layout
+ * and visual affordances only.
+ *
+ *   <details class="re-disclosure">
+ *     <summary class="re-disclosure__summary">Title</summary>
+ *     <div class="re-disclosure__body">…</div>
+ *   </details>
+ *
+ * Variants (data-variant on <details>):
+ *   default — bordered card
+ *   plain   — borderless, just a hover background on the summary
+ */
+
+@layer re.components {
+  .re-disclosure {
+    border: var(--re-border-default);
+    border-radius: var(--re-radius-md);
+    background-color: var(--re-color-surface);
+    overflow: hidden; /* keep summary corners aligned with the border-radius */
+  }
+
+  .re-disclosure__summary {
+    list-style: none; /* hide default marker; replaced with our chevron */
+    cursor: pointer;
+    padding: var(--re-space-3) var(--re-space-4);
+    font-weight: var(--re-font-weight-medium);
+    color: var(--re-color-text);
+    display: flex;
+    align-items: center;
+    gap: var(--re-space-3);
+    user-select: none;
+    transition: background-color var(--re-duration-fast) var(--re-easing-standard);
+  }
+  .re-disclosure__summary::-webkit-details-marker {
+    display: none;
+  }
+
+  .re-disclosure__summary::before {
+    content: "";
+    flex-shrink: 0;
+    inline-size: 0.6rem;
+    block-size: 0.6rem;
+    border-inline-end: 2px solid currentColor;
+    border-block-end: 2px solid currentColor;
+    transform: rotate(-45deg);
+    transition: transform var(--re-duration-fast) var(--re-easing-standard);
+    margin-inline-end: var(--re-space-1);
+  }
+
+  .re-disclosure[open] > .re-disclosure__summary::before {
+    transform: rotate(45deg);
+  }
+
+  .re-disclosure__summary:hover {
+    background-color: var(--re-color-bg-subtle);
+  }
+
+  .re-disclosure__summary:focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+  }
+
+  .re-disclosure__body {
+    padding: var(--re-space-3) var(--re-space-4) var(--re-space-4);
+    border-block-start: var(--re-border-default);
+    color: var(--re-color-text);
+    line-height: var(--re-line-height-normal);
+  }
+
+  /* ---- Variants -------------------------------------------------------- */
+  .re-disclosure[data-variant="plain"] {
+    border: 0;
+    background: transparent;
+  }
+  .re-disclosure[data-variant="plain"] > .re-disclosure__body {
+    border-block-start: 0;
+    padding-block-start: var(--re-space-2);
+  }
+}