@jjlmoya/utils-tabletop 1.3.0

package/src/tool/board-game-timer/modules/TimerEngineBase.ts

@@ -0,0 +1,49 @@
+import type { TimerState, TimerEventCallback, TimeControlMode } from '../types';
+
+export class TimerEngineBase {
+  protected timers = new Map<string, TimerState>();
+  protected expiredCallbacks: TimerEventCallback[] = [];
+  protected tickCallbacks: TimerEventCallback[] = [];
+  protected warningCallbacks: TimerEventCallback[] = [];
+  protected activeId: string | undefined;
+
+  protected currentMode: TimeControlMode = 'normal';
+  protected currentIncrement = 0;
+  protected currentDelay = 0;
+
+  public getTimer(id: string) {
+    return this.timers.get(id);
+  }
+
+  public getAllTimers() {
+    return Array.from(this.timers.values());
+  }
+
+  public onExpired(cb: TimerEventCallback) {
+    this.expiredCallbacks.push(cb);
+  }
+
+  public onTick(cb: TimerEventCallback) {
+    this.tickCallbacks.push(cb);
+  }
+
+  public onWarning(cb: TimerEventCallback) {
+    this.warningCallbacks.push(cb);
+  }
+
+  public setMode(mode: TimeControlMode) {
+    this.currentMode = mode;
+  }
+
+  public setIncrement(seconds: number) {
+    this.currentIncrement = seconds;
+  }
+
+  public setDelay(seconds: number) {
+    this.currentDelay = seconds;
+  }
+
+  public get activeTimerId() {
+    return this.activeId;
+  }
+}

package/src/tool/board-game-timer/modules/TimerEngineClock.ts

@@ -0,0 +1,127 @@
+import type { TimerState, TimerConfig } from '../types';
+import { TimerEngineBase } from './TimerEngineBase';
+
+export class TimerEngineClock extends TimerEngineBase {
+  protected intervalId: ReturnType<typeof setInterval> | undefined;
+  protected lastWarningId: string | undefined;
+  protected delayRemaining = 0;
+  protected config: TimerConfig | undefined;
+
+  constructor(config?: TimerConfig) {
+    super();
+    this.config = config;
+    this.currentMode = config?.mode ?? 'normal';
+    this.currentIncrement = config?.increment ?? 0;
+    this.currentDelay = config?.delay ?? 0;
+  }
+
+  protected getNow(): number {
+    return Date.now();
+  }
+
+  protected notifyTick(id: string) {
+    const t = this.timers.get(id);
+    if (!t) return;
+    this.tickCallbacks.forEach(cb => cb(id, t.remaining));
+    this.checkWarning(t);
+  }
+
+  private checkWarning(t: TimerState) {
+    const limit = this.config?.warningTime ?? 30;
+    if (t.remaining > limit) {
+      this.resetWarning(t.id);
+      return;
+    }
+    if (t.status === 'running' && t.remaining > 0 && this.lastWarningId !== t.id) {
+      this.triggerWarning(t);
+    }
+  }
+
+  private resetWarning(id: string) {
+    if (this.lastWarningId === id) {
+      this.lastWarningId = undefined;
+    }
+  }
+
+  private triggerWarning(t: TimerState) {
+    this.lastWarningId = t.id;
+    this.warningCallbacks.forEach(cb => cb(t.id, t.remaining));
+  }
+
+  protected notifyExpired(id: string) {
+    const t = this.timers.get(id);
+    if (t) {
+      this.expiredCallbacks.forEach(cb => cb(id, t.remaining));
+    }
+  }
+
+  protected processTick() {
+    if (!this.activeId) return;
+    const t = this.timers.get(this.activeId);
+    if (!t) return;
+    const now = this.getNow();
+    const elapsed = (now - (t._lastTickAt ?? now)) / 1000;
+    t._lastTickAt = now;
+    if (t.status === 'running') {
+      this.tickRunning(t, elapsed);
+    } else if (t.status === 'overtime') {
+      this.tickOvertime(t, elapsed);
+    }
+  }
+
+  private tickRunning(t: TimerState, elapsed: number) {
+    if (this.delayRemaining > 0) {
+      this.delayRemaining = Math.max(0, this.delayRemaining - elapsed);
+      t._lastTickAt = this.getNow();
+      this.notifyTick(t.id);
+      return;
+    }
+    if (elapsed >= t.remaining) {
+      this.handleExpiration(t, elapsed);
+    } else {
+      this.handleCountdown(t, elapsed);
+    }
+  }
+
+  private handleExpiration(t: TimerState, elapsed: number) {
+    t.overtime += elapsed - t.remaining;
+    t.remaining = 0;
+    t.status = 'overtime';
+    this.notifyTick(t.id);
+    this.notifyExpired(t.id);
+  }
+
+  private handleCountdown(t: TimerState, elapsed: number) {
+    t.remaining = Math.max(0, +(t.remaining - elapsed).toFixed(3));
+    this.notifyTick(t.id);
+    if (this.currentMode === 'hourglass') {
+      this.applyHourglass(elapsed);
+    }
+  }
+
+  private applyHourglass(elapsed: number) {
+    this.timers.forEach((other, id) => {
+      if (id !== this.activeId && other.status !== 'expired') {
+        other.remaining = +(other.remaining + elapsed).toFixed(3);
+        this.notifyTick(id);
+      }
+    });
+  }
+
+  private tickOvertime(t: TimerState, elapsed: number) {
+    t.overtime = +(t.overtime + elapsed).toFixed(3);
+    this.notifyTick(t.id);
+  }
+
+  protected startClock() {
+    this.stopClock();
+    this.intervalId = setInterval(() => this.processTick(), this.config?.tickInterval ?? 100);
+  }
+
+  protected stopClock() {
+    if (this.intervalId !== undefined) {
+      clearInterval(this.intervalId);
+      this.intervalId = undefined;
+    }
+  }
+}

