@johnmorrisdotca/dougu-sports 0.28.0 → 0.29.0

package/CHANGELOG.md

@@ -6,6 +6,39 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-11-03
+
+Put it anywhere: a tag, an embed page and the code for both. A practice baseball with slots all over. The playground's turning is the family's view controls. And the family's must-have list: a documentation site in English and Japanese, usage that is tested, and a check that holds it.
+
+### Added
+
+- **`@johnmorrisdotca/dougu-sports/element`: `<dougu-emblem>`**, any emblem as a web component, still or turning. Attributes `emblem`, `variant`, `size`, `tint`, `accent`, `initials`, `theme`, `locale`, `title`, `yaw`, `pitch`, `roll`, `turnable`, `autoplay` and `speed`; change one and it is drawn again. It draws SVG in a shadow root (styles adopted as a constructable stylesheet, so `style-src 'self'` is enough), waits while it is out of sight, and does not start by itself for a reader who prefers reduced motion. One script line from a CDN: `https://cdn.jsdelivr.net/npm/@johnmorrisdotca/dougu-sports/element/+esm`. Importing it on a server is safe and draws nothing.
+- **`embed.html`**, the page for an `<iframe>`: `embed.html?emblem=trophy:cup&variant=line&size=160&turnable=1`, with a small Pause button when it turns by itself, and nothing else on it.
+- **`emblemEmbedCode(ref, options)`** (in `/emblems` and the main entry): the tag, an iframe, an ES module, an `<img>` with a data address and the raw SVG for an emblem, as text.
+- **Three practice baseballs with slots on both halves**: `ball:plastic-baseball-practice` (high-visibility yellow and black, two-tone), `ball:plastic-baseball-practice-white` and `ball:plastic-baseball-practice-orange`. Two rings of six slots on each half, real see-through holes as the one-sided ball has, drawn from photographs looked at and never copied; no maker's name. The registry goes from 346 to 349 emblems.
+- **`hands: false`** for `bindTurn`: nothing is bound to the element, so a control with its own hands turns the emblem through `setAngles`.
+- **A documentation site** at `/docs/` (a page for each export with a TSDoc summary, parameters, what it returns and an example that was run when the site was built), nine guides in English and in Japanese, and `llms.txt`.
+- **Usage that is tested**: `examples/` holds a script tag from jsDelivr and from unpkg, Vite, webpack, React (and a server render of it), Vue, Svelte, Angular, an iframe, TypeScript and Node, and `pnpm test:usage` builds, type-checks or runs each against the package as npm packs it, opens the ones with a page in a browser, and checks that the README and the guides hold the same text.
+- **The family's must-have check** (`scripts/check-standard.mjs`, held to its recorded hash by `test/standard.test.ts`) and CI runs `test:usage`.
+
+### Changed
+
+- **The playground's turning is `<kazoku-view-controls>`** (kazoku-ui 0.10): the angle slider, Auto-turn with Slow, Medium and Fast, tilt, zoom and Fit, and the pan, with the drag, the wheel, a pinch and the arrow keys on the stage. The view is in the address (`yaw`, `tilt`, `zoom`); the old `pitch`, `speed` and `dir` are no longer read, and the Reverse button is gone (the bar has no reverse). A ball keeps its Roll slider. The pointer over the stage still turns it, a tap still turns it on a phone, and `?turn=1` still starts it.
+- `sideEffects` in `package.json` names `./dist/element.js` instead of being `false`, so a bundler keeps the tag's registration. Nothing else has a side effect.
+- Every export has a TSDoc summary, `@param`, `@returns` and an `@example` (the documentation site is made from them).
+- - The demo (not the package): no long pages of folds (MODULES-112). The playground's three "The call that draws it" folds, open by default, are closed, and the playground's own sits right under the playground instead of at the foot of the page. The composing and brands pages had a fold in every card (five, and twenty-three); each card now has a "Show the call" button that puts its call in one panel at the foot of the window (it follows a change of look and closes with Close or Escape) and the "Copy the call" button it already had. Tests in `e2e/demo.demo.ts`, `e2e/compose.demo.ts` and `e2e/brands.demo.ts`.
+
+## [0.28.1] - 2026-11-02
+
+### Changed
+
+- **The demo takes the family's shared parts from `@johnmorrisdotca/kazoku-ui` 0.7** (a dev dependency used only by the demo; the library stays dependency-free). The three pages that wrote their choices into the address by hand (`demo/demo.ts`, `demo/brands.ts`, `demo/compose.ts`) use the shared address state: the same keys, written a quarter of a second after the last change, so the page's own timer and its `replaceState` code are gone. The family header has the shared language picker (English and Japanese; it keeps the choice in the address, `?lang=`, and in the same `localStorage` key as before) and a new theme switch (Light, Dark, Auto; `?theme=`), from family template 2026-11-02, the same file in every repo that carries it. The demo's own Light and Dark buttons for the emblems are unchanged. The tests hold the new template's hash and the picker and switch, and reach the address with a wait, as it is written after a short delay.
+
+### Changed (repository)
+
+- `release.yml` is a few lines that call kazoku-ui's shared `reusable-release.yml` (pinned to v0.7.3): the same checks, tag, GitHub release with the tarball, and npm publish by trusted publishing. The trusted publisher on npmjs.com stays `release.yml`. The GitHub release's notes are generated by GitHub until the shared workflow reads `scripts/release-notes.ts`.
+- `AGENTS.md` is written from kazoku-ui's template: the family rules above a marker, this repo's board, ports, checks and rules below it.
+
 ## [0.28.0] - 2026-10-30
 
 More league awards: the Jackie Robinson Rookie of the Year plaque, the NFC's Halas Trophy and the Mark Messier and Willie O'Ree awards, the NBA's postseason trophies, and redrawn WNBA, Lamar Hunt, Larry O'Brien and Bill Russell trophies.

