@relements/core 0.1.0

package/src/components/tabs.css

@@ -0,0 +1,86 @@
+/**
+ * Relements tabs.
+ *
+ * Visual layer for the ARIA tab pattern. The DOM contract:
+ *
+ *   <div class="re-tabs" data-re-tabs>
+ *     <div class="re-tabs__list" role="tablist" aria-label="…">
+ *       <button class="re-tab" role="tab" id="t-1" aria-controls="p-1" aria-selected="true">Profile</button>
+ *       <button class="re-tab" role="tab" id="t-2" aria-controls="p-2" aria-selected="false" tabindex="-1">Security</button>
+ *     </div>
+ *     <section class="re-tabpanel" role="tabpanel" id="p-1" aria-labelledby="t-1">…</section>
+ *     <section class="re-tabpanel" role="tabpanel" id="p-2" aria-labelledby="t-2" hidden>…</section>
+ *   </div>
+ *
+ * Server-rendered initial state shows the selected tab; enhanceTabs adds
+ * keyboard navigation and runtime selection.
+ */
+
+@layer re.components {
+  .re-tabs {
+    display: flex;
+    flex-direction: column;
+    gap: var(--re-space-4);
+  }
+
+  .re-tabs__list {
+    display: flex;
+    gap: var(--re-space-1);
+    flex-wrap: wrap;
+    border-block-end: var(--re-border-default);
+    padding-block-end: 0;
+  }
+
+  .re-tab {
+    appearance: none;
+    background: transparent;
+    border: 0;
+    cursor: pointer;
+    font: inherit;
+    color: var(--re-color-text-muted);
+    padding: var(--re-space-2) var(--re-space-4);
+    border-radius: var(--re-radius-md) var(--re-radius-md) 0 0;
+    position: relative;
+    line-height: 1.4;
+    font-weight: var(--re-font-weight-medium);
+    transition:
+      color var(--re-duration-fast) var(--re-easing-standard),
+      background-color var(--re-duration-fast) var(--re-easing-standard);
+  }
+
+  .re-tab:hover {
+    color: var(--re-color-text);
+    background-color: var(--re-color-bg-subtle);
+  }
+
+  .re-tab:focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+  }
+
+  .re-tab[aria-selected="true"] {
+    color: var(--re-color-text);
+    background-color: var(--re-color-bg);
+  }
+
+  /* Active underline indicator */
+  .re-tab[aria-selected="true"]::after {
+    content: "";
+    position: absolute;
+    inset-inline: var(--re-space-2);
+    inset-block-end: calc(var(--re-border-width) * -1);
+    block-size: 2px;
+    background-color: var(--re-color-accent-600);
+    border-radius: var(--re-radius-sm);
+  }
+
+  .re-tabpanel {
+    color: var(--re-color-text);
+    line-height: var(--re-line-height-normal);
+  }
+  .re-tabpanel:focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+    border-radius: var(--re-radius-md);
+  }
+}

package/src/components/toast.css

