@tungstenstudio/dartboard-input 1.0.0-rc.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright 2026 Tungsten Studio
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# @tungstenstudio/dartboard-input
+
+Interactive SVG dartboard input component built with D3. Click, tap, or keyboard-navigate beds to fire throw events.
+
+**[Live Demo](https://tungstenstudio.gitlab.io/libs/dartboard-input/)**
+
+## Install
+
+```bash
+npm install @tungstenstudio/dartboard-input d3-selection d3-shape
+# or
+pnpm add @tungstenstudio/dartboard-input d3-selection d3-shape
+# or
+yarn add @tungstenstudio/dartboard-input d3-selection d3-shape
+# or
+bun add @tungstenstudio/dartboard-input d3-selection d3-shape
+```
+
+## Quick Start
+
+```js
+import { Dartboard } from '@tungstenstudio/dartboard-input';
+import '@tungstenstudio/dartboard-input/style.css';
+
+const board = new Dartboard('#dartboard');
+board.render();
+
+document.querySelector('#dartboard').addEventListener('throw', (e) => {
+  console.log(e.detail); // { bed: 'T20', ring: 'triple', score: 60 }
+});
+```
+
+## React Usage
+
+```tsx
+import { useRef, useEffect } from 'react';
+import { Dartboard } from '@tungstenstudio/dartboard-input';
+import '@tungstenstudio/dartboard-input/style.css';
+
+function DartboardInput({ onThrow }) {
+  const ref = useRef(null);
+
+  useEffect(() => {
+    const board = new Dartboard(ref.current, { size: 400 });
+    board.render();
+
+    const handler = (e) => onThrow?.(e.detail);
+    ref.current.addEventListener('throw', handler);
+
+    return () => board.destroy();
+  }, []);
+
+  return <div ref={ref} />;
+}
+```
+
+## API
+
+### `new Dartboard(container, options?)`
+
+Creates a dartboard instance.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `container` | `string \| HTMLElement` | CSS selector or DOM element |
+| `options` | `Partial<DartboardOptions>` | Size and ring proportions |
+
+### `board.render(): this`
+
+Renders the dartboard SVG. Chainable.
+
+### `board.destroy(): void`
+
+Removes the board from the DOM and cleans up references.
+
+### `board.throwAt(target): void`
+
+Programmatically triggers a throw event.
+
+```js
+board.throwAt('T20');                              // bed string
+board.throwAt({ segment: 20, ring: 'TRIPLE' });   // explicit BedTarget
+```
+
+### `board.highlight(targets, options?): void`
+
+Adds a CSS class to targeted beds. All targeting methods accept any mix of bed strings, numbers, and `BedTarget` objects.
+
+```js
+// Bed strings — target specific beds
+board.highlight(['T20', 'D16', 'DB25']);
+
+// Segment number — target all scoring beds on that segment
+board.highlight([20]);       // double, triple, inner single, outer single
+board.highlight(['20']);     // same thing as a string
+
+// Miss ring
+board.highlight(['miss']);   // highlight entire miss ring
+board.highlight(['M20']);    // highlight a specific miss bed
+
+// BedTarget object — for precision targeting
+board.highlight([{ segment: 20, ring: 'INNER_SINGLE' }]);
+
+// BedTarget without ring — same as segment number
+board.highlight([{ segment: 20 }]);
+
+// Custom class name
+board.highlight(['D20'], { className: 'my-highlight' });
+```
+
+### `board.unhighlight(targets, options?): void`
+
+Removes a CSS class from specific beds (counterpart to `highlight`).
+
+```js
+board.unhighlight(['T20']);
+board.unhighlight([20]);     // unhighlight all beds on segment 20
+board.unhighlight(['miss']); // unhighlight entire miss ring
+```
+
+### `board.reset(className?): void`
+
+Removes highlight class from all beds.
+
+### `board.disable(): this`
+
+Disables the board — suppresses all throw and hover events, dims the board visually. Chainable.
+
+### `board.enable(): this`
+
+Re-enables the board after `disable()`. Chainable.
+
+### `board.disabled: boolean`
+
+Read-only property indicating whether the board is currently disabled.
+
+## Bed Strings
+
+Beds are identified by an abbreviation prefix and a segment number:
+
+| Input | Targets | Example |
+|-------|---------|---------|
+| `T` + number | Triple | `'T20'` |
+| `D` + number | Double | `'D16'` |
+| `S` + number | Both singles (inner + outer) | `'S20'` |
+| `DB` + number | Double Bull (Bullseye) | `'DB25'` |
+| `B` + number | Single Bull (Bull) | `'B25'` |
+| `M` + number | Miss | `'M20'` |
+| number only | All scoring beds on that segment | `'20'` or `20` |
+| `'miss'` | Entire miss ring (all 20 segments) | `'miss'` |
+
+When a number is used alone, all scoring beds on that segment are targeted (double, triple, inner single, outer single, single bull, double bull) — the miss ring is excluded. To target a specific single, use the explicit `BedTarget` form: `{ segment: 20, ring: 'INNER_SINGLE' }`.
+
+## Events
+
+### `throw`
+
+Dispatched on the container element when a bed is clicked, tapped, or activated via keyboard.
+
+```ts
+interface ThrowDetail {
+  bed: string;   // e.g. 'T20', 'D16', 'B25', 'DB25', 'M20'
+  ring: string;  // e.g. 'triple', 'double', 'singleBull', 'doubleBull', 'miss'
+  score: number; // e.g. 60, 32, 25, 50, 0
+}
+```
+
+### `hover`
+
+Dispatched when a bed is entered or left.
+
+```ts
+interface HoverDetail {
+  bed: string;
+  ring: string;
+  score: number;
+  hovering: boolean;
+}
+```
+
+## Segment States
+
+Three built-in state classes are included for marking beds as good, bad, or neutral — useful for coaching sessions, practice games, or heatmaps:
+
+```js
+// Mark good targets (green)
+board.highlight(['T20'], { className: 'is-good' });
+
+// Mark bad targets (red)
+board.highlight(['T1'], { className: 'is-bad' });
+
+// Mark neutral targets (blue)
+board.highlight(['D5'], { className: 'is-neutral' });
+
+// Remove a specific state
+board.unhighlight(['T1'], { className: 'is-bad' });
+
+// Clear all of one state
+board.reset('is-good');
+```
+
+The colors are themeable via CSS custom properties:
+
+```css
+.c-Dartboard {
+  --dartboard-good: #228b22;
+  --dartboard-bad: #e32636;
+  --dartboard-neutral: #4a6fa5;
+}
+```
+
+You can also define your own state classes. Use this specificity pattern to override the default bed fills:
+
+```css
+.c-Dartboard .c-Dartboard-bed.is-warning.isDark,
+.c-Dartboard .c-Dartboard-bed.is-warning.isLight {
+  fill: orange;
+}
+```
+
+## Mobile / Touch-Friendly Sizing
+
+The default ring proportions can be too narrow for comfortable tapping on small screens. The exported `MOBILE_OPTIONS` preset widens the scoring rings (double, triple, bull) for larger touch targets:
+
+```js
+import { Dartboard, MOBILE_OPTIONS } from '@tungstenstudio/dartboard-input';
+
+const isMobile = window.matchMedia('(max-width: 600px)').matches;
+const board = new Dartboard('#dartboard', isMobile ? MOBILE_OPTIONS : {});
+board.render();
+```
+
+You can also build your own proportions — the `*Percent` options control each ring's share of the radius (they should sum to 100):
+
+```js
+new Dartboard('#dartboard', {
+  missPercent: 7,
+  doublePercent: 14,
+  outerSinglePercent: 21,
+  triplePercent: 14,
+  innerSinglePercent: 26,
+  singleBullPercent: 9,
+  doubleBullPercent: 9,
+});
+```
+
+## Theming
+
+Override CSS custom properties on the `.c-Dartboard` element:
+
+```css
+.c-Dartboard {
+  --dartboard-dark: #1a1a1a;
+  --dartboard-light: #f5f5dc;
+  --dartboard-scoring-dark: #e32636;
+  --dartboard-scoring-light: #228b22;
+  --dartboard-miss: #000;
+  --dartboard-miss-label: #fff;
+  --dartboard-stroke: silver;
+  --dartboard-stroke-width: 2px;
+  --dartboard-highlight-color: #ffd700;
+  --dartboard-good: #228b22;
+  --dartboard-bad: #e32636;
+  --dartboard-neutral: #4a6fa5;
+}
+```
+
+## Terminology
+
+This library uses standard darts terminology:
+
+- **Segment** — one of the 20 numbered wedges on the board (1–20)
+- **Bed** — a specific scoring zone: the intersection of a segment and a ring (e.g., "triple 20")
+- **Ring** — a concentric band: double, triple, inner single, outer single, single bull, double bull, miss
+
+## Types
+
+All types are exported for TypeScript consumers:
+
+- `Dartboard` — main class
+- `DartboardOptions` — constructor options
+- `ThrowDetail` — throw event payload
+- `HoverDetail` — hover event payload
+- `BedTarget` — explicit target (`{ segment, ring? }`) — omit `ring` to target all scoring beds
+- `BedInput` — union of `BedTarget | string | number` accepted by all targeting methods
+- `HighlightOptions` — options for `highlight`
+- `Ring`, `Rings`, `Segment`, `Bed` — board model types
+- `DEFAULT_OPTIONS`, `MOBILE_OPTIONS` — ring proportion presets
+- `DEFAULT_RINGS`, `DEFAULT_SEGMENTS` — board layout constants
+- `parseBed` — utility to parse a bed string into `BedTarget[]`
+
+## License
+
+ISC