package/NOTICE.md

@@ -53,6 +53,7 @@ Each ball's `size.rule` names the rule; the table gives the document and where i
 | `ball:netball` | World Netball Rules of Netball, Rule 1 (Equipment: Ball), item 15 a-d | https://netballhamilton.org.nz/media/1997/world-netball-rules-book-2024.pdf |
 | `ball:pickleball-outdoor`, `ball:pickleball-indoor` | USA Pickleball Equipment Standards Manual (Jan 2025, Revision 3.0), 2.D.1 Design, 2.D.3 Size, 2.D.4 Weight, 2.D.8 Design (holes); USA Pickleball 2026 Official Rulebook rule 3.C Ball Specifications | https://equipment.usapickleball.org/docs/Equipment-Standards-Manual.pdf |
 | `ball:plastic-baseball-slotted` | English Wikipedia, the article on the hollow plastic practice ball with eight oblong holes (accessed 2026-10-21): hollow plastic, wall at most 1/8 in (3.2 mm), eight oblong holes of 0.75 in (19 mm) on one half only, about the size of a regulation baseball; the size is a baseball's, from Official Baseball Rules, Rule 3.01 The Ball | no link: the article is titled with the maker's registered trademark, which this package does not use |
+| `ball:plastic-baseball-practice`, `-white`, `-orange` | The same English Wikipedia article on the hollow plastic practice ball (accessed 2026-10-21) for the material, the wall and the 19 mm slot; Official Baseball Rules, Rule 3.01, for the size. The number and the layout of the slots, and the two tones, are drawn from product photographs looked at and never copied or traced; no maker's name or mark is used | https://en.wikipedia.org/wiki/Wiffle_ball |
 | `ball:squash` and its coloured dots | World Squash 'Specifications for Squash Balls' (Recommended standards approved by the WSF; updated WSF AGM 2021, rebranded 2025), sections 1-3 and Notes 2-4 | https://www.worldsquash.sport/wp-content/uploads/2025/07/211127_Ball-Specifications.pdf |
 | `ball:racquetball` | USA Racquetball Rules, Rule 2.2 Ball Specifications (a)-(b); Rule 2.3 Ball Selection | https://www.usaracquetball.com/play/rules/2-courts-and-equipment |
 | `ball:lacrosse` | World Lacrosse Rules of Men's Field Lacrosse 2025-2027 (Ver 1.0), Section 2 Equipment, Rule 14 The Ball, 14.1 | https://www.bclacrosse.com/Referees%20and%20Officials/World%20Lacrosse%20Men's%20Field%20Rule%20Book.pdf |

package/README.md

@@ -11,7 +11,7 @@ The ball and the gear of every sport, trophies, medals, crests and the icon of e
   <img alt="TypeScript" src="https://img.shields.io/badge/types-TypeScript-3178c6">
 </p>
 
-<p align="center"><a href="https://johnmorrisdotca.github.io/dougu-sports/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/dougu-sports/gallery.html">Gallery</a> · <a href="./docs/gallery.md">Every id</a> · <a href="./docs/turning.md">Turning</a> · <a href="./docs/engraving.md">Engraving</a> · <a href="./docs/layout.md">Layout</a> · <a href="./docs/japanese-sports.md">Japanese sports</a></p>
+<p align="center"><a href="https://johnmorrisdotca.github.io/dougu-sports/"><strong>Open the demo →</strong></a> · <a href="https://johnmorrisdotca.github.io/dougu-sports/embed.html?emblem=trophy:stanley-cup&size=120&turnable=1">Embed page</a> · <a href="https://johnmorrisdotca.github.io/dougu-sports/docs/">Documentation</a> · <a href="https://johnmorrisdotca.github.io/dougu-sports/gallery.html">Gallery</a> · <a href="./docs/gallery.md">Every id</a> · <a href="./docs/turning.md">Turning</a> · <a href="./docs/engraving.md">Engraving</a> · <a href="./docs/layout.md">Layout</a> · <a href="./docs/japanese-sports.md">Japanese sports</a></p>
 
 <p align="center">
 <picture>
@@ -88,7 +88,7 @@ The ball and the gear of every sport, trophies, medals, crests and the icon of e
 </picture>
 </p>
 
-- **A slotted plastic practice baseball**, a hollow white ball with eight oblong slots on one half, drawn with the same see-through holes ([slotted ball](./docs/slotted-ball.md)).
+- **Two plastic practice baseballs**: a hollow white one with eight oblong slots on one half, and the common one with slots all over both halves, in two-tone yellow and black, white and orange (`ball:plastic-baseball-practice`, `-white`, `-orange`), drawn with the same see-through holes ([slotted ball](./docs/slotted-ball.md)).
 
 <p align="center">
 <picture>
