@hypermedia-components/core 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ingcreators
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @hypermedia-components/core
+
+Semantic CSS components, DTCG-token-based themes, htmx-friendly recipes, small behavior helpers, and optional Light DOM macros.
+
+See the [project documentation](https://ingcreators.com/hypermedia-components/) for usage.
+
+## Layout
+
+```text
+src/
+  css/      Component, base, layer, and htmx CSS
+  js/       Behavior helpers (vanilla ESM)
+  macros/   Optional Light DOM custom-element macros
+  tokens/   DTCG token sources (primitive, semantic, component, theme, density)
+dist/       Build output (hc.css, hc.tokens.css, hc.behaviors.js, hc.macros.js, ...)
+```

package/dist/anchor-fallback.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Feature-detect CSS Anchor Positioning. Returns false where `CSS.supports`
+ * is missing (e.g. jsdom), which routes those environments through the
+ * fallback too.
+ *
+ * @returns {boolean}
+ */
+export function supportsAnchorPositioning(): boolean;
+/**
+ * Read a floating element's `data-side` / `data-align` attributes into the
+ * `{ side, align }` options {@link positionFloating} understands, falling
+ * back to the component's default when an attribute is absent or invalid.
+ * The CSS Anchor Positioning path keys off the same attributes
+ * (`position-area`), so both paths place the element identically.
+ *
+ * @param {Element} el
+ * @param {{ side?: string, align?: string }} [fallback]
+ * @returns {{ side: string, align: 'start'|'center'|'end' }}
+ */
+export function readSideAlign(el: Element, fallback?: {
+    side?: string;
+    align?: string;
+}): {
+    side: string;
+    align: "start" | "center" | "end";
+};
+/**
+ * Position `floating` next to `anchor`, once.
+ *
+ * @param {HTMLElement} floating  the popover to place (already in the top layer)
+ * @param {HTMLElement} anchor    the trigger to place it against
+ * @param {object} [opts]
+ * @param {'block-end'|'block-start'|'inline-end'|'inline-start'} [opts.side='block-end']
+ *   primary side. The block sides drop the floating element below / above the
+ *   anchor (dropdown); the inline sides place it to the right / left
+ *   (submenu), aligning their block-start edges.
+ * @param {'start'|'center'} [opts.align='start']  inline-axis alignment (block sides only)
+ * @param {number} [opts.gap=4]  distance from the anchor, px
+ * @param {boolean} [opts.matchWidth=false]  set min-width to the anchor width
+ */
+export function positionFloating(floating: HTMLElement, anchor: HTMLElement, opts?: {
+    side?: "block-end" | "block-start" | "inline-end" | "inline-start";
+    align?: "start" | "center";
+    gap?: number;
+    matchWidth?: boolean;
+}): void;
+/**
+ * Position `floating` against `anchor` now and keep it tracking while open.
+ * Re-runs on scroll (in any ancestor, via capture) and on resize.
+ *
+ * @param {HTMLElement} floating
+ * @param {HTMLElement} anchor
+ * @param {object} [opts]  see {@link positionFloating}
+ * @returns {() => void}  cleanup — removes the listeners and clears the inline
+ *   styles. Idempotent.
+ */
+export function trackFloating(floating: HTMLElement, anchor: HTMLElement, opts?: object): () => void;

package/dist/anchor-fallback.js

@@ -0,0 +1,198 @@
+// Shared fallback positioning for popovers when CSS Anchor Positioning is
+// unavailable (e.g. current Firefox). The components position their popovers
+// with CSS anchor positioning + `position-try-fallbacks`; in engines without
+// it, a `[popover]` would otherwise sit centred in the viewport. This module
+// mirrors that CSS behaviour in JS: place the floating element next to its
+// anchor, flip on overflow, clamp to the viewport, and keep it tracking on
+// scroll / resize until cleaned up.
+//
+// Geometry is set with PHYSICAL `top` / `left` (computed from
+// getBoundingClientRect, which is physical), so it is correct under both LTR
+// and RTL; inline-axis *alignment* is direction-aware.
+
+/**
+ * Feature-detect CSS Anchor Positioning. Returns false where `CSS.supports`
+ * is missing (e.g. jsdom), which routes those environments through the
+ * fallback too.
+ *
+ * @returns {boolean}
+ */
+export function supportsAnchorPositioning() {
+  try {
+    return (
+      typeof CSS !== 'undefined' &&
+      typeof CSS.supports === 'function' &&
+      CSS.supports('anchor-name', '--x')
+    );
+  } catch {
+    return false;
+  }
+}
+
+const clamp = (value, min, max) => Math.max(min, Math.min(value, max));
+
+// data-side (physical) → fallback `side` (logical block / inline axis).
+const SIDE_TO_AXIS = {
+  top: 'block-start',
+  bottom: 'block-end',
+  left: 'inline-start',
+  right: 'inline-end',
+};
+
+/**
+ * Read a floating element's `data-side` / `data-align` attributes into the
+ * `{ side, align }` options {@link positionFloating} understands, falling
+ * back to the component's default when an attribute is absent or invalid.
+ * The CSS Anchor Positioning path keys off the same attributes
+ * (`position-area`), so both paths place the element identically.
+ *
+ * @param {Element} el
+ * @param {{ side?: string, align?: string }} [fallback]
+ * @returns {{ side: string, align: 'start'|'center'|'end' }}
+ */
+export function readSideAlign(el, fallback = {}) {
+  const side = SIDE_TO_AXIS[el.getAttribute('data-side')] ?? fallback.side ?? 'block-end';
+  const alignAttr = el.getAttribute('data-align');
+  const align = ['start', 'center', 'end'].includes(alignAttr)
+    ? alignAttr
+    : fallback.align ?? 'start';
+  return { side, align };
+}
+
+/**
+ * Position `floating` next to `anchor`, once.
+ *
+ * @param {HTMLElement} floating  the popover to place (already in the top layer)
+ * @param {HTMLElement} anchor    the trigger to place it against
+ * @param {object} [opts]
+ * @param {'block-end'|'block-start'|'inline-end'|'inline-start'} [opts.side='block-end']
+ *   primary side. The block sides drop the floating element below / above the
+ *   anchor (dropdown); the inline sides place it to the right / left
+ *   (submenu), aligning their block-start edges.
+ * @param {'start'|'center'} [opts.align='start']  inline-axis alignment (block sides only)
+ * @param {number} [opts.gap=4]  distance from the anchor, px
+ * @param {boolean} [opts.matchWidth=false]  set min-width to the anchor width
+ */
+export function positionFloating(floating, anchor, opts = {}) {
+  const { side = 'block-end', align = 'start', gap = 4, matchWidth = false } = opts;
+  const a = anchor.getBoundingClientRect();
+  const f = floating.getBoundingClientRect();
+  const view = floating.ownerDocument.defaultView;
+  const vw = view?.innerWidth ?? 0;
+  const vh = view?.innerHeight ?? 0;
+  const rtl = view ? view.getComputedStyle(anchor).direction === 'rtl' : false;
+
+  // Inline sides (submenu): place beside the anchor, align block tops.
+  if (side === 'inline-end' || side === 'inline-start') {
+    // `inline-end` resolves to the physical right in LTR, left in RTL.
+    const toRight = (side === 'inline-end') !== rtl;
+    let left;
+    if (toRight) {
+      left = a.right + gap;
+      if (left + f.width > vw && a.left - f.width - gap >= 0) left = a.left - f.width - gap;
+    } else {
+      left = a.left - f.width - gap;
+      if (left < 0 && a.right + f.width + gap <= vw) left = a.right + gap;
+    }
+    // Cross axis (block): align start (tops) / center / end (bottoms),
+    // flipping the chosen edge when it would overflow.
+    let top;
+    if (align === 'center') {
+      top = a.top + (a.height - f.height) / 2;
+    } else if (align === 'end') {
+      top = a.bottom - f.height;
+      if (top < 0 && a.top + f.height <= vh) top = a.top;
+    } else {
+      top = a.top;
+      if (top + f.height > vh && a.bottom - f.height >= 0) top = a.bottom - f.height;
+    }
+    top = clamp(top, gap, Math.max(gap, vh - f.height - gap));
+    left = clamp(left, gap, Math.max(gap, vw - f.width - gap));
+
+    floating.style.position = 'fixed';
+    floating.style.top = `${top}px`;
+    floating.style.left = `${left}px`;
+    floating.style.insetInlineStart = 'auto';
+    floating.style.insetBlockStart = 'auto';
+    floating.style.margin = '0';
+    if (matchWidth) floating.style.minWidth = `${a.width}px`;
+    return;
+  }
+
+  // Block axis: primary side, flip when it would overflow and there is room.
+  let top;
+  if (side === 'block-start') {
+    top = a.top - f.height - gap;
+    if (top < 0 && a.bottom + f.height + gap <= vh) top = a.bottom + gap;
+  } else {
+    top = a.bottom + gap;
+    if (top + f.height > vh && a.top - f.height - gap >= 0) top = a.top - f.height - gap;
+  }
+
+  // Inline axis: align start / center / end, then flip on overflow.
+  let left;
+  if (align === 'center') {
+    left = a.left + (a.width - f.width) / 2;
+  } else {
+    // `start` aligns the inline-start edges, `end` the inline-end edges; RTL
+    // swaps which physical edge each maps to.
+    const startToLeft = (align !== 'end') !== rtl;
+    if (startToLeft) {
+      left = a.left;
+      if (left + f.width > vw && a.right - f.width >= 0) left = a.right - f.width;
+    } else {
+      left = a.right - f.width;
+      if (left < 0 && a.left + f.width <= vw) left = a.left;
+    }
+  }
+
+  // Final safety clamp so it can never sit fully off-screen.
+  top = clamp(top, gap, Math.max(gap, vh - f.height - gap));
+  left = clamp(left, gap, Math.max(gap, vw - f.width - gap));
+
+  floating.style.position = 'fixed';
+  floating.style.top = `${top}px`;
+  floating.style.left = `${left}px`;
+  floating.style.insetInlineStart = 'auto';
+  floating.style.insetBlockStart = 'auto';
+  floating.style.margin = '0';
+  if (matchWidth) floating.style.minWidth = `${a.width}px`;
+}
+
+const CLEARED = [
+  'position',
+  'top',
+  'left',
+  'inset-inline-start',
+  'inset-block-start',
+  'margin',
+  'min-width',
+];
+
+/**
+ * Position `floating` against `anchor` now and keep it tracking while open.
+ * Re-runs on scroll (in any ancestor, via capture) and on resize.
+ *
+ * @param {HTMLElement} floating
+ * @param {HTMLElement} anchor
+ * @param {object} [opts]  see {@link positionFloating}
+ * @returns {() => void}  cleanup — removes the listeners and clears the inline
+ *   styles. Idempotent.
+ */
+export function trackFloating(floating, anchor, opts = {}) {
+  const view = floating.ownerDocument.defaultView;
+  const reposition = () => positionFloating(floating, anchor, opts);
+  reposition();
+  // capture:true so scrolls in ancestor scroll containers are caught too.
+  view?.addEventListener('scroll', reposition, true);
+  view?.addEventListener('resize', reposition);
+
+  let done = false;
+  return () => {
+    if (done) return;
+    done = true;
+    view?.removeEventListener('scroll', reposition, true);
+    view?.removeEventListener('resize', reposition);
+    for (const prop of CLEARED) floating.style.removeProperty(prop);
+  };
+}

package/dist/avatar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Install the avatar behavior on every composite `.hc-avatar` (one holding a
+ * `.hc-avatar__image`) in the document: track the image's load / error state
+ * in `data-state` so the initials fallback shows when the image is missing.
+ * The CSS works without it; this adds the automatic swap.
+ *
+ * @param {Document|Element} [root]
+ * @returns {() => void}
+ */
+export function installAvatar(root?: Document | Element): () => void;

package/dist/avatar.js

@@ -0,0 +1,148 @@
+// installAvatar — image load/error → initials fallback for hc-avatar.
+//
+// Drives the `data-state` of a composite avatar off the native image
+// `load` / `error` events — no network of its own:
+//
+//   <span class="hc-avatar" role="img" aria-label="Ada Lovelace">
+//     <img class="hc-avatar__image" src="/ada.jpg" alt="">
+//     <span class="hc-avatar__fallback" aria-hidden="true">AL</span>
+//   </span>
+//
+// State machine (written to `data-state` on the wrapper):
+//
+//   loading  — image is fetching; the fallback shows so the slot is never
+//              empty (this is the default while waiting).
+//   pending  — image is fetching but `data-delay="<ms>"` is set, so the
+//              fallback stays hidden for that window to avoid a flash on a
+//              fast connection. Becomes `loading` when the delay elapses.
+//   loaded   — image decoded successfully; the fallback is hidden.
+//   error    — the image failed or has no `src`; the fallback shows and the
+//              broken image is removed from the box.
+//
+// Each change dispatches a bubbling `hc:avatarstatechange` (detail.state).
+//
+// Only composite avatars (a `.hc-avatar` with a `.hc-avatar__image` child)
+// are managed; plain `<img class="hc-avatar">` / `<span class="hc-avatar">`
+// avatars are left untouched. Progressive: with JS off the image still
+// covers the fallback when it loads (a broken image shows the fallback
+// behind it).
+//
+// installAvatar(root = document) returns an idempotent uninstaller.
+
+const INSTALL_KEY = '__hcAvatarUninstall';
+
+function imageOf(avatar) {
+  return avatar.querySelector(':scope > .hc-avatar__image');
+}
+
+function hasSrc(img) {
+  const src = img.getAttribute('src');
+  return src != null && src.trim() !== '';
+}
+
+// Synchronous verdict for an image that may already be settled (e.g. served
+// from cache before the behavior runs). null means "still loading".
+function settle(img) {
+  if (!hasSrc(img)) return 'error';
+  if (img.complete) return img.naturalWidth > 0 ? 'loaded' : 'error';
+  return null;
+}
+
+function setState(avatar, state) {
+  if (avatar.dataset.state === state) return;
+  avatar.dataset.state = state;
+  avatar.dispatchEvent(
+    new CustomEvent('hc:avatarstatechange', { bubbles: true, detail: { state } }),
+  );
+}
+
+function attach(avatar, detachers) {
+  if (detachers.has(avatar)) return;
+  const img = imageOf(avatar);
+  if (!img) return; // a plain avatar — nothing to manage
+
+  let timer = null;
+  const clearTimer = () => {
+    if (timer != null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+
+  function onLoad() {
+    clearTimer();
+    setState(avatar, 'loaded');
+  }
+  function onError() {
+    clearTimer();
+    setState(avatar, 'error');
+  }
+
+  const initial = settle(img);
+  if (initial === 'loaded' || initial === 'error') {
+    setState(avatar, initial);
+  } else {
+    const delay = Math.max(0, parseInt(avatar.getAttribute('data-delay'), 10) || 0);
+    if (delay > 0) {
+      setState(avatar, 'pending');
+      timer = setTimeout(() => {
+        timer = null;
+        if (avatar.dataset.state === 'pending') setState(avatar, 'loading');
+      }, delay);
+    } else {
+      setState(avatar, 'loading');
+    }
+    img.addEventListener('load', onLoad);
+    img.addEventListener('error', onError);
+  }
+
+  detachers.set(avatar, () => {
+    clearTimer();
+    img.removeEventListener('load', onLoad);
+    img.removeEventListener('error', onError);
+  });
+}
+
+/**
+ * Install the avatar behavior on every composite `.hc-avatar` (one holding a
+ * `.hc-avatar__image`) in the document: track the image's load / error state
+ * in `data-state` so the initials fallback shows when the image is missing.
+ * The CSS works without it; this adds the automatic swap.
+ *
+ * @param {Document|Element} [root]
+ * @returns {() => void}
+ */
+export function installAvatar(
+  root = typeof document !== 'undefined' ? document : null,
+) {
+  if (!root) return () => {};
+  if (root[INSTALL_KEY]) return root[INSTALL_KEY];
+
+  const detachers = new Map();
+
+  for (const el of root.querySelectorAll('.hc-avatar')) attach(el, detachers);
+
+  let observer = null;
+  if (typeof MutationObserver !== 'undefined') {
+    observer = new MutationObserver((records) => {
+      for (const rec of records) {
+        for (const node of rec.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          if (node.matches?.('.hc-avatar')) attach(node, detachers);
+          node.querySelectorAll?.('.hc-avatar').forEach((el) => attach(el, detachers));
+        }
+      }
+    });
+    observer.observe(root.body ?? root, { childList: true, subtree: true });
+  }
+
+  const uninstall = () => {
+    if (root[INSTALL_KEY] !== uninstall) return;
+    if (observer) observer.disconnect();
+    for (const detach of detachers.values()) detach();
+    detachers.clear();
+    delete root[INSTALL_KEY];
+  };
+  root[INSTALL_KEY] = uninstall;
+  return uninstall;
+}

package/dist/calendar.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Install the calendar behavior on every `.hc-calendar` container in the
+ * document. The returned uninstaller is idempotent and a no-op when the
+ * behavior is not installed.
+ *
+ * @param {Document|Element} [root]
+ * @returns {() => void}
+ */
+export function installCalendar(root?: Document | Element): () => void;