@classytic/stage 0.2.0 → 0.4.0

package/dist/primitives/Lines.d.mts

@@ -1,50 +1,22 @@
 import { Vec2 } from "../core/vec.mjs";
 import { StyleProps } from "./props.mjs";
-import { ReactNode } from "react";
 
 //#region src/primitives/Lines.d.ts
 interface SegmentProps extends StyleProps {
   from: Vec2;
   to: Vec2;
 }
-declare function Segment({
-  from,
-  to,
-  color,
-  weight,
-  opacity,
-  dashed
-}: SegmentProps): ReactNode;
+declare const Segment: import("react").NamedExoticComponent<SegmentProps>;
 interface LineProps extends StyleProps {
   from: Vec2;
   to: Vec2;
 }
-declare function Line({
-  from,
-  to,
-  color,
-  weight,
-  opacity,
-  dashed
-}: LineProps): ReactNode;
-declare function Ray({
-  from,
-  to,
-  color,
-  weight,
-  opacity,
-  dashed
-}: LineProps): ReactNode;
+declare const Line: import("react").NamedExoticComponent<LineProps>;
+declare const Ray: import("react").NamedExoticComponent<LineProps>;
 interface VectorProps extends StyleProps {
   tail?: Vec2;
   tip: Vec2;
 }
-declare function Vector({
-  tail,
-  tip,
-  color,
-  weight,
-  opacity
-}: VectorProps): ReactNode;
+declare const Vector: import("react").NamedExoticComponent<VectorProps>;
 //#endregion
 export { Line, LineProps, Ray, Segment, SegmentProps, Vector, VectorProps };

package/dist/primitives/Lines.mjs

@@ -2,6 +2,8 @@
 
 import { fmt } from "../core/coords.mjs";
 import { useCoords } from "../core/context.mjs";
+import { geomPropsEqual } from "./props.mjs";
+import { memo } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/primitives/Lines.tsx
@@ -14,7 +16,7 @@ const extend = (c, a, b, back) => {
 	const big = Math.hypot(c.width, c.height) * 2;
 	return [back ? [a[0] - ux * big, a[1] - uy * big] : a, [a[0] + ux * big, a[1] + uy * big]];
 };