@@ -199,6 +199,7 @@ The alias is a name in your `package.json` only: the same package, the same code
 | `@johnmorrisdotca/dougu-sports` | The full registry: every emblem by id, the functions, and each emblem as a constant |
 | `@johnmorrisdotca/dougu-sports/emblems` | `renderEmblem`, the ids and the types, with no single drawing imported by name |
 | `@johnmorrisdotca/dougu-sports/brands` | Experimental, designs will change: twelve made-up maker marks and ten made-up team logos as SVG (`makerLogo`, `teamLogo`, `makerBall`, `renderMakerBall`, the groups to place in a drawing and the data); see [docs/brands.md](./docs/brands.md) |
+| `@johnmorrisdotca/dougu-sports/element` | `<dougu-emblem>`, the tag that draws an emblem in any page, still or turning (the only entry with a side effect: it registers the tag) |
 | `@johnmorrisdotca/dougu-sports/turn` | `emblemFrame`, `ballFrame` and `bindTurn`; `bindTurn` with an emblem object takes nothing else with it |
 | `@johnmorrisdotca/dougu-sports/<group>/<name>` | One emblem, alone: `trophy/hockey-cup`, `medal/gold`, `crest/shield`, `sport/nhl`, `award/crown`, `ball/soccer`, `pennant/championship`, `gear/<name>` |
 
@@ -211,9 +212,67 @@ console.log(TROPHY_HOCKEY_CUP.id); // trophy:hockey-cup
 console.log(TROPHY_HOCKEY_CUP.svg({ size: 24 }).includes('width="24"')); // true
 ```
 
-A bundler that imports this module takes the cup and the renderer for a body of revolution, and no other emblem: the package says `"sideEffects": false` and each constant is marked pure. `test/size.test.ts` bundles one item with esbuild and holds it to a limit for its kind (a ball 7.6 kB, a medal or a crest 4.6 kB, a cup 7.1 kB gzipped, most of that the renderer); `pnpm test:package` does the same from the packed tarball.
+A bundler that imports this module takes the cup and the renderer for a body of revolution, and no other emblem: the package's `sideEffects` names only `./dist/element.js`, and each constant is marked pure. `test/size.test.ts` bundles one item with esbuild and holds it to a limit for its kind (a ball 7.6 kB, a medal or a crest 4.6 kB, a cup 7.1 kB gzipped, most of that the renderer); `pnpm test:package` does the same from the packed tarball.
 
-### In a page
+### Put it in your page
+
+One script tag and the tag `<dougu-emblem>` (from jsDelivr, as in [plain HTML](./docs/guides/html-and-cdn.md)):
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Dougu Sports from jsDelivr</title>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@johnmorrisdotca/dougu-sports/element/+esm"></script>
+  </head>
+  <body>
+    <dougu-emblem emblem="trophy:stanley-cup" size="200" turnable></dougu-emblem>
+  </body>
+</html>
+```
+
+Or one iframe of the embed page, with no script on your page ([iframe guide](./docs/guides/embed-in-an-iframe.md)):
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Dougu Sports in an iframe</title>
+  </head>
+  <body>
+    <iframe
+      src="https://johnmorrisdotca.github.io/dougu-sports/embed.html?emblem=trophy:stanley-cup&size=200&turnable=1"
+      title="The Stanley Cup"
+      width="216"
+      height="216"
+      loading="lazy"
+      style="border: 0"
+    ></iframe>
+  </body>
+</html>
+```
+
+In React (Vue, Svelte, Angular and Vite or webpack are in the [guides](./docs/guides/frameworks.md)); the element is imported where a browser is, so a server render still works:
+
+```tsx
+import { useEffect } from "react";
+
+export function DouguEmblem({ emblem = "trophy:stanley-cup", size = 200 }: { emblem?: string; size?: number }) {
+  useEffect(() => {
+    // The element needs a browser, so it is imported here, never at the top of the file: a server render never reaches an effect.
+    void import("@johnmorrisdotca/dougu-sports/element");
+  }, []);
+  return <dougu-emblem emblem={emblem} size={size} turnable />;
+}
+```
+
+`emblemEmbedCode(ref, options)` writes all of these (the tag, an iframe, an ES module, an `<img>` with a data address, and the raw SVG) for the emblem you have set up; the demo's "Put it in your page" panel is that function with buttons. Every example in the guides is a file in `examples/` that `pnpm test:usage` builds, type-checks or runs against the package as npm packs it. The [documentation site](https://johnmorrisdotca.github.io/dougu-sports/docs/) has a page for every export, guides in English and in Japanese, and a Vite, webpack, TypeScript and Node example each.
+
+### In a page, as a string
 
 ```html
 <span id="trophy"></span>