@@ -0,0 +1,87 @@
+/**
+ * Relements toast.
+ *
+ *   <div class="re-toast-region" role="region" aria-label="Notifications" data-re-toast-region>
+ *     <div class="re-toast-list" aria-live="polite" aria-relevant="additions"></div>
+ *   </div>
+ *
+ * showToast(message, { tone, duration }) appends a <div class="re-toast"> item
+ * with the appropriate tone. Items are removed on timeout or dismiss.
+ */
+
+@layer re.components {
+  .re-toast-region {
+    position: fixed;
+    inset-block-end: var(--re-space-6);
+    inset-inline-end: var(--re-space-6);
+    z-index: var(--re-z-toast);
+    pointer-events: none;
+  }
+
+  .re-toast-list {
+    display: flex;
+    flex-direction: column-reverse;
+    gap: var(--re-space-2);
+    margin: 0;
+    padding: 0;
+    min-inline-size: 16rem;
+    max-inline-size: 24rem;
+  }
+
+  .re-toast {
+    pointer-events: auto;
+    display: flex;
+    gap: var(--re-space-3);
+    align-items: flex-start;
+    padding: var(--re-space-3) var(--re-space-4);
+    background-color: var(--re-color-surface);
+    color: var(--re-color-text);
+    border: var(--re-border-default);
+    border-radius: var(--re-radius-md);
+    box-shadow: var(--re-shadow-md);
+    line-height: var(--re-line-height-normal);
+  }
+
+  .re-toast__body {
+    flex: 1 1 auto;
+  }
+
+  .re-toast__dismiss {
+    appearance: none;
+    background: transparent;
+    border: 0;
+    cursor: pointer;
+    color: var(--re-color-text-muted);
+    font: inherit;
+    font-size: var(--re-size-text-lg);
+    line-height: 1;
+    padding: 0 var(--re-space-1);
+    border-radius: var(--re-radius-sm);
+  }
+  .re-toast__dismiss:hover {
+    color: var(--re-color-text);
+    background: var(--re-color-bg-subtle);
+  }
+  .re-toast__dismiss:focus-visible {
+    outline: none;
+    box-shadow: var(--re-shadow-focus);
+  }
+
+  /* Tone variants: tinted background + colored border + colored label.
+     color-mix() adapts to both light and dark surface colours. */
+  .re-toast[data-tone="success"] {
+    background-color: color-mix(in srgb, var(--re-color-success-600) 12%, var(--re-color-surface));
+    border-color: var(--re-color-success-600);
+    color: var(--re-color-text);
+  }
+  .re-toast[data-tone="danger"] {
+    background-color: color-mix(in srgb, var(--re-color-danger-600) 12%, var(--re-color-surface));
+    border-color: var(--re-color-danger-600);
+    color: var(--re-color-text);
+  }
+  .re-toast[data-tone="warning"] {
+    background-color: color-mix(in srgb, var(--re-color-warning-600) 12%, var(--re-color-surface));
+    border-color: var(--re-color-warning-600);
+    color: var(--re-color-text);
+  }
+}

package/src/elements/re-menu.js

@@ -0,0 +1,54 @@
+/**
+ * <re-menu>
+ * ---------
+ * Custom element wrapping the menu-button pattern over light-DOM markup.
+ *
+ *   <re-menu>
+ *     <button class="re-button" aria-haspopup="menu" aria-expanded="false" aria-controls="m" id="b">Actions</button>
+ *     <div class="re-menu__panel" role="menu" id="m" aria-labelledby="b" hidden>
+ *       <button class="re-menu__item" role="menuitem" data-value="a">A</button>
+ *     </div>
+ *   </re-menu>
+ *
+ * The element exposes:
+ *   - `.open` boolean reflecting/setting the open state.
+ *   - bubbles `re-select` from the underlying enhancer.
+ */
+
+import { enhanceMenuButton } from "../behaviors/menu-button.js";
+
+export class ReMenuElement extends HTMLElement {
+  /** @type {{ destroy: () => void } | null} */
+  #controller = null;
+
+  connectedCallback() {
+    this.classList.add("re-menu");
+    this.setAttribute("data-re-menu", "");
+    this.#controller = enhanceMenuButton(this);
+  }
+
+  disconnectedCallback() {
+    this.#controller?.destroy();
+    this.#controller = null;
+  }
+
+  /** @returns {boolean} */
+  get open() {
+    const btn = this.querySelector('[aria-haspopup="menu"], [aria-haspopup="true"]');
+    return btn?.getAttribute("aria-expanded") === "true";
+  }
+
+  set open(value) {
+    const btn = /** @type {HTMLElement | null} */ (
+      this.querySelector('[aria-haspopup="menu"], [aria-haspopup="true"]')
+    );
+    if (!btn) return;
+    const want = Boolean(value);
+    if (this.open === want) return;
+    btn.click();
+  }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("re-menu")) {
+  customElements.define("re-menu", ReMenuElement);
+}

package/src/elements/re-popover.js

@@ -0,0 +1,59 @@
+/**
+ * <re-popover>
+ * ------------
+ * Custom element wrapping the native popover attribute.
+ *
+ *   <button class="re-button" popovertarget="tip">Toggle</button>
+ *   <re-popover id="tip">
+ *     <p>Hello!</p>
+ *   </re-popover>
+ *
+ * The element receives the native `popover` attribute on connect and
+ * runs enhancePopover for anchored positioning + re-toggle event.
+ *
+ * Methods:
+ *   show()    — calls showPopover()
+ *   hide()    — calls hidePopover()
+ *   toggle()  — calls togglePopover()
+ *
+ * Property:
+ *   open      — boolean reflecting native :popover-open state
+ */
+
+import { enhancePopover } from "../behaviors/popover.js";
+
+export class RePopoverElement extends HTMLElement {
+  /** @type {{ destroy: () => void } | null} */
+  #controller = null;
+
+  connectedCallback() {
+    if (!this.hasAttribute("popover")) this.setAttribute("popover", "auto");
+    this.classList.add("re-popover");
+    this.setAttribute("data-re-popover", "");
+    this.#controller = enhancePopover(this);
+  }
+
+  disconnectedCallback() {
+    this.#controller?.destroy();
+    this.#controller = null;
+  }
+
+  /** @returns {boolean} */
+  get open() {
+    return this.matches?.(":popover-open") ?? false;
+  }
+
+  show() {
+    /** @type {any} */ (this).showPopover?.();
+  }
+  hide() {
+    /** @type {any} */ (this).hidePopover?.();
+  }
+  toggle() {
+    /** @type {any} */ (this).togglePopover?.();
+  }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("re-popover")) {
+  customElements.define("re-popover", RePopoverElement);
+}

