@motionscript/geography 0.1.0-alpha.7 → 0.1.0-alpha.9

package/dist/nodes.d.ts

@@ -0,0 +1,15 @@
+import { GeoBorder } from "./border/index.js";
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
+ * Defining a component only *declares* that key: nothing is registered by
+ * importing a module, so a registry holds exactly what its owner asked for.
+ *
+ * Listing the component **values** is also what survives bundling: this package
+ * declares `sideEffects: false`, and a document names a node type by string, so
+ * an import kept only for its side effect is exactly what gets shaken out.
+ */
+export declare const NODES: (typeof GeoBorder)[];
+//# sourceMappingURL=nodes.d.ts.map

package/dist/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../src/nodes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,KAAK,EAAE,CAAC,OAAO,SAAS,CAAC,EAAgB,CAAC"}

package/dist/nodes.js

@@ -0,0 +1,16 @@
+import { GeoBorder } from "./border/index.js";
+/**
+ * Every node type this package publishes.
+ *
+ * A host registers these by handing the array to an engine —
+ * `new Engine(platform, { nodes: NODES })` — which reads each component's key.
+ * Defining a component only *declares* that key: nothing is registered by
+ * importing a module, so a registry holds exactly what its owner asked for.
+ *
+ * Listing the component **values** is also what survives bundling: this package
+ * declares `sideEffects: false`, and a document names a node type by string, so
+ * an import kept only for its side effect is exactly what gets shaken out.
+ */
+// Typed by name, so the declaration names each component rather than spelling out its type through core.
+export const NODES = [GeoBorder];
+//# sourceMappingURL=nodes.js.map

package/dist/nodes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.js","sourceRoot":"","sources":["../src/nodes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAErC;;;;;;;;;;;GAWG;AACH,yGAAyG;AACzG,MAAM,CAAC,MAAM,KAAK,GAAyB,CAAC,SAAS,CAAC,CAAC","sourcesContent":["import { GeoBorder } from \"./border\";\n\n/**\n * Every node type this package publishes.\n *\n * A host registers these by handing the array to an engine —\n * `new Engine(platform, { nodes: NODES })` — which reads each component's key.\n * Defining a component only *declares* that key: nothing is registered by\n * importing a module, so a registry holds exactly what its owner asked for.\n *\n * Listing the component **values** is also what survives bundling: this package\n * declares `sideEffects: false`, and a document names a node type by string, so\n * an import kept only for its side effect is exactly what gets shaken out.\n */\n// Typed by name, so the declaration names each component rather than spelling out its type through core.\nexport const NODES: (typeof GeoBorder)[] = [GeoBorder];\n"]}

package/package.json

@@ -1,48 +1,86 @@
 {
   "name": "@motionscript/geography",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.9",
   "type": "module",
-  "description": "Country and first-level subdivision outlines for Motion Script's GeoBorder, keyed by ISO 3166 code. Derived from Natural Earth (public domain).",
+  "description": "Geography for Motion Script: GeoBorder, and the country and state outlines it draws by ISO 3166 code, derived from Natural Earth (public domain).",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/motionscript-dev/motionscript.git",
-    "directory": "packages/geography"
+    "directory": "packages/components/geography"
   },
   "homepage": "https://motionscript.dev",
   "bugs": {
     "url": "https://github.com/motionscript-dev/motionscript/issues"
   },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "sideEffects": false,
   "files": [
     "NOTICE",
+    "dist",
+    "src",
+    "registry.json",
+    "CHANGELOG.md",
     "data",
     "CREDITS.md",
-    "CHANGELOG.md"
+    "!dist/**/*.tsbuildinfo",
+    "!src/**/tests/**",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.fixtures.ts"
   ],
   "publishConfig": {
     "access": "public"
   },
   "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
     "./package.json": "./package.json",
     "./data/*": "./data/*"
   },
   "keywords": [
     "motion-script",
+    "motion script",
     "geo",
+    "animation",
     "iso-3166",
     "natural-earth"
   ],
   "license": "Apache-2.0",
