From ee02bc3efebf992c47694ec4065f658473b1f904 Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 13:32:10 -0400
Subject: data: validateArrayItems: annotate multiline errors nicely

---
 src/data/things/validators.js | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

(limited to 'src/data')

diff --git a/src/data/things/validators.js b/src/data/things/validators.js
index f60c363c..e213e933 100644
--- a/src/data/things/validators.js
+++ b/src/data/things/validators.js
@@ -1,5 +1,9 @@
 import {inspect as nodeInspect} from 'node:util';
 
+// Heresy.
+import printable_characters from 'printable-characters';
+const {strlen} = printable_characters;
+
 import {colors, ENABLE_COLOR} from '#cli';
 import {empty, typeAppearance, withAggregate} from '#sugar';
 
@@ -174,8 +178,19 @@ function validateArrayItemsHelper(itemValidator) {
         throw new Error(`Expected validator to return true`);
       }
     } catch (error) {
-      error.message = `(index: ${colors.yellow(`${index}`)}, item: ${inspect(item)}) ${error.message}`;
+      const annotation = `(index: ${colors.yellow(`${index}`)}, item: ${inspect(item)})`;
+
+      error.message =
+        (error.message.includes('\n') || strlen(annotation) > 20
+          ? annotation + '\n' +
+            error.message
+              .split('\n')
+              .map(line => `  ${line}`)
+              .join('\n')
+          : `${annotation} ${error}`);
+
       error[Symbol.for('hsmusic.decorate.indexInSourceArray')] = index;
+
       throw error;
     }
   };
-- 
cgit 1.3.0-6-gf8a5


From 2d58b70d0bd5bbc7cdd8789332a31a220c78da01 Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 13:48:52 -0400
Subject: data: validateArrayItems (etc): pass through index, array

---
 src/data/things/validators.js | 16 +++++++++-------
 1 file changed, 9 insertions(+), 7 deletions(-)

(limited to 'src/data')

