npm - @apliteni/apliteni-ui - Versions diffs - 0.23.3 → 0.24.0 - Mend

@apliteni/apliteni-ui 0.23.3 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +6 -0
package/package.json +1 -1
package/src/components/dropdown.js +129 -7
package/src/styles/base.css +1 -1
package/src/styles/dropdown.css +30 -1
package/src/tokens/accents.css +18 -3
package/src/tokens/tokens.css +0 -2

package/README.md CHANGED Viewed

@@ -132,6 +132,12 @@ Each accent re-points only the accent family (`--accent`, `--purple*`, `--glow-p
 stay put — so **every accent works in both themes** and every component follows with no
 component-level change.
+Both attributes are overrides, not requirements: with neither present the kit paints dark
+Nebula, and `data-accent` alone paints that accent on the dark theme. An absent `data-theme`
+is *not* "follow the system" — the kit ships no `prefers-color-scheme` rule, so a host that
+wants the OS preference resolves it in JS and stamps the attribute. See
+[`docs/library.md`](./docs/library.md#an-absent-attribute-means-dark).
 Shipped accents: **Nebula** (purple, default), **Phoenix** (ember), **Ocean** (azure),
 **Emerald** (jade). Runtime helpers: `applyTheme('light')` / `applyAccent('phoenix')`
 (both persist to `localStorage`); or the `accentPicker()` component wired by `wireTopbar()`.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@apliteni/apliteni-ui",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "workspaces": [
     "react"
   ],

package/src/components/dropdown.js CHANGED Viewed

@@ -76,6 +76,8 @@ function ddBody({ items, sections }, listbox) {
  * @param {string} [o.header]      raw HTML pinned to the top of the panel
  * @param {string} [o.footer]      raw HTML pinned to the bottom of the panel
  * @param {string} [o.align]       'start' (default) | 'end' — the edge the panel hugs
+ * @param {string} [o.direction]   'down' (default) | 'up' | 'auto' — the way it opens
+ * @param {boolean} [o.portal]     mount the panel on <body>, for a clipping or sticky ancestor
  * @param {boolean|number} [o.scroll] true, or a maxHeight in px, to cap and scroll
  * @param {boolean} [o.open]       render already-open (handy for screenshots)
  * @param {string} [o.ariaLabel]   accessible name for the panel and trigger
@@ -84,7 +86,8 @@ function ddBody({ items, sections }, listbox) {
 export function dropdown({
   label, value, placeholder = 'Select…', variant, items, sections,
   header = '', footer = '', triggerContent, triggerClass = '', chevron = true,
-  align = 'start', scroll = false, open = false, ariaLabel, id, panelClass = '',
+  align = 'start', direction = 'down', portal = false,
+  scroll = false, open = false, ariaLabel, id, panelClass = '',
 } = {}) {
   const flat = sections ? sections.flatMap((s) => s.items || []) : (items || []);
   const isSelect = variant === 'select' || (variant == null && flat.some((it) => it && (it.selected || it.value != null)));
@@ -104,15 +107,30 @@ export function dropdown({
     ariaLabel && triggerContent != null ? `aria-label="${esc(ariaLabel)}"` : '',
   ].filter(Boolean).join(' ');
+  // `is-open` beside `open` because the descendant selector the panel normally
+  // takes its open state from stops matching once wireDropdown() portals it.
   const panelAttrs = [
-    `class="${cx('ui-dropdown__panel', align === 'end' && 'is-end', scroll && 'is-scroll', panelClass)}"`,
+    `class="${cx(
+      'ui-dropdown__panel',
+      align === 'end' && 'is-end',
+      direction === 'up' && 'is-up',
+      scroll && 'is-scroll',
+      portal && 'ui-dropdown__panel--portal',
+      portal && open && 'is-open',
+      panelClass,
+    )}"`,
     'data-dropdown-panel',
     `role="${listRole}"`,
     ariaLabel ? `aria-label="${esc(ariaLabel)}"` : '',
     scroll && scroll !== true ? `style="max-height:${typeof scroll === 'number' ? scroll + 'px' : esc(scroll)}"` : '',
   ].filter(Boolean).join(' ');
-  return `<div class="${cx('ui-dropdown', open && 'open')}" data-dropdown${isSelect ? ' data-dropdown-select' : ''}${id ? ` id="${esc(id)}"` : ''}>` +
+  const ddAttrs = 'data-dropdown'
+    + (isSelect ? ' data-dropdown-select' : '')
+    + (direction === 'auto' ? ' data-dropdown-direction="auto"' : '')
+    + (portal ? ' data-dropdown-portal' : '');
+  return `<div class="${cx('ui-dropdown', open && 'open')}" ${ddAttrs}${id ? ` id="${esc(id)}"` : ''}>` +
     `<button ${triggerAttrs}>${trig}${chevron ? '<span class="ui-dropdown__chevron" aria-hidden="true"></span>' : ''}</button>` +
     `<div ${panelAttrs}>${header}${ddBody({ items, sections }, isSelect)}${footer}</div>` +
     `</div>`;
