@relements/core 0.1.0

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@relements/core",
+  "version": "0.1.0",
+  "description": "HTML-first design system core: tokens, styles, and progressive enhancement.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "**/*.css",
+    "dist/**/*.css"
+  ],
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./index.css": "./dist/index.css",
+    "./tokens.css": "./dist/tokens.css",
+    "./reset.css": "./dist/reset.css",
+    "./base.css": "./dist/base.css",
+    "./components/button.css": "./dist/components/button.css",
+    "./components/link.css": "./dist/components/link.css",
+    "./components/form.css": "./dist/components/form.css",
+    "./components/disclosure.css": "./dist/components/disclosure.css",
+    "./components/dialog.css": "./dist/components/dialog.css",
+    "./components/progress.css": "./dist/components/progress.css",
+    "./components/tabs.css": "./dist/components/tabs.css",
+    "./components/menu.css": "./dist/components/menu.css",
+    "./components/popover.css": "./dist/components/popover.css",
+    "./components/toast.css": "./dist/components/toast.css",
+    "./themes/renascent.css": "./dist/themes/renascent.css",
+    "./behaviors/dismissible": {
+      "import": "./dist/behaviors/dismissible.js",
+      "types": "./dist/behaviors/dismissible.d.ts"
+    },
+    "./behaviors/dialog": {
+      "import": "./dist/behaviors/dialog.js",
+      "types": "./dist/behaviors/dialog.d.ts"
+    },
+    "./behaviors/tabs": {
+      "import": "./dist/behaviors/tabs.js",
+      "types": "./dist/behaviors/tabs.d.ts"
+    },
+    "./behaviors/menu-button": {
+      "import": "./dist/behaviors/menu-button.js",
+      "types": "./dist/behaviors/menu-button.d.ts"
+    },
+    "./behaviors/popover": {
+      "import": "./dist/behaviors/popover.js",
+      "types": "./dist/behaviors/popover.d.ts"
+    },
+    "./behaviors/toast": {
+      "import": "./dist/behaviors/toast.js",
+      "types": "./dist/behaviors/toast.d.ts"
+    },
+    "./elements/re-tabs": {
+      "import": "./dist/elements/re-tabs.js",
+      "types": "./dist/elements/re-tabs.d.ts"
+    },
+    "./elements/re-toast": {
+      "import": "./dist/elements/re-toast.js",
+      "types": "./dist/elements/re-toast.d.ts"
+    },
+    "./elements/re-menu": {
+      "import": "./dist/elements/re-menu.js",
+      "types": "./dist/elements/re-menu.d.ts"
+    },
+    "./elements/re-popover": {
+      "import": "./dist/elements/re-popover.js",
+      "types": "./dist/elements/re-popover.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build:css": "node build-css.mjs",
+    "build:js": "tsup",
+    "build": "node build-css.mjs && tsup"
+  }
+}

package/src/base.css

@@ -0,0 +1,129 @@
+/**
+ * Relements base styles.
+ *
+ * Document-level defaults driven by tokens. Applies to plain HTML without
+ * any `re-*` classes — loading `index.css` should already produce a readable
+ * page. Component styles in `re.components` take precedence.
+ */
+
+@layer re.base {
+  :root {
+    color-scheme: light dark;
+  }
+
+  html {
+    font-family: var(--re-font-sans);
+    font-size: var(--re-size-text-md);
+    line-height: var(--re-line-height-normal);
+    color: var(--re-color-text);
+    background-color: var(--re-color-bg);
+  }
+
+  ::selection {
+    background-color: var(--re-color-selection-bg);
+    color: var(--re-color-selection-text);
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    line-height: var(--re-line-height-tight);
+    font-weight: var(--re-font-weight-semibold);
+    color: var(--re-color-text);
+  }
+
+  h1 {
+    font-size: var(--re-size-text-4xl);
+  }
+  h2 {
+    font-size: var(--re-size-text-3xl);
+  }
+  h3 {
+    font-size: var(--re-size-text-2xl);
+  }
+  h4 {
+    font-size: var(--re-size-text-xl);
+  }
+  h5 {
+    font-size: var(--re-size-text-lg);
+  }
+  h6 {
+    font-size: var(--re-size-text-md);
+  }
+
+  p {
+    line-height: var(--re-line-height-normal);
+    color: var(--re-color-text);
+  }
+
+  small {
+    font-size: var(--re-size-text-sm);
+    color: var(--re-color-text-muted);
+  }
+
+  code,
+  kbd,
+  samp,
+  pre {
+    font-family: var(--re-font-mono);
+    font-size: 0.95em;
+  }
+
+  pre {
+    overflow: auto;
+    padding: var(--re-space-3) var(--re-space-4);
+    background-color: var(--re-color-bg-muted);
+    border-radius: var(--re-radius-md);
+  }
+
+  code {
+    padding: 0.1em 0.3em;
+    background-color: var(--re-color-bg-muted);
+    border-radius: var(--re-radius-sm);
+  }
+
+  pre code {
+    padding: 0;
+    background: none;
+    border-radius: 0;
+  }
+
+  hr {
+    border: 0;
+    border-top: var(--re-border-default);
+    margin-block: var(--re-space-6);
+  }
+
+  /* Native link default — `.re-link` overrides per component contract. */
+  a {
+    color: var(--re-color-link);
+    text-decoration-thickness: 0.08em;
+    text-underline-offset: 0.2em;
+  }
+
+  a:hover {
+    color: var(--re-color-link-hover);
+  }
+
+  a:visited {
+    color: var(--re-color-link-visited);
+  }
+
+  /* Visible focus for all interactive elements unless a component opts out. */
+  :focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+    border-radius: var(--re-radius-sm);
+  }
+
+  /* Native form controls inherit token colors. Component CSS may override. */
+  input,
+  textarea,
+  select {
+    color: var(--re-color-text);
+    background-color: var(--re-color-bg);
+  }
+}

