@astronox/core 0.5.8 → 0.5.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/client/scroll.ts

@@ -1,5 +1,5 @@
 type JumpToElementOptions = {
-  block?: ScrollLogicalPosition;
+  block?: ScrollLogicalPosition | 'auto';
   inline?: ScrollLogicalPosition;
 };
 
@@ -7,6 +7,19 @@ export function jumpToElement(
   element: Element,
   { block = 'center', inline = 'nearest' }: JumpToElementOptions = {},
 ): void {
+  if (block === 'auto') {
+    const header = document.querySelector<HTMLElement>('[data-site-header]');
+    const viewportHeight = window.visualViewport?.height ?? window.innerHeight;
+    const availableHeight = Math.max(
+      0,
+      viewportHeight - (header?.getBoundingClientRect().height ?? 0),
+    );
+    block =
+      element.getBoundingClientRect().height <= availableHeight
+        ? 'center'
+        : 'start';
+  }
+
   element.scrollIntoView({
     behavior: 'auto',
     block,

package/src/components/data-display/IconList/IconList.astro

@@ -2,6 +2,7 @@
 import type { HTMLAttributes } from 'astro/types';
 import type { DisplayIconItem } from '../../../display/contracts';
 import type { Tone } from '../../../theme/contracts';
+import Tooltip from '../../feedback/Tooltip/Tooltip.astro';
 
 type Props = HTMLAttributes<'div'> & {
   'data-tone'?: Tone;
@@ -9,6 +10,7 @@ type Props = HTMLAttributes<'div'> & {
   label?: string;
   size?: 'small' | 'medium';
   tone?: Tone;
+  tooltips?: boolean;
 };
 
 const {
@@ -18,6 +20,7 @@ const {
   label,
   size = 'small',
   tone,
+  tooltips = true,
   ...attrs
 }: Props = Astro.props;
 const resolvedTone = tone ?? dataTone;
@@ -34,6 +37,11 @@ const resolvedTone = tone ?? dataTone;
   {
     items.map((item) => {
       const Icon = item.icon;
+      const tooltip = tooltips
+        ? typeof item.tooltip === 'string'
+          ? item.tooltip.trim()
+          : item.tooltip
+        : undefined;
       const icon = (
         <span class="icon-list__icon">
           <Icon />
@@ -44,14 +52,16 @@ const resolvedTone = tone ?? dataTone;
           <span class="icon-list__value">{item.value}</span>
         ) : null;
 
-      return (
+      const content = (
         <span
           class="icon-list__item"
           data-muted={item.muted ? 'true' : undefined}
           data-tone={item.tone}
           role="group"
           aria-label={item.label}
-          title={item.label}
+          title={tooltips && !tooltip ? item.label : undefined}
+          tabindex={tooltip ? '0' : undefined}
+          data-tooltip-trigger={tooltip ? true : undefined}
         >
           <span class="icon-list__visible" aria-hidden="true">
             {item.iconPosition === 'end' ? value : icon}
@@ -59,6 +69,14 @@ const resolvedTone = tone ?? dataTone;
           </span>
         </span>
       );
+
+      return tooltip ? (
+        <Tooltip content={tooltip} activation="hover">
+          {content}
+        </Tooltip>
+      ) : (
+        content
+      );
     })
   }
 </div>

package/src/components/data-display/MetricTile/MetricTileContent.astro

@@ -42,7 +42,12 @@ const ValueIcon = icon?.component;
 <dd class="metric-tile__value">
   {
     items ? (
-      <IconList items={items} label={itemsLabel} size="medium" />
+      <IconList
+        items={items}
+        label={itemsLabel}
+        size="medium"
+        tooltips={!hint}
+      />
     ) : (
       <>
         <strong data-metric-value>{value}</strong>

package/src/components/feedback/Tooltip/Tooltip.css

@@ -26,8 +26,16 @@
   position: fixed;
   z-index: 100;
   inset: auto;
+  box-sizing: border-box;
   inline-size: max-content;
-  max-inline-size: min(22rem, calc(100vw - var(--nox-space-4) * 2));
+  min-inline-size: 0;
+  max-inline-size: min(
+    26rem,
+    var(
+      --tooltip-available-inline-size,
+      calc(100vw - var(--tooltip-viewport-gap) * 2)
+    )
+  );
   max-block-size: calc(100dvh - var(--nox-space-4) * 2);
   margin: 0;
   padding: var(--nox-space-3) var(--nox-space-4);

package/src/components/feedback/Tooltip/tooltipController.ts

@@ -125,17 +125,16 @@ export function initTooltip(root: HTMLElement): () => void {
     const triggerGap = getCssLength(panel, '--tooltip-trigger-gap', 8);
     const triggerRect = trigger.getBoundingClientRect();
     const boundary =
-      root.dataset.tooltipAlignTo === 'boundary'
-        ? root.closest<HTMLElement>('[data-tooltip-boundary]')
-        : null;
-    const boundaryRect = boundary?.getBoundingClientRect();
+      root.closest<HTMLElement>('[data-tooltip-boundary], main, dialog') ??
+      document.body;
+    const boundaryRect = boundary.getBoundingClientRect();
     const horizontalLeft = Math.max(
       viewport.left + viewportGap,
-      boundaryRect?.left ?? viewport.left + viewportGap,
+      boundaryRect.left,
     );
     const horizontalRight = Math.min(
       viewport.right - viewportGap,
-      boundaryRect?.right ?? viewport.right - viewportGap,
+      boundaryRect.right,
     );
     const maximumInlineSize = Math.max(0, horizontalRight - horizontalLeft);
     const maximumBlockSize = Math.max(
@@ -143,7 +142,10 @@ export function initTooltip(root: HTMLElement): () => void {
       viewport.bottom - viewport.top - viewportGap * 2,
     );
 
-    panel.style.maxInlineSize = `${Math.floor(maximumInlineSize)}px`;
+    panel.style.setProperty(
+      '--tooltip-available-inline-size',
+      `${Math.floor(maximumInlineSize)}px`,
+    );
     panel.style.maxBlockSize = `${Math.floor(maximumBlockSize)}px`;
     panel.style.visibility = 'hidden';
     panel.style.left = `${Math.round(horizontalLeft)}px`;
@@ -165,7 +167,8 @@ export function initTooltip(root: HTMLElement): () => void {
 
     panel.style.maxBlockSize = `${Math.floor(availableBlockSize)}px`;
     const panelRect = panel.getBoundingClientRect();
-    const horizontalAnchor = boundaryRect ?? triggerRect;
+    const horizontalAnchor =
+      root.dataset.tooltipAlignTo === 'boundary' ? boundaryRect : triggerRect;
     const centeredLeft =
       horizontalAnchor.left + (horizontalAnchor.width - panelRect.width) / 2;
     const left = Math.min(
@@ -199,7 +202,7 @@ export function initTooltip(root: HTMLElement): () => void {
     panel.hidden = true;
     panel.style.removeProperty('left');
     panel.style.removeProperty('top');
-    panel.style.removeProperty('max-inline-size');
+    panel.style.removeProperty('--tooltip-available-inline-size');
     panel.style.removeProperty('max-block-size');
     panel.style.removeProperty('visibility');
   };

package/src/components/media/EmbedFrame/EmbedFrame.astro

@@ -21,6 +21,9 @@ type Props = Omit<
   loading?: EmbedLoading;
   loadingIndicator?: EmbedLoadingIndicator;
   loadingLabel: string;
+  pageScroll?: 'auto' | 'lock-while-interacting';
+  scrollOnActivate?: boolean;
+  scrollTargetId?: string;
   src: string;
   title: string;
   tone?: Tone;
@@ -45,6 +48,9 @@ const {
   loading = 'lazy',
   loadingIndicator = 'spinner',
   loadingLabel,
+  pageScroll = 'auto',
+  scrollOnActivate = false,
+  scrollTargetId,
   src,
   title,
   tone,
@@ -59,6 +65,9 @@ const resolvedTone = tone ?? dataTone;
   class="embed-frame"
   data-embed-frame-activation={activation}
   data-embed-frame-source={activation === 'manual' ? src : undefined}
+  data-embed-frame-page-scroll={pageScroll}
+  data-embed-frame-scroll-on-activate={scrollOnActivate ? 'true' : undefined}
+  data-embed-frame-scroll-target={scrollTargetId}
   data-aspect-ratio={aspectRatio}
   data-fullscreen-region={fullscreen ? true : undefined}
   data-widget="embed-frame"

package/src/components/media/EmbedFrame/EmbedFrame.css

@@ -6,6 +6,11 @@
   overflow: hidden;
 }
 
+html:has([data-embed-frame-scroll-locked]),
+[data-site-scroll-root]:has([data-embed-frame-scroll-locked]) {
+  overflow: hidden;
+}
+
 .embed-frame[data-aspect-ratio='16/9'] {
   aspect-ratio: 16 / 9;
 }

package/src/components/media/EmbedFrame/embedFrameController.ts

@@ -1,3 +1,5 @@
+import { jumpToElement } from '../../../client/scroll';
+
 const activateEvent = 'nox:embed-frame:activate';
 
 export function activateEmbedFrame(
@@ -27,6 +29,55 @@ export const initEmbedFrame = (root: HTMLElement): (() => void) => {
   let activated =
     root.dataset.embedFrameActivation !== 'manual' ||
     root.dataset.embedFrameActive === 'true';
+  let activationFocusFrame = 0;
+  let focusCheckFrame = 0;
+  let interactionDismissed = false;
+  const lockPageScroll =
+    root.dataset.embedFramePageScroll === 'lock-while-interacting';
+
+  const setScrollLock = (locked: boolean) => {
+    root.toggleAttribute(
+      'data-embed-frame-scroll-locked',
+      lockPageScroll && activated && locked,
+    );
+  };
+
+  const releaseScroll = () => {
+    cancelAnimationFrame(activationFocusFrame);
+    cancelAnimationFrame(focusCheckFrame);
+    activationFocusFrame = 0;
+    focusCheckFrame = 0;
+    interactionDismissed = true;
+    setScrollLock(false);
+  };
+  const enterFrame = () => {
+    cancelAnimationFrame(focusCheckFrame);
+    focusCheckFrame = 0;
+    interactionDismissed = false;
+    setScrollLock(true);
+  };
+  const leaveFrame = (event: PointerEvent) => {
+    if (event.pointerType !== 'touch') releaseScroll();
+  };
+  const updateFocus = () => {
+    cancelAnimationFrame(focusCheckFrame);
+    focusCheckFrame = requestAnimationFrame(() => {
+      focusCheckFrame = 0;
+      setScrollLock(!interactionDismissed && document.activeElement === iframe);
+    });
+  };
+  const interactOutside = (event: Event) => {
+    if (event.target instanceof Node && !root.contains(event.target)) {
+      releaseScroll();
+    }
+  };
+
+  const scrollToFrame = () => {
+    if (root.dataset.embedFrameScrollOnActivate !== 'true') return;
+    const targetId = root.dataset.embedFrameScrollTarget;
+    const target = (targetId && document.getElementById(targetId)) || root;
+    jumpToElement(target, { block: 'auto' });
+  };
 
   const markLoaded = () => {
     if (!activated) return;
@@ -46,19 +97,51 @@ export const initEmbedFrame = (root: HTMLElement): (() => void) => {
     root.setAttribute('aria-busy', loading ? 'true' : 'false');
     root.setAttribute('data-embed-frame-active', 'true');
     iframe.src = src;
+    scrollToFrame();
   };
 
   const activateFromControl = () => {
     activate();
-    requestAnimationFrame(() => iframe.focus({ preventScroll: true }));
+    cancelAnimationFrame(activationFocusFrame);
+    interactionDismissed = false;
+    activationFocusFrame = requestAnimationFrame(() => {
+      activationFocusFrame = 0;
+      iframe.focus({ preventScroll: true });
+      setScrollLock(document.activeElement === iframe);
+    });
   };
 
   if (activated && activationLayer) activationLayer.hidden = true;
   iframe.addEventListener('load', markLoaded);
   root.addEventListener(activateEvent, activate);
   activationControl?.addEventListener('click', activateFromControl);
+  if (lockPageScroll) {
+    root.addEventListener('pointerenter', enterFrame);
+    root.addEventListener('pointerleave', leaveFrame);
+    iframe.addEventListener('focus', enterFrame);
+    iframe.addEventListener('blur', releaseScroll);
+    window.addEventListener('blur', updateFocus);
+    window.addEventListener('focus', updateFocus);
+    window.addEventListener('pagehide', releaseScroll);
+    document.addEventListener('focusin', interactOutside);
+    document.addEventListener('pointerdown', interactOutside, true);
+    document.addEventListener('wheel', interactOutside, { passive: true });
+    document.addEventListener('touchstart', interactOutside, { passive: true });
+  }
 
   return () => {
+    releaseScroll();
+    root.removeEventListener('pointerenter', enterFrame);
+    root.removeEventListener('pointerleave', leaveFrame);
+    iframe.removeEventListener('focus', enterFrame);
+    iframe.removeEventListener('blur', releaseScroll);
+    window.removeEventListener('blur', updateFocus);
+    window.removeEventListener('focus', updateFocus);
+    window.removeEventListener('pagehide', releaseScroll);
+    document.removeEventListener('focusin', interactOutside);
+    document.removeEventListener('pointerdown', interactOutside, true);
+    document.removeEventListener('wheel', interactOutside);
+    document.removeEventListener('touchstart', interactOutside);
     iframe.removeEventListener('load', markLoaded);
     root.removeEventListener(activateEvent, activate);
     activationControl?.removeEventListener('click', activateFromControl);

package/src/display/contracts.ts

@@ -92,6 +92,7 @@ export type DisplayIconItem = {
   label: string;
   muted?: boolean;
   tone?: Tone;
+  tooltip?: string | DisplayTooltip;
   value?: DisplayTextValue;
 };
 

package/src/patterns/CircuitPuzzle/CircuitPuzzle.astro

@@ -1,11 +1,14 @@
 ---
 import type { HTMLAttributes } from 'astro/types';
+import type { DisplayMedia } from '../../display/contracts';
+import Media from '../../primitives/media/Media/Media.astro';
 import PuzzleGrid from '../PuzzleGrid/PuzzleGrid.astro';
 import type { CircuitPuzzleLabels, CircuitPuzzleModel } from './contracts';
 
 type Props = HTMLAttributes<'section'> & {
   label: string;
   labels: CircuitPuzzleLabels;
+  coreMedia?: DisplayMedia;
   puzzles: readonly CircuitPuzzleModel[];
 };
 
@@ -13,6 +16,7 @@ const {
   class: className,
   label,
   labels,
+  coreMedia,
   puzzles,
   ...attrs
 }: Props = Astro.props;
@@ -54,6 +58,9 @@ const {
                 data-puzzle-cell-interactive={cell.fixed ? undefined : ''}
                 data-puzzle-cell-disabled={cell.fixed ? '' : undefined}
                 data-circuit-cell={cell.id}
+                data-puzzle-control={cell.fixed ? undefined : ''}
+                data-cell-row={cell.row}
+                data-cell-column={cell.column}
                 data-cell-kind={cell.kind}
                 data-cell-label={cellLabel}
                 data-orientation-label={labels.orientation}
@@ -64,7 +71,16 @@ const {
                 disabled={cell.fixed ? true : undefined}
                 style={`--cell-row: ${cell.row + 1}; --cell-column: ${cell.column + 1}; --cell-rotation: ${cell.initialRotation}deg; --cell-index: ${cellIndex};`}
               >
-                <span class="circuit-puzzle__piece" aria-hidden="true">
+                <span
+                  class:list={[
+                    'circuit-puzzle__piece',
+                    {
+                      'circuit-puzzle__piece--with-media':
+                        cell.kind === 'core' && coreMedia,
+                    },
+                  ]}
+                  aria-hidden="true"
+                >
                   {cell.connections.map((direction) => (
                     <span
                       class:list={[
@@ -73,8 +89,15 @@ const {
                       ]}
                     />
                   ))}
-                  <span class="circuit-puzzle__node" />
+                  {!(cell.kind === 'core' && coreMedia) && (
+                    <span class="circuit-puzzle__node" />
+                  )}
                 </span>
+                {cell.kind === 'core' && coreMedia && (
+                  <span class="circuit-puzzle__core-media" aria-hidden="true">
+                    <Media media={coreMedia} size="fill" />
+                  </span>
+                )}
               </button>
             );
           })}

package/src/patterns/CircuitPuzzle/CircuitPuzzle.css

@@ -36,6 +36,15 @@
   --circuit-puzzle-symbol-color: var(--nox-source-tone-danger);
 }
 
+.circuit-puzzle__instance[data-puzzle-status='valid']
+  .circuit-puzzle__cell[data-cell-kind='core'] {
+  --puzzle-cell-state-background: color-mix(
+    in srgb,
+    var(--nox-source-tone-success) 14%,
+    var(--nox-surface)
+  );
+}
+
 .circuit-puzzle__piece {
   position: relative;
   display: grid;
@@ -46,6 +55,21 @@
   color: var(--circuit-puzzle-symbol-color);
 }
 
+.circuit-puzzle__piece--with-media {
+  grid-area: 1 / 1;
+  inline-size: 100%;
+  block-size: 100%;
+}
+
+.circuit-puzzle__core-media {
+  z-index: 1;
+  grid-area: 1 / 1;
+  display: grid;
+  inline-size: 84%;
+  aspect-ratio: 1;
+  pointer-events: none;
+}
+
 .circuit-puzzle__node {
   z-index: 1;
   inline-size: 32%;

package/src/patterns/CircuitPuzzle/circuitPuzzleController.ts

@@ -3,6 +3,11 @@ import {
   setPuzzleGridState,
 } from '../PuzzleGrid/state';
 import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import {
+  initPuzzleKeyboard,
+  type PuzzleKeyboard,
+} from '../PuzzleGrid/keyboard';
+import type { PuzzleDirection } from '../PuzzleGrid/movement';
 import type {
   CircuitPuzzleChangeDetail,
   CircuitPuzzleEvaluation,
@@ -11,6 +16,7 @@ import type {
 
 type CircuitInstance = {
   activeIndex: number;
+  keyboard?: PuzzleKeyboard;
 };
 
 const rotations: readonly CircuitRotation[] = [0, 90, 180, 270];
@@ -60,6 +66,21 @@ export function initCircuitPuzzle(root: HTMLElement): void {
     setRotation(cell, rotations[nextIndex], visualRotation + 90);
     emitChange(root);
   });
+  instances.get(root)!.keyboard = initPuzzleKeyboard(root, {
+    getPanel: () => getActivePanel(root),
+    getSelected: () =>
+      getActivePanel(root)?.querySelector<HTMLButtonElement>(
+        '[data-circuit-cell][data-puzzle-cell-selected]',
+      ) ?? null,
+    select: (cell) => {
+      const panel = getActivePanel(root);
+      if (panel) selectCell(panel, cell);
+    },
+    move: (cell, direction) => {
+      const panel = getActivePanel(root);
+      if (panel) moveCellFocus(panel, cell, direction);
+    },
+  });
 }
 
 export function selectCircuitPuzzle(root: HTMLElement, index: number): void {
@@ -100,6 +121,7 @@ export function resetCircuitPuzzle(root: HTMLElement): void {
       panel.removeAttribute('data-puzzle-resetting');
     });
   });
+  instances.get(root)?.keyboard?.reset();
   emitChange(root);
 }
 
@@ -132,6 +154,7 @@ export function setCircuitPuzzleEvaluation(
   if (grid) {
     setPuzzleGridState(grid, evaluation.status === 'valid' ? 'valid' : null);
   }
+  if (evaluation.status === 'valid') selectCell(panel, null);
 
   if (evaluation.status === 'valid' && previous !== 'valid') {
     root.dispatchEvent(
@@ -170,6 +193,32 @@ function selectCell(
   }
 }
 
+function moveCellFocus(
+  panel: HTMLElement,
+  origin: HTMLButtonElement,
+  direction: PuzzleDirection,
+): void {
+  const vertical = direction === 'north' || direction === 'south';
+  const sign = direction === 'north' || direction === 'west' ? -1 : 1;
+  const row = Number(origin.dataset.cellRow);
+  const column = Number(origin.dataset.cellColumn);
+  let nearest: HTMLButtonElement | null = null;
+  let nearestDistance = Infinity;
+  for (const cell of panel.querySelectorAll<HTMLButtonElement>(
+    '[data-puzzle-control]:not(:disabled)',
+  )) {
+    const rowDistance = Number(cell.dataset.cellRow) - row;
+    const columnDistance = Number(cell.dataset.cellColumn) - column;
+    if (vertical ? columnDistance !== 0 : rowDistance !== 0) continue;
+    const distance = (vertical ? rowDistance : columnDistance) * sign;
+    if (distance > 0 && distance < nearestDistance) {
+      nearest = cell;
+      nearestDistance = distance;
+    }
+  }
+  nearest?.focus({ preventScroll: true });
+}
+
 function emitChange(root: HTMLElement): void {
   const panel = getActivePanel(root);
   if (!panel?.dataset.puzzleId) return;

package/src/patterns/LightMazePuzzle/LightMazePuzzle.astro

@@ -188,6 +188,7 @@ if (puzzles.some((puzzle) => puzzle.activators?.length) && !media.mechanism)
                 aria-label={labels[piece]}
                 aria-pressed="false"
                 data-light-maze-piece={piece}
+                data-puzzle-control
                 style={`--piece-row: ${initial[piece].row + 1}; --piece-column: ${initial[piece].column + 1};`}
               >
                 <span class="light-maze-puzzle__piece-media" aria-hidden="true">

package/src/patterns/LightMazePuzzle/LightMazePuzzle.css

@@ -33,7 +33,7 @@
 
 .light-maze-puzzle__activator {
   position: absolute;
-  inset: 18%;
+  inset: 8%;
   display: grid;
   pointer-events: none;
 }
@@ -110,7 +110,7 @@
   margin: var(--nox-space-1);
   padding: 0;
   place-items: center;
-  border: 0;
+  border: var(--nox-border-width) solid transparent;
   border-radius: var(--nox-radius-sm);
   background: transparent;
   cursor: grab;
@@ -120,7 +120,7 @@
 
 .light-maze-puzzle__piece-media {
   display: grid;
-  inline-size: 80%;
+  inline-size: 84%;
   aspect-ratio: 1;
   pointer-events: none;
 }
@@ -173,6 +173,12 @@
   --puzzle-cell-ring-width: 0px;
 }
 
+@media (width < 34rem) {
+  .light-maze-puzzle__piece {
+    margin: 2px;
+  }
+}
+
 @media (prefers-reduced-motion: no-preference) {
   .light-maze-puzzle__piece[data-piece-moved] {
     animation: light-maze-puzzle-move 260ms var(--nox-motion-easing-standard);