@abcnews/components-storylab 0.0.1 → 0.0.2

package/README.md

@@ -2,9 +2,27 @@
 
 A live repo containing reusable components and snippts by Story Lab. This repo is subject to change.
 
+## Installation
+
+1. Install the package:
+   ```sh
+   npm i @abcnews/components-storylab
+   ```
+2. Add the package to your `aunty` config's `includedDependencies` array in `package.json` so it gets built properly:
+   ```js
+     "aunty": {
+       "type": "svelte",
+       "build": {
+         "includedDependencies": [
+           "@abcnews/components-storylab"
+         ]
+       }
+     }
+   ```
+
 ## Components
 
-### initDarkModeIframe
+### 🌃 initDarkModeIframe
 
 Initializes dark mode inside an iframe, synchronizing with the parent site or system preferences.
 
@@ -16,8 +34,47 @@ import { initDarkModeIframe } from "@abcnews/components-storylab";
 initDarkModeIframe();
 ```
 
+### 🌏 MapLibre
+
+Tools and components for working with MapLibre. The `utils` export gives you the
+tools to do this yourself, whereas the MapLibreLoader component handles it for
+you in Svelte. Import these from `@abcnews/components-storylab/mapLibre`.
+
+#### MapLibreLoader
+
+Call back when MapLibre is loaded. Passes the `maplibre` namespace and a root
+node for you to use.
+
+```ts
+import type { maplibregl } from "@abcnews/components-storylab/mapLibre";
+import { MapLibreLoader, utils } from "@abcnews/components-storylab/mapLibre";
+
+// Load MapLibre and use it in your component
+const { loadMapLibre, STYLE_BRIGHT, STYLE_LIGHT } = utils;
+
+// Example of using MapLibreLoader in a Svelte component
+<MapLibreLoader
+  onLoad={({ rootNode, maplibregl }) => {
+    const map = new maplibregl.Map({
+      container: rootNode,
+      style: STYLE_BRIGHT,
+    });
+    return map;
+  }}
+/>
+```
+
+If you return the Map from `onLoad`, you can componentise your viz and access it
+from child components with:
+
+```ts
+let { map } = getContext<Map>("mapInstance");
+```
+
+This component will attempt to keep the map stable, so you can not change
+props after the fact. If you want to destroy the map and create a new one
+when props change, wrap it in a {#key}{/key} block/
+
 ## Developing
 
 See [DEVELOPMENT.md](DEVELOPMENT.md)
-
-Note: I haven't been able to `npm link` svelte components into an Aunty project. If you work this out please let me know.

package/dist/index.js

@@ -1,2 +1,3 @@
 // Reexport your entry components here
+// iframes
 export { default as initDarkModeIframe } from "./utils/initDarkModeIframe/initDarkModeIframe.js";

package/dist/mapLibre/MapLibreLoader/MapLibreLoader.stories.svelte

@@ -0,0 +1,58 @@
+<script module>
+  import { defineMeta } from "@storybook/addon-svelte-csf";
+  import MapLibreLoader from "./MapLibreLoader.svelte";
+
+  // More on how to set up stories at: https://storybook.js.org/docs/writing-stories
+  const { Story } = defineMeta({
+    title: "MapLibre/MapLibreLoader",
+    component: MapLibreLoader,
+    tags: ["autodocs"],
+  });
+</script>
+
+<Story
+  name="Bright style"
+  args={{
+    rootElStyle: "width:100%;height:calc(100dvh - 2rem);",
+    onLoad: async ({ rootNode, maplibregl }) => {
+      const map = new maplibregl.Map({
+        zoom: 3,
+        minZoom: 2,
+        maxZoom: 22,
+        attributionControl: false,
+        dragRotate: false,
+        doubleClickZoom: false,
+        style:
+          "https://www.abc.net.au/res/sites/news-projects/map-vector-style-bright/style.json",
+        container: rootNode,
+        interactive: true,
+        cooperativeGestures: true,
+        center: [133.28, -28.15],
+      });
+      return map;
+    },
+  }}
+></Story>
+<Story
+  name="Light style"
+  args={{
+    rootElStyle: "width:100%;height:calc(100dvh - 2rem);",
+    onLoad: async ({ rootNode, maplibregl }) => {
+      const map = new maplibregl.Map({
+        zoom: 3,
+        minZoom: 2,
+        maxZoom: 22,
+        attributionControl: false,
+        dragRotate: false,
+        doubleClickZoom: false,
+        style:
+          "https://www.abc.net.au/res/sites/news-projects/map-vector-style-light/style.json",
+        container: rootNode,
+        interactive: true,
+        cooperativeGestures: true,
+        center: [133.28, -28.15],
+      });
+      return map;
+    },
+  }}
+></Story>

package/dist/mapLibre/MapLibreLoader/MapLibreLoader.stories.svelte.d.ts

@@ -0,0 +1,27 @@
+export default MapLibreLoader;
+type MapLibreLoader = SvelteComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}> & {
+    $$bindings?: string | undefined;
+};
+declare const MapLibreLoader: $$__sveltets_2_IsomorphicComponent<{
+    [x: string]: never;
+}, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+import MapLibreLoader from "./MapLibreLoader.svelte";
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import("svelte").ComponentConstructorOptions<Props>): import("svelte").SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}

package/dist/mapLibre/MapLibreLoader/MapLibreLoader.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+  import { onMount, setContext, untrack } from "svelte";
+  import { loadMapLibre } from "../utils.js";
+  import type { maplibregl } from "../maplibre.d.js";
+  import type { Snippet } from "svelte";
+  type Props = {
+    rootElStyle?: string;
+    onLoad: ({}: {
+      rootNode: HTMLDivElement;
+      maplibregl: typeof maplibregl;
+    }) => maplibregl.Map | Promise<maplibregl.Map> | void | Promise<void>;
+    onTeardown?: () => void | Promise<void>;
+    children?: Snippet;
+  };
+  const {
+    rootElStyle = "width:100%;height:100%;",
+    onLoad,
+    children,
+  }: Props = $props();
+  let rootNode = $state<HTMLDivElement>();
+  let status = $state<"loading" | "loaded">("loading");
+  let mapInstance = $state<{ map: maplibregl.Map | void }>({ map: undefined });
+  setContext("mapInstance", mapInstance);
+
+  onMount(async () => {
+    if (!rootNode) {
+      return;
+    }
+    await loadMapLibre();
+    const newMapInstance = await onLoad({
+      rootNode,
+      maplibregl: window.maplibregl,
+    });
+    mapInstance.map = newMapInstance;
+    status = "loaded";
+  });
+</script>
+
+<div class="maplibre" bind:this={rootNode} style={rootElStyle}>
+  {@render children?.()}
+</div>
+
+<style>
+  .maplibre {
+    width: 100%;
+    height: 100%;
+  }
+</style>

package/dist/mapLibre/MapLibreLoader/MapLibreLoader.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { maplibregl } from "../maplibre.d.ts";
+import type { Snippet } from "svelte";
+type Props = {
+    rootElStyle?: string;
+    onLoad: ({}: {
+        rootNode: HTMLDivElement;
+        maplibregl: typeof maplibregl;
+    }) => maplibregl.Map | Promise<maplibregl.Map> | void | Promise<void>;
+    onTeardown?: () => void | Promise<void>;
+    children?: Snippet;
+};
+declare const MapLibreLoader: import("svelte").Component<Props, {}, "">;
+type MapLibreLoader = ReturnType<typeof MapLibreLoader>;
+export default MapLibreLoader;

package/dist/mapLibre/index.d.ts

@@ -0,0 +1,3 @@
+export { default as MapLibreLoader } from "./MapLibreLoader/MapLibreLoader.svelte";
+export * as utils from "./utils.ts";
+export type { maplibregl } from "./maplibre.d.ts";

package/dist/mapLibre/index.js

@@ -0,0 +1,3 @@
+// MapLibre
+export { default as MapLibreLoader } from "./MapLibreLoader/MapLibreLoader.svelte";
+export * as utils from "./utils.js";

package/dist/mapLibre/maplibre.d.ts

@@ -0,0 +1,6 @@
+/**
+ * We only use the npm version of MapLibre for its types, and keep the version
+ * synced to the shared version in news-projects.
+ */
+import type * as maplibregl from "maplibre-gl/dist/maplibre-gl.d.ts";
+export type { maplibregl };

package/dist/mapLibre/utils.d.ts

@@ -0,0 +1,20 @@
+import type { maplibregl } from "./maplibre.d.ts";
+export declare const MAPLIBRE_JS_URL = "https://www.abc.net.au/res/sites/news-projects/maplibre/v5.x.x-latest/maplibre-gl.js";
+export declare const MAPLIBRE_CSS_URL = "https://www.abc.net.au/res/sites/news-projects/maplibre/v5.x.x-latest/maplibre-gl.css";
+/** Colourful style */
+export declare const STYLE_BRIGHT = "https://www.abc.net.au/res/sites/news-projects/map-vector-style-bright/style.json";
+/** Grey style */
+export declare const STYLE_LIGHT = "https://www.abc.net.au/res/sites/news-projects/map-vector-style-light/style.json";
+/**
+ * Load common MapLibre version from news-projects.
+ *
+ * To keep bundle sizes, deploys, and end user downloads svelte, we can load
+ * MapLibre from news-projects. This version is updated only when the major
+ * version changes, which should be safe given semver conventions.
+ *
+ * - Regular visitors should only need to download & parse MapLibre once, ever,
+ *   no matter how many different deploys or projects they hit.
+ * - Build sizes stay small, preventing duplication & deploy size blowouts
+ * - Build times are quicker with MapLibre externalised.
+ */
+export declare function loadMapLibre(): Promise<typeof maplibregl>;

package/dist/mapLibre/utils.js

@@ -0,0 +1,58 @@
+export const MAPLIBRE_JS_URL = "https://www.abc.net.au/res/sites/news-projects/maplibre/v5.x.x-latest/maplibre-gl.js";
+export const MAPLIBRE_CSS_URL = "https://www.abc.net.au/res/sites/news-projects/maplibre/v5.x.x-latest/maplibre-gl.css";
+/** Colourful style */
+export const STYLE_BRIGHT = "https://www.abc.net.au/res/sites/news-projects/map-vector-style-bright/style.json";
+/** Grey style */
+export const STYLE_LIGHT = "https://www.abc.net.au/res/sites/news-projects/map-vector-style-light/style.json";
+const promises = {};
+function importModule(url) {
+    const key = "module" + url;
+    const promise = promises[key];
+    if (promise) {
+        return promise;
+    }
+    const newPromise = new Promise((resolve, reject) => {
+        const s = document.createElement("script");
+        s.src = url;
+        s.type = "module";
+        s.addEventListener("load", () => resolve());
+        s.addEventListener("error", reject);
+        document.head.appendChild(s);
+    });
+    promises[key] = newPromise;
+    return newPromise;
+}
+function loadCss(url) {
+    const key = "css" + url;
+    const promise = promises[key];
+    if (promise) {
+        return promise;
+    }
+    const newPromise = new Promise((resolve, reject) => {
+        const s = document.createElement("link");
+        s.rel = "stylesheet";
+        s.type = "text/css";
+        s.href = url;
+        s.addEventListener("load", () => resolve());
+        s.addEventListener("error", reject);
+        document.head.appendChild(s);
+    });
+    promises[key] = newPromise;
+    return newPromise;
+}
+/**
+ * Load common MapLibre version from news-projects.
+ *
+ * To keep bundle sizes, deploys, and end user downloads svelte, we can load
+ * MapLibre from news-projects. This version is updated only when the major
+ * version changes, which should be safe given semver conventions.
+ *
+ * - Regular visitors should only need to download & parse MapLibre once, ever,
+ *   no matter how many different deploys or projects they hit.
+ * - Build sizes stay small, preventing duplication & deploy size blowouts
+ * - Build times are quicker with MapLibre externalised.
+ */
+export async function loadMapLibre() {
+    await Promise.all([importModule(MAPLIBRE_JS_URL), loadCss(MAPLIBRE_CSS_URL)]);
+    return window.maplibregl;
+}

package/package.json

@@ -1,14 +1,18 @@
 {
   "name": "@abcnews/components-storylab",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "scripts": {
-    "dev": "vite dev",
-    "build": "vite build && npm run prepack",
+    "dev": "npm run storybook",
+    "build": "npm run prepack",
     "preview": "vite preview",
     "prepare": "svelte-kit sync || echo ''",
     "prepack": "svelte-kit sync && svelte-package && publint",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
-    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch"
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "test:unit": "vitest",
+    "test": "npm run test:unit -- --run",
+    "storybook": "export AUNTY_HOST=${AUNTY_HOST:-localhost} && storybook dev -p 6006 --host $AUNTY_HOST --ci",
+    "build-storybook": "storybook build"
   },
   "files": [
     "dist",
@@ -25,30 +29,40 @@
     ".": {
       "types": "./dist/index.d.ts",
       "svelte": "./dist/index.js"
+    },
+    "./mapLibre": {
+      "types": "./dist/mapLibre/index.d.ts",
+      "default": "./dist/mapLibre/index.js"
     }
   },
   "peerDependencies": {
     "svelte": "^5.0.0"
   },
   "devDependencies": {
+    "@storybook/addon-svelte-csf": "^5.0.10",
+    "@storybook/sveltekit": "^10.1.11",
     "@sveltejs/adapter-auto": "^7.0.0",
     "@sveltejs/kit": "^2.49.1",
     "@sveltejs/package": "^2.5.7",
     "@sveltejs/vite-plugin-svelte": "^6.2.1",
+    "@types/node": "^24",
+    "@vitest/browser-playwright": "^4.0.15",
+    "maplibre-gl": "^5.16.0",
+    "playwright": "^1.57.0",
     "publint": "^0.3.15",
+    "sass-embedded": "^1.97.2",
+    "storybook": "^10.1.11",
     "svelte": "^5.45.6",
     "svelte-check": "^4.3.4",
     "typescript": "^5.9.3",
-    "vite": "^7.2.6"
+    "vite": "^7.2.6",
+    "vitest": "^4.0.15",
+    "vitest-browser-svelte": "^2.0.1"
   },
   "keywords": [
     "svelte"
   ],
   "license": "MIT",
   "homepage": "https://github.com/abcnews/components-storylab",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/abcnews/components-storylab.git"
-  },
-  "private": false
+  "repository": "github:abcnews/components-storylab"
 }