@optolith/entity-descriptions 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file. See [commit-and-tag-version](https://github.com/absolute-version/commit-and-tag-version) for commit guidelines.
 
+## [0.11.1](https://github.com/Optolith/entity-descriptions/compare/v0.11.0...v0.11.1) (2026-09-13)
+
+### Features
+
+* attributed target category ([8411c00](https://github.com/Optolith/entity-descriptions/commit/8411c00eb0ac8df5f4335a41db951578cbaffe26))
+
+### Bug Fixes
+
+* advanced special ability sorting ([fd8ec9c](https://github.com/Optolith/entity-descriptions/commit/fd8ec9cf41625bc67f243850045f2bdf358bae5b)), closes [#50](https://github.com/Optolith/entity-descriptions/issues/50)
+* advanced special ability sorting (other parts) ([75ccc67](https://github.com/Optolith/entity-descriptions/commit/75ccc671ad4a60116067a0b5df143d0b1c1cc3f9))
+* display additional name ([460385e](https://github.com/Optolith/entity-descriptions/commit/460385ee19ea7be58766fb46859256514c75208f))
 ## [0.11.0](https://github.com/Optolith/entity-descriptions/compare/v0.10.0...v0.11.0) (2026-09-13)
 
 ### ⚠ BREAKING CHANGES

package/lib/entities/activatable.d.ts

@@ -34,6 +34,7 @@ export type BaseActivatable = {
  */
 export type BaseActivatableTranslation = {
     name: string;
+    additionalName?: string;
     name_in_library?: string;
     rules?: string;
     range?: string;
@@ -48,7 +49,7 @@ export type BaseActivatableTranslation = {
 /**
  * Get a JSON representation of the rules text for a special ability.
  */
-export declare const getActivatableEntityDescription: import("../creator.js").EntityDescriptionCreator<"AdvancedCombatSpecialAbility" | "AdvancedKarmaSpecialAbility" | "AdvancedMagicalSpecialAbility" | "AdvancedSkillSpecialAbility" | "Advantage" | "AncestorGlyph" | "ArcaneOrbEnchantment" | "AttireEnchantment" | "Beutelzauber" | "BlessedTradition" | "BowlEnchantment" | "BrawlingSpecialAbility" | "CauldronEnchantment" | "CeremonialItemSpecialAbility" | "ChronicleEnchantment" | "CombatSpecialAbility" | "CombatStyleSpecialAbility" | "CommandSpecialAbility" | "DaggerRitual" | "Disadvantage" | "FamiliarSpecialAbility" | "FatePointSexSpecialAbility" | "FatePointSpecialAbility" | "FoolsHatEnchantment" | "GeneralSpecialAbility" | "Haubenzauber" | "Hauerkettenzauber" | "InstrumentEnchantment" | "KarmaSpecialAbility" | "Keulenzauber" | "Krallenkettenzauber" | "Kristallkugelzauber" | "LiturgicalStyleSpecialAbility" | "LycantropicGift" | "MagicStyleSpecialAbility" | "MagicalSign" | "MagicalSpecialAbility" | "MagicalTradition" | "OrbEnchantment" | "PactGift" | "ProtectiveWardingCircleSpecialAbility" | "RingEnchantment" | "Schweinetrommelzauber" | "Sermon" | "SexSpecialAbility" | "SickleRitual" | "SikaryanDrainSpecialAbility" | "SkillStyleSpecialAbility" | "SpellSwordEnchantment" | "StaffEnchantment" | "ToyEnchantment" | "Trinkhornzauber" | "VampiricGift" | "Vision" | "WandEnchantment" | "WeaponEnchantment", {
+export declare const getActivatableEntityDescription: import("../creator.js").EntityDescriptionCreator<"Advantage" | "Disadvantage" | "AdvancedCombatSpecialAbility" | "AdvancedKarmaSpecialAbility" | "AdvancedMagicalSpecialAbility" | "AdvancedSkillSpecialAbility" | "AncestorGlyph" | "ArcaneOrbEnchantment" | "AttireEnchantment" | "Beutelzauber" | "BlessedTradition" | "BowlEnchantment" | "BrawlingSpecialAbility" | "CauldronEnchantment" | "CeremonialItemSpecialAbility" | "ChronicleEnchantment" | "CombatSpecialAbility" | "CombatStyleSpecialAbility" | "CommandSpecialAbility" | "DaggerRitual" | "FamiliarSpecialAbility" | "FatePointSexSpecialAbility" | "FatePointSpecialAbility" | "FoolsHatEnchantment" | "GeneralSpecialAbility" | "Haubenzauber" | "Hauerkettenzauber" | "InstrumentEnchantment" | "KarmaSpecialAbility" | "Keulenzauber" | "Krallenkettenzauber" | "Kristallkugelzauber" | "LiturgicalStyleSpecialAbility" | "LycantropicGift" | "MagicalSign" | "MagicalSpecialAbility" | "MagicalTradition" | "MagicStyleSpecialAbility" | "OrbEnchantment" | "PactGift" | "ProtectiveWardingCircleSpecialAbility" | "RingEnchantment" | "Schweinetrommelzauber" | "Sermon" | "SexSpecialAbility" | "SickleRitual" | "SikaryanDrainSpecialAbility" | "SkillStyleSpecialAbility" | "SpellSwordEnchantment" | "StaffEnchantment" | "ToyEnchantment" | "Trinkhornzauber" | "VampiricGift" | "Vision" | "WandEnchantment" | "WeaponEnchantment", {
     getInstanceById: GetInstanceById<"Publication" | "Subject" | ActivatableIdentifier["kind"] | RatedIdentifier["kind"] | "TradeSecret" | "Aspect" | "Property" | "Race" | "Culture" | "State" | "Enhancement" | "PactCategory" | "PactDomain" | "SocialStatus" | "Weapon" | "Patron" | "PersonalityTrait" | "Brew" | "Blessing" | "Cantrip">;
     getAllInstances: GetAllInstances<"Script">;
     getResolvedSelectOptionById: GetResolvedSelectOptionById;

package/lib/entities/activatable.js

@@ -4,6 +4,7 @@ import { count } from "@elyukai/utils/array/reductions";
 import { deepEqual } from "@elyukai/utils/equality";
 import { constant, on } from "@elyukai/utils/function";
 import { isNotNullish } from "@elyukai/utils/nullable";
+import { reduceCompare } from "@elyukai/utils/ordering";
 import { Reader } from "@elyukai/utils/reader";
 import { numAsc } from "@optolith/helpers/compare";
 import { sign } from "@optolith/helpers/math";
@@ -546,7 +547,7 @@ const renderAdvancedSpecialAbilityName = (translate, translateMap, getInstanceBy
     const normalizedId = normalizeId(entityName, id);
     return `^[${mapNullable(printActivatableName(getInstanceById, translate, normalizedId, option, undefined, getResolvedSelectOptionById, false), name => renderActivatableNameComponents(translateMap, name, false)) ?? MISSING_VALUE}](entity: "${normalizedId.kind}", instance: "${fromUniformCase(normalizedId)}", style: "normal")`;
 };
-const renderAdvancedValue = (translate, translateMap, localeJoin, getInstanceById, getResolvedSelectOptionById, entityName, advanced) => {
+const renderAdvancedValue = (translate, translateMap, localeJoin, localeCompare, getInstanceById, getResolvedSelectOptionById, entityName, advanced) => {
     if (advanced.every(entry => entry.kind === "OneOf") &&
         isNotEmpty(advanced) &&
         advanced.every(entry => entry.OneOf.options.length === 3)) {
@@ -558,7 +559,9 @@ const renderAdvancedValue = (translate, translateMap, localeJoin, getInstanceByI
             if (uniqueOptions.length === advanced.length) {
                 const [first, second] = optionsInAllEntries.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option));
                 return [
-                    ...uniqueOptions.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option)),
+                    ...uniqueOptions
+                        .map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option))
+                        .toSorted(localeCompare),
                     translate("one or two of these special abilities can alternatively be replaced by advanced special abilities {$first} and/or {$second}", { first, second }),
                 ].join(", ");
             }
@@ -568,25 +571,38 @@ const renderAdvancedValue = (translate, translateMap, localeJoin, getInstanceByI
         entry.DeriveFromExternalOption.display_option === undefined);
     const anyEntriesToGenerate = count(advanced, entry => entry.kind === "Any");
     const arr = [
-        ...advanced.map((entry) => {
+        ...advanced
+            .map((entry) => {
             switch (entry.kind) {
                 case "General":
-                    return renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, entry.General);
+                    return [
+                        "general",
+                        renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, entry.General),
+                    ];
                 case "RestrictOptions":
-                    return renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, entry.RestrictOptions.id, entry.RestrictOptions.option);
+                    return [
+                        "general",
+                        renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, entry.RestrictOptions.id, entry.RestrictOptions.option),
+                    ];
                 case "OneOf": {
                     if (entry.OneOf.display_option !== undefined) {
                         switch (entry.OneOf.display_option.kind) {
                             case "Hide":
                                 return undefined;
                             case "ReplaceWith":
-                                return (translateMap(entry.OneOf.display_option.ReplaceWith.translations)?.replacement ??
-                                    MISSING_VALUE);
+                                return [
+                                    "special",
+                                    translateMap(entry.OneOf.display_option.ReplaceWith.translations)
+                                        ?.replacement ?? MISSING_VALUE,
+                                ];
                             default:
                                 return assertExhaustive(entry.OneOf.display_option);
                         }
                     }
-                    return localeJoin(entry.OneOf.options.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option)), "disjunction");
+                    return [
+                        "general",
+                        localeJoin(entry.OneOf.options.map(option => renderAdvancedSpecialAbilityName(translate, translateMap, getInstanceById, getResolvedSelectOptionById, entityName, option)), "disjunction"),
+                    ];
                 }
                 case "DeriveFromExternalOption":
                     if (entry.DeriveFromExternalOption.display_option !== undefined) {
@@ -594,7 +610,10 @@ const renderAdvancedValue = (translate, translateMap, localeJoin, getInstanceByI
                             case "Hide":
                                 return undefined;
                             case "ReplaceWith":
-                                return (translateMap(entry.DeriveFromExternalOption.display_option.ReplaceWith.translations)?.replacement ?? MISSING_VALUE);
+                                return [
+                                    "special",
+                                    translateMap(entry.DeriveFromExternalOption.display_option.ReplaceWith.translations)?.replacement ?? MISSING_VALUE,
+                                ];
                             default:
                                 return assertExhaustive(entry.DeriveFromExternalOption.display_option);
                         }
@@ -605,7 +624,10 @@ const renderAdvancedValue = (translate, translateMap, localeJoin, getInstanceByI
                 default:
                     return assertExhaustive(entry);
             }
-        }),
+        })
+            .filter((item) => isNotNullish(item) && item[1] !== undefined)
+            .toSorted(reduceCompare(on(([type]) => type, localeCompare), on(([, value]) => value, localeCompare)))
+            .map(value => value[1]),
         derivedFromExternalOptionEntriesToGenerate === 0
             ? undefined
             : translate(".input {$count :number} {{{$count} more by primary patron}}", {
@@ -782,8 +804,7 @@ export const getActivatableEntityDescription = createEntityDescriptionCreator(({
         ? name => translate("Tradition ({$tradition})", { tradition: name })
         : name => name;
     return {
-        title: makeTraditionName(translation.name_in_library ?? translation.name) +
-            (baseEntry.levels !== undefined ? ` I–${romanize(baseEntry.levels)}` : ""),
+        title: makeTraditionName(translation.name_in_library ?? translation.name + parensIf(translation.additionalName)) + (baseEntry.levels !== undefined ? ` I–${romanize(baseEntry.levels)}` : ""),
         subtitle: mapNullable(baseEntry.subtype, subtype => renderAdvantageDisadvantageSubtype(subtype).run(env)) ??
             mapNullable(baseEntry.usage_type, usageType => renderCombatSpecialAbilityType(usageType).run(env)),
         badge: mapNullable(entityName === "CombatStyleSpecialAbility" || entityName === "AdvancedCombatSpecialAbility"
@@ -839,7 +860,7 @@ export const getActivatableEntityDescription = createEntityDescriptionCreator(({
                     mapNullable(baseEntry.advanced, advanced => isStyleSpecialAbilityKind(entityName)
                         ? {
                             label: renderAdvancedLabel(translate, entityName),
-                            value: renderAdvancedValue(translate, translateMap, locale.join, getInstanceById, getResolvedSelectOptionById, entityName, advanced),
+                            value: renderAdvancedValue(translate, translateMap, locale.join, locale.compare, getInstanceById, getResolvedSelectOptionById, entityName, advanced),
                         }
                         : undefined),
                     mapNullable(baseEntry.penalty, penalty => ({

package/lib/entities/disease.d.ts

@@ -3,7 +3,7 @@ import type { IdMap } from "../index.js";
 /**
  * Get a JSON representation of the rules text for an optional rule.
  */
-export declare const getDiseaseEntityDescription: import("../creator.js").EntityDescriptionCreator<"AnimalDisease" | "Disease", {
+export declare const getDiseaseEntityDescription: import("../creator.js").EntityDescriptionCreator<"Disease" | "AnimalDisease", {
     getInstanceById: GetInstanceById<"Publication" | "AnimalType" | "DerivedCharacteristic">;
     idMap: IdMap;
 }, import("../index.js").EntityDescription>;

package/lib/entities/equipment.d.ts

@@ -19,7 +19,7 @@ export declare const renderRangedWeapon: <Damage>(translate: Translate, translat
 /**
  * Get a JSON representation of the rules text for equipment.
  */
-export declare const getEquipmentEntityDescription: import("../creator.js").EntityDescriptionCreator<"Ammunition" | "Animal" | "AnimalCare" | "Armor" | "BandageOrRemedy" | "Book" | "CeremonialItem" | "Clothes" | "ClothingPackage" | "Container" | "EquipmentOfBlessedOnes" | "GemOrPreciousStone" | "IlluminationLightSource" | "IlluminationRefillOrSupply" | "Jewelry" | "Laboratory" | "Liebesspielzeug" | "LuxuryGood" | "MagicalArtifact" | "MusicalInstrument" | "Newspaper" | "OrienteeringAid" | "RopeOrChain" | "Stationery" | "ThievesTool" | "ToolOfTheTrade" | "TravelGearOrTool" | "Vehicle" | "Weapon" | "WeaponAccessory" | "WorkingSupernaturalCreature", {
+export declare const getEquipmentEntityDescription: import("../creator.js").EntityDescriptionCreator<"Weapon" | "Ammunition" | "Armor" | "Animal" | "AnimalCare" | "BandageOrRemedy" | "Book" | "CeremonialItem" | "Clothes" | "ClothingPackage" | "Container" | "EquipmentOfBlessedOnes" | "GemOrPreciousStone" | "IlluminationLightSource" | "IlluminationRefillOrSupply" | "Jewelry" | "Laboratory" | "Liebesspielzeug" | "LuxuryGood" | "MagicalArtifact" | "MusicalInstrument" | "Newspaper" | "OrienteeringAid" | "RopeOrChain" | "Stationery" | "ThievesTool" | "ToolOfTheTrade" | "TravelGearOrTool" | "Vehicle" | "WeaponAccessory" | "WorkingSupernaturalCreature", {
     getInstanceById: GetInstanceById<"Publication" | "Attribute" | "Reach" | "SocialStatus" | "CloseCombatTechnique" | "RangedCombatTechnique" | "MagicalTradition" | "BlessedTradition" | "DerivedCharacteristic" | AmmunitionishIdentifier["kind"] | "Race" | "Culture" | "Profession" | "Skill">;
     idMap: IdMap;
 }, import("../index.js").EntityDescription>;

package/lib/entities/partial/rated/activatable/cost.d.ts

@@ -42,7 +42,7 @@ export declare const renderIndefiniteCost: (value: IndefiniteCost, shouldAppendN
 /**
  * Returns the text for a standalone one-time cost map of an activatable skill.
  */
-export declare const renderStandaloneCostMap: (value: StandaloneCostMap) => Reader<StdEnv<"rts" | "t" | "tm"> & {
+export declare const renderStandaloneCostMap: (value: StandaloneCostMap) => Reader<StdEnv<"tm" | "t" | "rts"> & {
     translate: import("../../../../helpers/translate.js").Translate;
     energyUnit: import("../../units/energy.js").EnergyUnit;
 }, string>;
@@ -63,7 +63,7 @@ export declare const renderNonModifiableSustainedCost: (value: NonModifiableSust
     responsiveTextSize: import("../../responsiveText.js").ResponsiveTextSize;
 } & {
     translate: import("../../../../helpers/translate.js").Translate;
-} & StdEnv<"f" | "rts" | "t" | "tm"> & StdEnv<"eu" | "rts" | "t" | "tm", never, never, never>, string>;
+} & StdEnv<"f" | "tm" | "t" | "rts"> & StdEnv<"tm" | "t" | "rts" | "eu", never, never, never>, string>;
 /**
  * Returns the text for the cost of a sustained activatable skill.
  */

package/lib/entities/partial/rated/activatable/targetCategory.js

@@ -1,12 +1,9 @@
 import { Reader } from "@elyukai/utils/reader";
-import { mapNullable } from "@optolith/helpers/nullable";
 import { assertExhaustive } from "@optolith/helpers/typeSafety";
-import { getInstanceByIdFnR, translateMapR, translateR } from "../../reader.js";
+import { attributedNameR, translateMapR, translateR } from "../../reader.js";
 import { MISSING_VALUE } from "../../unknown.js";
 import { appendInParensIfNotEmpty } from "./parensIf.js";
-const renderPredefined = (targetCategoryId) => getInstanceByIdFnR()
-    .thenW(getInstanceById => mapNullable(getInstanceById("TargetCategory", targetCategoryId), targetCategory => translateMapR(targetCategory.translations).map(translation => translation?.name)) ?? Reader.of(undefined))
-    .map(translation => translation ?? MISSING_VALUE);
+const renderPredefined = (targetCategoryId) => attributedNameR("target-category", "TargetCategory", targetCategoryId).map(name => name ?? MISSING_VALUE);
 const getTargetCategoryTranslationByType = (id) => {
     switch (id.kind) {
         case "Self":

package/lib/entities/partial/reader.d.ts

@@ -316,5 +316,5 @@ export declare const modifyBySpeedR: Reader<{
 /**
  * Returns the default values wrapped in a reader if the value is nullish, otherwise applies the given function to the value and returns the result.
  */
-export declare const mapNullableR: <T, U, R>(defaultValue: U, fn: (value: NonNullable<T>) => Reader<U, R>) => (value: T) => Reader<unknown, U> | Reader<U, R>;
+export declare const mapNullableR: <T, U, R>(defaultValue: U, fn: (value: NonNullable<T>) => Reader<U, R>) => (value: T) => Reader<U, R> | Reader<unknown, U>;
 export {};

package/lib/entities/partial/responsiveText.d.ts

@@ -40,4 +40,4 @@ export declare const replaceTextIfNeeded: (translations: LocaleMap<{
  */
 export declare const appendNoteIfNeeded: (translations: LocaleMap<{
     note?: ResponsiveTextOptional;
-}> | undefined, valueToAppendTo: string) => Reader<StdEnv<"rts" | "tm">, string>;
+}> | undefined, valueToAppendTo: string) => Reader<StdEnv<"tm" | "rts">, string>;