@broberg/bodymap 0.14.0 → 0.15.0

package/dist/preact.d.ts

@@ -0,0 +1,223 @@
+import { VNode } from 'preact';
+import { z } from 'zod';
+
+/** One marked pain point. `region` MUST be a known region key; `intensity` is a
+ *  0-10 integer; `type` is optional but constrained; `timestamp` is an ISO string. */
+declare const painPointSchema: z.ZodObject<{
+    region: z.ZodString;
+    intensity: z.ZodNumber;
+    type: z.ZodOptional<z.ZodEnum<{
+        stikkende: "stikkende";
+        dump: "dump";
+        konstant: "konstant";
+        jagende: "jagende";
+    }>>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+type PainPoint = z.infer<typeof painPointSchema>;
+type PainReport = PainPoint[];
+interface RegionSetting {
+    /** Render this region at all. Default true. */
+    visible?: boolean;
+    /** Allow marking pain on this region. Default true. */
+    selectable?: boolean;
+}
+/** Per-app config keyed by region key. An absent key ⇒ visible + selectable. */
+type RegionConfig = Record<string, RegionSetting>;
+/**
+ * What a pick on a region should DO (F052.20).
+ *
+ * Lives in the core because the 2D and 3D renderers share no click code, and a
+ * rule written twice is a rule that drifts. This repo measured the cost of that
+ * twice on 2026-08-28 alone: a fix applied to one half of a pair, and a sibling
+ * branch that carried the same defect with no test on it.
+ *
+ *   "clear"   the region is already marked → picking it again removes the mark
+ *   "select"  unmarked → open it for marking
+ *   "ignore"  not selectable (read-only or config) → nothing happens
+ *
+ * Three outcomes, not a boolean: "nothing happened because it is locked" and
+ * "nothing happened because we removed the mark" must never look alike to a
+ * caller.
+ */
+type PickOutcome = "clear" | "select" | "ignore";
+/**
+ * What a pick did, handed to the consuming app so it can make a sound or a buzz.
+ *
+ * The outcome is the one `decidePick` ACTUALLY returned, never the intent to tap
+ * — so a tap on a locked region can not announce itself as a removal, and a tap
+ * the pan/pinch guard swallowed emits nothing at all (it never gets here).
+ *
+ * It deliberately reuses `PickOutcome` rather than introducing a second
+ * three-word vocabulary. Two enums meaning the same thing is a drift bug waiting
+ * for the first person who adds a fourth outcome to only one of them.
+ */
+interface FeedbackSignal {
+    outcome: PickOutcome;
+    /** The region key that was picked. */
+    region: string;
+}
+type FeedbackFn = (signal: FeedbackSignal) => void;
+/** Colour control for the body renderers. Consumers pass a palette to theme the
+ *  body base colour, the hover + selected highlights, the pain-heat colours, and
+ *  optional per-region base colours. All values are CSS/hex colour strings. */
+interface BodymapPalette {
+    /** Base body colour (an unmarked region). */
+    body: string;
+    /** Region highlight on hover (before click). */
+    hover: string;
+    /** A region selected (clicked) but not yet given an intensity. */
+    selected: string;
+    /** Pain-intensity heat colours: low (0-3), mid (4-6), high (7-10). */
+    heat: {
+        low: string;
+        mid: string;
+        high: string;
+    };
+    /** Optional per-region base-colour overrides (region key → colour). */
+    regions?: Record<string, string>;
+    /**
+     * Optional panel-chrome colours (the selection panel, labels, hint box) —
+     * NOT the body itself. All optional; anything omitted falls back to
+     * {@link defaultUi}. A palette that only themed the body was half a palette:
+     * a consumer passing brand colours still got hardcoded chrome. (F052.19)
+     */
+    ui?: BodymapUiColors;
+}
+/** Panel-chrome colours. Every default is WCAG-AA (>=4.5:1) on its own background. */
+interface BodymapUiColors {
+    /** Primary text (headings, values). */
+    text?: string;
+    /** Secondary text — section labels, the empty-state hint. */
+    mutedText?: string;
+    /** Panel background — the card, its buttons, the empty hint. */
+    panelBg?: string;
+    /**
+     * THE STAGE: the fullscreen backdrop, the canvas frame, and the three.js
+     * scene behind the body. A different surface from `panelBg` with an opposite
+     * need — see F052.29, where one field paints both and no value is right for
+     * either.
+     *
+     * 3D only. The 2D renderer has no canvas and no fullscreen, so it ignores
+     * this; it is declared here because a stage is a shared idea, not because
+     * every renderer has one.
+     *
+     * Defaults to {@link STAGE_BG}. Pass `'#fff'` for the pre-0.8.0 white
+     * fullscreen backdrop.
+     */
+    stageBg?: string;
+    /** Panel + control borders. */
+    border?: string;
+    /** Background behind the region-code badge. */
+    badgeBg?: string;
+    /** The destructive action (remove a marked region). */
+    danger?: string;
+    /** Border on the destructive control. Its TEXT was already themeable and its
+     *  border was not — half a control. (F052.30) */
+    dangerBorder?: string;
+    /**
+     * THE ACTIVE CONTROL colour — the chosen intensity, the active sex toggle.
+     *
+     * NOT `palette.selected`. That is the colour of a MARK ON SKIN; this is the
+     * colour of an active button. Collapsing them would stop a consumer having a
+     * teal mark and a navy button, which is a normal thing to want. (F052.30)
+     */
+    accent?: string;
+    /** Text ON the accent. Check it against your accent — see the README. */
+    accentText?: string;
+}
+
+type BodyView2D = "front" | "back";
+interface BodyMapLabels {
+    /** Region key → display name. */
+    regions: Record<string, string>;
+    /** PainType → display word (e.g. "stikkende" → "Stabbing"). */
+    qualities: Record<string, string>;
+    intensity: string;
+    quality: string;
+    remove: string;
+    /** Close the picker without marking anything (F052.26). */
+    close: string;
+    front: string;
+    back: string;
+    empty: string;
+    /** Compare view (F052.13). */
+    before: string;
+    after: string;
+    noChange: string;
+    change: {
+        new: string;
+        resolved: string;
+        improved: string;
+        worse: string;
+    };
+    /** Accessible name for a marked region. */
+    ariaMarked: (name: string, intensity: number, quality?: string) => string;
+    /** Accessible name for an unmarked, selectable region. */
+    ariaUnmarked: (name: string) => string;
+    svgLabel: string;
+    viewLabel: string;
+    zoomLabel: string;
+    zoomIn: string;
+    zoomOut: string;
+    zoomReset: string;
+}
+type BodyMapLocale = "da" | "en";
+interface BodyMapProps {
+    /** Controlled report. Omit for an uncontrolled component (use defaultValue). */
+    value?: PainReport;
+    /** Initial report when uncontrolled. */
+    defaultValue?: PainReport;
+    /** Fired with the full validated PainReport on every change. */
+    onChange?: (report: PainReport) => void;
+    /** Per-app region config (visible / selectable). */
+    config?: RegionConfig;
+    /** Initial body view (front / back). Default "front". */
+    defaultView?: BodyView2D;
+    /** Fired when the user toggles the front/back view — pass it to
+     *  serializeReport({ view }) so the wire report carries the active view. */
+    onViewChange?: (view: BodyView2D) => void;
+    /** Colour theme (F052.10). Overrides the default rainbow: body/hover/selected/
+     *  heat + optional per-region base colours. Without it, the rainbow is used
+     *  (themeable via --bmap-body / --bmap-region-<key> / --bmap-heat-* CSS vars). */
+    palette?: BodymapPalette;
+    /** UI language (F052.12). "da" (default) or "en". */
+    locale?: BodyMapLocale;
+    /** Override individual UI strings (region names, headings, quality words, …).
+     *  Merged over the locale set — region CODE + wire format are never affected. */
+    labels?: Partial<BodyMapLabels>;
+    /** Display-only mode (F052.9): render a saved report coloured by intensity
+     *  with NO picker and no interactivity. For journals, PDFs, clinician views. */
+    readOnly?: boolean;
+    /** Fired after every pick with what ACTUALLY happened (F052.22): "select",
+     *  "clear" or "ignore". Wire it to a sound (`@broberg/soundkit`) or to native
+     *  haptics (Capacitor `Haptics.impact()` — the only route to a real buzz on an
+     *  iPhone, where web vibration does not exist). A pick swallowed by the
+     *  pan/pinch guard fires nothing at all. */
+    onFeedback?: FeedbackFn;
+    /** Web vibration on select/clear. Default true; silently inert where
+     *  `navigator.vibrate` is absent (every browser on iPhone, most desktops).
+     *  Set false to keep the signal but drop the buzz. */
+    haptics?: boolean;
+    className?: string;
+}
+interface BodyMapCompareProps {
+    /** The earlier report. */
+    before: PainReport;
+    /** The later report. */
+    after: PainReport;
+    palette?: BodymapPalette;
+    locale?: BodyMapLocale;
+    labels?: Partial<BodyMapLabels>;
+    defaultView?: BodyView2D;
+    className?: string;
+}
+
+/** 2D SVG body pain-map. Click/tap a region → set intensity + quality → PainReport. */
+declare function BodyMap(props: BodyMapProps): VNode;
+/** Read-only before/after view: two bodies side by side + a per-region change list. */
+declare function BodyMapCompare(props: BodyMapCompareProps): VNode;
+declare const LABELS_DA: BodyMapLabels;
+declare const LABELS_EN: BodyMapLabels;
+
+export { BodyMap, BodyMapCompare, type BodyMapCompareProps, type BodyMapLabels, type BodyMapLocale, type BodyMapProps, type BodyView2D, LABELS_DA, LABELS_EN };