@fusion.dev/helix-core 0.194.0 → 0.195.0

package/custom-elements.json

@@ -16707,6 +16707,54 @@
             "module": "./utils/autofill-select/autofill-select.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "BoxAxisText",
+          "declaration": {
+            "name": "BoxAxisText",
+            "module": "./utils/box-labels/box-labels.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "BoxLabel",
+          "declaration": {
+            "name": "BoxLabel",
+            "module": "./utils/box-labels/box-labels.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "BoxLabelSizes",
+          "declaration": {
+            "name": "BoxLabelSizes",
+            "module": "./utils/box-labels/box-labels.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "BoxPlace",
+          "declaration": {
+            "name": "BoxPlace",
+            "module": "./utils/box-labels/box-labels.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "boxLabels",
+          "declaration": {
+            "name": "boxLabels",
+            "module": "./utils/box-labels/box-labels.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "SeenPlace",
+          "declaration": {
+            "name": "SeenPlace",
+            "module": "./utils/box-labels/box-labels.js"
+          }
+        },
         {
           "kind": "js",
           "name": "addDays",
@@ -18051,6 +18099,14 @@
             "module": "./utils/projection/projection.js"
           }
         },
+        {
+          "kind": "js",
+          "name": "hullOf",
+          "declaration": {
+            "name": "hullOf",
+            "module": "./utils/projection/projection.js"
+          }
+        },
         {
           "kind": "js",
           "name": "ISOMETRIC",
@@ -26883,6 +26939,52 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/box-labels/box-labels.ts",
+      "declarations": [
+        {
+          "kind": "function",
+          "name": "boxLabels",
+          "return": {
+            "type": {
+              "text": "BoxLabel[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "seen",
+              "type": {
+                "text": "(place: BoxPlace) => SeenPlace"
+              }
+            },
+            {
+              "name": "axes",
+              "type": {
+                "text": "{ x: BoxAxisText; y: BoxAxisText; z: BoxAxisText }"
+              }
+            },
+            {
+              "name": "sizes",
+              "type": {
+                "text": "BoxLabelSizes"
+              }
+            }
+          ],
+          "description": "The numbers and names of a box's three axes, placed on the page for a\nview `seen` takes each place in the box through."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "boxLabels",
+          "declaration": {
+            "name": "boxLabels",
+            "module": "src/utils/box-labels/box-labels.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/calendar/calendar.ts",
@@ -31960,6 +32062,24 @@
             }
           ]
         },
+        {
+          "kind": "function",
+          "name": "hullOf",
+          "return": {
+            "type": {
+              "text": "PagePoint[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "points",
+              "type": {
+                "text": "readonly PagePoint[]"
+              }
+            }
+          ],
+          "description": "The outline around a set of points on the page: their convex hull, in order round it."
+        },
         {
           "kind": "function",
           "name": "solid",
@@ -32074,6 +32194,14 @@
             "module": "src/utils/projection/projection.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "hullOf",
+          "declaration": {
+            "name": "hullOf",
+            "module": "src/utils/projection/projection.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "solid",
@@ -36231,7 +36359,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.194.0'",
+          "default": "'0.195.0'",
           "description": "The version of the package this file ships in.\n\n**Written by `fusion/scripts/version.mjs`** wherever it writes the package's\n`package.json`, and stamped back into the repository beside it after a\nrelease, so the two never disagree; a spec beside this holds them to it.\nNothing else in the running code knows which release it is."
         }
       ],
@@ -36867,6 +36995,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.194.0"
+    "version": "0.195.0"
   }
 }

package/dist/index.d.ts

@@ -63,6 +63,7 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { arrowReach, sideOf } from './utils/arrow/arrow.js';
 export { assignSlots } from './utils/assign-slots/assign-slots.js';
 export { type DrawAutofillOptions, drawAutofill, } from './utils/autofill-select/autofill-select.js';
+export { type BoxAxisText, type BoxLabel, type BoxLabelSizes, type BoxPlace, boxLabels, type SeenPlace, } from './utils/box-labels/box-labels.js';
 export { addDays, addMonths, type Barring, barredBy, type CalendarParts, type CalendarView, calendarLocale, type DateCalendar, localToday, MONTH_CALENDARS, type MonthCalendar, type MonthSystem, monthOf, monthOut, monthSystem, type PeriodCell, type PeriodPage, periodCells, periodKey, periodMove, sameMonth, todayIn, weekendOf, weekStartOf, YEARS_SHOWN, yearOut, yearPageOf, } from './utils/calendar/calendar.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { centerInView } from './utils/center-in-view/center-in-view.js';
@@ -120,7 +121,7 @@ export { applyOwnRule, type OwnRule } from './utils/own-rule/own-rule.js';
 export { plainClick } from './utils/plain-click/plain-click.js';
 export { appleTouch, onAndroid, onApple, type Platform } from './utils/platform/platform.js';
 export { pressType, type RecentPress } from './utils/press-type/press-type.js';
-export { type Camera, type Drawn, depthOrder, type Face, ISOMETRIC, LOWEST_TILT, type PagePoint, type Projection, pathData, projectionOf, type Solid, shortNumber, solid, } from './utils/projection/projection.js';
+export { type Camera, type Drawn, depthOrder, type Face, hullOf, ISOMETRIC, LOWEST_TILT, type PagePoint, type Projection, pathData, projectionOf, type Solid, shortNumber, solid, } from './utils/projection/projection.js';
 export { rangeAdd } from './utils/range-add/range-add.js';
 export { type ColorBytes, type ColorBytesAlpha, readColor, readColorAlpha, rgbOf, } from './utils/read-color/read-color.js';
 export { type ChartData, type ChartDatum, rowsFromData, seriesFromData, } from './utils/read-data/read-data.js';

package/dist/index.js

@@ -63,6 +63,7 @@ export { anchorElement } from './utils/anchor-element/anchor-element.js';
 export { arrowReach, sideOf } from './utils/arrow/arrow.js';
 export { assignSlots } from './utils/assign-slots/assign-slots.js';
 export { drawAutofill, } from './utils/autofill-select/autofill-select.js';
+export { boxLabels, } from './utils/box-labels/box-labels.js';
 export { addDays, addMonths, barredBy, calendarLocale, localToday, MONTH_CALENDARS, monthOf, monthOut, monthSystem, periodCells, periodKey, periodMove, sameMonth, todayIn, weekendOf, weekStartOf, YEARS_SHOWN, yearOut, yearPageOf, } from './utils/calendar/calendar.js';
 export { capturePointer } from './utils/capture-pointer/capture-pointer.js';
 export { centerInView } from './utils/center-in-view/center-in-view.js';
@@ -120,7 +121,7 @@ export { applyOwnRule } from './utils/own-rule/own-rule.js';
 export { plainClick } from './utils/plain-click/plain-click.js';
 export { appleTouch, onAndroid, onApple } from './utils/platform/platform.js';
 export { pressType } from './utils/press-type/press-type.js';
-export { depthOrder, ISOMETRIC, LOWEST_TILT, pathData, projectionOf, shortNumber, solid, } from './utils/projection/projection.js';
+export { depthOrder, hullOf, ISOMETRIC, LOWEST_TILT, pathData, projectionOf, shortNumber, solid, } from './utils/projection/projection.js';
 export { rangeAdd } from './utils/range-add/range-add.js';
 export { readColor, readColorAlpha, rgbOf, } from './utils/read-color/read-color.js';
 export { rowsFromData, seriesFromData, } from './utils/read-data/read-data.js';

package/dist/utils/box-labels/box-labels.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Where a box's numbers and names stand on the page, from whichever side it
+ * is seen: the box a spatial chart draws its readings in, in SVG or with
+ * three.js.
+ *
+ * **Each axis is written along the edge that faces the reader**, outside the
+ * box. Across and depth are written along the floor's two edges nearest the
+ * reader, and up along the upright edge at the left of the box on the page.
+ * Each number stands off its edge on the side away from the box, the side of
+ * it nearest the edge, and each name stands beyond its numbers. So a turn
+ * moves the numbers to the edges that face the reader, and none is written
+ * behind the box or inside it.
+ *
+ * **A number that would cover another label is left out**, which thins an
+ * axis seen at a slant, and an axis whose edge is seen end on is left out
+ * whole. Every name is kept.
+ *
+ * Pure, and measured in the page's own units: the SVG drawing passes its
+ * drawing's units, and three.js passes pixels.
+ */
+import type { PagePoint } from '../projection/projection.js';
+/** A place in the box: across, up, and in depth toward the reader, each from -1 to 1. */
+export type BoxPlace = readonly [number, number, number];
+/** A place on the page, and how near the reader it stands: the larger, the nearer. */
+export interface SeenPlace extends PagePoint {
+    depth: number;
+}
+/** One axis' name, and its numbers at their places along it, from -1 to 1. */
+export interface BoxAxisText {
+    name: string;
+    ticks: readonly {
+        at: number;
+        text: string;
+    }[];
+}
+/** A number or a name, centered on its place on the page. */
+export interface BoxLabel {
+    /** Whether it is an axis' name, which is written larger. */
+    name: boolean;
+    text: string;
+    x: number;
+    y: number;
+}
+/** How large the labels are, in the page's units. */
+export interface BoxLabelSizes {
+    /** The space between an edge and its numbers, and between the numbers and the name. */
+    gap: number;
+    /** How tall a name is. */
+    name: number;
+    /** How tall a number is. */
+    tick: number;
+    /** How wide a character is, as a share of its height, which is near enough to keep labels apart. */
+    wide: number;
+}
+/**
+ * The numbers and names of a box's three axes, placed on the page for a
+ * view `seen` takes each place in the box through.
+ */
+export declare const boxLabels: (seen: (place: BoxPlace) => SeenPlace, axes: {
+    x: BoxAxisText;
+    y: BoxAxisText;
+    z: BoxAxisText;
+}, sizes: BoxLabelSizes) => BoxLabel[];

package/dist/utils/box-labels/box-labels.js

@@ -0,0 +1,89 @@
+const overlaps = (one, other, pad) => Math.abs(one.x - other.x) < one.half.width + other.half.width + pad &&
+    Math.abs(one.y - other.y) < one.half.height + other.half.height + pad;
+export const boxLabels = (seen, axes, sizes) => {
+    const corners = [];
+    for (const x of [-1, 1]) {
+        for (const y of [-1, 1]) {
+            for (const z of [-1, 1]) {
+                corners.push(seen([x, y, z]));
+            }
+        }
+    }
+    const middle = {
+        x: corners.reduce((sum, corner) => sum + corner.x, 0) / corners.length,
+        y: corners.reduce((sum, corner) => sum + corner.y, 0) / corners.length,
+    };
+    const reach = Math.max(Math.max(...corners.map((corner) => corner.x)) - Math.min(...corners.map((corner) => corner.x)), Math.max(...corners.map((corner) => corner.y)) - Math.min(...corners.map((corner) => corner.y)));
+    const back = seen([0, -1, 1]).depth >= seen([0, -1, -1]).depth ? 1 : -1;
+    const side = seen([1, -1, 0]).depth >= seen([-1, -1, 0]).depth ? 1 : -1;
+    let upright;
+    for (const x of [-1, 1]) {
+        for (const z of [-1, 1]) {
+            const at = seen([x, -1, z]);
+            const further = upright === undefined || at.x < upright.at.x - reach * 1e-3;
+            const level = upright !== undefined && Math.abs(at.x - upright.at.x) <= reach * 1e-3;
+            if (further || (level && upright !== undefined && at.depth > upright.at.depth)) {
+                upright = { at, x, z };
+            }
+        }
+    }
+    const { x: ux, z: uz } = upright;
+    const edges = [
+        { along: (t) => [t, -1, back], key: 'x' },
+        { along: (t) => [side, -1, t], key: 'z' },
+        { along: (t) => [ux, t, uz], key: 'y' },
+    ];
+    const size = (text, name) => {
+        const height = name ? sizes.name : sizes.tick;
+        return { height, width: text.length * height * sizes.wide };
+    };
+    const off = (at, out, box, by) => ({
+        half: { height: box.height / 2, width: box.width / 2 },
+        x: at.x + out.x * by + (out.x * box.width) / 2,
+        y: at.y + out.y * by + (out.y * box.height) / 2,
+    });
+    const names = [];
+    const ticks = [];
+    for (const { along, key } of edges) {
+        const axis = axes[key];
+        const [from, to] = [seen(along(-1)), seen(along(1))];
+        const length = Math.hypot(to.x - from.x, to.y - from.y);
+        if (length < reach * 0.05) {
+            continue;
+        }
+        let out = { x: -(to.y - from.y) / length, y: (to.x - from.x) / length };
+        const away = { x: (from.x + to.x) / 2 - middle.x, y: (from.y + to.y) / 2 - middle.y };
+        if (out.x * away.x + out.y * away.y < 0) {
+            out = { x: -out.x, y: -out.y };
+        }
+        let deepest = 0;
+        for (const tick of axis.ticks) {
+            const box = size(tick.text, false);
+            ticks.push({ ...off(seen(along(tick.at)), out, box, sizes.gap), text: tick.text });
+            deepest = Math.max(deepest, Math.abs(out.x) * box.width + Math.abs(out.y) * box.height);
+        }
+        const box = size(axis.name, true);
+        names.push({
+            ...(key === 'y'
+                ?
+                    off(to, { x: 0, y: -1 }, box, sizes.gap)
+                : off(seen(along(0)), out, box, sizes.gap * 2 + deepest)),
+            text: axis.name,
+        });
+    }
+    const kept = [...names];
+    const labels = names.map((one) => ({
+        name: true,
+        text: one.text,
+        x: one.x,
+        y: one.y,
+    }));
+    for (const tick of ticks) {
+        if (kept.some((other) => overlaps(tick, other, sizes.gap / 2))) {
+            continue;
+        }
+        kept.push(tick);
+        labels.push({ name: false, text: tick.text, x: tick.x, y: tick.y });
+    }
+    return labels;
+};

package/dist/utils/projection/projection.d.ts

@@ -58,6 +58,8 @@ export type Solid = 'block' | 'cylinder' | 'pyramid';
 /** A number written short enough for path data, and never as `-0`. */
 export declare const shortNumber: (value: number) => string;
 export declare const pathData: (points: readonly PagePoint[]) => string;
+/** The outline around a set of points on the page: their convex hull, in order round it. */
+export declare const hullOf: (points: readonly PagePoint[]) => PagePoint[];
 /** One face of a solid, as path data, and how far it is darkened toward black. */
 export interface Face {
     d: string;

package/dist/utils/projection/projection.js

@@ -23,7 +23,7 @@ export const projectionOf = (camera) => {
 };
 export const shortNumber = (value) => String(Math.round(value * 1000) / 1000 || 0);
 export const pathData = (points) => `M${points.map((point) => `${shortNumber(point.x)} ${shortNumber(point.y)}`).join('L')}Z`;
-const hullOf = (points) => {
+export const hullOf = (points) => {
     const sorted = [...points].sort((one, other) => one.x - other.x || one.y - other.y);
     if (sorted.length < 3) {
         return sorted;

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.194.0";
+export declare const VERSION = "0.195.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.194.0';
+export const VERSION = '0.195.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.194.0",
+  "version": "0.195.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -74,12 +74,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.194.0",
+    "@fusion.dev/helix-icons": "0.195.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.194.0",
-    "@fusion.dev/helix-testing": "0.194.0",
+    "@fusion.dev/helix-cem": "0.195.0",
+    "@fusion.dev/helix-testing": "0.195.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },