courthive-components 4.5.0 → 6.0.0

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/policy-catalog/editors/scoring/scoringEditorStore.d.ts

@@ -23,6 +23,17 @@ export declare class ScoringEditorStore {
     isAllowedFormatDuplicate(format: string, excludeIndex?: number): boolean;
     addAllowedFormatCategory(index: number, kind: 'categoryNames' | 'categoryTypes', value: string): void;
     removeAllowedFormatCategory(index: number, kind: 'categoryNames' | 'categoryTypes', valueIndex: number): void;
+    /**
+     * Add a code to a status group.
+     *
+     * The operator types a code; the entry stored is an OBJECT. Only `matchUpStatusCode` is set —
+     * `matchUpStatusCodeDisplay` and `label` are authored per code and this control has no field for
+     * them, so inventing values would be worse than leaving them absent (the reason picker falls back
+     * to the code, which is the policy saying "the code IS the label").
+     *
+     * Entries that arrive already carrying display text are never rewritten by this path, which is
+     * the whole point: the previous `string[]` model discarded them on every save.
+     */
     addStatusCode(status: MatchUpStatusKey, value: string): void;
     removeStatusCode(status: MatchUpStatusKey, index: number): void;
     addProcessCode(value: string): void;

package/dist/components/policy-catalog/editors/scoring/types.d.ts

@@ -1,14 +1,4 @@
-/**
- * Scoring Policy Editor — Type Definitions
- *
- * Mirrors the factory's scoring policy data shape (see
- * factory/src/fixtures/policies/POLICY_SCORING_DEFAULT.ts).
- *
- * The factory does not export a TypeScript interface for the scoring
- * policy itself — the fixture defines the shape via runtime defaults.
- * We re-derive the shape here so the editor can stay type-safe without
- * dragging factory internals into courthive-components.
- */
+import { StatusCodeEntry } from '../../../scoring/logic/statusCodes';
 export type MatchUpStatusKey = 'ABANDONED' | 'CANCELLED' | 'DEFAULTED' | 'INCOMPLETE' | 'RETIRED' | 'WALKOVER';
 export declare const MATCH_UP_STATUS_KEYS: MatchUpStatusKey[];
 export type RequireAllPositionsTriState = 'default' | 'true' | 'false';
@@ -36,7 +26,7 @@ export interface ScoringPolicyData {
     requireAllPositionsAssigned?: boolean;
     allowChangePropagation?: boolean;
     allowDeletionWithScoresPresent?: AllowDeletionWithScoresPresent;
-    matchUpStatusCodes?: Partial<Record<MatchUpStatusKey, string[]>>;
+    matchUpStatusCodes?: Partial<Record<MatchUpStatusKey, StatusCodeEntry[]>>;
     stage?: Record<string, {
         stageSequence?: Record<string, StageSequenceOverride>;
     }>;

package/dist/components/policy-catalog/editors/seeding/domain/seedingNormalise.d.ts

@@ -0,0 +1,5 @@
+import { NormalisedSeedingProfile, SeedingPolicyData, SeedingPolicyDraft } from '../types';
+/** Widen a policy's `seedingProfile` — and every drawType override — to the object form. */
+export declare function normaliseSeedingProfile(profile: SeedingPolicyData['seedingProfile']): NormalisedSeedingProfile | undefined;
+/** Widen a whole policy to the editor's internal draft form. */
+export declare function toDraft(policy: SeedingPolicyData): SeedingPolicyDraft;

package/dist/components/policy-catalog/editors/seeding/domain/seedingProjections.d.ts

@@ -8,3 +8,12 @@ export declare const POSITIONING_OPTIONS: {
 export declare const DRAW_TYPE_OPTIONS: string[];
 export declare function emptySeedingPolicy(): SeedingPolicyData;
 export declare function positioningLabel(value: SeedingPositioning | undefined): string;
+/**
+ * `ADJACENT` is the factory's synonym for `CLUSTER` — `generateBlockPattern` and
+ * `getContainerBlocks` treat them identically. The picker deliberately offers ONE option
+ * rather than two that do the same thing, so either stored value selects it.
+ *
+ * This is display-only: the stored value is left exactly as it arrived, because rewriting
+ * a caller's `ADJACENT` to `CLUSTER` would be an unrequested edit to their policy.
+ */
+export declare function canonicalPositioning(value?: SeedingPositioning): SeedingPositioning | undefined;

package/dist/components/policy-catalog/editors/seeding/index.d.ts

@@ -5,4 +5,4 @@ export { SeedingEditorControl, createSeedingEditor } from './seedingEditorContro
 export { SeedingEditorStore } from './seedingEditorStore';
 export { buildSeedingEditorPanel } from './seedingEditorPanel';
 export { emptySeedingPolicy, POSITIONING_OPTIONS, DRAW_TYPE_OPTIONS } from './domain/seedingProjections';
-export type { SeedingPolicyData, SeedingProfile, SeedingPositioning, SeedsCountThreshold, SeedingEditorState, SeedingEditorSection, SeedingEditorChangeListener, SeedingEditorConfig } from './types';
+export type { SeedingPolicyData, SeedingPolicyDraft, NormalisedSeedingProfile, PolicySeedingProfile, DrawSeedingProfile, SeedingProfile, SeedingPositioning, SeedsCountThreshold, SeedingEditorState, SeedingEditorSection, SeedingEditorChangeListener, SeedingEditorConfig } from './types';

package/dist/components/policy-catalog/editors/seeding/seedingEditorControl.d.ts

@@ -1,5 +1,5 @@
 import { SeedingEditorStore } from './seedingEditorStore';
-import { SeedingPolicyData, SeedingEditorConfig } from './types';
+import { SeedingPolicyDraft, SeedingPolicyData, SeedingEditorConfig } from './types';
 import { PolicyEditorInstance as CatalogEditorInstance } from '../../types';
 export declare class SeedingEditorControl {
     private readonly store;
@@ -9,7 +9,7 @@ export declare class SeedingEditorControl {
     constructor(config: SeedingEditorConfig);
     render(container: HTMLElement): void;
     destroy(): void;
-    getData(): SeedingPolicyData;
+    getData(): SeedingPolicyDraft;
     setData(data: SeedingPolicyData): void;
     getStore(): SeedingEditorStore;
     static createEditorInstance(config: {

package/dist/components/policy-catalog/editors/seeding/seedingEditorStore.d.ts

@@ -1,11 +1,11 @@
-import { SeedingPolicyData, SeedingEditorState, SeedingEditorSection, SeedingEditorChangeListener, SeedingEditorConfig, SeedsCountThreshold, SeedingPositioning } from './types';
+import { SeedingPolicyDraft, SeedingPolicyData, SeedingEditorState, SeedingEditorSection, SeedingEditorChangeListener, SeedingEditorConfig, SeedsCountThreshold, SeedingPositioning } from './types';
 export declare class SeedingEditorStore {
     private state;
     private readonly listeners;
     private readonly config;
     constructor(config: SeedingEditorConfig);
     getState(): SeedingEditorState;
-    getData(): SeedingPolicyData;
+    getData(): SeedingPolicyDraft;
     setData(data: SeedingPolicyData): void;
     toggleSection(sectionId: SeedingEditorSection): void;
     setPolicyName(value: string): void;

package/dist/components/policy-catalog/editors/seeding/types.d.ts

@@ -1,41 +1,42 @@
+import { SeedingProfile as DrawSeedingProfile, PolicySeedingProfile, SeedingProfileUnion, SeedsCountThreshold, SeedingPolicy } from 'tods-competition-factory';
+export type { SeedsCountThreshold, PolicySeedingProfile, DrawSeedingProfile };
+/** `'ADJACENT' | 'CLUSTER' | 'SEPARATE' | 'WATERFALL'` — the factory's closed union. */
+export type SeedingPositioning = SeedingProfileUnion;
+/** The policy-level profile in its object form. */
+export type SeedingProfile = PolicySeedingProfile;
+/** What the editor accepts and emits — the factory's policy shape, verbatim. */
+export type SeedingPolicyData = SeedingPolicy;
 /**
- * Seeding Policy Editor — Type Definitions
+ * The editor's INTERNAL draft.
  *
- * Mirrors the factory's seeding policy data shape (see
- * factory/src/fixtures/policies/POLICY_SEEDING_*.ts).
+ * `SeedingPolicy.seedingProfile` is `PolicySeedingProfile | SeedingProfileUnion` — the
+ * factory still honours a bare positioning string where a profile object is expected.
+ * The editor holds and mutates an object, so the string form is normalised away on
+ * ingest (see `normaliseSeedingProfile`) and the draft is the object form only.
  */
-export type SeedingPositioning = 'SEPARATE' | 'WATERFALL' | 'CLUSTER';
-export interface SeedsCountThreshold {
-    drawSize: number;
-    minimumParticipantCount: number;
-    seedsCount: number;
-}
-export interface SeedingProfile {
-    positioning?: SeedingPositioning;
-    drawTypes?: Record<string, {
-        positioning: SeedingPositioning;
-    }>;
-}
-export interface SeedingPolicyData {
-    policyName?: string;
-    seedingProfile?: SeedingProfile;
-    validSeedPositions?: {
-        ignore: boolean;
-    };
-    duplicateSeedNumbers?: boolean;
-    drawSizeProgression?: boolean;
-    seedsCountThresholds?: SeedsCountThreshold[];
-}
+export type SeedingPolicyDraft = Omit<SeedingPolicyData, 'seedingProfile'> & {
+    seedingProfile?: NormalisedSeedingProfile;
+};
+/**
+ * A {@link PolicySeedingProfile} whose drawType overrides are known to be objects.
+ * The factory types each override as `SeedingProfile | SeedingProfileUnion`; the editor
+ * normalises the string form away on ingest, so the draft need not re-narrow at every read.
+ */
+export type NormalisedSeedingProfile = Omit<PolicySeedingProfile, 'drawTypes'> & {
+    drawTypes?: Record<string, DrawSeedingProfile>;
+};
 export type SeedingEditorSection = 'profile' | 'flags' | 'thresholds' | 'drawTypeOverrides';
 export interface SeedingEditorState {
-    draft: SeedingPolicyData;
+    draft: SeedingPolicyDraft;
     expandedSections: Set<SeedingEditorSection>;
     dirty: boolean;
 }
 export type SeedingEditorChangeListener = (state: SeedingEditorState) => void;
 export interface SeedingEditorConfig {
+    /** Accepts either form the factory accepts; the string form is normalised on ingest. */
     initialPolicy?: SeedingPolicyData;
     /** Override the list of drawTypes offered in the overrides picker. */
     drawTypes?: string[];
-    onChange?: (policy: SeedingPolicyData) => void;
+    /** Emits the normalised object form, which is itself a valid {@link SeedingPolicyData}. */
+    onChange?: (policy: SeedingPolicyDraft) => void;
 }

package/dist/components/policy-catalog/index.d.ts

@@ -24,5 +24,5 @@ export type { PrivacyPolicyData, PrivacyEditorConfig, PrivacyFieldMeta } from '.
 export type { PolicyCatalogItem, PolicyCatalogState, PolicyCatalogChangeListener, PolicyCatalogConfig, PolicyEditorInstance, PolicyEditorPlugin, PolicySource, PolicyTypeGroup, PolicyTypeMeta, CatalogGroupBy, UIPanel } from './types';
 export type { SchedulingPolicyData, SchedulingEditorState, SchedulingEditorSection, SchedulingEditorChangeListener, SchedulingEditorConfig, SchedulingValidationResult, ValidationSeverity, MinutesEntry, AverageTimeEntry, RecoveryTimeEntry, MatchUpAverageTime, MatchUpRecoveryTime } from './editors/scheduling';
 export type { RankingPolicyData, RankingPointsEditorState, RankingEditorSection, RankingPointsEditorChangeListener, RankingPointsEditorConfig, AwardProfileData, QualityWinProfileData, AggregationRulesData, TableLayout } from './editors/ranking';
-export type { SeedingPolicyData, SeedingProfile, SeedingPositioning, SeedsCountThreshold, SeedingEditorState, SeedingEditorSection, SeedingEditorChangeListener, SeedingEditorConfig } from './editors/seeding';
+export type { SeedingPolicyData, SeedingPolicyDraft, NormalisedSeedingProfile, PolicySeedingProfile, DrawSeedingProfile, SeedingProfile, SeedingPositioning, SeedsCountThreshold, SeedingEditorState, SeedingEditorSection, SeedingEditorChangeListener, SeedingEditorConfig } from './editors/seeding';
 export declare function createPolicyCatalog(config: PolicyCatalogConfig, container: HTMLElement): PolicyCatalogControl;

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;