ogm-viewer 0.4.0 → 0.5.0

package/dist/collection/components/ogm-preview/ogm-preview.js

@@ -0,0 +1,144 @@
+import { h, Host } from "@stencil/core";
+import IIIFSource from "../../lib/sources/iiif";
+// Wraps a single source's preview and surfaces error(s) during the preview.
+export class OgmPreview {
+    theme;
+    source;
+    previewOpacity;
+    sidebarPadding;
+    error;
+    // A new source is a fresh load attempt, so clear any error left over from the previous one.
+    resetError() {
+        this.error = undefined;
+    }
+    // Catch the load error emitted by the child map/image and show it in place of the preview.
+    handlePreviewError(event) {
+        event.stopPropagation();
+        this.error = event.detail;
+    }
+    // IIIF sources use the image viewer; every other source type is previewed on the map.
+    renderPreview() {
+        if (this.source instanceof IIIFSource) {
+            return h("ogm-image", { theme: this.theme, source: this.source, padding: this.sidebarPadding });
+        }
+        return h("ogm-map", { "preview-opacity": this.previewOpacity, theme: this.theme, source: this.source, padding: this.sidebarPadding });
+    }
+    render() {
+        return (h(Host, { key: 'c962bdcbebdebb1abde8900b0d0811be218fca46' }, this.renderPreview(), this.error && h("ogm-alerts", { key: '87b8217bbb7d5101d9f306f2492326d3f9f92429', theme: this.theme, error: this.error })));
+    }
+    static get is() { return "ogm-preview"; }
+    static get encapsulation() { return "shadow"; }
+    static get originalStyleUrls() {
+        return {
+            "$": ["ogm-preview.css"]
+        };
+    }
+    static get styleUrls() {
+        return {
+            "$": ["ogm-preview.css"]
+        };
+    }
+    static get properties() {
+        return {
+            "theme": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'light' | 'dark'",
+                    "resolved": "\"dark\" | \"light\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "theme"
+            },
+            "source": {
+                "type": "unknown",
+                "mutable": false,
+                "complexType": {
+                    "original": "Source",
+                    "resolved": "Source",
+                    "references": {
+                        "Source": {
+                            "location": "global",
+                            "id": "global::Source"
+                        }
+                    }
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false
+            },
+            "previewOpacity": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "preview-opacity"
+            },
+            "sidebarPadding": {
+                "type": "number",
+                "mutable": false,
+                "complexType": {
+                    "original": "number",
+                    "resolved": "number",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [],
+                    "text": ""
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "sidebar-padding"
+            }
+        };
+    }
+    static get states() {
+        return {
+            "error": {}
+        };
+    }
+    static get watchers() {
+        return [{
+                "propName": "source",
+                "methodName": "resetError"
+            }];
+    }
+    static get listeners() {
+        return [{
+                "name": "previewError",
+                "method": "handlePreviewError",
+                "target": undefined,
+                "capture": false,
+                "passive": false
+            }];
+    }
+}

package/dist/collection/components/ogm-preview/ogm-preview.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, h, vi } from "@stencil/vitest";
+// Render with Stencil's low-level render directly rather than @stencil/vitest's `render` wrapper: the
+// wrapper re-throws lifecycle errors, and the <ogm-map>/<ogm-image> mounted inside a preview throw
+// when they try to initialize WebGL/OpenSeadragon (unavailable in the test DOM).
+import { render as stencilRender } from "@stencil/core";
+import GeoJSONSource from "../../lib/sources/geojson";
+import { referenceError } from "../../lib/errors";
+// Let Stencil's RAF-based update cycle flush after a state change (mirrors the vitest waitForChanges).
+const flush = () => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+const renderPreview = async (source) => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+    await stencilRender(h("ogm-preview", { source: source }), container);
+    const el = container.firstElementChild;
+    await el.componentOnReady?.();
+    consoleError.mockRestore();
+    return el;
+};
+describe('ogm-preview', () => {
+    it('renders a preview for a source', async () => {
+        const el = await renderPreview(new GeoJSONSource('id', 'http://example.com/data.json'));
+        const shadowRoot = el.shadowRoot;
+        expect(shadowRoot.querySelector('ogm-map')).not.toBeNull();
+        expect(shadowRoot.querySelector('ogm-alerts')).toBeNull();
+    });
+    it('shows the error over the preview when a previewError is reported', async () => {
+        const el = await renderPreview(new GeoJSONSource('id', 'http://example.com/data.json'));
+        const error = referenceError(new TypeError('Failed to fetch'), 'GeoJSON', 'http://example.com/data.json');
+        el.dispatchEvent(new CustomEvent('previewError', { detail: error, bubbles: true }));
+        await flush();
+        const shadowRoot = el.shadowRoot;
+        expect(shadowRoot.querySelector('ogm-alerts')).not.toBeNull();
+        // The preview stays mounted underneath so its in-flight load can finish and not leak loading state
+        expect(shadowRoot.querySelector('ogm-map')).not.toBeNull();
+    });
+});