package/src/elements/re-tabs.js

@@ -0,0 +1,92 @@
+/**
+ * <re-tabs>
+ * ---------
+ * Custom-element wrapper around enhanceTabs over light-DOM markup.
+ *
+ *   <re-tabs aria-label="Account">
+ *     <div role="tablist">
+ *       <button role="tab" id="t-1" aria-controls="p-1" aria-selected="true">Profile</button>
+ *       <button role="tab" id="t-2" aria-controls="p-2" aria-selected="false" tabindex="-1">Security</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>
+ *   </re-tabs>
+ *
+ * Exposes:
+ *   - Property `value`: id of the selected tab (e.g. "t-1"). Set to switch.
+ *   - Re-dispatches `re-change` from the underlying enhancer with bubbles.
+ *   - Works framework-neutrally: any HTML rendering produces the same contract.
+ *
+ *   import "@relements/core/elements/re-tabs";
+ */
+
+import { enhanceTabs } from "../behaviors/tabs.js";
+
+export class ReTabsElement extends HTMLElement {
+  /** @type {{ destroy: () => void } | null} */
+  #controller = null;
+
+  static get observedAttributes() {
+    return ["value"];
+  }
+
+  connectedCallback() {
+    // Mark the host so enhanceTabs picks it up.
+    this.setAttribute("data-re-tabs", "");
+    this.#controller = enhanceTabs(this);
+    // Honor a value attribute if present and different from initial state.
+    const initial = this.getAttribute("value");
+    if (initial) this.#selectById(initial);
+  }
+
+  disconnectedCallback() {
+    this.#controller?.destroy();
+    this.#controller = null;
+  }
+
+  /**
+   * @param {string} name
+   * @param {string | null} _oldValue
+   * @param {string | null} newValue
+   */
+  attributeChangedCallback(name, _oldValue, newValue) {
+    if (name === "value" && newValue) {
+      this.#selectById(newValue);
+    }
+  }
+
+  /**
+   * Currently selected tab id.
+   * @returns {string | null}
+   */
+  get value() {
+    const sel = this.querySelector('[role="tab"][aria-selected="true"]');
+    return sel ? sel.id : null;
+  }
+
+  set value(id) {
+    if (!id) return;
+    this.setAttribute("value", id);
+    this.#selectById(id);
+  }
+
+  /**
+   * @param {string} id
+   */
+  #selectById(id) {
+    /** @type {HTMLElement | null} */
+    const tab = this.querySelector(`[role="tab"]#${cssEscape(id)}`);
+    if (tab && tab.getAttribute("aria-selected") !== "true") {
+      tab.click();
+    }
+  }
+}
+
+/** @param {string} value */
+function cssEscape(value) {
+  return typeof CSS !== "undefined" && CSS.escape ? CSS.escape(value) : value;
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("re-tabs")) {
+  customElements.define("re-tabs", ReTabsElement);
+}

package/src/elements/re-toast.js