+  "author": "Motionscript",
+  "peerDependencies": {
+    "@motionscript/sdk": "^0.1.0-alpha.9"
+  },
   "devDependencies": {
-    "d3-geo": "3.1.1",
+    "@types/d3-geo": "^3.1.0",
+    "@types/node": "^25.6.2",
     "d3-geo-projection": "4.0.0",
+    "eslint": "^9.39.4",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.16.1",
     "topojson-client": "3.1.0",
     "topojson-server": "3.0.1",
-    "topojson-simplify": "3.0.3"
+    "topojson-simplify": "3.0.3",
+    "tsc-alias": "^1.8.16",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.48.0",
+    "vitest": "^4.1.5",
+    "@motionscript/core": "0.1.0-alpha.9",
+    "@motionscript/sdk": "0.1.0-alpha.9"
+  },
+  "dependencies": {
+    "d3-geo": "^3.1.1"
   },
   "scripts": {
+    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json --resolve-full-paths && node ../../../scripts/build-browser.mjs",
+    "dev": "tsc -p tsconfig.build.json --watch & tsc-alias -p tsconfig.build.json --resolve-full-paths -w",
+    "clean": "rimraf --glob dist .turbo *.tsbuildinfo",
+    "test": "vitest run && node --test \"scripts/**/*.test.mjs\"",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "generate": "node --max-old-space-size=8192 scripts/generate.mjs",
-    "verify": "node scripts/verify.mjs",
-    "test": "node --test \"scripts/**/*.test.mjs\""
+    "verify": "node scripts/verify.mjs"
   }
 }

package/registry.json

@@ -0,0 +1,16 @@
+{
+  "kit": {
+    "barrel": "src/index.ts",
+    "specifier": "@motionscript/geography"
+  },
+  "items": [
+    {
+      "name": "geo-border",
+      "description": "Country and state outlines by ISO 3166 code, with adjustable detail.",
+      "root": "src/border",
+      "files": [
+        "geo-border.ts"
+      ]
+    }
+  ]
+}

package/src/border/format.ts

@@ -0,0 +1,147 @@
+import { geoArea } from "d3-geo"
+
+/** The on-disk shape `@motionscript/geography` writes; see its `generate.mjs`. */
+export const GEO_DATA_FORMAT = 1
+
+export interface GeoFileData {
+    format: number
+    source?: string
+    transform: { scale: [number, number]; translate: [number, number] }
+    /** Global arc id per local arc — identical across files for a shared border. */
+    arcIds: number[]
+    /** Per arc, flat `[x0, y0, w0, dx, dy, w, …]`: delta-encoded quantized lon/lat and a weight bucket. */
+    arcs: number[][]
+    features: GeoFeatureData[]
+}
+
+export interface GeoFeatureData {
+    code: string
+    name: string
+    nameNl?: string
+    parent: string | null
+    first: boolean
+    listed: boolean
+    remote?: boolean
+    area: number
+    mainland: number[] | null
+    areas: number[]
+    /** Polygons → rings → arc refs (`~i` is arc `i` reversed). */
+    polygons: number[][][]
+}
+
+/** `[code, name, nameNl, parent, first]` per listed region. */
+export type GeoIndexEntry = [string, string, string, string | null, 0 | 1]
+
+export interface GeoIndex {
+    format: number
+    source?: string
+    regions: GeoIndexEntry[]
+}
+
+export interface GeoArc {
+    /** Identity for de-duplicating a border drawn by two regions, across files. */
+    key: number | string
+    /** Interleaved lon/lat, in degrees. */
+    points: Float64Array
+    /** Per point: 0 always survives, higher buckets are less significant; see `thresholdBucket`. */
+    buckets: Uint8Array
+}
+
+export interface GeoRingRef {
+    arc: GeoArc
+    reversed: boolean
+}
+
+export interface GeoPolygon {
+    rings: GeoRingRef[][]
+    /** Per ring, in steradians — exterior first, then holes. */
+    ringAreas: number[]
+    area: number
+    mainland: boolean
+}
+
+export interface GeoFeature {
+    code: string
+    name: string
+    nameNl: string
+    parent: string | null
+    first: boolean
+    listed: boolean
+    remote: boolean
+    polygons: GeoPolygon[]
+}
+
+export interface DecodedGeoFile {
+    features: Map<string, GeoFeature>
+}
+
+function decodeArc(encoded: number[], key: number, [kx, ky]: [number, number], [tx, ty]: [number, number]): GeoArc {
+    const count = encoded.length / 3
+    const points = new Float64Array(count * 2)
+    const buckets = new Uint8Array(count)
+    let x = 0
+    let y = 0
+    for (let i = 0; i < count; i++) {
+        x += encoded[i * 3]
+        y += encoded[i * 3 + 1]
+        points[i * 2] = x * kx + tx
+        points[i * 2 + 1] = y * ky + ty
+        buckets[i] = encoded[i * 3 + 2]
+    }
+    return { key, points, buckets }
+}
+
+export function ringCoordinates(ring: readonly GeoRingRef[]): [number, number][] {
+    const out: [number, number][] = []
+    for (const { arc, reversed } of ring) {
+        const n = arc.buckets.length
+        for (let j = out.length === 0 ? 0 : 1; j < n; j++) {
+            const i = reversed ? n - 1 - j : j
+            out.push([arc.points[i * 2], arc.points[i * 2 + 1]])
+        }
+    }
+    return out
+}
+
+/** A ring's area in steradians, whichever way it winds. */
+export function ringArea(ring: readonly GeoRingRef[]): number {
+    const coordinates = ringCoordinates(ring)
+    if (coordinates.length < 4) return 0
+    const area = geoArea({ type: "Polygon", coordinates: [coordinates] })
+    return area > 2 * Math.PI ? 4 * Math.PI - area : area
+}
+
+export function decodeGeoFile(data: GeoFileData): DecodedGeoFile {
+    if (data.format !== GEO_DATA_FORMAT) {
+        throw new Error(`geo data format ${data.format} is not supported (expected ${GEO_DATA_FORMAT})`)
+    }
+    const arcs = data.arcs.map((encoded, i) =>
+        decodeArc(encoded, data.arcIds[i], data.transform.scale, data.transform.translate)
+    )
+    const ref = (index: number): GeoRingRef =>
+        index < 0 ? { arc: arcs[~index], reversed: true } : { arc: arcs[index], reversed: false }
+
+    const features = new Map<string, GeoFeature>()
+    for (const f of data.features) {
+        const mainland = f.mainland ? new Set(f.mainland) : null
+        features.set(f.code, {
+            code: f.code,
+            name: f.name,
+            nameNl: f.nameNl ?? f.name,
+            parent: f.parent,
+            first: f.first,
+            listed: f.listed,
+            remote: f.remote === true,
+            polygons: f.polygons.map((rings, i) => {
+                const resolved = rings.map((ring) => ring.map(ref))
+                return {
+                    rings: resolved,
+                    ringAreas: resolved.map((ring, r) => (r === 0 ? f.areas[i] : ringArea(ring))),
+                    area: f.areas[i],
+                    mainland: mainland === null || mainland.has(i),
+                }
+            }),
+        })
+    }
+    return { features }
+}

