@johnmorrisdotca/kumimoji 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -6,6 +6,41 @@ All notable changes to this project are written down here. The format follows
 
 ## [Unreleased]
 
+## [1.3.0] - 2026-10-14
+
+The table is a custom element with the family's standard embed attributes and a shared builder, and the package has an English and Japanese documentation site with a checked example for every export. The rules, generation, seeds and saved games are unchanged.
+
+### Added
+
+- Add the bilingual documentation site, checked public examples, paired guides, local search and machine-readable pages.
+- Add the shared crossword-table builder and validated iframe route with reflected settings and display options. Preserve native saved/table access and gameplay methods; presentation updates now retain play.
+- Add native ready/set, optional initial saved state, control visibility and localized load failures, forwarded by the React wrapper. Preserve event shapes with composed JSON-safe snapshots and add load/error events.
+- Share a package-independent embed builder for option controls, preview adapters, code tabs and shareable links.
+
+### Changed
+
+- Synchronize documentation tooling for repository layouts, generated type references, Node entry points and repository-specific README links.
+- Keep large documentation resource catalogues on the entry index and the active resource beside core navigation, preserving every reference page; render valid default imports in HTML and Markdown.
+- The props table of `KumimojiBoard` moved from the README to `docs/react.md`, so that the README, which now lists the sports packages too, stays under npm's 65,536 characters; the README keeps a summary and a link.
+- Group the package family by kind, alphabetize each group, and include the geography packages and REST in Pieces in the shared footer and README.
+- Update the shared family description for addresses in all seven supported countries, including France and Germany.
+
+## [1.2.2] - 2026-10-06
+
+Nothing that was exported has changed.
+
+### Changed
+
+- The README takes the family's one layout, fully: a hero picture of the demo on a desk and on a phone in light and dark, a picture of each kind of table (English, kana, a run that is not a word, a hand of eleven, a wild tile), an Examples section of ten examples whose output is what they print, an Install section, and a short list of the calls to learn first. Its pictures are in `docs/images` (WebP, light and dark) and are retaken with `pnpm screenshots:readme` (it replaces `pnpm pictures` and the two JPEGs `docs/desktop.jpg` and `docs/phone.jpg`); they are not in the tarball, and `pnpm test:package` fails if one is.
+- To keep the README under the 64,000 characters npm can show, the long tables of exports (dealing and judging, tiles and grids, playing, the table of players, looking at the table) and the table's, the element's and the React components' options moved to `docs/API.md`, and the source tree moved to `docs/ARCHITECTURE.md`, each with a summary and a link left in the README. Nothing was removed, and the tests that hold these tables to the code read the README and `docs/API.md` together.
+- `pnpm test:readme` type-checks and runs every TypeScript and JavaScript example in the README against the built package, as a CI job of its own, and `pnpm check` holds the README to the family's lint.
+- "The command line" says there is none, and now sits after the languages, where the other sections of the standard's order leave room for it.
+- Repository only: the package and everything it exports are unchanged. `CONTRIBUTING.md` is the family's one text with a section of its own for Kumimoji, held to the master in johnmorrisdotca/.github by `src/family.test.js`; `ci.yml` and `pages.yml` are the family's one text (`pnpm check`, the demo, and the package on Linux, macOS and Windows), and any jobs of the package's own after them.
+
+### Fixed
+
+- The API reference page wraps a long entry path instead of running about 2 px wider than a 360 px screen. Nothing the package exports has changed.
+
 ## [1.2.1] - 2026-10-05
 
 Nothing that was exported has changed.
@@ -141,7 +176,8 @@ The first release.
   `@johnmorrisdotca/kumimoji/react`.
 - A static demo for GitHub Pages.
 
