SPB Git

Repository Public

types.ts 3.2 KB 65 lines typescript

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
Files main
Menu

Theme