psychic-potato 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# psychic-potato
+
+`psychic-potato` exports a single browser function, `squeezeText`, that mutates matching `div` / `span` pairs in place so the rendered span boxes fit inside their corresponding div content boxes.
+
+## Contract
+
+- pass `HTMLDivElement[]` and `HTMLSpanElement[]` of the same length
+- each span must be inside its matching div
+- the library measures spans with `getBoundingClientRect()`
+- the fitting target is each div's content box, so padding and borders reduce usable space
+- the same scalar font-size multiplier is applied to both every div and every span
+- fitting defaults to both axes, but you can set `axis: "width"` or `axis: "height"`
+- during the exponential sweep, the divs must stay size-stable on the measured axis or the function throws
+
+## Intended usage
+
+This is designed for UI resize flows where the spans are already laid out how you want them. If you want tighter or looser fitting, control that through your own span/div CSS; `squeezeText` fits the rendered DOM boxes it sees.
+
+```ts
+import { squeezeText } from "psychic-potato";
+
+const divs = Array.from(document.querySelectorAll("div.fit-target"));
+const spans = Array.from(document.querySelectorAll("div.fit-target > span"));
+
+squeezeText(divs, spans);
+squeezeText(divs, spans, { axis: "width" });
+```

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { type FitAxis } from "./measurement.js";
+export type SqueezeTextOptions = {
+    axis?: FitAxis;
+};
+export declare function squeezeText(divs: HTMLDivElement[], spans: HTMLSpanElement[], options?: SqueezeTextOptions): void;

package/dist/index.js