package/src/tool/board-game-timer/modules/TimerStateHelper.ts

@@ -0,0 +1,55 @@
+import type { TimerState } from '../types';
+
+export function createTimerState(id: string, label: string, duration: number): TimerState {
+  return {
+    id,
+    label,
+    initialDuration: duration,
+    remaining: duration,
+    status: 'idle',
+    _lastTickAt: 0,
+    roundsPlayed: 0,
+    overtime: 0,
+  };
+}
+
+export function addTimerTime(t: TimerState, seconds: number) {
+  if (t.status === 'overtime') {
+    const remainingOvertime = t.overtime - seconds;
+    if (remainingOvertime <= 0) {
+      t.remaining = Math.abs(remainingOvertime);
+      t.overtime = 0;
+      t.status = 'paused';
+    } else {
+      t.overtime = +remainingOvertime.toFixed(3);
+    }
+  } else {
+    t.remaining = Math.max(0, +(t.remaining + seconds).toFixed(3));
+    if (t.status === 'expired' && t.remaining > 0) {
+      t.status = 'paused';
+    }
+  }
+}
+
+export function removeTimerTime(t: TimerState, seconds: number, notifyExpired: () => void) {
+  if (t.status === 'overtime') {
+    t.overtime = +(t.overtime + seconds).toFixed(3);
+  } else if (t.status === 'running') {
+    if (seconds >= t.remaining) {
+      t.overtime = +(seconds - t.remaining + (t.overtime || 0)).toFixed(3);
+      t.remaining = 0;
+      t.status = 'overtime';
+      notifyExpired();
+    } else {
+      t.remaining = Math.max(0, +(t.remaining - seconds).toFixed(3));
+    }
+  } else {
+    if (seconds >= t.remaining) {
+      t.remaining = 0;
+      t.status = 'expired';
+      notifyExpired();
+    } else {
+      t.remaining = Math.max(0, +(t.remaining - seconds).toFixed(3));
+    }
+  }
+}

package/src/tool/board-game-timer/modules/particles.ts

