@astronox/core 0.5.9 → 0.5.11

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 />

package/src/patterns/PuzzleGrid/keyboard.ts

@@ -0,0 +1,220 @@
+import {
+  getPuzzleMoveTarget,
+  puzzleArrowDirections,
+  type PuzzleDirection,
+} from './movement';
+
+type PuzzleKeyboardOptions = {
+  getPanel: () => HTMLElement | undefined;
+  getSelected: () => HTMLButtonElement | null;
+  select: (control: HTMLButtonElement | null) => void;
+  move: (control: HTMLButtonElement, direction: PuzzleDirection) => void;
+  isLocked?: () => boolean;
+};
+
+export type PuzzleKeyboard = {
+  reset: () => void;
+  destroy: () => void;
+};
+
+export function initPuzzleKeyboard(
+  root: HTMLElement,
+  {
+    getPanel,
+    getSelected,
+    select,
+    move,
+    isLocked = () => false,
+  }: PuzzleKeyboardOptions,
+): PuzzleKeyboard {
+  const controller = new AbortController();
+  const options = { signal: controller.signal };
+  let engaged = false;
+  let released = false;
+  let pointerFocus = false;
+  let focusing = false;
+  let entry: HTMLButtonElement | null = null;
+  const getBoard = (): HTMLElement | null =>
+    getPanel()?.querySelector<HTMLElement>('[data-puzzle-grid]') ?? null;
+  const isComplete = (): boolean =>
+    getPanel()?.dataset.puzzleStatus === 'valid';
+  const getControls = (): HTMLButtonElement[] => [
+    ...(getBoard()?.querySelectorAll<HTMLButtonElement>(
+      '[data-puzzle-control]:not(:disabled)',
+    ) ?? []),
+  ];
+
+  const sync = (): void => {
+    const controls = getControls();
+    const selected = getSelected();
+    entry =
+      (selected && controls.includes(selected) ? selected : null) ??
+      (entry && controls.includes(entry) ? entry : null) ??
+      controls[0] ??
+      null;
+    if (!selected || isComplete()) engaged = false;
+    const board = getBoard();
+    if (board) board.tabIndex = released && !isComplete() ? 0 : -1;
+    for (const control of controls) {
+      control.tabIndex =
+        !released && !isComplete() && control === entry ? 0 : -1;
+      control.setAttribute(
+        'aria-keyshortcuts',
+        'ArrowUp ArrowRight ArrowDown ArrowLeft Tab Shift+Tab Escape Enter Space',
+      );
+    }
+  };
+
+  const focus = (control: HTMLElement): void => {
+    focusing = true;
+    control.focus({ preventScroll: true });
+    focusing = false;
+  };
+
+  const activate = (control: HTMLButtonElement): void => {
+    released = false;
+    entry = control;
+    if (getSelected() !== control) select(control);
+    sync();
+    engaged = true;
+    focus(control);
+  };
+
+  root.addEventListener(
+    'pointerdown',
+    () => {
+      pointerFocus = true;
+    },
+    { ...options, capture: true },
+  );
+  root.addEventListener(
+    'pointercancel',
+    () => {
+      pointerFocus = false;
+    },
+    options,
+  );
+  root.addEventListener(
+    'focusin',
+    (event) => {
+      if (focusing || pointerFocus || isLocked() || isComplete()) return;
+      if (!(event.target instanceof HTMLButtonElement)) return;
+      if (getControls().includes(event.target)) activate(event.target);
+    },
+    options,
+  );
+  root.addEventListener(
+    'focusout',
+    (event) => {
+      if (
+        event.relatedTarget instanceof Node &&
+        getBoard()?.contains(event.relatedTarget)
+      )
+        return;
+      engaged = false;
+      released = false;
+      pointerFocus = false;
+      select(null);
+      sync();
+    },
+    options,
+  );
+  root.addEventListener(
+    'click',
+    (event) => {
+      if (!(event.target instanceof Element) || isLocked()) return;
+      const selected = getSelected();
+      if (selected && getPuzzleMoveTarget(getPanel(), event)) focus(selected);
+    },
+    { ...options, capture: true },
+  );
+  root.addEventListener(
+    'click',
+    (event) => {
+      pointerFocus = false;
+      if (
+        !(event.target instanceof Node) ||
+        !getBoard()?.contains(event.target)
+      )
+        return;
+      const selected = getSelected();
+      if (selected && !isComplete()) {
+        released = false;
+        engaged = true;
+        sync();
+        focus(selected);
+      } else if (getBoard()?.contains(document.activeElement)) {
+        released = true;
+        sync();
+        const board = getBoard();
+        if (board) focus(board);
+      } else sync();
+    },
+    options,
+  );
+  root.addEventListener(
+    'keydown',
+    (event) => {
+      pointerFocus = false;
+      if (event.altKey || event.ctrlKey || event.metaKey) return;
+      const board = getBoard();
+      if (!(event.target instanceof Node) || !board?.contains(event.target))
+        return;
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        event.stopPropagation();
+        engaged = false;
+        released = true;
+        select(null);
+        sync();
+        focus(board);
+        return;
+      }
+      if (isComplete()) return;
+      const direction = puzzleArrowDirections[event.key];
+      if (event.key === 'Tab') {
+        if (!engaged) return;
+        event.preventDefault();
+        if (isLocked()) return;
+        const controls = getControls();
+        if (!controls.length) return;
+        const index = controls.indexOf(getSelected() ?? entry ?? controls[0]);
+        const next =
+          (index + (event.shiftKey ? -1 : 1) + controls.length) %
+          controls.length;
+        activate(controls[next]);
+      } else if (isLocked()) {
+        if (direction || event.key === 'Enter' || event.key === ' ')
+          event.preventDefault();
+      } else if (direction) {
+        event.preventDefault();
+        const selected = getSelected() ?? entry ?? getControls()[0];
+        if (!selected) return;
+        activate(selected);
+        move(selected, direction);
+        sync();
+      } else if (
+        event.target === board &&
+        (event.key === 'Enter' || event.key === ' ')
+      ) {
+        event.preventDefault();
+        const selected = entry ?? getControls()[0];
+        if (selected) activate(selected);
+      }
+    },
+    options,
+  );
+  root.addEventListener('puzzle:change', sync, options);
+  root.addEventListener('puzzle:complete', sync, options);
+  sync();
+  return {
+    reset: () => {
+      engaged = false;
+      released = false;
+      entry = null;
+      pointerFocus = false;
+      sync();
+    },
+    destroy: () => controller.abort(),
+  };
+}