diff --git a/src/data/things/validators.js b/src/data/things/validators.js
index e213e933..2893e7fd 100644
--- a/src/data/things/validators.js
+++ b/src/data/things/validators.js
@@ -170,9 +170,9 @@ export function is(...values) {
 }
 
 function validateArrayItemsHelper(itemValidator) {
-  return (item, index) => {
+  return (item, index, array) => {
     try {
-      const value = itemValidator(item);
+      const value = itemValidator(item, index, array);
 
       if (value !== true) {
         throw new Error(`Expected validator to return true`);
@@ -197,13 +197,15 @@ function validateArrayItemsHelper(itemValidator) {
 }
 
 export function validateArrayItems(itemValidator) {
-  const fn = validateArrayItemsHelper(itemValidator);
+  const helper = validateArrayItemsHelper(itemValidator);
 
   return (array) => {
     isArray(array);
 
-    withAggregate({message: 'Errors validating array items'}, ({wrap}) => {
-      array.forEach(wrap(fn));
+    withAggregate({message: 'Errors validating array items'}, ({call}) => {
+      for (let index = 0; index < array.length; index++) {
+        call(helper, array[index], index, array);
+      }
     });
 
     return true;
@@ -215,12 +217,12 @@ export function strictArrayOf(itemValidator) {
 }
 
 export function sparseArrayOf(itemValidator) {
-  return validateArrayItems(item => {
+  return validateArrayItems((item, index, array) => {
     if (item === false || item === null) {
       return true;
     }
 
-    return itemValidator(item);
+    return itemValidator(item, index, array);
   });
 }
 
-- 
cgit 1.3.0-6-gf8a5


From 9a35630d91ebd7227994a1009487794a65ec38e1 Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 13:53:36 -0400
Subject: data: tidy yaml error message construction, cut long strings

...Using maxStringLength, which is more than a bit annoying,
because this isn't the same cut() algorithm we just added,
looks bulkier, and can't be customized. But that's the cost
of using util.inspect() here. It's better than displaying the
entire long string or handling line breaks poorly. FOR NOW.
---
 src/data/yaml.js | 38 +++++++++++++++++++++++++++++++-------
 1 file changed, 31 insertions(+), 7 deletions(-)

(limited to 'src/data')

diff --git a/src/data/yaml.js b/src/data/yaml.js
index 0734d539..49e05266 100644
--- a/src/data/yaml.js
+++ b/src/data/yaml.js
@@ -38,8 +38,8 @@ import {
 
 // --> General supporting stuff
 
-function inspect(value) {
-  return nodeInspect(value, {colors: ENABLE_COLOR});
+function inspect(value, opts = {}) {
+  return nodeInspect(value, {colors: ENABLE_COLOR, ...opts});
 }
 
 // --> YAML data repository structure constants
@@ -308,7 +308,12 @@ export class FieldCombinationError extends Error {
   constructor(fields, message) {
     const fieldNames = Object.keys(fields);
 
-    const mainMessage = `Don't combine ${fieldNames.map(field => colors.red(field)).join(', ')}`;
+    const fieldNamesText =
+      fieldNames
+        .map(field => colors.red(field))
+        .join(', ');
+
+    const mainMessage = `Don't combine ${fieldNamesText}`;
 
     const causeMessage =
       (typeof message === 'function'
@@ -330,7 +335,12 @@ export class FieldCombinationError extends Error {
 
 export class FieldValueAggregateError extends AggregateError {
   constructor(thingConstructor, errors) {
-    super(errors, `Errors processing field values for ${colors.green(thingConstructor.name)}`);
+    const constructorText =
+      colors.green(thingConstructor.name);
+
+    super(
+      errors,
+      `Errors processing field values for ${constructorText}`);
   }
 }
 
@@ -341,8 +351,17 @@ export class FieldValueError extends Error {
         ? caughtError.cause
         : caughtError);
 
+    const fieldText =
+      colors.green(`"${field}"`);
+
+    const propertyText =
+      colors.green(property);
+
+    const valueText =
+      inspect(value, {maxStringLength: 40});
+
     super(
-      `Failed to set ${colors.green(`"${field}"`)} field (${colors.green(property)}) to ${inspect(value)}`,
+      `Failed to set ${fieldText} field (${propertyText}) to ${valueText}`,
       {cause});
   }
 }
@@ -354,13 +373,18 @@ export class SkippedFieldsSummaryError extends Error {
     const lines =
       entries.map(([field, value]) =>
         ` - ${field}: ` +
-        inspect(value)
+        inspect(value, {maxStringLength: 70})
           .split('\n')
           .map((line, index) => index === 0 ? line : `   ${line}`)
           .join('\n'));
 
+    const numFieldsText =
+      (entries.length === 1
+        ? `1 field`
+        : `${entries.length} fields`);
+
     super(
-      colors.bright(colors.yellow(`Altogether, skipped ${entries.length === 1 ? `1 field` : `${entries.length} fields`}:\n`)) +
+      colors.bright(colors.yellow(`Altogether, skipped ${numFieldsText}:\n`)) +
       lines.join('\n') + '\n' +
       colors.bright(colors.yellow(`See above errors for details.`)));
   }
-- 
cgit 1.3.0-6-gf8a5


From 87988954ad7314bee59932b0e5ef3474936ed33e Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 13:59:13 -0400
Subject: data: update and revamp isCommentary validator

---
 src/data/things/validators.js | 59 +++++++++++++++++++++++++++++++++++--------
 1 file changed, 49 insertions(+), 10 deletions(-)

(limited to 'src/data')

diff --git a/src/data/things/validators.js b/src/data/things/validators.js
index 2893e7fd..569a7b34 100644
--- a/src/data/things/validators.js
+++ b/src/data/things/validators.js
@@ -5,7 +5,8 @@ import printable_characters from 'printable-characters';
 const {strlen} = printable_characters;
 
 import {colors, ENABLE_COLOR} from '#cli';
-import {empty, typeAppearance, withAggregate} from '#sugar';
+import {cut, empty, typeAppearance, withAggregate} from '#sugar';
+import {commentaryRegex} from '#wiki-data';
 
 function inspect(value) {
   return nodeInspect(value, {colors: ENABLE_COLOR});
@@ -248,18 +249,56 @@ export function isColor(color) {
   throw new TypeError(`Unknown color format`);
 }
 
-export function isCommentary(commentary) {
-  isString(commentary);
+export function isCommentary(commentaryText) {
+  isString(commentaryText);
 
-  const [firstLine] = commentary.match(/.*/);
-  if (!firstLine.replace(/<\/b>/g, '').includes(':</i>')) {
-    throw new TypeError(`Missing commentary citation: "${
-      firstLine.length > 40
-        ? firstLine.slice(0, 40) + '...'
-        : firstLine
-    }"`);
+  const rawMatches =
+    Array.from(commentaryText.matchAll(commentaryRegex));
+
+  if (empty(rawMatches)) {
+    throw new TypeError(`Expected at least one commentary heading`);
   }
 
+  const niceMatches =
+    rawMatches.map(match => ({
+      position: match.index,
+      length: match[0].length,
+    }));
+
+  validateArrayItems(({position, length}, index) => {
+    if (index === 0 && position > 0) {
+      throw new TypeError(`Expected first commentary heading to be at top`);
+    }
+
+    const ownInput = commentaryText.slice(position, position + length);
+    const restOfInput = commentaryText.slice(position + length);
+    const nextLineBreak = restOfInput.indexOf('\n');
+    const upToNextLineBreak = restOfInput.slice(0, nextLineBreak);
+
+    if (/\S/.test(upToNextLineBreak)) {
+      throw new TypeError(
+        `Expected commentary heading to occupy entire line, got extra text:\n` +
+        `${colors.green(`"${cut(ownInput, 40)}"`)} (<- heading)\n` +
+        `(extra on same line ->) ${colors.red(`"${cut(upToNextLineBreak, 30)}"`)}\n` +
+        `(Check for missing "|-" in YAML, or a misshapen annotation)`);
+    }
+
+    const nextHeading =
+      (index === niceMatches.length - 1
+        ? commentaryText.length
+        : niceMatches[index + 1].position);
+
+    const upToNextHeading =
+      commentaryText.slice(position + length, nextHeading);
+
+    if (!/\S/.test(upToNextHeading)) {
+      throw new TypeError(
+        `Expected commentary entry to have body text, only got a heading`);
+    }
+
+    return true;
+  })(niceMatches);
+
   return true;
 }
 
-- 
cgit 1.3.0-6-gf8a5


From f87fa920f91d36424e4613ac5da50f46418f4b19 Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 14:31:58 -0400
Subject: data, util: principle "translucent errors" & applications

---
 src/data/yaml.js | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

(limited to 'src/data')

diff --git a/src/data/yaml.js b/src/data/yaml.js
index 49e05266..dddf5fb2 100644
--- a/src/data/yaml.js
+++ b/src/data/yaml.js
@@ -334,6 +334,8 @@ export class FieldCombinationError extends Error {
 }
 
 export class FieldValueAggregateError extends AggregateError {
+  [Symbol.for('hsmusic.aggregate.translucent')] = true;
+
   constructor(thingConstructor, errors) {
     const constructorText =
       colors.green(thingConstructor.name);
@@ -1162,7 +1164,10 @@ export async function loadAndProcessDataDocuments({dataPath}) {
 
   for (const dataStep of dataSteps) {
     await processDataAggregate.nestAsync(
-      {message: `Errors during data step: ${colors.bright(dataStep.title)}`},
+      {
+        message: `Errors during data step: ${colors.bright(dataStep.title)}`,
+        translucent: true,
+      },
       async ({call, callAsync, map, mapAsync, push}) => {
         const {documentMode} = dataStep;
 
@@ -1407,7 +1412,7 @@ export async function loadAndProcessDataDocuments({dataPath}) {
 
         switch (documentMode) {
           case documentModes.headerAndEntries:
-            map(yamlResults, {message: `Errors processing documents in data files`},
+            map(yamlResults, {message: `Errors processing documents in data files`, translucent: true},
               decorateErrorWithFile(({documents}) => {
                 const headerDocument = documents[0];
                 const entryDocuments = documents.slice(1).filter(Boolean);
-- 
cgit 1.3.0-6-gf8a5


From 453b0e9845d41c7a1049d4f0982b66121626766a Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 19:28:06 -0400
Subject: data: use optional in definitions for more utility validators

---
 src/data/things/validators.js | 15 ++++++---------
 1 file changed, 6 insertions(+), 9 deletions(-)

(limited to 'src/data')

diff --git a/src/data/things/validators.js b/src/data/things/validators.js
index f60c363c..19ad1c0a 100644
--- a/src/data/things/validators.js
+++ b/src/data/things/validators.js
@@ -96,7 +96,10 @@ export function isStringNonEmpty(value) {
 }
 
 export function optional(validator) {
-  return value => value === null || value === undefined || validator(value);
+  return value =>
+    value === null ||
+    value === undefined ||
+    validator(value);
 }
 
 // Complex types (non-primitives)
@@ -285,20 +288,14 @@ export function validateProperties(spec) {
 
 export const isContribution = validateProperties({
   who: isArtistRef,
-  what: (value) =>
-    value === undefined ||
-    value === null ||
-    isStringNonEmpty(value),
+  what: optional(isStringNonEmpty),
 });
 
 export const isContributionList = validateArrayItems(isContribution);
 
 export const isAdditionalFile = validateProperties({
   title: isString,
-  description: (value) =>
-    value === undefined ||
-    value === null ||
-    isString(value),
+  description: optional(isStringNonEmpty),
   files: validateArrayItems(isString),
 });
 
-- 
cgit 1.3.0-6-gf8a5


From 765e039ef94f7cd1365ba9f211bd686beab5e8ec Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 19:31:05 -0400
Subject: data: move accent-parsing regex out of parseContributors

Also use named capturing groups (and non-capturing groups) for
generally better regex form.
---
 src/data/yaml.js | 26 ++++++++++++++------------
 1 file changed, 14 insertions(+), 12 deletions(-)

(limited to 'src/data')

diff --git a/src/data/yaml.js b/src/data/yaml.js
index 1d35bae8..67cd8db7 100644
--- a/src/data/yaml.js
+++ b/src/data/yaml.js
@@ -717,26 +717,28 @@ export function parseAdditionalFiles(array) {
   }));
 }
 
-export function parseContributors(contributors) {
+const extractAccentRegex =
+  /^(?<main>.*?)(?: \((?<accent>.*)\))?$/;
+
+export function parseContributors(contributionStrings) {
   // If this isn't something we can parse, just return it as-is.
   // The Thing object's validators will handle the data error better
   // than we're able to here.
-  if (!Array.isArray(contributors)) {
-    return contributors;
+  if (!Array.isArray(contributionStrings)) {
+    return contributionStrings;
   }
 
-  contributors = contributors.map((contrib) => {
-    if (typeof contrib !== 'string') return contrib;
+  return contributionStrings.map(contribString => {
+    if (typeof contribString !== 'string') return contribString;
 
-    const match = contrib.match(/^(.*?)( \((.*)\))?$/);
-    if (!match) return contrib;
+    const match = contribString.match(extractAccentRegex);
+    if (!match) return contribString;
 
-    const who = match[1];
-    const what = match[3] || null;
-    return {who, what};
+    return {
+      who: match.groups.main,
+      what: match.groups.accent ?? null,
+    };
   });
-
-  return contributors;
 }
 
 function parseDimensions(string) {
-- 
cgit 1.3.0-6-gf8a5


From bde469f4cede426bd9baa8981b876e82ae290972 Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Mon, 20 Nov 2023 19:32:03 -0400
Subject: data: add additionalNames wiki property ("Additional Names")

---
 .../composite/wiki-properties/additionalNameList.js  | 13 +++++++++++++
 src/data/composite/wiki-properties/index.js          |  1 +
 src/data/things/track.js                             |  2 ++
 src/data/things/validators.js                        |  7 +++++++
 src/data/yaml.js                                     | 20 ++++++++++++++++++++
 5 files changed, 43 insertions(+)
 create mode 100644 src/data/composite/wiki-properties/additionalNameList.js

(limited to 'src/data')

diff --git a/src/data/composite/wiki-properties/additionalNameList.js b/src/data/composite/wiki-properties/additionalNameList.js
new file mode 100644
index 00000000..d1302224
--- /dev/null
+++ b/src/data/composite/wiki-properties/additionalNameList.js
@@ -0,0 +1,13 @@
+// A list of additional names! These can be used for a variety of purposes,
+// e.g. providing extra searchable titles, localizations, romanizations or
+// original titles, and so on. Each item has a name and, optionally, a
+// descriptive annotation.
+
+import {isAdditionalNameList} from '#validators';
+
+export default function() {
+  return {
+    flags: {update: true, expose: true},
+    update: {validate: isAdditionalNameList},
+  };
+}
diff --git a/src/data/composite/wiki-properties/index.js b/src/data/composite/wiki-properties/index.js
index 2462b047..7607e361 100644
--- a/src/data/composite/wiki-properties/index.js
+++ b/src/data/composite/wiki-properties/index.js
@@ -1,4 +1,5 @@
 export {default as additionalFiles} from './additionalFiles.js';
+export {default as additionalNameList} from './additionalNameList.js';
 export {default as color} from './color.js';
 export {default as commentary} from './commentary.js';
 export {default as commentatorArtists} from './commentatorArtists.js';
diff --git a/src/data/things/track.js b/src/data/things/track.js
index 8d310611..f6320677 100644
--- a/src/data/things/track.js
+++ b/src/data/things/track.js
@@ -24,6 +24,7 @@ import {
 
 import {
   additionalFiles,
+  additionalNameList,
   commentary,
   commentatorArtists,
   contributionList,
@@ -63,6 +64,7 @@ export class Track extends Thing {
 
     name: name('Unnamed Track'),
     directory: directory(),
+    additionalNames: additionalNameList(),
 
     duration: duration(),
     urls: urls(),
diff --git a/src/data/things/validators.js b/src/data/things/validators.js
index 19ad1c0a..71570c5a 100644
--- a/src/data/things/validators.js
+++ b/src/data/things/validators.js
@@ -373,6 +373,13 @@ export function isURL(string) {
   return true;
 }
 
+export const isAdditionalName = validateProperties({
+  name: isName,
+  annotation: optional(isStringNonEmpty),
+});
+
+export const isAdditionalNameList = validateArrayItems(isAdditionalName);
+
 export function validateReference(type = 'track') {
   return (ref) => {
     isStringNonEmpty(ref);
diff --git a/src/data/yaml.js b/src/data/yaml.js
index 67cd8db7..cde4413b 100644
--- a/src/data/yaml.js
+++ b/src/data/yaml.js
@@ -436,6 +436,7 @@ export const processTrackSectionDocument = makeProcessDocument(T.TrackSectionHel
 
 export const processTrackDocument = makeProcessDocument(T.Track, {
   fieldTransformations: {
+    'Additional Names': parseAdditionalNames,
     'Duration': parseDuration,
 
     'Date First Released': (value) => new Date(value),
@@ -457,6 +458,7 @@ export const processTrackDocument = makeProcessDocument(T.Track, {
   propertyFieldMapping: {
     name: 'Track',
     directory: 'Directory',
+    additionalNames: 'Additional Names',
     duration: 'Duration',
     color: 'Color',
     urls: 'URLs',
@@ -741,6 +743,24 @@ export function parseContributors(contributionStrings) {
   });
 }
 
+export function parseAdditionalNames(additionalNameStrings) {
+  if (!Array.isArray(additionalNameStrings)) {
+    return additionalNameStrings;
+  }
+
+  return additionalNameStrings.map(additionalNameString => {
+    if (typeof additionalNameString !== 'string') return additionalNameString;
+
+    const match = additionalNameString.match(extractAccentRegex);
+    if (!match) return additionalNameString;
+
+    return {
+      name: match.groups.main,
+      annotation: match.groups.accent ?? null,
+    };
+  });
+}
+
 function parseDimensions(string) {
   // It's technically possible to pass an array like [30, 40] through here.
   // That's not really an issue because if it isn't of the appropriate shape,
-- 
cgit 1.3.0-6-gf8a5


From c9847299d6a31b5fb39f82f80c92e80d53c44234 Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Tue, 21 Nov 2023 07:20:16 -0400
Subject: data: parse contribs & additional names from object shape

---
 src/data/yaml.js | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

(limited to 'src/data')

diff --git a/src/data/yaml.js b/src/data/yaml.js
index cde4413b..5da66c93 100644
--- a/src/data/yaml.js
+++ b/src/data/yaml.js
@@ -730,11 +730,14 @@ export function parseContributors(contributionStrings) {
     return contributionStrings;
   }
 
-  return contributionStrings.map(contribString => {
-    if (typeof contribString !== 'string') return contribString;
+  return contributionStrings.map(item => {
+    if (typeof item === 'object' && item['Who'])
+      return {who: item['Who'], what: item['What'] ?? null};
 
-    const match = contribString.match(extractAccentRegex);
-    if (!match) return contribString;
+    if (typeof item !== 'string') return item;
+
+    const match = item.match(extractAccentRegex);
+    if (!match) return item;
 
     return {
       who: match.groups.main,
@@ -748,11 +751,14 @@ export function parseAdditionalNames(additionalNameStrings) {
     return additionalNameStrings;
   }
 
-  return additionalNameStrings.map(additionalNameString => {
-    if (typeof additionalNameString !== 'string') return additionalNameString;
+  return additionalNameStrings.map(item => {
+    if (typeof item === 'object' && item['Name'])
+      return {name: item['Name'], annotation: item['Annotation'] ?? null};
+
+    if (typeof item !== 'string') return item;
 
-    const match = additionalNameString.match(extractAccentRegex);
-    if (!match) return additionalNameString;
+    const match = item.match(extractAccentRegex);
+    if (!match) return item;
 
     return {
       name: match.groups.main,
-- 
cgit 1.3.0-6-gf8a5


From 8f17782a5f2adbafd031b269195879eb7f79e05f Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Thu, 23 Nov 2023 11:16:48 -0400
Subject: data, content: extract external link parsing into nicer interface

---
 src/data/language.js        | 14 ++++++--------
 src/data/things/language.js | 34 +++++++++++++++++++++++++++++++++-
 2 files changed, 39 insertions(+), 9 deletions(-)

(limited to 'src/data')

diff --git a/src/data/language.js b/src/data/language.js
index 3fc14da7..6f774f27 100644
--- a/src/data/language.js
+++ b/src/data/language.js
@@ -7,15 +7,11 @@ import chokidar from 'chokidar';
 import he from 'he'; // It stands for "HTML Entities", apparently. Cursed.
 import yaml from 'js-yaml';
 
-import T from '#things';
+import {externalLinkSpec} from '#external-links';
 import {colors, logWarn} from '#cli';
-
-import {
-  annotateError,
-  annotateErrorWithFile,
-  showAggregate,
-  withAggregate,
-} from '#sugar';
+import {annotateError, annotateErrorWithFile, showAggregate, withAggregate}
+  from '#sugar';
+import T from '#things';
 
 const {Language} = T;
 
@@ -114,6 +110,8 @@ export function initializeLanguageObject() {
   language.escapeHTML = string =>
     he.encode(string, {useNamedReferences: true});
 
+  language.externalLinkSpec = externalLinkSpec;
+
   return language;
 }
 
diff --git a/src/data/things/language.js b/src/data/things/language.js
index 646eb6d1..185488e2 100644
--- a/src/data/things/language.js
+++ b/src/data/things/language.js
@@ -1,5 +1,11 @@
-import {Tag} from '#html';
 import {isLanguageCode} from '#validators';
+import {Tag} from '#html';
+
+import {
+  getExternalLinkStringsFromDescriptors,
+  isExternalLinkSpec,
+  isExternalLinkStyle,
+} from '#external-links';
 
 import {
   externalFunction,
@@ -72,6 +78,13 @@ export class Language extends Thing {
       update: {validate: (t) => typeof t === 'object'},
     },
 
+    // List of descriptors for providing to external link utilities when using
+    // language.formatExternalLink - refer to util/external-links.js for info.
+    externalLinkSpec: {
+      flags: {update: true, expose: true},
+      update: {validate: isExternalLinkSpec},
+    },
+
     // Update only
 
     escapeHTML: externalFunction(),
@@ -299,6 +312,25 @@ export class Language extends Thing {
       : duration;
   }
 
+  formatExternalLink(url, {style = 'normal'} = {}) {
+    if (!this.externalLinkSpec) {
+      throw new TypeError(`externalLinkSpec unavailable`);
+    }
+
+    if (style !== 'all') {
+      isExternalLinkStyle(style);
+    }
+
+    const results =
+      getExternalLinkStringsFromDescriptors(url, this.externalLinkSpec, this);
+
+    if (style === 'all') {
+      return results;
+    } else {
+      return results[style];
+    }
+  }
+
   formatIndex(value) {
     this.assertIntlAvailable('intl_pluralOrdinal');
     return this.formatString('count.index.' + this.intl_pluralOrdinal.select(value), {index: value});
-- 
cgit 1.3.0-6-gf8a5


From cf08893d48db6f8082a176f54d0d92cb82716b3a Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Thu, 23 Nov 2023 18:50:59 -0400
Subject: external-links: general support for page-contextual formatting

---
 src/data/things/language.js | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)

(limited to 'src/data')

diff --git a/src/data/things/language.js b/src/data/things/language.js
index 185488e2..f83b4218 100644
--- a/src/data/things/language.js
+++ b/src/data/things/language.js
@@ -3,6 +3,7 @@ import {Tag} from '#html';
 
 import {
   getExternalLinkStringsFromDescriptors,
+  isExternalLinkContext,
   isExternalLinkSpec,
   isExternalLinkStyle,
 } from '#external-links';
@@ -312,17 +313,22 @@ export class Language extends Thing {
       : duration;
   }
 
-  formatExternalLink(url, {style = 'normal'} = {}) {
+  formatExternalLink(url, {
+    style = 'normal',
+    context = 'generic',
+  } = {}) {
     if (!this.externalLinkSpec) {
       throw new TypeError(`externalLinkSpec unavailable`);
     }
 
-    if (style !== 'all') {
-      isExternalLinkStyle(style);
-    }
+    if (style !== 'all') isExternalLinkStyle(style);
+    isExternalLinkContext(context);
 
     const results =
-      getExternalLinkStringsFromDescriptors(url, this.externalLinkSpec, this);
+      getExternalLinkStringsFromDescriptors(url, this.externalLinkSpec, {
+        language: this,
+        context,
+      });
 
     if (style === 'all') {
       return results;
-- 
cgit 1.3.0-6-gf8a5


From ba6c4e043b3364481ac3beff1e2a141d1bfcf6fb Mon Sep 17 00:00:00 2001
From: "(quasar) nebula" <qznebula@protonmail.com>
Date: Thu, 23 Nov 2023 20:47:34 -0400
Subject: external-links: cleaner per-style logic

---
 src/data/things/language.js | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

(limited to 'src/data')

diff --git a/src/data/things/language.js b/src/data/things/language.js
index f83b4218..70481299 100644
--- a/src/data/things/language.js
+++ b/src/data/things/language.js
@@ -2,6 +2,7 @@ import {isLanguageCode} from '#validators';
 import {Tag} from '#html';
 
 import {
+  getExternalLinkStringOfStyleFromDescriptors,
   getExternalLinkStringsFromDescriptors,
   isExternalLinkContext,
   isExternalLinkSpec,
@@ -321,20 +322,19 @@ export class Language extends Thing {
       throw new TypeError(`externalLinkSpec unavailable`);
     }
 
-    if (style !== 'all') isExternalLinkStyle(style);
     isExternalLinkContext(context);
 
-    const results =
-      getExternalLinkStringsFromDescriptors(url, this.externalLinkSpec, {
+    if (style === 'all') {
+      return getExternalLinkStringsFromDescriptors(url, this.externalLinkSpec, {
         language: this,
         context,
       });
-
-    if (style === 'all') {
-      return results;
-    } else {
-      return results[style];
     }
+
+    return getExternalLinkStringOfStyleFromDescriptors(url, style, this.externalLinkSpec, {
+      language: this,
+      context,
+    });
   }
 
   formatIndex(value) {
-- 
cgit 1.3.0-6-gf8a5