@classytic/labs 0.1.0 → 0.3.0

package/dist/kit/figure/figure.mjs

@@ -0,0 +1,99 @@
+'use client';
+
+import { createContext, useContext, useId } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/figure/figure.tsx
+/**
+* Figure, the root of every hand-drawn scene.
+*
+* One `<svg class="lab-figure">` that carries the art-direction tokens (styles/figure.css),
+* the domain palette (`data-fig-domain`), a shared `<defs>` block (soft shadow, glow) and a
+* context so primitives can reference those defs without inventing ids. Labs compose the
+* primitives in this folder inside it and never set stroke widths, hex colours or font sizes
+* themselves.
+*
+*   <Figure viewBox={[720, 380]} domain="chem" label="Reaction vessel at 300 K">
+*     <Glass x={28} y={64} w={284} h={268} fill={0.6} />
+*     <Ball cx={100} cy={100} r={6} />
+*     <FigText x={170} y={52} size="title">reaction vessel</FigText>
+*   </Figure>
+*/
+const Ctx = createContext(null);
+/** Stable id prefix for defs inside the nearest <Figure>. */
+function useFigureId() {
+	return useContext(Ctx)?.uid ?? "fig";
+}
+/** `url(#…)` reference to a shared def (`shadow`, `glow`) or a caller-registered one. */
+const figUrl = (uid, name) => `url(#${uid}-${name})`;
+function Figure({ viewBox, domain, label, className, style, preserveAspectRatio, decorative = false, children }) {
+	const uid = useId().replace(/:/g, "");
+	const vb = typeof viewBox === "string" ? viewBox : `0 0 ${viewBox[0]} ${viewBox[1]}`;
+	return /* @__PURE__ */ jsx(Ctx.Provider, {
+		value: { uid },
+		children: /* @__PURE__ */ jsxs("svg", {
+			className: ["lab-figure", className].filter(Boolean).join(" "),
+			"data-fig-domain": domain,
+			viewBox: vb,
+			preserveAspectRatio,
+			style,
+			role: decorative ? void 0 : "img",
+			"aria-label": decorative ? void 0 : label,
+			"aria-hidden": decorative || void 0,
+			children: [/* @__PURE__ */ jsxs("defs", { children: [/* @__PURE__ */ jsx("filter", {
+				id: `${uid}-shadow`,
+				x: "-20%",
+				y: "-20%",
+				width: "140%",
+				height: "160%",
+				children: /* @__PURE__ */ jsx("feDropShadow", {
+					dx: "0",
+					dy: "1.5",
+					stdDeviation: "2",
+					style: { floodColor: "var(--fig-shadow)" }
+				})
+			}), /* @__PURE__ */ jsx("filter", {
+				id: `${uid}-glow`,
+				x: "-50%",
+				y: "-50%",
+				width: "200%",
+				height: "200%",
+				children: /* @__PURE__ */ jsx("feGaussianBlur", { stdDeviation: "3" })
+			})] }), children]
+		})
+	});
+}
+const STROKE = {
+	hair: 1,
+	line: 1.75,
+	edge: 2.5,
+	bold: 3.5
+};
+/** Colour roles a lab may use; anything else is a bug. */
+const HUE = {
+	1: "var(--fig-hue-1)",
+	2: "var(--fig-hue-2)",
+	3: "var(--fig-hue-3)",
+	ink: "var(--fig-ink)",
+	soft: "var(--fig-ink-soft)",
+	paper: "var(--fig-paper)",
+	hot: "var(--fig-hot)",
+	cold: "var(--fig-cold)",
+	good: "var(--fig-good)",
+	warn: "var(--fig-warn)",
+	danger: "var(--fig-danger)",
+	metal: "var(--fig-metal)",
+	wood: "var(--fig-wood)",
+	glass: "var(--fig-glass)",
+	liquid: "var(--fig-liquid)"
+};
+/** A colour mixed toward the paper (for fills that must recede in both themes). */
+const tint = (color, pct) => `color-mix(in oklab, ${color} ${pct}%, var(--fig-paper))`;
+/** A colour mixed toward the ink (for outlines of a filled shape). */
+const shade = (color, pct = 70) => `color-mix(in oklab, ${color} ${pct}%, var(--fig-ink))`;
+/** A colour at reduced alpha (for glows and shaded areas). */
+const alpha = (color, pct) => `color-mix(in oklab, ${color} ${pct}%, transparent)`;
+const fmt = (n, digits = 1) => Number(n.toFixed(digits)).toString();
+
+//#endregion
+export { Figure, HUE, STROKE, alpha, figUrl, fmt, shade, tint, useFigureId };