package/src/border/geo-border.ts

@@ -0,0 +1,268 @@
+import {
+    Flow,
+    Graphics2D,
+    Paint,
+    Shapes,
+    Types,
+    component2d,
+    type EntryOptions,
+    type FillResolved,
+    type NodeOf,
+    // Named so this component's emitted type reaches the shape surface it spreads through the sdk, not core.
+    type Alignment as _Alignment,
+    type Fill as _Fill,
+    type FlowMode as _FlowMode,
+    type FlowResolved as _FlowResolved,
+    type GapSize as _GapSize,
+    type Node2D as _Node2D,
+    type Node2DProps as _Node2DProps,
+    type Shadow as _Shadow,
+    type Stroke as _Stroke,
+    type Vector2 as _Vector2,
+    type PathBounds,
+    type ShadowResolved,
+    type ShapeProps,
+    type Size2D,
+    type StrokeResolved,
+    type Type,
+} from "@motionscript/sdk"
+import { snapValue } from "@motionscript/sdk/component"
+
+import { geoGeometry, type GeoBorders, type GeoContour, type GeoGeometry, type GeoProjectionKind } from "./geometry"
+import { geoDataVersion, geoLoader } from "./loader"
+import { geoRegistry } from "./registry"
+import { geoFilesFor, normalizeIso, selectGeoFeatures, type GeoFrame, type GeoLevel } from "./selection"
+
+export interface GeoBorderProps extends ShapeProps {
+    /** ISO 3166-1 alpha-2 (`"FR"`) or ISO 3166-2 (`"US-CA"`) codes. */
+    iso: string | readonly string[]
+    level: GeoLevel
+    /** 0–1: 1 is full resolution, lower is a more stylised outline. */
+    detail: number
+    projection: GeoProjectionKind
+    frame: GeoFrame
+    borders: GeoBorders
+}
+
+interface Chunk {
+    data: string
+    /** Where this chunk's contours sit along the whole drawing, as fractions of its length. */
+    from: number
+    to: number
+}
+
+interface Drawn {
+    geometry: GeoGeometry
+    width: number
+    height: number
+    fills: Chunk[]
+    lines: Chunk[]
+}
+
+// A renderer's cost for one path grows faster than its contour count, and a shape
+// drawn as several paths under one paint is unioned every frame — so a region
+// is cut into paths of bounded size, each painted on its own.
+const CONTOURS_PER_PATH = 256
+const POINTS_PER_PATH = 40_000
+
+const coordinate = (value: number) => String(Math.round(value * 100) / 100)
+
+function chunk(contours: readonly GeoContour[], total: number, scale: number): Chunk[] {
+    const chunks: Chunk[] = []
+    let parts: string[] = []
+    let count = 0
+    let points = 0
+    let from = 0
+    let length = 0
+    const flush = () => {
+        if (count === 0) return
+        const to = total > 0 ? Math.min(1, length / total) : 1
+        chunks.push({ data: parts.join(""), from, to })
+        from = to
+        parts = []
+        count = 0
+        points = 0
+    }
+    for (const contour of contours) {
+        const p = contour.points
+        // Path data is y-down; the unit geometry is y-up.
+        for (let i = 0; i < p.length; i += 2) {
+            parts.push(i === 0 ? "M" : "L", coordinate(p[i] * scale), " ", coordinate(-p[i + 1] * scale))
+        }
+        if (contour.closed) parts.push("Z")
+        count++
+        points += p.length / 2
+        length += contour.length
+        if (count >= CONTOURS_PER_PATH || points >= POINTS_PER_PATH) flush()
+    }
+    flush()
+    return chunks
+}
+
+/** One of `values`, switched at the end of a `to`, with its choices listed as its `options`. */
+function choice<const V extends readonly string[]>(values: V, initial: V[number]): Type<V[number]> {
+    return Types.custom<V[number], V[number], EntryOptions & { readonly options: V }>(initial, { lerp: snapValue, options: values })
+}
+
+/** A node's own drawing state, kept by its fields' view (one object per node, the same every frame). */
+interface Kept {
+    drawn: Drawn | null
+    readonly warned: Set<string>
+}
+
+const kept = new WeakMap<object, Kept>()
+
+function keptBy(state: object): Kept {
+    let entry = kept.get(state)
+    if (!entry) kept.set(state, (entry = { drawn: null, warned: new Set() }))
+    return entry
+}
+
+interface Selected {
+    readonly iso: readonly string[]
+    readonly level: GeoLevel
+    readonly frame: GeoFrame
+    readonly projection: GeoProjectionKind
+    readonly borders: GeoBorders
+    readonly detail: number
+}
+
+/** The selection's outlines cut into paths at `size`, or `null` while there is nothing to draw. */
+function drawnOf(state: Selected, size: Size2D): Drawn | null {
+    const own = keptBy(state)
+    const codes = state.iso
+    const { level, frame } = state
+    const selection = selectGeoFeatures(codes, level, frame)
+    for (const code of selection.unknown) {
+        if (own.warned.has(code)) continue
+        own.warned.add(code)
+        console.warn(`[GeoBorder] no region with code ${code}`)
+    }
+    if (selection.features.length === 0) return null
+
+    const geometry = geoGeometry({
+        selectionKey: `${geoRegistry.generation}:${geoDataVersion()}:${level}:${frame}:${codes.join(",")}`,
+        features: selection.features,
+        frame,
+        projection: state.projection,
+        borders: state.borders,
+        detail: state.detail,
+    })
+    if (!geometry) return null
+
+    const { width, height } = size
+    const cached = own.drawn
+    if (cached && cached.geometry === geometry && cached.width === width && cached.height === height) return cached
+    const scale = Math.min(width / geometry.width, height / geometry.height)
+    const drawn: Drawn = {
+        geometry,
+        width,
+        height,
+        fills: chunk(geometry.fills, geometry.fillLength, scale),
+        lines: chunk(geometry.lines, geometry.lineLength, scale),
+    }
+    own.drawn = drawn
+    return drawn
+}
+
+/** Adds `chunk` to `g`, trimmed by `start`/`end` along the whole drawing; `false` when none of it is drawn. */
+function pathOp(g: Graphics2D, chunk: Chunk, size: Size2D, start: number, end: number): boolean {
+    const { width, height } = size
+    const centerBounds: PathBounds = [-width / 2, -height / 2, width / 2, height / 2]
+    if (start <= 0 && end >= 1) {
+        g.path({ data: chunk.data, centerBounds })
+        return true
+    }
+    const span = chunk.to - chunk.from
+    if (span <= 0) return false
+    const localStart = Math.max(0, (start - chunk.from) / span)
+    const localEnd = Math.min(1, (end - chunk.from) / span)
+    if (localEnd <= localStart) return false
+    g.path({ data: chunk.data, centerBounds, start: localStart, end: localEnd })
+    return true
+}
+
+/**
+ * Country and subdivision outlines by ISO 3166 code, fitted into the node's box.
+ *
+ *   <GeoBorder iso={["FR", "DE"]} detail={0.4} stroke={{ weight: 2, fill: "white" }} />
+ *
+ * Geometry comes from whatever `geoRegistry` has been given — a URL, a loader,
+ * or shapes defined by hand — and loads as a declared asset, so a frame never
+ * draws half a country. Fill and stroke are separate geometry: the fill is each
+ * region's polygons, the stroke is every border once, which is why a border two
+ * selected regions share is not drawn twice and why `stroke.align` does not
+ * apply.
+ */
+export const GeoBorder = component2d({
+    key: "geoBorder",
+    state: {
+        ...Paint.state,
+        ...Flow.state,
+        iso: Types.custom<string | readonly string[], string[]>(["FR"], { resolve: normalizeIso, lerp: snapValue }),
+        level: choice(["country", "state"], "country"),
+        detail: Types.number(0.5, { min: 0, max: 1, step: 0.01 }),
+        projection: choice(["conic", "mercator", "equirectangular", "orthographic"], "conic"),
+        frame: choice(["mainland", "all"], "mainland"),
+        borders: choice(["all", "outline"], "all"),
+    },
+    commands: { ...Paint.commands },
+    // The data gates the draw, not layout: the box never waits on it.
+    load: (loader, state) => {
+        for (const file of geoFilesFor(state.iso, state.level)) loader.task(`geo:${file}`, geoLoader(file))
+    },
+    measure: (measurer, state, children) => Flow.measure(measurer, state, children, Paint.inset(state)),
+    layout: (box, state, children) => Flow.layout(box, state, children, Paint.inset(state)),
+    render: (ctx, state) => {
+        const size = ctx.size
+        const { start, end } = state
+        const fill = state.fill as FillResolved[]
+        const shadow = state.shadow as ShadowResolved[]
+        const drawn = () => drawnOf(state, size)
+
+        ctx.inFront(() => {
+            const shape = drawn()
+            if (!shape || shape.fills.length === 0) return
+            const g = new Graphics2D()
+            for (const part of shape.fills) {
+                if (!pathOp(g, part, size, start, end)) continue
+                if (shadow.length > 0) g.shadow(shadow)
+                g.fill(fill)
+            }
+            ctx.draw(g)
+        })
+
+        // The box, not the outline, confines the children and is what picking
+        // tests: a path clip has no winding test, and a country's bounding box is
+        // what the selection shows.
+        Paint.draw(ctx, state, null, { clipShape: Shapes.box(size) })
+
+        ctx.inFront(() => {
+            const overlay = state.overlay as FillResolved[]
+            if (overlay.length > 0) {
+                const shape = drawn()
+                if (shape) {
+                    const g = new Graphics2D()
+                    for (const part of shape.fills) if (pathOp(g, part, size, start, end)) g.fill(overlay)
+                    ctx.draw(g)
+                }
+            }
+
+            const stroke = state.stroke as StrokeResolved[]
+            if (stroke.length === 0) return
+            const shape = drawn()
+            if (!shape || shape.lines.length === 0) return
+            const centred = stroke.map((layer) => (layer.align === 0 ? layer : { ...layer, align: 0 }))
+            const castsShadow = shadow.length > 0 && !fill.some((layer) => (layer.opacity ?? 1) > 0)
+            const g = new Graphics2D()
+            for (const part of shape.lines) {
+                if (!pathOp(g, part, size, start, end)) continue
+                if (castsShadow) g.shadow(shadow)
+                g.stroke(centred)
+            }
+            ctx.draw(g)
+        })
+    },
+})
+
+export type GeoBorder = NodeOf<typeof GeoBorder>