package/src/behaviors/dialog.js

@@ -0,0 +1,106 @@
+/**
+ * enhanceDialog
+ * -------------
+ * Lightweight ergonomic helpers for native <dialog>.
+ *
+ * Wires:
+ *   - `[data-re-dialog-trigger]` → opens the <dialog> referenced by its
+ *     `data-re-dialog-target="dialog-id"` attribute (or aria-controls).
+ *   - `[data-re-dialog-close]` inside a <dialog> → closes the parent dialog,
+ *     setting the dialog's returnValue to the element's value attribute.
+ *   - Click on the dialog's backdrop closes the dialog when the dialog
+ *     element itself has `data-re-dialog-close-on-backdrop`.
+ *
+ * Usage:
+ *
+ *   <button type="button" data-re-dialog-trigger data-re-dialog-target="confirm">
+ *     Open
+ *   </button>
+ *   <dialog id="confirm" data-re-dialog-close-on-backdrop>
+ *     …
+ *     <button data-re-dialog-close value="cancel">Cancel</button>
+ *   </dialog>
+ *
+ *   import { enhanceDialog } from "@relements/core/behaviors/dialog";
+ *   const c = enhanceDialog(document);
+ *   c.destroy();
+ *
+ * Native semantics are preserved: showModal/close/Escape behavior all
+ * come from the browser.
+ */
+
+/**
+ * @param {Document | Element | ShadowRoot} [root=document]
+ * @returns {{ destroy: () => void }}
+ */
+export function enhanceDialog(root = document) {
+  if (root == null) {
+    throw new TypeError("enhanceDialog: root must be a Document, Element, or ShadowRoot");
+  }
+
+  /** @param {Event} event */
+  const onClick = (event) => {
+    const target = /** @type {Element | null} */ (event.target);
+    if (!target) return;
+
+    // 1) Trigger → open dialog
+    const trigger = target.closest("[data-re-dialog-trigger]");
+    if (trigger) {
+      const id =
+        trigger.getAttribute("data-re-dialog-target") ?? trigger.getAttribute("aria-controls");
+      if (!id) return;
+      const ownerDoc = trigger.ownerDocument;
+      const dialog = /** @type {HTMLDialogElement | null} */ (ownerDoc.getElementById(id));
+      if (dialog && typeof dialog.showModal === "function" && !dialog.open) {
+        dialog.showModal();
+      }
+      return;
+    }
+
+    // 2) Close button inside a dialog
+    const closeBtn = target.closest("[data-re-dialog-close]");
+    if (closeBtn) {
+      const dialog = /** @type {HTMLDialogElement | null} */ (closeBtn.closest("dialog"));
+      if (dialog && dialog.open) {
+        const value = /** @type {HTMLButtonElement} */ (closeBtn).value || "";
+        dialog.close(value);
+      }
+      return;
+    }
+
+    // 3) Backdrop click → close (only when opted in)
+    if (target.tagName === "DIALOG") {
+      const dialog = /** @type {HTMLDialogElement} */ (target);
+      if (
+        dialog.open &&
+        dialog.hasAttribute("data-re-dialog-close-on-backdrop") &&
+        isEventOnBackdrop(/** @type {MouseEvent} */ (event), dialog)
+      ) {
+        dialog.close("backdrop");
+      }
+    }
+  };
+
+  root.addEventListener("click", onClick);
+
+  return {
+    destroy() {
+      root.removeEventListener("click", onClick);
+    },
+  };
+}
+
+/**
+ * The native ::backdrop pseudo-element is the click target when the user
+ * clicks outside the dialog box. Detect by comparing the click coordinates
+ * against the dialog's bounding box.
+ *
+ * @param {MouseEvent} event
+ * @param {HTMLDialogElement} dialog
+ * @returns {boolean}
+ */
+function isEventOnBackdrop(event, dialog) {
+  const rect = dialog.getBoundingClientRect();
+  const { clientX: x, clientY: y } = event;
+  return x < rect.left || x > rect.right || y < rect.top || y > rect.bottom;
+}