package/dist/kit/figure/illustration.d.mts

@@ -0,0 +1,28 @@
+import { ReactNode } from "react";
+
+//#region src/kit/figure/illustration.d.ts
+interface IllustrationProps {
+  /** Light-theme asset URL (the host's `public/…`). */
+  src: string;
+  /** Dark-theme asset URL; falls back to `src`. */
+  srcDark?: string;
+  /** The text alternative; say what the picture shows, not that it is a picture. */
+  alt: string;
+  /** width / height, reserves space before load (default 16/9). */
+  ratio?: number;
+  caption?: ReactNode;
+  /** `eager` for the hero above the fold. */
+  loading?: 'lazy' | 'eager';
+  className?: string;
+}
+declare function Illustration({
+  src,
+  srcDark,
+  alt,
+  ratio,
+  caption,
+  loading,
+  className
+}: IllustrationProps): ReactNode;
+//#endregion
+export { Illustration, IllustrationProps };

package/dist/kit/figure/illustration.mjs

@@ -0,0 +1,31 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/figure/illustration.tsx
+function Illustration({ src, srcDark, alt, ratio = 16 / 9, caption, loading = "lazy", className }) {
+	return /* @__PURE__ */ jsxs("figure", {
+		className: ["lab-illustration", className].filter(Boolean).join(" "),
+		children: [
+			/* @__PURE__ */ jsx("img", {
+				src,
+				alt,
+				"data-scheme": "light",
+				loading,
+				decoding: "async",
+				style: { aspectRatio: String(ratio) }
+			}),
+			srcDark && /* @__PURE__ */ jsx("img", {
+				src: srcDark,
+				alt: "",
+				"aria-hidden": "true",
+				"data-scheme": "dark",
+				loading,
+				decoding: "async",
+				style: { aspectRatio: String(ratio) }
+			}),
+			caption != null && /* @__PURE__ */ jsx("figcaption", { children: caption })
+		]
+	});
+}
+
+//#endregion
+export { Illustration };

package/dist/kit/figure/index.d.mts

@@ -0,0 +1,7 @@
+import { FigDomain, Figure, FigureProps, HUE, STROKE, StrokeRole, alpha, figUrl, fmt, shade, tint, useFigureId } from "./figure.mjs";
+import { FigTag, FigText, FigTextProps, FigTextSize, FigTextTone } from "./text.mjs";
+import { Ball, BallProps, Block, BlockProps, Particle } from "./body.mjs";
+import { Bubbles, Glass, GlassProps, GlassShape, Region, glassInner } from "./container.mjs";
+import { Arrow, ArrowProps, Ground, Ray, Track } from "./beam.mjs";
+import { Area, Curve, Marker, PlotBox, PlotFrame, PlotFrameProps, SegmentBar, scale } from "./plot.mjs";
+import { Illustration, IllustrationProps } from "./illustration.mjs";

package/dist/kit/figure/plot.d.mts

