@crockery/fellowship-components 0.1.0

package/package.json

@@ -0,0 +1,149 @@
+{
+  "name": "@crockery/fellowship-components",
+  "version": "0.1.0",
+  "description": "Lit web components for rendering Fellowship game data.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Crockery/fellowship-components.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Crockery/fellowship-components/issues"
+  },
+  "homepage": "https://github.com/Crockery/fellowship-components#readme",
+  "keywords": [
+    "fellowship",
+    "web-components",
+    "lit",
+    "react",
+    "dungeon-map",
+    "talent-calculator",
+    "tooltip"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": [
+    "./dist/index.js",
+    "./dist/dungeon-map.js",
+    "./dist/talent-calculator.js",
+    "./dist/tooltip.js",
+    "./dist/react.js",
+    "./dist/react/*.js"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./dungeon-map": {
+      "types": "./dist/dungeon-map/index.d.ts",
+      "import": "./dist/dungeon-map.js",
+      "default": "./dist/dungeon-map.js"
+    },
+    "./talent-calculator": {
+      "types": "./dist/talent-calculator/index.d.ts",
+      "import": "./dist/talent-calculator.js",
+      "default": "./dist/talent-calculator.js"
+    },
+    "./tooltip": {
+      "types": "./dist/tooltip/index.d.ts",
+      "import": "./dist/tooltip.js",
+      "default": "./dist/tooltip.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./react/dungeon-map": {
+      "types": "./dist/react/dungeon-map.d.ts",
+      "import": "./dist/react/dungeon-map.js",
+      "default": "./dist/react/dungeon-map.js"
+    },
+    "./react/talent-calculator": {
+      "types": "./dist/react/talent-calculator.d.ts",
+      "import": "./dist/react/talent-calculator.js",
+      "default": "./dist/react/talent-calculator.js"
+    },
+    "./react/tooltip": {
+      "types": "./dist/react/tooltip.d.ts",
+      "import": "./dist/react/tooltip.js",
+      "default": "./dist/react/tooltip.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/*/README.md",
+    "README.md",
+    "RELEASING.md",
+    "LICENSE",
+    "THIRD_PARTY_LICENSES.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "packageManager": "pnpm@11.3.0",
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "test": "pnpm test:unit && pnpm test:browser",
+    "test:unit": "vitest run --project unit",
+    "test:browser": "vitest run --project browser",
+    "test:browser:smoke": "FELLOWSHIP_TEST_BROWSERS=smoke vitest run --project browser -t '\\[smoke\\]'",
+    "test:browser:all": "FELLOWSHIP_TEST_BROWSERS=all vitest run --project browser",
+    "ladle": "ladle serve",
+    "ladle:build": "ladle build",
+    "package:lint": "publint --strict --pack npm && attw --pack . --profile esm-only",
+    "pack:check": "pnpm build && node scripts/check-build.mjs && pnpm package:lint && pnpm pack --dry-run",
+    "prepublishOnly": "pnpm build && node scripts/check-build.mjs && pnpm package:lint",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  },
+  "dependencies": {
+    "@crockery/fellowship-data": "^1.0.0",
+    "@lit/react": "^1.0.8",
+    "lit": "^3.3.3"
+  },
+  "peerDependencies": {
+    "react": ">=18 <20",
+    "react-dom": ">=18 <20"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@changesets/cli": "^2.31.0",
+    "@fontsource/ibm-plex-mono": "5.2.7",
+    "@fontsource/ibm-plex-sans-condensed": "5.2.8",
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@ladle/react": "^5.1.1",
+    "@types/react": "^18.3.24",
+    "@types/react-dom": "^18.3.7",
+    "@vitejs/plugin-react-swc": "^4.3.1",
+    "@vitest/browser-playwright": "^4.1.10",
+    "playwright": "^1.61.1",
+    "publint": "^0.3.21",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
+  }
+}

package/src/dungeon-map/README.md