@@ -676,7 +735,7 @@ Bug reports and ideas go in the [issues](https://github.com/johnmorrisdotca/doug
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). 0.28.0 adds the Jackie Robinson Rookie of the Year plaque (`trophy:jackie-robinson-award`), the Halas, Messier, O'Ree and NBA postseason trophies and redraws the WNBA, Lamar Hunt, Larry O'Brien and Bill Russell trophies (346 emblems); 0.27.0 adds the NHL Foundation Player Award (`trophy:foundation-player-award`, 335 emblems) and redraws the Kelly Cup and the Calder Cup closer to their photographs; 0.26.0 adds four league championship trophies, drawn from photographs of the real ones: the Calder Cup of the AHL, the Kelly Cup of the ECHL, the MLS Cup and the College Football Playoff trophy (`trophy:calder-cup`, `trophy:kelly-cup`, `trophy:mls-cup`, `trophy:cfp-trophy`, 334 emblems); 0.25.0 adds two of baseball's awards, drawn from photographs of the real ones: the Hank Aaron Award and the Relief Man Award (`trophy:hank-aaron-award`, `trophy:relief-man-award`, 330 emblems); 0.24.0 adds a baseball cap (`gear:baseball-cap`, 328 emblems); 0.23.0 adds the Bill Russell Finals MVP Trophy, drawn from a photograph of the real one (`trophy:bill-russell-trophy`, 327 emblems); 0.22.0 takes out the award cups and the cap of the unpublished 0.17.0 to 0.21.0, which did not match the real objects; 0.16.0 adds a slotted plastic practice baseball (`ball:plastic-baseball-slotted`, 326 emblems: [docs/slotted-ball.md](./docs/slotted-ball.md)); 0.15.0 gives the pickleballs real holes, cut through the shell and drawn with the inside of the ball behind them, so the page shows through where two holes line up ([docs/pickleball.md](./docs/pickleball.md)); 0.14.0 lets the auto-turn go either way (`direction: "clockwise"` or `"counterclockwise"`, `setDirection()`); 0.13.0 adds a pictogram for each of four combat sports, MMA (a cage), boxing (a glove), wrestling (two wrestlers on the mat) and professional wrestling (a ring with ropes), in the three styles (326 emblems); 0.12.0 adds forty-seven named trophies, each a close likeness measured on a photograph (321 emblems); 0.11.0 gives the era soccer balls neutral ids (the old ones stay as aliases), new looks and a second 1980s ball (274 emblems); 0.10.0 adds a standalone ribbon and the nets and posts of sepak takraw, netball and teqball from their rulebooks' sizes (273 emblems); 0.9.0 lets the baseball, the softball and the classic soccer balls be painted and printed: solid and two-tone colours, a logo of your own wrapped onto the ball, stamped text, an original cursive word and a small mark, all turning with the ball ([docs/custom-balls.md](./docs/custom-balls.md)); 0.8.0 makes `bindTurn` light: it takes an emblem object and then needs no registry, so a turnable cup is about 9.4 kB gzipped instead of about 81 kB, and an id loads the registry on demand; 0.7.3 turns the build, docs and picture scripts, the browser tests and the demo's source from JavaScript into TypeScript, with no change to the package; 0.7.2 makes every docs page single-language (a page in Japanese beside each page that had Japanese words in it, and a test that holds them apart), with no change to the pictures; 0.7.1 puts real countries (Canada, Japan) in the crest and puck examples in place of made-up teams, with no change to the code; 0.7.0 gives the national volleyballs layouts that tell them apart (Japan a crimson band, Poland white above and red below, the USA a navy field), strengthens the 2010-style grooved soccer ball, and adds six pictures of how the judo belt is tied, `gear:obi-step-1` to `gear:obi-step-6` (269 emblems: [docs/obi-steps.md](./docs/obi-steps.md)); 0.6.0 gives the judo suit and the karate suit their sleeves (a judogi has no short ones: they reach the wrist) and adds the judogi seen from behind with the IJF-style back number, a family name and a country code on a patch, with a `backnumber` option (269 emblems: [docs/judogi-back.md](./docs/judogi-back.md)); 0.5.1 redraws the judo suit, the belt and the football pictograms and adds the blue and folded suits and the belts of every grade (261 emblems: [docs/japanese-sports.md](./docs/japanese-sports.md)); 0.5.0 adds fifty balls: vintage leather soccer balls, era-style and shop-wall soccer balls, baseballs of other threads and volleyballs in national colours, with a `colors` option (244 emblems: [docs/vintage-balls.md](./docs/vintage-balls.md)); 0.4.0 adds eight printed pucks and a `face` option (194 emblems: [docs/pucks.md](./docs/pucks.md)); 0.3.0 adds nineteen soccer balls (26, 18, 14, 12 and 6 panels, winter orange and high-visibility yellow, futsal and beach soccer: 186 emblems); 0.2.1 draws every ball and implement to the rulebook's proportions; 0.2.0 is 167 emblems, every one drawn here, with the Japanese sports, engraving, a turn for every emblem and the compose helpers; 0.1.0 brought the first full set of 148; 0.0.1 was the first preview.
+See [CHANGELOG.md](./CHANGELOG.md). 0.29.0 adds `<dougu-emblem>` and the embed page, three practice baseballs with slots on both halves, and the documentation site, and puts the playground on the family's view controls. 0.28.0 adds the Jackie Robinson Rookie of the Year plaque (`trophy:jackie-robinson-award`), the Halas, Messier, O'Ree and NBA postseason trophies and redraws the WNBA, Lamar Hunt, Larry O'Brien and Bill Russell trophies (346 emblems); 0.27.0 adds the NHL Foundation Player Award (`trophy:foundation-player-award`, 335 emblems) and redraws the Kelly Cup and the Calder Cup closer to their photographs; 0.26.0 adds four league championship trophies, drawn from photographs of the real ones: the Calder Cup of the AHL, the Kelly Cup of the ECHL, the MLS Cup and the College Football Playoff trophy (`trophy:calder-cup`, `trophy:kelly-cup`, `trophy:mls-cup`, `trophy:cfp-trophy`, 334 emblems); 0.25.0 adds two of baseball's awards, drawn from photographs of the real ones: the Hank Aaron Award and the Relief Man Award (`trophy:hank-aaron-award`, `trophy:relief-man-award`, 330 emblems); 0.24.0 adds a baseball cap (`gear:baseball-cap`, 328 emblems); 0.23.0 adds the Bill Russell Finals MVP Trophy, drawn from a photograph of the real one (`trophy:bill-russell-trophy`, 327 emblems); 0.22.0 takes out the award cups and the cap of the unpublished 0.17.0 to 0.21.0, which did not match the real objects; 0.16.0 adds a slotted plastic practice baseball (`ball:plastic-baseball-slotted`, 326 emblems: [docs/slotted-ball.md](./docs/slotted-ball.md)); 0.15.0 gives the pickleballs real holes, cut through the shell and drawn with the inside of the ball behind them, so the page shows through where two holes line up ([docs/pickleball.md](./docs/pickleball.md)); 0.14.0 lets the auto-turn go either way (`direction: "clockwise"` or `"counterclockwise"`, `setDirection()`); 0.13.0 adds a pictogram for each of four combat sports, MMA (a cage), boxing (a glove), wrestling (two wrestlers on the mat) and professional wrestling (a ring with ropes), in the three styles (326 emblems); 0.12.0 adds forty-seven named trophies, each a close likeness measured on a photograph (321 emblems); 0.11.0 gives the era soccer balls neutral ids (the old ones stay as aliases), new looks and a second 1980s ball (274 emblems); 0.10.0 adds a standalone ribbon and the nets and posts of sepak takraw, netball and teqball from their rulebooks' sizes (273 emblems); 0.9.0 lets the baseball, the softball and the classic soccer balls be painted and printed: solid and two-tone colours, a logo of your own wrapped onto the ball, stamped text, an original cursive word and a small mark, all turning with the ball ([docs/custom-balls.md](./docs/custom-balls.md)); 0.8.0 makes `bindTurn` light: it takes an emblem object and then needs no registry, so a turnable cup is about 9.4 kB gzipped instead of about 81 kB, and an id loads the registry on demand; 0.7.3 turns the build, docs and picture scripts, the browser tests and the demo's source from JavaScript into TypeScript, with no change to the package; 0.7.2 makes every docs page single-language (a page in Japanese beside each page that had Japanese words in it, and a test that holds them apart), with no change to the pictures; 0.7.1 puts real countries (Canada, Japan) in the crest and puck examples in place of made-up teams, with no change to the code; 0.7.0 gives the national volleyballs layouts that tell them apart (Japan a crimson band, Poland white above and red below, the USA a navy field), strengthens the 2010-style grooved soccer ball, and adds six pictures of how the judo belt is tied, `gear:obi-step-1` to `gear:obi-step-6` (269 emblems: [docs/obi-steps.md](./docs/obi-steps.md)); 0.6.0 gives the judo suit and the karate suit their sleeves (a judogi has no short ones: they reach the wrist) and adds the judogi seen from behind with the IJF-style back number, a family name and a country code on a patch, with a `backnumber` option (269 emblems: [docs/judogi-back.md](./docs/judogi-back.md)); 0.5.1 redraws the judo suit, the belt and the football pictograms and adds the blue and folded suits and the belts of every grade (261 emblems: [docs/japanese-sports.md](./docs/japanese-sports.md)); 0.5.0 adds fifty balls: vintage leather soccer balls, era-style and shop-wall soccer balls, baseballs of other threads and volleyballs in national colours, with a `colors` option (244 emblems: [docs/vintage-balls.md](./docs/vintage-balls.md)); 0.4.0 adds eight printed pucks and a `face` option (194 emblems: [docs/pucks.md](./docs/pucks.md)); 0.3.0 adds nineteen soccer balls (26, 18, 14, 12 and 6 panels, winter orange and high-visibility yellow, futsal and beach soccer: 186 emblems); 0.2.1 draws every ball and implement to the rulebook's proportions; 0.2.0 is 167 emblems, every one drawn here, with the Japanese sports, engraving, a turn for every emblem and the compose helpers; 0.1.0 brought the first full set of 148; 0.0.1 was the first preview.
 
 ## Credits
 

