@optolith/entity-descriptions 0.1.1 → 0.2.0

package/lib/entities/partial/units/energy.js

@@ -0,0 +1,30 @@
+import { assertExhaustive } from "@optolith/helpers/typeSafety";
+import { Entity } from "../rated/activatable/entity.js";
+const lengthUnitTranslationKeys = {
+    ArcaneEnergy: "{0} AE",
+    KarmaPoints: "{0} KP",
+};
+/**
+ * Returns the text for an energy unit.
+ */
+export const formatEnergy = (locale, unit, value) => {
+    const key = lengthUnitTranslationKeys[unit];
+    return locale.translate(key, value);
+};
+/**
+ * Returns the text for an energy unit that is based on the entity type.
+ */
+export const formatEnergyByEntity = (locale, entity, value) => {
+    switch (entity) {
+        case Entity.Cantrip:
+        case Entity.Spell:
+        case Entity.Ritual:
+            return formatEnergy(locale, "ArcaneEnergy", value);
+        case Entity.Blessing:
+        case Entity.LiturgicalChant:
+        case Entity.Ceremony:
+            return formatEnergy(locale, "KarmaPoints", value);
+        default:
+            return assertExhaustive(entity);
+    }
+};

package/lib/entities/partial/units/length.d.ts

@@ -0,0 +1,8 @@
+import { LocaleEnvironment } from "../../../helpers/locale.js";
+import { ResponsiveTextSize } from "../responsiveText.js";
+type LengthUnit = "Steps" | "Miles";
+/**
+ * Returns the text for a length unit.
+ */
+export declare const formatLength: (locale: LocaleEnvironment, responsiveTextSize: ResponsiveTextSize, unit: LengthUnit, value: number | string) => string;
+export {};

package/lib/entities/partial/units/length.js

@@ -0,0 +1,12 @@
+import { responsive } from "../responsiveText.js";
+const lengthUnitTranslationKeys = {
+    Steps: ["{0} yards", "{0} yd"],
+    Miles: ["{0} miles", "{0} mi."],
+};
+/**
+ * Returns the text for a length unit.
+ */
+export const formatLength = (locale, responsiveTextSize, unit, value) => {
+    const [fullKey, compressedKey] = lengthUnitTranslationKeys[unit];
+    return responsive(responsiveTextSize, () => locale.translate(fullKey, value), () => locale.translate(compressedKey, value));
+};

package/lib/entities/partial/units/timeSpan.d.ts

@@ -0,0 +1,8 @@
+import { LocaleEnvironment } from "../../../helpers/locale.js";
+import { ResponsiveTextSize } from "../responsiveText.js";
+type TimeSpanUnit = "Seconds" | "Minutes" | "Hours" | "Days" | "Weeks" | "Months" | "Years" | "Centuries" | "Actions" | "CombatRounds" | "SeductionActions" | "Rounds";
+/**
+ * Returns the text for a time span unit.
+ */
+export declare const formatTimeSpan: (locale: LocaleEnvironment, responsiveTextSize: ResponsiveTextSize, unit: TimeSpanUnit, value: number | string) => string;
+export {};

package/lib/entities/partial/units/timeSpan.js

@@ -0,0 +1,22 @@
+import { responsive } from "../responsiveText.js";
+const timeSpanUnitTranslationKeys = {
+    Seconds: ["{0} seconds", "{0} s"],
+    Minutes: ["{0} minutes", "{0} min"],
+    Hours: ["{0} hours", "{0} h"],
+    Days: ["{0} days", "{0} d"],
+    Weeks: ["{0} weeks", "{0} wks."],
+    Months: ["{0} months", "{0} mos."],
+    Years: ["{0} years", "{0} yrs."],
+    Centuries: ["{0} centuries", "{0} cent."],
+    Actions: ["{0} actions", "{0} act"],
+    CombatRounds: ["{0} combat rounds", "{0} CR"],
+    SeductionActions: ["{0} seduction actions", "{0} SA"],
+    Rounds: ["{0} rounds", "{0} rnds"],
+};
+/**
+ * Returns the text for a time span unit.
+ */
+export const formatTimeSpan = (locale, responsiveTextSize, unit, value) => {
+    const [fullKey, compressedKey] = timeSpanUnitTranslationKeys[unit];
+    return responsive(responsiveTextSize, () => locale.translate(fullKey, value), () => locale.translate(compressedKey, value));
+};

