Add sortable concept entries (closes #336)

Concepts in a ConceptScheme tree and members of a skos:Collection were
rendered in source-TTL order, which is unfriendly when skimming a vocab.

Add a config option `sortBy: "prefLabel" | "notation" | "none"`
(default "prefLabel") that seeds an initial order, plus a Sort selector
in TreeControls so visitors can switch at runtime. Sorting is locale-
and numerically aware via Intl.Collator (e.g. "Item 2" before "Item 10",
"1.1" < "1.2" < "1.10"). Items missing a notation sink to the bottom
when sorting by notation, tie-broken by prefLabel.

TreeControls now also renders for flat schemes so the sort selector is
reachable; Collapse/Expand are hidden when there's no nesting.

Note: existing sites will reorder alphabetically by default after upgrade.
Set `sortBy: "none"` in config.yaml to preserve TTL order.

Author: sroertgen

README.md

@@ -144,6 +144,7 @@ You can configure the following settings:
     - Colors
     - Fonts
 - Searchable Fields
+- Sort order
 
 The settings are explained in the following sections.
 
@@ -166,6 +167,26 @@ Then provide `http://my-awesome-domain.org` as `custom_domain` in your `config.y
 
 If `true` (default) the build process will stop if a validation error occures.
 
+### Sort order
+
+Concept entries inside a ConceptScheme tree (and members of a `skos:Collection`)
+can be sorted at display time. Set the initial default in `config.yaml`:
+
+```yaml
+sortBy: "prefLabel"   # one of: "prefLabel" | "notation" | "none"
+```
+
+- `"prefLabel"` (default) — alphabetical by `skos:prefLabel` in the currently
+  selected language. Locale-aware via `Intl.Collator` and numerically aware
+  (so `Item 2` comes before `Item 10`).
+- `"notation"` — sorted by `skos:notation`. Numeric and dotted numeric
+  notations sort naturally (`1.1`, `1.2`, `1.10`). Items without a notation
+  fall to the bottom and are tie-broken by `prefLabel`.
+- `"none"` — preserves the order in which entries appear in the source TTL.
+
+Visitors can switch between these options at runtime via the **Sort** selector
+that lives next to the Collapse / Expand controls in the tree sidebar.
+
 ### UI
 
 The following customizations can be made:

config.default.yaml

@@ -3,6 +3,7 @@
 tokenizer: "full" # strict, forward, reverse, full
 custom_domain: ""
 fail_on_validation: true
+sortBy: "prefLabel" # one of: "prefLabel" | "notation" | "none" — initial default for the tree/collection sort selector
 searchableAttributes:
   - "prefLabel" # you should not delete this one
   - "notation"

cypress/e2e/sort.cy.js

@@ -0,0 +1,57 @@
+describe("Sort entries", () => {
+  // Top concepts from systematik.ttl, in source (TTL) order:
+  //   n1 Geisteswissenschaften, n2 Sport, n3 Rechts-..., n4 Mathematik,
+  //   n5 Humanmedizin, n7 Agrar-..., n8 Ingenieurwissenschaften, n9 Kunst
+  // Notations: 1, 2, 3, 4, 5, 7, 8, 9
+  // Alphabetical (de): Agrar-, Geisteswissenschaften, Humanmedizin,
+  //   Ingenieurwissenschaften, Kunst, Mathematik, Rechts-, Sport
+  const url = "/w3id.org/kim/hochschulfaechersystematik/scheme.html?lang=de"
+
+  it("renders the sort selector with prefLabel as default", () => {
+    cy.visit(url)
+    cy.findByRole("combobox", { name: /sort entries by/i })
+      .should("exist")
+      .and("have.value", "prefLabel")
+  })
+
+  it("default order is alphabetical by prefLabel", () => {
+    cy.visit(url)
+    // First top-level link in the tree should start with "Agrar"
+    cy.get(".concepts > nav, .concepts").should("exist")
+    cy.get(".concepts ul li > div > a")
+      .first()
+      .invoke("text")
+      .should("match", /Agrar/)
+  })
+
+  it("switching to Notation reorders the tree by notation", () => {
+    cy.visit(url)
+    cy.findByRole("combobox", { name: /sort entries by/i }).select("notation")
+    // Notation 1 → Geisteswissenschaften
+    cy.get(".concepts ul li > div > a")
+      .first()
+      .invoke("text")
+      .should("match", /Geisteswissenschaften/)
+  })
+
+  it("switching to Source order preserves TTL order", () => {
+    cy.visit(url)
+    cy.findByRole("combobox", { name: /sort entries by/i }).select("none")
+    cy.get(".concepts ul li > div > a")
+      .first()
+      .invoke("text")
+      .should("match", /Geisteswissenschaften/)
+  })
+
+  it("sort selector is visible even on flat schemes (no hierarchy)", () => {
+    cy.visit("/purl.org/dcx/lrmi-vocabs/interactivityType/index.html", {
+      onBeforeLoad(win) {
+        Object.defineProperty(win.navigator, "language", { value: "en-EN" })
+      },
+    })
+    cy.findByRole("combobox", { name: /sort entries by/i }).should("exist")
+    // Collapse/Expand should still be hidden on flat schemes
+    cy.contains("Collapse").should("not.exist")
+    cy.contains("Expand").should("not.exist")
+  })
+})

gatsby-config.js

@@ -16,6 +16,7 @@ module.exports = {
     searchableAttributes: config.searchableAttributes,
     customDomain: config.customDomain,
     failOnValidation: config.failOnValidation,
+    sortBy: config.sortBy,
   },
   pathPrefix: `${process.env.BASEURL || ""}`,
   plugins: [

src/components/Collection.jsx

@@ -2,10 +2,13 @@ import { Link } from "gatsby"
 import { i18n, getFilePath } from "../common"
 import JsonLink from "./JsonLink"
 import { useSkoHubContext } from "../context/Context"
+import { getConfigAndConceptSchemes } from "../hooks/configAndConceptSchemes"
+import { sortConcepts } from "../sortConcepts"
 import { useEffect, useState } from "react"
 
 const Collection = ({ pageContext: { node: collection, customDomain } }) => {
   const { data } = useSkoHubContext()
+  const { config } = getConfigAndConceptSchemes()
   const [language, setLanguage] = useState("")
 
   useEffect(() => {
@@ -14,13 +17,16 @@ const Collection = ({ pageContext: { node: collection, customDomain } }) => {
     }
   }, [data?.selectedLanguage])
 
+  const sortBy = data?.sortBy ?? config?.sortBy ?? "prefLabel"
+  const sortedMembers = sortConcepts(collection.member, sortBy, language)
+
   return (
     <div>
       <h1>{i18n(language)(collection.prefLabel)}</h1>
       <h2>{collection.id}</h2>
       <JsonLink to={getFilePath(collection.id, "json", customDomain)} />
       <ul>
-        {collection.member.map((member) => (
+        {sortedMembers.map((member) => (
           <li key={member.id}>
             <Link to={getFilePath(member.id, `html`, customDomain)}>
               {i18n(language)(member.prefLabel) ||

src/components/TreeControls.jsx

@@ -1,44 +1,89 @@
+import { useEffect } from "react"
 import { css } from "@emotion/react"
+import { getConfigAndConceptSchemes } from "../hooks/configAndConceptSchemes"
+import { useSkoHubContext } from "../context/Context"
 
 const style = css`
   display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
   margin-bottom: 10px;
+  align-items: center;
 
   input[type="button"] {
     flex: 1;
     padding: 5px 10px;
+    min-width: 80px;
+  }
+
+  .sortControl {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    margin-left: auto;
+    font-size: 0.9em;
 
-    &:first-of-type {
-      margin-right: 10px;
+    select {
+      padding: 4px 6px;
     }
   }
 `
 
-const TreeControls = () => (
-  <div className="TreeControls" css={style}>
-    <input
-      type="button"
-      className="inputStyle"
-      value="Collapse"
-      onClick={() => {
-        ;[...document.querySelectorAll(".treeItemIcon")].forEach((el) => {
-          el.classList.add("collapsed")
-          el.setAttribute("aria-expanded", false)
-        })
-      }}
-    />
-    <input
-      type="button"
-      className="inputStyle"
-      value="Expand"
-      onClick={() => {
-        ;[...document.querySelectorAll(".collapsed")].forEach((el) => {
-          el.classList.remove("collapsed")
-          el.setAttribute("aria-expanded", true)
-        })
-      }}
-    />
-  </div>
-)
+const TreeControls = ({ hasNesting = true }) => {
+  const { config } = getConfigAndConceptSchemes()
+  const { data, updateState } = useSkoHubContext()
+
+  // Initialise sortBy from config on first render if it hasn't been set yet.
+  useEffect(() => {
+    if (data.sortBy == null) {
+      updateState({ ...data, sortBy: config?.sortBy || "prefLabel" })
+    }
+  }, [data.sortBy, config?.sortBy])
+
+  const currentSort = data.sortBy ?? config?.sortBy ?? "prefLabel"
+
+  return (
+    <div className="TreeControls" css={style}>
+      {hasNesting && (
+        <>
+          <input
+            type="button"
+            className="inputStyle"
+            value="Collapse"
+            onClick={() => {
+              ;[...document.querySelectorAll(".treeItemIcon")].forEach((el) => {
+                el.classList.add("collapsed")
+                el.setAttribute("aria-expanded", false)
+              })
+            }}
+          />
+          <input
+            type="button"
+            className="inputStyle"
+            value="Expand"
+            onClick={() => {
+              ;[...document.querySelectorAll(".collapsed")].forEach((el) => {
+                el.classList.remove("collapsed")
+                el.setAttribute("aria-expanded", true)
+              })
+            }}
+          />
+        </>
+      )}
+      <label className="sortControl">
+        Sort:
+        <select
+          aria-label="Sort entries by"
+          value={currentSort}
+          onChange={(e) => updateState({ ...data, sortBy: e.target.value })}
+        >
+          <option value="prefLabel">Label</option>
+          <option value="notation">Notation</option>
+          <option value="none">Source order</option>
+        </select>
+      </label>
+    </div>
+  )
+}
 
 export default TreeControls

src/components/nestedList.jsx

@@ -5,6 +5,7 @@ import { Link as GatsbyLink } from "gatsby"
 
 import { getConfigAndConceptSchemes } from "../hooks/configAndConceptSchemes"
 import { useSkoHubContext } from "../context/Context"
+import { sortConcepts } from "../sortConcepts"
 
 const getNestedItems = (item) => {
   let ids = [item.id]
@@ -151,7 +152,8 @@ const NestedList = ({
     }
   }
 
-  const filteredItems = getFilteredItems()
+  const sortBy = data?.sortBy ?? config?.sortBy ?? "prefLabel"
+  const filteredItems = sortConcepts(getFilteredItems(), sortBy, language)
   const t = i18n(language)
 
   const isExpanded = (item, truthy, falsy) => {

src/context/Context.jsx

@@ -5,6 +5,7 @@ const defaultState = {
   selectedLanguage: "",
   conceptSchemeLanguages: [],
   indexPage: false,
+  sortBy: null,
 }
 const Context = createContext(defaultState)
 

src/hooks/configAndConceptSchemes.js

@@ -85,6 +85,7 @@ export const getConfigAndConceptSchemes = () => {
           searchableAttributes
           customDomain
           failOnValidation
+          sortBy
         }
       }
       allConceptScheme {

src/sortConcepts.js

@@ -0,0 +1,47 @@
+const { i18n } = require("./common")
+
+/**
+ * Stable, locale-aware sort for SKOS-shaped items (concepts, collection
+ * members, top concepts).
+ *
+ * @param {Array} items
+ * @param {"prefLabel" | "notation" | "none" | null | undefined} sortBy
+ * @param {string} language - BCP-47 language tag used both to pick the
+ *   prefLabel string and as the locale for Intl.Collator
+ * @returns {Array} a new array (input is not mutated). When sortBy is "none"
+ *   or falsy, the original array is returned unchanged.
+ */
+const sortConcepts = (items, sortBy, language) => {
+  if (!Array.isArray(items) || items.length < 2) return items
+  if (!sortBy || sortBy === "none") return items
+
+  const t = i18n(language)
+  const collator = new Intl.Collator(language || undefined, {
+    numeric: true,
+    sensitivity: "base",
+  })
+
+  const labelOf = (item) => t(item.prefLabel) || item.id || ""
+  const notationOf = (item) =>
+    Array.isArray(item.notation) && item.notation.length > 0
+      ? String(item.notation[0])
+      : ""
+
+  const compareByLabel = (a, b) => collator.compare(labelOf(a), labelOf(b))
+
+  const compareByNotation = (a, b) => {
+    const na = notationOf(a)
+    const nb = notationOf(b)
+    if (na && nb) return collator.compare(na, nb)
+    // Items without a notation sink below items that have one; among the
+    // notation-less, fall back to prefLabel so the order is still meaningful.
+    if (na && !nb) return -1
+    if (!na && nb) return 1
+    return compareByLabel(a, b)
+  }
+
+  const compare = sortBy === "notation" ? compareByNotation : compareByLabel
+  return [...items].sort(compare)
+}
+
+module.exports = { sortConcepts }