@johnmorrisdotca/dougu-sports 0.0.1 → 0.1.0

package/README.md

@@ -1,7 +1,7 @@
 <h1 align="center">Dougu Sports <sub>道具</sub></h1>
 
 <p align="center"><strong>Sports emblems as SVG strings, with optional 3D turning.</strong><br>
-Trophies, medals, crests, and the ball and gear of every sport, each one a function that returns SVG: in metal, in one line, or in flat colour, light and dark, any size, any tint. Turn one about its axis and it is another string. Each emblem is its own module, so a page that wants one ball takes one ball. MIT, with no dependencies.</p>
+Trophies, medals, crests, the icon of every sport, and the ball and gear of the sports, each one a function that returns SVG: in polished metal, in one line, or in flat colour, light and dark, any size, any tint. Turn one about its axis and it is another string. Each emblem is its own module, so a page that wants one trophy takes one trophy. MIT, with no dependencies.</p>
 
 <p align="center">
   <a href="https://github.com/johnmorrisdotca/dougu-sports/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/johnmorrisdotca/dougu-sports/actions/workflows/ci.yml/badge.svg"></a>
@@ -16,14 +16,14 @@ Trophies, medals, crests, and the ball and gear of every sport, each one a funct
 <p align="center">
 <picture>
 <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-dark.png">
-<img alt="The package's two sample emblems, each in the three styles: a gold medal on a red ribbon, and a soccer ball, drawn in metal with gradients, as one outline, and in flat colour." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="760">
+<img alt="Ten trophies drawn in metal, each a generic form that stands for a league's cup: a tall banded silver cup, a ring of gold pennants round a baseball, a football on a three-sided stand, a basketball over a net, a wide two-handled bowl on a tall base, a globe held up by spiral figures, a gilt dish, a lidded cup with a pineapple, a terracotta urn and a gilded lidded cup. Below them gold, silver and bronze medals, crests, a rosette, a wreath and a belt, and one cup in the three styles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="760">
 </picture>
 </p>
 
 <table align="center">
 <tr>
 <td align="center" valign="top">
-<img alt="A soccer ball and a medal turned through five angles: the ball rolls, and the medal flips like a coin to show its plain back." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.png" width="470"><br><em>Turned: a ball rolls, a medal flips</em>
+<img alt="A two-handled cup, a banded cup, a medal and a soccer ball each turned through five angles: the cups keep their outline and move their light and handles, the medal flips like a coin to show its plain back, and the ball rolls." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.png" width="470"><br><em>Turned: a ball rolls, a medal flips</em>
 </td>
 <td align="center" valign="top">
 <img alt="The same emblems on a phone, light." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/phone-light.png" width="200"><br><em>On a phone</em>
@@ -31,7 +31,7 @@ Trophies, medals, crests, and the ball and gear of every sport, each one a funct
 </tr>
 </table>
 
-> **Status: scaffold.** The package so far holds the machinery and two sample emblems, `award:medal` and `ball:soccer`, that stand in for the art. The trophies, medals, crests and the ball and gear of 33 sports arrive group by group ([docs/layout.md](./docs/layout.md) says where each goes), and the README's counts are read from the code, so they grow with it. Not on npm yet.
+> **Status: preview.** 148 emblems: 20 trophies, 5 awards, 6 medals, 4 crests, a pictogram for each of the 33 sports, 47 balls and implements drawn in 3D, and 33 pieces of gear ([docs/layout.md](./docs/layout.md) says where each goes).
 
 ## In 30 seconds
 
@@ -42,10 +42,10 @@ npm install @johnmorrisdotca/dougu-sports
 ```js
 import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
 
-const svg = renderEmblem("ball:soccer", { style: "color", size: 48 });
+const svg = renderEmblem("trophy:hockey-cup", { size: 48 });
 
 console.log(svg.startsWith("<svg")); // true
-console.log(svg.includes("<title>Soccer ball</title>")); // true
+console.log(svg.includes("<title>Tall banded silver cup</title>")); // true
 ```
 
 Put the string in a page (`element.innerHTML = svg`), write it to a file, or send it from a server: it is plain SVG, with no script, no font and no network. The outline takes the page's text colour, so an emblem follows light and dark mode as the text does.
@@ -55,14 +55,15 @@ Put the string in a page (`element.innerHTML = svg`), write it to a file, or sen
 - **Sports sites** that mark a champion, a result or a list with a trophy, a medal or a crest, without licensing a logo.
 - **Scoreboards and brackets** that want a generic emblem for a team that has no logo, tinted in the team's colour.
 - **Anyone building a game or a card** who needs a ball or a piece of gear for a sport, in one style that matches the rest.
-- **Pages that care about weight**: one emblem is one module and about 2 kB gzipped, and the package says `"sideEffects": false`.
+- **Pages that care about weight**: one emblem is one module, 2 to 6 kB gzipped with the renderer for its kind (a medal about 3, a turning cup about 5), and the package says `"sideEffects": false`.
 
 ## Features
 