@@ -0,0 +1,109 @@
+import { StrokeRole } from "./figure.mjs";
+import { ReactNode } from "react";
+
+//#region src/kit/figure/plot.d.ts
+interface PlotBox {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+/** Linear mappers from data space to the plot box (y grows downward on screen). */
+declare function scale(box: PlotBox, xDomain: readonly [number, number], yDomain: readonly [number, number]): {
+  x: (v: number) => number;
+  y: (v: number) => number;
+};
+interface PlotFrameProps extends PlotBox {
+  xLabel?: ReactNode;
+  yLabel?: ReactNode;
+  title?: ReactNode;
+  /** Arrowheads on the axes (schematic plots) vs plain (quantitative). */
+  arrows?: boolean;
+  /** Tick positions in figure units along each axis, with optional labels. */
+  xTicks?: ReadonlyArray<{
+    at: number;
+    label?: ReactNode;
+  }>;
+  yTicks?: ReadonlyArray<{
+    at: number;
+    label?: ReactNode;
+  }>;
+  /** Faint horizontal grid lines at these y positions. */
+  grid?: ReadonlyArray<number>;
+  children?: ReactNode;
+}
+declare function PlotFrame({
+  x,
+  y,
+  w,
+  h,
+  xLabel,
+  yLabel,
+  title,
+  arrows,
+  xTicks,
+  yTicks,
+  grid,
+  children
+}: PlotFrameProps): ReactNode;
+declare function Curve({
+  points,
+  color,
+  weight,
+  dashed,
+  opacity
+}: {
+  points: ReadonlyArray<readonly [number, number]>;
+  color?: string;
+  weight?: StrokeRole;
+  dashed?: boolean;
+  opacity?: number;
+}): ReactNode;
+/** Shaded region under a curve segment down to `baseY`. */
+declare function Area({
+  points,
+  baseY,
+  color,
+  opacity
+}: {
+  points: ReadonlyArray<readonly [number, number]>;
+  baseY: number;
+  color?: string; /** Fill strength in percent. */
+  opacity?: number;
+}): ReactNode;
+/** A data point on a plot. */
+declare function Marker({
+  x,
+  y,
+  color,
+  r,
+  label
+}: {
+  x: number;
+  y: number;
+  color?: string;
+  r?: number;
+  label?: ReactNode;
+}): ReactNode;
+/** A horizontal proportion bar split into coloured segments (a composition, a mixture). */
+declare function SegmentBar({
+  x,
+  y,
+  w,
+  h,
+  segments,
+  radius
+}: {
+  x: number;
+  y: number;
+  w: number;
+  h?: number;
+  segments: ReadonlyArray<{
+    frac: number;
+    color: string;
+    label?: ReactNode;
+  }>;
+  radius?: number;
+}): ReactNode;
+//#endregion
+export { Area, Curve, Marker, PlotBox, PlotFrame, PlotFrameProps, SegmentBar, scale };

package/dist/kit/figure/plot.mjs

@@ -0,0 +1,207 @@
+'use client';
+
+import { STROKE, alpha } from "./figure.mjs";
+import { FigText } from "./text.mjs";
+import { Ball } from "./body.mjs";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/figure/plot.tsx
+/** Linear mappers from data space to the plot box (y grows downward on screen). */
+function scale(box, xDomain, yDomain) {
+	const [x0, x1] = xDomain;
+	const [y0, y1] = yDomain;
+	return {
+		x: (v) => box.x + (v - x0) / (x1 - x0 || 1) * box.w,
+		y: (v) => box.y + box.h - (v - y0) / (y1 - y0 || 1) * box.h
+	};
+}
+function PlotFrame({ x, y, w, h, xLabel, yLabel, title, arrows = true, xTicks, yTicks, grid, children }) {
+	const bottom = y + h;
+	const right = x + w;
+	const ah = 7;
+	return /* @__PURE__ */ jsxs("g", { children: [
+		title != null && /* @__PURE__ */ jsx(FigText, {
+			x,
+			y: y - 8,
+			size: "title",
+			children: title
+		}),
+		grid?.map((gy) => /* @__PURE__ */ jsx("line", {
+			x1: x,
+			y1: gy,
+			x2: right,
+			y2: gy,
+			stroke: "var(--fig-grid)",
+			strokeWidth: STROKE.hair
+		}, gy)),
+		children,
+		/* @__PURE__ */ jsx("line", {
+			x1: x,
+			y1: bottom,
+			x2: right + (arrows ? 4 : 0),
+			y2: bottom,
+			stroke: "var(--fig-axis)",
+			strokeWidth: STROKE.line,
+			strokeLinecap: "round"
+		}),
+		/* @__PURE__ */ jsx("line", {
+			x1: x,
+			y1: bottom,
+			x2: x,
+			y2: y - (arrows ? 4 : 0),
+			stroke: "var(--fig-axis)",
+			strokeWidth: STROKE.line,
+			strokeLinecap: "round"
+		}),
+		arrows && /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("path", {
+			d: `M ${right + 6} ${bottom} l -7 ${-7 * .55} v ${ah * 1.1} Z`,
+			fill: "var(--fig-axis)"
+		}), /* @__PURE__ */ jsx("path", {
+			d: `M ${x} ${y - 6} l ${-7 * .55} ${ah} h ${ah * 1.1} Z`,
+			fill: "var(--fig-axis)"
+		})] }),
+		xTicks?.map((t, i) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("line", {
+			x1: t.at,
+			y1: bottom,
+			x2: t.at,
+			y2: bottom + 4,
+			stroke: "var(--fig-axis)",
+			strokeWidth: STROKE.hair
+		}), t.label != null && /* @__PURE__ */ jsx(FigText, {
+			x: t.at,
+			y: bottom + 16,
+			anchor: "middle",
+			size: "note",
+			tone: "soft",
+			children: t.label
+		})] }, i)),
+		yTicks?.map((t, i) => /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("line", {
+			x1: x - 4,
+			y1: t.at,
+			x2: x,
+			y2: t.at,
+			stroke: "var(--fig-axis)",
+			strokeWidth: STROKE.hair
+		}), t.label != null && /* @__PURE__ */ jsx(FigText, {
+			x: x - 7,
+			y: t.at,
+			anchor: "end",
+			baseline: "middle",
+			size: "note",
+			tone: "soft",
+			children: t.label
+		})] }, i)),
+		xLabel != null && /* @__PURE__ */ jsx(FigText, {
+			x: right,
+			y: bottom + (xTicks?.length ? 30 : 18),
+			anchor: "end",
+			size: "note",
+			tone: "soft",
+			children: xLabel
+		}),
+		yLabel != null && /* @__PURE__ */ jsx(FigText, {
+			x: x - (yTicks?.length ? 30 : 8),
+			y: y + h / 2,
+			anchor: "middle",
+			size: "note",
+			tone: "soft",
+			rotate: -90,
+			children: yLabel
+		})
+	] });
+}
+const toPath = (points) => points.map(([px, py], i) => `${i ? "L" : "M"} ${px.toFixed(1)} ${py.toFixed(1)}`).join(" ");
+function Curve({ points, color = "var(--fig-hue-1)", weight = "edge", dashed = false, opacity }) {
+	const sw = STROKE[weight];
+	return /* @__PURE__ */ jsx("path", {
+		d: toPath(points),
+		fill: "none",
+		stroke: color,
+		strokeWidth: sw,
+		strokeLinecap: "round",
+		strokeLinejoin: "round",
+		strokeDasharray: dashed ? `${sw * 3} ${sw * 2.2}` : void 0,
+		opacity
+	});
+}
+/** Shaded region under a curve segment down to `baseY`. */
+function Area({ points, baseY, color = "var(--fig-hue-2)", opacity = 22 }) {
+	if (!points.length) return null;
+	const first = points[0];
+	const last = points[points.length - 1];
+	return /* @__PURE__ */ jsx("path", {
+		d: `M ${first[0].toFixed(1)} ${baseY} ${toPath(points).replace(/^M/, "L")} L ${last[0].toFixed(1)} ${baseY} Z`,
+		fill: alpha(color, opacity)
+	});
+}
+/** A dashed reference line with a label at its far end. */
+function Guide({ x1, y1, x2, y2, color = "var(--fig-hot)", label, labelAnchor = "middle", labelDx = 0, labelDy = -6 }) {
+	return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("line", {
+		x1,
+		y1,
+		x2,
+		y2,
+		stroke: color,
+		strokeWidth: STROKE.line,
+		strokeDasharray: "5 4",
+		strokeLinecap: "round"
+	}), label != null && /* @__PURE__ */ jsx(FigText, {
+		x: x2 + labelDx,
+		y: y2 + labelDy,
+		anchor: labelAnchor,
+		size: "note",
+		tone: "ink",
+		children: label
+	})] });
+}
+/** A data point on a plot. */
+function Marker({ x, y, color = "var(--fig-hue-1)", r = 5, label }) {
+	return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx(Ball, {
+		cx: x,
+		cy: y,
+		r,
+		color
+	}), label != null && /* @__PURE__ */ jsx(FigText, {
+		x: x + r + 5,
+		y,
+		baseline: "middle",
+		size: "note",
+		children: label
+	})] });
+}
+/** A horizontal proportion bar split into coloured segments (a composition, a mixture). */
+function SegmentBar({ x, y, w, h = 22, segments, radius = 6 }) {
+	let cursor = x;
+	return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
+		x,
+		y,
+		width: w,
+		height: h,
+		rx: radius,
+		fill: "var(--fig-ground)"
+	}), segments.map((s, i) => {
+		const sw = Math.max(0, s.frac) * w;
+		const sx = cursor;
+		cursor += sw;
+		if (sw <= .5) return null;
+		return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
+			x: sx,
+			y,
+			width: sw,
+			height: h,
+			rx: radius,
+			fill: s.color,
+			style: { transition: "x 0.45s cubic-bezier(0.2,0.8,0.2,1), width 0.45s cubic-bezier(0.2,0.8,0.2,1)" }
+		}), s.label != null && sw > 40 && /* @__PURE__ */ jsx(FigText, {
+			x: sx + 9,
+			y: y + h / 2,
+			baseline: "middle",
+			size: "note",
+			tone: "inverse",
+			children: s.label
+		})] }, i);
+	})] });
+}
+
+//#endregion
+export { Area, Curve, Guide, Marker, PlotFrame, SegmentBar, scale };