package/src/behaviors/dismissible.js

@@ -0,0 +1,68 @@
+/**
+ * enhanceDismissible
+ * ------------------
+ * Wires up dismiss buttons inside any element marked `[data-re-dismissible]`.
+ *
+ * Usage in HTML:
+ *
+ *   <aside data-re-dismissible>
+ *     Banner copy…
+ *     <button type="button" data-re-dismiss aria-label="Dismiss">×</button>
+ *   </aside>
+ *
+ * Usage in JavaScript:
+ *
+ *   import { enhanceDismissible } from "@relements/core/behaviors/dismissible";
+ *   const controller = enhanceDismissible(document);
+ *   // …later
+ *   controller.destroy();
+ *
+ * Behavior:
+ *   - Click or Enter/Space on `[data-re-dismiss]` hides the closest
+ *     `[data-re-dismissible]` ancestor (sets `hidden`).
+ *   - Dispatches a `re-dismiss` `CustomEvent` (bubbles, cancelable) on the
+ *     dismissible element before hiding; calling `preventDefault()` cancels.
+ *   - `controller.destroy()` removes all listeners.
+ *
+ * Root can be a Document, Element, or ShadowRoot.
+ */
+
+/**
+ * @param {Document | Element | ShadowRoot} [root=document]
+ * @returns {{ destroy: () => void }}
+ */
+export function enhanceDismissible(root = document) {
+  if (root == null) {
+    throw new TypeError("enhanceDismissible: root must be a Document, Element, or ShadowRoot");
+  }
+
+  /** @type {(event: Event) => void} */
+  const handle = (event) => {
+    const target = /** @type {Element | null} */ (event.target);
+    if (!target) return;
+    const trigger = target.closest("[data-re-dismiss]");
+    if (!trigger) return;
+    if (event.type === "keydown") {
+      const ke = /** @type {KeyboardEvent} */ (event);
+      if (ke.key !== "Enter" && ke.key !== " " && ke.key !== "Spacebar") return;
+      ke.preventDefault();
+    }
+    const host = trigger.closest("[data-re-dismissible]");
+    if (!host) return;
+    const cancelable = host.dispatchEvent(
+      new CustomEvent("re-dismiss", { bubbles: true, cancelable: true }),
+    );
+    if (!cancelable) return;
+    /** @type {HTMLElement} */ (host).hidden = true;
+  };
+
+  root.addEventListener("click", handle);
+  root.addEventListener("keydown", handle);
+
+  return {
+    destroy() {
+      root.removeEventListener("click", handle);
+      root.removeEventListener("keydown", handle);
+    },
+  };
+}

package/src/behaviors/menu-button.js

