verseluft-dnd-library 0.1.0 → 0.2.0

package/README.md

@@ -14,6 +14,7 @@ A small JavaScript library for DnD-style apps and websites.
 - [Human docs](./docs/human/README.md)
 - [AI docs](./docs/ai/README.md)
 - [Dice tool](./docs/human/api/tools/dice.md)
+- [Name picker tool](./docs/human/api/tools/name-picker.md)
 - The published npm package includes both doc sets
 - Build the standalone wiki with `npm run wiki:build`
 

package/docs/ai/README.md

@@ -16,7 +16,8 @@ Start here:
 
 Scope:
 
-- Dice tool only
+- Dice tool
+- Name picker tool
 
 Rules:
 

package/docs/ai/api/index.md

@@ -5,6 +5,7 @@ Only the dice tool is in scope for now.
 ## Tools
 
 - [Dice tool](./tools/dice.md)
+- [Name picker tool](./tools/name-picker.md)
 
 ## Agent rules
 

package/docs/ai/api/tools/name-picker.md

@@ -0,0 +1,112 @@
+# AI Name Picker Reference
+
+This file is the AI-specific reference for the name picker tool.
+
+## Exported functions
+
+- `pickName(options?, randomFn?)`
+- `getSupportedNameRaces()`
+- `listNameData()`
+
+## Source files
+
+- [src/tools/name-picker.js](/D:/Projects/Verseluft-Core/src/tools/name-picker.js)
+- [src/data/nameDatabase.js](/D:/Projects/Verseluft-Core/src/data/nameDatabase.js)
+
+## Supported races
+
+- `human`
+- `elf`
+- `dwarf`
+- `halfling`
+- `gnome`
+- `dragonborn`
+- `tiefling`
+- `aasimar`
+- `goliath`
+- `orc`
+
+## Behavior summary
+
+### `pickName(options?, randomFn?)`
+- Normalizes `race` to lowercase
+- Unknown races fall back to `human`
+- Normalizes `sex` to `male`, `female`, or `any`
+- Normalizes `mode` to `full`, `first`, `surname`, or `split`
+- If `sex` is `any`, the tool randomly chooses a male or female bucket first
+- Returns output based on `mode`
+
+### Example
+
+```js
+import { pickName } from "verseluft-dnd-library";
+
+const name = pickName({ race: "dwarf", sex: "male" });
+/*
+{
+  race: "dwarf",
+  sex: "male",
+  firstName: "Baern",
+  surname: "Amberaxe",
+  fullName: "Baern Amberaxe"
+}
+*/
+```
+
+### Output modes
+
+- `full`: returns `race`, `sex`, `firstName`, `surname`, and `fullName`
+- `first`: returns `race`, `sex`, and `firstName`
+- `surname`: returns `race`, `sex`, and `surname`
+- `split`: returns `race`, `sex`, `firstName`, and `surname`
+
+### `getSupportedNameRaces()`
+- Returns the supported species keys from the internal database
+
+### Example
+
+```js
+import { getSupportedNameRaces } from "verseluft-dnd-library";
+
+getSupportedNameRaces();
+// ["human", "elf", "dwarf", "halfling", "gnome", "dragonborn", "tiefling", "aasimar", "goliath", "orc"]
+```
+
+### `listNameData()`
+- Returns a cloned copy of the whole database
+- Intended for inspection, not mutation of the source data
+
+### Example
+
+```js
+import { listNameData } from "verseluft-dnd-library";
+
+const data = listNameData();
+// data.human.male.first[0] === "Aren"
+```
+
+## Data model
+
+The database is organized as:
+
+```js
+{
+  [race]: {
+    male: { first: string[], surname: string[] },
+    female: { first: string[], surname: string[] }
+  }
+}
+```
+
+## Test guidance
+
+- Use a deterministic `randomFn` when testing
+- Verify the race fallback path for unknown values
+- Verify that `sex: "any"` can select either bucket
+- Verify the output mode behavior for `first`, `surname`, `split`, and `full`
+
+## Edit boundaries
+
+- If name logic changes, update this file and the human version together
+- If the database changes, update examples or supported race notes
+- Do not touch the dice docs when editing the name picker

