@altpsyche/maths 0.11.0 → 0.13.0

package/dist/index.js

@@ -8,6 +8,7 @@
  * Nothing below the line may import anything above it.
  */
 export { clamp, inverseLerp, lerp, remap } from './values/scalar.js';
+export { colourOf, colourText, lerpColour } from './values/colour.js';
 export { curveFor, easeIn, easeOut, linear, smoothstep } from './values/ease.js';
 export { vec2 } from './values/vec2.js';
 export { vec3 } from './values/vec3.js';
@@ -15,7 +16,7 @@ export { interval } from './values/interval.js';
 export { mat3 } from './values/mat3.js';
 export { mat4 } from './values/mat4.js';
 export { SAME_TIME, keyAt, sampleTrack, sampleTracks, withKey, withoutKey } from './timing/track.js';
-export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, slopeOn, splitCurve, straight, transformPath } from './figure/path.js';
+export { arc, circle, line, polygon, polyline, pointCount, pointOn, rect, splitCurve, straight, tangentOn, transformPath } from './figure/path.js';
 export { pathFromData } from './figure/path-data.js';
 export { TOLERANCE } from './figure/tolerance.js';
 export { areaOf } from './figure/area.js';
@@ -30,10 +31,12 @@ export { vectorField } from './figure/field.js';
 export { streamlineOf } from './figure/streamline.js';
 export { axes, numberLine, numberPlane } from './figure/axis.js';
 export { camera3, orthographic, perspective } from './figure/camera.js';
-export { arrow3, dot3, fieldArrows3, polyline3, space, surface3, surfaceCells, text3, vectorField3 } from './figure/space.js';
+export { arrow3, dot3, polyline3, scene3, text3 } from './figure/space.js';
+export { fieldArrows3, vectorField3 } from './figure/field3.js';
+export { surface3, surfaceCells } from './figure/surface3.js';
 export { axes3 } from './figure/axis3.js';
 export { sectionOf } from './figure/section.js';
-export { coordsOf, pointOf, scaleOf, scaled, unscaled } from './figure/scale.js';
+export { coordsOf, pointOf, scaleOf, toGraph, toUnits } from './figure/scale.js';
 export { labelFor, tickStep, ticksOn } from './figure/ticks.js';
 export { flatten, group, shape, text } from './figure/node.js';
 export { circumscribe, countTo, fadeIn, fadeOut, fadeTo, draw, flash, growFrom, indicate, morph, morphEquation, moveAlong, moveBy, rotate, scale } from './figure/animation.js';
@@ -41,10 +44,11 @@ export { Timeline } from './figure/timeline.js';
 export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
-export { at, durationOf, loops, sameMarks, viewAt } from './figure/figure.js';
-export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
+export { durationOf, isLoop, marksAt, sameMarks, viewAt } from './figure/figure.js';
+export { frameTimesOf, framesOf } from './figure/frames.js';
+export { paintSvg, pathToData, svgElements, svgMarkup } from './paint/svg.js';
 export { paintCanvas } from './paint/canvas.js';
 export { arrow, brace, bracePath, callout, dot } from './figure/annotate.js';
 export { typesetElement } from './figure/typeset.js';
-export { equationFromTex, equationMarks, equationNode } from './figure/equation.js';
+export { equationFromTex, equationNode, equationOf } from './figure/equation.js';
 export { glyphToken, matchGlyphs } from './figure/equation-match.js';

package/dist/paint/number.js

