pts 0.12.8 → 1.0.0

package/src/Types.ts

@@ -0,0 +1,301 @@
+/*! Pts.js is licensed under Apache License 2.0. Copyright © 2017-current William Ngan and contributors. (https://github.com/williamngan/pts) */
+
+import { type Pt, type Group, type Bound } from "./Pt";
+import { type Space } from "./Space";
+import { type UI, type UIPointerAction } from "./UI";
+
+/**
+ * Typescript interface: IPt is an interface that represents an object with x, y, z, w properties.
+ */
+export interface IPt {
+  x?: number;
+  y?: number;
+  z?: number;
+  w?: number;
+}
+
+/**
+ * Typescript type: PtLike represents the data of a point. It can be either a Pt instance or an array of numbers.
+ */
+export type PtLike = Pt | Float32Array | number[];
+
+/**
+ * Typescript type: GroupLike represents an array of Pt instances. It be a Group instance or an array of Pt. Unlike `PtIterable`, this type only allows arrays but not iterables.
+ */
+export type GroupLike = Group | Pt[];
+
+/**
+ * Typescript type: PtIterable represents an iterable list of Pt instances. Unlike `PtLikeIterable`, this type only allows Pt instances but not numbers' arrays.
+ * If you aren't sure what this type means, treat this as a [`Group`](#link) instance.
+ */
+export type PtIterable = GroupLike | Pt[] | Iterable<Pt>;
+
+/**
+ * Typescript type: PtLikeIterable is the most flexible way to represent an iterable list of point data. For example, it can be a Group, an iterable of Pt instances, or an array of numbers' arrays.
+ * If you aren't sure what this type means, treat this as a [`Group`](#link) instance.
+ */
+export type PtLikeIterable = GroupLike | PtLike[] | Iterable<PtLike>;
+
+/**
+ * Typescript type: TextMeasure represents a function that returns the rendered width of a string of text, such as canvas context's `measureText` or an estimator created via [`Typography.textWidthEstimator`](#link).
+ */
+export type TextMeasure = (text: string) => number;
+
+/**
+ * Typescript type: TextVerticalAlign represents the vertical alignment options accepted by [`CanvasForm.textBox`](#link) and [`CanvasForm.paragraphBox`](#link).
+ */
+export type TextVerticalAlign =
+  "top" | "start" | "middle" | "center" | "bottom" | "end";
+
+/**
+ * Typescript type: AnimateCallbackFn represents a callback function for animation. It accepts parameters to keep track of current time, current frame-time, and current space instance.
+ */
+export type AnimateCallbackFn = (
+  time: number,
+  frameTime: number,
+  currentSpace: Space,
+) => void;
+
+/**
+ * Typescript type: UIActionEvent represents the DOM events a Space dispatches to players and UI handlers — pointer, mouse, touch, and keyboard.
+ */
+export type UIActionEvent =
+  MouseEvent | TouchEvent | PointerEvent | KeyboardEvent;
+
+/**
+ * Typescript interface: IPlayer is an interface that represents a "player" object that can be added into a Space.
+ */
+export interface IPlayer {
+  animateID?: string;
+  animate?: AnimateCallbackFn;
+  resize?(bound: Bound, evt?: Event | null): void;
+  action?(type: string, px: number, py: number, evt: UIActionEvent): void;
+  start?(bound: Bound, space: Space): void;
+}
+
+/**
+ * Typescript interface: ISpacePlayers represents a map of IPlayer instances.
+ */
+export interface ISpacePlayers {
+  [key: string]: IPlayer;
+}
+
+/**
+ *Typescript interface: ITimer represents a time-recording object.
+ */
+export interface ITimer {
+  prev: number;
+  diff: number;
+  end: number;
+  min: number;
+}
+
+/**
+ * Typescript type: TouchPointsKey represents a set of acceptable string keys for defining touch action.
+ */
+export type TouchPointsKey = "touches" | "changedTouches" | "targetTouches";
+
+/**
+ * Typescript interface: MultiTouchElement represents an element that can handle touch events.
+ */
+export interface MultiTouchElement {
+  addEventListener(
+    evt: string,
+    callback: EventListenerOrEventListenerObject,
+  ): void;
+  removeEventListener(
+    evt: string,
+    callback: EventListenerOrEventListenerObject,
+  ): void;
+}
+
+/**
+ * Typescript type: Setup options for CanvasSpace. See [`CanvasSpace.setup()`](#link) function.
+ */
+export type CanvasSpaceOptions = {
+  bgcolor?: string;
+  resize?: boolean;
+  retina?: boolean;
+  offscreen?: boolean;
+  pixelDensity?: number;
+};
+
+/**
+ * Typescript type: ColorType represents a defined set of string values such as "rgb" and "lab".
+ */
+export type ColorType =
+  "rgb" | "hsl" | "hsb" | "lab" | "lch" | "luv" | "xyz" | "oklab" | "oklch";
+
+/**
+ * Typescript type: DelaunayShape represents an object type that can store a Delaunay element. It has 3 indices (i, j, k) and two groups that represent a triangle and a circle.
+ */
+export type DelaunayShape = {
+  i: number;
+  j: number;
+  k: number;
+  triangle: GroupLike;
+  circle: Group;
+};
+
+/**
+ * Typescript type: DelaunayMesh represents an object type that has an array of {key: shape} items, where each shape represents a DelaunayShape.
+ * Note the unusual shape: it is an array indexed by point index, where each entry is a dictionary keyed by `"min-max"` neighbor-pair strings. This mirrors the mesh cache built by [`Delaunay.mesh`](#link) and is kept as-is for compatibility.
+ */
+export type DelaunayMesh = { [key: string]: DelaunayShape }[];
+
+/**
+ * Typescript type: FlockBoundary is how a [`Flock`](#link) treats the edges of its bound:
+ * `"steer"` turns agents back within a margin, `"wrap"` moves them to the opposite edge,
+ * `"bounce"` reflects them, and `"none"` lets them leave.
+ */
+export type FlockBoundary = "steer" | "wrap" | "bounce" | "none";
+
+/**
+ * Typescript type: FlockOptions are the settings accepted by [`Create.flock`](#link) and
+ * [`Flock.setup`](#link). Every field is optional; see the matching [`Flock`](#link) accessor
+ * for its meaning and default.
+ */
+export type FlockOptions = {
+  /** Radius within which an agent sees its neighbors. Default is 40. */
+  perception?: number;
+  /** Radius within which an agent steers away from its neighbors. Default is 20. */
+  separation?: number;
+  /** Weight of steering toward the neighbors' center. Default is 1. */
+  cohesionWeight?: number;
+  /** Weight of matching the neighbors' heading. Default is 1. */
+  alignWeight?: number;
+  /** Weight of steering away from close neighbors. Default is 1.5. */
+  separateWeight?: number;
+  /** Maximum speed, in units per second. Default is 100. */
+  maxSpeed?: number;
+  /** Minimum speed, in units per second. Default is 0. */
+  minSpeed?: number;
+  /** Maximum steering force, in units per second squared. Default is 200. */
+  maxForce?: number;
+  /** A [`Bound`](#link) or a Group of 2 Pts that keeps the flock in view. Default is none. */
+  bound?: GroupLike;
+  /** How the bound's edges are treated. Default is `"steer"`. */
+  boundary?: FlockBoundary;
+  /** Distance from an edge at which `"steer"` starts turning agents back. Default is 50. */
+  margin?: number;
+  /** Maximum simulated time in milliseconds per step. Default is 50. */
+  maxTimeStep?: number;
+  /** Speed given to agents added without a velocity. Default is half of `maxSpeed`. */
+  initialSpeed?: number;
+};
+
+/**
+ * Typescript type: DOMFormContext represents the current context for an DOMForm.
+ */
+export type DOMFormContext = {
+  group: Element | null | undefined;
+  groupID: string;
+  groupCount: number;
+  currentID: string;
+  currentClass?: string;
+  style: Record<string, string | number | boolean>;
+};
+
+/**
+ * Typescript type: IntersectContext represents a type of an object that store the intersection info.
+ */
+export type IntersectContext = {
+  which: number;
+  dist: number;
+  normal: Pt;
+  vertex: Pt;
+  edge: Group;
+  other?: unknown;
+};
+
+/**
+ * Typescript type: UIHandler represents a callback function to handle UI actions.
+ */
+export type UIHandler = (
+  target: UI,
+  pt: PtLike,
+  type: UIPointerAction | (string & {}),
+  evt: UIActionEvent,
+) => void;
+
+/**
+ * Typescript type: WarningType specifies a level of warning for [`Util.warnLevel`](#link).
+ */
+export type WarningType = "error" | "warn" | "mute";
+
+/**
+ * Typescript type: a callback function type used in `tempo.every(...).start( fn )`
+ */
+export type ITempoStartFn = (count: number) => void | boolean;
+
+/**
+ * Typescript type: a callback function type used in `tempo.every(...).progress( fn )`
+ */
+export type ITempoProgressFn = (
+  count: number,
+  t: number,
+  ms: number,
+  start: boolean,
+) => void | boolean;
+
+/**
+ * Typescript type: ITempoListener represents a listener created by Tempo class
+ */
+export type ITempoListener = {
+  name?: string; // reference id
+  beats?: number | number[]; // rhythm in beats
+  period?: number; // current number of beats per period
+  duration?: number; // current duration in ms per period
+  offset?: number; // time offset
+  continuous?: boolean; // track progress is true, otherwise track only triggers
+  index?: number; // if beats is an array, this is the current index
+  count?: number; // number of periods started so far
+  fn: ITempoStartFn | ITempoProgressFn; // callback function
+};
+
+/**
+ * Typescript type: the return type of `tempo.every(...)`
+ */
+export type ITempoResponses = {
+  start: (fn: ITempoStartFn, offset?: number, name?: string) => ITempoResponses;
+  progress: (
+    fn: ITempoProgressFn,
+    offset?: number,
+    name?: string,
+  ) => ITempoResponses;
+};
+
+/**
+ * Typescript type: ISoundAnalyzer represents an object that stores the AnalyzerNode properties
+ */
+export type ISoundAnalyzer = {
+  node: AnalyserNode;
+  size: number;
+  data: Uint8Array;
+};
+
+/**
+ * Typescript type: SoundType represents a type of sound input. It corresponds to Sound.type property.
+ */
+export type SoundType = "file" | "gen" | "input";
+
+/**
+ * Typescript type: DefaultFormStyle represents a default object for visual styles such as fill, stroke, line width, and others.
+ */
+export type DefaultFormStyle = {
+  fillStyle?: string | CanvasGradient | CanvasPattern;
+  strokeStyle?: string | CanvasGradient | CanvasPattern;
+  lineWidth?: number;
+  lineJoin?: CanvasLineJoin;
+  lineCap?: CanvasLineCap;
+  globalAlpha?: number;
+};
+
+/**
+ * Typescript type: CanvasPatternRepetition represents the string options to specify pattern repetition
+ */
+export type CanvasPatternRepetition =
+  "repeat" | "repeat-x" | "repeat-y" | "no-repeat";
+
+export type RenderingContext2D =
+  CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;