package/docs/ai/changelog.md

@@ -7,6 +7,23 @@
 - Starter content and tests added
 - Standalone wiki generator added
 
+## 0.1.1
+
+- Added the name picker tool
+- Added the internal name database for the supported species
+- Added human and AI docs for the name picker tool
+
+## 0.1.2
+
+- Added output modes for the name picker tool
+- The picker can now return first-only, surname-only, split, or full-name output
+
+## 0.2.0
+
+- Added the name picker tool as a packaged database-backed feature
+- Added first-name-only, surname-only, split, and full output modes
+- Expanded docs for both human and AI readers
+
 AI editing notes:
 
 - Keep changelog entries short and factual

package/docs/ai/overview.md

@@ -5,7 +5,7 @@ Project: Verseluft DnD Library
 Purpose:
 
 - Small JavaScript toolkit for DnD-style apps and websites
-- Current scope is only the dice tool
+- Current scope includes the dice tool and the name picker tool
 
 Agent guidance:
 
@@ -19,5 +19,6 @@ Documentation map:
 - `docs/ai/changelog.md`
 - `docs/ai/api/index.md`
 - `docs/ai/api/tools/dice.md`
+- `docs/ai/api/tools/name-picker.md`
 
 Do not add new tool docs without explicit scope changes.

package/docs/human/README.md

@@ -8,7 +8,8 @@ Start here:
 
 Current scope:
 
-- Dice tool only
+- Dice tool
+- Name picker tool
 
 To generate the standalone wiki site, run `npm run wiki:build`.
 The built HTML files will appear in `wiki-site/`.

package/docs/human/api/index.md

@@ -5,6 +5,7 @@ This page is the central map for the library documentation.
 ## Tools
 
 - [Dice tool](./tools/dice.md)
+- [Name picker tool](./tools/name-picker.md)
 
 ## Notes for editors
 

package/docs/human/api/tools/name-picker.md

@@ -0,0 +1,125 @@
+# Name Picker Tool
+
+The name picker tool generates fantasy names based on race and sex.
+
+## Purpose
+
+Use this tool to:
+
+- Pick a first name and surname
+- Generate names for common DnD species
+- Keep the output simple and readable for games, apps, or character tools
+- Return first-only, surname-only, split, or full-name output
+
+## Supported races
+
+The current built-in database supports:
+
+- `human`
+- `elf`
+- `dwarf`
+- `halfling`
+- `gnome`
+- `dragonborn`
+- `tiefling`
+- `aasimar`
+- `goliath`
+- `orc`
+
+## Exports
+
+- `pickName(options?, randomFn?)`
+- `getSupportedNameRaces()`
+- `listNameData()`
+
+## `pickName(options?, randomFn?)`
+
+Returns a generated name for the selected race and sex.
+
+### Input
+
+- `options.race`: the race/species name, such as `human`, `elf`, or `dwarf`
+- `options.sex`: `male`, `female`, or `any`
+- `options.mode`: `full`, `first`, `surname`, or `split`
+- `randomFn`: optional random function, defaults to `Math.random`
+
+### Output
+
+```js
+{
+  race: string,
+  sex: string,
+  firstName: string,
+  surname: string,
+  fullName: string
+}
+```
+
+### Example
+
+```js
+import { pickName } from "verseluft-dnd-library";
+
+const name = pickName({ race: "elf", sex: "female" });
+// { race: "elf", sex: "female", firstName: "Ayla", surname: "Galanodel", fullName: "Ayla Galanodel" }
+```
+
+### Example result
+
+```js
+{
+  race: "elf",
+  sex: "female",
+  firstName: "Ayla",
+  surname: "Galanodel",
+  fullName: "Ayla Galanodel"
+}
+```
+
+### Output modes
+
+```js
+pickName({ race: "elf", sex: "female", mode: "first" });
+// { race: "elf", sex: "female", firstName: "Ayla" }
+
+pickName({ race: "elf", sex: "female", mode: "surname" });
+// { race: "elf", sex: "female", surname: "Galanodel" }
+
+pickName({ race: "elf", sex: "female", mode: "split" });
+// { race: "elf", sex: "female", firstName: "Ayla", surname: "Galanodel" }
+
+pickName({ race: "elf", sex: "female", mode: "full" });
+// { race: "elf", sex: "female", firstName: "Ayla", surname: "Galanodel", fullName: "Ayla Galanodel" }
+```
+
+If you do not pass `mode`, the default is `full`.
+
+## `getSupportedNameRaces()`
+
+Returns the supported race list used by the current database.
+
+### Example
+
+```js
+import { getSupportedNameRaces } from "verseluft-dnd-library";
+
+getSupportedNameRaces();
+// ["human", "elf", "dwarf", "halfling", "gnome", "dragonborn", "tiefling", "aasimar", "goliath", "orc"]
+```
+
+## `listNameData()`
+
+Returns a copy of the full internal name database.
+
+### Example
+
+```js
+import { listNameData } from "verseluft-dnd-library";
+
+const data = listNameData();
+```
+
+## Editing rule
+
+If you change the name picker behavior, update this file and the AI version together.
+If the public API changes, update the central index and changelog too.

