From 12ed686dd6bd3aee1c413f212062c441c4f97456 Mon Sep 17 00:00:00 2001
From: Raymond Yee <raymond.yee@gmail.com>
Date: Tue, 28 Apr 2026 17:13:40 -0700
Subject: [PATCH 1/2] Explorer: render SKOS prefLabels for facet URIs (#148
 step 2)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wires the vocab_labels.parquet artifact (now live at
data.isamples.org/vocab_labels.parquet, 58KB) into the Material /
Sampled Feature / Specimen Type facets. Adds vocabLabels (URI →
prefLabel Map) and a prettyLabel(uri) helper with last-segment
fallback for any URIs not declared in the TTLs (4 known stragglers,
~169 of ~6M samples — see #148). Each checkbox row now shows the
prefLabel with the full URI in a hover tooltip.

Smoke-tested locally: 0 JS exceptions, 0 console errors, 0 network
failures. Preload hint added for cache-warm parity with the other
parquets.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 tutorials/isamples_explorer.qmd | 47 ++++++++++++++++++++++++++++-----
 1 file changed, 41 insertions(+), 6 deletions(-)

diff --git a/tutorials/isamples_explorer.qmd b/tutorials/isamples_explorer.qmd
index a3d1a44..99c84c6 100644
--- a/tutorials/isamples_explorer.qmd
+++ b/tutorials/isamples_explorer.qmd
@@ -11,6 +11,7 @@ format:
         <link rel="preconnect" href="https://data.isamples.org" crossorigin>
         <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/isamples_202601_facet_summaries.parquet">
         <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/isamples_202601_facet_cross_filter.parquet">
+        <link rel="preload" as="fetch" crossorigin="anonymous" href="https://data.isamples.org/vocab_labels.parquet">
         <script>
         // Opt-in perf panel (?perf=1). Plain script — independent of the
         // OJS reactive graph, which was unreliable at firing this cell.
@@ -98,6 +99,10 @@ cross_filter_url = "https://data.isamples.org/isamples_202601_facet_cross_filter
 // Facets file for on-the-fly multi-filter queries (63MB - URI strings, not BIGINT FKs)
 sample_facets_url = "https://data.isamples.org/isamples_202601_sample_facets_v2.parquet"
 
+// Vocabulary labels (~60KB) — maps SKOS concept URIs to human-readable prefLabels.
+// Built by scripts/build_vocab_labels.py from isamplesorg/vocabularies TTLs. See #148.
+vocab_labels_url = "https://data.isamples.org/vocab_labels.parquet"
+
 // Source color scheme — imported from canonical palette (issue #113)
 _palette = await import(new URL('/assets/js/source-palette.js', document.baseURI).href)
 SOURCE_COLORS = _palette.SOURCE_COLORS
@@ -180,8 +185,8 @@ viewof materialCheckboxes = {
     format: (x) => {
       const r = counts.find(s => s.value === x);
       const count = r ? Number(r.count).toLocaleString() : "0";
-      return html`<span style="display: inline-flex; align-items: center; gap: 4px;">
-        ${x} <span class="facet-count" data-facet="material" data-value="${x}" style="color: #888; font-size: 11px;">(${count})</span>
+      return html`<span style="display: inline-flex; align-items: center; gap: 4px;" title="${x}">
+        ${prettyLabel(x)} <span class="facet-count" data-facet="material" data-value="${x}" style="color: #888; font-size: 11px;">(${count})</span>
       </span>`;
     }
   });
@@ -201,8 +206,8 @@ viewof contextCheckboxes = {
     format: (x) => {
       const r = counts.find(s => s.value === x);
       const count = r ? Number(r.count).toLocaleString() : "0";
-      return html`<span style="display: inline-flex; align-items: center; gap: 4px;">
-        ${x} <span class="facet-count" data-facet="context" data-value="${x}" style="color: #888; font-size: 11px;">(${count})</span>
+      return html`<span style="display: inline-flex; align-items: center; gap: 4px;" title="${x}">
+        ${prettyLabel(x)} <span class="facet-count" data-facet="context" data-value="${x}" style="color: #888; font-size: 11px;">(${count})</span>
       </span>`;
     }
   });