package/dist/brands/brand.ball.d.ts

@@ -2,7 +2,15 @@ import { type EmblemRef } from "../emblems/emblem.api.ts";
 import type { EmblemOptions } from "../emblems/emblem.core.ts";
 import type { MakerId } from "./brand.data.ts";
 import { type MakerLogoOptions } from "./brand.render.ts";
-/** How a maker's logo sits on a ball. */
+/**
+ * How a maker's logo sits on a ball.
+ * @example
+ * ```ts
+ * import type { MakerBallOptions } from "@johnmorrisdotca/dougu-sports/brands";
+ * const options: MakerBallOptions = { layout: "stacked", width: 60, turn: 10 };
+ * console.log(options.width);
+ * ```
+ */
 export interface MakerBallOptions extends Omit<MakerLogoOptions, "size" | "title"> {
     /** How wide the logo is, in degrees of the ball (the mark alone 50 by default, a layout with a wordmark 74). */
     width?: number;
@@ -11,6 +19,9 @@ export interface MakerBallOptions extends Omit<MakerLogoOptions, "size" | "title
 }
 /**
  * The ball options that print a maker's logo on it: `{ decal: { svg, size, turn } }`, to spread into the options of `renderEmblem`, `emblemFrame` or `bindTurn`. The logo is wrapped onto the sphere, so it curves with the ball and turns with it.
+ * @param id - A maker id from `MAKER_IDS`.
+ * @param o - The layout, colours, width and turn of the logo on the ball.
+ * @returns The ball options `{ decal }` that print the logo.
  * @example
  * ```ts
  * import { makerBall } from "@johnmorrisdotca/dougu-sports/brands";
@@ -25,5 +36,17 @@ export declare function makerBall(id: MakerId, o?: MakerBallOptions): {
         turn: number;
     };
 };
-/** A ball with a maker's logo printed on it: `renderMakerBall("ball:baseball", "arvane", { size: 320 })`. Any other options of the ball (`paint`, `stamp`, `spots`...) go in `ball`. */
+/**
+ * A ball with a maker's logo printed on it: `renderMakerBall("ball:baseball", "arvane", { size: 320 })`. Any other options of the ball (`paint`, `stamp`, `spots`...) go in `ball`.
+ * @param ball - The ball to print on: an id or an emblem.
+ * @param id - A maker id from `MAKER_IDS`.
+ * @param o - How the logo sits on the ball.
+ * @param ballOptions - The other options of the ball.
+ * @returns The printed ball as a document of SVG.
+ * @example
+ * ```ts
+ * import { renderMakerBall } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(renderMakerBall("ball:baseball", "arvane", { width: 40 }, { size: 160 }).startsWith("<svg"));
+ * ```
+ */
 export declare function renderMakerBall(ball: EmblemRef, id: MakerId, o?: MakerBallOptions, ballOptions?: EmblemOptions): string;