@@ -0,0 +1,168 @@
+# Dungeon map
+
+`<fellowship-dungeon-map>` draws a Fellowship dungeon map to canvas and places enemy and group
+HTML in a synchronized, interactive DOM overlay.
+
+## Import and basic usage
+
+Importing the component entry point registers the custom element:
+
+```ts
+import "@crockery/fellowship-components/dungeon-map";
+```
+
+```html
+<fellowship-dungeon-map
+  dungeon-id="Level.ID.DemonicRitual"
+  map-image-id="Level.ID.DemonicRitual:T_Map_Demonicritual_Start"
+></fellowship-dungeon-map>
+```
+
+The default data source lazily loads dungeons, enemies, and the manifest from
+`@crockery/fellowship-data`. When `mapImageId` is absent, the first upstream map image is
+selected.
+
+## Lit renderers
+
+Renderer functions receive upstream enemy placement data plus normalized group geometry. Group
+children are already position-aware and only need to be wrapped:
+
+```ts
+import { html } from "lit";
+import type { FellowshipDungeonMapElement } from "@crockery/fellowship-components/dungeon-map";
+
+const map = document.querySelector<FellowshipDungeonMapElement>("fellowship-dungeon-map")!;
+
+map.renderEnemy = ({ model }) => html` <span>${model.enemy?.name ?? model.placement.id}</span> `;
+
+map.renderGroup = ({ group, children }) => html`
+  <div class="pull" data-group=${group.id}>${children}</div>
+`;
+```
+
+`LitEnemyRenderer` receives `{ model, group, dungeon, mapImage }`.
+`LitGroupRenderer` receives `{ group, children, dungeon, mapImage }`, where `children`
+contains positioned enemy anchors. Both return a Lit `TemplateResult` or `nothing`.
+
+## React
+
+```tsx
+import { DungeonMapViewer } from "@crockery/fellowship-components/react/dungeon-map";
+
+export function DungeonRoute() {
+  return (
+    <DungeonMapViewer
+      dungeonId="Level.ID.DemonicRitual"
+      renderEnemy={({ model }) => <EnemyMarker enemy={model.enemy} />}
+      renderGroup={({ group, children }) => <PullGroup group={group}>{children}</PullGroup>}
+      onMapImageChange={(event) => console.log(event.detail.mapImageId)}
+    />
+  );
+}
+```
+
+Custom React nodes render through a React-owned light-DOM overlay while the Lit element retains
+map loading, canvas drawing, positioning, and viewport interactions.
+
+## Data and assets
+
+Set `assetBaseUrl` to self-host package images:
+
+```ts
+map.assetBaseUrl = "https://static.example.com/fellowship-data/v1.0.0/";
+```
+
+Replace `dataSource` for filtered, experimental, remote, or application-owned data:
+
+```ts
+import type { FellowshipDataSource } from "@crockery/fellowship-components/dungeon-map";
+
+declare const applicationData: FellowshipDataSource;
+
+const source: FellowshipDataSource = {
+  async loadDungeon(dungeonId, signal) {
+    return applicationData.loadDungeon(dungeonId, signal);
+  },
+  resolveAssetUrl(asset) {
+    return new URL(asset.path, "https://static.example.com/").href;
+  },
+};
+
+map.dataSource = source;
+```
+
+## API
+
+### Properties
+
+- `dungeonId: string`
+- `mapImageId: string | null`
+- `assetBaseUrl: string | null` — `null` uses the package-pinned CDN.
+- `dataSource: FellowshipDataSource | null` — `null` uses the package provider.
+- `renderEnemy: LitEnemyRenderer | null`
+- `renderGroup: LitGroupRenderer | null`
+- `mapLabelFormatter: MapLabelFormatter | null`
+- `showControls: boolean` — defaults to `true`.
+- `showMapSelector: boolean` — defaults to `true`.
+- `maxZoom: number` — defaults to `8`.
+
+The React wrapper treats `mapImageId` as hybrid controlled state: an initial value selects the
+starting floor, user selections update the rendered map immediately, and later prop changes still
+replace the selection.
+
+### Methods
+
+- `fitToView()`
+- `zoomIn()`
+- `zoomOut()`
+- `retry()`
+
+### Events
+
+- `fellowship-map-ready`
+- `fellowship-map-error`
+- `fellowship-map-warning`
+- `fellowship-map-image-change`
+- `fellowship-map-viewport-change`
+
+All events bubble across the shadow boundary and carry typed `detail` payloads.
+
+## Interaction and accessibility
+
+- Mouse-wheel zoom stays anchored beneath the pointer.
+- Pointer drag and arrow keys pan the map.
+- Two touch pointers pinch to zoom.
+- `+`, `-`, and `0` zoom in, zoom out, and fit.
+- The map selector uses a tablist with arrow, Home, and End navigation.
+- Initial load, map changes, and resize fit the map to the viewport.
+- Reduced-motion preferences remove marker and control transitions.
+
+## Theming
+
+```css
+fellowship-dungeon-map {
+  --fellowship-map-soot: #0b0f13;
+  --fellowship-map-ink: #f1eee5;
+  --fellowship-map-muted-ink: #b7b4aa;
+  --fellowship-map-border: rgb(241 238 229 / 10%);
+  --fellowship-map-focus: #a8e6ee;
+  --fellowship-map-rune: #69c4d4;
+  --fellowship-map-ember: #d9784c;
+  --fellowship-map-control-surface: rgb(21 28 35 / 92%);
+  --fellowship-map-enemy-size: 32px;
+  --fellowship-map-font-family: "Fellowship Field", sans-serif;
+  --fellowship-map-tactical-font-family: "Fellowship Tactical", monospace;
+  --fellowship-map-radius: 6px;
+}
+
+fellowship-dungeon-map::part(control-button) {
+  font-weight: 800;
+}
+```
+
+CSS parts: `viewport`, `map-canvas`, `overlay`, `group`, `enemy`, `controls`,
+`control-button`, `map-selector`, `map-selector-button`, and `status`.
+
+The map also inherits all shared `--fellowship-field-*` tokens. Component tokens above take
+precedence. Compact control rails respond to the map element's container width, so narrow embedded
+maps adapt even when the browser viewport is wide.

