@heroiclands/package-build 22.4.5 → 22.4.6

package/types/engine/map-layout.d.mts

@@ -34,26 +34,32 @@ export function bearingSteps(a: unknown, b: unknown): number | undefined;
  * days nobody stated, is named. One log step beyond the horizon, so the rim
  * reads as the next ring rather than a margin.
  *
+ * @param {number} [horizon] - The horizon in days; the map from a place's
+ *   by default.
  * @returns {number} Points.
  */
-export function rimRadius(): number;
+export function rimRadius(horizon?: number): number;
 /**
  * The radius of the ring a days value sits on.
  *
  * Logarithmic in days, so equal ratios of days are equal steps of radius: a
- * day to two days is the same step as five to ten. Any value beyond the
- * horizon, and no value at all, is the rim.
+ * day to two days is the same step as five to ten, whatever the horizon. Any
+ * value beyond the horizon, and no value at all, is the rim.
  *
  * @param {number|undefined} days - A days value, on the scale or not.
+ * @param {number} [horizon] - The horizon in days; the map from a place's
+ *   by default.
  * @returns {number} Points.
  */
-export function ringRadius(days: number | undefined): number;
+export function ringRadius(days: number | undefined, horizon?: number): number;
 /**
  * The rings, inside out — one per marker up to the horizon.
  *
+ * @param {number} [horizon] - The horizon in days; the map from a place's
+ *   by default.
  * @returns {Array<{days: number, radius: number}>} Each marker and its radius.
  */
-export function rings(): Array<{
+export function rings(horizon?: number): Array<{
     days: number;
     radius: number;
 }>;
@@ -79,24 +85,37 @@ export function daysMarker(total: number | undefined): number | undefined;
  */
 export function edgeLength(days: number | undefined): number;
 /**
- * One hop of a journey: a bearing and, for a route, its days.
+ * A chain of hops composed into one bearing and one total, or nothing where
+ * a hop turns back.
+ *
+ * The composed direction is that of the hops added as vectors weighted by
+ * their days, and the total is their sum. Each hop after the first is
+ * checked against the running direction of the chain before it — not
+ * against the previous hop — and composes only where it lies within one
+ * octant of that direction, so a path may bend a little at every hop and
+ * drift past an octant of where it began, but a hop that turns back ends
+ * the chain: a place east and then north of here is not in any one
+ * direction, and the drawing omits it rather than guess. A hop with no days
+ * — a border — makes the total unknown, because a frontier states no
+ * distance, and then every hop weighs the same, because nothing says which
+ * is the longer.
  *
- * @typedef {object} Hop
- * @property {string} bearing - Where the far end lies from the near end.
- * @property {number} [days] - The route's marker; absent for a border.
+ * @param {Hop[]} hops - The hops, from the centre outward.
+ * @returns {{angle: number, days: number|undefined}|undefined} The composed
+ *   bearing in degrees and the total days, or `undefined` where a hop turns
+ *   back, a bearing is not one, or there are no hops.
  */
+export function composeChain(hops: Hop[]): {
+    angle: number;
+    days: number | undefined;
+} | undefined;
 /**
  * Two hops composed into one bearing and one total, or nothing where they
  * disagree.
  *
- * Two hops agree when their bearings are the same or adjacent; then the
- * composed direction is that of the two hops added as vectors weighted by
- * their days, and the total is their sum. A hop with no days — a border —
- * makes the total unknown, because a frontier states no distance, and then
- * the two hops weigh the same, because nothing says which is the longer.
- * Hops two or more steps apart do not compose:
- * a place east and then north of here is not in any one direction, and the
- * map omits it rather than guess.
+ * Two hops agree when their bearings are the same or adjacent — the
+ * two-hop case of {@link composeChain}: the second hop is checked against
+ * the first, which is the whole running direction at that point.
  *
  * @param {Hop} first - The hop from the centre.
  * @param {Hop} second - The hop onward.
@@ -133,7 +152,8 @@ export function relationsOf(places: Map<string, MapPlace>, shortcode: string): {
     }>;
 };
 /**
- * Lay out the map from a place.
+ * Lay out the map from a place: two hops, a horizon of 90 days, and a rim
+ * naming what lies beyond it.
  *
  * The centre at the origin. Every neighbour it states, or that states it, at
  * the angle of its bearing and on the ring of its days — the innermost ring
@@ -147,25 +167,35 @@ export function relationsOf(places: Map<string, MapPlace>, shortcode: string): {
  *
  * @param {Map<string, MapPlace>} places - Every place, by shortcode.
  * @param {string} centre - The place the map is from.
- * @returns {{centre: string, nodes: FromNode[], edges: FromEdge[],
- *   rings: Array<{days: number, radius: number}>, rim: number,
- *   unresolved: Array<{from: string, to: string}>}} The layout, in points.
+ * @returns {FromLayout} The layout, in points.
  * @throws {Error} When `centre` is not a place.
  */
-export function layoutFrom(places: Map<string, MapPlace>, centre: string): {
-    centre: string;
-    nodes: FromNode[];
-    edges: FromEdge[];
-    rings: Array<{
-        days: number;
-        radius: number;
-    }>;
-    rim: number;
-    unresolved: Array<{
-        from: string;
-        to: string;
-    }>;
-};
+export function layoutFrom(places: Map<string, MapPlace>, centre: string): FromLayout;
+/**
+ * Lay out the chart from a place: the map from it at a larger horizon.
+ *
+ * The neighbours as on the map from a place. Beyond them the hops chain on,
+ * each checked against the running direction of the chain so far and
+ * composing only within one octant of it, so a path bends but never turns
+ * back; a place is drawn at the composed bearing on the ring of the summed
+ * days, and where several chains reach it, by the one with the fewest. A
+ * border beyond the first hop makes the total unknown and sends the place to
+ * the rim, and nothing is drawn beyond it. A place whose total exceeds the
+ * horizon is left out — the chart is already the larger view — so the rim
+ * holds the unknown alone.
+ *
+ * @param {Map<string, MapPlace>} places - Every place, by shortcode.
+ * @param {string} centre - The place the chart is from.
+ * @param {object} [opts]
+ * @param {number} [opts.horizon] - The horizon in days, a marker of the
+ *   scale; {@link CHART_HORIZON_DAYS} by default.
+ * @returns {FromLayout} The layout, in points.
+ * @throws {Error} When `centre` is not a place, or `horizon` is not a marker
+ *   of the scale.
+ */
+export function layoutChart(places: Map<string, MapPlace>, centre: string, { horizon }?: {
+    horizon?: number | undefined;
+}): FromLayout;
 /**
  * One edge of the whole route graph.
  *
@@ -213,18 +243,12 @@ export const HORIZON_DAYS: number;
  */
 export const RING_DAYS: readonly number[];
 /**
- * One hop of a journey: a bearing and, for a route, its days.
+ * The horizon of the chart from a place when none is asked for, in days: the
+ * end of the scale, so the whole of what the notes state fits on the page.
+ *
+ * @type {number}
  */
-export type Hop = {
-    /**
-     * - Where the far end lies from the near end.
-     */
-    bearing: string;
-    /**
-     * - The route's marker; absent for a border.
-     */
-    days?: number | undefined;
-};
+export const CHART_HORIZON_DAYS: number;
 /**
  * A place as the map reads it. The shape {@link module :engine/map-places}
  * builds from the content index; only the relation fields matter here.
@@ -265,6 +289,35 @@ export type Relation = {
      */
     stated: boolean;
 };