package/dist/brands/brand.ball.js

@@ -4,6 +4,9 @@ import { renderEmblem } from "../emblems/emblem.api.js";
 import { makerLogo } from "./brand.render.js";
 /**
  * The ball options that print a maker's logo on it: `{ decal: { svg, size, turn } }`, to spread into the options of `renderEmblem`, `emblemFrame` or `bindTurn`. The logo is wrapped onto the sphere, so it curves with the ball and turns with it.
+ * @param id - A maker id from `MAKER_IDS`.
+ * @param o - The layout, colours, width and turn of the logo on the ball.
+ * @returns The ball options `{ decal }` that print the logo.
  * @example
  * ```ts
  * import { makerBall } from "@johnmorrisdotca/dougu-sports/brands";
@@ -17,7 +20,19 @@ export function makerBall(id, o) {
     const turn = typeof o?.turn === "number" && Number.isFinite(o.turn) ? o.turn : 0;
     return { decal: { svg: makerLogo(id, { ...o, title: false, size: 200 }), size, turn } };
 }
-/** A ball with a maker's logo printed on it: `renderMakerBall("ball:baseball", "arvane", { size: 320 })`. Any other options of the ball (`paint`, `stamp`, `spots`...) go in `ball`. */
+/**
+ * A ball with a maker's logo printed on it: `renderMakerBall("ball:baseball", "arvane", { size: 320 })`. Any other options of the ball (`paint`, `stamp`, `spots`...) go in `ball`.
+ * @param ball - The ball to print on: an id or an emblem.
+ * @param id - A maker id from `MAKER_IDS`.
+ * @param o - How the logo sits on the ball.
+ * @param ballOptions - The other options of the ball.
+ * @returns The printed ball as a document of SVG.
+ * @example
+ * ```ts
+ * import { renderMakerBall } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(renderMakerBall("ball:baseball", "arvane", { width: 40 }, { size: 160 }).startsWith("<svg"));
+ * ```
+ */
 export function renderMakerBall(ball, id, o, ballOptions) {
     return renderEmblem(ball, { ...ballOptions, ...makerBall(id, o) });
 }

package/dist/brands/brand.data.d.ts

@@ -1,23 +1,67 @@
 import type { LetterStyle } from "./brand.letters.ts";
+/**
+ * Which colour of a palette a part of a mark takes: `a`, `b` or `c`.
+ * @example
+ * ```ts
+ * import type { PartRole } from "@johnmorrisdotca/dougu-sports/brands";
+ * const role: PartRole = "b";
+ * console.log(role);
+ * ```
+ */
 export type PartRole = "a" | "b" | "c";
-/** One flat shape of a mark: an SVG path (drawn with the even-odd rule, so a hole is a hole) and the colour it takes. */
+/**
+ * One flat shape of a mark: an SVG path (drawn with the even-odd rule, so a hole is a hole) and the colour it takes.
+ * @example
+ * ```ts
+ * import type { LogoPart } from "@johnmorrisdotca/dougu-sports/brands";
+ * const part: LogoPart = { d: "M0 0h10v10z", role: "a" };
+ * console.log(part.role);
+ * ```
+ */
 export interface LogoPart {
     d: string;
     role: PartRole;
 }
-/** The colours of a maker on a light page or a dark one: the two of its mark and the ink of its wordmark. */
+/**
+ * The colours of a maker on a light page or a dark one: the two of its mark and the ink of its wordmark.
+ * @example
+ * ```ts
+ * import { MAKERS } from "@johnmorrisdotca/dougu-sports/brands";
+ * import type { MakerPalette } from "@johnmorrisdotca/dougu-sports/brands";
+ * const palette: MakerPalette = MAKERS.arvane.light;
+ * console.log(palette.a, palette.b, palette.ink);
+ * ```
+ */
 export interface MakerPalette {
     a: string;
     b: string;
     ink: string;
 }
-/** The three colours of a team logo on a light page or a dark one. */
+/**
+ * The three colours of a team logo on a light page or a dark one.
+ * @example
+ * ```ts
+ * import { TEAMS } from "@johnmorrisdotca/dougu-sports/brands";
+ * import type { TeamPalette } from "@johnmorrisdotca/dougu-sports/brands";
+ * const palette: TeamPalette = TEAMS.saltmere.dark;
+ * console.log(palette.a, palette.b, palette.c);
+ * ```
+ */
 export interface TeamPalette {
     a: string;
     b: string;
     c: string;
 }
-/** A fictional maker of balls and sports gear: a mark, a name to set as a wordmark, two palettes and the note of how it differs from the nearest real brand. */
+/**
+ * A fictional maker of balls and sports gear: a mark, a name to set as a wordmark, two palettes and the note of how it differs from the nearest real brand.
+ * @example
+ * ```ts
+ * import { MAKERS } from "@johnmorrisdotca/dougu-sports/brands";
+ * import type { MakerData } from "@johnmorrisdotca/dougu-sports/brands";
+ * const maker: MakerData = MAKERS.arvane;
+ * console.log(maker.name, maker.parts.length);
+ * ```
+ */
 export interface MakerData {
     id: MakerId;
     name: string;
@@ -28,7 +72,16 @@ export interface MakerData {
     dark: MakerPalette;
     lettering: LetterStyle;
 }
-/** A fictional team: a city and a nickname, a logo, two palettes and a note. */
+/**
+ * A fictional team: a city and a nickname, a logo, two palettes and a note.
+ * @example
+ * ```ts
+ * import { TEAMS } from "@johnmorrisdotca/dougu-sports/brands";
+ * import type { TeamData } from "@johnmorrisdotca/dougu-sports/brands";
+ * const team: TeamData = TEAMS.saltmere;
+ * console.log(team.city, team.nickname);
+ * ```
+ */
 export interface TeamData {
     id: TeamId;
     city: string;
@@ -39,9 +92,59 @@ export interface TeamData {
     light: TeamPalette;
     dark: TeamPalette;
 }
+/**
+ * The ids of the fictional makers.
+ * @example
+ * ```ts
+ * import { MAKER_IDS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(MAKER_IDS.length, MAKER_IDS[0]);
+ * ```
+ */
 export declare const MAKER_IDS: readonly ["arvane", "tarsin", "ravelle", "kovreth", "dunmar", "ostrel", "vexlin", "quillan", "tenzar", "marenko", "halvane", "solvik"];
+/**
+ * The id of a fictional maker.
+ * @example
+ * ```ts
+ * import type { MakerId } from "@johnmorrisdotca/dougu-sports/brands";
+ * const id: MakerId = "arvane";
+ * console.log(id);
+ * ```
+ */
 export type MakerId = (typeof MAKER_IDS)[number];
+/**
+ * The ids of the fictional teams.
+ * @example
+ * ```ts
+ * import { TEAM_IDS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(TEAM_IDS.length, TEAM_IDS[0]);
+ * ```
+ */
 export declare const TEAM_IDS: readonly ["saltmere", "greywick", "brightwater", "cinderfell", "valmere", "larkmoor", "ironport", "pinecrest", "redfern", "tarn"];
+/**
+ * The id of a fictional team.
+ * @example
+ * ```ts
+ * import type { TeamId } from "@johnmorrisdotca/dougu-sports/brands";
+ * const id: TeamId = "saltmere";
+ * console.log(id);
+ * ```
+ */
 export type TeamId = (typeof TEAM_IDS)[number];
+/**
+ * The fictional makers of balls and sports gear, by id: each a mark, a name, two palettes and a note on how it differs from the nearest real brand.
+ * @example
+ * ```ts
+ * import { MAKERS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(Object.keys(MAKERS).length);
+ * ```
+ */
 export declare const MAKERS: Readonly<Record<MakerId, MakerData>>;
+/**
+ * The fictional teams, by id: each a city, a nickname, a logo, two palettes and a note.
+ * @example
+ * ```ts
+ * import { TEAMS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(Object.keys(TEAMS).length);
+ * ```
+ */
 export declare const TEAMS: Readonly<Record<TeamId, TeamData>>;

package/dist/brands/brand.data.js

@@ -1,8 +1,32 @@
 // The set: twelve fictional maker marks and ten fictional team logos, as data. Every mark is drawn for this package on a 100 by 100 box in a few flat parts, each part one path and one role (`a` the main colour, `b` the second, `c` a third
 // for a team); the parts never overlap, so the mark is the same drawn in one colour. Nothing here is a real company's or club's mark, name or lettering: each note says what the nearest real one is and how this differs.
+/**
+ * The ids of the fictional makers.
+ * @example
+ * ```ts
+ * import { MAKER_IDS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(MAKER_IDS.length, MAKER_IDS[0]);
+ * ```
+ */
 export const MAKER_IDS = ["arvane", "tarsin", "ravelle", "kovreth", "dunmar", "ostrel", "vexlin", "quillan", "tenzar", "marenko", "halvane", "solvik"];
+/**
+ * The ids of the fictional teams.
+ * @example
+ * ```ts
+ * import { TEAM_IDS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(TEAM_IDS.length, TEAM_IDS[0]);
+ * ```
+ */
 export const TEAM_IDS = ["saltmere", "greywick", "brightwater", "cinderfell", "valmere", "larkmoor", "ironport", "pinecrest", "redfern", "tarn"];
 const part = (role, d) => ({ role, d });
+/**
+ * The fictional makers of balls and sports gear, by id: each a mark, a name, two palettes and a note on how it differs from the nearest real brand.
+ * @example
+ * ```ts
+ * import { MAKERS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(Object.keys(MAKERS).length);
+ * ```
+ */
 export const MAKERS = Object.freeze({
     arvane: {
         id: "arvane",
@@ -168,6 +192,14 @@ export const MAKERS = Object.freeze({
         lettering: { weight: 13, corner: "round", radius: 16, width: 0.85, gap: 12, slant: 0, cap: "round" },
     },
 });
+/**
+ * The fictional teams, by id: each a city, a nickname, a logo, two palettes and a note.
+ * @example
+ * ```ts
+ * import { TEAMS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(Object.keys(TEAMS).length);
+ * ```
+ */
 export const TEAMS = Object.freeze({
     saltmere: {
         id: "saltmere",

package/dist/brands/brand.letters.d.ts

@@ -1,4 +1,12 @@
-/** How a wordmark is lettered. */
+/**
+ * How a wordmark is lettered.
+ * @example
+ * ```ts
+ * import type { LetterStyle } from "@johnmorrisdotca/dougu-sports/brands";
+ * const style: LetterStyle = { weight: 12, corner: "round", radius: 6, width: 1, gap: 8, slant: 6, cap: "round" };
+ * console.log(style.weight);
+ * ```
+ */
 export interface LetterStyle {
     /** Stroke weight, in units of a letter 100 high. */
     weight: number;
@@ -15,9 +23,25 @@ export interface LetterStyle {
     /** The ends of a stroke. */
     cap: "butt" | "round" | "square";
 }
-/** The letters the alphabet draws. */
+/**
+ * The letters the alphabet draws.
+ * @example
+ * ```ts
+ * import { LETTERS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(LETTERS.length, LETTERS[0]);
+ * ```
+ */
 export declare const LETTERS: readonly string[];
-/** A word laid out: the path of all its letters (stroked, not filled) and the box it fills. */
+/**
+ * A word laid out: the path of all its letters (stroked, not filled) and the box it fills.
+ * @example
+ * ```ts
+ * import { MAKERS, lettering } from "@johnmorrisdotca/dougu-sports/brands";
+ * import type { Lettering } from "@johnmorrisdotca/dougu-sports/brands";
+ * const word: Lettering = lettering("ARVANE", MAKERS.arvane.lettering);
+ * console.log(word.d.startsWith("M"), word.weight);
+ * ```
+ */
 export interface Lettering {
     d: string;
     width: number;
@@ -27,5 +51,16 @@ export interface Lettering {
 }
 /** The unit height the lettering is drawn at. */
 export declare const LETTER_HEIGHT = 100;
-/** A word in capitals, in a style. A letter the alphabet does not have is left out. The box includes the stroke's half weight and the room a lean needs. */
+/**
+ * A word in capitals, in a style. A letter the alphabet does not have is left out. The box includes the stroke's half weight and the room a lean needs.
+ * @param word - The word, in capitals.
+ * @param style - The weight, corners, width, gap, slant and line ends.
+ * @returns The path of the letters and the box it fills.
+ * @example
+ * ```ts
+ * import { MAKERS, lettering } from "@johnmorrisdotca/dougu-sports/brands";
+ * const word = lettering("ARVANE", MAKERS.arvane.lettering);
+ * console.log(word.width > 0, word.height > 0);
+ * ```
+ */
 export declare function lettering(word: string, style: LetterStyle): Lettering;

package/dist/brands/brand.letters.js

@@ -32,7 +32,14 @@ const SKELETONS = {
 /** Letters whose right side is open at the top or the bottom, and letters whose sides lean in: a pair of the two is set closer. */
 const OPEN = "LTFPYRVAW";
 const LEAN = "AVWYT";
-/** The letters the alphabet draws. */
+/**
+ * The letters the alphabet draws.
+ * @example
+ * ```ts
+ * import { LETTERS } from "@johnmorrisdotca/dougu-sports/brands";
+ * console.log(LETTERS.length, LETTERS[0]);
+ * ```
+ */
 export const LETTERS = Object.freeze(Object.keys(SKELETONS));
 const round1 = (value) => String(Math.round(value * 10) / 10 + 0);
 /** One stroke as a path: corners rounded or cut by `radius`, never by more than half a side. */
@@ -61,7 +68,18 @@ function strokePath(points, closed, style) {
 }
 /** The unit height the lettering is drawn at. */
 export const LETTER_HEIGHT = 100;
-/** A word in capitals, in a style. A letter the alphabet does not have is left out. The box includes the stroke's half weight and the room a lean needs. */
+/**
+ * A word in capitals, in a style. A letter the alphabet does not have is left out. The box includes the stroke's half weight and the room a lean needs.
+ * @param word - The word, in capitals.
+ * @param style - The weight, corners, width, gap, slant and line ends.
+ * @returns The path of the letters and the box it fills.
+ * @example
+ * ```ts
+ * import { MAKERS, lettering } from "@johnmorrisdotca/dougu-sports/brands";
+ * const word = lettering("ARVANE", MAKERS.arvane.lettering);
+ * console.log(word.width > 0, word.height > 0);
+ * ```
+ */
 export function lettering(word, style) {
     const lean = Math.tan((style.slant * Math.PI) / 180);
     const half = style.weight / 2;