@caperjs/core 0.1.0

package/src/plugins/breakpoints/BreakpointPlugin.ts

@@ -0,0 +1,293 @@
+import type { IApplication } from '../../core';
+import { Signal, type SignalConnection, type SignalOrder } from '../../signals';
+import { Logger, type Orientation, type Size } from '../../utils';
+import type { IPlugin } from '../Plugin';
+import { Plugin } from '../Plugin';
+import type { NormalizedLadder } from './evaluate';
+import {
+  activeNames,
+  buildContext,
+  diffNames,
+  matchesMode,
+  normalizeTiers,
+  resolveStop,
+  resolveValue,
+} from './evaluate';
+import type {
+  BreakpointChangeDetail,
+  BreakpointContext,
+  BreakpointMode,
+  BreakpointNameLike,
+  BreakpointPluginOptions,
+  BreakpointTierName,
+  Pointer,
+} from './types';
+import { defaultBreakpoints } from './types';
+
+const AXIS_NAMES = new Set<string>(['portrait', 'landscape', 'coarse', 'fine']);
+const ZERO: Size = { width: 0, height: 0 };
+
+export interface IBreakpointPlugin extends IPlugin<BreakpointPluginOptions> {
+  readonly onBreakpointChanged: Signal<(detail: BreakpointChangeDetail) => void>;
+  readonly onChange: Signal<(detail: BreakpointChangeDetail) => void>;
+  readonly current: BreakpointNameLike;
+  readonly size: Size;
+  readonly width: number;
+  readonly height: number;
+  readonly orientation: Orientation;
+  readonly pointer: Pointer;
+  is(name: BreakpointNameLike): boolean;
+  atLeast(value: BreakpointNameLike | number): boolean;
+  below(value: BreakpointNameLike | number): boolean;
+  between(lower: BreakpointNameLike | number, upper: BreakpointNameLike | number): boolean;
+  matches(mode: BreakpointMode): boolean;
+  value<T>(map: Partial<Record<BreakpointTierName, T>>): T | undefined;
+  define(name: string, mode: BreakpointMode): void;
+  undefine(name: string): void;
+  onEnter(name: BreakpointNameLike, callback: () => void, order?: SignalOrder): SignalConnection;
+  onLeave(name: BreakpointNameLike, callback: () => void, order?: SignalOrder): SignalConnection;
+  when(name: BreakpointNameLike, callback: () => void, order?: SignalOrder): SignalConnection;
+}
+
+/**
+ * Named responsive state derived from the renderer size.
+ *
+ * Declare tiers and modes in `caper.config.ts`; the plugin re-evaluates on
+ * every resize but only emits when a name actually flips.
+ *
+ * @example
+ * ```ts
+ * const bp = app.breakpoints;
+ *
+ * const columns = bp.value({ mobile: 1, tablet: 2, desktop: 3 });
+ * if (bp.is('stacked')) { ... }
+ *
+ * // run now, and again on every entry into the mode
+ * this.addSignalConnection(bp.when('stacked', () => this.relayout()));
+ * ```
+ *
+ * Listen to `app.onResize` or `bp.onChange` — never `app.webEvents.onResize`,
+ * which fires ahead of this plugin and so reports a stale tier.
+ */
+export class BreakpointPlugin extends Plugin<BreakpointPluginOptions> implements IBreakpointPlugin {
+  public readonly id = 'breakpoints';
+
+  /**
+   * Named to match its `ICoreSignals` key — `registerCoreSignals` copies
+   * `this[name]` into the registry under the same string.
+   */
+  public readonly onBreakpointChanged = new Signal<(detail: BreakpointChangeDetail) => void>();
+
+  private _ladder: NormalizedLadder;
+  private _modes = new Map<string, BreakpointMode>();
+  private _ctx: BreakpointContext;
+  private _active: Set<string> = new Set();
+  private _enter = new Map<string, Signal<() => void>>();
+  private _leave = new Map<string, Signal<() => void>>();
+  private _pointer: Pointer = 'fine';
+  private _pointerQuery: MediaQueryList | null = null;
+  private _warnedListenerNames = new Set<string>();
+
+  /** Fluent alias for {@link onBreakpointChanged}. */
+  get onChange(): Signal<(detail: BreakpointChangeDetail) => void> {
+    return this.onBreakpointChanged;
+  }
+
+  get current(): BreakpointNameLike {
+    return this._ctx.tier;
+  }
+
+  get size(): Size {
+    return { width: this._ctx.width, height: this._ctx.height };
+  }
+
+  get width(): number {
+    return this._ctx.width;
+  }
+
+  get height(): number {
+    return this._ctx.height;
+  }
+
+  get orientation(): Orientation {
+    return this._ctx.orientation;
+  }
+
+  get pointer(): Pointer {
+    return this._ctx.pointer;
+  }
+
+  async initialize(options: Partial<BreakpointPluginOptions> = {}) {
+    // Seed a safe default ladder and context before validating the user's
+    // tiers below. `normalizeTiers` throws on an invalid ladder, and
+    // `Application.registerPlugin` swallows a rejected `initialize` and
+    // continues — leaving `_ladder`/`_ctx` unset would turn every later
+    // accessor into an unrelated TypeError instead of surfacing the real
+    // cause (spec §11).
+    this._ladder = normalizeTiers({ ...defaultBreakpoints });
+    this._ctx = buildContext(ZERO, this._ladder, this._pointer);
+
+    this._options = {
+      tiers: options.tiers ?? { ...defaultBreakpoints },
+      modes: options.modes ?? {},
+    };
+    this._ladder = normalizeTiers(this._options.tiers!);
+    for (const [name, mode] of Object.entries(this._options.modes!)) {
+      this._modes.set(name, mode);
+    }
+    this._initPointer();
+    this._ctx = buildContext(ZERO, this._ladder, this._pointer);
+    this._active = activeNames(this._ctx, this._modes, this._ladder);
+  }
+
+  /**
+   * `'highest'` priority so `current` is already updated when normal-priority
+   * scene resize handlers run.
+   */
+  async postInitialize(_app: IApplication) {
+    this._evaluate(this.app.size ?? ZERO);
+    this.addSignalConnection(this.app.onResize.connect(this._evaluate, 'highest'));
+  }
+
+  public destroy(): void {
+    this._pointerQuery?.removeEventListener('change', this._onPointerChange);
+    this._pointerQuery = null;
+    for (const signal of this._enter.values()) signal.disconnectAll();
+    for (const signal of this._leave.values()) signal.disconnectAll();
+    this._enter.clear();
+    this._leave.clear();
+    this.onBreakpointChanged.disconnectAll();
+    super.destroy();
+  }
+
+  public is(name: BreakpointNameLike): boolean {
+    if (!this._isKnown(name as string)) {
+      Logger.warn(`[breakpoints] unknown name '${name}'. Known: ${this._knownNames().join(', ')}.`);
+      return false;
+    }
+    return this._active.has(name as string);
+  }
+
+  public atLeast(value: BreakpointNameLike | number): boolean {
+    const stop = resolveStop(this._ladder, value);
+    return stop !== undefined && this._ctx.width >= stop;
+  }
+
+  public below(value: BreakpointNameLike | number): boolean {
+    const stop = resolveStop(this._ladder, value);
+    return stop !== undefined && this._ctx.width < stop;
+  }
+
+  public between(lower: BreakpointNameLike | number, upper: BreakpointNameLike | number): boolean {
+    return this.atLeast(lower) && this.below(upper);
+  }
+
+  public matches(mode: BreakpointMode): boolean {
+    return matchesMode(this._ctx, mode, this._ladder);
+  }
+
+  public value<T>(map: Partial<Record<BreakpointTierName, T>>): T | undefined {
+    return resolveValue(this._ladder, this._ctx.tier, map as Partial<Record<string, T>>);
+  }
+
+  public define(name: string, mode: BreakpointMode): void {
+    this._modes.set(name, mode);
+    this._evaluate(this.size);
+  }
+
+  public undefine(name: string): void {
+    if (!this._modes.delete(name)) return;
+    this._evaluate(this.size);
+  }
+
+  public onEnter(name: BreakpointNameLike, callback: () => void, order?: SignalOrder): SignalConnection {
+    this._warnIfUnknown(name as string);
+    return this._signal(this._enter, name as string).connect(callback, order);
+  }
+
+  public onLeave(name: BreakpointNameLike, callback: () => void, order?: SignalOrder): SignalConnection {
+    this._warnIfUnknown(name as string);
+    return this._signal(this._leave, name as string).connect(callback, order);
+  }
+
+  /** Run now if already matching, then on every subsequent entry. */
+  public when(name: BreakpointNameLike, callback: () => void, order?: SignalOrder): SignalConnection {
+    if (this._active.has(name as string)) callback();
+    return this.onEnter(name, callback, order);
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onBreakpointChanged'];
+  }
+
+  /**
+   * Re-derive state from a size. Emits leave before enter — a scene tears the
+   * old layout down before the new one goes up — and `onChange` last.
+   */
+  private _evaluate = (size: Size): void => {
+    const next = buildContext(size ?? ZERO, this._ladder, this._pointer);
+    const nextActive = activeNames(next, this._modes, this._ladder);
+    const { entered, left } = diffNames(this._active, nextActive);
+    const previous = this._ctx.tier;
+
+    this._ctx = next;
+    this._active = nextActive;
+
+    if (entered.length === 0 && left.length === 0) return;
+
+    for (const name of left) this._leave.get(name)?.emit();
+    for (const name of entered) this._enter.get(name)?.emit();
+
+    this.onBreakpointChanged.emit({
+      current: next.tier,
+      previous,
+      entered,
+      left,
+      size: { width: next.width, height: next.height },
+    });
+  };
+
+  private _onPointerChange = (e: MediaQueryListEvent): void => {
+    this._pointer = e.matches ? 'coarse' : 'fine';
+    this._evaluate(this.size);
+  };
+
+  private _initPointer(): void {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+      this._pointer = 'fine';
+      return;
+    }
+    this._pointerQuery = window.matchMedia('(pointer: coarse)');
+    this._pointer = this._pointerQuery.matches ? 'coarse' : 'fine';
+    this._pointerQuery.addEventListener('change', this._onPointerChange);
+  }
+
+  private _signal(store: Map<string, Signal<() => void>>, name: string): Signal<() => void> {
+    let signal = store.get(name);
+    if (!signal) {
+      signal = new Signal<() => void>();
+      store.set(name, signal);
+    }
+    return signal;
+  }
+
+  private _isKnown(name: string): boolean {
+    return name in this._ladder.byName || this._modes.has(name) || AXIS_NAMES.has(name);
+  }
+
+  /**
+   * `onEnter`/`onLeave` (and `when`, which delegates to `onEnter`) still
+   * connect a live signal for an unknown name — it may be `define`d later
+   * (§8) — but warn once per name so a typo doesn't silently create a
+   * listener nothing will ever emit.
+   */
+  private _warnIfUnknown(name: string): void {
+    if (this._isKnown(name) || this._warnedListenerNames.has(name)) return;
+    this._warnedListenerNames.add(name);
+    Logger.warn(`[breakpoints] unknown name '${name}'. Known: ${this._knownNames().join(', ')}.`);
+  }
+
+  private _knownNames(): string[] {
+    return [...this._ladder.names, ...this._modes.keys(), ...AXIS_NAMES];
+  }
+}

package/src/plugins/breakpoints/evaluate.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it } from 'vitest';
+
+import { defaultBreakpoints } from './types';
+import type { BreakpointContext, BreakpointMode } from './types';
+import { activeNames, buildContext, diffNames, matchesMode, normalizeTiers, resolveTier, resolveStop, resolveValue } from './evaluate';
+
+const ladder = normalizeTiers({ ...defaultBreakpoints });
+
+function ctx(overrides: Partial<BreakpointContext> = {}): BreakpointContext {
+  return {
+    width: 800,
+    height: 600,
+    aspect: 800 / 600,
+    tier: 'tablet',
+    orientation: 'landscape',
+    pointer: 'fine',
+    ...overrides,
+  };
+}
+
+describe('normalizeTiers', () => {
+  it('sorts by stop regardless of key order', () => {
+    const ladder = normalizeTiers({ desktop: 1024, mobile: 0, tablet: 768 });
+    expect(ladder.names).toEqual(['mobile', 'tablet', 'desktop']);
+    expect(ladder.stops).toEqual([0, 768, 1024]);
+    expect(ladder.byName.tablet).toBe(768);
+  });
+
+  it('throws on an empty ladder', () => {
+    expect(() => normalizeTiers({})).toThrow(/at least one tier/i);
+  });
+
+  it('throws when the lowest tier does not start at 0', () => {
+    expect(() => normalizeTiers({ small: 320, large: 1024 })).toThrow(/must start at 0/i);
+  });
+
+  it('throws on duplicate stops', () => {
+    expect(() => normalizeTiers({ a: 0, b: 768, c: 768 })).toThrow(/same stop/i);
+  });
+
+  it('throws on a negative or non-finite stop', () => {
+    expect(() => normalizeTiers({ a: 0, b: -1 })).toThrow(/invalid stop/i);
+    expect(() => normalizeTiers({ a: 0, b: Number.NaN })).toThrow(/invalid stop/i);
+  });
+});
+
+describe('resolveTier', () => {
+  it('resolves each boundary exactly', () => {
+    expect(resolveTier(ladder, 0)).toBe('mobile');
+    expect(resolveTier(ladder, 767)).toBe('mobile');
+    expect(resolveTier(ladder, 768)).toBe('tablet');
+    expect(resolveTier(ladder, 1023)).toBe('tablet');
+    expect(resolveTier(ladder, 1024)).toBe('desktop');
+    expect(resolveTier(ladder, 1439)).toBe('desktop');
+    expect(resolveTier(ladder, 1440)).toBe('wide');
+    expect(resolveTier(ladder, 99999)).toBe('wide');
+  });
+
+  it('clamps below the lowest stop to the lowest tier', () => {
+    expect(resolveTier(ladder, -50)).toBe('mobile');
+  });
+
+  it('works with a custom ladder', () => {
+    const custom = normalizeTiers({ tiny: 0, huge: 2200 });
+    expect(resolveTier(custom, 2199)).toBe('tiny');
+    expect(resolveTier(custom, 2200)).toBe('huge');
+  });
+});
+
+describe('resolveStop', () => {
+  it('passes numbers through', () => {
+    expect(resolveStop(ladder, 880)).toBe(880);
+  });
+
+  it('resolves a tier name to its stop', () => {
+    expect(resolveStop(ladder, 'tablet')).toBe(768);
+  });
+
+  it('returns undefined for an unknown name', () => {
+    expect(resolveStop(ladder, 'nope')).toBeUndefined();
+  });
+});
+
+describe('matchesMode', () => {
+  it('matches an empty condition', () => {
+    expect(matchesMode(ctx(), {}, ladder)).toBe(true);
+  });
+
+  it('matches a single tier', () => {
+    expect(matchesMode(ctx({ tier: 'tablet' }), { tier: 'tablet' }, ladder)).toBe(true);
+    expect(matchesMode(ctx({ tier: 'mobile' }), { tier: 'tablet' }, ladder)).toBe(false);
+  });
+
+  it('matches tier membership in an array', () => {
+    const mode = { tier: ['mobile', 'tablet'] };
+    expect(matchesMode(ctx({ tier: 'mobile' }), mode, ladder)).toBe(true);
+    expect(matchesMode(ctx({ tier: 'tablet' }), mode, ladder)).toBe(true);
+    expect(matchesMode(ctx({ tier: 'desktop' }), mode, ladder)).toBe(false);
+  });
+
+  it('resolves atLeast/below by tier name identically to the raw stop', () => {
+    const byName = matchesMode(ctx({ width: 768 }), { atLeast: 'tablet' }, ladder);
+    const byPx = matchesMode(ctx({ width: 768 }), { atLeast: 768 }, ladder);
+    expect(byName).toBe(true);
+    expect(byPx).toBe(byName);
+
+    expect(matchesMode(ctx({ width: 767 }), { atLeast: 'tablet' }, ladder)).toBe(false);
+    expect(matchesMode(ctx({ width: 767 }), { below: 'tablet' }, ladder)).toBe(true);
+    expect(matchesMode(ctx({ width: 768 }), { below: 'tablet' }, ladder)).toBe(false);
+  });
+
+  it('is false when a stop name is unknown', () => {
+    expect(matchesMode(ctx(), { atLeast: 'nope' }, ladder)).toBe(false);
+    expect(matchesMode(ctx(), { below: 'nope' }, ladder)).toBe(false);
+  });
+
+  it('ANDs every key', () => {
+    const mode = { atLeast: 'tablet' as const, orientation: 'landscape' as const };
+    expect(matchesMode(ctx({ width: 900, orientation: 'landscape' }), mode, ladder)).toBe(true);
+    expect(matchesMode(ctx({ width: 900, orientation: 'portrait' }), mode, ladder)).toBe(false);
+    expect(matchesMode(ctx({ width: 400, orientation: 'landscape' }), mode, ladder)).toBe(false);
+  });
+
+  it('matches the pointer and height keys', () => {
+    expect(matchesMode(ctx({ pointer: 'coarse' }), { pointer: 'coarse' }, ladder)).toBe(true);
+    expect(matchesMode(ctx({ pointer: 'fine' }), { pointer: 'coarse' }, ladder)).toBe(false);
+    expect(matchesMode(ctx({ height: 600 }), { minHeight: 600 }, ladder)).toBe(true);
+    expect(matchesMode(ctx({ height: 599 }), { minHeight: 600 }, ladder)).toBe(false);
+    expect(matchesMode(ctx({ height: 600 }), { maxHeight: 600 }, ladder)).toBe(true);
+    expect(matchesMode(ctx({ height: 601 }), { maxHeight: 600 }, ladder)).toBe(false);
+  });
+
+  it('supports a predicate', () => {
+    expect(matchesMode(ctx({ width: 800, height: 600 }), (c) => c.aspect > 1, ladder)).toBe(true);
+    expect(matchesMode(ctx(), () => false, ladder)).toBe(false);
+  });
+
+  it('treats a throwing predicate as false', () => {
+    const boom = () => {
+      throw new Error('boom');
+    };
+    expect(matchesMode(ctx(), boom, ladder, 'boom')).toBe(false);
+  });
+});
+
+describe('buildContext', () => {
+  it('derives tier, orientation and aspect', () => {
+    const c = buildContext({ width: 1000, height: 500 }, ladder, 'fine');
+    expect(c.tier).toBe('tablet');
+    expect(c.orientation).toBe('landscape');
+    expect(c.aspect).toBe(2);
+    expect(c.pointer).toBe('fine');
+  });
+
+  it('treats equal width and height as portrait', () => {
+    expect(buildContext({ width: 600, height: 600 }, ladder, 'fine').orientation).toBe('portrait');
+  });
+
+  it('survives a zero size without dividing by zero', () => {
+    const c = buildContext({ width: 0, height: 0 }, ladder, 'fine');
+    expect(c.tier).toBe('mobile');
+    expect(c.orientation).toBe('portrait');
+    expect(c.aspect).toBe(0);
+  });
+});
+
+describe('activeNames', () => {
+  const modes = new Map<string, BreakpointMode>([
+    ['stacked', { below: 880 }],
+    ['roomy', { atLeast: 'desktop' }],
+  ]);
+
+  it('collects tier, axes and matching modes into one set', () => {
+    const c = buildContext({ width: 800, height: 600 }, ladder, 'coarse');
+    expect(activeNames(c, modes, ladder)).toEqual(new Set(['tablet', 'landscape', 'coarse', 'stacked']));
+  });
+
+  it('drops modes that stop matching', () => {
+    const c = buildContext({ width: 1200, height: 600 }, ladder, 'fine');
+    expect(activeNames(c, modes, ladder)).toEqual(new Set(['desktop', 'landscape', 'fine', 'roomy']));
+  });
+});
+
+describe('diffNames', () => {
+  it('reports an empty diff when nothing changed', () => {
+    const a = new Set(['tablet', 'landscape']);
+    expect(diffNames(a, new Set(['tablet', 'landscape']))).toEqual({ entered: [], left: [] });
+  });
+
+  it('reports a tier change', () => {
+    const d = diffNames(new Set(['tablet']), new Set(['desktop']));
+    expect(d.entered).toEqual(['desktop']);
+    expect(d.left).toEqual(['tablet']);
+  });
+
+  it('reports an orientation change', () => {
+    const d = diffNames(new Set(['tablet', 'portrait']), new Set(['tablet', 'landscape']));
+    expect(d.entered).toEqual(['landscape']);
+    expect(d.left).toEqual(['portrait']);
+  });
+
+  it('reports a mode flip independently of the tier', () => {
+    const d = diffNames(new Set(['tablet', 'stacked']), new Set(['tablet']));
+    expect(d.entered).toEqual([]);
+    expect(d.left).toEqual(['stacked']);
+  });
+});
+
+describe('resolveValue', () => {
+  it('takes an exact hit', () => {
+    expect(resolveValue(ladder, 'tablet', { mobile: 1, tablet: 2, desktop: 3 })).toBe(2);
+  });
+
+  it('falls to the nearest defined tier below', () => {
+    expect(resolveValue(ladder, 'desktop', { mobile: 1, tablet: 2 })).toBe(2);
+    expect(resolveValue(ladder, 'tablet', { mobile: 1, desktop: 3 })).toBe(1);
+  });
+
+  it('falls back to the lowest defined entry when nothing is below', () => {
+    expect(resolveValue(ladder, 'mobile', { desktop: 3, wide: 4 })).toBe(3);
+  });
+
+  it('handles a single-entry map from any tier', () => {
+    expect(resolveValue(ladder, 'wide', { tablet: 2 })).toBe(2);
+    expect(resolveValue(ladder, 'mobile', { tablet: 2 })).toBe(2);
+  });
+
+  it('returns undefined for an empty map', () => {
+    expect(resolveValue(ladder, 'tablet', {})).toBeUndefined();
+  });
+
+  it('treats an explicit undefined value as absent', () => {
+    expect(resolveValue(ladder, 'tablet', { mobile: 1, tablet: undefined })).toBe(1);
+  });
+
+  it('falls back to the lowest entry when the tier is not on the ladder', () => {
+    expect(resolveValue(ladder, 'bogus', { mobile: 1 })).toBe(1);
+  });
+});