package/lib/entities/skill.d.ts

@@ -4,10 +4,10 @@ import { All, GetById } from "../helpers/getTypes.js";
 /**
  * Get a JSON representation of the rules text for a skill.
  */
-export declare const getSkillLibraryEntry: import("../libraryEntry.js").LibraryEntryCreator<Skill | undefined, {
+export declare const getSkillEntityDescription: import("../index.js").EntityDescriptionCreator<Skill | undefined, {
     getAttributeById: GetById.Static.Attribute;
     blessedTraditions: All.Static.BlessedTraditions;
     diseases: All.Static.Diseases;
     regions: All.Static.Regions;
     cache: NewApplicationsAndUsesCache;
-}, import("../libraryEntry.js").LibraryEntry>;
+}, import("../index.js").EntityDescription>;

package/lib/entities/skill.js

@@ -1,12 +1,12 @@
 import { isNotNullish } from "@optolith/helpers/nullable";
 import { assertExhaustive } from "@optolith/helpers/typeSafety";
-import { createLibraryEntryCreator } from "../libraryEntry.js";
+import { createEntityDescriptionCreator } from "../index.js";
 import { createImprovementCost } from "./partial/rated/improvementCost.js";
 import { getTextForCheck } from "./partial/rated/skillCheck.js";
 /**
  * Get a JSON representation of the rules text for a skill.
  */