package/dist/kit/figure/text.d.mts

@@ -0,0 +1,50 @@
+import { ReactNode } from "react";
+
+//#region src/kit/figure/text.d.ts
+type FigTextSize = 'label' | 'note' | 'title' | 'measure' | 'eyebrow';
+type FigTextTone = 'ink' | 'soft' | 'hue-1' | 'hue-2' | 'hue-3' | 'hot' | 'good' | 'inverse';
+interface FigTextProps {
+  x: number;
+  y: number;
+  size?: FigTextSize;
+  tone?: FigTextTone;
+  anchor?: 'start' | 'middle' | 'end';
+  /** Vertical alignment relative to y (default: alphabetic baseline). */
+  baseline?: 'auto' | 'middle' | 'hanging';
+  /** Rotate around (x, y), degrees. */
+  rotate?: number;
+  /** Drop the halo (e.g. text on a solid fill). */
+  halo?: boolean;
+  className?: string;
+  children: ReactNode;
+}
+declare function FigText({
+  x,
+  y,
+  size,
+  tone,
+  anchor,
+  baseline,
+  rotate,
+  halo,
+  className,
+  children
+}: FigTextProps): ReactNode;
+/** A small rounded tag with text inside (legend chips, value pills, unit badges). */
+declare function FigTag({
+  x,
+  y,
+  children,
+  color,
+  anchor,
+  width
+}: {
+  x: number;
+  y: number;
+  children: ReactNode; /** Fill colour; text renders inverse on it. */
+  color?: string;
+  anchor?: 'start' | 'middle' | 'end'; /** Explicit width (user units). Defaults to an estimate from the text length. */
+  width?: number;
+}): ReactNode;
+//#endregion
+export { FigTag, FigText, FigTextProps, FigTextSize, FigTextTone };