@@ -0,0 +1,154 @@
+const SEARCH_EPSILON_START_PX = 1;
+const MAX_SWEEP_STEPS = 32;
+const MAX_BINARY_STEPS = 32;
+const MIN_SCALAR = 1 / 2 ** 32;
+const SCALAR_STALL_EPSILON = 1e-7;
+import { assertAtLeastOneSpanRenders, assertDivsStable, measureDivTarget, measureFit, } from "./measurement.js";
+export function squeezeText(divs, spans, options = {}) {
+    validateInputs(divs, spans);
+    const axis = options.axis ?? "both";
+    const fontSnapshot = snapshotInlineFontSizes(divs, spans);
+    const baseFontSizes = captureBaseFontSizes(divs, spans);
+    const divTargets = divs.map((div) => measureDivTarget(div, axis));
+    const appliedScalar = { value: null };
+    try {
+        applyScalar(divs, spans, baseFontSizes, appliedScalar, 1);
+        assertAtLeastOneSpanRenders(spans);
+        const bracket = runExponentialSweep(divs, spans, baseFontSizes, divTargets, appliedScalar, axis);
+        runBinarySearch(divs, spans, baseFontSizes, divTargets, bracket, appliedScalar, axis);
+    }
+    catch (error) {
+        restoreInlineFontSizes(divs, spans, fontSnapshot);
+        throw error;
+    }
+}
+function validateInputs(divs, spans) {
+    if (divs.length !== spans.length) {
+        throw new Error("squeezeText requires div and span arrays of the same length.");
+    }
+    if (divs.length === 0) {
+        throw new Error("squeezeText requires at least one div/span pair.");
+    }
+    const hasAnyText = spans.some((span) => (span.textContent ?? "").length > 0);
+    if (!hasAnyText) {
+        throw new Error("squeezeText requires at least one span with text content.");
+    }
+    for (let index = 0; index < divs.length; index += 1) {
+        const div = divs[index];
+        const span = spans[index];
+        if (!div.isConnected || !span.isConnected) {
+            throw new Error("squeezeText requires connected div/span elements.");
+        }
+        if (!div.contains(span)) {
+            throw new Error(`squeezeText requires span ${index} to be contained inside div ${index}.`);
+        }
+    }
+}
+function snapshotInlineFontSizes(divs, spans) {
+    return {
+        divInline: divs.map((div) => div.style.fontSize),
+        spanInline: spans.map((span) => span.style.fontSize),
+    };
+}
+function restoreInlineFontSizes(divs, spans, snapshot) {
+    for (let index = 0; index < divs.length; index += 1) {
+        divs[index].style.fontSize = snapshot.divInline[index];
+        spans[index].style.fontSize = snapshot.spanInline[index];
+    }
+}
+function captureBaseFontSizes(divs, spans) {
+    return {
+        divs: divs.map((div, index) => readFontSize(div, `div ${index}`)),
+        spans: spans.map((span, index) => readFontSize(span, `span ${index}`)),
+    };
+}
+function readFontSize(element, label) {
+    const fontSize = Number.parseFloat(getComputedStyle(element).fontSize);
+    if (!Number.isFinite(fontSize) || fontSize <= 0) {
+        throw new Error(`squeezeText requires a positive computed font size for ${label}.`);
+    }
+    return fontSize;
+}
+function applyScalar(divs, spans, baseFontSizes, appliedScalar, scalar) {
+    if (appliedScalar.value === scalar) {
+        return;
+    }
+    for (let index = 0; index < divs.length; index += 1) {
+        divs[index].style.fontSize = `${baseFontSizes.divs[index] * scalar}px`;
+    }
+    for (let index = 0; index < spans.length; index += 1) {
+        spans[index].style.fontSize = `${baseFontSizes.spans[index] * scalar}px`;
+    }
+    appliedScalar.value = scalar;
+}
+function runExponentialSweep(divs, spans, baseFontSizes, divTargets, appliedScalar, axis) {
+    let scalar = 1;
+    let assessment = measureFit(divs, spans, divTargets, axis);
+    for (let step = 0; step < MAX_SWEEP_STEPS; step += 1) {
+        if (assessment.fits) {
+            const nextScalar = scalar * 2;
+            applyScalar(divs, spans, baseFontSizes, appliedScalar, nextScalar);
+            assertDivsStable(divs, divTargets, axis);
+            const nextAssessment = measureFit(divs, spans, divTargets, axis);
+            if (!nextAssessment.fits) {
+                return {
+                    insideScalar: scalar,
+                    outsideScalar: nextScalar,
+                    initialInsideGap: assessment.minGap,
+                };
+            }
+            scalar = nextScalar;
+            assessment = nextAssessment;
+            continue;
+        }
+        const nextScalar = scalar / 2;
+        if (nextScalar < MIN_SCALAR) {
+            throw new Error("squeezeText could not find a fitting font size during the sweep.");
+        }
+        applyScalar(divs, spans, baseFontSizes, appliedScalar, nextScalar);
+        assertDivsStable(divs, divTargets, axis);
+        const nextAssessment = measureFit(divs, spans, divTargets, axis);
+        if (nextAssessment.fits) {
+            return {
+                insideScalar: nextScalar,
+                outsideScalar: scalar,
+                initialInsideGap: nextAssessment.minGap,
+            };
+        }
+        scalar = nextScalar;
+        assessment = nextAssessment;
+    }
+    throw new Error("squeezeText could not bracket a fit during the sweep.");
+}
+function runBinarySearch(divs, spans, baseFontSizes, divTargets, bracket, appliedScalar, axis) {
+    let inside = bracket.insideScalar;
+    let outside = bracket.outsideScalar;
+    let bestInside = inside;
+    let bestGap = bracket.initialInsideGap;
+    let epsilon = SEARCH_EPSILON_START_PX;
+    for (let step = 0; step < MAX_BINARY_STEPS; step += 1) {
+        const midpoint = (inside + outside) / 2;
+        if (Math.abs(midpoint - inside) <= SCALAR_STALL_EPSILON ||
+            Math.abs(outside - midpoint) <= SCALAR_STALL_EPSILON) {
+            break;
+        }
+        applyScalar(divs, spans, baseFontSizes, appliedScalar, midpoint);
+        const assessment = measureFit(divs, spans, divTargets, axis);
+        if (assessment.fits) {
+            inside = midpoint;
+            bestInside = midpoint;
+            bestGap = assessment.minGap;
+            if (assessment.minGap <= epsilon) {
+                return;
+            }
+        }
+        else {
+            outside = midpoint;
+        }
+        epsilon += 1;
+    }
+    applyScalar(divs, spans, baseFontSizes, appliedScalar, bestInside);
+    if (bestGap < 0) {
+        throw new Error("squeezeText could not preserve a non-clipping fit.");
+    }
+}

package/dist/measurement.d.ts

@@ -0,0 +1,18 @@
+export declare const DIV_STABILITY_TOLERANCE_PX = 1;
+export type FitAxis = "both" | "width" | "height";
+export type DivTarget = {
+    initialWidth: number;
+    initialHeight: number;
+    insetLeft: number;
+    insetRight: number;
+    insetTop: number;
+    insetBottom: number;
+};
+export type FitAssessment = {
+    fits: boolean;
+    minGap: number;
+};
+export declare function measureDivTarget(div: HTMLDivElement, axis: FitAxis): DivTarget;
+export declare function assertAtLeastOneSpanRenders(spans: HTMLSpanElement[]): void;
+export declare function assertDivsStable(divs: HTMLDivElement[], divTargets: DivTarget[], axis: FitAxis): void;
+export declare function measureFit(divs: HTMLDivElement[], spans: HTMLSpanElement[], divTargets: DivTarget[], axis: FitAxis): FitAssessment;