-[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.1...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.3.0...HEAD
+[1.3.0]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.2...v1.3.0
 [1.2.1]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.2.0...v1.2.1
 [1.1.1]: https://github.com/johnmorrisdotca/kumimoji/compare/v1.1.0...v1.1.1
 [1.1.0]: https://github.com/johnmorrisdotca/kumimoji/releases/tag/v1.1.0

package/CONTRIBUTING.md

@@ -1,28 +1,100 @@
-# Contributing to Kumimoji
+# Contributing
 
-Thank you for helping. Bug reports, rule questions, corrections to the
-Japanese and pull requests are all welcome.
+Thank you for helping. Bug reports, ideas, corrections to the Japanese and pull
+requests are all welcome.
 
-## Reporting a bug
+This first part is the same in every package of the family. It is the master
+text kept in
+[johnmorrisdotca/.github](https://github.com/johnmorrisdotca/.github/blob/main/CONTRIBUTING.md),
+copied unchanged into `scripts/community/CONTRIBUTING.md`, and a test holds
+this file to that copy. What is particular to the package follows it, under
+the heading "Particular to" and the package's name.
+
+## Before you start
+
+Open an issue first for anything bigger than a typo, so that we can agree on the
+shape before you spend time on it. Taking part follows the
+[Code of Conduct](CODE_OF_CONDUCT.md); report a security concern privately, as
+[SECURITY.md](SECURITY.md) says.
+
+## Making a change
+
+```sh
+pnpm install
+pnpm check          # lint, types and tests: the same as CI
+pnpm test:package   # pack it as npm does, install it in an empty project, import every entry
+pnpm site           # build the demo into ./site, as GitHub Pages publishes it
+```
+
+The package's own further commands (its browser tests, its command line, its
+data scripts) are listed under its own heading below.
+
+## House rules, shared by every package of the family
+
+- **No runtime dependencies.** Development dependencies are for tests, builds and
+  documentation only.
+- **The core is pure.** Every function in it returns new values and never
+  changes what it was given.
+- **Test what you change.** Tests sit beside the code they test. A rule you
+  change has a test that would have caught it.
+- **Words a person reads come in English and Japanese.** If you cannot write the
+  Japanese, say so in the pull request and someone will.
+- **Option values and names are kebab case.**
+- **Art and sound are CC0 or public domain only**, checked at the source and
+  credited. Data and word lists may be under another licence that lets them be
+  shipped, with its notice kept in `NOTICE.md`. No GPL or LGPL code.
+- **Needs Node 22 or later.**
+- **A README table, example or count that a test holds to the code** changes
+  together with the code.
+- **The family's own files are the same in every package**: `demo/family.css`,
+  `scripts/family-template.mjs`, `scripts/family-readme.mjs`,
+  `scripts/release-notes.mjs`, the files in `scripts/community/` and
+  `family.test.js` (in `src/`, or in `test/`). Do not edit one here. To change
+  one, change it in every repository at once, bump `FAMILY_TEMPLATE_VERSION` for
+  the template, and record the new hash in `family.test.js`. What is the
+  package's own goes in its own stylesheet, `demo/<name>.css`, and its page
+  builder, `scripts/site.mjs`.
+- **The list of the family in the README is made, not written.**
+  `pnpm family:readme` writes it between its markers from
+  `scripts/family-template.mjs`.
+- **The workflows are the family's too.** `ci.yml` runs `pnpm check`, the demo's
+  browser tests and the packed package on Linux, macOS and Windows; `pages.yml`
+  is the same text in every package. A package adds jobs of its own after those.
+
+## Pull requests
+
+One change per pull request. Say what changed and how you checked it, and add a
+line to `CHANGELOG.md` under **Unreleased**: for a change a user would notice,
+and for one to the repository alone.
+
+## Releasing
+
+Maintainers bump the version in `package.json` (and in `src/version.ts`, where
+the package has one), move *Unreleased* to the new version in `CHANGELOG.md`,
+dated, push, wait for CI and tag `vX.Y.Z`, the same as `package.json`'s version.
+The Release workflow (`.github/workflows/release.yml`) checks and builds the
+package, attaches the tarball to a GitHub release and publishes it to npm by
+trusted publishing, with provenance and no token. A version already on npm is
+not published again.
+
+## Particular to Kumimoji
+
+### Reporting a bug
 
 Open an [issue](https://github.com/johnmorrisdotca/kumimoji/issues/new?template=report-a-bug.md)
 with what you did, what you expected and what happened. A seed deals the same
 bag every time, so the table's *Save as JSON* file, or the seed with the
 language, hand and level, makes almost any bug reproducible.
 
-## Making a change
+### Commands and rules
 
 ```sh
-git clone https://github.com/johnmorrisdotca/kumimoji
-cd kumimoji
-pnpm install
 pnpm check            # lint, types and tests: the same as CI
 pnpm test:table       # the demo in real browsers: builds it, then taps it
 pnpm test:package     # npm pack, install the tarball, import and require every entry, read both lists
 pnpm test:frameworks  # the README's examples built in React, Vue, Svelte, Angular and a plain page
 pnpm site             # builds the demo into ./site
 pnpm pictures         # re-takes the README's two pictures from the built demo
-pnpm dlx serve site   # or any static server
 ```
 
 - **The rules are pure.** Everything outside `src/ui` and `src/react.tsx` is
@@ -44,7 +116,6 @@ pnpm dlx serve site   # or any static server
 - **How the lists load is not to be changed lightly.** They are fetched by a
   dynamic import behind `typeof window`, so that a page's server code never
   carries them; Itsutsu relies on it.
-- **Test what you change.** Tests sit beside their source as `*.test.ts`.
 - **The table is tested by tapping it.** `table/*.table.mjs` are Playwright
   tests that open the built demo in Chromium and WebKit, at a phone's width by
   touch and at a desktop's by mouse, and do what a person does. After every
@@ -61,38 +132,4 @@ pnpm dlx serve site   # or any static server
   each from the packed tarball and lays a tile.
 - **Every export gets a doc comment**, which a test holds, and the README's
   tables (options, theming, limits) are checked against the code.
-- **The demo wears the family's look.** `demo/family.css` is the same file in
-  every sibling package's demo, and a test fails if it differs from its
-  recorded hash. What is Kumimoji's own goes in `demo/kumimoji.css`.
-- **No dependencies.** The package has none at run time and should stay so.
 - **No name, art or wording of a published game.**
-- One change per pull request, with a line in `CHANGELOG.md` under
-  *Unreleased*.
-
-## House rules, shared by every package of the family
-
-- Open an issue first for anything bigger than a typo, so that we can agree on the shape before you spend time on it.
-- No runtime dependencies. Every function that plays or checks a game is pure: it returns new values and never changes what it was given.
-- Tests sit beside the code they test. A rule you change has a test that would have caught it.
-- Words a player reads come in English and Japanese. If you cannot write the Japanese, say so in the pull request and someone will.
-- Option values and names are kebab case.
-- Art and sound are CC0 or public domain only, checked at the source, and credited in the README. No GPL or LGPL code.
-- Needs Node 22 or later. A change a user would notice gets a line in `CHANGELOG.md`.
-- **The list of the family in the README is made, not written.** `pnpm family:readme` writes it between its
-  markers from `scripts/family-template.mjs` (the names, the Japanese names and a line on each), and
-  `scripts/family-readme.mjs` is the same file in every package. To add a package or change a line, change the
-  template in every repository, bump `FAMILY_TEMPLATE_VERSION` and record the new hash in `src/family.test.js`.
-
-## Releasing
-
-Maintainers bump the version in `package.json` and `src/version.ts` and move
-*Unreleased* to the new version in `CHANGELOG.md`, dated. Pushing the tag
-`vX.Y.Z` runs the Release workflow, which checks that the tag matches
-`package.json`, runs the checks, builds the package, installs and uses it as
-npm packs it, attaches the tarball to a GitHub release, and publishes it to
-npm with provenance, through npm's trusted publishing (no token is kept). A
-version already on npm is not published again. The workflow can also be run
-by hand.
-
-By contributing you agree that your code is released under the
-[MIT licence](LICENSE), and to follow the [code of conduct](CODE_OF_CONDUCT.md).