@@ -129,16 +147,74 @@ export function dropdown({
 // document. Safe to call repeatedly (e.g. Storybook re-renders).
 let _ddGlobalWired = false;
+// The trigger-to-panel offset is --ui-dropdown-gap in src/styles/dropdown.css.
+// This is the fallback for a document that has not loaded the sheet;
+// src/components/dropdown.test.js pins the two to each other.
+const DD_GAP = 9;
+// A portalled panel is no longer a descendant of its container, so everything
+// below asks the container for its panel rather than querying inside it.
+const ddPanelOf = (dd) => dd.__ddPanel || dd.querySelector('[data-dropdown-panel]');
+function ddGap(panel) {
+  const declared = parseFloat(getComputedStyle(panel).getPropertyValue('--ui-dropdown-gap'));
+  return Number.isFinite(declared) ? declared : DD_GAP;
+}
 function ddItemsOf(dd) {
-  const panel = dd.querySelector('[data-dropdown-panel]');
+  const panel = ddPanelOf(dd);
   if (!panel) return [];
   return Array.from(panel.querySelectorAll('[data-dd-item]'))
     .filter((el) => el.getAttribute('aria-disabled') !== 'true');
 }
+// `auto` is the only direction the wiring decides; `up` and the default are the
+// panel's own class, set once at render. Flip only when below is too tight AND
+// above is roomier, so a panel that fits nowhere still opens the way it says.
+function ddResolveDirection(dd, panel) {
+  if (dd.getAttribute('data-dropdown-direction') !== 'auto') return;
+  const trigger = dd.querySelector('[data-dropdown-trigger]');
+  if (!trigger || typeof trigger.getBoundingClientRect !== 'function') return;
+  const t = trigger.getBoundingClientRect();
+  const below = window.innerHeight - t.bottom;
+  panel.classList.toggle('is-up', below < panel.offsetHeight + ddGap(panel) && t.top > below);
+}
+// Nothing lays a portalled panel out any more, so these four inline values are
+// its layout. Inline, so no rule in any sheet can pin the opposite edge.
+function positionPortalPanel(dd, panel) {
+  const trigger = dd.querySelector('[data-dropdown-trigger]');
+  if (!trigger || typeof trigger.getBoundingClientRect !== 'function') return;
+  const t = trigger.getBoundingClientRect();
+  const gap = ddGap(panel);
+  const s = panel.style;
+  if (panel.classList.contains('is-up')) {
+    s.top = 'auto';
+    s.bottom = `${window.innerHeight - t.top + gap}px`;
+  } else {
+    s.bottom = 'auto';
+    s.top = `${t.bottom + gap}px`;
+  }
+  if (panel.classList.contains('is-end')) {
+    s.left = 'auto';
+    s.right = `${window.innerWidth - t.right}px`;
+  } else {
+    s.right = 'auto';
+    s.left = `${t.left}px`;
+  }
+}
+// A panel left on <body> outlives the container that owned it — a re-render
+// replaces the container and the old panel has nothing pointing at it.
+function sweepOrphanPanels() {
+  document.querySelectorAll('body > [data-dropdown-panel][data-dropdown-portal]')
+    .forEach((p) => { if (!p.__ddOwner || !p.__ddOwner.isConnected) p.remove(); });
+}
 function closeDropdown(dd) {
   if (!dd.classList.contains('open')) return;
   dd.classList.remove('open');
+  ddPanelOf(dd)?.classList.remove('is-open');
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'false');
 }
@@ -148,6 +224,11 @@ function closeAllDropdowns(except) {
 function openDropdown(dd, focusIdx) {
   closeAllDropdowns(dd);
+  const panel = ddPanelOf(dd);
+  if (panel) {
+    ddResolveDirection(dd, panel);
+    if (dd.__ddPanel) { positionPortalPanel(dd, panel); panel.classList.add('is-open'); }
+  }
   dd.classList.add('open');
   dd.querySelector('[data-dropdown-trigger]')?.setAttribute('aria-expanded', 'true');
   if (focusIdx != null) {
@@ -161,7 +242,7 @@ function openDropdown(dd, focusIdx) {
 function selectOption(dd, item) {
   if (!dd.hasAttribute('data-dropdown-select')) return;
   ddItemsOf(dd).forEach((el) => el.setAttribute('aria-selected', el === item ? 'true' : 'false'));
-  dd.querySelectorAll('[data-dd-item].is-selected').forEach((el) => el.classList.remove('is-selected'));
+  ddPanelOf(dd)?.querySelectorAll('[data-dd-item].is-selected').forEach((el) => el.classList.remove('is-selected'));
   item.classList.add('is-selected');
   const valueEl = dd.querySelector('[data-dropdown-trigger] .ui-dropdown__value');
   const label = item.querySelector('.ui-dropdown__label');
@@ -177,6 +258,23 @@ export function wireDropdown(root = document) {
     const panel = dd.querySelector('[data-dropdown-panel]');
     if (!trigger) return;
+    // Portal: lift the panel onto <body>. An ancestor whose overflow is not
+    // `visible` clips it on both axes, and one that is `position: sticky` opens
+    // a stacking context whatever z-index the panel carries — the app rail is
+    // both at once. why: docs/specification.md#the-dropdown-panel
+    if (panel && dd.hasAttribute('data-dropdown-portal')) {
+      sweepOrphanPanels();
+      panel.setAttribute('data-dropdown-portal', '');
+      panel.__ddOwner = dd;
+      dd.__ddPanel = panel;
+      document.body.appendChild(panel);
+      if (dd.classList.contains('open')) {
+        ddResolveDirection(dd, panel);
+        positionPortalPanel(dd, panel);
+        panel.classList.add('is-open');
+      }
+    }
     trigger.addEventListener('click', (e) => {
       e.stopPropagation();
       if (dd.classList.contains('open')) closeDropdown(dd);
@@ -196,7 +294,7 @@ export function wireDropdown(root = document) {
       });
     }
-    dd.addEventListener('keydown', (e) => {
+    const onKeydown = (e) => {
       const open = dd.classList.contains('open');
       const onTrigger = e.target === trigger;
       if ((e.key === 'ArrowDown' || e.key === 'ArrowUp') && (onTrigger || open)) {
@@ -217,7 +315,22 @@ export function wireDropdown(root = document) {
       } else if (e.key === 'Tab' && open) {
         closeDropdown(dd);
       }
-    });
+    };
+    dd.addEventListener('keydown', onKeydown);
+    if (dd.__ddPanel) {
+      // A portalled panel is no longer inside the container, so a keystroke on
+      // an item never bubbles to it. Bound here only, or it would fire twice.
+      dd.__ddPanel.addEventListener('keydown', onKeydown);
+      // It is also placed once, on open, and a trigger whose box changes after
+      // that — a webfont arriving, a longer label — leaves it adrift. Scroll
+      // and resize do not see a reflow; this does.
+      if (typeof ResizeObserver === 'function') {
+        new ResizeObserver(() => {
+          if (dd.classList.contains('open')) positionPortalPanel(dd, dd.__ddPanel);
+        }).observe(trigger);
+      }
+    }
   });
   if (!_ddGlobalWired) {
@@ -228,5 +341,14 @@ export function wireDropdown(root = document) {
       const open = document.querySelector('[data-dropdown].open');
       if (open) { closeDropdown(open); open.querySelector('[data-dropdown-trigger]')?.focus(); }
     });
+    // Viewport coordinates go stale the moment anything scrolls. Capture, so a
+    // scroll inside the rail the panel was lifted out of counts too.
+    const reposition = () => {
+      document.querySelectorAll('[data-dropdown].open').forEach((dd) => {
+        if (dd.__ddPanel) positionPortalPanel(dd, dd.__ddPanel);
+      });
+    };
+    window.addEventListener('scroll', reposition, true);
+    window.addEventListener('resize', reposition);
   }
 }

package/src/styles/base.css CHANGED Viewed

@@ -16,7 +16,7 @@ html {
 body {
   background: var(--bg);
-  color: var(--ink);
+  color: var(--text);
   font-family: var(--font-sans);
   font-weight: var(--weight-normal);
   font-size: var(--text-base);

package/src/styles/dropdown.css CHANGED Viewed

@@ -41,8 +41,12 @@
 /* Panel — the popover surface */
 .ui-dropdown__panel {
+  /* One number for the trigger-to-panel offset, read by both edges here and by
+     the portal's JS, so an upward panel cannot drift from a downward one.
+     why: docs/specification.md#the-dropdown-panel */
+  --ui-dropdown-gap: 9px;
   position: absolute;
-  top: calc(100% + 9px);
+  top: calc(100% + var(--ui-dropdown-gap));
   left: 0;
   min-width: 240px;
   background: var(--surface-2);
@@ -63,8 +67,33 @@
 }
 .ui-dropdown__panel.is-end { left: auto; right: 0; }
 .ui-dropdown__panel.is-scroll { max-height: 300px; overflow-y: auto; }
+/* Opening upward. The kit releases its own `top` here so that nothing outside
+   the kit has to: an absolute box with both edges pinned is stretched between
+   them, and a consumer who set `bottom` and left our `top` standing got a
+   fourteen-pixel panel. The entry travel is mirrored too, so the panel arrives
+   from the trigger whichever way it opens.
+   why: docs/specification.md#the-dropdown-panel */
+.ui-dropdown__panel.is-up {
+  top: auto;
+  bottom: calc(100% + var(--ui-dropdown-gap));
+  transform: translateY(6px);
+}
 .ui-dropdown.open .ui-dropdown__panel { opacity: 1; visibility: visible; transform: translateY(0); }
+/* Portalled panel — wireDropdown() moves it onto <body>, clear of every
+   ancestor's overflow and every ancestor's stacking context. The descendant
+   selector above stops matching the moment it leaves the trigger's subtree, so
+   its open state is a class of its own; the wiring writes the viewport
+   coordinates inline, and these `auto`s are what it writes over.
+   why: docs/specification.md#the-dropdown-panel */
+.ui-dropdown__panel--portal {
+  position: fixed;
+  top: auto; right: auto; bottom: auto; left: auto;
+}
+.ui-dropdown__panel--portal.is-open { opacity: 1; visibility: visible; transform: translateY(0); }
 /* Item row — [icon] [main: label + desc] [badge] [tick] */
 .ui-dropdown__item {
   display: flex;

package/src/tokens/accents.css CHANGED Viewed

@@ -1,7 +1,8 @@
 /* Accent sub-themes — an orthogonal `data-accent` dimension on top of
- * `data-theme`. Set both on <html>:
+ * `data-theme`. On <html>, with or without a theme:
  *
  *     <html data-theme="dark" data-accent="phoenix">
+ *     <html data-accent="phoenix">              <!-- default theme, same accent -->
  *
  * Each sub-theme only re-points the accent family. Surfaces, text and signal
  * colours (green = live, pink = danger) stay put, so every accent works in
@@ -10,12 +11,24 @@
  * --ring is NOT here: it is declared once in tokens.css as var(--accent), so
  * re-pointing --accent re-points the focus ring too.
  *
- * Selectors carry two attributes + :root, so they always out-specify the
- * single-attribute theme blocks in tokens.css regardless of import order.
+ * Every dark cell is a two-line selector list — a bare `:root[data-accent]`
+ * above the stamped form — which is the shape tokens.css gives the dark theme
+ * one file earlier, and for the same reason: the default theme needs no
+ * attribute, so neither may the accent. Written stamped-only, `data-accent`
+ * paints nothing at all in the state hosts use to mean "follow the system",
+ * where data-theme is simply absent. See issue #250.
+ *
+ * That bare line ties on specificity with :root[data-theme="light"] and wins on
+ * import order, so LIGHT is what the cascade has to be careful about: each light
+ * cell carries three attributes to out-specify it, and declares the same
+ * properties as its dark twin so none of the dark ramp leaks past it. Adding a
+ * property to one half of a pair and not the other is what breaks that, and
+ * stories/accent-without-theme.test.js is the gate that says so.
  *
  * why: docs/specification.md#the-focus-ring */
 /* ---- Phoenix — ember / rising fire (the strategy's namesake) ------------- */
+:root[data-accent="phoenix"],
 :root[data-theme="dark"][data-accent="phoenix"] {
   --purple: #e0531f;
   --purple-light: #ff8a5c;
@@ -45,6 +58,7 @@
 }
 /* ---- Ocean — azure ------------------------------------------------------- */
+:root[data-accent="ocean"],
 :root[data-theme="dark"][data-accent="ocean"] {
   --purple: #1f7fe0;
   --purple-light: #5ab0ff;
@@ -77,6 +91,7 @@
 }
 /* ---- Emerald — jade ------------------------------------------------------ */
+:root[data-accent="emerald"],
 :root[data-theme="dark"][data-accent="emerald"] {
   --purple: #0fa876;
   --purple-light: #3ad9a0;

package/src/tokens/tokens.css CHANGED Viewed

@@ -157,7 +157,6 @@
   --accent: #b479ff;
   --accent-strong: #7c3aed; /* button bg — white text clears WCAG AA at 5.70:1 */
   --accent-contrast: #ffffff;
-  --ink: #e9e7f0;
   /* Ink that reads on a SIGNAL colour once that colour becomes a fill — the glyph in a
      success circle, or on a toast's status circle. One near-black ink clears all five in
@@ -267,7 +266,6 @@
   --accent: #6a2dcc;
   --accent-strong: #6a2dcc; /* already dark enough for white text */
   --accent-contrast: #ffffff;
-  --ink: #1e232b;
   --signal-contrast: #0c0c0c;
   --danger-contrast: #ffffff;