@@ -0,0 +1,199 @@
+/**
+ * enhanceMenuButton
+ * -----------------
+ * ARIA menu-button pattern over markup like:
+ *
+ *   <div class="re-menu" data-re-menu>
+ *     <button aria-haspopup="menu" aria-expanded="false" aria-controls="m-1" id="b-1">…</button>
+ *     <div role="menu" id="m-1" aria-labelledby="b-1" hidden>
+ *       <button role="menuitem">Rename</button>
+ *       …
+ *     </div>
+ *   </div>
+ *
+ * Behavior:
+ *   - Click the button toggles the menu.
+ *   - ArrowDown opens the menu and focuses the first item.
+ *   - Up/Down on items moves focus within the menu (wraps).
+ *   - Home/End jump.
+ *   - Escape closes the menu and returns focus to the button.
+ *   - Tab outside the menu closes it.
+ *   - Clicking outside closes it.
+ *
+ * Dispatches `re-select` (bubbles, cancelable) when a menuitem is activated:
+ *   detail = { item: HTMLElement, value: string }
+ */
+
+/** @typedef {{ destroy: () => void }} Controller */
+
+/**
+ * @param {Document | Element | ShadowRoot} [root=document]
+ * @returns {Controller}
+ */
+export function enhanceMenuButton(root = document) {
+  if (root == null) {
+    throw new TypeError("enhanceMenuButton: root must be a Document, Element, or ShadowRoot");
+  }
+
+  /** @type {Array<() => void>} */
+  const cleanups = [];
+
+  if (root instanceof Element && /** @type {Element} */ (root).matches?.("[data-re-menu]")) {
+    cleanups.push(wireOne(/** @type {HTMLElement} */ (root)));
+  }
+
+  /** @type {NodeListOf<Element>} */
+  const hosts = root.querySelectorAll("[data-re-menu]");
+  hosts.forEach((host) => {
+    cleanups.push(wireOne(/** @type {HTMLElement} */ (host)));
+  });
+
+  return {
+    destroy() {
+      while (cleanups.length) {
+        const fn = cleanups.pop();
+        fn?.();
+      }
+    },
+  };
+}
+
+/**
+ * @param {HTMLElement} host
+ * @returns {() => void}
+ */
+function wireOne(host) {
+  const button = /** @type {HTMLElement | null} */ (
+    host.querySelector('[aria-haspopup="menu"], [aria-haspopup="true"]')
+  );
+  const panel = /** @type {HTMLElement | null} */ (host.querySelector('[role="menu"]'));
+  if (!button || !panel) return () => {};
+
+  const items = () =>
+    /** @type {HTMLElement[]} */ (
+      Array.from(panel.querySelectorAll('[role="menuitem"]:not([disabled])'))
+    );
+
+  const isOpen = () => button.getAttribute("aria-expanded") === "true";
+
+  /** @param {boolean} open */
+  const setOpen = (open) => {
+    button.setAttribute("aria-expanded", String(open));
+    panel.hidden = !open;
+  };
+
+  /** @param {{ focusFirst?: boolean }} [opts] */
+  const openMenu = (opts = {}) => {
+    if (isOpen()) return;
+    setOpen(true);
+    if (opts.focusFirst) {
+      const first = items()[0];
+      first?.focus();
+    }
+  };
+
+  /** @param {{ returnFocus?: boolean }} [opts] */
+  const closeMenu = (opts = {}) => {
+    if (!isOpen()) return;
+    setOpen(false);
+    if (opts.returnFocus) button.focus();
+  };
+
+  /** @param {Event} event */
+  const onButtonClick = (event) => {
+    event.stopPropagation();
+    if (isOpen()) closeMenu();
+    else openMenu({ focusFirst: false });
+  };
+
+  /** @param {KeyboardEvent} event */
+  const onButtonKey = (event) => {
+    if (event.key === "ArrowDown" || event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      openMenu({ focusFirst: true });
+    } else if (event.key === "ArrowUp") {
+      event.preventDefault();
+      openMenu();
+      const all = items();
+      all[all.length - 1]?.focus();
+    }
+  };
+
+  /** @param {KeyboardEvent} event */
+  const onPanelKey = (event) => {
+    const all = items();
+    const active = document.activeElement;
+    const idx = all.findIndex((el) => el === active);
+    switch (event.key) {
+      case "ArrowDown": {
+        event.preventDefault();
+        const next = all[(idx + 1 + all.length) % all.length];
+        next?.focus();
+        return;
+      }
+      case "ArrowUp": {
+        event.preventDefault();
+        const prev = all[(idx - 1 + all.length) % all.length];
+        prev?.focus();
+        return;
+      }
+      case "Home":
+        event.preventDefault();
+        all[0]?.focus();
+        return;
+      case "End":
+        event.preventDefault();
+        all[all.length - 1]?.focus();
+        return;
+      case "Escape":
+        event.preventDefault();
+        closeMenu({ returnFocus: true });
+        return;
+      case "Tab":
+        closeMenu();
+        return;
+    }
+  };
+
+  /** @param {Event} event */
+  const onPanelClick = (event) => {
+    const target = /** @type {Element | null} */ (event.target);
+    if (!target) return;
+    const item = target.closest('[role="menuitem"]');
+    if (!item) return;
+    const value =
+      /** @type {HTMLElement} */ (item).dataset.value ??
+      /** @type {HTMLElement} */ (item).textContent?.trim() ??
+      "";
+    const allowed = host.dispatchEvent(
+      new CustomEvent("re-select", {
+        bubbles: true,
+        cancelable: true,
+        detail: { item, value },
+      }),
+    );
+    if (allowed) closeMenu({ returnFocus: true });
+  };
+
+  /** @param {Event} event */
+  const onOutsideClick = (event) => {
+    if (!isOpen()) return;
+    const t = /** @type {Node | null} */ (event.target);
+    if (t && host.contains(t)) return;
+    closeMenu();
+  };
+
+  button.addEventListener("click", onButtonClick);
+  button.addEventListener("keydown", /** @type {EventListener} */ (onButtonKey));
+  panel.addEventListener("keydown", /** @type {EventListener} */ (onPanelKey));
+  panel.addEventListener("click", onPanelClick);
+  document.addEventListener("click", onOutsideClick);
+
+  return () => {
+    button.removeEventListener("click", onButtonClick);
+    button.removeEventListener("keydown", /** @type {EventListener} */ (onButtonKey));
+    panel.removeEventListener("keydown", /** @type {EventListener} */ (onPanelKey));
+    panel.removeEventListener("click", onPanelClick);
+    document.removeEventListener("click", onOutsideClick);
+  };
+}