package/docs/human/changelog.md

@@ -7,6 +7,23 @@
 - Added starter content modules
 - Added package tests and a browser playground
 
+## 0.1.1
+
+- Added the name picker tool
+- Added a small built-in name database for 2024-style DnD species
+- Added human and AI documentation for the new tool
+
+## 0.1.2
+
+- Added output modes for the name picker tool
+- The picker can now return first-only, surname-only, split, or full-name output
+
+## 0.2.0
+
+- Added the name picker tool as a packaged database-backed feature
+- Added first-name-only, surname-only, split, and full output modes
+- Expanded docs for both human and AI readers
+
 ## Documentation notes
 
 - The docs are organized by topic so AI edits can stay isolated

package/docs/human/overview.md

@@ -5,6 +5,7 @@ Verseluft DnD Library is a small JavaScript toolkit for DnD-style apps and websi
 Right now, this documentation set focuses on a single tool:
 
 - Dice tools
+- Name picker tools
 
 ## What this docs set is for
 
@@ -18,8 +19,9 @@ Right now, this documentation set focuses on a single tool:
 - `docs/human/changelog.md` for version notes
 - `docs/human/api/index.md` for the API map
 - `docs/human/api/tools/dice.md` for the dice tool
+- `docs/human/api/tools/name-picker.md` for the name picker tool
 
 ## Current scope
 
-This docs set intentionally covers only the dice tool for now.
+This docs set intentionally covers only the current tools for now.
 Other tools and modules can be added later as separate files.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "verseluft-dnd-library",
-  "version": "0.1.0",
-  "description": "A small DnD utility library with reusable content modules and dice tools for apps and websites.",
+  "version": "0.2.0",
+  "description": "A small DnD utility library with reusable content modules, dice tools, and a name picker for apps and websites.",
   "license": "MIT",
   "keywords": [
     "dnd",
     "rpg",
     "library",
+    "name-generator",
     "javascript",
     "browser"
   ],
@@ -16,7 +17,8 @@
     ".": "./src/index.js",
     "./modules/*": "./src/modules/*.js",
     "./tools/*": "./src/tools/*.js",
