@efolusi/meridian 1.5.0

package/overlay/Portal.js

@@ -0,0 +1,127 @@
+import React from 'react';
+// Bare imports are stripped by the bundle compiler, so this resolves to the
+// window global there; in an ESM consumer it resolves normally. Both work.
+import ReactDOM from 'react-dom';
+import { injectEfCss } from "../forms/Button.js";
+const CSS = `
+.ef-portal{position:fixed;top:0;left:0;width:0;height:0}
+`;
+
+/**
+ * Renders children into document.body (or `container`).
+ *
+ * Every floating surface needs this. An overlay positioned inside its trigger's
+ * subtree is clipped by the first ancestor with overflow:auto|hidden — which in
+ * practice is the scrolling table, drawer, or card it was opened from.
+ */
+export function Portal({
+  children,
+  container
+}) {
+  injectEfCss('ef-css-portal', CSS);
+  const hostRef = React.useRef(null);
+  if (hostRef.current === null && typeof document !== 'undefined') {
+    hostRef.current = document.createElement('div');
+    hostRef.current.className = 'ef-portal';
+  }
+  // Children mount into the host on the first render, while it is still detached,
+  // and this layout effect attaches it before paint. Gating the render on a
+  // "mounted" state instead would leave the panel absent when the parent measures
+  // it for placement, which puts every anchored overlay at the viewport origin.
+  React.useLayoutEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+    const parent = container || document.body;
+    parent.appendChild(host);
+    return () => {
+      if (host.parentNode) host.parentNode.removeChild(host);
+    };
+  }, [container]);
+  if (!hostRef.current) return null;
+  return /*#__PURE__*/ReactDOM.createPortal(children, hostRef.current);
+}
+
+/**
+ * Position a portaled panel against its anchor, in viewport coordinates.
+ *
+ * Flips to the opposite side when the preferred one would overflow, then shifts
+ * along the cross axis to stay on screen. Returns { style, side } — the panel is
+ * hidden for the first frame so the measurement never flashes, and `side` is the
+ * placement actually resolved, which a caller drawing an arrow has to know.
+ *
+ * Not exported on the namespace — it is a building block for the overlay
+ * components, and is only useful with a panel ref you already control.
+ */
+export function useAnchoredStyle(anchorRef, panelRef, {
+  open,
+  placement = 'bottom',
+  align = 'start',
+  offset = 6,
+  matchWidth = false
+} = {}) {
+  const [state, setState] = React.useState({
+    style: {
+      position: 'fixed',
+      top: 0,
+      left: 0,
+      visibility: 'hidden'
+    },
+    side: placement
+  });
+  React.useLayoutEffect(() => {
+    if (!open) {
+      setState(s => s.style.visibility === 'hidden' ? s : {
+        ...s,
+        style: {
+          ...s.style,
+          visibility: 'hidden'
+        }
+      });
+      return;
+    }
+    const place = () => {
+      const anchor = anchorRef.current;
+      const panel = panelRef.current;
+      if (!anchor || !panel) return;
+      const a = anchor.getBoundingClientRect();
+      const p = panel.getBoundingClientRect();
+      const vw = document.documentElement.clientWidth;
+      const vh = document.documentElement.clientHeight;
+      const edge = 8;
+      const roomBelow = vh - a.bottom - offset;
+      const roomAbove = a.top - offset;
+      const wantsTop = placement === 'top';
+      const side = wantsTop ? roomAbove >= p.height || roomAbove >= roomBelow ? 'top' : 'bottom' : roomBelow >= p.height || roomBelow >= roomAbove ? 'bottom' : 'top';
+
+      // a width-matched panel (a listbox under its input) is measured at the
+      // anchor's width, not its own, or the clamp below uses the wrong number
+      const width = matchWidth ? a.width : p.width;
+      let top = side === 'bottom' ? a.bottom + offset : a.top - offset - p.height;
+      let left = align === 'end' ? a.right - width : align === 'center' ? a.left + a.width / 2 - width / 2 : a.left;
+      left = Math.max(edge, Math.min(left, vw - width - edge));
+      top = Math.max(edge, Math.min(top, vh - p.height - edge));
+      const next = {
+        position: 'fixed',
+        top: Math.round(top),
+        left: Math.round(left),
+        right: 'auto',
+        bottom: 'auto',
+        visibility: 'visible'
+      };
+      if (matchWidth) next.width = Math.round(a.width);
+      setState({
+        style: next,
+        side
+      });
+    };
+    place();
+    // capture phase: any scrolling ancestor moves the anchor, not just the window
+    window.addEventListener('scroll', place, true);
+    window.addEventListener('resize', place);
+    return () => {
+      window.removeEventListener('scroll', place, true);
+      window.removeEventListener('resize', place);
+    };
+  }, [open, placement, align, offset, matchWidth, anchorRef, panelRef]);
+  return state;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@efolusi/meridian",
+  "version": "1.5.0",
+  "description": "A general-purpose open-source design system by Efolusi: accessible React components, design tokens, blocks and example apps.",
+  "license": "MIT",
+  "homepage": "https://meridian.efolusi.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/efolusi/meridian.git"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./styles.css": "./styles.css",
+    "./tokens/*": "./tokens/*",
+    "./*": {
+      "types": "./*.d.ts",
+      "default": "./*.js"
+    }
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "keywords": [
+    "design-system",
+    "react",
+    "components",
+    "accessible",
+    "design-tokens",
+    "meridian"
+  ]
+}