-export const getSkillLibraryEntry = createLibraryEntryCreator((entry, { getAttributeById, blessedTraditions, diseases, regions, cache }) => ({ translate, translateMap, localeCompare }) => {
+export const getSkillEntityDescription = createEntityDescriptionCreator(({ getAttributeById, blessedTraditions, diseases, regions, cache }, { translate, translateMap, compare: localeCompare }, entry) => {
     const translation = translateMap(entry.translations);
     if (translation === undefined) {
         return undefined;
@@ -55,7 +55,7 @@ export const getSkillLibraryEntry = createLibraryEntryCreator((entry, { getAttri
     return {
         title: translation.name,
         className: "skill",
-        content: [
+        body: [
             newApplications.length === 0
                 ? undefined
                 : {

package/lib/entities/spell.d.ts

@@ -6,16 +6,16 @@ import { GetById } from "../helpers/getTypes.js";
 /**
  * Get a JSON representation of the rules text for a cantrip.
  */
-export declare const getCantripLibraryEntry: import("../libraryEntry.js").LibraryEntryCreator<Cantrip | undefined, {
+export declare const getCantripEntityDescription: import("../index.js").EntityDescriptionCreator<Cantrip | undefined, {
     getTargetCategoryById: GetById.Static.TargetCategory;
     getPropertyById: GetById.Static.Property;
     getMagicalTraditionById: GetById.Static.MagicalTradition;
     getCurriculumById: GetById.Static.Curriculum;
-}, import("../libraryEntry.js").LibraryEntry>;
+}, import("../index.js").EntityDescription>;
 /**
  * Get a JSON representation of the rules text for a skill.
  */
-export declare const getSpellLibraryEntry: import("../libraryEntry.js").LibraryEntryCreator<Spell | undefined, {
+export declare const getSpellEntityDescription: import("../index.js").EntityDescriptionCreator<Spell | undefined, {
     getAttributeById: GetById.Static.Attribute;
     getSpirit: () => DerivedCharacteristic | undefined;
     getToughness: () => DerivedCharacteristic | undefined;
@@ -23,11 +23,11 @@ export declare const getSpellLibraryEntry: import("../libraryEntry.js").LibraryE
     getTargetCategoryById: GetById.Static.TargetCategory;
     getPropertyById: GetById.Static.Property;
     getMagicalTraditionById: GetById.Static.MagicalTradition;
-}, import("../libraryEntry.js").LibraryEntry>;
+}, import("../index.js").EntityDescription>;
 /**
  * Get a JSON representation of the rules text for a ritual.
  */
-export declare const getRitualLibraryEntry: import("../libraryEntry.js").LibraryEntryCreator<Ritual | undefined, {
+export declare const getRitualEntityDescription: import("../index.js").EntityDescriptionCreator<Ritual | undefined, {
     getAttributeById: GetById.Static.Attribute;
     getSpirit: () => DerivedCharacteristic | undefined;
     getToughness: () => DerivedCharacteristic | undefined;
@@ -35,4 +35,4 @@ export declare const getRitualLibraryEntry: import("../libraryEntry.js").Library
     getTargetCategoryById: GetById.Static.TargetCategory;
     getPropertyById: GetById.Static.Property;
     getMagicalTraditionById: GetById.Static.MagicalTradition;
-}, import("../libraryEntry.js").LibraryEntry>;
+}, import("../index.js").EntityDescription>;

package/lib/entities/spell.js

@@ -1,13 +1,13 @@
 import { isNotNullish, mapNullable } from "@optolith/helpers/nullable";
 import { assertExhaustive } from "@optolith/helpers/typeSafety";
-import { createLibraryEntryCreator, } from "../libraryEntry.js";
-import { getTextForCantripDuration } from "./partial/rated/activatable/duration.js";
+import { createEntityDescriptionCreator, } from "../index.js";
+import { getDurationTranslationForCantrip } from "./partial/rated/activatable/duration.js";
 import { getTextForEffect } from "./partial/rated/activatable/effect.js";
 import { Entity } from "./partial/rated/activatable/entity.js";
-import { getTextForFastOneTimePerformanceParameters, getTextForFastSustainedPerformanceParameters, getTextForSlowOneTimePerformanceParameters, getTextForSlowSustainedPerformanceParameters, } from "./partial/rated/activatable/index.js";
+import { getFastOneTimePerformanceParametersTranslations, getFastSustainedPerformanceParametersTranslations, getSlowOneTimePerformanceParametersTranslations, getSlowSustainedPerformanceParametersTranslations, } from "./partial/rated/activatable/index.js";
 import { parensIf } from "./partial/rated/activatable/parensIf.js";
 import { getTextForCantripRange } from "./partial/rated/activatable/range.js";
-import { getTextForTargetCategory } from "./partial/rated/activatable/targetCategory.js";
+import { getTargetCategoryTranslation } from "./partial/rated/activatable/targetCategory.js";
 import { createImprovementCost } from "./partial/rated/improvementCost.js";
 import { getTextForCheck } from "./partial/rated/skillCheck.js";
 import { ResponsiveTextSize } from "./partial/responsiveText.js";
@@ -53,21 +53,18 @@ const getTraditionNameForArcaneSpellworksById = (ref, getMagicalTraditionById, t
 /**
  * Get a JSON representation of the rules text for a cantrip.
  */
-export const getCantripLibraryEntry = createLibraryEntryCreator((entry, { getTargetCategoryById, getPropertyById, getMagicalTraditionById, getCurriculumById, }) => ({ translate, translateMap, localeCompare }) => {
+export const getCantripEntityDescription = createEntityDescriptionCreator(({ getTargetCategoryById, getPropertyById, getMagicalTraditionById, getCurriculumById, }, locale, entry) => {
+    const { translate, translateMap, compare: localeCompare } = locale;
     const translation = translateMap(entry.translations);
     if (translation === undefined) {
         return undefined;
     }
-    const range = getTextForCantripRange({ translate }, entry.parameters.range, {
-        responsiveText: ResponsiveTextSize.Full,
-    });
-    const duration = getTextForCantripDuration({ translate, translateMap }, entry.parameters.duration, {
-        responsiveText: ResponsiveTextSize.Full,
-    });
+    const range = getTextForCantripRange(locale, ResponsiveTextSize.Full, entry.parameters.range);
+    const duration = getDurationTranslationForCantrip(locale, ResponsiveTextSize.Full, entry.parameters.duration);
     return {
         title: translation.name,
         className: "cantrip",
-        content: [
+        body: [
             {
                 label: translate("Effect"),
                 value: translation.effect,
@@ -84,7 +81,7 @@ export const getCantripLibraryEntry = createLibraryEntryCreator((entry, { getTar
                     ? `***${duration}*** (${translation.duration})`
                     : duration,
             },
-            getTextForTargetCategory({ translate, translateMap, getTargetCategoryById }, entry.target),
+            getTargetCategoryTranslation(getTargetCategoryById, locale, entry.target),
             getTextForProperty({ translate, translateMap, getPropertyById }, entry.property),
             mapNullable(entry.note, (note) => ({
                 label: translate("Note"),
@@ -119,13 +116,14 @@ export const getCantripLibraryEntry = createLibraryEntryCreator((entry, { getTar
                 })(),
             })),
         ],
-        src: entry.src,
+        references: entry.src,
     };
 });
 /**
  * Get a JSON representation of the rules text for a skill.
  */
-export const getSpellLibraryEntry = createLibraryEntryCreator((entry, { getAttributeById, getSpirit, getToughness, getSkillModificationLevelById, getTargetCategoryById, getPropertyById, getMagicalTraditionById, }) => ({ translate, translateMap, localeCompare }) => {
+export const getSpellEntityDescription = createEntityDescriptionCreator(({ getAttributeById, getSpirit, getToughness, getSkillModificationLevelById, getTargetCategoryById, getPropertyById, getMagicalTraditionById, }, locale, entry) => {
+    const { translate, translateMap, compare: localeCompare } = locale;
     const translation = translateMap(entry.translations);
     if (translation === undefined) {
         return undefined;
@@ -133,23 +131,9 @@ export const getSpellLibraryEntry = createLibraryEntryCreator((entry, { getAttri
     const { castingTime, cost, range, duration } = (() => {
         switch (entry.parameters.tag) {
             case "OneTime":
-                return getTextForFastOneTimePerformanceParameters({
-                    getSkillModificationLevelById,
-                    translate,
-                    translateMap,
-                }, entry.parameters.one_time, {
-                    entity: Entity.Spell,
-                    responsiveText: ResponsiveTextSize.Full,
-                });
+                return getFastOneTimePerformanceParametersTranslations(getSkillModificationLevelById, locale, Entity.Spell, ResponsiveTextSize.Full, entry.parameters.one_time);
             case "Sustained":
-                return getTextForFastSustainedPerformanceParameters({
-                    getSkillModificationLevelById,
-                    translate,
-                    translateMap,
-                }, entry.parameters.sustained, {
-                    entity: Entity.Spell,
-                    responsiveText: ResponsiveTextSize.Full,
-                });
+                return getFastSustainedPerformanceParametersTranslations(getSkillModificationLevelById, locale, Entity.Spell, ResponsiveTextSize.Full, entry.parameters.sustained);
             default:
                 return assertExhaustive(entry.parameters);
         }
@@ -157,14 +141,14 @@ export const getSpellLibraryEntry = createLibraryEntryCreator((entry, { getAttri
     return {
         title: translation.name,
         className: "spell",
-        content: [
+        body: [
             getTextForCheck({ translate, translateMap, getAttributeById }, entry.check, {
                 value: entry.check_penalty,
                 responsiveText: ResponsiveTextSize.Full,
                 getSpirit,
                 getToughness,
             }),
-            ...getTextForEffect(translation.effect, translate),
+            ...getTextForEffect(locale, translation.effect),
             {
                 label: translate("Casting Time"),
                 value: castingTime !== translation.casting_time.full
@@ -189,18 +173,19 @@ export const getSpellLibraryEntry = createLibraryEntryCreator((entry, { getAttri
                     ? `***${duration}*** (${translation.duration.full})`
                     : duration,
             },
-            getTextForTargetCategory({ translate, translateMap, getTargetCategoryById }, entry.target),
+            getTargetCategoryTranslation(getTargetCategoryById, locale, entry.target),
             getTextForProperty({ translate, translateMap, getPropertyById }, entry.property),
             getTextForTraditions({ translate, translateMap, localeCompare, getMagicalTraditionById }, entry.traditions),
             createImprovementCost(translate, entry.improvement_cost),
         ],
-        src: entry.src,
+        references: entry.src,
     };
 });
 /**
  * Get a JSON representation of the rules text for a ritual.
  */
-export const getRitualLibraryEntry = createLibraryEntryCreator((entry, { getAttributeById, getSpirit, getToughness, getSkillModificationLevelById, getTargetCategoryById, getPropertyById, getMagicalTraditionById, }) => ({ translate, translateMap, localeCompare }) => {
+export const getRitualEntityDescription = createEntityDescriptionCreator(({ getAttributeById, getSpirit, getToughness, getSkillModificationLevelById, getTargetCategoryById, getPropertyById, getMagicalTraditionById, }, locale, entry) => {
+    const { translate, translateMap, compare: localeCompare } = locale;
     const translation = translateMap(entry.translations);
     if (translation === undefined) {
         return undefined;
@@ -208,23 +193,9 @@ export const getRitualLibraryEntry = createLibraryEntryCreator((entry, { getAttr
     const { castingTime, cost, range, duration } = (() => {
         switch (entry.parameters.tag) {
             case "OneTime":
-                return getTextForSlowOneTimePerformanceParameters({
-                    getSkillModificationLevelById,
-                    translate,
-                    translateMap,
-                }, entry.parameters.one_time, {
-                    entity: Entity.Ritual,
-                    responsiveText: ResponsiveTextSize.Full,
-                });
+                return getSlowOneTimePerformanceParametersTranslations(getSkillModificationLevelById, locale, Entity.Ritual, ResponsiveTextSize.Full, entry.parameters.one_time);
             case "Sustained":
-                return getTextForSlowSustainedPerformanceParameters({
-                    getSkillModificationLevelById,
-                    translate,
-                    translateMap,
-                }, entry.parameters.sustained, {
-                    entity: Entity.Ritual,
-                    responsiveText: ResponsiveTextSize.Full,
-                });
+                return getSlowSustainedPerformanceParametersTranslations(getSkillModificationLevelById, locale, Entity.Ritual, ResponsiveTextSize.Full, entry.parameters.sustained);
             default:
                 return assertExhaustive(entry.parameters);
         }
@@ -232,14 +203,14 @@ export const getRitualLibraryEntry = createLibraryEntryCreator((entry, { getAttr
     return {
         title: translation.name,
         className: "ritual",
-        content: [
+        body: [
             getTextForCheck({ translate, translateMap, getAttributeById }, entry.check, {
                 value: entry.check_penalty,
                 responsiveText: ResponsiveTextSize.Full,
                 getSpirit,
                 getToughness,
             }),
-            ...getTextForEffect(translation.effect, translate),
+            ...getTextForEffect(locale, translation.effect),
             {
                 label: translate("Ritual Time"),
                 value: castingTime !== translation.casting_time.full
@@ -264,11 +235,11 @@ export const getRitualLibraryEntry = createLibraryEntryCreator((entry, { getAttr
                     ? `***${duration}*** (${translation.duration.full})`
                     : duration,
             },
-            getTextForTargetCategory({ translate, translateMap, getTargetCategoryById }, entry.target),
+            getTargetCategoryTranslation(getTargetCategoryById, locale, entry.target),
             getTextForProperty({ translate, translateMap, getPropertyById }, entry.property),
             getTextForTraditions({ translate, translateMap, localeCompare, getMagicalTraditionById }, entry.traditions),
             createImprovementCost(translate, entry.improvement_cost),
         ],
-        src: entry.src,
+        references: entry.src,
     };
 });

package/lib/helpers/locale.d.ts

@@ -0,0 +1,8 @@
+import { Compare } from "@optolith/helpers/compare";
+import { Translate, TranslateMap } from "./translate.js";
+export type LocaleEnvironment = {
+    id: string;
+    translate: Translate;
+    translateMap: TranslateMap;
+    compare: Compare<string>;
+};

package/lib/helpers/locale.js

@@ -0,0 +1 @@
+export {};

package/lib/index.d.ts

@@ -1 +1,45 @@
-export {};
+import { PublicationRefs } from "optolith-database-schema/types/source/_PublicationRef";
+import { GetById } from "./helpers/getTypes.js";
+import { LocaleEnvironment } from "./helpers/locale.js";
+/**
+ * Creates a function that creates the JSON representation of the rules text for
+ * a library entry.
+ */
+export declare const createEntityDescriptionCreator: <T, A extends object = Record<string, never>>(fn: EntityDescriptionCreator<T, A, RawEntityDescription>) => EntityDescriptionCreator<T | undefined, A>;
+/**
+ * A function that creates the JSON representation of the rules text for a
+ * library entry.
+ */
+export type EntityDescriptionCreator<T, A extends object = Record<string, never>, R = EntityDescription> = (databaseAccessors: A & {
+    getPublicationById: GetById.Static.Publication;
+}, locale: LocaleEnvironment, entry: T) => R | undefined;
+/**
+ * A JSON representation of the rules text for a library entry.
+ */
+export type EntityDescription = {
+    title: string;
+    subtitle?: string;
+    className: string;
+    body: EntityDescriptionSection[];
+    references?: string;
+};
+/**
+ * A JSON representation of the rules text for a library entry that has not been
+ * cleaned up.
+ */
+export type RawEntityDescription = {
+    title: string;
+    subtitle?: string;
+    className: string;
+    body: (EntityDescriptionSection | undefined)[];
+    references?: PublicationRefs;
+};
+/**
+ * A slice of the content of a library entry text.
+ */
+export type EntityDescriptionSection = {
+    label?: string;
+    value: string | number;
+    noIndent?: boolean;
+    className?: string;
+};

package/lib/index.js

@@ -1 +1,22 @@
-export {};
+import { filterNonNullable } from "@optolith/helpers/array";
+import { getReferencesTranslation } from "./references/index.js";
+/**
+ * Creates a function that creates the JSON representation of the rules text for
+ * a library entry.
+ */
+export const createEntityDescriptionCreator = (fn) => (databaseAccessors, locale, entry) => {
+    if (entry === undefined) {
+        return undefined;
+    }
+    const rawEntry = fn(databaseAccessors, locale, entry);
+    if (rawEntry === undefined) {
+        return undefined;
+    }
+    return {
+        ...rawEntry,
+        body: filterNonNullable(rawEntry.body),
+        references: rawEntry.references === undefined
+            ? undefined
+            : getReferencesTranslation(databaseAccessors.getPublicationById, locale, rawEntry.references),
+    };
+};

package/lib/references/index.d.ts

@@ -0,0 +1,4 @@
+import { PublicationRefs } from "optolith-database-schema/types/source/_PublicationRef";
+import { GetById } from "../helpers/getTypes.js";
+import { LocaleEnvironment } from "../helpers/locale.js";
+export declare const getReferencesTranslation: (getPublicationById: GetById.Static.Publication, locale: LocaleEnvironment, references: PublicationRefs) => string;

package/lib/references/index.js

@@ -0,0 +1,46 @@
+import { isNotNullish } from "@optolith/helpers/nullable";
+import { assertExhaustive } from "@optolith/helpers/typeSafety";
+import { isSimpleOccurrence, isSimpleOccurrences, isVersionedOccurrence, } from "./occurrence.js";
+import { fromRawPageRange, normalizePageRanges, numberRangeToPageRange, printPageRange, printPageRanges, } from "./pageRange.js";
+export const getReferencesTranslation = (getPublicationById, locale, references) => references
+    .map((ref) => {
+    const publication = getPublicationById(ref.id.publication);
+    const publicationTranslations = locale.translateMap(publication?.translations);
+    const occurrences = locale.translateMap(ref.occurrences);
+    if (publication === undefined ||
+        publicationTranslations === undefined ||
+        occurrences === undefined) {
+        return undefined;
+    }
+    if (isSimpleOccurrence(occurrences)) {
+        return `${publicationTranslations.name} ${printPageRange(locale.translate, numberRangeToPageRange(occurrences))}`;
+    }
+    if (isSimpleOccurrences(occurrences)) {
+        const ranges = normalizePageRanges(occurrences.map(numberRangeToPageRange));
+        return `${publicationTranslations.name} ${printPageRanges(locale.translate, ranges)}`;
+    }
+    if (isVersionedOccurrence(occurrences)) {
+        const initialPageRanges = normalizePageRanges(occurrences.initial.pages.map(fromRawPageRange));
+        const initial = occurrences.initial.printing === undefined
+            ? printPageRanges(locale.translate, initialPageRanges)
+            : `${printPageRanges(locale.translate, initialPageRanges)} (${locale.translate("since the {0}. printing", occurrences.initial.printing)})`;
+        const revisions = occurrences.revisions?.map((rev) => {
+            switch (rev.tag) {
+                case "Since": {
+                    const pageRanges = normalizePageRanges(rev.since.pages.map(fromRawPageRange));
+                    return `${printPageRanges(locale.translate, pageRanges)} (${locale.translate("since the {0}. printing", rev.since.printing)})`;
+                }
+                case "Deprecated": {
+                    return locale.translate("removed in {0}. printing", rev.deprecated.printing);
+                }
+                default:
+                    return assertExhaustive(rev);
+            }
+        }) ?? [];
+        const allPageRanges = [initial, ...revisions].join("; ");
+        return `${publicationTranslations.name} ${allPageRanges}`;
+    }
+    return assertExhaustive(occurrences);
+})
+    .filter(isNotNullish)
+    .join("; ");

package/lib/references/occurrence.d.ts

@@ -0,0 +1,4 @@
+import { Occurrence, SimpleOccurrence, SimpleOccurrences, VersionedOccurrence } from "optolith-database-schema/types/source/_PublicationRef";
+export declare const isSimpleOccurrence: (occurrence: Occurrence) => occurrence is SimpleOccurrence;
+export declare const isSimpleOccurrences: (occurrence: Occurrence) => occurrence is SimpleOccurrences;
+export declare const isVersionedOccurrence: (occurrence: Occurrence) => occurrence is VersionedOccurrence;

package/lib/references/occurrence.js

@@ -0,0 +1,3 @@
+export const isSimpleOccurrence = (occurrence) => Object.hasOwn(occurrence, "first_page");
+export const isSimpleOccurrences = (occurrence) => Array.isArray(occurrence);
+export const isVersionedOccurrence = (occurrence) => Object.hasOwn(occurrence, "initial");

package/lib/references/page.d.ts

@@ -0,0 +1,23 @@
+import { Compare } from "@optolith/helpers/compare";
+import { Page } from "optolith-database-schema/types/source/_PublicationRef";
+import { Translate } from "../helpers/translate.js";
+/**
+ * A comparison function for two pages.
+ */
+export declare const comparePage: Compare<Page>;
+/**
+ * Checks if two pages are equal.
+ */
+export declare const equalsPage: (a: Page, b: Page) => boolean;
+/**
+ * Returns the successor of a page.
+ */
+export declare const succ: (page: Page) => Page;
+/**
+ * Creates a page object for a page number.
+ */
+export declare const numberToPage: (number: number) => Page;
+/**
+ * Returns a string representation of a page.
+ */
+export declare const printPage: (translate: Translate, page: Page) => string;

package/lib/references/page.js

@@ -0,0 +1,61 @@
+import { assertExhaustive } from "@optolith/helpers/typeSafety";
+/**
+ * A comparison function for two pages.
+ */
+export const comparePage = (a, b) => {
+    switch (a.tag) {
+        case "InsideCoverFront":
+            return b.tag === "InsideCoverFront" ? 0 : -1;
+        case "InsideCoverBack":
+            return b.tag === "InsideCoverBack" ? 0 : 1;
+        case "Numbered":
+            return b.tag === "Numbered"
+                ? a.numbered - b.numbered
+                : b.tag === "InsideCoverFront"
+                    ? 1
+                    : -1;
+        default:
+            return assertExhaustive(a);
+    }
+};
+/**
+ * Checks if two pages are equal.
+ */
+export const equalsPage = (a, b) => comparePage(a, b) === 0;
+/**
+ * Returns the successor of a page.
+ */
+export const succ = (page) => {
+    switch (page.tag) {
+        case "InsideCoverFront":
+            return { tag: "Numbered", numbered: 1 };
+        case "InsideCoverBack":
+            return { tag: "InsideCoverFront", inside_cover_front: {} };
+        case "Numbered":
+            return { tag: "Numbered", numbered: page.numbered + 1 };
+        default:
+            return assertExhaustive(page);
+    }
+};
+/**
+ * Creates a page object for a page number.
+ */
+export const numberToPage = (number) => ({
+    tag: "Numbered",
+    numbered: number,
+});
+/**
+ * Returns a string representation of a page.
+ */
+export const printPage = (translate, page) => {
+    switch (page.tag) {
+        case "InsideCoverFront":
+            return translate("Front Cover Inside");
+        case "InsideCoverBack":
+            return translate("Back Cover Inside");
+        case "Numbered":
+            return page.numbered.toString();
+        default:
+            return assertExhaustive(page);
+    }
+};

package/lib/references/pageRange.d.ts

@@ -0,0 +1,30 @@
+import { Page, PageRange as RawPageRange, SimpleOccurrence } from "optolith-database-schema/types/source/_PublicationRef";
+import { Translate } from "../helpers/translate.js";
+/**
+ * A range of pages, including the first and last page, if the range includes
+ * more than on page.
+ */
+export type PageRange = {
+    firstPage: Page;
+    lastPage?: Page;
+};
+/**
+ * Converts a numeric range to a page object range.
+ */
+export declare const numberRangeToPageRange: (numberRange: SimpleOccurrence) => PageRange;
+/**
+ * Converts a page object range from the database to a local page object range.
+ */
+export declare const fromRawPageRange: (pageRange: RawPageRange) => PageRange;
+/**
+ * Sorts and combines page ranges while removing duplicates.
+ */
+export declare const normalizePageRanges: (ranges: PageRange[]) => PageRange[];
+/**
+ * Returns a string representation of a page range.
+ */
+export declare const printPageRange: (translate: Translate, pageRange: PageRange) => string;
+/**
+ * Returns a string representation of a list of page ranges.
+ */
+export declare const printPageRanges: (translate: Translate, pageRanges: PageRange[]) => string;