courthive-components 5.0.0 → 6.0.1

package/README.md

@@ -320,6 +320,39 @@ Import the bundled CSS:
 import 'courthive-components/dist/courthive-components.css';
 ```
 
+### Theme tokens — two families, on purpose
+
+Colour is driven entirely by CSS custom properties defined in `src/styles/theme.css`, in a `:root`
+block (light) and a `[data-theme='dark']` block. **Never hardcode a colour in component CSS**, and
+never use Bulma classes or `--bulma-*`: class names that merely follow Bulma's naming are ours and
+are fine, but the palette must resolve through a token or it cannot follow the theme.
+
+| family    | what it is                                                                                                                                                                     | use it for                                                                                                                                   |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--chc-*` | The general design system. Semantic roles — `--chc-text-primary`, `--chc-bg-elevated`, `--chc-border-primary`, `--chc-container-*` intents and their `--chc-on-*` foregrounds. | Anything shared: draws, cards, tables, buttons, notifications.                                                                               |
+| `--sp-*`  | A slate palette with translucent, layered surfaces (`--sp-panel-bg`, `--sp-card-bg`, `--sp-border`) plus finer border and status intensities.                                  | The schedule page, scheduling profile, policy catalog, topology builder and interactive scoring — surfaces designed as panels over a ground. |
+
+They are **not** duplicates. `--chc-*` began as a compatibility layer whose light values match
+previously hardcoded ones; `--sp-*` is a newer, denser palette with alpha-composited surfaces
+`--chc-*` has no equivalent for. Consumers bridge both: TMX aliases 29 `--chc-*` and 13 `--sp-*` to
+its own `--tmx-*` system.
+
+**Rules that keep them working:**
+
+- **Every token must be defined** in `theme.css`, in both blocks. A token used but never defined
+  renders its call-site fallback in _both_ themes — which is how `--sp-border-focus` shipped an
+  invisible focus border.
+- **Do not write a fallback.** `var(--sp-muted)`, never `var(--sp-muted, #888)`. Fallbacks drift from
+  the definition — `--sp-muted` once had five different ones — and the token stops being a single
+  source of truth.
+- **The library must not reference a consumer's tokens.** `--tmx-*` belongs to TMX; reaching for it
+  from here inverts the dependency.
+- **`--chc-on-*` is the readable foreground for a `--chc-container-*` fill.** Both themes are held to
+  WCAG AA by `src/styles/theme-contrast.test.ts`; change a container colour and that test tells you
+  whether its foreground still works.
+- Brand themes (`src/styles/themes.css`, `.chc-theme-*`) keep literal colours. A brand does not
+  follow the light/dark theme.
+
 ## TypeScript Support
 
 The package includes TypeScript definitions:

package/dist/components/renderStructure/seedingBasis.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Why a seed exists, for the on-screen draw.
+ *
+ * `Side.seedingBasis` records the ground on which a seeding was awarded, as distinct from
+ * `seedValue`, which says only where it sits in the order. It matters wherever a governing body
+ * permits seeds ABOVE the count its policy allows — a protected ranking seeded ALONGSIDE the normal
+ * seeds rather than in place of one. Such a seed displaced nobody, and it is the one somebody will
+ * ask about.
+ *
+ * ## Why the bracket is marked here and not on the printed sheet
+ *
+ * pdf-factory deliberately leaves the bracket alone and footnotes its **seedings table** instead:
+ * an entry line there already carries name, nationality and an entry-status badge, and the table
+ * exists to answer "why these seeds". The on-screen draw has **no seedings table** — the bracket is
+ * the only surface the fact can appear on, so leaving it unmarked leaves it nowhere.
+ *
+ * The marker is a single character appended inside the seed's own brackets, so it costs no layout;
+ * the basis itself goes in a `title`, following the same rule the presence work settled on — the
+ * fact is displayed, the detail is on hover.
+ *
+ * `RANKING` is the ordinary basis and is never marked. An absent basis means the ordinary one, not
+ * "unknown", so marking every seed would bury the one that is not.
+ */
+/** The marker to append to a seed display, or `''` where the seed is ordinary. */
+export declare function seedingBasisMarker(seedingBasis?: string): string;
+/**
+ * The hover text for a marked seed, or `undefined` where there is nothing to say.
+ *
+ * An unrecognised basis is printed verbatim rather than dropped. The factory's basis enum can gain
+ * members, and a tooltip that silently omits one it does not know is worse than a tooltip showing
+ * an unfamiliar word — the second is a question, the first is a wrong answer.
+ */
+export declare function seedingBasisTitle(seedingBasis?: string): string | undefined;

package/dist/components/scoring/statusCodePicker.d.ts

@@ -10,4 +10,6 @@ export type StatusCodePickerHandle = {
 export declare function buildStatusCodePicker(params: {
     groups?: StatusCodeGroups;
     labels?: ScoringModalLabels;
+    /** The code already recorded on the matchUp, so re-opening the dialog shows what was saved. */
+    initialCode?: string;
 }): StatusCodePickerHandle;