-function Segment({ from, to, color = "var(--stage-fg)", weight = 2, opacity = 1, dashed }) {
+const Segment = memo(function Segment({ from, to, color = "var(--stage-fg)", weight = 2, opacity = 1, dashed }) {
 	const c = useCoords();
 	const a = c.toPx(from.x, from.y);
 	const b = c.toPx(to.x, to.y);
@@ -29,8 +31,8 @@ function Segment({ from, to, color = "var(--stage-fg)", weight = 2, opacity = 1,
 		strokeLinecap: "round",
 		strokeDasharray: dashed ? "6 6" : void 0
 	});
-}
-function Line({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, dashed }) {
+}, geomPropsEqual);
+const Line = memo(function Line({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, dashed }) {
 	const c = useCoords();
 	const [p1, p2] = extend(c, c.toPx(from.x, from.y), c.toPx(to.x, to.y), true);
 	return /* @__PURE__ */ jsx("line", {
@@ -43,8 +45,8 @@ function Line({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1,
 		opacity,
 		strokeDasharray: dashed ? "6 6" : void 0
 	});
-}
-function Ray({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, dashed }) {
+}, geomPropsEqual);
+const Ray = memo(function Ray({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, dashed }) {
 	const c = useCoords();
 	const [p1, p2] = extend(c, c.toPx(from.x, from.y), c.toPx(to.x, to.y), false);
 	return /* @__PURE__ */ jsx("line", {
@@ -57,8 +59,8 @@ function Ray({ from, to, color = "var(--stage-axis)", weight = 2, opacity = 1, d
 		opacity,
 		strokeDasharray: dashed ? "6 6" : void 0
 	});
-}
-function Vector({ tail = {
+}, geomPropsEqual);
+const Vector = memo(function Vector({ tail = {
 	x: 0,
 	y: 0
 }, tip, color = "var(--stage-accent-2)", weight = 2.5, opacity = 1 }) {
@@ -76,7 +78,7 @@ function Vector({ tail = {
 		strokeLinecap: "round",
 		markerEnd: "url(#stage-arrow)"
 	});
-}
+}, geomPropsEqual);
 
 //#endregion
 export { Line, Ray, Segment, Vector };

package/dist/primitives/Shapes.d.mts

@@ -1,6 +1,5 @@
 import { Vec2 } from "../core/vec.mjs";
 import { StyleProps } from "./props.mjs";
-import { ReactNode } from "react";
 
 //#region src/primitives/Shapes.d.ts
 interface CircleProps extends StyleProps {
@@ -9,15 +8,7 @@ interface CircleProps extends StyleProps {
   fill?: string;
   fillOpacity?: number;
 }
-declare function Circle({
-  center,
-  r,
-  color,
-  fill,
-  fillOpacity,
-  weight,
-  opacity
-}: CircleProps): ReactNode;
+declare const Circle: import("react").NamedExoticComponent<CircleProps>;
 interface EllipseProps extends StyleProps {
   center: Vec2;
   rx: number;
@@ -25,52 +16,23 @@ interface EllipseProps extends StyleProps {
   fill?: string;
   fillOpacity?: number;
 }
-declare function Ellipse({
-  center,
-  rx,
-  ry,
-  color,
-  fill,
-  fillOpacity,
-  weight,
-  opacity
-}: EllipseProps): ReactNode;
+declare const Ellipse: import("react").NamedExoticComponent<EllipseProps>;
 interface PolygonProps extends StyleProps {
   points: Vec2[];
   fill?: string;
   fillOpacity?: number;
 }
-declare function Polygon({
-  points,
-  color,
-  fill,
-  fillOpacity,
-  weight,
-  opacity
-}: PolygonProps): ReactNode;
+declare const Polygon: import("react").NamedExoticComponent<PolygonProps>;
 interface PolylineProps extends StyleProps {
   points: Vec2[];
 }
-declare function Polyline({
-  points,
-  color,
-  weight,
-  opacity,
-  dashed
-}: PolylineProps): ReactNode;
+declare const Polyline: import("react").NamedExoticComponent<PolylineProps>;
 /** Low-level pixel-space path (d is already in pixels). */
 interface PathProps extends StyleProps {
   d: string;
   fill?: string;
   fillOpacity?: number;
 }
-declare function Path({
-  d,
-  color,
-  fill,
-  fillOpacity,
-  weight,
-  opacity
-}: PathProps): ReactNode;
+declare const Path: import("react").NamedExoticComponent<PathProps>;
 //#endregion
 export { Circle, CircleProps, Ellipse, EllipseProps, Path, PathProps, Polygon, PolygonProps, Polyline, PolylineProps };

package/dist/primitives/Shapes.mjs

@@ -2,6 +2,8 @@
 
 import { fmt } from "../core/coords.mjs";
 import { useCoords } from "../core/context.mjs";
+import { geomPropsEqual } from "./props.mjs";
+import { memo } from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/primitives/Shapes.tsx
@@ -9,7 +11,7 @@ const toPoints = (c, points) => points.map((p) => {
 	const [x, y] = c.toPx(p.x, p.y);
 	return `${fmt(x)},${fmt(y)}`;
 }).join(" ");
-function Circle({ center, r, color = "var(--stage-accent)", fill = "none", fillOpacity = .12, weight = 2, opacity = 1 }) {
+const Circle = memo(function Circle({ center, r, color = "var(--stage-accent)", fill = "none", fillOpacity = .12, weight = 2, opacity = 1 }) {
 	const c = useCoords();
 	const [cx, cy] = c.toPx(center.x, center.y);
 	return /* @__PURE__ */ jsx("ellipse", {
@@ -23,8 +25,8 @@ function Circle({ center, r, color = "var(--stage-accent)", fill = "none", fillO
 		fillOpacity: fill === "none" ? void 0 : fillOpacity,
 		opacity
 	});
-}
-function Ellipse({ center, rx, ry, color = "var(--stage-accent)", fill = "none", fillOpacity = .12, weight = 2, opacity = 1 }) {
+}, geomPropsEqual);
+const Ellipse = memo(function Ellipse({ center, rx, ry, color = "var(--stage-accent)", fill = "none", fillOpacity = .12, weight = 2, opacity = 1 }) {
 	const c = useCoords();
 	const [cx, cy] = c.toPx(center.x, center.y);
 	return /* @__PURE__ */ jsx("ellipse", {
@@ -38,8 +40,8 @@ function Ellipse({ center, rx, ry, color = "var(--stage-accent)", fill = "none",
 		fillOpacity: fill === "none" ? void 0 : fillOpacity,
 		opacity
 	});
-}
-function Polygon({ points, color = "var(--stage-accent)", fill = "var(--stage-accent)", fillOpacity = .12, weight = 2, opacity = 1 }) {
+}, geomPropsEqual);
+const Polygon = memo(function Polygon({ points, color = "var(--stage-accent)", fill = "var(--stage-accent)", fillOpacity = .12, weight = 2, opacity = 1 }) {
 	return /* @__PURE__ */ jsx("polygon", {
 		points: toPoints(useCoords(), points),
 		stroke: color,
@@ -49,8 +51,8 @@ function Polygon({ points, color = "var(--stage-accent)", fill = "var(--stage-ac
 		opacity,
 		strokeLinejoin: "round"
 	});
-}
-function Polyline({ points, color = "var(--stage-fg)", weight = 2, opacity = 1, dashed }) {
+}, geomPropsEqual);
+const Polyline = memo(function Polyline({ points, color = "var(--stage-fg)", weight = 2, opacity = 1, dashed }) {
 	return /* @__PURE__ */ jsx("polyline", {
 		points: toPoints(useCoords(), points),
 		fill: "none",
@@ -61,8 +63,8 @@ function Polyline({ points, color = "var(--stage-fg)", weight = 2, opacity = 1,
 		strokeLinecap: "round",
 		strokeDasharray: dashed ? "6 6" : void 0
 	});
-}
-function Path({ d, color = "var(--stage-fg)", fill = "none", fillOpacity = 1, weight = 2, opacity = 1 }) {
+}, geomPropsEqual);
+const Path = memo(function Path({ d, color = "var(--stage-fg)", fill = "none", fillOpacity = 1, weight = 2, opacity = 1 }) {
 	return /* @__PURE__ */ jsx("path", {
 		d,
 		stroke: color,
@@ -73,7 +75,7 @@ function Path({ d, color = "var(--stage-fg)", fill = "none", fillOpacity = 1, we
 		strokeLinejoin: "round",
 		strokeLinecap: "round"
 	});
-}
+}, geomPropsEqual);
 
 //#endregion
 export { Circle, Ellipse, Path, Polygon, Polyline };

package/dist/primitives/index.d.mts

@@ -4,7 +4,7 @@ import { Line, LineProps, Ray, Segment, SegmentProps, Vector, VectorProps } from
 import { Circle, CircleProps, Ellipse, EllipseProps, Path, PathProps, Polygon, PolygonProps, Polyline, PolylineProps } from "./Shapes.mjs";
 import { Label, LabelProps } from "./Label.mjs";
 import { Tex, TexProps } from "./Tex.mjs";
-import { Axes, AxesProps, Grid, GridProps, niceStep } from "./Grid.mjs";
+import { Axes, AxesProps, ClearZone, Grid, GridProps, clearOfLabel, niceStep } from "./Grid.mjs";
 import { OfXProps, OfYProps, ParametricProps, Plot } from "./Plot.mjs";
 import { CanvasLayer, CanvasLayerProps } from "./CanvasLayer.mjs";
-export { type A11yProps, Axes, type AxesProps, CanvasLayer, type CanvasLayerProps, Circle, type CircleProps, Dot, type DotProps, Ellipse, type EllipseProps, Grid, type GridProps, Label, type LabelProps, Line, type LineProps, type OfXProps, type OfYProps, type ParametricProps, Path, type PathProps, Plot, Point, Polygon, type PolygonProps, Polyline, type PolylineProps, Ray, Segment, type SegmentProps, type StyleProps, Tex, type TexProps, Vector, type VectorProps, niceStep };
+export { type A11yProps, Axes, type AxesProps, CanvasLayer, type CanvasLayerProps, Circle, type CircleProps, type ClearZone, Dot, type DotProps, Ellipse, type EllipseProps, Grid, type GridProps, Label, type LabelProps, Line, type LineProps, type OfXProps, type OfYProps, type ParametricProps, Path, type PathProps, Plot, Point, Polygon, type PolygonProps, Polyline, type PolylineProps, Ray, Segment, type SegmentProps, type StyleProps, Tex, type TexProps, Vector, type VectorProps, clearOfLabel, niceStep };

package/dist/primitives/index.mjs

@@ -3,8 +3,8 @@ import { Line, Ray, Segment, Vector } from "./Lines.mjs";
 import { Circle, Ellipse, Path, Polygon, Polyline } from "./Shapes.mjs";
 import { Label } from "./Label.mjs";
 import { Tex } from "./Tex.mjs";
-import { Axes, Grid, niceStep } from "./Grid.mjs";
+import { Axes, Grid, clearOfLabel, niceStep } from "./Grid.mjs";
 import { Plot } from "./Plot.mjs";
 import { CanvasLayer } from "./CanvasLayer.mjs";
 
-export { Axes, CanvasLayer, Circle, Dot, Ellipse, Grid, Label, Line, Path, Plot, Point, Polygon, Polyline, Ray, Segment, Tex, Vector, niceStep };
+export { Axes, CanvasLayer, Circle, Dot, Ellipse, Grid, Label, Line, Path, Plot, Point, Polygon, Polyline, Ray, Segment, Tex, Vector, clearOfLabel, niceStep };

package/dist/primitives/props.mjs

@@ -0,0 +1,31 @@
+//#region src/primitives/props.ts
+const MAX_DEPTH = 4;
+const valEq = (a, b, depth) => {
+	if (Object.is(a, b)) return true;
+	if (depth <= 0) return false;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if ("$$typeof" in a || "$$typeof" in b) return false;
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		for (let i = 0; i < a.length; i++) if (!valEq(a[i], b[i], depth - 1)) return false;
+		return true;
+	}
+	const ka = Object.keys(a);
+	if (ka.length !== Object.keys(b).length) return false;
+	for (const k of ka) {
+		if (!(k in b)) return false;
+		if (!valEq(a[k], b[k], depth - 1)) return false;
+	}
+	return true;
+};
+/**
+* Value-based props comparator for `React.memo` on geometry primitives.
+* Labs recreate `Vec2`/`points` objects every render (often 60×/s under a frame
+* tick), so identity-based memo never hits; comparing coordinate VALUES lets
+* static shapes skip reconciliation while anything that actually moved still
+* re-renders. Functions and React elements compare by reference (safe fallback).
+*/
+const geomPropsEqual = (prev, next) => valEq(prev, next, MAX_DEPTH);
+
+//#endregion
+export { geomPropsEqual };

package/dist/quantity/index.d.mts

@@ -0,0 +1,119 @@
+//#region src/quantity/index.d.ts
+/**
+ * quantity, a number that knows its unit.
+ *
+ * The model: every quantity is stored as its value in SI BASE UNITS plus a dimension vector over
+ * (kg, m, s, mol, K, A). A unit string is a recipe for converting to that pair, so arithmetic is
+ * ordinary arithmetic on the SI values and integer addition on the exponents:
+ *
+ *   a · b  →  si = a.si · b.si,   dim = a.dim + b.dim
+ *   a / b  →  si = a.si / b.si,   dim = a.dim − b.dim
+ *   a ± b  →  requires a.dim = b.dim
+ *
+ * Why this matters more than it looks. "Choose the right formula" is, operationally, "choose the
+ * one whose units cancel to the unit the answer is in", and cm³-against-dm³ is the single most
+ * common arithmetic error in A-level chemistry. Under this model that error cannot be made:
+ *
+ *   qty(0.100, 'mol/dm3').times(qty(24.50, 'cm3'))   →   2.45e-3 mol
+ *
+ * is simply correct, because both volumes reduce to m³ and the factors cancel. (An earlier plan
+ * said this case should THROW, on the grounds that cm³ "is not" dm³. That would be a worse design:
+ * it rejects a valid calculation and leaves the author to do the conversion by hand, which is the
+ * step that goes wrong.) What does throw is genuine nonsense: adding a mass to a volume, or asking
+ * for a mass in dm³.
+ *
+ * SCOPE, deliberately small: dimensional analysis over a fixed table of the units the Cambridge
+ * syllabuses actually use. Not a general units library, not arbitrary dimensional algebra, no
+ * user-defined units. The whole of A-level chemistry and physics fits in the table below.
+ *
+ * Pure: no React, no pixels.
+ */
+/** SI base dimensions. Everything in the table reduces to integer powers of these. */
+declare const BASE: readonly ["kg", "m", "s", "mol", "K", "A"];
+type Base = (typeof BASE)[number];
+/** Integer powers of the base dimensions. Absent key = power 0. */
+type Dimension = Readonly<Partial<Record<Base, number>>>;
+declare const DIMENSIONLESS: Dimension;
+declare const mulDim: (a: Dimension, b: Dimension) => Dimension;
+declare const divDim: (a: Dimension, b: Dimension) => Dimension;
+/** Raise a dimension to an integer power. A fractional power is legal only if it leaves every
+ *  exponent an integer, which is what makes `sqrt(Ka·c)` work and `sqrt(mol)` fail. */
+declare function powDim(a: Dimension, n: number): Dimension;
+declare const sameDim: (a: Dimension, b: Dimension) => boolean;
+declare const isDimensionless: (a: Dimension) => boolean;
+/** For error messages, where "1" would read as a number rather than as "has no units". */
+declare const describeDimension: (d: Dimension) => string;
+/**
+ * "kg·m^2/s^2·mol": readable in an error message AND parseable by `parseUnit`.
+ *
+ * Both properties are required. It names the dimension in messages, and it also names the unit of
+ * a quantity produced by arithmetic, which is then re-read the next time that quantity is used. An
+ * earlier version emitted `m2`, which reads back as an unknown unit rather than as m², so a
+ * perfectly good result became unusable one operation later.
+ */
+declare function formatDimension(d: Dimension): string;
+interface ResolvedUnit {
+  readonly dim: Dimension;
+  readonly factor: number;
+  readonly offset?: number;
+}
+/**
+ * Resolve a unit string to a dimension and a factor.
+ *
+ * Grammar: atoms separated by `·`, `*` or a space are multiplied; **every** segment after a `/` is
+ * a denominator, so `J/K/mol` is J·K⁻¹·mol⁻¹. That reading is the chemistry convention and it is
+ * stated here because `a/b/c` is genuinely ambiguous in general.
+ *
+ * An atom may carry an integer exponent written with a caret: `mol^2`, `dm3^2` (which is dm⁶, the
+ * denominator of a Ksp for a 1:2 salt). The caret is REQUIRED rather than optional, because a
+ * trailing digit is already part of the name in `dm3` and `cm3`, so `dm6` would have to be read as
+ * both a name and a power.
+ */
+declare function parseUnit(spec: string): ResolvedUnit;
+/** The units this kernel knows, for an error message or an editor. */
+declare const knownUnits: () => string[];
+/**
+ * A value with a unit. Immutable: every operation returns a new Quantity.
+ *
+ * `si` is the value in SI base units and is the single source of truth; `unit` is only how it is
+ * currently being displayed.
+ */
+declare class Quantity {
+  readonly si: number;
+  readonly dim: Dimension;
+  readonly unit: string;
+  /** True only for a Celsius temperature. Carried rather than re-derived: see `requireScale`. */
+  private readonly onScale;
+  private constructor();
+  static of(value: number, unit: string): Quantity;
+  /** Build directly from an SI value, naming the unit from the dimension. */
+  static fromSI(si: number, dim: Dimension): Quantity;
+  /** The number, expressed in `this.unit`. */
+  get value(): number;
+  /** The number, expressed in `unit`. Throws if the dimensions differ. */
+  in(unit: string): number;
+  /** The same quantity, displayed in `unit`. */
+  to(unit: string): Quantity;
+  private requireScale;
+  times(other: Quantity | number): Quantity;
+  over(other: Quantity | number): Quantity;
+  plus(other: Quantity): Quantity;
+  /**
+   * Note what this CANNOT do: subtract two Celsius temperatures. The SI difference would be right
+   * (a kelvin interval) but the result would be displayed back on the Celsius scale, where 12.5 K
+   * reads as −260.65 °C. `requireScale` refuses it, and `.to('K')` on both sides is the fix.
+   */
+  minus(other: Quantity): Quantity;
+  pow(n: number): Quantity;
+  private requireSame;
+  /** Equal within a RELATIVE tolerance (default 1e-9), after reducing both to SI. */
+  equals(other: Quantity, tol?: number): boolean;
+  /** "2.45e-3 mol", at `sf` significant figures. */
+  toString(sf?: number): string;
+}
+/** `qty(24.50, 'cm3')`. */
+declare const qty: (value: number, unit: string) => Quantity;
+/** The SI-coherent name for a dimension: 'mol', 'J', or a composed 'kg·m2/s2'. */
+declare function canonicalUnit(dim: Dimension): string;
+//#endregion
+export { Base, DIMENSIONLESS, Dimension, Quantity, canonicalUnit, describeDimension, divDim, formatDimension, isDimensionless, knownUnits, mulDim, parseUnit, powDim, qty, sameDim };