package/src/Typography.ts

@@ -0,0 +1,228 @@
+/*! Pts.js is licensed under Apache License 2.0. Copyright © 2017-current William Ngan and contributors. (https://github.com/williamngan/pts) */
+
+import { Pt, Bound } from "./Pt";
+import { Util } from "./Util";
+import { type PtLikeIterable, type TextMeasure } from "./Types";
+
+/**
+ * Typography provides helper functions to support typographic layouts. For a concrete example, see [a demo here](https://ptsjs.org/demo/?name=canvasform.textBox) that uses the [`CanvasForm.textBox`](#link) function.
+ */
+export class Typography {
+  /**
+   * Create a heuristic text width estimate function. It will be less accurate but faster.
+   * @param fn a reference function that can measure text width accurately
+   * @param samples a list of string samples. Default is ["M", "n", "."]
+   * @param distribution a list of the samples' probability distribution, which should have the same length as `samples` and sum to 1. Default is [0.06, 0.8, 0.14]. (A distribution that sums to more or less than 1 will proportionally inflate or deflate every estimate.)
+   * @return a function that can estimate text width
+   */
+  static textWidthEstimator(
+    fn: TextMeasure,
+    samples: string[] = ["M", "n", "."],
+    distribution: number[] = [0.06, 0.8, 0.14],
+  ): TextMeasure {
+    if (samples.length !== distribution.length) {
+      throw new Error(
+        `textWidthEstimator: samples (${samples.length}) and distribution (${distribution.length}) must have the same length`,
+      );
+    }
+    const m = samples.map(fn);
+    const avg = new Pt(distribution).dot(m);
+    return (text: string): number => text.length * avg;
+  }
+
+  /**
+   * Create a memoizing text width function that measures each distinct character once and sums the cached widths. Nearly as accurate as the reference function for most texts (kerning and ligatures excepted) at close to estimator speed after warmup. The cache is keyed by character, so create a new instance whenever the font changes.
+   * @param fn a reference function that can measure text width accurately
+   * @return a function that measures text width using per-character caching
+   */
+  static charWidthCache(fn: TextMeasure): TextMeasure {
+    // Latin-1 goes through a typed array — a Map lookup per character would
+    // cost as much as the measurement it replaces. NaN marks "not yet measured".
+    const latin = new Float64Array(256).fill(NaN);
+    const cache = new Map<string, number>();
+    return (text: string): number => {
+      let sum = 0;
+      for (let i = 0, len = text.length; i < len; i++) {
+        const code = text.charCodeAt(i);
+        if (code < 256) {
+          let w = latin[code];
+          if (w !== w) {
+            w = fn(text[i]);
+            latin[code] = w;
+          }
+          sum += w;
+        } else {
+          let ch = text[i];
+          if (code >= 0xd800 && code <= 0xdbff && i + 1 < len) {
+            ch += text[i + 1]; // measure a surrogate pair as one character
+            i++;
+          }
+          let w = cache.get(ch);
+          if (w === undefined) {
+            w = fn(ch);
+            cache.set(ch, w);
+          }
+          sum += w;
+        }
+      }
+      return sum;
+    };
+  }
+
+  /**
+   * Truncate text to fit width. The result is guaranteed to fit: the largest prefix (possibly empty) is kept such that the prefix plus the tail measures within `width`. The cut never splits a surrogate pair. If even the tail alone cannot fit, `["", 0]` is returned.
+   * @param fn a function that can measure text width
+   * @param str text to truncate
+   * @param width width to fit
+   * @param tail text to indicate overflow such as "...". Default is empty "".
+   * @param hint optional expected number of characters to keep — a pure performance hint (any value yields the same result) that seeds the search, such as the previous line's length when wrapping. With an empty `tail`, a hint also avoids measuring the entire string.
+   * @return a tuple of the truncated text (tail included) and the number of characters kept from `str`
+   */
+  static truncate(
+    fn: TextMeasure,
+    str: string,
+    width: number,
+    tail: string = "",
+    hint?: number,
+  ): [string, number] {
+    const len = str.length;
+    let budget: number;
+    let max: number;
+    let seed: number;
+
+    if (hint !== undefined && !tail) {
+      // Hinted search with no tail: skip the full-string measure. The domain
+      // includes `len` itself, so "everything fits" is discovered by the
+      // search rather than by a separate upfront measurement.
+      budget = width;
+      max = len;
+      seed = Math.min(max, Math.max(0, Math.floor(hint)));
+    } else {
+      const full = fn(str);
+      if (full <= width) return [str, len];
+      budget = width - (tail ? fn(tail) : 0);
+      max = len - 1;
+      seed =
+        hint !== undefined
+          ? Math.min(max, Math.max(0, Math.floor(hint)))
+          : Math.min(max, Math.max(0, Math.floor((len * budget) / full)));
+    }
+
+    const fits = (k: number): boolean => fn(str.slice(0, k)) <= budget;
+
+    // Find the largest k in [0, max] where the prefix fits, starting from the
+    // seed — exact for linear measures, so the gallop below usually settles
+    // the boundary in two probes.
+    let best = -1;
+    let lo = 0;
+    let hi = max;
+
+    if (budget >= 0) {
+      const k = seed;
+      if (fits(k)) {
+        best = k;
+        lo = k + 1;
+        for (let inc = 1; lo <= hi; inc *= 2) {
+          const p = Math.min(hi, k + inc);
+          if (!fits(p)) {
+            hi = p - 1;
+            break;
+          }
+          best = p;
+          lo = p + 1;
+        }
+      } else {
+        hi = k - 1;
+        for (let inc = 1; lo <= hi; inc *= 2) {
+          const p = Math.max(lo, k - inc);
+          if (fits(p)) {
+            best = p;
+            lo = p + 1;
+            break;
+          }
+          hi = p - 1;
+        }
+      }
+      while (lo <= hi) {
+        const p = (lo + hi) >> 1;
+        if (fits(p)) {
+          best = p;
+          lo = p + 1;
+        } else {
+          hi = p - 1;
+        }
+      }
+    }
+
+    if (best < 0) return ["", 0];
+    if (best === len) return [str, len]; // hinted search found the whole string fits
+
+    // Don't cut between a surrogate pair's halves; a shorter prefix still fits.
+    let cut = best;
+    if (cut > 0) {
+      const code = str.charCodeAt(cut - 1);
+      if (code >= 0xd800 && code <= 0xdbff) cut--;
+    }
+
+    return [str.slice(0, cut) + tail, cut];
+  }
+
+  /**
+   * Get a function to scale font size proportionally to a box's size. (Deprecated form: passing an initial box as the first parameter is deprecated — it never affected the result — and will be removed in a future version.)
+   * @param ratio font-size to box-size ratio. Default is 1.
+   * @param byHeight `true` to scale by the box's height, `false` to scale by its width. Default is `true`.
+   * @returns a function where input parameter is a box, and returns a font size value (`ratio` multiplied by the box's height or width)
+   */
+  static fontSizeToBox(
+    ratio?: number,
+    byHeight?: boolean,
+  ): (box: PtLikeIterable) => number;
+  /**
+   * @deprecated The initial box never affected the result. Use `fontSizeToBox(ratio, byHeight)` instead.
+   */
+  static fontSizeToBox(
+    box: PtLikeIterable,
+    ratio?: number,
+    byHeight?: boolean,
+  ): (box: PtLikeIterable) => number;
+  static fontSizeToBox(
+    ratio: number | PtLikeIterable = 1,
+    byHeight: boolean | number = true,
+    legacyByHeight?: boolean,
+  ): (box: PtLikeIterable) => number {
+    if (typeof ratio !== "number") {
+      Util.warn(
+        "Typography.fontSizeToBox(box, ratio, byHeight) is deprecated: the initial box never affected the result. Use fontSizeToBox(ratio, byHeight) instead.",
+      );
+      ratio = typeof byHeight === "number" ? byHeight : 1;
+      byHeight = legacyByHeight === undefined ? true : legacyByHeight;
+    }
+    const r = ratio as number;
+    const by = byHeight as boolean;
+    return (box: PtLikeIterable): number => {
+      const bound = Bound.fromGroup(box);
+      return r * (by ? bound.height : bound.width);
+    };
+  }
+
+  /**
+   * Get a function to scale font size based on a threshold value.
+   * @param threshold threshold value. Cannot be 0.
+   * @param direction if negative, get a font size <= defaultSize; if positive, get a font size >= defaultSize; Default is 0 which will scale font without min or max limits.
+   * @returns a function whose input parameters are a default font size and a value to compare with threshold, and which returns a new font size value
+   */
+  static fontSizeToThreshold(
+    threshold: number,
+    direction: number = 0,
+  ): (defaultSize: number, val: number) => number {
+    if (threshold === 0) {
+      throw new Error("fontSizeToThreshold: threshold cannot be 0");
+    }
+    return function (defaultSize: number, val: number): number {
+      const d = (defaultSize * val) / threshold;
+      if (direction < 0) return Math.min(d, defaultSize);
+      if (direction > 0) return Math.max(d, defaultSize);
+      return d;
+    };
+  }
+}