+/**
+ * The layout of the map from a place or of the chart from one.
+ */
+export type FromLayout = {
+    centre: string;
+    nodes: FromNode[];
+    edges: FromEdge[];
+    rings: Array<{
+        days: number;
+        radius: number;
+    }>;
+    /**
+     * - The rim's radius, in points.
+     */
+    rim: number;
+    /**
+     * - The horizon, in days.
+     */
+    horizon: number;
+    /**
+     * - Whether a place past the horizon is named at
+     * the rim; false, it is omitted and the rim holds only the unknown.
+     */
+    beyond: boolean;
+    unresolved: Array<{
+        from: string;
+        to: string;
+    }>;
+};
 /**
  * One edge of the whole route graph.
  */
@@ -283,13 +336,27 @@ export type TravelEdge = {
      */
     len: number;
 };
+/**
+ * One hop of a journey: a bearing and, for a route, its days.
+ */
+export type Hop = {
+    /**
+     * - Where the far end lies from the near end.
+     */
+    bearing: string;
+    /**
+     * - The route's marker; absent for a border.
+     */
+    days?: number | undefined;
+};
 /**
  * One place on the map from a place.
  */
 export type FromNode = {
     shortcode: string;
     /**
-     * - 0 for the centre, 1 for a neighbour, 2 beyond.
+     * - 0 for the centre, 1 for a neighbour, 2 and up
+     * beyond — the map from a place stops at 2, the chart goes on.
      */
     hop: number;
     /**
@@ -321,7 +388,8 @@ export type FromNode = {
      */
     unknown: boolean;
     /**
-     * - The neighbour a second hop is reached through.
+     * - The place a hop beyond the neighbours is reached
+     * through.
      */
     via?: string | undefined;
 };
@@ -353,7 +421,7 @@ export type FromEdge = {
         days: number | undefined;
     }>;
     /**
-     * - 1 from the centre, 2 onward.
+     * - 1 from the centre, 2 and up onward.
      */
     hop: number;
 };