-- **Three styles** for every emblem: `metal` (full colour with gradients), `line` (one outline in the page's text colour) and `color` (flat fills); see [Theming](#theming).
-- **Size, tint and theme** as options: a tint recolours the main part (a medal's metal, a ball's patches), a theme sets the outline for light, dark or either.
+- **Three styles** for every emblem: `metal` (polished metal: a gradient, a highlight and a soft rim of reflected light, edged in a darker tone of its own metal, with no heavy outline), `line` (one clean outline in the page's text colour, made to read at 14 pixels) and `color` (flat fills); see [Theming](#theming).
+- **Size, tint, accent and theme** as options: a tint recolours the main part (a medal's metal, a crest's colour, a ball's patches), an accent the second colour (a ribbon, a crest's band, the pennants), a theme sets the ink for light, dark or either.
 - **Turning**: `emblemFrame` and `ballFrame` return the emblem at an angle, in plain SVG; see [docs/turning.md](./docs/turning.md).
 - **One module per item**, so a bundler takes only what is imported; see [Use it in your project](#use-it-in-your-project).
+- **Short names and helpers**: `"cup"` is `"trophy:cup"`, `"trophy:cup/line"` is the line style, and `crest`, `medal` and `sportIcon` draw a team's crest, a medal and a sport's icon.
 - **Typed ids**: `EmblemId` is a union of `award:*`, `trophy:*`, `medal:*`, `crest:*`, `ball:*`, `gear:*` and `sport:*` ids.
 - **Generic by design**: no emblem carries a league's, a team's or a federation's name or mark.
 - **Accessible**: every drawing is `role="img"` with a `<title>`; see [Accessibility](#accessibility).
@@ -73,12 +74,12 @@ Put the string in a page (`element.innerHTML = svg`), write it to a file, or sen
 
 <table>
 <tr>
-<td align="center" valign="top"><img alt="A gold medal on a red ribbon with a star on its face, in metal, line and color." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="360"><br><em><code>award:medal</code> and <code>ball:soccer</code>, each in three styles</em></td>
-<td align="center" valign="top"><img alt="A soccer ball and a medal turned through five angles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.png" width="360"><br><em>Turned through five angles</em></td>
+<td align="center" valign="top"><img alt="Ten trophies, medals and crests, and one cup in the three styles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/hero-desk-light.png" width="360"><br><em>Trophies, medals and crests, and one cup in three styles</em></td>
+<td align="center" valign="top"><img alt="Cups, a medal and a ball turned through five angles." src="https://raw.githubusercontent.com/johnmorrisdotca/dougu-sports/main/docs/images/turn-desk-light.png" width="360"><br><em>Turned through five angles</em></td>
 </tr>
 </table>
 
-The list of every emblem, with its names, kind, source and the import that takes it alone, is [docs/gallery.md](./docs/gallery.md), made from the built package.
+Every emblem, with its id in both styles and a button that copies it, is on the [gallery page](https://johnmorrisdotca.github.io/dougu-sports/gallery.html); the same list as text, with its names, kind, source and the import that takes it alone, is [docs/gallery.md](./docs/gallery.md), made from the built package. [docs/emblems.md](./docs/emblems.md) says how the art is drawn.
 
 ## Use it in your project
 
@@ -111,20 +112,18 @@ 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/turn` | `emblemFrame` and `ballFrame` |
-| `@johnmorrisdotca/dougu-sports/award/<name>` | One award, trophy, medal, crest or sport emblem, alone (`award/medal`) |
-| `@johnmorrisdotca/dougu-sports/ball/<name>` | One ball, alone (`ball/soccer`) |
-| `@johnmorrisdotca/dougu-sports/gear/<name>` | One piece of gear, alone |
+| `@johnmorrisdotca/dougu-sports/<group>/<name>` | One emblem, alone: `trophy/hockey-cup`, `medal/gold`, `crest/shield`, `sport/nhl`, `award/crown`, `ball/soccer`, `gear/<name>` |
 
 ### One emblem and nothing else
 
 ```js
-import { BALL_SOCCER } from "@johnmorrisdotca/dougu-sports/ball/soccer";
+import { TROPHY_HOCKEY_CUP } from "@johnmorrisdotca/dougu-sports/trophy/hockey-cup";
 
-console.log(BALL_SOCCER.id); // ball:soccer
-console.log(BALL_SOCCER.svg({ size: 24 }).includes('width="24"')); // true
+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 soccer ball and the small renderer for balls, 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 under 3 kB gzipped; `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 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 6.8 kB, a medal or a crest 3.6 kB, a cup 6.2 kB gzipped, most of that the renderer); `pnpm test:package` does the same from the packed tarball.
 
 ### In a page
 
@@ -132,7 +131,7 @@ A bundler that imports this module takes the soccer ball and the small renderer
 <span id="trophy"></span>
 <script type="module">
   import { renderEmblem } from "https://cdn.jsdelivr.net/npm/@johnmorrisdotca/dougu-sports@0/emblems";
-  document.getElementById("trophy").innerHTML = renderEmblem("award:medal", { size: 40 });
+  document.getElementById("trophy").innerHTML = renderEmblem("trophy:hockey-cup", { size: 40 });
 </script>
 ```
 
@@ -142,7 +141,7 @@ A bundler that imports this module takes the soccer ball and the small renderer
 import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
 import { writeFileSync } from "node:fs";
 
-writeFileSync("medal.svg", renderEmblem("award:medal", { size: 256, theme: "light" }));
+writeFileSync("cup.svg", renderEmblem("trophy:hockey-cup", { size: 256, theme: "light" }));
 ```
 
 ## Examples
@@ -154,10 +153,14 @@ An id is `<group>:<name>`. `renderEmblem` takes an id, or an id with a style aft
 ```js
 import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
 
-console.log(renderEmblem("award:medal/line") === renderEmblem("award:medal", { style: "line" })); // true
-console.log(renderEmblem("award:medal") === renderEmblem("award:medal", { style: "metal" })); // true
+console.log(renderEmblem("medal:gold/line") === renderEmblem("medal:gold", { style: "line" })); // true
+console.log(renderEmblem("medal:gold") === renderEmblem("medal:gold", { style: "metal" })); // true
+console.log(renderEmblem("cup") === renderEmblem("trophy:cup")); // true
+console.log(renderEmblem("gear:hurley").includes("<title>Hurley</title>")); // true
 ```
 
+A trophy or an award can also be written without its group: `"cup"` is `"trophy:cup"` and `"crown"` is `"award:crown"` (`EMBLEM_ALIASES` lists them).
+
 ### Tint an emblem in a team's colour
 
 ```js
@@ -168,16 +171,40 @@ console.log(svg.includes('fill="#0b6e4f"')); // true
 console.log(renderEmblem("ball:soccer", { tint: "not a colour" }) === renderEmblem("ball:soccer")); // true
 ```
 
-A tint is `#rgb`, `#rrggbb` or `rgb(r, g, b)`; anything else is ignored, so a colour that comes from outside cannot reach the markup.
+A tint is `#rgb`, `#rrggbb` or `rgb(r, g, b)`; anything else is ignored, so a colour that comes from outside cannot reach the markup. The `accent` option is a second colour in the same form: a medal's ribbon, a crest's band, a rosette's tails.
+
+### Draw a crest for a team with no logo
+
+```js
+import { crest } from "@johnmorrisdotca/dougu-sports/emblems";
+
+const svg = crest({ shape: "roundel", colors: ["#c8102e", "#f4f0e4"], initials: "no" });
+console.log(svg.includes(">NO<")); // true
+console.log(svg.includes("#c8102e") && svg.includes("#f4f0e4")); // true
+```
+
+A crest takes the team's colour and a second colour, and up to three letters, in the ink that reads on the colour; with no letters it has a star. `medal("gold")` and `sportIcon("nhl")` are the same kind of shortcut.
+
+### Draw balls at their true sizes
+
+```js
+import { emblemInfo, lineup } from "@johnmorrisdotca/dougu-sports/emblems";
+
+console.log(emblemInfo("ball:golf").size.diameterMm); // 42.67
+const svg = lineup(["ball:golf", "ball:tennis", "ball:soccer", "ball:puck"], { height: 80 });
+console.log(svg.includes("<title>Balls at their true relative sizes")); // true
+```
+
+Each ball carries the official size of the rulebook it is from (`emblemInfo(id).size`, with the rule), and `lineup` draws several side by side at the rules' relative sizes.
 
 ### Choose the outline for a theme
 
 ```js
 import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
 
-console.log(renderEmblem("award:medal", { theme: "dark" }).includes('color="#eef1f3"')); // true
-console.log(renderEmblem("award:medal", { theme: "light" }).includes('color="#20262d"')); // true
-console.log(renderEmblem("award:medal").includes(" color=")); // false
+console.log(renderEmblem("medal:gold", { theme: "dark" }).includes('color="#eef1f3"')); // true
+console.log(renderEmblem("medal:gold", { theme: "light" }).includes('color="#20262d"')); // true
+console.log(renderEmblem("medal:gold").includes(" color=")); // false
 ```
 
 ### Turn an emblem
@@ -186,7 +213,8 @@ console.log(renderEmblem("award:medal").includes(" color=")); // false
 import { ballFrame, emblemFrame } from "@johnmorrisdotca/dougu-sports/turn";
 import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
 
-console.log(emblemFrame("award:medal", { yaw: 0 }) === renderEmblem("award:medal")); // true
+console.log(emblemFrame("trophy:hockey-cup", { yaw: 0 }) === renderEmblem("trophy:hockey-cup")); // true
+console.log(emblemFrame("trophy:tennis-cup", { yaw: 90 }) === renderEmblem("trophy:tennis-cup")); // false
 console.log(ballFrame("ball:soccer", { yaw: 90 }) === ballFrame("ball:soccer", { yaw: 450 })); // true
 ```
 
@@ -197,8 +225,9 @@ More in [docs/turning.md](./docs/turning.md).
 ```js
 import { emblemInfo, emblemName } from "@johnmorrisdotca/dougu-sports";
 
-console.log(emblemInfo("award:medal").kind); // flat
-console.log(emblemName("award:medal", "ja")); // メダル
+console.log(emblemInfo("medal:gold").kind); // flat
+console.log(emblemInfo("trophy:hockey-cup").kind); // lathe
+console.log(emblemName("medal:gold", "ja")); // 金メダル
 ```
 
 ### List the emblems
@@ -223,46 +252,49 @@ console.log(parseEmblem("ball:nonesuch")); // undefined
 
 ### In React, Vue and the rest
 
-The functions return strings, so a framework puts them where it puts any markup: `dangerouslySetInnerHTML={{ __html: renderEmblem("award:medal") }}` in React, `v-html` in Vue, `{@html …}` in Svelte. The string holds no script and no external reference.
+The functions return strings, so a framework puts them where it puts any markup: `dangerouslySetInnerHTML={{ __html: renderEmblem("medal:gold") }}` in React, `v-html` in Vue, `{@html …}` in Svelte. The string holds no script and no external reference.
 
 ```ts no-check
-const Medal = () => <span dangerouslySetInnerHTML={{ __html: renderEmblem("award:medal", { size: 32 }) }} />;
+const Cup = () => <span dangerouslySetInnerHTML={{ __html: renderEmblem("trophy:hockey-cup", { size: 32 }) }} />;
 ```
 
 ## The emblems
 
-An emblem is a small object: `id`, `en` and `ja` names, a `source` (who drew it), a `kind`, the `model` it is drawn from, and two functions, `svg(options)` and `frame(options)`.
+An emblem is a small object: `id`, `en` and `ja` names, a `source` (who drew it), a `kind`, the `model` it is drawn from, and two functions, `svg(options)` and `frame(options)`. A ball or an implement also has a `size`, its official dimensions and the rule they are from.
 
 | Kind | What it is | A turn |
 | --- | --- | --- |
-| `flat` | A front and a back drawn from paths: a medal, a plaque, a rosette | Flips like a coin |
-| `ball` | Marks on a sphere: a ball | Rolls |
-| `lathe` | A body of revolution: a cup, a bowl, an urn | Keeps its outline, moves its light |
-| `icon` | One path | Is not turned |
-
-Only `flat` and `ball` exist so far; the others are named here because the art that is coming needs them.
+| `lathe` | A body of revolution: a cup, a bowl, an urn, a column with a ball or a globe on it, a stand with flat faces | Keeps its outline, and moves its light, its handles, its seams and its grooves |
+| `flat` | A front and a back drawn from shapes: a medal, a crest, a plaque, a rosette | Flips like a coin, thick at the rim as it goes edge on |
+| `ball` | A ball or an implement drawn in true 3D, with its panels, seams and marks on the surface | Rolls |
+| `icon` | One drawing: a Material Symbols icon or a sport's pictogram | Is not turned |
+| `gear` | A piece of equipment, a flat drawing | Is not turned |
 
 ### The groups
 
 | Group | What it holds | Folder |
 | --- | --- | --- |
-| `award` | Awards: a medal on a ribbon, a crown, a star, a badge | `src/emblems/award/` |
-| `trophy` | Cups, bowls, plaques, belts, wreaths | `src/emblems/award/` |
-| `medal` | Gold, silver and bronze, and the places | `src/emblems/award/` |
-| `crest` | Generic crests, tinted by a team's colour | `src/emblems/award/` |
-| `ball` | The ball of each sport | `src/emblems/ball/` |
-| `gear` | The gear of each sport: a stick, a racket, a helmet | `src/emblems/gear/` |
-| `sport` | An icon for the sport itself | `src/emblems/award/` |
+| `award` | Five awards from Material Symbols: a medal, a badge, a crown, a star, a shield | `src/emblems/award/` |
+| `trophy` | Twenty trophies: ten that stand for a league's cup in a generic form (a tall banded cup, a ring of pennants round a baseball, a football on a stand, a ball over a net, a wide two-handled bowl, a globe held up by spiral figures, a gilt dish, a lidded cup with a pineapple, an urn, a gilded cup), plain cups, bowls and dishes, a plaque, a belt, a wreath, a rosette | `src/emblems/trophy/` |
+| `medal` | Gold, silver and bronze medals on a ribbon of five stripes, and a badge for each of the first three places | `src/emblems/medal/` |
+| `crest` | Four generic crests, tinted by a team's colours, with its letters | `src/emblems/crest/` |
+| `ball` | 47 balls and implements, in 3D, each with its official size: soccer, basketball, baseball, tennis, rugby, the footballs, golf, the puck, the curling stone and the rest | `src/emblems/ball/` |
+| `gear` | 33 pieces of equipment: sticks, rackets, skates, a glove, a helmet, nets and posts, a javelin, starting blocks | `src/emblems/gear/` |
+| `sport` | One pictogram for each of the thirty-three sports | `src/emblems/sport/` |
 
-The thirty-three sports the ball, gear and sport emblems are made for are `SPORT_NAMES`: NFL, CFL, IFAF, NHL, NBA, MLB, soccer, curling, tennis, volleyball, badminton, pickleball, table tennis, padel, squash, racquetball, sepak takraw, teqball, roundnet, netball, swimming, water polo, diving, artistic swimming, lacrosse, rugby, Australian football, Gaelic games, cricket, field hockey, handball, athletics and skating.
+The thirty-three sports the ball, gear and sport emblems are made for are `SPORT_NAMES`: NFL, CFL, IFAF, NHL, NBA, MLB, soccer, curling, tennis, volleyball, badminton, pickleball, table tennis, padel, squash, racquetball, sepak takraw, teqball, roundnet, netball, swimming, water polo, diving, artistic swimming, lacrosse, rugby, Australian football, Gaelic games, cricket, field hockey, handball, athletics and skating. How the trophies are drawn, and what each stands for, is in [docs/emblems.md](./docs/emblems.md); the balls and the gear are described in [src/emblems/README.md](./src/emblems/README.md).
 
 ## API
 
 | Function or value | What it does |
 | --- | --- |
-| `renderEmblem(ref, options?)` | An emblem as SVG. `ref` is an id, an id with a style (`"award:medal/line"`), or an emblem |
+| `renderEmblem(ref, options?)` | An emblem as SVG. `ref` is an id, an id with a style (`"medal:gold/line"`), or an emblem |
 | `emblemSvg` | The same as `renderEmblem` |
-| `emblemFrame(ref, options?)` | An emblem turned by `yaw` and `pitch` degrees |
+| `crest(options?)` | A crest by shape, colours and letters |
+| `medal(kind, options?)` | A gold, silver or bronze medal on its ribbon |
+| `sportIcon(sport, options?)` | The pictogram of a sport, by the names of `SPORT_NAMES`; an unknown sport is an error |
+| `lineup(ids, options?)` | Several balls side by side, at their true relative sizes (or all as large as the largest) |
+| `emblemFrame(ref, options?)` | An emblem turned by `yaw` and `pitch` degrees (and `roll` for a ball) |
 | `ballFrame(id, options?)` | A ball rolled; an id that is not a ball is an error |
 | `parseEmblem(value)` | The id and style a string names, or `undefined` |
 | `isEmblemId(value)`, `isBallId(value)` | Whether a value is the id of an emblem, or of a ball |
@@ -270,9 +302,10 @@ The thirty-three sports the ball, gear and sport emblems are made for are `SPORT
 | `emblemInfo(id)`, `emblemName(id, language?)`, `emblemModel(id)` | What an emblem is: its names, kind and source, and the data it is drawn from |
 | `EMBLEMS` | Every emblem as markup in the metal style at 64 pixels, by id |
 | `EMBLEM_TABLE` | Every emblem object, by id |
-| `AWARD_MEDAL`, `BALL_SOCCER` | The two emblems so far, as constants |
-| `EMBLEM_IDS`, `EMBLEM_GROUPS`, `EMBLEM_FOLDERS` | Every id, the groups, and the folder of each group's art |
+| `TROPHY_HOCKEY_CUP`, `MEDAL_GOLD`, `CREST_SHIELD`, `SPORT_NHL`, `BALL_SOCCER`, `GEAR_HURLEY`... | Each emblem as a constant, named by its id in capitals (`trophy:hockey-cup`); [docs/gallery.md](./docs/gallery.md) lists every constant with its id and the module that takes it alone |
+| `EMBLEM_IDS`, `EMBLEM_GROUPS`, `EMBLEM_FOLDERS`, `EMBLEM_ALIASES` | Every id, the groups, the folder of each group's art, and the short names (`cup` for `trophy:cup`) |
 | `AWARD_IDS`, `TROPHY_IDS`, `MEDAL_IDS`, `CREST_IDS`, `BALL_IDS`, `GEAR_IDS`, `SPORT_IDS` | The ids of each group |
+| `MEDAL_KINDS`, `CREST_SHAPES` | The kinds of medal, and the shapes of crest |
 | `SPORT_NAMES` | The thirty-three sports |
 | `EMBLEM_STYLES`, `EMBLEM_INK`, `EMBLEM_PAGE`, `METALS` | The styles, the ink and page colours the themes use, and the metals |
 | `VERSION` | The package's version |
@@ -284,38 +317,42 @@ The thirty-three sports the ball, gear and sport emblems are made for are `SPORT
 | `style` | `"metal"`, `"line"`, `"color"` | `"metal"` |
 | `size` | A number of pixels, 4096 at most | `64` |
 | `tint` | `#rgb`, `#rrggbb` or `rgb(r, g, b)` | the emblem's own colour |
+| `accent` | `#rgb`, `#rrggbb` or `rgb(r, g, b)` | the emblem's second colour (a ribbon, a band, pennants) |
+| `initials` | Up to three letters (a crest only) | none: the crest has a star |
 | `theme` | `"inherit"`, `"auto"`, `"light"`, `"dark"` | `"inherit"` |
-| `yaw`, `pitch` (turning only) | Degrees from the resting view | `0` |
+| `grain` | `true` or `false` (a ball only) | on for a ball of 48 pixels or more that is not turning |
+| `yaw`, `pitch`, `roll` (turning only; `roll` for a ball) | Degrees from the resting view | `0` |
 
-The types are `EmblemId`, `EmblemRef`, `EmblemOptions`, `FrameOptions`, `EmblemStyle`, `EmblemTheme`, `Emblem`, `EmblemInfo`, `EmblemKind`, `EmblemSource`, `EmblemGroup`, `SportName`, and the id types of each group.
+The types are `EmblemId`, `EmblemRef`, `EmblemOptions`, `FrameOptions`, `EmblemStyle`, `EmblemTheme`, `Emblem`, `EmblemInfo`, `EmblemKind`, `EmblemSource`, `EmblemGroup`, `CrestOptions`, `CrestShape`, `MedalKind`, `LineupOptions`, `PieceSize`, `SportName`, the id types of each group, and the types of the models the emblems are drawn from (`LatheModel`, `FlatModel`, `MaterialModel` and their parts).
 
 ## Theming
 
-Every emblem is drawn with its outline in `currentColor`, so it takes the colour of the text around it. The `theme` option changes that when the SVG is used where it cannot inherit (an `<img>`, a data address):
+In the `metal` and `color` styles a trophy, a medal or a crest is edged by a darker tone of its own metal, so it needs nothing from the page and looks the same on a light page and on a dark one. In the `line` style (and in a pictogram, which is a drawing in ink) the drawing is `currentColor`, so it takes the colour of the text around it. The `theme` option changes that when the SVG is used where it cannot inherit (an `<img>`, a data address):
 
-| `theme` | The outline |
+| `theme` | The ink |
 | --- | --- |
 | `inherit` | The page's text colour (`currentColor`): the default for markup put in a page |
 | `auto` | Dark ink on a light device and pale ink on a dark one, by `prefers-color-scheme` |
 | `light` | `#20262d`, made to read on `#ffffff` |
 | `dark` | `#eef1f3`, made to read on `#14181c` |
 
-The metals are `METALS` (gold `#d9a620`, silver `#aeb6c0`, bronze `#b8733a`). The `line` style has no fill, so it takes only the outline's colour.
+The metals are `METALS` (gold `#d9a620`, silver `#aeb6c0`, bronze `#b8733a`); each is shaded with a dark edge, a bright band, the metal, a darker side and a faint light from the rim, which holds on both pages. The `line` style has no fill, so it takes only the ink. For a ball and a piece of gear, `color` is the same shaded drawing as `metal`.
 
 ## Limits
 
-- Two sample emblems exist so far; the rest of the art is on its way (see the status note above).
-- A turn is drawn in plain SVG, not in 3D: a flat emblem is squeezed, and a ball's patches are projected points, not a lit mesh. A patch round a ball's edge is flattened against it rather than clipped to the sphere.
-- A tint is one colour. A second colour (a ribbon, a crest's band) is not an option yet.
+- A turn is drawn in plain SVG, not in 3D: a cup keeps its silhouette and moves its light, handles and seams; a medal is squeezed; a ball is projected from its own geometry, panel by panel, and has no grain while it turns. Gear and pictograms are not turned.
+- A tint is one colour, the main one, and an accent a second. The pieces of a trophy that are another metal (the gilt of a plate, the green bands of a globe, the black foot of a cup) keep their own colour.
+- The trophies are generic: each is drawn for this package in a simplified form that a reader knows at a glance, and none is traced from a photograph or carries a name, a mark or an engraving.
+- A trophy in the metal style is about 3 to 4.5 kB of markup, a medal or a crest about 1 to 2 kB, a line drawing about 1 to 2.5 kB; a ball in 3D is 5 to 13 kB, and some gear is as large, because it is copied from detailed artwork.
 - The size is a number of pixels up to 4096; the drawing is a vector at any size.
 - No emblem carries a real league's, team's or federation's mark.
 
 ## Accessibility
 
-- Every emblem is `role="img"` with a `<title>` that names it in English ("Medal", "Soccer ball"). `emblemName(id, "ja")` gives the Japanese name for a caller that writes its own label.
+- Every emblem is `role="img"` with a `<title>` that names it in English ("Gold medal", "Soccer ball"). `emblemName(id, "ja")` gives the Japanese name for a caller that writes its own label.
 - Where an emblem is only decoration next to text that says the same, hide it from a screen reader with `aria-hidden="true"` on the element that holds it.
 - Colour is never the only carrier of meaning: the `line` style has no colour at all.
-- The outline reads at 4.5 to 1 against the page the `light` and `dark` themes name; the tests hold the pair.
+- The ink reads at 4.5 to 1 against the page the `light` and `dark` themes name, and a crest's letters read at 4.5 to 1 on the crest's colour, whatever the colour; the tests hold both.
 - Nothing moves by itself: turning happens when the caller asks for a frame, and the demo's sliders are 44 pixels tall.
 
 ## Browser and runtime support
@@ -328,14 +365,12 @@ The package's own words are the emblems' names, in English (`en`) and Japanese (
 
 ## Roadmap
 
-- The art: trophies, medals, crests, then the ball and the gear of each of the 33 sports, group by group.
-- Bodies of revolution (`lathe`), so a cup turns with its outline kept.
-- A second colour as an option.
+- Native review of the Japanese names, and more pictograms and gear where a sport has none yet.
 - Deliberately not: logos of real leagues and teams, a canvas or WebGL renderer, and a runtime dependency.
 
 ## Architecture
 
-The code is `src/emblems/`: the core (options, colours, the wrapper), the id lists, the registry, the two renderers (flat and ball) and one module per emblem; [docs/layout.md](./docs/layout.md) has the folders and how to add one. The package has no state and no clock: every function is a pure function of its arguments.
+The code is `src/emblems/`: the core (options, colours, gradients, the wrapper), the id lists, the registry, the renderers (the body of revolution, the flat object and icon, the Material icon, and the ball and gear engines) and one module per emblem, or per family of balls and gear, in a folder for its group; [docs/layout.md](./docs/layout.md) has the folders and how to add one. The package has no state and no clock: every function is a pure function of its arguments.
 
 ## The name
 
@@ -343,11 +378,11 @@ Dougu (道具, *dōgu*, どうぐ) is Japanese for a tool or a piece of equipmen
 
 ## Where it comes from, and where it is used
 
-The emblems are drawn for this package or made from the open sources listed in [NOTICE.md](./NOTICE.md), each with its licence in [LICENSES/](./LICENSES/). It is made for [spxn.com](https://spxn.com), the historical record of the NHL, NBA, MLB, NFL and CFL, and for the other packages of the family that draw sport.
+The emblems are drawn for this package or made from the open sources listed in [NOTICE.md](./NOTICE.md), each with its licence in [LICENSES/](./LICENSES/): sixteen icons are Material Symbols (Apache 2.0), fetched at a pinned commit by `scripts/fetch-material-symbols.mjs`; some gear is copied from Noto Emoji, Wikimedia Commons and game-icons.net, with its credit; everything else is drawn here, and the rulebooks the balls' sizes were read from are in [docs/references.md](./docs/references.md). It is made for [spxn.com](https://spxn.com), the historical record of the NHL, NBA, MLB, NFL and CFL, and for the other packages of the family that draw sport.
 
 ### Used by
 
-[Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) draws the same kind of emblems today, inside itself; they move here, and Kyogijo then imports them.
+[Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) drew the same kind of emblems inside itself; they moved here, redrawn, and Kyogijo then imports them.
 
 ### The family
 
@@ -381,7 +416,7 @@ Dougu Sports is one of twenty-seven packages, each made for the same site, each
 - [Houseki](https://github.com/johnmorrisdotca/houseki) (宝石): gem and stone matching puzzles: falling triplets, stone collapse, colour chains and gem swap. [Demo](https://johnmorrisdotca.github.io/houseki/).
 - [Kyogijo Stadiums](https://github.com/johnmorrisdotca/kyogijo-stadiums) (競技場): sports fields, rinks, courts and ballparks drawn to scale as SVG, with each team and the score on them. [Demo](https://johnmorrisdotca.github.io/kyogijo-stadiums/).
 - [Taisen Brackets](https://github.com/johnmorrisdotca/taisen-brackets) (対戦): a sport-agnostic tournament bracket, drawn as SVG, from a list of ties. [Demo](https://johnmorrisdotca.github.io/taisen-brackets/).
-- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/). Not on npm yet.
+- [Dougu Sports](https://github.com/johnmorrisdotca/dougu-sports) (道具): sports emblems as SVG: trophies, medals, crests, and the ball and gear of every sport, with optional 3D turning. [Demo](https://johnmorrisdotca.github.io/dougu-sports/).
 
 **This package is Dougu Sports.** The demos of all twenty-seven share one header and footer, so each links the rest.
 <!-- family:end -->
@@ -405,7 +440,7 @@ Bug reports and ideas go in the [issues](https://github.com/johnmorrisdotca/doug
 
 ## Changes
 
-See [CHANGELOG.md](./CHANGELOG.md). 0.0.1 is the first preview: the name, the API and two sample emblems; the full set follows.
+See [CHANGELOG.md](./CHANGELOG.md). 0.1.0 brings the full set of 148 emblems; 0.0.1 was the first preview.
 
 ## Credits
 

package/dist/emblems/award/badge.d.ts

@@ -0,0 +1,2 @@
+/** Award badge. */
+export declare const AWARD_BADGE: import("../emblem.core.ts").Emblem<import("../emblem.material.ts").MaterialModel>;

package/dist/emblems/award/badge.js

@@ -0,0 +1,5 @@
+// Award badge: the Material Symbols icon `workspace_premium` (Google, Apache License 2.0; see NOTICE.md), in metal, line and flat colour.
+import { M_WORKSPACE_PREMIUM } from "../emblem.material.data.js";
+import { defineMaterial } from "../emblem.material.js";
+/** Award badge. */
+export const AWARD_BADGE = /* @__PURE__ */ defineMaterial("award:badge", "Award badge", "表彰バッジ", M_WORKSPACE_PREMIUM, "gold");

package/dist/emblems/award/crown.d.ts

@@ -0,0 +1,2 @@
+/** Crown. */
+export declare const AWARD_CROWN: import("../emblem.core.ts").Emblem<import("../emblem.material.ts").MaterialModel>;

package/dist/emblems/award/crown.js

@@ -0,0 +1,5 @@
+// Crown: the Material Symbols icon `crown` (Google, Apache License 2.0; see NOTICE.md), in metal, line and flat colour.
+import { M_CROWN } from "../emblem.material.data.js";
+import { defineMaterial } from "../emblem.material.js";
+/** Crown. */
+export const AWARD_CROWN = /* @__PURE__ */ defineMaterial("award:crown", "Crown", "王冠", M_CROWN, "gold");

package/dist/emblems/award/medal.d.ts

@@ -1,2 +1,2 @@
-/** A medal on a ribbon. Turned, it flips like a coin and shows its plain back. */
-export declare const AWARD_MEDAL: import("../emblem.core.ts").Emblem<import("../emblem.shapes.ts").FlatModel>;
+/** Medal. */
+export declare const AWARD_MEDAL: import("../emblem.core.ts").Emblem<import("../emblem.material.ts").MaterialModel>;

package/dist/emblems/award/medal.js

@@ -1,19 +1,5 @@
-// The medal on a ribbon: a gold disc with a star on its face and a plain back, on two crossed straps. Drawn for this package. A sample of the award area (see docs/layout.md).
-import { circlePath, defineFlat, starPath } from "../emblem.shapes.js";
-/** A medal on a ribbon. Turned, it flips like a coin and shows its plain back. */
-export const AWARD_MEDAL = /* @__PURE__ */ defineFlat("award:medal", "Medal", "メダル", "ours", {
-    metal: "gold",
-    front: [
-        { part: "ribbon", d: "M17 3H29L39 31H28Z" },
-        { part: "ribbon", d: "M47 3H35L25 31H36Z" },
-        { part: "main", d: circlePath(32, 42, 17) },
-        { part: "detail", d: circlePath(32, 42, 12.5) },
-        { part: "main", d: starPath(32, 42, 8.6, 3.6) },
-    ],
-    back: [
-        { part: "ribbon", d: "M17 3H29L39 31H28Z" },
-        { part: "ribbon", d: "M47 3H35L25 31H36Z" },
-        { part: "main", d: circlePath(32, 42, 17) },
-        { part: "detail", d: circlePath(32, 42, 12.5) },
-    ],
-});
+// Medal: the Material Symbols icon `military_tech` (Google, Apache License 2.0; see NOTICE.md), in metal, line and flat colour.
+import { M_MILITARY_TECH } from "../emblem.material.data.js";
+import { defineMaterial } from "../emblem.material.js";
+/** Medal. */
+export const AWARD_MEDAL = /* @__PURE__ */ defineMaterial("award:medal", "Medal", "メダル", M_MILITARY_TECH, "gold");

package/dist/emblems/award/shield.d.ts

@@ -0,0 +1,2 @@
+/** Shield. */
+export declare const AWARD_SHIELD: import("../emblem.core.ts").Emblem<import("../emblem.material.ts").MaterialModel>;

package/dist/emblems/award/shield.js

@@ -0,0 +1,5 @@
+// Shield: the Material Symbols icon `shield` (Google, Apache License 2.0; see NOTICE.md), in metal, line and flat colour.
+import { M_SHIELD } from "../emblem.material.data.js";
+import { defineMaterial } from "../emblem.material.js";
+/** Shield. */
+export const AWARD_SHIELD = /* @__PURE__ */ defineMaterial("award:shield", "Shield", "盾", M_SHIELD, "silver");

package/dist/emblems/award/star.d.ts

@@ -0,0 +1,2 @@
+/** Star. */
+export declare const AWARD_STAR: import("../emblem.core.ts").Emblem<import("../emblem.material.ts").MaterialModel>;

package/dist/emblems/award/star.js

@@ -0,0 +1,5 @@
+// Star: the Material Symbols icon `star` (Google, Apache License 2.0; see NOTICE.md), in metal, line and flat colour.
+import { M_STAR } from "../emblem.material.data.js";
+import { defineMaterial } from "../emblem.material.js";
+/** Star. */
+export const AWARD_STAR = /* @__PURE__ */ defineMaterial("award:star", "Star", "星", M_STAR, "gold");

package/dist/emblems/ball/ball.afl.d.ts

@@ -0,0 +1 @@
+export declare const BALL_AFL: import("./ball.core.ts").Piece<import("./ball.engine.ts").BallSpec>;

package/dist/emblems/ball/ball.afl.js

@@ -0,0 +1,24 @@
+// Australian football: a red leather ball, rounder than an American one, with four panels whose seams are sewn with white stitches.
+import { defineBall } from "./ball.engine.js";
+import { footballSeams } from "./ball.family.prolate.js";
+import { stitches } from "./ball.stitch.js";
+import { mix } from "./ball.core.js";
+export const BALL_AFL = /* @__PURE__ */ defineBall({
+    id: "ball:afl",
+    en: "Australian football",
+    ja: "オーストラリアンフットボールのボール",
+    size: { extentMm: 280, lengthMm: 280, circumferenceMm: 550.0, longCircumferenceMm: 725.0, rule: "Laws of Australian Football 2026, Law 4 The Football, 4.1 Specifications", note: "The Laws give the two circumferences (720-730 mm and 545-555 mm) and no length: 280 mm is the length of an ellipse of those two girths." },
+    spec: {
+        axes: [1, 0.7, 0.7],
+        view: { yaw: -30, pitch: 20, roll: -25 },
+        base: "#b4202b",
+        mat: { gloss: 0.55, shade: "#2a0408", grain: { f: 1.0, a: 0.34 } },
+        draw: (s, base) => {
+            const seams = footballSeams(Math.PI / 4);
+            let out = s.strokes(seams, mix(base, -0.5), 1.1, { closed: true });
+            for (const seam of seams)
+                out += s.strokes(stitches(seam, true, 46, 0.045, { lean: 0.0 }), "#f4efe4", 0.8, { ink: false });
+            return out;
+        },
+    },
+});

package/dist/emblems/ball/ball.baseball.d.ts

@@ -0,0 +1 @@
+export declare const BALL_BASEBALL: import("./ball.core.ts").Piece<import("./ball.engine.ts").BallSpec>;

package/dist/emblems/ball/ball.baseball.js

@@ -0,0 +1,14 @@
+// Baseball: a white leather ball with 108 red double stitches in V's along the figure-eight seam.
+import { seamedBall } from "./ball.family.seamed.js";
+export const BALL_BASEBALL = /* @__PURE__ */ seamedBall({
+    id: "ball:baseball",
+    en: "Baseball",
+    ja: "野球のボール",
+    size: { extentMm: 73.8, diameterMm: 73.8, circumferenceMm: 231.77, massG: [141.75, 148.83], rule: "Official Baseball Rules, Rule 3.01 The Ball", note: "Diameter worked out from the middle of the circumference range." },
+    base: "#f4f0e6",
+    b: 0.4,
+    view: { yaw: 18, pitch: 28, roll: -10 },
+    mat: { gloss: 0.3, shade: "#4a3a2a", grain: { f: 1.4, a: 0.12 } },
+    groove: "#8a7a62",
+    stitch: { colour: "#c4262e", count: 108, half: 0.075, width: 0.85, lean: 0.032 },
+});

package/dist/emblems/ball/ball.basketball.d.ts

@@ -0,0 +1,7 @@
+import { type BallSpec } from "./ball.engine.ts";
+import type { V3 } from "./ball.math.ts";
+/** One side channel: the wave above the equator for `sign` 1 and below it for -1. */
+export declare const basketballChannel: (sign: 1 | -1, n?: number) => V3[];
+/** The spec of a basketball: its colour, and the colour of its lower half for a two-tone ball. */
+export declare function basketballSpec(base: string, lower?: string): BallSpec;
+export declare const BALL_BASKETBALL: import("./ball.core.ts").Piece<BallSpec>;

package/dist/emblems/ball/ball.basketball.js

@@ -0,0 +1,32 @@
+// The basketball: an orange sphere with the equator, the meridian and the two curved side channels. The channels are the curves latitude = +-(0.304 + 0.585 sin^2 longitude) round the ball,
+// each crossing the meridian square on and swinging away from the equator toward both sides; the constants were fitted to a photograph and a drawing of a generic ball (a least-squares
+// match of 1,766 seam pixels), not copied from either. FIBA allows at most 12 seams of at most 6.35 mm; this ball has the four channels of the usual pattern.
+import { defineBall } from "./ball.engine.js";
+import { greatCircle, lonLat, smallCircle } from "./ball.math.js";
+import { mix } from "./ball.core.js";
+const L0 = 0.304;
+const AMP = 0.585;
+/** One side channel: the wave above the equator for `sign` 1 and below it for -1. */
+export const basketballChannel = (sign, n = 72) => Array.from({ length: n }, (_, i) => {
+    const lon = (i / n) * 2 * Math.PI;
+    return lonLat(lon, sign * (L0 + AMP * Math.sin(lon) ** 2));
+});
+/** The spec of a basketball: its colour, and the colour of its lower half for a two-tone ball. */
+export function basketballSpec(base, lower) {
+    return {
+        view: { yaw: 46.8, pitch: -13.5, roll: 183.6 },
+        base,
+        mat: { gloss: 0.5, shade: "#4a1c06", grain: { f: 1.1, a: 0.32 } },
+        draw(s, colour) {
+            const ink = mix(colour, -0.88);
+            let out = "";
+            if (lower !== undefined)
+                out += s.panel(smallCircle([0, -1, 0], 1.545, 72), lower, { n: 1, ink: false });
+            const curves = [greatCircle([0, 1, 0], 72), greatCircle([1, 0, 0], 72), basketballChannel(1), basketballChannel(-1)];
+            out += s.strokes(curves, ink, 2.0, { closed: true });
+            return out;
+        },
+    };
+}
+const SIZE7 = { extentMm: 241.9, diameterMm: 241.9, circumferenceMm: 760.0, massG: [580, 620], rule: "FIBA Basketball Equipment 2026, Rule 2 Basketballs, 2.4 and Table 1 (size 7 = men's competitions)", note: "Diameter worked out from the middle of the circumference range." };
+export const BALL_BASKETBALL = /* @__PURE__ */ defineBall({ id: "ball:basketball", en: "Basketball", ja: "バスケットボール", size: SIZE7, spec: basketballSpec("#e0701f") });

package/dist/emblems/ball/ball.basketball3x3.d.ts

@@ -0,0 +1 @@
+export declare const BALL_BASKETBALL_3X3: import("./ball.core.ts").Piece<import("./ball.engine.ts").BallSpec>;

package/dist/emblems/ball/ball.basketball3x3.js

@@ -0,0 +1,10 @@
+// The 3x3 basketball: two-tone, orange above and charcoal below, the size of a 6 and the weight of a 7. Our own two-tone scheme; the rules fix the size and the weight.
+import { defineBall } from "./ball.engine.js";
+import { basketballSpec } from "./ball.basketball.js";
+export const BALL_BASKETBALL_3X3 = /* @__PURE__ */ defineBall({
+    id: "ball:basketball-3x3",
+    en: "Basketball, 3x3",
+    ja: "3x3バスケットボール",
+    size: { extentMm: 232.4, diameterMm: 232.4, circumferenceMm: 730.0, massG: [580, 620], rule: "FIBA 3x3 Official Equipment & Software Appendix to the 3x3 Official Rules (Dec 2024 update), Table 1 and section 5.7 (as quoted by balls.com)", note: "Not read in the FIBA 3x3 equipment appendix itself (fiba3x3.com refused the request); the figures are those a ball retailer prints from it: the circumference of a size 6 with the weight of a size 7. Diameter worked out from the middle of the circumference range." },
+    spec: basketballSpec("#e0701f", "#2b2d33"),
+});