package/dist/measurement.js

@@ -0,0 +1,79 @@
+export const DIV_STABILITY_TOLERANCE_PX = 1;
+export function measureDivTarget(div, axis) {
+    const rect = div.getBoundingClientRect();
+    const style = getComputedStyle(div);
+    const insetLeft = parsePixelValue(style.borderLeftWidth) + parsePixelValue(style.paddingLeft);
+    const insetRight = parsePixelValue(style.borderRightWidth) + parsePixelValue(style.paddingRight);
+    const insetTop = parsePixelValue(style.borderTopWidth) + parsePixelValue(style.paddingTop);
+    const insetBottom = parsePixelValue(style.borderBottomWidth) + parsePixelValue(style.paddingBottom);
+    const contentWidth = rect.width - insetLeft - insetRight;
+    const contentHeight = rect.height - insetTop - insetBottom;
+    if ((axis === "both" || axis === "width") && contentWidth <= 0) {
+        throw new Error("squeezeText requires each div to have a positive content width.");
+    }
+    if ((axis === "both" || axis === "height") && contentHeight <= 0) {
+        throw new Error("squeezeText requires each div to have a positive content box.");
+    }
+    return {
+        initialWidth: rect.width,
+        initialHeight: rect.height,
+        insetLeft,
+        insetRight,
+        insetTop,
+        insetBottom,
+    };
+}
+export function assertAtLeastOneSpanRenders(spans) {
+    const anyRenderableSpan = spans.some((span) => {
+        const rect = span.getBoundingClientRect();
+        return rect.width > 0 || rect.height > 0;
+    });
+    if (!anyRenderableSpan) {
+        throw new Error("squeezeText requires at least one span to render measurable text.");
+    }
+}
+export function assertDivsStable(divs, divTargets, axis) {
+    for (let index = 0; index < divs.length; index += 1) {
+        const rect = divs[index].getBoundingClientRect();
+        const target = divTargets[index];
+        const widthDelta = Math.abs(rect.width - target.initialWidth);
+        const heightDelta = Math.abs(rect.height - target.initialHeight);
+        if ((axis === "both" || axis === "width") && widthDelta > DIV_STABILITY_TOLERANCE_PX) {
+            throw new Error(`squeezeText requires div ${index} to stay size-stable while fitting text.`);
+        }
+        if ((axis === "both" || axis === "height") && heightDelta > DIV_STABILITY_TOLERANCE_PX) {
+            throw new Error(`squeezeText requires div ${index} to stay size-stable while fitting text.`);
+        }
+    }
+}
+export function measureFit(divs, spans, divTargets, axis) {
+    let minGap = Number.POSITIVE_INFINITY;
+    for (let index = 0; index < divs.length; index += 1) {
+        const divRect = divs[index].getBoundingClientRect();
+        const spanRect = spans[index].getBoundingClientRect();
+        const target = divTargets[index];
+        const contentLeft = divRect.left + target.insetLeft;
+        const contentRight = divRect.right - target.insetRight;
+        const contentTop = divRect.top + target.insetTop;
+        const contentBottom = divRect.bottom - target.insetBottom;
+        const pairMinGap = measurePairGap(spanRect, contentLeft, contentRight, contentTop, contentBottom, axis);
+        minGap = Math.min(minGap, pairMinGap);
+    }
+    return {
+        fits: minGap >= 0,
+        minGap,
+    };
+}
+function measurePairGap(spanRect, contentLeft, contentRight, contentTop, contentBottom, axis) {
+    if (axis === "width") {
+        return Math.min(spanRect.left - contentLeft, contentRight - spanRect.right);
+    }
+    if (axis === "height") {
+        return Math.min(spanRect.top - contentTop, contentBottom - spanRect.bottom);
+    }
+    return Math.min(spanRect.left - contentLeft, contentRight - spanRect.right, spanRect.top - contentTop, contentBottom - spanRect.bottom);
+}
+function parsePixelValue(value) {
+    const parsed = Number.parseFloat(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "psychic-potato",
+	"version": "0.1.0",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/hcubasd/psychic-potato"
+	},
+	"engines": {
+		"node": ">=22.12.0 <25.0.0"
+	},
+	"scripts": {
+		"test": "vitest --environment jsdom",
+		"build": "tsc --rootDir src --outDir dist"
+	},
+	"files": [
+		"dist"
+	],
+	"devDependencies": {
+		"@tsconfig/node22": "^22.0.5",
+		"jsdom": "^26.1.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.7"
+	}
+}