package/src/talent-calculator/README.md

@@ -0,0 +1,190 @@
+# Talent calculator
+
+`<fellowship-talent-calculator>` renders a hero's six-row talent grid and manages an affordable
+selection against a configurable point budget.
+
+## Import and basic usage
+
+Importing the entry point registers the calculator and its tooltip dependency:
+
+```ts
+import "@crockery/fellowship-components/talent-calculator";
+```
+
+```html
+<fellowship-talent-calculator hero-id="firemage" talent-points="14"> </fellowship-talent-calculator>
+```
+
+The default provider lazily loads heroes, talents, and the manifest from
+`@crockery/fellowship-data`. Missing or failed talent images use deterministic rune fallbacks.
+
+## Point budget and selection
+
+`talentPoints` is the total available budget, not the remaining point count. The header displays
+`spent / available`.
+
+- Any affordable combination may be selected, including multiple talents from one row.
+- There are no tier prerequisites or one-per-row restrictions.
+- Unaffordable talents remain focusable for tooltip and requirement discovery.
+- Selected talents can always be removed.
+- The **Clear All** button removes every selected talent without changing the point budget.
+- Point controls normalize the total to an integer from `0` through `14`.
+- The total cannot be decreased below currently spent points.
+
+The element is hybrid controlled. User actions update `selectedTalentIds` and `talentPoints`
+before events are emitted, and applications may set either property directly.
+
+Externally supplied over-budget selections are preserved and marked invalid. New choices remain
+blocked until the state is valid, while deselection and point increases are still available.
+Unknown, duplicate, or inactive supplied IDs are removed after data loads.
+
+## Lit API
+
+```ts
+import type {
+  FellowshipTalentCalculatorElement,
+  TalentSelectionChangeEvent,
+} from "@crockery/fellowship-components/talent-calculator";
+
+const calculator = document.querySelector<FellowshipTalentCalculatorElement>(
+  "fellowship-talent-calculator",
+)!;
+
+calculator.selectedTalentIds = ["firemage-talent-id"];
+calculator.addEventListener(
+  "fellowship-talent-selection-change",
+  (event: TalentSelectionChangeEvent) => {
+    console.log(event.detail.selectedTalentIds, event.detail.remainingPoints);
+  },
+);
+```
+
+### Custom talent content
+
+The element owns each card button, talent image, point cost, tooltip, positioning, focus, and
+selection behavior. A renderer changes the label presentation inside that shell and must not
+return nested interactive controls. The default talent image remains visible; hide or restyle it
+with `::part(talent-icon)` when supplying a complete custom presentation:
+
+```ts
+import { html } from "lit";
+
+calculator.renderTalent = ({ talent, selected }) => html`
+  <span class=${selected ? "chosen" : "available"}>
+    ${talent.row}.${talent.column} · ${talent.talent.name}
+  </span>
+`;
+```
+
+## React
+
+```tsx
+import { useState } from "react";
+import { TalentCalculator } from "@crockery/fellowship-components/react/talent-calculator";
+
+export function HeroBuild() {
+  const [selected, setSelected] = useState<readonly string[]>([]);
+
+  return (
+    <TalentCalculator
+      heroId="firemage"
+      talentPoints={14}
+      selectedTalentIds={selected}
+      onSelectionChange={(event) => setSelected(event.detail.selectedTalentIds)}
+      renderTalent={({ talent }) => <span>{talent.talent.name}</span>}
+    />
+  );
+}
+```
+
+React talent renderers mount presentation-only nodes into stable named slots. The web component
+continues to own button semantics and selection state.
+
+## Data and assets
+
+Self-host images with `assetBaseUrl`, or replace the complete provider:
+
+```ts
+import type { FellowshipTalentDataSource } from "@crockery/fellowship-components/talent-calculator";
+
+declare const applicationTalentData: FellowshipTalentDataSource;
+
+calculator.assetBaseUrl = "https://static.example.com/fellowship-data/v1.0.0/";
+
+const source: FellowshipTalentDataSource = {
+  async loadHeroTalents(heroId, signal) {
+    return applicationTalentData.loadHeroTalents(heroId, signal);
+  },
+  resolveAssetUrl(asset) {
+    return new URL(asset.path, "https://static.example.com/").href;
+  },
+};
+
+calculator.dataSource = source;
+```
+
+## API
+
+### Properties
+
+- `heroId: string`
+- `talentPoints: number` — defaults to `14`, normalized from `0` through
+  `MAX_TALENT_POINTS`.
+- `selectedTalentIds: readonly string[]`
+- `assetBaseUrl: string | null`
+- `dataSource: FellowshipTalentDataSource | null`
+- `renderTalent: LitTalentRenderer | null`
+- `showPointControls: boolean` — defaults to `true`.
+- `showTooltips: boolean` — defaults to `true`.
+
+### Methods
+
+- `selectTalent(talentId): boolean`
+- `deselectTalent(talentId): boolean`
+- `reset()` — clears selections without changing the point total.
+- `retry()`
+
+### Events
+
+- `fellowship-talents-ready`
+- `fellowship-talents-error`
+- `fellowship-talents-warning`
+- `fellowship-talent-selection-change`
+- `fellowship-talent-points-change`
+
+All events bubble across the shadow boundary and carry typed details. Selection events report
+`selectedTalentIds`, `spentPoints`, `remainingPoints`, and their change source.
+
+## Accessibility
+
+Rows are semantic fieldsets with legends. Cards are native buttons with `aria-pressed`, accessible
+descriptions, visible focus rings, and focusable `aria-disabled` states. Clear All and the point
+controls are native buttons with visible focus states and 44px interaction targets. Status changes
+use polite live regions; newly raised errors use assertive announcements.
+
+## Theming
+
+The calculator inherits the shared `--fellowship-field-*` theme described in the package README.
+Its existing component tokens take precedence, so established themes remain compatible.
+
+```css
+fellowship-talent-calculator {
+  --fellowship-talent-background: #0b0f13;
+  --fellowship-talent-surface: #10161c;
+  --fellowship-talent-card-background: #10161c;
+  --fellowship-talent-selection: #69c4d4;
+  --fellowship-talent-points: #c1a36a;
+  --fellowship-talent-danger: #d9784c;
+  --fellowship-talent-icon-size: 56px;
+}
+```
+
+CSS parts: `container`, `header`, `heading`, `points`, `points-spent`, `points-total`,
+`point-controls`, `point-control`, `clear-all`, `grid`, `row`, `row-label`, `talent`,
+`talent-icon`, `talent-icon-fallback`, `talent-name`, `talent-cost`, `status`,
+`empty-state`, and `error-state`.
+
+Design tokens use the `--fellowship-talent-*` prefix and cover the background and surfaces,
+foreground hierarchy, disabled state, border, selection, focus, point accent, danger state,
+control surface, icon size, interface and tactical font families, and radius. The compact
+single-column layout is activated by the component's own container width rather than the viewport.