package/src/behaviors/popover.js

@@ -0,0 +1,103 @@
+/**
+ * enhancePopover
+ * --------------
+ * Thin helper for native [popover]. Provides:
+ *   - Anchored positioning: places the popover below its `popovertarget`
+ *     button when the popover opens. (Native CSS Anchor Positioning isn't
+ *     universally supported yet; this is a tiny JS fallback.)
+ *   - `re-toggle` CustomEvent on the popover element when it opens/closes
+ *     (detail = { open: boolean }), mirroring the native `toggle` event so
+ *     consumers don't need feature-detect it.
+ *
+ *   <button class="re-button" popovertarget="tip">Toggle</button>
+ *   <div class="re-popover" id="tip" popover data-re-popover>Hello</div>
+ *
+ *   import { enhancePopover } from "@relements/core/behaviors/popover";
+ *   const c = enhancePopover(document);
+ */
+
+/** @typedef {{ destroy: () => void }} Controller */
+
+/**
+ * @param {Document | Element | ShadowRoot} [root=document]
+ * @returns {Controller}
+ */
+export function enhancePopover(root = document) {
+  if (root == null) {
+    throw new TypeError("enhancePopover: root must be a Document, Element, or ShadowRoot");
+  }
+
+  /** @type {Array<() => void>} */
+  const cleanups = [];
+
+  if (root instanceof Element && /** @type {Element} */ (root).matches?.("[data-re-popover]")) {
+    cleanups.push(wireOne(/** @type {HTMLElement} */ (root)));
+  }
+
+  /** @type {NodeListOf<HTMLElement>} */
+  const popovers = root.querySelectorAll("[data-re-popover]");
+  popovers.forEach((pop) => {
+    cleanups.push(wireOne(pop));
+  });
+
+  return {
+    destroy() {
+      while (cleanups.length) cleanups.pop()?.();
+    },
+  };
+}
+
+/**
+ * @param {HTMLElement} popover
+ * @returns {() => void}
+ */
+function wireOne(popover) {
+  if (!("popover" in popover) || typeof popover.showPopover !== "function") {
+    // Native popover API unavailable. Bail out gracefully.
+    return () => {};
+  }
+
+  /** @param {Event} event */
+  const onToggle = (event) => {
+    const e = /** @type {ToggleEvent} */ (event);
+    const open = e.newState === "open";
+    if (open) {
+      positionUnderTrigger(popover);
+    }
+    popover.dispatchEvent(
+      new CustomEvent("re-toggle", {
+        bubbles: true,
+        detail: { open },
+      }),
+    );
+  };
+
+  popover.addEventListener("toggle", onToggle);
+
+  return () => {
+    popover.removeEventListener("toggle", onToggle);
+  };
+}
+
+/**
+ * @param {HTMLElement} popover
+ */
+function positionUnderTrigger(popover) {
+  const id = popover.id;
+  if (!id) return;
+  /** @type {HTMLElement | null} */
+  const trigger = document.querySelector(`[popovertarget="${cssEscape(id)}"]`);
+  if (!trigger) return;
+  const tRect = trigger.getBoundingClientRect();
+  popover.style.position = "fixed";
+  popover.style.top = `${tRect.bottom + 4}px`;
+  popover.style.left = `${tRect.left}px`;
+  popover.style.right = "auto";
+  popover.style.bottom = "auto";
+  popover.style.margin = "0";
+}
+
+/** @param {string} value */
+function cssEscape(value) {
+  return typeof CSS !== "undefined" && CSS.escape ? CSS.escape(value) : value;
+}