@astronox/core 0.1.0

package/src/patterns/SpriteProjectilePreview/spriteProjectilePreviewController.ts

@@ -0,0 +1,586 @@
+import type {
+  SpriteProjectilePreviewModel,
+  SpriteSheetAnimation,
+} from './contracts';
+
+const initializedAttribute = 'data-sprite-projectile-preview-initialized';
+const intervalChangeEvent = 'sprite-projectile-preview:interval-change';
+const canvasSelector = '[data-sprite-projectile-preview-canvas]';
+const configSelector = '[data-sprite-projectile-preview-config]';
+const maximumDevicePixelRatio = 2;
+const maximumCatchUpProjectiles = 8;
+const actorCenterRatio = 1 / 3;
+const scaleReferenceFootprintRatio = 0.45;
+const scenePaddingRatio = 0.08;
+const noop = (): void => undefined;
+
+type LoadedAnimation = {
+  image: HTMLImageElement;
+  model: SpriteSheetAnimation;
+  frameWidth: number;
+  frameHeight: number;
+};
+
+type ActiveProjectile = {
+  launchedAt: number;
+};
+
+type AnimationPlacement = {
+  visibleCenterX: number;
+  visibleCenterY: number;
+};
+
+type SceneLayout = {
+  scale: number;
+  actor: AnimationPlacement;
+  projectile?: {
+    startCenterX: number;
+    visibleCenterY: number;
+    visibleWidth: number;
+  };
+};
+
+export function setSpriteProjectilePreviewInterval(
+  root: HTMLElement,
+  intervalMs: number,
+): void {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) return;
+
+  root.dataset.spriteProjectilePreviewInterval = String(intervalMs);
+  root.dispatchEvent(
+    new CustomEvent<number>(intervalChangeEvent, {
+      detail: intervalMs,
+    }),
+  );
+}
+
+export function initSpriteProjectilePreview(root: HTMLElement): () => void {
+  if (root.getAttribute(initializedAttribute) === 'true') return noop;
+
+  const canvas = root.querySelector<HTMLCanvasElement>(canvasSelector);
+  const config = root.querySelector<HTMLScriptElement>(configSelector);
+  const context = canvas?.getContext('2d');
+  const initialModel = readModel(config?.textContent);
+
+  if (!canvas || !context || !initialModel) return noop;
+
+  root.setAttribute(initializedAttribute, 'true');
+
+  const requestedInterval = Number(
+    root.dataset.spriteProjectilePreviewInterval,
+  );
+  let model =
+    initialModel.projectile &&
+    Number.isFinite(requestedInterval) &&
+    requestedInterval > 0
+      ? {
+          ...initialModel,
+          projectile: {
+            ...initialModel.projectile,
+            intervalMs: requestedInterval,
+          },
+        }
+      : initialModel;
+  let actor: LoadedAnimation | null = null;
+  let projectile: LoadedAnimation | null = null;
+  let logicalWidth = 1;
+  let logicalHeight = 1;
+  let animationFrame: number | null = null;
+  let animationStartedAt = 0;
+  let lastLaunchAt: number | null = null;
+  let activeProjectiles: ActiveProjectile[] = [];
+  let isDestroyed = false;
+  let isIntersecting = !('IntersectionObserver' in window);
+  let isDocumentVisible = !document.hidden;
+  const reducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+  const stop = (): void => {
+    if (animationFrame !== null) {
+      window.cancelAnimationFrame(animationFrame);
+      animationFrame = null;
+    }
+    lastLaunchAt = null;
+    activeProjectiles = [];
+  };
+
+  const resize = (): void => {
+    const bounds = canvas.getBoundingClientRect();
+    const nextWidth = Math.max(1, bounds.width);
+    const nextHeight = Math.max(1, bounds.height);
+    const pixelRatio = Math.min(
+      maximumDevicePixelRatio,
+      Math.max(1, window.devicePixelRatio || 1),
+    );
+    const physicalWidth = Math.max(1, Math.round(nextWidth * pixelRatio));
+    const physicalHeight = Math.max(1, Math.round(nextHeight * pixelRatio));
+
+    logicalWidth = nextWidth;
+    logicalHeight = nextHeight;
+
+    const hasNewCanvasSize =
+      canvas.width !== physicalWidth || canvas.height !== physicalHeight;
+
+    if (hasNewCanvasSize) {
+      canvas.width = physicalWidth;
+      canvas.height = physicalHeight;
+    }
+
+    context.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
+    context.imageSmoothingEnabled = false;
+
+    if (
+      actor &&
+      (hasNewCanvasSize || reducedMotion.matches || animationFrame === null)
+    ) {
+      drawStaticScene();
+    }
+  };
+
+  const getLayout = (): SceneLayout => {
+    if (!actor) {
+      throw new Error('Missing sprite preview actor');
+    }
+
+    const padding = Math.min(logicalWidth, logicalHeight) * scenePaddingRatio;
+    const visibleCenterX = logicalWidth * (projectile ? actorCenterRatio : 0.5);
+    const actorAvailableWidth = projectile
+      ? (visibleCenterX - padding) * 2
+      : logicalWidth - padding * 2;
+    const targetFootprint = logicalHeight * scaleReferenceFootprintRatio;
+    const sceneScale = getDisplayScale(
+      model.scaleReference.width,
+      model.scaleReference.height,
+      targetFootprint,
+      targetFootprint,
+      Math.max(1, actorAvailableWidth),
+      Math.max(1, logicalHeight - padding * 2),
+    );
+    const visibleActorWidth =
+      actor.model.contentBounds.width * actor.model.baseScale * sceneScale;
+    const visibleCenterY = Math.round(logicalHeight / 2);
+    const layout: SceneLayout = {
+      scale: sceneScale,
+      actor: {
+        visibleCenterX,
+        visibleCenterY,
+      },
+    };
+
+    if (projectile) {
+      const visibleProjectileWidth =
+        projectile.model.contentBounds.width *
+        projectile.model.baseScale *
+        sceneScale;
+
+      layout.projectile = {
+        startCenterX:
+          visibleCenterX + visibleActorWidth / 2 + visibleProjectileWidth / 2,
+        visibleCenterY,
+        visibleWidth: visibleProjectileWidth,
+      };
+    }
+
+    return layout;
+  };
+
+  const clear = (): void => {
+    context.clearRect(0, 0, logicalWidth, logicalHeight);
+  };
+
+  const drawStaticScene = (): void => {
+    if (!actor) return;
+
+    clear();
+    const layout = getLayout();
+    drawAnimation(
+      context,
+      actor,
+      0,
+      layout.actor,
+      layout.scale * actor.model.baseScale,
+    );
+
+    if (projectile && layout.projectile) {
+      drawAnimation(
+        context,
+        projectile,
+        0,
+        {
+          visibleCenterX: layout.projectile.startCenterX,
+          visibleCenterY: layout.projectile.visibleCenterY,
+        },
+        layout.scale * projectile.model.baseScale,
+      );
+    }
+  };
+
+  const render = (timestamp: number): void => {
+    animationFrame = null;
+    if (
+      isDestroyed ||
+      !actor ||
+      !isIntersecting ||
+      !isDocumentVisible ||
+      reducedMotion.matches
+    ) {
+      return;
+    }
+
+    if (animationStartedAt === 0) animationStartedAt = timestamp;
+
+    const layout = getLayout();
+    clear();
+    drawAnimation(
+      context,
+      actor,
+      timestamp - animationStartedAt,
+      layout.actor,
+      layout.scale * actor.model.baseScale,
+    );
+
+    const projectileModel = model.projectile;
+    const loadedProjectile = projectile;
+    const projectileLayout = layout.projectile;
+
+    if (projectileModel && loadedProjectile && projectileLayout) {
+      if (lastLaunchAt === null) {
+        lastLaunchAt = timestamp - projectileModel.intervalMs;
+      }
+
+      const launches = Math.min(
+        maximumCatchUpProjectiles,
+        Math.floor((timestamp - lastLaunchAt) / projectileModel.intervalMs),
+      );
+
+      for (let index = 0; index < launches; index += 1) {
+        lastLaunchAt += projectileModel.intervalMs;
+        activeProjectiles.push({ launchedAt: lastLaunchAt });
+      }
+
+      activeProjectiles = activeProjectiles.filter((activeProjectile) => {
+        const elapsed = timestamp - activeProjectile.launchedAt;
+        const progress = elapsed / projectileModel.travelDurationMs;
+        const travelDistance =
+          logicalWidth -
+          projectileLayout.startCenterX +
+          projectileLayout.visibleWidth / 2;
+        const visibleCenterX =
+          projectileLayout.startCenterX + travelDistance * progress;
+        const isInsideScene = progress < 1;
+
+        if (isInsideScene) {
+          drawAnimation(
+            context,
+            loadedProjectile,
+            elapsed,
+            {
+              visibleCenterX,
+              visibleCenterY: projectileLayout.visibleCenterY,
+            },
+            layout.scale * loadedProjectile.model.baseScale,
+          );
+        }
+
+        return isInsideScene;
+      });
+    }
+
+    animationFrame = window.requestAnimationFrame(render);
+  };
+
+  const start = (): void => {
+    if (
+      animationFrame !== null ||
+      !actor ||
+      !isIntersecting ||
+      !isDocumentVisible ||
+      reducedMotion.matches
+    ) {
+      if (actor && reducedMotion.matches) drawStaticScene();
+      return;
+    }
+
+    animationStartedAt = 0;
+    lastLaunchAt = null;
+    activeProjectiles = [];
+    animationFrame = window.requestAnimationFrame(render);
+  };
+
+  const updatePlayback = (): void => {
+    if (reducedMotion.matches || !isIntersecting || !isDocumentVisible) {
+      stop();
+      if (actor) drawStaticScene();
+      return;
+    }
+
+    start();
+  };
+
+  const handleVisibilityChange = (): void => {
+    isDocumentVisible = !document.hidden;
+    updatePlayback();
+  };
+
+  const handleReducedMotionChange = (): void => {
+    updatePlayback();
+  };
+
+  const handleIntervalChange = (event: Event): void => {
+    const interval = event as CustomEvent<number>;
+    if (!model.projectile || interval.detail <= 0) return;
+
+    model = {
+      ...model,
+      projectile: {
+        ...model.projectile,
+        intervalMs: interval.detail,
+      },
+    };
+    lastLaunchAt = null;
+    activeProjectiles = [];
+  };
+
+  const resizeObserver =
+    'ResizeObserver' in window ? new ResizeObserver(() => resize()) : null;
+  const intersectionObserver =
+    'IntersectionObserver' in window
+      ? new IntersectionObserver((entries) => {
+          isIntersecting = entries.some((entry) => entry.isIntersecting);
+          updatePlayback();
+        })
+      : null;
+  const handleWindowResize = (): void => resize();
+
+  if (resizeObserver) {
+    resizeObserver.observe(root);
+  } else {
+    window.addEventListener('resize', handleWindowResize);
+  }
+  intersectionObserver?.observe(root);
+  document.addEventListener('visibilitychange', handleVisibilityChange);
+  reducedMotion.addEventListener('change', handleReducedMotionChange);
+  root.addEventListener(intervalChangeEvent, handleIntervalChange);
+  resize();
+
+  const projectilePromise = model.projectile
+    ? loadAnimation(model.projectile).catch(() => null)
+    : Promise.resolve(null);
+
+  void Promise.all([loadAnimation(model.actor), projectilePromise])
+    .then(([loadedActor, loadedProjectile]) => {
+      if (isDestroyed) return;
+
+      actor = loadedActor;
+      projectile = loadedProjectile;
+      resize();
+      updatePlayback();
+    })
+    .catch(() => {
+      if (!isDestroyed) root.dataset.spriteProjectilePreviewState = 'error';
+    });
+
+  return () => {
+    isDestroyed = true;
+    stop();
+    resizeObserver?.disconnect();
+    intersectionObserver?.disconnect();
+    window.removeEventListener('resize', handleWindowResize);
+    document.removeEventListener('visibilitychange', handleVisibilityChange);
+    reducedMotion.removeEventListener('change', handleReducedMotionChange);
+    root.removeEventListener(intervalChangeEvent, handleIntervalChange);
+    root.removeAttribute(initializedAttribute);
+    delete root.dataset.spriteProjectilePreviewState;
+  };
+}
+
+function drawAnimation(
+  context: CanvasRenderingContext2D,
+  animation: LoadedAnimation,
+  elapsedMs: number,
+  destination: AnimationPlacement,
+  scale: number,
+): void {
+  const frame =
+    Math.floor(elapsedMs / animation.model.frameDurationMs) %
+    animation.model.frames;
+  const sourceX = frame * animation.frameWidth;
+  const sourceY = animation.model.row * animation.frameHeight;
+  const contentBounds = animation.model.contentBounds;
+  const destinationX =
+    destination.visibleCenterX -
+    (contentBounds.x + contentBounds.width / 2) * scale;
+  const destinationY =
+    destination.visibleCenterY -
+    (contentBounds.y + contentBounds.height / 2) * scale;
+
+  context.drawImage(
+    animation.image,
+    sourceX,
+    sourceY,
+    animation.frameWidth,
+    animation.frameHeight,
+    snapPixelPosition(destinationX, scale),
+    snapPixelPosition(destinationY, scale),
+    animation.frameWidth * scale,
+    animation.frameHeight * scale,
+  );
+}
+
+function snapPixelPosition(value: number, scale: number): number {
+  return Number.isInteger(scale) ? Math.round(value) : value;
+}
+
+function getDisplayScale(
+  sourceWidth: number,
+  sourceHeight: number,
+  targetWidth: number,
+  targetHeight: number,
+  maximumWidth: number,
+  maximumHeight: number,
+): number {
+  const targetScale = Math.min(
+    targetWidth / sourceWidth,
+    targetHeight / sourceHeight,
+  );
+  const maximumScale = Math.min(
+    maximumWidth / sourceWidth,
+    maximumHeight / sourceHeight,
+  );
+
+  if (maximumScale < 1) return Math.max(0.1, maximumScale);
+
+  return Math.min(
+    Math.max(1, Math.round(targetScale)),
+    Math.floor(maximumScale),
+  );
+}
+
+async function loadAnimation(
+  model: SpriteSheetAnimation,
+): Promise<LoadedAnimation> {
+  const image = new Image();
+  image.decoding = 'async';
+
+  await new Promise<void>((resolve, reject) => {
+    image.addEventListener('load', () => resolve(), { once: true });
+    image.addEventListener('error', () => reject(new Error(model.src)), {
+      once: true,
+    });
+    image.src = model.src;
+  });
+
+  return {
+    image,
+    model,
+    frameWidth: image.naturalWidth / model.frames,
+    frameHeight: image.naturalHeight / model.rows,
+  };
+}
+
+function readModel(value: string | null | undefined) {
+  if (!value) return null;
+
+  try {
+    const candidate: unknown = JSON.parse(value);
+    return isPreviewModel(candidate) ? candidate : null;
+  } catch {
+    return null;
+  }
+}
+
+function isPreviewModel(value: unknown): value is SpriteProjectilePreviewModel {
+  if (!isRecord(value) || typeof value.label !== 'string') return false;
+  if (!isScaleReference(value.scaleReference)) return false;
+  if (!isAnimation(value.actor)) return false;
+
+  return value.projectile === undefined || isProjectile(value.projectile);
+}
+
+function isProjectile(
+  value: unknown,
+): value is NonNullable<SpriteProjectilePreviewModel['projectile']> {
+  if (!isRecord(value)) return false;
+
+  const { intervalMs, travelDurationMs } = value;
+
+  return (
+    isAnimation(value) &&
+    isPositiveNumber(intervalMs) &&
+    isPositiveNumber(travelDurationMs)
+  );
+}
+
+function isScaleReference(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isPositiveNumber(value.width) &&
+    isPositiveNumber(value.height)
+  );
+}
+
+function isAnimation(value: unknown): value is SpriteSheetAnimation {
+  if (
+    !isRecord(value) ||
+    !isPositiveNumber(value.width) ||
+    !isPositiveNumber(value.height) ||
+    !isPositiveNumber(value.baseScale) ||
+    !isPositiveInteger(value.frames) ||
+    !isPositiveInteger(value.rows)
+  ) {
+    return false;
+  }
+
+  const frameWidth = value.width / value.frames;
+  const frameHeight = value.height / value.rows;
+
+  return (
+    typeof value.src === 'string' &&
+    value.src.length > 0 &&
+    isNonNegativeInteger(value.row) &&
+    value.row < value.rows &&
+    isPositiveNumber(value.frameDurationMs) &&
+    isContentBounds(value.contentBounds, frameWidth, frameHeight)
+  );
+}
+
+function isContentBounds(
+  value: unknown,
+  frameWidth: number,
+  frameHeight: number,
+): boolean {
+  if (
+    !isRecord(value) ||
+    !isNonNegativeNumber(value.x) ||
+    !isNonNegativeNumber(value.y) ||
+    !isPositiveNumber(value.width) ||
+    !isPositiveNumber(value.height)
+  ) {
+    return false;
+  }
+
+  const geometryTolerance = 0.000001;
+  return (
+    value.x + value.width <= frameWidth + geometryTolerance &&
+    value.y + value.height <= frameHeight + geometryTolerance
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function isPositiveNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+
+function isNonNegativeNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+
+function isPositiveInteger(value: unknown): value is number {
+  return isPositiveNumber(value) && Number.isInteger(value);
+}
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return isNonNegativeNumber(value) && Number.isInteger(value);
+}

package/src/patterns/StageFlow/StageFlow.astro

@@ -0,0 +1,57 @@
+---
+import type { HTMLAttributes } from 'astro/types';
+import type { Tone } from '../../theme/contracts';
+import type { StageFlowStep } from '../../display/contracts';
+import StageFlowConnector from './StageFlowConnector.astro';
+import StageFlowStepItem from './StageFlowStep.astro';
+
+type Props = HTMLAttributes<'nav'> & {
+  label: string;
+  steps: readonly StageFlowStep[];
+  emptyLabel: string;
+  tone?: Tone;
+};
+
+const {
+  class: className,
+  'data-tone': dataTone,
+  label,
+  steps,
+  emptyLabel,
+  tone,
+  ...attrs
+}: Props = Astro.props;
+const resolvedTone = tone ?? dataTone;
+---
+
+{
+  steps.length > 0 ? (
+    <nav
+      {...attrs}
+      class:list={['stage-flow', className]}
+      data-widget="stage-flow"
+      data-tone={resolvedTone}
+      aria-label={label}
+    >
+      <div class="stage-flow__viewport">
+        <ol class="stage-flow__list">
+          {steps.map((step, index) => (
+            <>
+              {index > 0 ? <StageFlowConnector /> : null}
+              <StageFlowStepItem options={step.options} />
+            </>
+          ))}
+        </ol>
+      </div>
+    </nav>
+  ) : (
+    <p
+      {...attrs}
+      class:list={['stage-flow__empty', className]}
+      data-widget="stage-flow"
+      data-tone={resolvedTone}
+    >
+      {emptyLabel}
+    </p>
+  )
+}

package/src/patterns/StageFlow/StageFlow.css

@@ -0,0 +1,54 @@
+.stage-flow {
+  container-type: inline-size;
+  display: grid;
+  min-inline-size: 0;
+  color: var(--nox-text);
+}
+
+.stage-flow__viewport {
+  min-inline-size: 0;
+  overflow-x: auto;
+  overflow-y: hidden;
+  overscroll-behavior-inline: contain;
+}
+
+.stage-flow__list {
+  --stage-flow-stage-min-inline-size: 8rem;
+  --stage-flow-media-size: 6.25rem;
+  --stage-flow-connector-inline-size: 2.5rem;
+  --stage-flow-alternative-inline-size: 1.5rem;
+
+  display: grid;
+  inline-size: max-content;
+  min-inline-size: 100%;
+  align-items: center;
+  justify-content: center;
+  grid-auto-columns: max-content;
+  grid-auto-flow: column;
+  gap: var(--nox-space-3);
+  list-style: none;
+  margin: 0;
+  padding: var(--nox-space-4) var(--nox-space-3);
+}
+
+.stage-flow__item {
+  display: grid;
+  min-inline-size: 0;
+}
+
+.stage-flow__empty {
+  margin: 0;
+  color: var(--nox-text-muted);
+}
+
+@container (width < 32rem) {
+  .stage-flow__list {
+    --stage-flow-stage-min-inline-size: 7.25rem;
+    --stage-flow-media-size: 5.5rem;
+    --stage-flow-connector-inline-size: 2rem;
+    --stage-flow-alternative-inline-size: 1.25rem;
+
+    padding-inline: var(--nox-space-2);
+    gap: var(--nox-space-2);
+  }
+}

package/src/patterns/StageFlow/StageFlowAlternative.astro

@@ -0,0 +1,23 @@
+<li class="stage-flow__item stage-flow__item--alternative" aria-hidden="true">
+  <svg
+    class="stage-flow__symbol stage-flow__alternative"
+    viewBox="0 0 20 44"
+    fill="none"
+    focusable="false"
+  >
+    <path
+      class="stage-flow__symbol-outline"
+      d="M14 6.5 6 37.5"
+      stroke="currentColor"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="5.5"></path>
+    <path
+      class="stage-flow__symbol-line"
+      d="M14 6.5 6 37.5"
+      stroke="currentColor"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      stroke-width="2.75"></path>
+  </svg>
+</li>