@@ -8,8 +8,7 @@
  */
 const PLACES = 3;
 export function short(value) {
-    // A rounded value that lands on an integer keeps no decimal point, and a
-    // negative zero is written as zero, because otherwise the same coordinate
+    // An integer keeps no decimal point and a negative zero is written as zero, or the same coordinate
     // reached two ways would compare as two strings.
     const rounded = Number(value.toFixed(PLACES));
     return Object.is(rounded, -0) ? '0' : String(rounded);

package/dist/paint/svg.d.ts

@@ -23,18 +23,43 @@ export interface SvgElement {
     attributes: Record<string, string>;
     text?: string;
 }
+/** A colour per ground for one CSS custom property. A mark painted with
+ * `var(--name, colour)` takes the value of the ground it is read on, and the
+ * colour written inside the `var()` is what it falls back to. */
+export interface SvgTheme {
+    [property: string]: {
+        light: string;
+        dark: string;
+    };
+}
+export interface SvgMarkupOptions {
+    /** Written into the markup as a `<style>` element, so one file is read on a
+     * light page and a dark one with no script and no page CSS. */
+    theme?: SvgTheme;
+    /**
+     * The smallest font size written, in the units painted into rather than in
+     * figure units. A view that fits a wide extent scales every figure unit down,
+     * so a glyph readable in one frame is not readable in a row of them.
+     *
+     * Every text size is multiplied by the one factor that brings the smallest of
+     * them to this, which holds the sizes in the ratios the figure gave them.
+     * Raising each size on its own to the floor would flatten two sizes that both
+     * fall under it into one.
+     */
+    minTextSize?: number;
+}
 /** The `d` attribute: a move to the start, a cubic per segment, and a close
  * where the subpath joins back. */
-export declare function pathData(path: Path, view: Mat3): string;
+export declare function pathToData(path: Path, view: Mat3): string;
 /** Every mark described as an element, in the order they are drawn. */
-export declare function svgElements(marks: readonly Mark[], view: Mat3): SvgElement[];
+export declare function svgElements(marks: readonly Mark[], view: Mat3, options?: SvgMarkupOptions): SvgElement[];
 /**
  * A whole `<svg>` as text, for a page that has not run any script yet.
  *
  * It carries no width or height of its own and only a view box, so the element
  * around it decides how big it is and the picture stays where it was put.
  */
-export declare function svgMarkup(marks: readonly Mark[], view: Mat3, width: number, height: number): string;
+export declare function svgMarkup(marks: readonly Mark[], view: Mat3, width: number, height: number, options?: SvgMarkupOptions): string;
 /**
  * Only what a painter needs from a document, named here rather than taken from
  * the DOM types, so this package declares no browser library at all: it can be
@@ -66,4 +91,4 @@ export interface ElementMaker<Made extends PaintNode = PaintNode> {
  * and matching them up first would cost more than it saved while adding a way for
  * two frames to disagree.
  */
-export declare function paintSvg<Made extends PaintNode>(into: PaintTarget<NoInfer<Made>>, marks: readonly Mark[], view: Mat3, maker: ElementMaker<Made>): void;
+export declare function paintSvg<Made extends PaintNode>(into: PaintTarget<NoInfer<Made>>, marks: readonly Mark[], view: Mat3, maker: ElementMaker<Made>, options?: SvgMarkupOptions): void;

package/dist/paint/svg.js

@@ -17,7 +17,7 @@ import { mat3 } from '../values/mat3.js';
 import { short } from './number.js';
 /** The `d` attribute: a move to the start, a cubic per segment, and a close
  * where the subpath joins back. */
-export function pathData(path, view) {
+export function pathToData(path, view) {
     const parts = [];
     for (const subpath of path) {
         const start = mat3.transformPoint(view, subpath.start);
@@ -36,7 +36,7 @@ export function pathData(path, view) {
 function pathElement(mark, view, scale) {
     const attributes = {
         'data-mark': mark.id,
-        d: pathData(mark.path, view),
+        d: pathToData(mark.path, view),
         fill: mark.fill ? mark.fill.colour : 'none',
     };
     if (mark.fill?.rule === 'evenodd')
@@ -57,14 +57,14 @@ function pathElement(mark, view, scale) {
         attributes.opacity = short(mark.opacity);
     return { tag: 'path', attributes };
 }
-function textElement(mark, view, scale) {
+function textElement(mark, view, scale, lift) {
     const at = mat3.transformPoint(view, mark.at);
     const attributes = {
         'data-mark': mark.id,
         x: short(at.x),
         y: short(at.y),
         'font-family': mark.family,
-        'font-size': short(mark.size * scale),
+        'font-size': short(mark.size * scale * lift),
         fill: mark.fill.colour,
     };
     if (mark.weight !== undefined)
@@ -77,23 +77,59 @@ function textElement(mark, view, scale) {
         attributes.opacity = short(mark.opacity);
     return { tag: 'text', attributes, text: mark.text };
 }
+/**
+ * What every text size is multiplied by so the smallest of them reaches the
+ * floor, or one where they already do and where no text is drawn at all.
+ */
+function textLift(marks, scale, floor) {
+    if (floor <= 0)
+        return 1;
+    const written = marks.filter((mark) => mark.kind === 'text').map((mark) => mark.size * scale);
+    const smallest = Math.min(...written.filter((size) => size > 0));
+    if (!Number.isFinite(smallest))
+        return 1;
+    return Math.max(1, floor / smallest);
+}
 /** Every mark described as an element, in the order they are drawn. */
-export function svgElements(marks, view) {
+export function svgElements(marks, view, options = {}) {
     const scale = mat3.scaleFactor(view);
-    return marks.map((mark) => (mark.kind === 'path' ? pathElement(mark, view, scale) : textElement(mark, view, scale)));
+    const lift = textLift(marks, scale, options.minTextSize ?? 0);
+    return marks.map((mark) => mark.kind === 'path' ? pathElement(mark, view, scale) : textElement(mark, view, scale, lift));
 }
 /** The five characters that would otherwise close a tag or open an entity. */
 function escaped(value) {
     return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
+const PROPERTY = /^[A-Za-z0-9_-]+$/;
+/** A value safe to write between `<style>` tags: no delimiter that would end the
+ * declaration or the element. */
+function plainValue(value) {
+    return !/[<>&{};"]/.test(value);
+}
+/**
+ * The theme as a `<style>` element, the light ground on `:root` and the dark one
+ * behind `prefers-color-scheme`.
+ *
+ * An entry whose name or either colour would need escaping is left out, which
+ * leaves the mark on the colour written inside its own `var()` rather than on a
+ * value that could close the element.
+ */
+function themeStyle(theme) {
+    const names = Object.keys(theme).filter((name) => PROPERTY.test(name) && plainValue(theme[name].light) && plainValue(theme[name].dark));
+    if (names.length === 0)
+        return '';
+    const block = (ground) => names.map((name) => `--${name}:${theme[name][ground]}`).join(';');
+    return `<style>:root{${block('light')}}@media(prefers-color-scheme:dark){:root{${block('dark')}}}</style>`;
+}
 /**
  * A whole `<svg>` as text, for a page that has not run any script yet.
  *
  * It carries no width or height of its own and only a view box, so the element
  * around it decides how big it is and the picture stays where it was put.
  */
-export function svgMarkup(marks, view, width, height) {
-    const body = svgElements(marks, view)
+export function svgMarkup(marks, view, width, height, options = {}) {
+    const style = options.theme ? themeStyle(options.theme) : '';
+    const body = svgElements(marks, view, options)
         .map((element) => {
         const attributes = Object.entries(element.attributes)
             .map(([name, value]) => `${name}="${escaped(value)}"`)
@@ -103,7 +139,7 @@ export function svgMarkup(marks, view, width, height) {
         return `<${element.tag} ${attributes}>${escaped(element.text)}</${element.tag}>`;
     })
         .join('');
-    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${short(width)} ${short(height)}">${body}</svg>`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${short(width)} ${short(height)}">${style}${body}</svg>`;
 }
 const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
 /**
@@ -115,11 +151,10 @@ const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
  * two frames to disagree.
  */
 export function paintSvg(
-// The maker alone says what kind of element this is. Read from the target as
-// well, a real element would offer the whole union its own call accepts, text
-// included, and that union is not a thing this painter can set an attribute on.
-into, marks, view, maker) {
-    const elements = svgElements(marks, view);
+// The maker alone says what kind of element this is: read from the target as well, a real element
+// would offer the whole union its own call accepts, which is not one this painter can write to.
+into, marks, view, maker, options = {}) {
+    const elements = svgElements(marks, view, options);
     into.replaceChildren(...elements.map((element) => {
         const node = maker.createElementNS(SVG_NAMESPACE, element.tag);
         for (const [name, value] of Object.entries(element.attributes))

package/dist/values/colour.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Reading a colour out of the text a figure is written with, so two of them can
+ * be walked between.
+ *
+ * A colour here is a string, which is what both painters take and what a CSS
+ * author already knows how to write. Nothing reads it back, so an animation that
+ * wants to cross-fade has nothing to work with. This reads the two forms a figure
+ * is actually handed, hex and `rgb()`, and refuses every other form rather than
+ * guessing at it: a named colour or an `hsl()` read as black is a wrong picture
+ * with nothing to say it went wrong.
+ */
+/** A colour read out of its text, each channel nothing to 255 and the alpha
+ * nothing to one. */
+export interface Rgba {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+/**
+ * A colour read out of its text, or nothing where the form is one this does not
+ * read.
+ *
+ * Hex takes three, four, six or eight digits, which are the short forms with and
+ * without an alpha and the long ones. `rgb()` and `rgba()` take their channels
+ * separated by commas or by spaces, as numbers or as percentages, and either name
+ * takes an alpha, since CSS stopped keeping them apart.
+ */
+export declare function colourOf(colour: string): Rgba | undefined;
+/** A colour written back out, as `rgb()` where it is opaque and `rgba()` where it
+ * is not, with the channels rounded so the same colour reached two ways is the
+ * same string. */
+export declare function colourText({ r, g, b, a }: Rgba): string;
+/**
+ * A colour a fraction of the way from one to another, or nothing where either
+ * end is a form `colourOf` does not read.
+ *
+ * The walk is straight through each channel in sRGB, which is what CSS mixes in
+ * when nothing names a space. Mixing in a space with even lightness would keep a
+ * mid-point from going dull, and that is a different call with a different name
+ * rather than a quiet change to this one.
+ */
+export declare function lerpColour(from: string, to: string, along: number): string | undefined;

package/dist/values/colour.js

@@ -0,0 +1,110 @@
+/**
+ * Reading a colour out of the text a figure is written with, so two of them can
+ * be walked between.
+ *
+ * A colour here is a string, which is what both painters take and what a CSS
+ * author already knows how to write. Nothing reads it back, so an animation that
+ * wants to cross-fade has nothing to work with. This reads the two forms a figure
+ * is actually handed, hex and `rgb()`, and refuses every other form rather than
+ * guessing at it: a named colour or an `hsl()` read as black is a wrong picture
+ * with nothing to say it went wrong.
+ */
+const HEX = /^#([0-9a-f]{3,8})$/i;
+const FUNCTIONAL = /^rgba?\(([^)]*)\)$/i;
+function channel(text, top) {
+    const trimmed = text.trim();
+    if (trimmed === '')
+        return undefined;
+    const percent = trimmed.endsWith('%');
+    const value = Number(percent ? trimmed.slice(0, -1) : trimmed);
+    if (!Number.isFinite(value))
+        return undefined;
+    return percent ? (value / 100) * top : value;
+}
+/**
+ * A colour read out of its text, or nothing where the form is one this does not
+ * read.
+ *
+ * Hex takes three, four, six or eight digits, which are the short forms with and
+ * without an alpha and the long ones. `rgb()` and `rgba()` take their channels
+ * separated by commas or by spaces, as numbers or as percentages, and either name
+ * takes an alpha, since CSS stopped keeping them apart.
+ */
+export function colourOf(colour) {
+    const text = colour.trim();
+    const hex = HEX.exec(text);
+    if (hex) {
+        const digits = hex[1];
+        if (digits.length === 3 || digits.length === 4) {
+            const parts = [...digits].map((digit) => Number.parseInt(digit + digit, 16));
+            return { r: parts[0], g: parts[1], b: parts[2], a: parts[3] === undefined ? 1 : parts[3] / 255 };
+        }
+        if (digits.length === 6 || digits.length === 8) {
+            const parts = [0, 2, 4, 6]
+                .filter((at) => at < digits.length)
+                .map((at) => Number.parseInt(digits.slice(at, at + 2), 16));
+            return { r: parts[0], g: parts[1], b: parts[2], a: parts[3] === undefined ? 1 : parts[3] / 255 };
+        }
+        return undefined;
+    }
+    const call = FUNCTIONAL.exec(text);
+    if (!call)
+        return undefined;
+    const inside = call[1].includes(',') ? call[1].split(',') : call[1].replace('/', ' ').split(/\s+/);
+    const parts = inside.map((part) => part.trim()).filter((part) => part !== '');
+    if (parts.length < 3 || parts.length > 4)
+        return undefined;
+    const r = channel(parts[0], 255);
+    const g = channel(parts[1], 255);
+    const b = channel(parts[2], 255);
+    const a = parts[3] === undefined ? 1 : channel(parts[3], 1);
+    if (r === undefined || g === undefined || b === undefined || a === undefined)
+        return undefined;
+    return { r, g, b, a };
+}
+/** A colour written back out, as `rgb()` where it is opaque and `rgba()` where it
+ * is not, with the channels rounded so the same colour reached two ways is the
+ * same string. */
+export function colourText({ r, g, b, a }) {
+    const whole = (value) => Math.round(Math.min(255, Math.max(0, value)));
+    const parts = `${whole(r)}, ${whole(g)}, ${whole(b)}`;
+    if (a >= 1)
+        return `rgb(${parts})`;
+    return `rgba(${parts}, ${Number(Math.min(1, Math.max(0, a)).toFixed(3))})`;
+}
+const VARIABLE = /^var\(\s*--[A-Za-z0-9_-]+\s*,\s*(.+)\)$/;
+/**
+ * The colour a `var()` names as its fallback, or the text unchanged where it is
+ * not one.
+ *
+ * A themed colour is painted as `var(--ink, #1b1b1b)`, and the fallback is a
+ * colour written in a form `colourOf` already reads, so mixing from it is mixing
+ * from a stated value. The mix runs through that value on every ground, so a
+ * themed colour cross-faded on a dark page starts from its light end.
+ */
+function statedValue(colour) {
+    const call = VARIABLE.exec(colour.trim());
+    return call ? call[1].trim() : colour;
+}
+/**
+ * A colour a fraction of the way from one to another, or nothing where either
+ * end is a form `colourOf` does not read.
+ *
+ * The walk is straight through each channel in sRGB, which is what CSS mixes in
+ * when nothing names a space. Mixing in a space with even lightness would keep a
+ * mid-point from going dull, and that is a different call with a different name
+ * rather than a quiet change to this one.
+ */
+export function lerpColour(from, to, along) {
+    const start = colourOf(statedValue(from));
+    const end = colourOf(statedValue(to));
+    if (!start || !end)
+        return undefined;
+    const at = (a, b) => a + (b - a) * along;
+    return colourText({
+        r: at(start.r, end.r),
+        g: at(start.g, end.g),
+        b: at(start.b, end.b),
+        a: at(start.a, end.a),
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altpsyche/maths",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
   "license": "MIT",
   "author": "Siva",