Repository Public
1import type { ReactNode } from "react";2import type { Locale, SimKind } from "@/schema";34export type SimParams = Readonly<Record<string, number>>;5export type SimConfig = Readonly<Record<string, string | number | boolean>>;6export type L10n = Record<Locale, string>;78/** One slider. */9export interface ParamDef { key: string; label: L10n; min: number; max: number; step: number; default: number; unit?: string }1011export interface ViewProps<M> {12 model: M;13 locale: Locale;14 /** Animation frame, 0 … steps(model) − 1. Always 0 for simulations that are not animated. */15 step: number;16 /** Unique prefix for SVG ids (clip paths, gradients). */17 idPrefix: string;18}1920/**21 * A pre-approved simulation. `compute` is pure and deterministic: every number a reader sees comes from it.22 * `View` only draws a model (no hooks, no state, no random numbers), so it renders identically on the server.23 */24export interface SimDef<M = unknown> {25 kind: SimKind;26 title: L10n;27 description: L10n;28 /** Sliders of the default configuration. Kinds whose sliders depend on `config` also implement `paramsFor`. */29 params: ParamDef[];30 /** Whether the picture uses random draws (then the seed matters and the data is labelled synthetic). */31 stochastic: boolean;32 /** Keys accepted in `config` (besides the ones every simulation accepts). */33 configKeys?: readonly string[];34 /** True when `validateConfig` checks the config keys itself (keys that depend on the content, as in function-plot). */35 openConfig?: boolean;36 /** Sliders for a given configuration (distribution family, function-plot expressions…). */37 paramsFor?(config: SimConfig): ParamDef[];38 /** Problems in `config`, in plain English, for the author. */39 validateConfig?(config: SimConfig): string[];40 compute(params: SimParams, seed: number, config: SimConfig): M;41 /** Number of animation frames; absent for static pictures. */42 steps?(model: M): number;43 View(props: ViewProps<M>): ReactNode;44}4546export function param(key: string, fr: string, en: string, min: number, max: number, step: number, def: number, unit?: string): ParamDef {47 return unit === undefined ? { key, label: { fr, en }, min, max, step, default: def } : { key, label: { fr, en }, min, max, step, default: def, unit };48}4950/** A string option restricted to a list; anything else falls back to the first entry. */51export function option<T extends string>(config: SimConfig, key: string, allowed: readonly T[]): T {52 const v = config[key];53 return typeof v === "string" && (allowed as readonly string[]).includes(v) ? (v as T) : allowed[0];54}55export function optionError(config: SimConfig, key: string, allowed: readonly string[]): string[] {56 const v = config[key];57 if (v === undefined) return [];58 return typeof v === "string" && allowed.includes(v) ? [] : [`config.${key}: expected one of ${allowed.join(", ")} (got ${JSON.stringify(v)})`];59}60export function numberOption(config: SimConfig, key: string, fallback: number, min = -Infinity, max = Infinity): number {61 const v = config[key];62 return typeof v === "number" && Number.isFinite(v) ? Math.min(max, Math.max(min, v)) : fallback;63}64export function clamp(v: number, lo: number, hi: number): number { return Math.min(hi, Math.max(lo, v)); }65