Add support for customizing pieces by using slots

README.md

@@ -12,7 +12,7 @@
 |:--------:|:----:|
 |![](./gifs/hexchess-perf.gif)|![](./gifs/hexchess-resize-perf.gif)|
 
-2. Completely customizable - every single color you see can be changed to whatever fits your style and liking! Soon, we will support [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot), which will also allow you to customize the pieces on the board.
+2. Completely customizable - every single color you see can be changed to whatever fits your style and liking! Provide your own artwork via [slots](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) (for example, `piece-white-queen`) to override the built-in piece set.
 
 3. Can be standalone without a server! `hexchess-board` ships with a complete game engine that can detect illegal moves, checkmate, stalemate, and more! You can play with two players on the same laptop without any other dependencies, should you choose.
 
@@ -62,6 +62,29 @@ startButton.addEventListener('click', () => {
 
 If you want to reuse the shipped cues from JS you can import `DEFAULT_SOUND_PACK` from the package and merge it with your overrides.
 
+## Custom pieces
+
+Slots expose each piece so you can bring your own set without forking the component. Drop `<img>` tags inside the element with the matching slot name and the board, captured piece tray, and promotion dialog will automatically switch to your artwork.
+
+```html
+<hexchess-board board="start">
+  <img slot="piece-white-queen" src="/pieces/white-queen.svg" />
+  <img slot="piece-black-queen" src="/pieces/black-queen.svg" />
+  <img slot="piece-black-pawn" src="/pieces/black-pawn.svg" />
+</hexchess-board>
+```
+
+| Slot name | Piece |
+| --------- | ----- |
+| `piece-white-king` / `piece-black-king` | King (`K`/`k`) |
+| `piece-white-queen` / `piece-black-queen` | Queen (`Q`/`q`) |
+| `piece-white-bishop` / `piece-black-bishop` | Bishop (`B`/`b`) |
+| `piece-white-knight` / `piece-black-knight` | Knight (`N`/`n`) |
+| `piece-white-rook` / `piece-black-rook` | Rook (`R`/`r`) |
+| `piece-white-pawn` / `piece-black-pawn` | Pawn (`P`/`p`) |
+
+Only the slots you fill are overridden—the rest fall back to the bundled Wikimedia set—so you can replace one piece or the entire collection. Since the board draws onto a canvas, use `<img>` elements (any format the browser can load works, including SVG and PNG). The component scales everything to the current board size, so ship high-resolution art for the cleanest result.
+
 ## Installing
 
 `hexchess-board` is packaged as a [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) and should be usable directly in most modern browsers. It bundles its own (configurable) styles, inline assets (for chess pieces), and code.

docs-src/examples/custom-pieces.md

@@ -0,0 +1,34 @@
+---
+layout: example.11ty.cjs
+title: <hexchess-board> ⌲ Examples ⌲ Custom pieces
+tags: example
+name: Custom pieces
+description: Override the built-in set with slots
+---
+
+<script src="https://unpkg.com/@webcomponents/webcomponentsjs@latest/webcomponents-loader.js"></script>
+<script type="module" src="https://esm.sh/@hexchess/hexchess-board@latest/hexchess-board.js?module"></script>
+
+<div style="width: 575px; height: 500px">
+  <hexchess-board board="start">
+    <img
+      slot="piece-white-king"
+      src="https://raw.githubusercontent.com/clarkerubber/Staunton-Pieces/master/Trophies/Big-Gold-Cup.png"
+      alt="White king trophy"
+    />
+  </hexchess-board>
+</div>
+
+<h3>HTML</h3>
+
+```html
+<hexchess-board board="start">
+  <img
+    slot="piece-white-king"
+    src="https://raw.githubusercontent.com/clarkerubber/Staunton-Pieces/master/Trophies/Big-Gold-Cup.png"
+    alt="White king trophy"
+  />
+</hexchess-board>
+```
+
+Add `<img>` tags for any other slot (`piece-white-queen`, `piece-black-pawn`, etc.) to override more pieces. Every surface of the component (canvas, captured pieces, promotions) swaps to the provided art automatically.

docs-src/index.md

@@ -82,3 +82,26 @@ Built-in cues (move, capture, check, checkmate, victory, defeat, and draw) reuse
 ```
 
 The `prepareAudio()` helper lets you unlock and preload sounds during your own UI gesture (to satisfy autoplay restrictions) if your players won't click on the board directly.
+
+## Custom pieces
+
+Bring your own artwork by filling the hidden slots for each piece. Add `<img>` elements with slot names like `piece-white-queen` inside the component and every rendering surface (board, captured pieces, promotions) swaps to your graphics. Leave any slot empty to keep the default set.
+
+```html
+<hexchess-board board="start">
+  <img slot="piece-white-queen" src="/pieces/white-queen.svg" />
+  <img slot="piece-black-queen" src="/pieces/black-queen.svg" />
+  <img slot="piece-black-pawn" src="/pieces/black-pawn.svg" />
+</hexchess-board>
+```
+
+Available slots:
+
+- `piece-white-king` / `piece-black-king`
+- `piece-white-queen` / `piece-black-queen`
+- `piece-white-bishop` / `piece-black-bishop`
+- `piece-white-knight` / `piece-black-knight`
+- `piece-white-rook` / `piece-black-rook`
+- `piece-white-pawn` / `piece-black-pawn`
+
+Any image format the browser supports works (PNG, SVG, AVIF, etc.). The board scales assets to match the current hex size, so ship large, crisp art for the sharpest results.

docs/examples/change-look/index.html

@@ -38,6 +38,14 @@ <h1>Example: Customizing colors</h1>
                     <a href="">Changing the look and feel of the board</a>
                   </li>
 
+                  <li class=>
+                    <a href="../custom-pieces/">Override the built-in set with slots</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../darkmode/">Dark and light modes are both supported.</a>
+                  </li>
+
                   <li class=>
                     <a href="../hexfen/">Customizing the board layout with Hex-FEN</a>
                   </li>
@@ -54,10 +62,6 @@ <h1>Example: Customizing colors</h1>
                     <a href="../preset-moves/">Analyzing a game that has a specific set of moves played.</a>
                   </li>
 
-                  <li class=>
-                    <a href="../darkmode/">Dark and light modes are both supported.</a>
-                  </li>
-
         </ul>
       </nav>
       <div>

docs/examples/custom-pieces/index.html

@@ -0,0 +1,96 @@
+
+<!doctype html>
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title><hexchess-board> ⌲ Examples ⌲ Custom pieces</title>
+    <link rel="stylesheet" href="../../docs.css">
+    <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:300,400,600|Roboto+Mono">
+    <link href="../../prism-okaidia.css" rel="stylesheet" />
+    <script src="/node_modules/@webcomponents/webcomponentsjs/webcomponents-loader.js"></script>
+    <script src="/node_modules/lit/polyfill-support.js"></script>
+    <script type="module" src="../../hexchess-board.bundled.js"></script>
+  </head>
+  <body>
+
+<header>
+  <h1>&lt;hexchess-board></h1>
+  <h2>Chess is better with hexagons</h2>
+</header>
+
+<nav>
+  <a href="../../">Home</a>
+  <a href="../">Examples</a>
+  <a href="../../api/">API</a>
+  <a href="../../install/">Install</a>
+</nav>
+    <div id="main-wrapper">
+      <main>
+
+    <h1>Example: Custom pieces</h1>
+    <section class="examples">
+      <nav class="collection">
+        <ul>
+
+                  <li class=>
+                    <a href="../change-look/">Changing the look and feel of the board</a>
+                  </li>
+
+                  <li class=selected>
+                    <a href="">Override the built-in set with slots</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../darkmode/">Dark and light modes are both supported.</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../hexfen/">Customizing the board layout with Hex-FEN</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../">Common keyboard operations</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../player-roles/">Set player roles</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../preset-moves/">Analyzing a game that has a specific set of moves played.</a>
+                  </li>
+
+        </ul>
+      </nav>
+      <div>
+        <script src="https://unpkg.com/@webcomponents/webcomponentsjs@latest/webcomponents-loader.js"></script>
+<script type="module" src="https://esm.sh/@hexchess/hexchess-board@latest/hexchess-board.js?module"></script>
+<div style="width: 575px; height: 500px">
+  <hexchess-board board="start">
+    <img
+      slot="piece-white-king"
+      src="https://raw.githubusercontent.com/clarkerubber/Staunton-Pieces/master/Trophies/Big-Gold-Cup.png"
+      alt="White king trophy"
+    />
+  </hexchess-board>
+</div>
+<h3>HTML</h3>
+<pre class="language-html"><code class="language-html"><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>hexchess-board</span> <span class="token attr-name">board</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>start<span class="token punctuation">"</span></span><span class="token punctuation">></span></span><br>  <span class="token tag"><span class="token tag"><span class="token punctuation">&lt;</span>img</span><br>    <span class="token attr-name">slot</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>piece-white-king<span class="token punctuation">"</span></span><br>    <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>https://raw.githubusercontent.com/clarkerubber/Staunton-Pieces/master/Trophies/Big-Gold-Cup.png<span class="token punctuation">"</span></span><br>    <span class="token attr-name">alt</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>White king trophy<span class="token punctuation">"</span></span><br>  <span class="token punctuation">/></span></span><br><span class="token tag"><span class="token tag"><span class="token punctuation">&lt;/</span>hexchess-board</span><span class="token punctuation">></span></span></code></pre>
+<p>Add <code>&lt;img&gt;</code> tags for any other slot (<code>piece-white-queen</code>, <code>piece-black-pawn</code>, etc.) to override more pieces. Every surface of the component (canvas, captured pieces, promotions) swaps to the provided art automatically.</p>
+
+      </div>
+    </section>
+
+      </main>
+    </div>
+
+<footer>
+  <p>
+    Made with
+    <a href="https://github.com/lit/lit-element-starter-ts">lit-starter-ts</a>
+  </p>
+</footer>
+  </body>
+</html>

docs/examples/darkmode/index.html

@@ -38,6 +38,14 @@ <h1>Example: Dark Mode</h1>
                     <a href="../change-look/">Changing the look and feel of the board</a>
                   </li>
 
+                  <li class=>
+                    <a href="../custom-pieces/">Override the built-in set with slots</a>
+                  </li>
+
+                  <li class=selected>
+                    <a href="">Dark and light modes are both supported.</a>
+                  </li>
+
                   <li class=>
                     <a href="../hexfen/">Customizing the board layout with Hex-FEN</a>
                   </li>
@@ -54,10 +62,6 @@ <h1>Example: Dark Mode</h1>
                     <a href="../preset-moves/">Analyzing a game that has a specific set of moves played.</a>
                   </li>
 
-                  <li class=selected>
-                    <a href="">Dark and light modes are both supported.</a>
-                  </li>
-
         </ul>
       </nav>
       <div>

docs/examples/hexfen/index.html

@@ -38,6 +38,14 @@ <h1>Example: Hex-FEN Notation</h1>
                     <a href="../change-look/">Changing the look and feel of the board</a>
                   </li>
 
+                  <li class=>
+                    <a href="../custom-pieces/">Override the built-in set with slots</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../darkmode/">Dark and light modes are both supported.</a>
+                  </li>
+
                   <li class=selected>
                     <a href="">Customizing the board layout with Hex-FEN</a>
                   </li>
@@ -54,10 +62,6 @@ <h1>Example: Hex-FEN Notation</h1>
                     <a href="../preset-moves/">Analyzing a game that has a specific set of moves played.</a>
                   </li>
 
-                  <li class=>
-                    <a href="../darkmode/">Dark and light modes are both supported.</a>
-                  </li>
-
         </ul>
       </nav>
       <div>

docs/examples/index.html

@@ -38,6 +38,14 @@ <h1>Example: Keyboard input</h1>
                     <a href="change-look/">Changing the look and feel of the board</a>
                   </li>
 
+                  <li class=>
+                    <a href="custom-pieces/">Override the built-in set with slots</a>
+                  </li>
+
+                  <li class=>
+                    <a href="darkmode/">Dark and light modes are both supported.</a>
+                  </li>
+
                   <li class=>
                     <a href="hexfen/">Customizing the board layout with Hex-FEN</a>
                   </li>
@@ -54,10 +62,6 @@ <h1>Example: Keyboard input</h1>
                     <a href="preset-moves/">Analyzing a game that has a specific set of moves played.</a>
                   </li>
 
-                  <li class=>
-                    <a href="darkmode/">Dark and light modes are both supported.</a>
-                  </li>
-
         </ul>
       </nav>
       <div>

docs/examples/preset-moves/index.html

@@ -38,6 +38,14 @@ <h1>Example: Preset Moves</h1>
                     <a href="../change-look/">Changing the look and feel of the board</a>
                   </li>
 
+                  <li class=>
+                    <a href="../custom-pieces/">Override the built-in set with slots</a>
+                  </li>
+
+                  <li class=>
+                    <a href="../darkmode/">Dark and light modes are both supported.</a>
+                  </li>
+
                   <li class=>
                     <a href="../hexfen/">Customizing the board layout with Hex-FEN</a>
                   </li>
@@ -54,10 +62,6 @@ <h1>Example: Preset Moves</h1>
                     <a href="">Analyzing a game that has a specific set of moves played.</a>
                   </li>
 
-                  <li class=>
-                    <a href="../darkmode/">Dark and light modes are both supported.</a>
-                  </li>
-
         </ul>
       </nav>
       <div>