@@ -222,8 +227,8 @@ viewof objectTypeCheckboxes = {
     format: (x) => {
       const r = counts.find(s => s.value === x);
       const count = r ? Number(r.count).toLocaleString() : "0";
-      return html`<span style="display: inline-flex; align-items: center; gap: 4px;">
-        ${x} <span class="facet-count" data-facet="object_type" data-value="${x}" style="color: #888; font-size: 11px;">(${count})</span>
+      return html`<span style="display: inline-flex; align-items: center; gap: 4px;" title="${x}">
+        ${prettyLabel(x)} <span class="facet-count" data-facet="object_type" data-value="${x}" style="color: #888; font-size: 11px;">(${count})</span>
       </span>`;
     }
   });
@@ -457,6 +462,36 @@ facetsByType = {
 }
 ```
 
+```{ojs}
+//| code-fold: true
+// Load SKOS prefLabels for vocabulary URIs (#148). Tiny lookup (~60KB);
+// fallback to last URI segment if a URI isn't covered.
+vocabLabels = {
+  try {
+    const rows = await runQuery(
+      `SELECT uri, pref_label FROM read_parquet('${vocab_labels_url}') WHERE lang = 'en'`
+    );
+    const m = new Map();
+    for (const r of rows) m.set(r.uri, r.pref_label);
+    return m;
+  } catch (e) {
+    console.warn("vocab_labels load failed; falling back to URI tails:", e);
+    return new Map();
+  }
+}
+
+prettyLabel = function (uri) {
+  if (uri == null) return "";
+  const hit = vocabLabels.get(uri);
+  if (hit) return hit;
+  // Fallback: last non-empty path segment of the URI
+  const s = String(uri);
+  if (!/^https?:\/\//.test(s)) return s;
+  const parts = s.replace(/[#?].*$/, "").split("/").filter(Boolean);
+  return parts.length ? parts[parts.length - 1] : s;
+}
+```
+
 ```{ojs}
 //| code-fold: true
 // Cross-filter: build WHERE clause excluding one facet dimension

From a6f1cd97561b02708f2b47741130654fe4a438b4 Mon Sep 17 00:00:00 2001
From: Raymond Yee <raymond.yee@gmail.com>
Date: Tue, 28 Apr 2026 17:47:10 -0700
Subject: [PATCH 2/2] Use path-relative source-palette import for fork-preview
 compatibility

The three OJS pages that import the canonical SOURCE_COLORS palette
were resolving '/assets/js/source-palette.js' against the origin,
which works on isamples.org (custom domain at root) but 404s on
project-pages fork previews like rdhyee.github.io/isamplesorg.github.io/...
The failed import cascades through the OJS reactive graph and breaks
every downstream cell in the Explorer / progressive globe.

Switch to '../assets/...' (and '../../assets/...' for the archived
tutorial one level deeper) so document.baseURI does the right thing
in both deploy modes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 tutorials/archive/parquet_cesium_isamples_wide.qmd | 2 +-
 tutorials/isamples_explorer.qmd                    | 5 ++++-
 tutorials/progressive_globe.qmd                    | 6 ++++--
 3 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/tutorials/archive/parquet_cesium_isamples_wide.qmd b/tutorials/archive/parquet_cesium_isamples_wide.qmd
index b748070..4380b9a 100644
--- a/tutorials/archive/parquet_cesium_isamples_wide.qmd
+++ b/tutorials/archive/parquet_cesium_isamples_wide.qmd
@@ -96,7 +96,7 @@ viewof viewModeToggle = Inputs.radio(["clustered", "all points"], {
 ```{ojs}
 //| echo: false
 // Source color scheme — imported from canonical palette (issue #113)
-_palette = await import(new URL('/assets/js/source-palette.js', document.baseURI).href)
+_palette = await import(new URL('../../assets/js/source-palette.js', document.baseURI).href)
 CLUSTER_COLORS = _palette.SOURCE_COLORS
 
 // H3 resolution based on camera height
diff --git a/tutorials/isamples_explorer.qmd b/tutorials/isamples_explorer.qmd
index 99c84c6..a4f5691 100644
--- a/tutorials/isamples_explorer.qmd
+++ b/tutorials/isamples_explorer.qmd
@@ -104,7 +104,10 @@ sample_facets_url = "https://data.isamples.org/isamples_202601_sample_facets_v2.
 vocab_labels_url = "https://data.isamples.org/vocab_labels.parquet"
 
 // Source color scheme — imported from canonical palette (issue #113)
-_palette = await import(new URL('/assets/js/source-palette.js', document.baseURI).href)
+// Use a path-relative URL so this works under both the production custom
+// domain (isamples.org/tutorials/...) and a project-pages fork preview
+// (rdhyee.github.io/isamplesorg.github.io/tutorials/...).
+_palette = await import(new URL('../assets/js/source-palette.js', document.baseURI).href)
 SOURCE_COLORS = _palette.SOURCE_COLORS
 
 // Cesium colors
diff --git a/tutorials/progressive_globe.qmd b/tutorials/progressive_globe.qmd
index aec008e..6686bee 100644
--- a/tutorials/progressive_globe.qmd
+++ b/tutorials/progressive_globe.qmd
@@ -208,8 +208,10 @@ wide_url = `${R2_BASE}/current/wide.parquet`
 facets_url = `${R2_BASE}/isamples_202601_sample_facets.parquet`
 facet_summaries_url = `${R2_BASE}/isamples_202601_facet_summaries.parquet`
 
-// Canonical palette — see issue #113
-_palette = await import(new URL('/assets/js/source-palette.js', document.baseURI).href)
+// Canonical palette — see issue #113. Path-relative so this works under
+// both isamples.org (custom domain at root) and project-pages fork
+// previews (rdhyee.github.io/isamplesorg.github.io/...).
+_palette = await import(new URL('../assets/js/source-palette.js', document.baseURI).href)
 SOURCE_COLORS = _palette.SOURCE_COLORS
 SOURCE_NAMES = _palette.SOURCE_NAMES