@@ -0,0 +1,108 @@
+export function spawnParticle(options: { parent: HTMLElement; text: string; x: number; y: number; variant?: 'accent' | 'warning' | 'danger' | 'success' }) {
+  const el = document.createElement('div');
+  el.className = `timer-particle timer-particle-${options.variant ?? 'accent'}`;
+  el.textContent = options.text;
+  el.style.left = `${options.x}px`;
+  el.style.top = `${options.y}px`;
+  const container = options.parent.closest('.timer-player-card') || options.parent.closest('.timer-single-display') || options.parent.closest('.timer-main-card') || options.parent;
+  container.appendChild(el);
+  setTimeout(() => el.remove(), 900);
+}
+
+export function spawnTimerPop(parent: HTMLElement, text: string, variant: 'accent' | 'warning' | 'danger' | 'success' = 'accent') {
+  const el = document.createElement('div');
+  el.className = `timer-pop-burst`;
+  el.textContent = text;
+  el.style.color = `var(--color-timer-${variant})`;
+  parent.appendChild(el);
+  setTimeout(() => el.remove(), 1200);
+}
+
+export function spawnExpiredBurst(parent: HTMLElement) {
+  const symbols = ['!', '!!', '!!!', '!!'];
+  const colors = ['#ef4444', '#dc2626', '#b91c1c', '#ef4444'];
+  for (let i = 0; i < 8; i++) {
+    const el = document.createElement('div');
+    el.className = 'timer-expired-particle';
+    el.textContent = symbols[i % symbols.length]!;
+    const angle = (i / 8) * 360;
+    const dist = 60 + Math.random() * 60;
+    const rad = (angle * Math.PI) / 180;
+    el.style.setProperty('--dx', `${Math.cos(rad) * dist}px`);
+    el.style.setProperty('--dy', `${Math.sin(rad) * dist}px`);
+    el.style.setProperty('--color', colors[i % colors.length]!);
+    parent.appendChild(el);
+    setTimeout(() => el.remove(), 1000);
+  }
+}
+
+export function spawnTurnBurst(parent: HTMLElement, color?: string) {
+  const symbols = ['>', '>>', '>>>'];
+  for (let i = 0; i < 6; i++) {
+    const el = document.createElement('div');
+    el.className = 'timer-turn-particle';
+    el.textContent = symbols[i % symbols.length]!;
+    const angle = (i / 6) * 360 + 15;
+    const dist = 40 + Math.random() * 40;
+    const rad = (angle * Math.PI) / 180;
+    el.style.setProperty('--dx', `${Math.cos(rad) * dist}px`);
+    el.style.setProperty('--dy', `${Math.sin(rad) * dist}px`);
+    if (color) el.style.setProperty('--accent', color);
+    parent.appendChild(el);
+    setTimeout(() => el.remove(), 800);
+  }
+}
+
+export function spawnConfetti(container: HTMLElement, count = 50) {
+  const colors = ['#ef4444', '#3b82f6', '#22c55e', '#eab308', '#a855f7', '#f97316', '#14b8a6', '#ec4899'];
+  for (let i = 0; i < count; i++) {
+    const el = document.createElement('div');
+    el.className = `timer-confetti-piece${Math.random() > 0.5 ? ' timer-confetti-round' : ''}`;
+    el.style.left = `${10 + Math.random() * 80}%`;
+    el.style.top = `-${5 + Math.random() * 15}px`;
+    el.style.background = colors[Math.floor(Math.random() * colors.length)]!;
+    el.style.width = `${5 + Math.random() * 7}px`;
+    el.style.height = `${5 + Math.random() * 7}px`;
+    el.style.animationDelay = `${Math.random() * 1.2}s`;
+    el.style.animationDuration = `${2 + Math.random() * 1.5}s`;
+    container.appendChild(el);
+    setTimeout(() => el.remove(), 5000);
+  }
+}
+
+export function spawnRippleEffect(container: HTMLElement) {
+  const el = document.createElement('div');
+  el.className = 'ripple';
+  const size = 200 + Math.random() * 200;
+  const x = 20 + Math.random() * 60;
+  const y = 20 + Math.random() * 60;
+  el.style.width = `${size}px`;
+  el.style.height = `${size}px`;
+  el.style.left = `${x}%`;
+  el.style.top = `${y}%`;
+  el.style.marginLeft = `-${size / 2}px`;
+  el.style.marginTop = `-${size / 2}px`;
+  container.appendChild(el);
+  setTimeout(() => el.remove(), 800);
+}
+
+export function spawnDigitSparkle(element: HTMLElement) {
+  element.classList.remove('timer-digit-update');
+  void element.offsetWidth;
+  element.classList.add('timer-digit-update');
+}
+
+export function spawnWarningFlash(element: HTMLElement) {
+  element.classList.remove('warning-glow');
+  void element.offsetWidth;
+  element.classList.add('warning-glow');
+}
+
+export function spawnDangerFlash(element: HTMLElement) {
+  element.classList.remove('danger-glow');
+  void element.offsetWidth;
+  element.classList.add('danger-glow');
+  element.classList.remove('danger-shake');
+  void element.offsetWidth;
+  element.classList.add('danger-shake');
+}

package/src/tool/board-game-timer/seo.astro

@@ -0,0 +1,16 @@
+---
+import { SEORenderer } from '@jjlmoya/utils-shared';
+import { boardGameTimer } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props;
+const loader = boardGameTimer.i18n[locale] || boardGameTimer.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content.seo?.length > 0 && <SEORenderer content={{ locale, sections: content.seo }} />}