package/dist/kit/figure/text.mjs

@@ -0,0 +1,44 @@
+'use client';
+
+import { jsx, jsxs } from "react/jsx-runtime";
+
+//#region src/kit/figure/text.tsx
+function FigText({ x, y, size = "label", tone = "ink", anchor = "start", baseline = "auto", rotate, halo = true, className, children }) {
+	return /* @__PURE__ */ jsx("text", {
+		className: ["fig-text", className].filter(Boolean).join(" "),
+		"data-size": size === "label" ? void 0 : size,
+		"data-tone": tone === "ink" ? void 0 : tone,
+		"data-halo": halo ? void 0 : "false",
+		x,
+		y,
+		textAnchor: anchor,
+		dominantBaseline: baseline === "auto" ? void 0 : baseline,
+		transform: rotate ? `rotate(${rotate} ${x} ${y})` : void 0,
+		children
+	});
+}
+/** A small rounded tag with text inside (legend chips, value pills, unit badges). */
+function FigTag({ x, y, children, color = "var(--fig-hue-1)", anchor = "start", width }) {
+	const w = width ?? Math.max(24, (typeof children === "string" || typeof children === "number" ? String(children) : "").length * 7.2 + 14);
+	const h = 20;
+	const x0 = anchor === "middle" ? x - w / 2 : anchor === "end" ? x - w : x;
+	return /* @__PURE__ */ jsxs("g", { children: [/* @__PURE__ */ jsx("rect", {
+		x: x0,
+		y: y - h / 2,
+		width: w,
+		height: h,
+		rx: h / 2,
+		fill: color
+	}), /* @__PURE__ */ jsx(FigText, {
+		x: x0 + w / 2,
+		y,
+		anchor: "middle",
+		baseline: "middle",
+		size: "note",
+		tone: "inverse",
+		children
+	})] });
+}
+
+//#endregion
+export { FigTag, FigText };

package/dist/kit/finance-viz/apportion-bar.d.mts

@@ -0,0 +1,33 @@
+import { ReactNode } from "react";
+
+//#region src/kit/finance-viz/apportion-bar.d.ts
+interface ApportionSegment {
+  label: string;
+  /** the basis this segment carries (area, hours, headcount…). */
+  weight: number;
+  /** optional colour override; otherwise cycles the palette. */
+  color?: string;
+}
+interface ApportionBarProps {
+  /** the pool being shared out (e.g. total rent). */
+  total: number;
+  segments: ApportionSegment[];
+  /** format the money share, e.g. (n) => `$${n}`. */
+  format?: (n: number) => string;
+  /** what the weight is measured in, e.g. "sq ft" or "hrs". */
+  weightLabel?: string;
+  /** header line above the bar. */
+  caption?: ReactNode;
+  height?: number;
+}
+/** One pool split into proportional zones; each zone's width = its share of the cost. */
+declare function ApportionBar({
+  total,
+  segments,
+  format,
+  weightLabel,
+  caption,
+  height
+}: ApportionBarProps): ReactNode;
+//#endregion
+export { ApportionBar, ApportionBarProps, ApportionSegment };