package/dist/collection/components/ogm-previews/ogm-previews.css

@@ -37,8 +37,9 @@ wa-tab::part(base) {
   font-size: var(--wa-font-size-s);
 }
 
-ogm-map,
-ogm-image {
+/* ogm-preview wraps each tab's map/image; ogm-map is also rendered bare as the no-record fallback. */
+ogm-preview,
+ogm-map {
   display: block;
   height: 100%;
 }

package/dist/collection/components/ogm-previews/ogm-previews.js

@@ -10,25 +10,15 @@ import XYZSource from "../../lib/sources/xyz";
 import IIIFSource from "../../lib/sources/iiif";
 import IIIFManifestSource from "../../lib/sources/iiif-manifest";
 export class OgmPreviews {
-    el;
     theme;
     record;
     previewOpacity;
     sidebarPadding;
     sources = [];
-    // Pick the appropriate preview to render based on the source type
-    renderPreview(source) {
-        if (source instanceof IIIFSource)
-            return this.renderImagePreview(source);
-        return this.renderMapPreview(source);
-    }
-    // Render an image preview
-    renderImagePreview(source) {
-        return h("ogm-image", { theme: this.theme, source: source, padding: this.sidebarPadding });
-    }
-    // Render a map preview
-    renderMapPreview(source) {
-        return h("ogm-map", { "preview-opacity": this.previewOpacity, theme: this.theme, source: source, padding: this.sidebarPadding });
+    // @Watch only fires on changes; handle the initial load here
+    componentWillLoad() {
+        if (this.record)
+            this.getSources(this.record);
     }
     // Given a record, get all of the valid sources that can be used to preview it on a map
     getSources(record) {
@@ -58,9 +48,10 @@ export class OgmPreviews {
     }
     // Render as tabs for switching between sources
     render() {
-        if (!this.record)
+        // Render a blank map if there is no record or no sources
+        if (!this.record || !this.sources.length)
             return h("ogm-map", { theme: this.theme, padding: this.sidebarPadding });
-        return (h(Host, { class: this.theme && `wa-${this.theme}` }, h("wa-tab-group", null, this.sources.map((source, idx) => (h("wa-tab", { key: idx, panel: `${source.constructor.name}-${source.id}-${idx}` }, source.label()))), this.sources.map((source, idx) => (h("wa-tab-panel", { key: idx, name: `${source.constructor.name}-${source.id}-${idx}`, active: idx === 0 }, this.renderPreview(source)))))));
+        return (h(Host, { class: this.theme && `wa-${this.theme}` }, h("wa-tab-group", null, this.sources.map((source, idx) => (h("wa-tab", { key: idx, panel: `${source.constructor.name}-${source.id}-${idx}` }, source.label()))), this.sources.map((source, idx) => (h("wa-tab-panel", { key: idx, name: `${source.constructor.name}-${source.id}-${idx}`, active: idx === 0 }, h("ogm-preview", { theme: this.theme, source: source, "preview-opacity": this.previewOpacity, "sidebar-padding": this.sidebarPadding })))))));
     }
     static get is() { return "ogm-previews"; }
     static get encapsulation() { return "shadow"; }
@@ -162,7 +153,6 @@ export class OgmPreviews {
             "sources": {}
         };
     }
-    static get elementRef() { return "el"; }
     static get watchers() {
         return [{
                 "propName": "record",

package/dist/collection/components/ogm-previews/ogm-previews.test.js

@@ -0,0 +1,83 @@
+import { describe, it, expect, h, vi } from "@stencil/vitest";
+// Render with Stencil's low-level render directly rather than @stencil/vitest's `render` wrapper: the
+// wrapper re-throws lifecycle errors, and the <ogm-map> mounted inside a preview panel throws when it
+// tries to initialize WebGL (unavailable in the test DOM). Stencil's own safeCall only routes that to
+// console.error, so stencilRender still produces the ogm-previews shadow DOM we want to assert on.
+import { render as stencilRender } from "@stencil/core";
+import OgmRecord from "../../lib/record";
+// Build a minimal Aardvark record, optionally with a WMS reference that yields one previewable source
+const buildRecord = (previewable) => new OgmRecord({
+    id: 'berkeley-s7sq63',
+    dct_title_s: 'Calaveras County Contours',
+    gbl_resourceClass_sm: ['Datasets'],
+    dct_accessRights_s: 'Public',
+    gbl_mdVersion_s: 'Aardvark',
+    ...(previewable
+        ? {
+            gbl_wxsIdentifier_s: 's7sq63',
+            dct_references_s: JSON.stringify({ 'http://www.opengis.net/def/serviceType/ogc/wms': 'https://example.com/geoserver/wms' }),
+        }
+        : {}),
+});
+const renderPreviews = async (record) => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    // The mounted <ogm-map> logs a swallowed WebGL init error; keep test output clean
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+    await stencilRender(h("ogm-previews", { record: record }), container);
+    const el = container.firstElementChild;
+    await el.componentOnReady?.();
+    consoleError.mockRestore();
+    return el.shadowRoot;
+};
+// Let Stencil's RAF-based update cycle flush so the nested <ogm-preview> renders its own shadow DOM.
+const flush = () => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+// Render previews and drill into the single <ogm-preview> to see which preview (map or image) it
+// chose. Going through <ogm-previews> means the source is constructed in the built component's module
+// realm, so <ogm-preview>'s `instanceof IIIFSource` check holds (unlike a source built in the test).
+const renderPreviewChild = async (record) => {
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => { });
+    await stencilRender(h("ogm-previews", { record: record }), container);
+    const el = container.firstElementChild;
+    await el.componentOnReady?.();
+    const preview = el.shadowRoot.querySelector('ogm-preview');
+    await preview?.componentOnReady?.();
+    await flush();
+    consoleError.mockRestore();
+    return preview.shadowRoot;
+};
+// A minimal Aardvark record whose only reference is the given previewable one
+const buildRecordWith = (references) => new OgmRecord({
+    id: 'test-record',
+    dct_title_s: 'Test Record',
+    gbl_resourceClass_sm: ['Datasets'],
+    dct_accessRights_s: 'Public',
+    gbl_mdVersion_s: 'Aardvark',
+    dct_references_s: JSON.stringify(references),
+});
+describe('ogm-previews', () => {
+    it('renders a tab for a record supplied at initial render', async () => {
+        const shadowRoot = await renderPreviews(buildRecord(true));
+        const tabs = shadowRoot.querySelectorAll('wa-tab');
+        expect(shadowRoot.querySelector('wa-tab-group')).not.toBeNull();
+        expect(tabs).toHaveLength(1);
+        expect(tabs[0].textContent).toContain('WMS');
+    });
+    it('falls back to an empty map for a record with no previewable sources', async () => {
+        const shadowRoot = await renderPreviews(buildRecord(false));
+        expect(shadowRoot.querySelector('wa-tab-group')).toBeNull();
+        expect(shadowRoot.querySelector('ogm-map')).not.toBeNull();
+    });
+    it('wraps a map source in an ogm-preview that renders the map', async () => {
+        const previewShadow = await renderPreviewChild(buildRecordWith({ 'http://geojson.org/geojson-spec.html': 'https://example.com/data.json' }));
+        expect(previewShadow.querySelector('ogm-map')).not.toBeNull();
+        expect(previewShadow.querySelector('ogm-image')).toBeNull();
+    });
+    it('wraps a IIIF image source in an ogm-preview that renders the image viewer', async () => {
+        const previewShadow = await renderPreviewChild(buildRecordWith({ 'http://iiif.io/api/image': 'https://example.com/iiif/info.json' }));
+        expect(previewShadow.querySelector('ogm-image')).not.toBeNull();
+        expect(previewShadow.querySelector('ogm-map')).toBeNull();
+    });
+});

package/dist/collection/components/ogm-settings/ogm-settings.js

@@ -12,7 +12,7 @@ export class OgmSettings {
         this.opacityChange.emit(this.waSlider.value);
     }
     render() {
-        return (h("div", { key: '706e4027a015a9904b6a0ce792a35482b7b3e7ef', class: "settings" }, h("wa-slider", { key: '70129a4d1aab6fef042d818009814c8ffe5129f6', disabled: !this.record || this.record.references.iiifOnly, label: "Layer opacity", min: "0", max: "100", step: "1", value: "100" })));
+        return (h("div", { key: 'e2b21549c2bb82aa80780e99bcbed78497683690', class: "settings" }, h("wa-slider", { key: 'bc45061a08522c2e227be5b422cac15fb6da04c3', disabled: !this.record || this.record.references.iiifOnly, label: "Layer opacity", min: "0", max: "100", step: "1", value: "100" })));
     }
     static get is() { return "ogm-settings"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ogm-sidebar/ogm-sidebar.js

@@ -20,7 +20,7 @@ export class OgmSidebar {
             this.tabs.active = 'information';
     }
     render() {
-        return (h(Host, { key: 'f509e573871fdc8b54f33577f1f036401c087ea9', class: this.theme && `wa-${this.theme}` }, h("div", { key: '111ac328e9ba5d3bbc4d0783117c89e071e71b92', class: `sidebar ${this.open ? 'open' : ''}`, role: "region", "aria-label": "Sidebar", "aria-hidden": this.open ? 'false' : 'true' }, h("wa-tab-group", { key: '67d4ed7726ec166956c3ac27eb055938c9dc90c2', placement: "start" }, h("wa-tab", { key: '040c71d6ea4f023b1b37f24c0a12faa027d8873b', slot: "nav", panel: "information" }, h("wa-icon", { key: '84faaf111905ab96fdc2103a93ca17c50eadb03c', name: "info-circle-fill", label: "Information", canvas: "auto" })), h("wa-tab", { key: '59331d6334e81951fb2602accbe4a941cb0f38e2', slot: "nav", panel: "rights" }, h("wa-icon", { key: 'b86d3a0e2b4eac72727f23d531298943cba592a4', name: "c-circle", label: "Rights", canvas: "auto" })), h("wa-tab", { key: '829cb148639415680a29c3f274649a82935bb2ed', slot: "nav", panel: "links" }, h("wa-icon", { key: 'f9a083c20ab0073a3826eca7ffdf270292d0c521', name: "box-arrow-up-right", label: "Links", canvas: "auto" })), h("wa-tab", { key: 'e8eeaea243304648eb68d5b14ba9b7ed661c515c', slot: "nav", panel: "record" }, h("wa-icon", { key: '58b892bd76b00627c39b1d657d1728d221358a13', name: "braces", label: "Record", canvas: "auto" })), h("wa-tab", { key: '7f1363299fccd4e9f8ff56d5fda23c8bed277506', slot: "nav", panel: "settings" }, h("wa-icon", { key: '362f697d663fed741277d58c6e553baf1cca3a22', name: "sliders", label: "Settings", canvas: "auto" })), h("wa-tab-panel", { key: '09941411a1f7410b732ba2b319e5cdc886e2d390', name: "information" }, h("div", { key: '679de2935761f12cfbfd43e2330b02864333dcf1', class: "panel-header" }, "About this item"), h("div", { key: '6572b357d462d3e808d1f0b3dcf6fab7f693cdb0', class: "panel-content" }, h("ogm-metadata", { key: '9964e3d0f392837cdeca4deb4b6c8066d8848cb7', record: this.record, fieldNames: [
+        return (h(Host, { key: 'f2b189bf52bcb7deaec53be53c79083423ac2cc7', class: this.theme && `wa-${this.theme}` }, h("div", { key: '42ecd1fd9391fde0dd9cd8c0f2f2ca78d9cedea1', class: `sidebar ${this.open ? 'open' : ''}`, role: "region", "aria-label": "Sidebar", "aria-hidden": this.open ? 'false' : 'true' }, h("wa-tab-group", { key: '61d629c83e125027857e2e634131254f6f621b71', placement: "start" }, h("wa-tab", { key: '35b9b6998f79be73d7e30ed9ee87045b95a06130', slot: "nav", panel: "information" }, h("wa-icon", { key: '7335b6c1e7024b64d5183057eb39f5c3daacc0e1', name: "info-circle-fill", label: "Information", canvas: "auto" })), h("wa-tab", { key: 'cf39ed59867f70ebfb58eddea1a916d4a9b839be', slot: "nav", panel: "rights" }, h("wa-icon", { key: 'b664695aeaedf956d0881a1916ad341841a23c1f', name: "c-circle", label: "Rights", canvas: "auto" })), h("wa-tab", { key: 'aa6172e06b0349fedb1c35cbc6ed03cb4cfa17a5', slot: "nav", panel: "links" }, h("wa-icon", { key: 'a47c7cb356f776f042a41fe610810119bc9ed6ca', name: "box-arrow-up-right", label: "Links", canvas: "auto" })), h("wa-tab", { key: '9befb56e552c93464ac2e1cc5979de92ada1832b', slot: "nav", panel: "record" }, h("wa-icon", { key: 'fd2d86ba6459eecce6303668e91a71723090829d', name: "braces", label: "Record", canvas: "auto" })), h("wa-tab", { key: '54ad126ec6eef8b89e5748528d6e30ef3f7dcd6f', slot: "nav", panel: "settings" }, h("wa-icon", { key: 'abf83b541d84ccca8caff08fa505c262b8338157', name: "sliders", label: "Settings", canvas: "auto" })), h("wa-tab-panel", { key: '933d76a9e75741b9b17e0924888963e8777d512d', name: "information" }, h("div", { key: 'd0639a93e8cf8d79cbc0486c699db57a6b46f207', class: "panel-header" }, "About this item"), h("div", { key: 'b4415b06fd5e7fbce31107b41a527b6e524bf056', class: "panel-content" }, h("ogm-metadata", { key: '1eb858dd9f4fd676e4fb1f4ec7ca5f8210e21f5e', record: this.record, fieldNames: [
                 'title',
                 'description',
                 'creators',
@@ -34,7 +34,7 @@ export class OgmSidebar {
                 'temporal',
                 'issued',
                 'mdModified',
-            ] }))), h("wa-tab-panel", { key: 'e57bbf559dd6587f4ac315a7fae175e3882bf245', name: "rights" }, h("div", { key: '4d207bd556a1c9975c1fe2ba7273898c7cb277d5', class: "panel-header" }, "Access conditions"), h("div", { key: '4cddf05f500b47b374f8abcf97aafe7f5778043a', class: "panel-content" }, h("ogm-metadata", { key: 'c5a8ab75b87ef32d3ccddd6eaaac67ffe161643d', record: this.record, fieldNames: ['provider', 'license', 'rights', 'rightsHolder'] }))), h("wa-tab-panel", { key: '3c61e94ea9387ec5574288ac02f0c5018698d340', name: "links" }, h("div", { key: '96866a01e6cfa16cfd7d01d5333b9d815bece444', class: "panel-header" }, "Links"), h("div", { key: 'd6a80e54d2484a50731fd80d210ab8608ff3b2b5', class: "panel-content" }, h("ogm-metadata", { key: '96ff29be57f6595f7a3e0fc3153f62415f0d004a', record: this.record, fieldNames: ['references'] }))), h("wa-tab-panel", { key: '4cdf9eee5be8b6bfa5d244a7a6d0835e1401e5ee', name: "record" }, h("div", { key: '70dc344f36664a6f2ae3de51fcfe6e4dada6ccf4', class: "panel-header" }, "Record view"), h("div", { key: '9de08526fa39cf08f6ae98b08fc6967d21c920d1', class: "panel-content" }, h("div", { key: '794e50ba83554943042102a1b2ef177a8a503e52', class: "record-json" }, JSON.stringify(this.record?.json, null, 2)))), h("wa-tab-panel", { key: '17afdc4e66bb2cc1f479cbd89c8c2b12c75b4c02', name: "settings" }, h("div", { key: 'a488b05c7ccd9e8778b0beb885b12ddcd67b77d0', class: "panel-header" }, "Settings"), h("div", { key: 'c33204c002758a55420c71cc1f60165e0f45d7ba', class: "panel-content" }, h("ogm-settings", { key: '0023f3f43cacc9b41c1fe6548b96002340d975ad', record: this.record })))))));
+            ] }))), h("wa-tab-panel", { key: '8bf2a486e918a0b172ec68261d43ab01d1e5927c', name: "rights" }, h("div", { key: '1ec5efad4edb737994982bc0e371174963437cb9', class: "panel-header" }, "Access conditions"), h("div", { key: '88e876ae699f82eec351217f731effcbd571036a', class: "panel-content" }, h("ogm-metadata", { key: '939c58b4fa0d96b3e042d951fac4199b448a757d', record: this.record, fieldNames: ['provider', 'license', 'rights', 'rightsHolder'] }))), h("wa-tab-panel", { key: '47563dce1a1d067f9ef2186e9ab423fe2f2725d9', name: "links" }, h("div", { key: '9021c78ef541235486f2d7a7d3fbeb88b02e3ec4', class: "panel-header" }, "Links"), h("div", { key: '868438dd07bfa1bdbfae1c8d9680c17aee026c31', class: "panel-content" }, h("ogm-metadata", { key: '868ac799f80c71e3730e80c9ee47afd887e4f22d', record: this.record, fieldNames: ['references'] }))), h("wa-tab-panel", { key: '1ca6a74b3b1a1b606a8a873ffae74ec6521a5fd6', name: "record" }, h("div", { key: '63f3998c6b8ba4cfed63e4b62d52b9ca7199ddcf', class: "panel-header" }, "Record view"), h("div", { key: '484f7b7ccd92f29ddfc1b9710b7a30868f39d63a', class: "panel-content" }, h("div", { key: '581a35264c287d71a77a897731c8a2d4098dcc4e', class: "record-json" }, JSON.stringify(this.record?.json, null, 2)))), h("wa-tab-panel", { key: '45f76acfae788d0e1fd5e158e54295c31b2b47ce', name: "settings" }, h("div", { key: '08e8c15c9e079d84a8444cb32bef6443feb303ce', class: "panel-header" }, "Settings"), h("div", { key: '9681b37b6e0c83cd5c2c953bbe90efbdfbbf6cc0', class: "panel-content" }, h("ogm-settings", { key: '00638f2ebf0a7a47f6df47aaf688492f42e86915', record: this.record })))))));
     }
     static get is() { return "ogm-sidebar"; }
     static get encapsulation() { return "shadow"; }

package/dist/collection/components/ogm-viewer/ogm-viewer.js

@@ -1,6 +1,7 @@
 import { setBasePath, getBasePath, registerIconLibrary } from "@awesome.me/webawesome";
 import { Host, getAssetPath, h } from "@stencil/core";
 import OgmRecord from "../../lib/record";
+import { fetchOrThrow, recordError } from "../../lib/errors";
 // Only need to call this once, at the top level
 setBasePath(getAssetPath(''));
 // Serve icons from our self-hosted bootstrap-icons subset instead of the default Font Awesome library
@@ -10,9 +11,9 @@ registerIconLibrary('default', {
 // Web Awesome's raw color palette is scoped to `:root`, which can only ever match the actual
 // document root - never an element inside a shadow tree, so a component-scoped @import can't
 // activate it. Loading it here, at the document level, lets it match `:root` for real, and lets
-// its `.wa-light`/`.wa-dark` theme rules match the <ogm-viewer> host itself (see render() below),
-// from which every token inherits down through the rest of the shadow tree. Injecting it here
-// means consumers don't have to remember to add it to their own page.
+// its `.wa-light`/`.wa-dark` theme rules match Host element in each component because that element
+// is part of the page light DOM and not the shadow DOM. Injecting it here means consumers
+// don't have to remember to add it to their own page.
 function loadWebAwesomeStylesheet() {
     const id = 'ogm-viewer-webawesome-styles';
     if (document.getElementById(id))
@@ -26,6 +27,7 @@ function loadWebAwesomeStylesheet() {
 loadWebAwesomeStylesheet();
 // Import all required Web Awesome components
 import "@awesome.me/webawesome/dist/components/button/button.js";
+import "@awesome.me/webawesome/dist/components/callout/callout.js";
 import "@awesome.me/webawesome/dist/components/icon/icon.js";
 import "@awesome.me/webawesome/dist/components/scroller/scroller.js";
 import "@awesome.me/webawesome/dist/components/slider/slider.js";
@@ -39,9 +41,11 @@ export class OgmViewer {
     recordUrl;
     theme = this.getThemePreference();
     record;
+    error;
     previewOpacity = 100;
     sidebarOpen = false;
     loading = false;
+    loadingCount = 0;
     sidebarPadding = 0;
     // Prior to rendering, fetch the record if a URL is provided
     async componentWillLoad() {
@@ -63,32 +67,44 @@ export class OgmViewer {
     }
     // Can be called externally to set the record directly
     async loadRecord(record) {
+        this.error = undefined;
         this.record = record;
     }
     // Listen for opacity changes from the sidebar and adjust the preview layer
     adjustPreviewOpacity(event) {
         this.previewOpacity = event.detail;
     }
-    // Listen for map to report loading started
+    // Listen for a preview to report loading started
     setLoadingStarted() {
+        this.loadingCount++;
         this.loading = true;
     }
-    // Listen for map to report loading finished
+    // When all in-flight previews have loaded, clear loading state
     setLoadingFinished() {
+        this.loadingCount = Math.max(0, this.loadingCount - 1);
+        this.loading = this.loadingCount > 0;
+    }
+    // When a new record loads, reset the loading count and loading state
+    resetLoading() {
+        this.loadingCount = 0;
         this.loading = false;
     }
-    // Fetch a record by URL and parse it into an OgmRecord instance
+    // Fetch a record by URL and parse it into an OgmRecord instance.
     async fetchRecord(recordUrl) {
-        const response = await fetch(recordUrl);
-        const data = await response.json();
-        return new OgmRecord(data);
+        this.error = undefined;
+        try {
+            const response = await fetchOrThrow(recordUrl);
+            const data = await response.json();
+            return new OgmRecord(data);
+        }
+        catch (error) {
+            console.error(`Error loading record ${recordUrl}:`, error);
+            this.error = recordError(error, recordUrl);
+            return undefined;
+        }
     }
     render() {
-        return (
-        // Applying the theme class to the host (rather than an internal div) lets the document-level
-        // Web Awesome stylesheet's `.wa-light`/`.wa-dark` rules match it directly, since the host sits
-        // in the consuming page's own light DOM while everything inside this shadow root does not.
-        h(Host, { key: 'db64abdf2b961976aa7359d089a57dcaf37fb175', class: `wa-${this.theme}` }, h("div", { key: '8fc67a48693890f017f481b91d0b870a79a5dc58', class: "container" }, h("ogm-menubar", { key: '9818fefb02eec280b73319c87e0a11b93bd69626', theme: this.theme, record: this.record, loading: this.loading }), h("div", { key: '5653ffea28fe78c8aa2d254db29e5c5d0ece96eb', class: "main-container" }, h("ogm-sidebar", { key: '97bda51d3b84e9d535e25bc1abb7615703485450', theme: this.theme, record: this.record, open: this.sidebarOpen }), h("ogm-previews", { key: '97f8dab53279ac2a9ce5f0a1da2e9f0dcb4ec5fd', theme: this.theme, record: this.record, "preview-opacity": this.previewOpacity, "sidebar-padding": this.sidebarPadding })))));
+        return (h(Host, { key: '6fae950d74eac18eca8192c3ab22d27cde8f8215', class: `wa-${this.theme}` }, h("div", { key: 'ddaf990f2145b165c24ded5272ec3f0f11d32df1', class: "container" }, h("ogm-menubar", { key: '93de36998fdfe07aaea28ee1d32512d129402ae6', theme: this.theme, record: this.record, loading: this.loading }), h("div", { key: 'cafd7e0862a8c39008caee372da2e79b48df2aec', class: "main-container" }, h("ogm-sidebar", { key: '03b5f864d35a385de6941f3eac9b1da050422eb9', theme: this.theme, record: this.record, open: this.sidebarOpen }), this.error ? (h("ogm-alerts", { theme: this.theme, error: this.error })) : (h("ogm-previews", { theme: this.theme, record: this.record, "preview-opacity": this.previewOpacity, "sidebar-padding": this.sidebarPadding }))))));
     }
     static get is() { return "ogm-viewer"; }
     static get encapsulation() { return "shadow"; }
@@ -148,8 +164,10 @@ export class OgmViewer {
     static get states() {
         return {
             "record": {},
+            "error": {},
             "previewOpacity": {},
-            "sidebarOpen": {}
+            "sidebarOpen": {},
+            "loading": {}
         };
     }
     static get methods() {
@@ -186,6 +204,9 @@ export class OgmViewer {
         return [{
                 "propName": "recordUrl",
                 "methodName": "updateRecord"
+            }, {
+                "propName": "record",
+                "methodName": "resetLoading"
             }];
     }
     static get listeners() {

package/dist/collection/lib/errors.js

@@ -0,0 +1,137 @@
+// Supertype for errors thrown inside ogm-viewer. `message` is inherited from Error; redeclaring it
+// here would emit an uninitialized class field that clobbers the value super() sets (under the
+// es2022 define-fields semantics this project compiles with), leaving every subtype's message empty.
+export class PreviewError extends Error {
+    title;
+    url;
+}
+// The OGM record URL responded with a non-OK HTTP status.
+class RecordLoadError extends PreviewError {
+    title = "This record couldn't be loaded";
+    constructor(status, url) {
+        super(`The record URL responded with an error (HTTP ${status}). Check that the URL is correct and the record is publicly available.`);
+        this.url = url;
+    }
+}
+// The OGM record URL fetch failed due to a network error or CORS restriction.
+class RecordNetworkError extends PreviewError {
+    title = "This record couldn't be reached";
+    constructor(url) {
+        super('The server may be unreachable, or it may be blocking cross-origin (CORS) requests from this page.');
+        this.url = url;
+    }
+}
+// The OGM record couldn't be parsed as JSON.
+class RecordParseError extends PreviewError {
+    title = "This record couldn't be parsed";
+    constructor(url) {
+        super("The record URL didn't return valid JSON metadata. It may be pointing at an HTML page or a malformed file.");
+        this.url = url;
+    }
+}
+// Something else went wrong reading the record.
+class RecordReadError extends PreviewError {
+    title = "This record couldn't be read";
+    constructor(message, url) {
+        super(message);
+        this.url = url;
+    }
+}
+// The reference URL responded with a non-OK HTTP status.
+class ReferenceLoadError extends PreviewError {
+    constructor(refType, status, url) {
+        super(`The reference URL responded with an error (HTTP ${status}). Check that the URL is correct and the reference is publicly available.`);
+        this.title = `The ${refType} preview couldn't be loaded`;
+        this.url = url;
+    }
+}
+// The reference URL fetch failed due to a network error or CORS restriction.
+class ReferenceNetworkError extends PreviewError {
+    constructor(refType, url) {
+        super('The server may be unreachable, or it may be blocking cross-origin (CORS) requests from this page.');
+        this.title = `The ${refType} preview couldn't be reached`;
+        this.url = url;
+    }
+}
+// Something else went wrong reading the reference.
+class ReferenceReadError extends PreviewError {
+    constructor(refType, message, url) {
+        super(message);
+        this.title = `The ${refType} preview couldn't be read`;
+        this.url = url;
+    }
+}
+// Used to re-raise HTTP responses from fetch() with a non-OK status as PreviewErrors
+export class HttpError extends Error {
+    status;
+    statusText;
+    url;
+    constructor(url, status, statusText) {
+        super(`HTTP ${status} ${statusText} for ${url}`);
+        this.name = 'HttpError';
+        this.status = status;
+        this.statusText = statusText;
+        this.url = url;
+    }
+}
+// Execute a fetch() and raise HttpError on non-OK status
+export async function fetchOrThrow(url, init) {
+    const response = await fetch(url, init);
+    if (!response.ok)
+        throw new HttpError(url, response.status, response.statusText);
+    return response;
+}
+// Attempt to get a useful HTTP status code from any error. We only keep values
+// over 400 because MapLibre uses code "0", which isn't a real HTTP status.
+function statusOf(error) {
+    if (error instanceof HttpError)
+        return error.status;
+    const status = error?.status;
+    return typeof status === 'number' && status >= 400 ? status : undefined;
+}
+// A fetch() failure to reach the server at all, or a CORS block, rejects with a TypeError. MapLibre
+// reports the same class of failure on its internal tile/data requests with a synthetic status of 0
+// (not a real HTTP status). Treat both as a network error so the user sees the unreachable/CORS
+// message rather than a generic read error or a nonsensical "HTTP 0".
+function isNetworkError(error) {
+    if (error instanceof TypeError)
+        return true;
+    return error?.status === 0;
+}
+// Attempt get a useful message from any error.
+function messageOf(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return undefined;
+}
+// Generate a PreviewError when something went wrong loading the record.
+export function recordError(error, url) {
+    const status = statusOf(error);
+    const message = messageOf(error);
+    // The request failed to reach the server at all, or was blocked by CORS.
+    if (isNetworkError(error))
+        return new RecordNetworkError(url);
+    // If we have an HTTP status code, the server responded.
+    if (status !== undefined)
+        return new RecordLoadError(status, url);
+    // A SyntaxError here means we got a response but it wasn't valid JSON metadata.
+    if (error instanceof SyntaxError)
+        return new RecordParseError(url);
+    // Anything else (e.g. an unsupported metadata version thrown by OgmRecord's constructor).
+    return new RecordReadError(message ?? 'An unknown error occurred while reading this record.', url);
+}
+// Generate a PreviewError when something went wrong loading an individual reference.
+export function referenceError(error, refType, url) {
+    const status = statusOf(error);
+    const message = messageOf(error);
+    // The request failed to reach the server at all, or was blocked by CORS.
+    if (isNetworkError(error))
+        return new ReferenceNetworkError(refType, url);
+    // If we have an HTTP status code, the server responded.
+    if (status !== undefined)
+        return new ReferenceLoadError(refType, status, url);
+    // Anything else.
+    return new ReferenceReadError(refType, message ?? 'An unknown error occurred while reading this reference.', url);
+}