-    "./content/*": "./src/content/*.js"
+    "./content/*": "./src/content/*.js",
+    "./data/*": "./src/data/*.js"
   },
   "files": [
     "src",

package/src/data/nameDatabase.js

@@ -0,0 +1,104 @@
+export const nameDatabase = {
+  human: {
+    male: {
+      first: ["Aren", "Darin", "Gavin", "Joran", "Theron"],
+      surname: ["Ashford", "Black", "Rivers", "Stone", "Vale"],
+    },
+    female: {
+      first: ["Elira", "Mira", "Nora", "Selene", "Talia"],
+      surname: ["Ashford", "Dawn", "Frost", "Hart", "Vale"],
+    },
+  },
+  elf: {
+    male: {
+      first: ["Aelar", "Erevan", "Faelar", "Laucian", "Soveliss"],
+      surname: ["Amakiir", "Galanodel", "Liadon", "Nailo", "Xiloscient"],
+    },
+    female: {
+      first: ["Ayla", "Dayereth", "Keyleth", "Leshanna", "Thia"],
+      surname: ["Amakiir", "Galanodel", "Liadon", "Nailo", "Xiloscient"],
+    },
+  },
+  dwarf: {
+    male: {
+      first: ["Baern", "Dain", "Eberk", "Harbek", "Orsik"],
+      surname: ["Amberaxe", "Balderk", "Fireforge", "Ironfist", "Strakeln"],
+    },
+    female: {
+      first: ["Amber", "Diesa", "Eldeth", "Falkrunn", "Vistra"],
+      surname: ["Amberaxe", "Balderk", "Fireforge", "Ironfist", "Strakeln"],
+    },
+  },
+  halfling: {
+    male: {
+      first: ["Ander", "Corrin", "Eldon", "Milo", "Osborn"],
+      surname: ["Brushgather", "Goodbarrel", "Greenbottle", "High-hill", "Tealeaf"],
+    },
+    female: {
+      first: ["Callie", "Lavinia", "Merla", "Piper", "Rosie"],
+      surname: ["Brushgather", "Goodbarrel", "Greenbottle", "High-hill", "Tealeaf"],
+    },
+  },
+  gnome: {
+    male: {
+      first: ["Alston", "Boddynock", "Dimble", "Fonkin", "Wrenn"],
+      surname: ["Beren", "Nackle", "Murnig", "Scheppen", "Timbers"],
+    },
+    female: {
+      first: ["Bree", "Caramip", "Ella", "Lidda", "Nissa"],
+      surname: ["Beren", "Nackle", "Murnig", "Scheppen", "Timbers"],
+    },
+  },
+  dragonborn: {
+    male: {
+      first: ["Arjhan", "Balasar", "Donaar", "Ghesh", "Kriv"],
+      surname: ["Clethtinthiallor", "Daardendrian", "Delmirev", "Norixius", "Saariv"],
+    },
+    female: {
+      first: ["Akra", "Biri", "Kava", "Sora", "Zykro"],
+      surname: ["Clethtinthiallor", "Daardendrian", "Delmirev", "Norixius", "Saariv"],
+    },
+  },
+  tiefling: {
+    male: {
+      first: ["Akmenos", "Barakas", "Mordai", "Skamos", "Zef"],
+      surname: ["Ashspear", "Nightbloom", "Silverthread", "Duskwalker", "Stormeye"],
+    },
+    female: {
+      first: ["Astra", "Bryseis", "Kallista", "Lerissa", "Vesper"],
+      surname: ["Ashspear", "Nightbloom", "Silverthread", "Duskwalker", "Stormeye"],
+    },
+  },
+  aasimar: {
+    male: {
+      first: ["Aurel", "Caelum", "Irian", "Mikael", "Seraph"],
+      surname: ["Brightsoul", "Dawnwatch", "Starfall", "Lightborn", "Sunveil"],
+    },
+    female: {
+      first: ["Arielle", "Celeste", "Ilyra", "Mirael", "Seren"],
+      surname: ["Brightsoul", "Dawnwatch", "Starfall", "Lightborn", "Sunveil"],
+    },
+  },
+  goliath: {
+    male: {
+      first: ["Aukan", "Eglath", "Gathak", "Keth", "Thuun"],
+      surname: ["Cloudseer", "Ironpeak", "Stoneward", "Thunderborn", "Wolfrun"],
+    },
+    female: {
+      first: ["Ena", "Gunna", "Helli", "Orla", "Zanna"],
+      surname: ["Cloudseer", "Ironpeak", "Stoneward", "Thunderborn", "Wolfrun"],
+    },
+  },
+  orc: {
+    male: {
+      first: ["Dench", "Gell", "Henk", "Ront", "Shump"],
+      surname: ["Bloodjaw", "Ironhide", "Skullcrusher", "Stonefang", "Warborn"],
+    },
+    female: {
+      first: ["Baggi", "Emen", "Engong", "Myev", "Ovak"],
+      surname: ["Bloodjaw", "Ironhide", "Skullcrusher", "Stonefang", "Warborn"],
+    },
+  },
+};
+
+export const supportedSpecies = Object.keys(nameDatabase);

package/src/index.js

@@ -1,5 +1,6 @@
 export { createDnDLibrary } from "./core/createDnDLibrary.js";
 export { rollDice, parseDiceExpression, averageRoll } from "./tools/dice.js";
+export { pickName, getSupportedNameRaces, listNameData } from "./tools/name-picker.js";
 export { getMonsterById, listMonsters } from "./modules/monsters.js";
 export { getSpellById, listSpells } from "./modules/spells.js";
 export { getItemById, listItems } from "./modules/items.js";

package/src/tools/name-picker.js

@@ -0,0 +1,83 @@
+import { nameDatabase, supportedSpecies } from "../data/nameDatabase.js";
+
+function normalizeSpecies(race) {
+  const value = String(race ?? "human").trim().toLowerCase();
+  return supportedSpecies.includes(value) ? value : "human";
+}
+
+function normalizeSex(sex) {
+  const value = String(sex ?? "any").trim().toLowerCase();
+  if (value === "male" || value === "female") {
+    return value;
+  }
+  return "any";
+}
+
+function normalizeMode(mode) {
+  const value = String(mode ?? "full").trim().toLowerCase();
+  if (value === "first" || value === "surname" || value === "split" || value === "full") {
+    return value;
+  }
+  return "full";
+}
+
+function pickFrom(items, randomFn) {
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error("No names available for the selected category.");
+  }
+
+  const index = Math.floor(randomFn() * items.length);
+  return items[index];
+}
+
+function pickSexBucket(speciesData, sex, randomFn) {
+  if (sex === "male" || sex === "female") {
+    return speciesData[sex];
+  }
+
+  return randomFn() < 0.5 ? speciesData.male : speciesData.female;
+}
+
+export function getSupportedNameRaces() {
+  return [...supportedSpecies];
+}
+
+export function pickName(options = {}, randomFn = Math.random) {
+  const race = normalizeSpecies(options.race);
+  const sex = normalizeSex(options.sex);
+  const mode = normalizeMode(options.mode);
+  const speciesData = nameDatabase[race] ?? nameDatabase.human;
+  const sexBucket = pickSexBucket(speciesData, sex, randomFn);
+  const firstName = pickFrom(sexBucket.first, randomFn);
+  const surname = pickFrom(sexBucket.surname, randomFn);
+
+  const result = {
+    race,
+    sex,
+  };
+
+  if (mode === "first") {
+    result.firstName = firstName;
+    return result;
+  }
+
+  if (mode === "surname") {
+    result.surname = surname;
+    return result;
+  }
+
+  if (mode === "split") {
+    result.firstName = firstName;
+    result.surname = surname;
+    return result;
+  }
+
+  result.firstName = firstName;
+  result.surname = surname;
+  result.fullName = `${firstName} ${surname}`;
+  return result;
+}
+
+export function listNameData() {
+  return structuredClone(nameDatabase);
+}