package/styles.css

@@ -0,0 +1,6 @@
+@import "tokens/fonts.css";
+@import "tokens/colors.css";
+@import "tokens/typography.css";
+@import "tokens/spacing.css";
+@import "tokens/effects.css";
+@import "tokens/base.css";

package/tokens/base.css

@@ -0,0 +1,10 @@
+body{margin:0;font-family:var(--font-sans);font-size:var(--text-md);line-height:var(--leading-normal);color:var(--text-primary);background:var(--surface-page);-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility}
+h1,h2,h3,h4{font-family:var(--font-display);letter-spacing:var(--tracking-display);line-height:var(--leading-snug);margin:0}
+p{margin:0}
+a{color:var(--text-link);text-decoration:none;transition:color var(--dur-fast) var(--ease-out)}
+a:hover{color:var(--accent-hover);text-decoration:underline;text-underline-offset:3px}
+a:focus-visible{outline:none;box-shadow:var(--focus-ring);border-radius:var(--radius-sm)}
+code,pre,kbd{font-family:var(--font-mono)}
+::selection{background:var(--brand-100)}
+*,*::before,*::after{box-sizing:border-box}
+@media (prefers-reduced-motion:reduce){*,*::before,*::after{animation-duration:.01ms!important;animation-iteration-count:1!important;transition-duration:.01ms!important;scroll-behavior:auto!important}}

package/tokens/colors.css