package/src/patterns/PuzzleGrid/movement.css

@@ -1,3 +1,7 @@
+.puzzle-grid__cell[data-puzzle-move-direction]:not(:disabled) {
+  cursor: pointer;
+}
+
 .puzzle-grid__path-stream {
   --puzzle-path-rotation: 0deg;
 

package/src/patterns/PuzzleGrid/movement.ts

@@ -14,7 +14,60 @@ export type PuzzleDrag = {
   moved: boolean;
 };
 
-type Direction = 'north' | 'east' | 'south' | 'west';
+export type PuzzleDirection = 'north' | 'east' | 'south' | 'west';
+
+export const puzzleArrowDirections: Readonly<
+  Partial<Record<string, PuzzleDirection>>
+> = {
+  ArrowUp: 'north',
+  ArrowRight: 'east',
+  ArrowDown: 'south',
+  ArrowLeft: 'west',
+};
+
+export function getPuzzleMoveTarget(
+  panel: HTMLElement | undefined,
+  event: MouseEvent,
+): { pieceId: string; direction: PuzzleDirection } | null {
+  const target = event.target;
+  if (!(target instanceof Element) || !panel?.contains(target)) return null;
+  let cell = target.closest<HTMLButtonElement>('[data-puzzle-move-direction]');
+  if (
+    !cell &&
+    target instanceof HTMLElement &&
+    target.matches('[data-puzzle-grid]')
+  ) {
+    const bounds = target.getBoundingClientRect();
+    const x = event.clientX - bounds.left - target.clientLeft;
+    const y = event.clientY - bounds.top - target.clientTop;
+    if (x < 0 || y < 0 || x >= target.clientWidth || y >= target.clientHeight)
+      return null;
+    const column = Math.floor(
+      (x * Number(target.dataset.puzzleColumns)) / target.clientWidth,
+    );
+    const row = Math.floor(
+      (y * Number(target.dataset.puzzleRows)) / target.clientHeight,
+    );
+    cell = target.querySelector<HTMLButtonElement>(
+      `[data-puzzle-move-direction][data-cell-row="${row}"][data-cell-column="${column}"]`,
+    );
+  }
+  if (!cell || cell.disabled) return null;
+  const pieceId = cell.dataset.puzzleMovePiece;
+  const direction = cell.dataset.puzzleMoveDirection as PuzzleDirection;
+  return pieceId ? { pieceId, direction } : null;
+}
+
+export function clearPuzzleMovementPreview(panel: HTMLElement): void {
+  for (const stream of panel.querySelectorAll('[data-puzzle-path-stream]'))
+    stream.remove();
+  for (const cell of panel.querySelectorAll<HTMLElement>(
+    '[data-puzzle-move-direction]',
+  )) {
+    delete cell.dataset.puzzleMoveDirection;
+    delete cell.dataset.puzzleMovePiece;
+  }
+}
 
 const pathChevronsPerCell = 3;
 const pathDurationPerCellMs = 2100;
@@ -78,7 +131,7 @@ export function findDirectionalDropDestination(
   deltaX: number,
   deltaY: number,
 ): HTMLButtonElement | null {
-  let direction: Direction;
+  let direction: PuzzleDirection;
   if (Math.abs(deltaX) >= Math.abs(deltaY)) {
     direction = deltaX >= 0 ? 'east' : 'west';
   } else {
@@ -99,12 +152,23 @@ export function renderPathStream(
   movement: {
     from: { row: number; column: number };
     to: { row: number; column: number };
-    direction: Direction;
+    direction: PuzzleDirection;
   },
+  pieceId: string,
 ): void {
   const rowDistance = movement.to.row - movement.from.row;
   const columnDistance = movement.to.column - movement.from.column;
   const cellDistance = Math.abs(rowDistance) + Math.abs(columnDistance);
+  for (let step = 1; step <= cellDistance; step += 1) {
+    const row = movement.from.row + Math.sign(rowDistance) * step;
+    const column = movement.from.column + Math.sign(columnDistance) * step;
+    const cell = board.querySelector<HTMLButtonElement>(
+      `[data-puzzle-cell][data-cell-row="${row}"][data-cell-column="${column}"]`,
+    );
+    if (!cell || cell.disabled) continue;
+    cell.dataset.puzzleMoveDirection = movement.direction;
+    cell.dataset.puzzleMovePiece = pieceId;
+  }
   const chevronCount = pathChevronsPerCell * cellDistance;
   const stream = document.createElement('span');
   stream.className = 'puzzle-grid__path-stream';

package/src/patterns/PuzzleGrid/selectionDismissal.ts

@@ -1,6 +1,6 @@
 type PuzzleSelectionDismissalOptions = {
   dismiss: () => void;
-  isSelectionTarget: (target: Element) => boolean;
+  isSelectionTarget: (target: Element, event: PointerEvent) => boolean;
 };
 
 export function initPuzzleSelectionDismissal(
@@ -15,7 +15,7 @@ export function initPuzzleSelectionDismissal(
       const target = event.target;
       if (!(target instanceof Node)) return;
       const element = target instanceof Element ? target : target.parentElement;
-      if (element && isSelectionTarget(element)) return;
+      if (element && isSelectionTarget(element, event)) return;
 
       dismiss();
       const focused = document.activeElement;

package/src/patterns/SlidingPuzzle/SlidingPuzzle.astro

@@ -170,6 +170,7 @@ const {
             type="button"
             aria-label={labels.piece}
             aria-pressed="false"
+            data-puzzle-control
             data-sliding-piece
             style={`--piece-row: ${puzzle.start.row + 1}; --piece-column: ${puzzle.start.column + 1};`}
           >