package/src/tool/board-game-timer/types.ts

@@ -0,0 +1,97 @@
+export type TimerStatus = 'idle' | 'running' | 'paused' | 'expired' | 'overtime';
+
+export interface TimerState {
+  id: string;
+  label: string;
+  initialDuration: number;
+  remaining: number;
+  status: TimerStatus;
+  _lastTickAt: number;
+  roundsPlayed: number;
+  overtime: number;
+}
+
+export type TimerEventCallback = (id: string, remaining: number) => void;
+
+export type TimeControlMode = 'normal' | 'fischer' | 'bronstein' | 'hourglass' | 'turn';
+
+export interface TimerConfig {
+  tickInterval?: number;
+  mode?: TimeControlMode;
+  increment?: number;
+  delay?: number;
+  warningTime?: number;
+}
+
+export interface PlayerConfig {
+  id: string;
+  name: string;
+  color: string;
+  avatar?: string;
+  time: number;
+}
+
+export type PlayerColor = 'blue' | 'red' | 'green' | 'yellow' | 'purple' | 'orange' | 'teal' | 'pink';
+
+export const PLAYER_COLORS: Record<PlayerColor, string> = {
+  blue: '#3b82f6',
+  red: '#ef4444',
+  green: '#22c55e',
+  yellow: '#eab308',
+  purple: '#a855f7',
+  orange: '#f97316',
+  teal: '#14b8a6',
+  pink: '#ec4899',
+};
+
+export const PLAYER_COLOR_NAMES: Record<PlayerColor, string> = {
+  blue: 'Blue',
+  red: 'Red',
+  green: 'Green',
+  yellow: 'Yellow',
+  purple: 'Purple',
+  orange: 'Orange',
+  teal: 'Teal',
+  pink: 'Pink',
+};
+
+export interface GameConfig {
+  players: PlayerConfig[];
+  turnOrder: 'clockwise' | 'sequential';
+  increment?: number;
+  delay?: number;
+  warningTime: number;
+  mode: TimeControlMode;
+  soundEnabled: boolean;
+}
+
+export interface GameState {
+  activePlayerIndex: number;
+  phase: 'setup' | 'playing' | 'paused' | 'finished';
+  round: number;
+}
+
+export interface TimerEngine {
+  create(id: string, label: string, duration: number): void;
+  start(id: string): void;
+  pause(id: string): void;
+  resume(id: string): void;
+  reset(id: string): void;
+  addTime(id: string, seconds: number): void;
+  removeTime(id: string, seconds: number): void;
+  getTimer(id: string): TimerState | undefined;
+  getAllTimers(): TimerState[];
+  switchTurn(nextId: string): void;
+  switchToNextPlayer(playerIds: string[], currentIndex: number): { nextId: string; nextIndex: number };
+  pauseAll(): void;
+  resumeAll(playerIds: string[], activeIndex: number): void;
+  readonly activeTimerId: string | undefined;
+  onExpired(cb: TimerEventCallback): void;
+  onTick(cb: TimerEventCallback): void;
+  onWarning(cb: TimerEventCallback): void;
+  destroyTimer(id: string): void;
+  destroy(): void;
+  setMode(mode: TimeControlMode): void;
+  setIncrement(seconds: number): void;
+  setDelay(seconds: number): void;
+}

package/src/tool/dice-roller-simulator/bibliography.astro

@@ -0,0 +1,16 @@
+---
+import { Bibliography as SharedBibliography } from '@jjlmoya/utils-shared';
+import { diceRollerSimulator } from './index';
+import type { KnownLocale } from '../../types';
+
+interface Props {
+  locale?: KnownLocale;
+}
+
+const { locale = 'en' } = Astro.props as Props;
+const loader = diceRollerSimulator.i18n[locale] || diceRollerSimulator.i18n.en;
+const content = await loader?.();
+if (!content) return null;
+---
+
+{content && <SharedBibliography links={content.bibliography} />}

package/src/tool/dice-roller-simulator/bibliography.ts

@@ -0,0 +1,12 @@
+import type { BibliographyEntry } from '../../types';
+
+export const bibliography: BibliographyEntry[] = [
+  {
+    name: 'Dice Probability Mathematics',
+    url: 'https://en.wikipedia.org/wiki/Dice_probability_formula',
+  },
+  {
+    name: 'Board Game Geek Dice Guide',
+    url: 'https://boardgamegeek.com/thread/3319696/dice-games-properly-explained',
+  },
+];