@astronox/core 0.5.8 → 0.5.10

package/src/patterns/LightMazePuzzle/lightMazePuzzleController.ts

@@ -1,13 +1,19 @@
 import {
   animatePieceMovement,
   cancelDragFrame,
+  clearPuzzleMovementPreview,
   findDirectionalDropDestination,
+  getPuzzleMoveTarget,
   hasLeftOriginCell,
   renderPathStream,
   scheduleDragFrame,
   type PuzzleDrag,
 } from '../PuzzleGrid/movement';
 import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import {
+  initPuzzleKeyboard,
+  type PuzzleKeyboard,
+} from '../PuzzleGrid/keyboard';
 import { presentLightMazeCell } from './presentation';
 import {
   setPuzzleGridCellState,
@@ -48,15 +54,10 @@ type Instance = {
   clickTimer: number | null;
   controller: AbortController;
   dismiss: () => void;
+  keyboard?: PuzzleKeyboard;
 };
 
 const instances = new WeakMap<HTMLElement, Instance>();
-const arrows: Record<string, LightMazeDirection> = {
-  ArrowUp: 'north',
-  ArrowRight: 'east',
-  ArrowDown: 'south',
-  ArrowLeft: 'west',
-};
 
 export function initLightMazePuzzle(root: HTMLElement): void {
   if (instances.has(root)) return;
@@ -92,15 +93,14 @@ export function initLightMazePuzzle(root: HTMLElement): void {
   instances.set(root, instance);
   instance.dismiss = initPuzzleSelectionDismissal(root, {
     dismiss: () => selectPiece(root, null),
-    isSelectionTarget: (target) => {
+    isSelectionTarget: (target, event) => {
       const panel = active(instance);
       return (
         panel.element.dataset.puzzleStatus !== 'valid' &&
         panel.element.contains(target) &&
         Boolean(
-          target.closest(
-            '[data-light-maze-piece], [data-light-maze-destination]',
-          ),
+          target.closest('[data-light-maze-piece]') ||
+          getPuzzleMoveTarget(panel.element, event),
         )
       );
     },
@@ -128,50 +128,14 @@ export function initLightMazePuzzle(root: HTMLElement): void {
         selectPiece(root, instance.selected === id ? null : id);
         return;
       }
-      const destination = event.target.closest<HTMLButtonElement>(
-        '[data-light-maze-destination]',
-      );
-      if (destination && !destination.disabled) {
-        void move(
-          root,
-          destination.dataset.destinationPiece as LightMazePiece,
-          destination.dataset.destinationDirection as LightMazeDirection,
-        );
+      const movement = getPuzzleMoveTarget(active(instance).element, event);
+      if (movement) {
+        void move(root, movement.pieceId as LightMazePiece, movement.direction);
       } else selectPiece(root, null);
     },
     options,
   );
 
-  root.addEventListener(
-    'keydown',
-    (event) => {
-      if (instance.motion) {
-        if (arrows[event.key] || ['Enter', ' ', 'Escape'].includes(event.key))
-          event.preventDefault();
-        return;
-      }
-      if (event.altKey || event.ctrlKey || event.metaKey || instance.drag)
-        return;
-      if (event.key === 'Escape') {
-        selectPiece(root, null);
-        return;
-      }
-      const direction = arrows[event.key];
-      if (!direction) return;
-      const focused =
-        event.target instanceof Element
-          ? event.target.closest<HTMLElement>('[data-light-maze-piece]')
-          : null;
-      const piece =
-        (focused?.dataset.lightMazePiece as LightMazePiece | undefined) ??
-        instance.selected;
-      if (!piece) return;
-      event.preventDefault();
-      void move(root, piece, direction);
-    },
-    options,
-  );
-
   root.addEventListener(
     'pointerdown',
     (event) => {
@@ -264,6 +228,30 @@ export function initLightMazePuzzle(root: HTMLElement): void {
     options,
   );
   render(root);
+  instance.keyboard = initPuzzleKeyboard(root, {
+    getPanel: () => active(instance).element,
+    getSelected: () =>
+      instance.selected
+        ? active(instance).element.querySelector<HTMLButtonElement>(
+            `[data-light-maze-piece="${instance.selected}"]`,
+          )
+        : null,
+    select: (piece) => {
+      if (!piece) cancelDrag(instance);
+      selectPiece(
+        root,
+        (piece?.dataset.lightMazePiece as LightMazePiece | undefined) ?? null,
+      );
+    },
+    move: (piece, direction) => {
+      void move(
+        root,
+        piece.dataset.lightMazePiece as LightMazePiece,
+        direction,
+      );
+    },
+    isLocked: () => instance.motion !== null || instance.drag !== null,
+  });
 }
 
 export function selectLightMazePuzzle(root: HTMLElement, index: number): void {
@@ -302,6 +290,7 @@ export function resetLightMazePuzzle(root: HTMLElement): void {
     piece.removeAttribute('data-piece-moved');
   }
   render(root);
+  instance.keyboard?.reset();
   emitChange(root, panel);
 }
 
@@ -339,6 +328,7 @@ export function destroyLightMazePuzzle(root: HTMLElement): void {
   cancelMotion(instance);
   instance.controller.abort();
   instance.dismiss();
+  instance.keyboard?.destroy();
   cancelDrag(instance);
   clearClickTimer(instance);
   for (const panel of instance.panels) {
@@ -360,7 +350,7 @@ function selectPiece(root: HTMLElement, piece: LightMazePiece | null): void {
   const instance = instances.get(root);
   if (
     !instance ||
-    instance.motion ||
+    (instance.motion && piece !== null) ||
     active(instance).element.dataset.puzzleStatus === 'valid'
   )
     return;
@@ -570,8 +560,8 @@ function renderSelection(root: HTMLElement): void {
     if (movement.piece !== instance.selected) continue;
     const destination = findCell(panel, movement.to);
     if (!destination) continue;
-    renderPathStream(panel.board, movement);
-    destination.tabIndex = 0;
+    renderPathStream(panel.board, movement, movement.piece);
+    destination.tabIndex = -1;
     destination.setAttribute('data-light-maze-destination', '');
     destination.setAttribute('data-puzzle-cell-interactive', '');
     destination.dataset.destinationPiece = movement.piece;
@@ -587,10 +577,7 @@ function renderSelection(root: HTMLElement): void {
 }
 
 function clearPreviews(panel: Panel): void {
-  for (const stream of panel.element.querySelectorAll(
-    '[data-puzzle-path-stream]',
-  ))
-    stream.remove();
+  clearPuzzleMovementPreview(panel.element);
   for (const cell of panel.element.querySelectorAll<HTMLButtonElement>(
     '[data-light-maze-destination]',
   )) {

package/src/patterns/MagneticFieldPuzzle/MagneticFieldPuzzle.astro

@@ -4,14 +4,17 @@ import MinusIcon from '../../components/icons/MinusIcon.astro';
 import PlusIcon from '../../components/icons/PlusIcon.astro';
 import SlashIcon from '../../components/icons/SlashIcon.astro';
 import PuzzleGrid from '../PuzzleGrid/PuzzleGrid.astro';
+import Media from '../../primitives/media/Media/Media.astro';
 import type {
   MagneticFieldPuzzleLabels,
   MagneticFieldPuzzleModel,
+  MagneticFieldPuzzleMedia,
 } from './contracts';
 
 type Props = HTMLAttributes<'section'> & {
   label: string;
   labels: MagneticFieldPuzzleLabels;
+  media?: MagneticFieldPuzzleMedia;
   puzzles: readonly MagneticFieldPuzzleModel[];
 };
 
@@ -19,9 +22,16 @@ const {
   class: className,
   label,
   labels,
+  media,
   puzzles,
   ...attrs
 }: Props = Astro.props;
+
+if (
+  media &&
+  puzzles.some((puzzle) => puzzle.pieces.some((piece) => !media[piece.id]))
+)
+  throw new Error('Magnetic field puzzle media must cover every piece.');
 ---
 
 <section
@@ -46,7 +56,53 @@ const {
           data-puzzle-id={puzzle.id}
           data-puzzle-status="incomplete"
           hidden={puzzleIndex !== 0}
+          style={
+            media
+              ? `--piece-selection-filter: url(#magnetic-outline-${encodeURIComponent(puzzle.id)}); --piece-hover-filter: url(#magnetic-hover-${encodeURIComponent(puzzle.id)});`
+              : undefined
+          }
         >
+          {media && (
+            <svg
+              class="magnetic-field-puzzle__filters"
+              aria-hidden="true"
+              focusable="false"
+            >
+              <defs>
+                <filter
+                  id={`magnetic-hover-${encodeURIComponent(puzzle.id)}`}
+                  color-interpolation-filters="sRGB"
+                >
+                  <feFlood
+                    class="magnetic-field-puzzle__hover-color"
+                    flood-opacity="0.1"
+                  />
+                  <feComposite operator="in" in2="SourceAlpha" />
+                  <feMerge>
+                    <feMergeNode in="SourceGraphic" />
+                    <feMergeNode />
+                  </feMerge>
+                </filter>
+                <filter
+                  id={`magnetic-outline-${encodeURIComponent(puzzle.id)}`}
+                  x="-25%"
+                  y="-25%"
+                  width="150%"
+                  height="150%"
+                  color-interpolation-filters="sRGB"
+                >
+                  <feMorphology in="SourceAlpha" operator="dilate" radius="2" />
+                  <feGaussianBlur stdDeviation="0.5" result="outline" />
+                  <feFlood class="magnetic-field-puzzle__ring-color" />
+                  <feComposite operator="in" in2="outline" />
+                  <feMerge>
+                    <feMergeNode />
+                    <feMergeNode in="SourceGraphic" />
+                  </feMerge>
+                </filter>
+              </defs>
+            </svg>
+          )}
           <PuzzleGrid
             class="magnetic-field-puzzle__board"
             label={puzzle.label}
@@ -158,6 +214,8 @@ const {
                 aria-label={`${piece.label} — ${labels.polarities[piece.polarity]}`}
                 aria-pressed="false"
                 data-field-piece={piece.id}
+                data-puzzle-control
+                data-field-piece-media={media ? '' : undefined}
                 data-piece-label={piece.label}
                 data-piece-short-label={piece.shortLabel}
                 data-piece-row={piece.row}
@@ -175,9 +233,13 @@ const {
                   class="magnetic-field-puzzle__piece-core"
                   aria-hidden="true"
                 >
-                  <span class="magnetic-field-puzzle__piece-iris">
-                    <span class="magnetic-field-puzzle__piece-pupil" />
-                  </span>
+                  {media ? (
+                    <Media media={media[piece.id]!} size="fill" />
+                  ) : (
+                    <span class="magnetic-field-puzzle__piece-iris">
+                      <span class="magnetic-field-puzzle__piece-pupil" />
+                    </span>
+                  )}
                   <span class="magnetic-field-puzzle__piece-identity-region">
                     <span
                       class="magnetic-field-puzzle__identity"

package/src/patterns/MagneticFieldPuzzle/MagneticFieldPuzzle.css

@@ -19,6 +19,21 @@
   display: none;
 }
 
+.magnetic-field-puzzle__filters {
+  position: absolute;
+  inline-size: 0;
+  block-size: 0;
+  pointer-events: none;
+}
+
+.magnetic-field-puzzle__ring-color {
+  flood-color: var(--nox-source-tone-info);
+}
+
+.magnetic-field-puzzle__hover-color {
+  flood-color: var(--nox-tone-color);
+}
+
 .magnetic-field-puzzle__board {
   isolation: isolate;
   touch-action: manipulation;
@@ -287,6 +302,60 @@
   );
 }
 
+.magnetic-field-puzzle__piece[data-field-piece-media] {
+  border: var(--nox-border-width) solid transparent;
+}
+
+.magnetic-field-puzzle__piece[data-field-piece-media]
+  .magnetic-field-puzzle__piece-core {
+  inline-size: 84%;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  box-shadow: none;
+  container-type: inline-size;
+  pointer-events: none;
+}
+
+.magnetic-field-puzzle__piece[data-field-piece-media]
+  .magnetic-field-puzzle__piece-identity-region {
+  inset-block: 68% 14%;
+}
+
+.magnetic-field-puzzle__piece[data-field-piece-media]
+  .magnetic-field-puzzle__identity {
+  font-size: clamp(0.625rem, 22cqi, var(--nox-font-size-md));
+}
+
+.magnetic-field-puzzle__piece[data-field-piece-media]:is(
+    [data-piece-selected],
+    :focus-visible
+  )
+  .magnetic-field-puzzle__piece-core {
+  filter: var(--piece-selection-filter);
+}
+
+@media (hover: hover) {
+  .magnetic-field-puzzle__piece[data-field-piece-media]:hover
+    .magnetic-field-puzzle__piece-core {
+    filter: var(--piece-hover-filter);
+  }
+
+  .magnetic-field-puzzle__piece[data-field-piece-media]:is(
+      [data-piece-selected],
+      :focus-visible
+    ):hover
+    .magnetic-field-puzzle__piece-core {
+    filter: var(--piece-hover-filter) var(--piece-selection-filter);
+  }
+}
+
+@media (width < 34rem) {
+  .magnetic-field-puzzle__piece[data-field-piece-media] {
+    margin: 2px;
+  }
+}
+
 @media (prefers-reduced-motion: no-preference) {
   .magnetic-field-puzzle__piece[data-piece-moved] {
     animation: magnetic-field-slide 260ms var(--nox-motion-easing-standard);

package/src/patterns/MagneticFieldPuzzle/contracts.ts

@@ -1,3 +1,7 @@
+import type { DisplayMedia } from '../../display/contracts';
+
+export type MagneticFieldPuzzleMedia = Readonly<Record<string, DisplayMedia>>;
+
 export type MagneticFieldDirection = 'north' | 'east' | 'south' | 'west';
 export type MagneticFieldPolarity = 'north' | 'south';
 export type MagneticFieldPupilPosition = 'upper-end' | 'center' | 'lower-start';

package/src/patterns/MagneticFieldPuzzle/magneticFieldPuzzleController.ts

@@ -1,7 +1,9 @@
 import {
   animatePieceMovement,
   cancelDragFrame,
+  clearPuzzleMovementPreview,
   findDirectionalDropDestination,
+  getPuzzleMoveTarget,
   hasLeftOriginCell,
   renderPathStream,
   scheduleDragFrame,
@@ -12,6 +14,10 @@ import {
   setPuzzleGridState,
 } from '../PuzzleGrid/state';
 import { initPuzzleSelectionDismissal } from '../PuzzleGrid/selectionDismissal';
+import {
+  initPuzzleKeyboard,
+  type PuzzleKeyboard,
+} from '../PuzzleGrid/keyboard';
 import type {
   MagneticFieldDirection,
   MagneticFieldPolarity,
@@ -33,6 +39,7 @@ type MagneticFieldInstance = {
   selectedPieceId: string | null;
   drag: PuzzleDrag | null;
   ignoreNextClick: boolean;
+  keyboard?: PuzzleKeyboard;
 };
 
 const dragThreshold = 12;
@@ -48,19 +55,14 @@ export function initMagneticFieldPuzzle(root: HTMLElement): void {
   });
   initPuzzleSelectionDismissal(root, {
     dismiss: () => selectPiece(root, null),
-    isSelectionTarget: (target) => {
+    isSelectionTarget: (target, event) => {
       const panel = getActivePanel(root);
       if (!panel || panel.dataset.puzzleStatus === 'valid') return false;
 
       const piece = target.closest<HTMLElement>('[data-field-piece]');
       if (piece && panel.contains(piece)) return true;
 
-      const destination = target.closest<HTMLButtonElement>(
-        '[data-field-destination]',
-      );
-      return Boolean(
-        destination && panel.contains(destination) && !destination.disabled,
-      );
+      return Boolean(getPuzzleMoveTarget(panel, event));
     },
   });
 
@@ -79,14 +81,9 @@ export function initMagneticFieldPuzzle(root: HTMLElement): void {
       return;
     }
 
-    const destination = target.closest<HTMLButtonElement>(
-      '[data-field-destination]',
-    );
-    if (destination && !destination.disabled) {
-      const pieceId = destination.dataset.destinationPiece;
-      const direction = destination.dataset.destinationDirection as
-        MagneticFieldDirection | undefined;
-      if (pieceId && direction) movePiece(root, pieceId, direction);
+    const movement = getPuzzleMoveTarget(getActivePanel(root), event);
+    if (movement) {
+      movePiece(root, movement.pieceId, movement.direction);
       return;
     }
 
@@ -102,12 +99,11 @@ export function initMagneticFieldPuzzle(root: HTMLElement): void {
     const pieceId = piece?.dataset.fieldPiece;
     if (!piece || !pieceId || !instance) return;
     const panel = getActivePanel(root);
-    const originCell = panel
-      ? findCell(panel, {
-          row: Number(piece.dataset.pieceRow),
-          column: Number(piece.dataset.pieceColumn),
-        })
-      : null;
+    if (!panel || panel.dataset.puzzleStatus === 'valid') return;
+    const originCell = findCell(panel, {
+      row: Number(piece.dataset.pieceRow),
+      column: Number(piece.dataset.pieceColumn),
+    });
     if (!originCell) return;
     const pieceBounds = piece.getBoundingClientRect();
 
@@ -155,24 +151,20 @@ export function initMagneticFieldPuzzle(root: HTMLElement): void {
     finishDrag(root, event, false);
   });
 
-  root.addEventListener('keydown', (event) => {
-    if (event.altKey || event.ctrlKey || event.metaKey) return;
-    const direction = arrowDirections[event.key.toLowerCase()];
-    if (!direction) {
-      if (event.key === 'Escape') selectPiece(root, null);
-      return;
-    }
-
-    const piece = (event.target as Element | null)?.closest<HTMLElement>(
-      '[data-field-piece]',
-    );
-    const pieceId =
-      piece?.dataset.fieldPiece ??
-      instances.get(root)?.selectedPieceId ??
-      undefined;
-    if (!pieceId) return;
-    event.preventDefault();
-    movePiece(root, pieceId, direction);
+  const instance = instances.get(root)!;
+  instance.keyboard = initPuzzleKeyboard(root, {
+    getPanel: () => getActivePanel(root),
+    getSelected: () =>
+      getActivePanel(root)?.querySelector<HTMLButtonElement>(
+        '[data-field-piece][data-piece-selected]',
+      ) ?? null,
+    select: (piece) => {
+      if (!piece) cancelDrag(instance);
+      selectPiece(root, piece?.dataset.fieldPiece ?? null);
+    },
+    move: (piece, direction) =>
+      movePiece(root, piece.dataset.fieldPiece!, direction),
+    isLocked: () => instance.drag !== null,
   });
 }
 
@@ -286,11 +278,11 @@ function updateDestinations(root: HTMLElement): void {
   for (const movement of getMagneticFieldMoves(puzzle, state, pieceId)) {
     const directionLabel = readDirectionLabel(labels, movement.direction);
     const board = panel.querySelector<HTMLElement>('[data-field-board]');
-    if (board) renderPathStream(board, movement);
+    if (board) renderPathStream(board, movement, pieceId);
 
     const destination = findCell(panel, movement.to);
     if (!destination) continue;
-    destination.removeAttribute('tabindex');
+    destination.tabIndex = -1;
     destination.setAttribute('data-field-destination', '');
     destination.setAttribute('data-puzzle-cell-interactive', '');
     destination.dataset.destinationPiece = pieceId;
@@ -350,13 +342,15 @@ function initializeActivePuzzle(root: HTMLElement): void {
   const initial = createMagneticFieldInitialState(puzzle);
 
   instance.selectedPieceId = null;
-  instance.drag = null;
+  cancelDrag(instance);
   instance.ignoreNextClick = false;
   panel.dataset.puzzleStatus = 'incomplete';
   const grid = panel.querySelector<HTMLElement>('[data-puzzle-grid]');
   if (grid) setPuzzleGridState(grid, null);
   renderState(panel, puzzle, initial);
+  syncPieceSelection(panel, null);
   hideMovePreviews(panel);
+  instance.keyboard?.reset();
   emitChange(root, puzzle.id, initial);
 }
 
@@ -458,14 +452,7 @@ function finishDrag(
       ? findDirectionalDropDestination(drag, deltaX, deltaY)
       : null;
 
-  cancelDragFrame(drag);
-  drag.element.removeAttribute('data-piece-dragging');
-  drag.element.style.removeProperty('--piece-drag-x');
-  drag.element.style.removeProperty('--piece-drag-y');
-  if (drag.element.hasPointerCapture(event.pointerId)) {
-    drag.element.releasePointerCapture(event.pointerId);
-  }
-  instance.drag = null;
+  cancelDrag(instance);
 
   if (commit && drag.moved) {
     instance.ignoreNextClick = true;
@@ -492,12 +479,20 @@ function getDropDestinations(root: HTMLElement): HTMLButtonElement[] {
   ];
 }
 
+function cancelDrag(instance: MagneticFieldInstance): void {
+  const drag = instance.drag;
+  if (!drag) return;
+  instance.drag = null;
+  cancelDragFrame(drag);
+  drag.element.removeAttribute('data-piece-dragging');
+  drag.element.style.removeProperty('--piece-drag-x');
+  drag.element.style.removeProperty('--piece-drag-y');
+  if (drag.element.hasPointerCapture(drag.pointerId))
+    drag.element.releasePointerCapture(drag.pointerId);
+}
+
 function hideMovePreviews(panel: HTMLElement): void {
-  for (const stream of panel.querySelectorAll<HTMLElement>(
-    '[data-puzzle-path-stream]',
-  )) {
-    stream.remove();
-  }
+  clearPuzzleMovementPreview(panel);
 
   for (const destination of panel.querySelectorAll<HTMLButtonElement>(
     '[data-field-destination]',
@@ -657,12 +652,3 @@ function formatTemplate(
 function capitalize(value: string): string {
   return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
 }
-
-const arrowDirections: Readonly<
-  Partial<Record<string, MagneticFieldDirection>>
-> = {
-  arrowup: 'north',
-  arrowright: 'east',
-  arrowdown: 'south',
-  arrowleft: 'west',
-};

package/src/patterns/PuzzleGrid/PuzzleGrid.astro

@@ -16,6 +16,8 @@ const { class: className, label, rows, columns, ...attrs }: Props = Astro.props;
   role="group"
   aria-label={label}
   data-puzzle-grid
+  data-puzzle-rows={rows}
+  data-puzzle-columns={columns}
   style={`--puzzle-columns: ${columns}; --puzzle-rows: ${rows};`}
 >
   <slot />