@@ -0,0 +1,46 @@
+/**
+ * <re-toast>
+ * ----------
+ * Custom element that hosts a toast region in light DOM and exposes a
+ * `.show(message, options)` method matching the showToast() API.
+ *
+ *   <re-toast id="toaster"></re-toast>
+ *   <script type="module">
+ *     import "@relements/core/elements/re-toast";
+ *     document.getElementById("toaster").show("Hi", { tone: "success" });
+ *   </script>
+ *
+ * On connection the element materializes a `.re-toast-region` / `.re-toast-list`
+ * inside itself if not already present. Toasts use the same CSS as the
+ * functional API.
+ */
+
+import { showToast } from "../behaviors/toast.js";
+
+export class ReToastElement extends HTMLElement {
+  connectedCallback() {
+    if (!this.querySelector("[data-re-toast-region]")) {
+      this.classList.add("re-toast-region");
+      this.setAttribute("role", "region");
+      if (!this.hasAttribute("aria-label")) this.setAttribute("aria-label", "Notifications");
+      this.setAttribute("data-re-toast-region", "");
+      const list = document.createElement("div");
+      list.className = "re-toast-list";
+      list.setAttribute("aria-live", this.getAttribute("data-live") ?? "polite");
+      list.setAttribute("aria-relevant", "additions");
+      this.appendChild(list);
+    }
+  }
+
+  /**
+   * @param {string} message
+   * @param {Parameters<typeof showToast>[1]} [options]
+   */
+  show(message, options) {
+    return showToast(message, { ...options, root: this });
+  }
+}
+
+if (typeof customElements !== "undefined" && !customElements.get("re-toast")) {
+  customElements.define("re-toast", ReToastElement);
+}

package/src/index.css

@@ -0,0 +1,30 @@
+/**
+ * Relements core entry stylesheet.
+ *
+ * Cascade layer order (lowest → highest specificity-wins):
+ *   1. re.tokens     — design tokens
+ *   2. re.reset      — minimal cross-browser normalization
+ *   3. re.base       — document-level typography & native element defaults
+ *   4. re.components — opt-in `.re-*` component styles
+ *
+ * Consumer overrides land in the unlayered cascade and win automatically.
+ * Subtree theming: redeclare tokens on any ancestor element.
+ */
+
+@layer re.tokens, re.reset, re.base, re.components;
+
+@import "./tokens.css" layer(re.tokens);
+@import "./reset.css" layer(re.reset);
+@import "./base.css" layer(re.base);
+
+/* Components */
+@import "./components/button.css";
+@import "./components/link.css";
+@import "./components/form.css";
+@import "./components/disclosure.css";
+@import "./components/dialog.css";
+@import "./components/progress.css";
+@import "./components/tabs.css";
+@import "./components/menu.css";
+@import "./components/popover.css";
+@import "./components/toast.css";

package/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * @relements/core entry point.
+ *
+ * Behaviors are tree-shakable named exports. CSS is imported separately
+ * via the package's exports map (e.g. `@relements/core/index.css`).
+ */
+
+export { enhanceDismissible } from "./behaviors/dismissible.js";
+export { enhanceDialog } from "./behaviors/dialog.js";
+export { enhanceTabs } from "./behaviors/tabs.js";
+export { enhanceMenuButton } from "./behaviors/menu-button.js";
+export { enhancePopover } from "./behaviors/popover.js";
+export { showToast } from "./behaviors/toast.js";

package/src/reset.css

@@ -0,0 +1,103 @@
+/**
+ * Relements reset.
+ *
+ * A minimal, opinionated normalization. Keeps native semantics intact;
+ * only removes obvious cross-browser inconsistencies and unifies box sizing.
+ * Native form controls retain native behavior — components opt in via classes.
+ */
+
+@layer re.reset {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  html {
+    -webkit-text-size-adjust: 100%;
+    text-size-adjust: 100%;
+    tab-size: 4;
+  }
+
+  body {
+    margin: 0;
+    min-height: 100vh;
+    min-height: 100dvh;
+    line-height: var(--re-line-height-normal);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+  }
+
+  /* Reset margins on common block elements; opt in via base.css. */
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6,
+  p,
+  figure,
+  blockquote,
+  dl,
+  dd {
+    margin: 0;
+  }
+
+  ul[role="list"],
+  ol[role="list"] {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+  }
+
+  img,
+  picture,
+  video,
+  canvas,
+  svg {
+    display: block;
+    max-width: 100%;
+    height: auto;
+  }
+
+  /* Inherit fonts in form controls — natural for typography tokens to apply. */
+  input,
+  button,
+  textarea,
+  select {
+    font: inherit;
+    color: inherit;
+  }
+
+  textarea {
+    resize: vertical;
+  }
+
+  /* Avoid orphaned text-flow problems. */
+  p,
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    overflow-wrap: break-word;
+  }
+
+  /* Honor the [hidden] attribute even when component CSS sets display. */
+  [hidden] {
+    display: none !important;
+  }
+
+  /* Respect users who request reduced motion. */
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}