package/src/tooltip/README.md

@@ -0,0 +1,113 @@
+# Tooltip
+
+`<fellowship-tooltip>` provides accessible, collision-aware Fellowship tooltips with a safe
+rich-text resolver.
+
+## Import and basic usage
+
+```ts
+import "@crockery/fellowship-components/tooltip";
+```
+
+```html
+<fellowship-tooltip
+  heading="Runic Convergence"
+  text="Gain <rt.absorb>20 absorb</> and restore <rt.mana>5 mana</>."
+>
+  <button type="button">Inspect talent</button>
+</fellowship-tooltip>
+```
+
+The default slot contains the trigger. Supply fully custom tooltip content through the named
+`content` slot.
+
+## React
+
+```tsx
+import { Tooltip } from "@crockery/fellowship-components/react/tooltip";
+
+export function Help() {
+  return (
+    <Tooltip heading="Talent points" text="Points can be reassigned at any time.">
+      <button type="button">Help</button>
+    </Tooltip>
+  );
+}
+```
+
+Pass a React node to the wrapper's `content` prop to fill the named content slot.
+
+## Interaction and positioning
+
+- Pointer hover opens after `openDelay`, which defaults to `250` milliseconds.
+- Keyboard focus opens immediately.
+- Pointer leave, focus leaving the host, or Escape closes the tooltip.
+- `placement` accepts `auto`, `top`, `right`, `bottom`, or `left`.
+- Automatic placement prefers top, then bottom, right, and left.
+- The surface repositions on scroll, viewport resize, trigger resize, and content resize.
+- Positioning maintains an 8px trigger gap and viewport collision margin.
+- The native Popover API is used when available, with a fixed-position fallback.
+
+Tooltip content is noninteractive and uses `role="tooltip"`. The first slotted trigger receives a
+plain-text `aria-description` while connected; any existing value is restored afterward.
+
+## API
+
+### Properties
+
+- `heading: string | null`
+- `text: string | null`
+- `placement: "auto" | "top" | "right" | "bottom" | "left"`
+- `openDelay: number`
+- `disabled: boolean`
+
+### Methods
+
+- `show()`
+- `hide()`
+
+### Event
+
+`fellowship-tooltip-toggle` bubbles across the shadow boundary. Its detail contains `open` and
+the reason: `pointer`, `focus`, `escape`, `programmatic`, or `disabled`.
+
+## Fellowship rich text
+
+Descriptions are parsed into inert Lit text bindings. The component never uses `unsafeHTML` or
+executes arbitrary markup.
+
+Supported tags:
+
+- `bold` and `rt.bold`
+- `rt.absorb`
+- `rt.warning`
+- `rt.effect`
+- `rt.mana`
+- `rt.heal`
+- `rt.meikoability1`
+- `rt.meikoability2`
+
+Both `</>` and named closing tags are supported. Unknown tags keep their text without styling,
+and malformed or unclosed markup recovers safely. Paragraphs and line breaks are preserved.
+
+The entry point also exports:
+
+```ts
+import {
+  resolveFellowshipRichText,
+  stripFellowshipRichText,
+} from "@crockery/fellowship-components/tooltip";
+```
+
+## Theming
+
+The tooltip inherits the shared `--fellowship-field-*` theme and exposes the established
+`--fellowship-tooltip-*` overrides. Its desaturated semantic defaults are ability `#76C5D2`,
+warning `#D4A761`, effect `#AFA1CA`, resource `#7CB2C2`, healing `#82B997`, Meiko primary
+`#C892A0`, and Meiko secondary `#8DBAB7`.
+
+CSS parts: `trigger`, `surface`, `arrow`, `heading`, `content`, and `paragraph`.
+
+Design tokens use the `--fellowship-tooltip-*` prefix and cover surface, foreground, muted text,
+border, focus, semantic rich-text tones, font family, radius, and maximum width. Reduced-motion
+preferences remove translated transitions.