@@ -0,0 +1,38 @@
+:root{
+/* Sand — warm neutrals */
+--sand-25:#FCFBF9;--sand-50:#FAF9F6;--sand-100:#F3F1EB;--sand-200:#E7E3D9;--sand-300:#D5CFC0;--sand-400:#B4AB97;--sand-500:#948A74;--sand-600:#786E59;--sand-700:#5E5545;--sand-800:#443D32;--sand-900:#2E2922;--sand-950:#1E1A14;
+/* Brand — cream→peach→caramel→cocoa ramp sampled from the owl mark */
+--brand-50:#F8F4E6;--brand-100:#F4E9D2;--brand-200:#EFCFAC;--brand-300:#DFB585;--brand-400:#CE9C66;--brand-500:#C08A5A;--brand-600:#A0693C;--brand-700:#7A4E2B;--brand-800:#5C3A1F;--brand-900:#482818;--brand-950:#2C1709;
+/* Named logo tones (aliases into the ramp) */
+--cocoa-950:var(--brand-950);--cocoa-900:#3A2012;--cocoa-700:var(--brand-900);--caramel-500:var(--brand-500);--peach-200:var(--brand-200);--cream-50:var(--brand-50);
+/* Status — each 600 fg holds ≥4.5:1 on its 100 tint and on white */
+--success-600:#2F7A40;--success-100:#EBF5EC;--success-300:#BFE0C6;
+--warning-600:#B45309;--warning-100:#FDF3E0;--warning-300:#F3D9A8;
+--danger-600:#C81E1E;--danger-700:#B91C1C;--danger-100:#FDEEEC;--danger-300:#F5C6C0;
+/* Semantic aliases */
+--surface-page:var(--sand-50);--surface-card:#FFFFFF;--surface-sunken:var(--sand-100);--surface-subtle:var(--sand-25);--surface-inverse:var(--sand-950);--surface-brand:var(--brand-900);
+--surface-code:#14110B;--text-code:#E8E3D9;--border-code:rgba(240,235,225,.09);/* code/terminal surface — fixed dark espresso in BOTH themes (never remap) */
+--overlay-scrim:rgba(31,26,20,.45);/* modal/drawer backdrop */--text-on-brand-muted:rgba(248,244,230,.75);/* muted text on brand/inverse surfaces */
+--text-primary:var(--sand-950);--text-secondary:var(--sand-700);--text-muted:#746A55;/* between sand-600/700: ≥4.5:1 on page, card, and sunken */--text-inverse:var(--sand-50);--text-link:var(--brand-700);
+--border-default:var(--sand-200);--border-strong:var(--sand-300);--border-inverse:rgba(250,249,246,.18);
+--accent:var(--brand-950);--accent-hover:#1D0E04;--accent-active:#120801;--accent-subtle:var(--brand-50);--accent-subtle-border:var(--brand-200);--accent-contrast:#FFFFFF;
+--danger-contrast:#FFFFFF;/* label on a solid --danger-600 fill; flips in dark where the red lightens */
+/* Focus ring — opaque, two-layer. The inner offset ring is surface-coloured so the
+   indicator never sits directly against a control fill; the outer ring only ever needs
+   contrast against the surface, clearing WCAG 1.4.11 (3:1 non-text) on every background. */
+--focus-ring-color:var(--brand-700);--focus-ring-offset:var(--surface-card);
+--focus-ring:0 0 0 2px var(--focus-ring-offset),0 0 0 4px var(--focus-ring-color);
+--focus-ring-danger:0 0 0 2px var(--focus-ring-offset),0 0 0 4px var(--danger-600);
+}
+/* Dark theme — semantic remap only; ramps stay fixed */
+[data-theme="dark"]{
+--surface-page:#191512;--surface-card:#211C17;--surface-sunken:#2A251E;--surface-subtle:#1D1814;--surface-inverse:var(--sand-50);--surface-brand:var(--brand-950);
+--text-primary:#F3EFE7;--text-secondary:#C9C0B2;--text-muted:#9C9280;--text-inverse:var(--sand-950);--text-link:var(--brand-400);
+--border-default:#332C24;--border-strong:#453C31;--border-inverse:rgba(30,26,20,.2);
+--accent:#F3EFE7;--accent-hover:#FFFFFF;--accent-active:#D5CFC0;--accent-subtle:#2A2119;--accent-subtle-border:#453728;--accent-contrast:#1E1A14;
+--success-600:#5FB86E;--success-100:#1C2B1F;--success-300:#2E4A34;
+--warning-100:#2E2413;--warning-300:#4A3A1D;--warning-600:#D9822B;
+--danger-100:#321B18;--danger-300:#54291F;--danger-600:#E85D4A;--danger-contrast:#1E1A14;
+--focus-ring-color:var(--brand-400);/* offset + composite inherit from :root and re-resolve here */
+}
+[data-theme="dark"] ::selection{background:#453728}

package/tokens/effects.css

@@ -0,0 +1,22 @@
+:root{
+--shadow-xs:0 1px 2px rgba(46,41,34,.05);
+--shadow-sm:0 1px 3px rgba(46,41,34,.07);
+--shadow-md:0 4px 12px rgba(46,41,34,.08);
+--shadow-lg:0 12px 28px rgba(46,41,34,.12);
+--shadow-xl:0 16px 40px rgba(31,26,20,.18),0 2px 8px rgba(31,26,20,.08);
+--shadow-pop:var(--shadow-xl);/* deprecated alias of --shadow-xl; kept one major */
+/* Elevation scale — the single source of overlay stacking order */
+--z-dropdown:1000;/* @kind other */
+--z-sticky:1100;/* @kind other */
+--z-overlay:1200;/* @kind other */
+--z-modal:1300;/* @kind other */
+--z-popover:1400;/* @kind other */
+--z-toast:1500;/* @kind other */
+--z-tooltip:1600;/* @kind other */
+--ease-spring:cubic-bezier(.3,1.04,.35,1);/* @kind other */
+--ease-out:cubic-bezier(.22,1,.36,1);/* @kind other */
+--ease-in-out:cubic-bezier(.65,0,.35,1);/* @kind other */
+--dur-fast:100ms;/* @kind other */
+--dur-med:160ms;/* @kind other */
+--dur-slow:240ms;/* @kind other */
+}

package/tokens/fonts.css

@@ -0,0 +1,5 @@
+@font-face{font-family:'Bricolage Grotesque';src:url('../assets/fonts/BricolageGrotesque-Variable.ttf') format('truetype-variations');font-weight:200 800;font-style:normal;font-display:swap}
+@font-face{font-family:'Figtree';src:url('../assets/fonts/Figtree-Variable.ttf') format('truetype-variations');font-weight:300 900;font-style:normal;font-display:swap}
+@font-face{font-family:'Figtree';src:url('../assets/fonts/Figtree-Italic-Variable.ttf') format('truetype-variations');font-weight:300 900;font-style:italic;font-display:swap}
+@font-face{font-family:'JetBrains Mono';src:url('../assets/fonts/JetBrainsMono-Variable.ttf') format('truetype-variations');font-weight:100 800;font-style:normal;font-display:swap}
+@font-face{font-family:'JetBrains Mono';src:url('../assets/fonts/JetBrainsMono-Italic-Variable.ttf') format('truetype-variations');font-weight:100 800;font-style:italic;font-display:swap}

package/tokens/spacing.css

@@ -0,0 +1,12 @@
+:root{
+--space-0:0;--space-1:4px;--space-2:8px;--space-3:12px;--space-4:16px;--space-5:20px;--space-6:24px;--space-8:32px;--space-10:40px;--space-12:48px;--space-16:64px;--space-20:80px;--space-24:96px;--space-32:128px;
+--radius-sm:4px;--radius-md:8px;--radius-lg:12px;--radius-xl:16px;--radius-full:999px;
+--container-max:1200px;--container-text:720px;
+--control-h-sm:28px;--control-h-md:36px;--control-h-lg:44px;
+--table-pad-y:12px;--table-pad-x:16px;
+}
+/* Compact density — data-heavy B2B views */
+[data-density="compact"]{
+--control-h-sm:24px;--control-h-md:30px;--control-h-lg:38px;
+--table-pad-y:7px;--table-pad-x:12px;
+}

package/tokens/typography.css

@@ -0,0 +1,9 @@
+:root{
+--font-display:'Bricolage Grotesque','Figtree',ui-sans-serif,system-ui,sans-serif;
+--font-sans:'Figtree',ui-sans-serif,system-ui,-apple-system,'Segoe UI',sans-serif;
+--font-mono:'JetBrains Mono',ui-monospace,'SF Mono',Menlo,monospace;
+--text-2xs:11px;--text-xs:12px;--text-sm:13px;--text-md:14px;--text-lg:16px;--text-xl:18px;--text-2xl:21px;--text-3xl:26px;--text-4xl:34px;--text-5xl:44px;--text-6xl:60px;--text-7xl:76px;
+--leading-tight:1.05;--leading-snug:1.25;--leading-normal:1.5;--leading-relaxed:1.65;
+--tracking-display:-0.02em;--tracking-tight:-0.01em;--tracking-wide:0.06em;
+--weight-regular:400;--weight-medium:500;--weight-semibold:600;--weight-bold:700;--weight-display:680;
+}