@ntmats/hc-ui 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type ButtonHTMLAttributes, type HTMLAttributes, type InputHTMLAttributes, type KeyboardEvent, type MouseEvent, type ReactElement, type ReactNode, type Ref } from 'react';
+import { type ButtonHTMLAttributes, type Dispatch, type HTMLAttributes, type InputHTMLAttributes, type KeyboardEvent, type MouseEvent, type ReactElement, type ReactNode, type Ref, type SetStateAction } from 'react';
 export type SurfaceTone = 'page' | 'main' | 'content' | 'elevated' | 'overlay' | 'card';
 export interface SurfaceProps extends HTMLAttributes<HTMLDivElement> {
     tone?: SurfaceTone;
@@ -46,6 +46,11 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     fullWidth?: boolean;
     /** Busy state: keeps focus and label, shows a spinner and ignores clicks. */
     loading?: boolean;
+    /**
+     * Opt-in: a long label wraps onto more lines (the button grows taller) instead of
+     * being cut with an ellipsis, which stays the default.
+     */
+    wrap?: boolean;
 }
 /** Pill button. The caller supplies the label text and handles the action. */
 export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
@@ -298,15 +303,12 @@ interface SheetChoiceProps<T extends string> extends Omit<HTMLAttributes<HTMLDiv
 }
 export interface SheetOptionsProps<T extends string> extends SheetChoiceProps<T> {
     options: readonly SheetOption<T>[];
-    /**
-     * `card` (default): rows on a `bg-muted-2` card, as HCUI's SheetOptions. `list`: plain
-     * 48px rows divided by a line, the chosen one bolder with a 20px check in the text color,
-     * as the list of HCUI's mobile sort sheet (`SortButton`).
-     */
-    variant?: 'card' | 'list';
 }
-/** Single-choice list of rows with a check (HCUI's SheetOptions), for inside a sheet. */
-export declare function SheetOptions<T extends string>({ label, options, value, onChange, variant, className, ...props }: SheetOptionsProps<T>): import("react/jsx-runtime").JSX.Element;
+/**
+ * Single-choice list of rows with a check on a `bg-muted-2` card (HCUI's SheetOptions),
+ * for inside a sheet. It is also the phone's sort list (decision of 2026-11-07).
+ */
+export declare function SheetOptions<T extends string>({ label, options, value, onChange, className, ...props }: SheetOptionsProps<T>): import("react/jsx-runtime").JSX.Element;
 export interface SheetChipsProps<T extends string> extends SheetChoiceProps<T> {
     options: readonly {
         value: T;
@@ -442,7 +444,7 @@ export interface SortMenuProps<T extends string> extends Omit<MenuProps, 'label'
 /**
  * Sort control: a `Chip` showing the current choice that opens a `Menu` with a
  * `MenuRadioGroup` (HCUI's `DesktopSortMenu`). Options and value come from the caller.
- * On phones, compose `Sheet` with `SheetOptions` behind an `IconButton` instead.
+ * On phones, compose `Sheet` with `SheetOptions` (its card look) behind an `IconButton` instead.
  */
 export declare function SortMenu<T extends string>({ label, value, options, onChange, applied, size, triggerClassName, ...props }: SortMenuProps<T>): import("react/jsx-runtime").JSX.Element;
 export interface PopoverProps extends PopupBaseProps, Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'children'> {
@@ -639,4 +641,966 @@ export interface CommandPaletteProps extends Omit<HTMLAttributes<HTMLDialogEleme
  * item under it. Texts, results and actions come from the caller.
  */
 export declare const CommandPalette: import("react").ForwardRefExoticComponent<CommandPaletteProps & import("react").RefAttributes<HTMLDialogElement>>;
+/**
+ * Walks a list of image addresses: starts at the first and moves to the next on
+ * each load error. Starts over when the list changes. `src` is `undefined` once
+ * every address failed.
+ */
+export declare function useImageChain(sources: readonly string[]): {
+    src: string | undefined;
+    index: number;
+    /** Call from `onError`: moves to the next address. */
+    next: () => void;
+};
+/** Rows of the mini dial, top to bottom. */
+export declare const MINI_DIAL_STATS: readonly ["speed", "attack", "defense", "damage"];
+export type MiniDialStat = (typeof MINI_DIAL_STATS)[number];
+/** One resolved cell: the power color (or none), whether it is round and whether it is a special power. */
+export interface MiniDialCell {
+    /** Standard power color. Without it the cell is the dial paper (no power). */
+    color?: string;
+    /** Round power (e.g. WWE). */
+    round?: boolean;
+    /** Special power: paper with a dark outline. */
+    special?: boolean;
+}
+/** One click of the dial, with its 4 cells. */
+export interface MiniDialColumn {
+    /** Click number; also decides what has passed relative to `currentClick`. */
+    click: number;
+    cells: Record<MiniDialStat, MiniDialCell>;
+}
+export interface MiniDialViewProps {
+    columns: readonly MiniDialColumn[];
+    /** In play: the current click gets an outline and earlier ones fade. */
+    currentClick?: number;
+    /** Accessible label, already localized (e.g. "Dial: 6 clicks"). */
+    label: string;
+    className?: string;
+}
+/**
+ * The dial summarized in small squares: one column per click, one row per value
+ * (speed, attack, defense, damage). The cell size is `--hc-mini-dial-cell` (7px).
+ */
+export declare const MiniDialView: import("react").ForwardRefExoticComponent<MiniDialViewProps & import("react").RefAttributes<HTMLSpanElement>>;
+export interface PowerIconViewProps {
+    /** Power color (the circle's fill). */
+    color: string;
+    /** Address of the value symbol (boot, fist, shield, starburst), already built. */
+    glyphSrc: string;
+    /** The symbol is black; `true` turns it white, for contrast on dark colors. */
+    invertGlyph?: boolean;
+    size?: number;
+}
+/** Power icon: a circle in the power color with the value symbol on top. */
+export declare const PowerIconView: import("react").ForwardRefExoticComponent<PowerIconViewProps & import("react").RefAttributes<HTMLSpanElement>>;
+export interface StatGlyphViewProps {
+    /** Address of the symbol, already built. */
+    src: string;
+    /** Alternative text, as the caller wants it read. */
+    alt: string;
+    size?: number;
+}
+/** The value symbol alone (no circle), in neutral gray. Used in the dial legend. */
+export declare const StatGlyphView: import("react").ForwardRefExoticComponent<StatGlyphViewProps & import("react").RefAttributes<HTMLImageElement>>;
+export interface SpecialIconViewProps {
+    /** Round white background (the image server's `sp/white.svg`), already built. */
+    backgroundSrc: string;
+    /** Symbol over the background (the trait star or a value symbol), already built. */
+    glyphSrc: string;
+    size?: number;
+}
+/** Special power and trait icon: a white circle with a symbol in the middle. */
+export declare const SpecialIconView: import("react").ForwardRefExoticComponent<SpecialIconViewProps & import("react").RefAttributes<HTMLSpanElement>>;
+export interface EquipmentIconProps {
+    size?: number;
+}
+/** Equipment icon: a white diamond on a purple circle. Decorative. */
+export declare function EquipmentIcon({ size }: EquipmentIconProps): import("react/jsx-runtime").JSX.Element;
+export type StatIconType = 'speed' | 'attack' | 'defense' | 'damage';
+export interface StatIconProps {
+    type: StatIconType;
+    size?: number;
+    className?: string;
+}
+/** Arrow, shield or diamond drawn in SVG in the text color (`currentColor`); not the official symbols. */
+export declare function StatIcon({ type, size, className }: StatIconProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Avatar shape:
+ * - `round`: the default (the caller's class crops it);
+ * - `card`: one-shot, a landscape card (width ÷ 1.42, proportional corners);
+ * - `square`: maps, a square with slightly rounded corners;
+ * - `square-fit`: terrain marker, a square with the whole image fitted in.
+ */
+export type AvatarShape = 'round' | 'card' | 'square' | 'square-fit';
+export interface AvatarViewProps {
+    /** Image addresses, in the order to try (e.g. a thumbnail, then the original). */
+    sources: readonly string[];
+    /** Image drawn when there is no address or all of them failed. */
+    fallbackSrc: string;
+    /** Alternative text, in the app's language. */
+    alt: string;
+    shape?: AvatarShape;
+    className?: string;
+    /** Reports that every attempt failed and the fallback is showing. */
+    onFallback?: () => void;
+    /** Width and height in px (the height follows the shape for `card`). Without it the caller's class sizes it. */
+    size?: number;
+}
+/**
+ * The piece's portrait. Tries each address in order and, when none loads, shows
+ * `fallbackSrc` (with `data-fallback` and the muted fill). The image cannot be
+ * dragged, selected or opened in a context menu.
+ */
+export declare const AvatarView: import("react").ForwardRefExoticComponent<AvatarViewProps & import("react").RefAttributes<HTMLImageElement>>;
+export interface SetIconViewProps {
+    /** Addresses of the set icon, in the order to try. Empty: renders nothing. */
+    sources: readonly string[];
+    className?: string;
+    /** Tooltip (e.g. the set name), in the app's language. */
+    title?: string;
+}
+/** Set icon. Tries each address in order and disappears when none loads. Decorative: the set name is next to it. */
+export declare const SetIconView: import("react").ForwardRefExoticComponent<SetIconViewProps & import("react").RefAttributes<HTMLImageElement>>;
+/** Value rows of the dial, top to bottom (the top row is the click number). */
+export declare const COMBAT_DIAL_STATS: readonly ["speed", "attack", "defense", "damage"];
+export type CombatDialStat = (typeof COMBAT_DIAL_STATS)[number];
+/** Content of a power's tip, already in the app's language. */
+export interface CombatDialCellTip {
+    title: string;
+    description: string;
+    /** Standard power color; none for a special power. */
+    accent?: string;
+    /** The color mark is a circle (round power, e.g. WWE). */
+    accentRound?: boolean;
+}
+/** One resolved value cell. */
+export interface CombatDialCell {
+    value: number;
+    /** Accessible label, already localized (e.g. "Click 1: Speed 8 — Charge"). */
+    label: string;
+    /** Cell fill: the power color, or the dial paper (`var(--hc-color-dial-paper)`) for no power. */
+    background: string;
+    /** Number color, chosen for contrast with the fill. */
+    color: string;
+    /** Round power (e.g. WWE). */
+    round?: boolean;
+    /** Special power: dark outline. */
+    outlined?: boolean;
+    /** Without a tip the cell opens nothing; on a static dial it is not even a button. */
+    tip?: CombatDialCellTip;
+}
+/** One click of the dial. */
+export interface CombatDialColumn {
+    click: number;
+    /** Group label (e.g. "Click 3"). */
+    label: string;
+    /** Label of the number button when the dial changes the click (e.g. "Select click 3"). */
+    selectLabel: string;
+    /** Outside the selected point value: faded. */
+    dimmed?: boolean;
+    /** Starting line of a point value: color of the bar left of the column. */
+    startColor?: string;
+    cells: Record<CombatDialStat, CombatDialCell>;
+}
+/** One legend symbol, with its address already built. */
+export interface CombatDialLegendIcon {
+    src: string;
+    alt: string;
+    title?: string;
+    /** `true`: the neutral value symbol (`StatGlyphView`); otherwise the piece's combat symbol. */
+    glyph?: boolean;
+}
+export interface CombatDialLegend {
+    range: number;
+    targets: number;
+    /** Address of the target bolt. */
+    boltSrc: string;
+    icons: Record<CombatDialStat, CombatDialLegendIcon>;
+}
+/** One point value, with the chip texts ready. */
+export interface CombatDialPoint {
+    index: number;
+    startClick: number;
+    color: string;
+    /** E.g. "100 pts". Without it the chip shows only the clicks; with none at all the row is hidden. */
+    valueLabel?: ReactNode;
+    /** E.g. "6 clicks". */
+    clicksLabel: ReactNode;
+    /** Native tooltip of the chip, shown only when there is more than one point value. */
+    title?: string;
+}
+export interface CombatDialLabels {
+    /** Header title (e.g. "Dial"). */
+    heading: string;
+    /** KO mark in the header (e.g. "K.O"). */
+    koMark: string;
+    /** What follows the KO mark (e.g. "at 7"), already localized. A node, so the number can stay in its own text node. */
+    koAt: ReactNode;
+    /** Text of the KO column cells (e.g. "KO"). */
+    koCell: string;
+}
+/** The open tip: which cell, how (passive hover or the touch dialog), where and its content. */
+export interface CombatDialTipState {
+    key: string;
+    click: number;
+    stat: CombatDialStat;
+    content: CombatDialCellTip;
+    mode: 'hover' | 'dialog';
+    anchor: {
+        x: number;
+        y: number;
+        preferAbove?: boolean;
+    };
+    trigger: HTMLElement;
+}
+export interface CombatDialViewProps {
+    columns: readonly CombatDialColumn[];
+    legend: CombatDialLegend;
+    points: readonly CombatDialPoint[];
+    /** `index` of the selected point value; -1 for none. */
+    selectedPointIndex: number;
+    /** Click centered in the track when the point value changes (its starting line). */
+    focusClick?: number;
+    currentClick?: number;
+    labels: CombatDialLabels;
+    /** `printed`: the physical card's dial, without the header, in rows of 12 clicks. */
+    presentation?: 'default' | 'printed';
+    /**
+     * `comfortable` (default): 40px cells. `compact`: 34px cells, 6px gaps, 13px numbers and
+     * tighter point chips, for dense lists (HCUI's compact dial of the unit view on phones).
+     * The printed presentation keeps its own measures.
+     */
+    density?: 'comfortable' | 'compact';
+    /** Without it the dial is static: it neither marks nor changes the click; only cells with a tip react. */
+    onClickChange?: (click: number) => void;
+    onSelectPoint: (point: CombatDialPoint) => void;
+    /** The open tip, controlled by the caller (which closes it when the piece changes). */
+    tip: CombatDialTipState | null;
+    onTipChange: Dispatch<SetStateAction<CombatDialTipState | null>>;
+    /** `id` of the tip element, for the hover's `aria-describedby`. */
+    tipId: string;
+    /** The tip drawn by the caller (callout, dialog), shown while `tip` is set. */
+    tipSlot?: ReactNode;
+}
+/**
+ * Combat dial: the legend, one column per click, the KO column and, outside the
+ * printed card, the header with the point values. Hover, touch and keyboard on
+ * the cells open the tip through `onTipChange`; the caller draws the tip.
+ */
+export declare const CombatDialView: import("react").ForwardRefExoticComponent<CombatDialViewProps & import("react").RefAttributes<HTMLElement>>;
+export declare const PHYSICAL_CARD_WIDTH = 375;
+export declare const PHYSICAL_CARD_HEIGHT = 525;
+export declare const PHYSICAL_CARD_BACK_TABLE_HEIGHT = 440;
+/** Position of each value of the bystander's dial: every row goes 24px down and 7px right. */
+export declare const PHYSICAL_CARD_BYSTANDER_DIAL_STEP: {
+    x: number;
+    y: number;
+};
+/**
+ * Splits the text blocks between the front (table 0) and the backs (1, 2, …), as
+ * HCUnits: a block that does not fit moves to the next column. The front may end
+ * up empty (the portrait and keywords already take room); a back column always
+ * keeps at least one block, even if it overflows.
+ *
+ * `overflowing(table)` tells whether that column overflows with the current split.
+ * Returns the next split, or `null` once it is stable.
+ */
+export declare function nextPhysicalCardDistribution(pages: number[], overflowing: (table: number) => boolean): number[] | null;
+/** How many backs the split needs (each back has two columns). There is always one. */
+export declare function physicalCardBackCount(pages: number[]): number;
+/** Cursor position on the card (0 to 1) → tilt, parallax (-1 to 1) and shine (%). */
+export declare function physicalCardTiltAt(x: number, y: number, damping?: number): {
+    rotateX: number;
+    rotateY: number;
+    parallaxX: number;
+    parallaxY: number;
+    shineX: number;
+    shineY: number;
+};
+type CardTilt = ReturnType<typeof physicalCardTiltAt>;
+/** The finished values each moving part of the card takes, ready for `style`. */
+export declare function physicalCardTiltStyles(tilt: CardTilt): {
+    card: string;
+    art: string;
+    header: string;
+    shine: string;
+};
+/** Sensor reading relative to the reference pose → position on the card (0 to 1). */
+export declare function physicalCardDevicePosition(beta: number, gamma: number, baseline: {
+    beta: number;
+    gamma: number;
+}, screenAngle?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * The iPhone only releases the motion sensor after a touch. Called at the end of
+ * the touches while the focus view is open, starting with the finger that opened
+ * it; outside iOS it does nothing. A touch the browser refuses leaves the request
+ * for the next one.
+ */
+export declare function requestPhysicalCardMotionAccess(): void;
+/** Value rows of the dial, top to bottom. */
+export declare const PHYSICAL_CARD_STATS: readonly ["speed", "attack", "defense", "damage"];
+export type PhysicalCardStat = (typeof PHYSICAL_CARD_STATS)[number];
+/** A tip's content (team ability, improved ability, bystander power), in the app's language. */
+export interface PhysicalCardTip {
+    title: string;
+    /** Original description; the app may translate it before drawing the tip. */
+    description: string;
+    iconSrc?: string;
+    /** Standard power color; without one it is a special power. */
+    accent?: string;
+    badgeType?: PhysicalCardStat;
+}
+/** An open tip: which control, how (passive hover or the touch dialog), where, and the content. */
+export interface PhysicalCardTipState extends PhysicalCardTip {
+    /** The control's key (e.g. `ta:<id>`, `imp:<type>:<id>`, `dial:<value>`). */
+    key: string;
+    mode: 'hover' | 'dialog';
+    anchor: {
+        x: number;
+        y: number;
+        preferAbove?: boolean;
+    };
+    trigger: HTMLElement;
+}
+/** A control that opens a tip: its key and content. */
+export interface PhysicalCardTipTarget {
+    key: string;
+    tip: PhysicalCardTip;
+}
+/** Team ability button in the title (or on the bystander token's stripe). */
+export interface PhysicalCardTeamAbility extends PhysicalCardTipTarget {
+    /** Accessible label (e.g. "Team ability: Avengers"). */
+    label: string;
+    iconSrc: string;
+}
+/** A group of improved abilities (movement or targeting) on the strip above the dial. */
+export interface PhysicalCardImprovedGroup {
+    kind: 'movement' | 'targeting';
+    kindIconSrc: string;
+    kindLabel: string;
+    abilities: (PhysicalCardTipTarget & {
+        label: string;
+        iconSrc: string;
+    })[];
+}
+/** A text block (special power, trait, effect), translated and assembled. */
+export interface PhysicalCardRule {
+    name?: string;
+    /** Drawn text (the game symbols already swapped in by the app). */
+    text: ReactNode;
+    /** Text copied when the paragraph is tapped. */
+    copyText: string;
+    icon?: ReactNode;
+}
+/** The front's portrait: the character's art, the terrain's art or an object token. */
+export type PhysicalCardToken = 
+/** The character's portrait, drawn by the app with the class the card asks for. */
+{
+    kind: 'portrait';
+    render: (className: string) => ReactNode;
+} | {
+    kind: 'terrain';
+    src: string;
+    alt: string;
+} | {
+    kind: 'object';
+    src?: string;
+    alt: string;
+    color?: string | null;
+};
+/** A cell of the bystander's dial (a single click). */
+export interface PhysicalCardBystanderCell {
+    stat: PhysicalCardStat;
+    value: number;
+    label: string;
+    background?: string;
+    color?: string;
+    special: boolean;
+    /** Without a tip the cell is not a button. */
+    tip?: PhysicalCardTipTarget;
+}
+/** Replica of the bystander's physical token (HCUnits' `BystanderView`). */
+export interface PhysicalCardBystander {
+    art?: {
+        src: string;
+        alt: string;
+    };
+    range?: number | null;
+    rangeLabel: string;
+    targets: number;
+    boltSrc: string;
+    symbols: Partial<Record<PhysicalCardStat, string>>;
+    /** In an arc on the left: the kind's icon (without `ability`) and each ability. */
+    improved: {
+        kind: 'movement' | 'targeting';
+        iconSrc: string;
+        label: string;
+        ability?: PhysicalCardTipTarget & {
+            label: string;
+            iconSrc: string;
+        };
+    }[];
+    trait?: {
+        src: string;
+        alt: string;
+    };
+    extra?: {
+        kind: 'construct' | 'stack' | 'passengers';
+        src: string;
+        alt: string;
+        text?: ReactNode;
+    };
+    name: string;
+    dial?: {
+        label: string;
+        cells: PhysicalCardBystanderCell[];
+    };
+}
+export interface PhysicalCardPoint {
+    index: number;
+    value: number;
+    color: string;
+    /** Accessible label (e.g. "100 pts, starts at click 1"). */
+    label: string;
+}
+/** Measures, backgrounds and seals of the front (the app's layout rules, already applied). */
+export interface PhysicalCardFrontLayout {
+    frontTable: 'normal' | 'long' | 'short' | 'none';
+    frontTableHeight: number;
+    rarityImage?: string | null;
+    dialImage?: string | null;
+    teamUp: boolean;
+    /** Smaller portrait when the dial takes two rows. */
+    smallToken: boolean;
+    improvedTop: number;
+}
+export interface PhysicalCardViewProps {
+    /** The card's backgrounds (front, back and the legacy overlay, when there is one), as addresses the app serves. */
+    images: {
+        front: string;
+        back: string;
+        legacy?: string | null;
+    };
+    layout: PhysicalCardFrontLayout;
+    /** Name in capitals; the type shrinks until it fits the title line. */
+    title: string;
+    gearSrc?: string;
+    /** Lines under the title, in order (object or bystander type, keywords). */
+    headerLines: {
+        kind: 'type' | 'keywords';
+        text: string;
+    }[];
+    teamAbilities: PhysicalCardTeamAbility[];
+    /** Shield drawn in every team ability button. */
+    teamAbilityIcon?: ReactNode;
+    collection: {
+        number: ReactNode;
+        setSources: readonly string[];
+        setTitle?: string;
+    };
+    dimensions?: {
+        text: string;
+        oval: boolean;
+    };
+    token?: PhysicalCardToken;
+    bystander?: PhysicalCardBystander;
+    /** Keyphrase lines of the object, in order, before the effects. */
+    keyphrases?: {
+        key: string;
+        content: ReactNode;
+    }[];
+    relic?: {
+        label: string;
+        value: string;
+    };
+    rules: PhysicalCardRule[];
+    /**
+     * Restarts the split of the text between front and backs when it changes
+     * (piece, language and translated texts).
+     */
+    contentKey: string;
+    improved: PhysicalCardImprovedGroup[];
+    /** The printed dial (a `CombatDialView` with `presentation="printed"`, built by the app) and how many rows it takes. */
+    dial?: {
+        tables: 1 | 2;
+        node: ReactNode;
+    };
+    terrainDial?: {
+        icons: {
+            range: {
+                src: string;
+                alt: string;
+            };
+            giantReach: {
+                src: string;
+                alt: string;
+            };
+            damage: {
+                src: string;
+                alt: string;
+            };
+            destroy: {
+                src: string;
+                alt: string;
+            };
+        };
+        values: [ReactNode, ReactNode, ReactNode];
+    };
+    /** Points on the front's bar: the point value buttons, an object's line, or nothing. */
+    points: {
+        kind: 'none';
+    } | {
+        kind: 'object';
+        values: string;
+        suffix: string;
+    } | {
+        kind: 'normal' | 'long' | 'short';
+        label: string;
+        items: PhysicalCardPoint[];
+        selectedIndex: number;
+    };
+    onSelectPoint: (point: PhysicalCardPoint) => void;
+    /** The last back's black bar: real name and source, already in capitals. */
+    backBar: {
+        realName?: {
+            label: string;
+            value: string;
+        };
+        source?: {
+            label: string;
+            value: string;
+        };
+    };
+    labels: {
+        /** The front's label (e.g. "Batman · card front"). */
+        front: string;
+        /** Each back's label (`index` from 0). */
+        back: (index: number, count: number) => string;
+    };
+    onCopy: (text: string) => void;
+    /** Desktop: the front fits whole in the visible height of the scrolling area (`fitHeightWithin`). */
+    fitHeight?: boolean;
+    /** Selector of the scrolling area, looked up from the card, for `fitHeight`. */
+    fitHeightWithin?: string;
+    /** Focus view: one side at a time, with the `focusActions` buttons below. */
+    focus?: boolean;
+    /** Holding the card with a finger (outside the focus view) asks for the focus view. */
+    onRequestFocus?: () => void;
+    /** The focus view's buttons; `flip` turns to the next side (`nextSide`: 0 is the front). */
+    focusActions?: (state: {
+        nextSide: number;
+        backs: number;
+        flip: () => void;
+    }) => ReactNode;
+    /** The open tip, controlled by the caller. */
+    tip: PhysicalCardTipState | null;
+    onTipChange: Dispatch<SetStateAction<PhysicalCardTipState | null>>;
+    /** `id` of the tip element, for the hover's `aria-describedby`. */
+    tipId: string;
+    /** The tip drawn by the app, while `tip` is set. */
+    tipSlot?: ReactNode;
+}
+export interface PhysicalCardFocusViewProps {
+    /** The dialog's accessible name (the piece's name). */
+    label: string;
+    onClose: () => void;
+    /** A second card with `focus`, usually the app's adapter again. */
+    children: ReactNode;
+}
+/**
+ * The card's focus view: a full-screen modal dialog over a dimmed, blurred
+ * background. Inside goes a second card with `focus`; tapping outside it (after
+ * the finger that opened it is lifted) or Esc calls `onClose`.
+ */
+export declare function PhysicalCardFocusView({ label, onClose, children }: PhysicalCardFocusViewProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The physical card (front and backs in HCUnits' format), presentation only. It
+ * gets everything resolved: backgrounds, seals, texts already translated and
+ * assembled, symbol addresses, the printed dial ready and the points. It handles
+ * the scale, the split of the text between front and backs, the tilt and shine,
+ * holding to open the focus view and flipping in it, and opens the tips through
+ * `onTipChange`; drawing the tip, translating and copying are the caller's.
+ */
+export declare const PhysicalCardView: import("react").ForwardRefExoticComponent<PhysicalCardViewProps & import("react").RefAttributes<HTMLDivElement>>;
+/**
+ * A faithful port of hcmaps.net's map drawing engine (map.js / tile.js / edge.js /
+ * wall.js), the same engine HCUnits uses to draw the map's canvas. It reads the
+ * same JSON (the piece's map) and draws it 1:1 locally, with no runtime
+ * dependency on their scripts. Credit: hcmaps.net (original engine in JS).
+ */
+export declare const MAP_TILE_SIZE = 64;
+export declare const MAP_ELEVATION_TILE_COLORS: string[];
+export declare const MAP_TERRAIN_TILE_COLORS: Record<string, string>;
+export declare const MAP_TERRAIN_EDGE_COLORS: Record<string, string>;
+export declare const MAP_ELEVATION_EDGE_COLOR = "#FF0000";
+export declare const MAP_INDOOR_EDGE_COLOR = "#FFFF00";
+export declare const MAP_WALL_COLORS: Record<string, string>;
+interface JsonLabel {
+    text: string;
+    color?: string;
+    rotate?: number;
+}
+interface JsonTile {
+    terrain?: string;
+    type?: string;
+    elevation?: number | string;
+    isStartingZone?: boolean;
+    isStartingZone4p?: boolean;
+    group?: number;
+    label?: JsonLabel;
+}
+interface JsonWall {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    type?: string;
+}
+interface JsonRamp {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+}
+export interface HCMapJson {
+    name?: string;
+    width: number;
+    height: number;
+    type?: string;
+    defaultTerrain?: string;
+    defaultElevation?: number;
+    defaultType?: string;
+    defaultWallType?: string;
+    hideLabels?: boolean;
+    rows: {
+        tiles: JsonTile[];
+    }[];
+    walls?: JsonWall[];
+    ramps?: JsonRamp[];
+    ziplines?: JsonWall[];
+}
+export declare class HCMap {
+    width: number;
+    height: number;
+    type: string;
+    private tiles;
+    private walls;
+    private ziplines;
+    constructor(json: HCMapJson);
+    private getTile;
+    private tryAddEdge;
+    draw(ctx: CanvasRenderingContext2D): void;
+    private drawWall;
+}
+export declare function mapSquare(map: HCMapJson, x: number, y: number): {
+    x: number;
+    y: number;
+    terrain: string;
+    elevation: string | number;
+    environment: string;
+    starting: boolean;
+    label: string | undefined;
+};
+export type MapSquare = ReturnType<typeof mapSquare>;
+/** A text elevation exists in the hcmaps format; the 2D drawing treats it as an elevated level. */
+export declare function mapElevationLevel(elevation: number | string): number;
+export declare function mapMaxLevel(map: HCMapJson): number;
+export interface MapInspection {
+    square: MapSquare;
+    adjacent?: MapSquare;
+    line?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    wall?: string;
+}
+/** Coordinates are in squares; wall tolerance is based on screen pixels by the caller. */
+export declare function inspectMap(map: HCMapJson, x: number, y: number, tolerance?: number): MapInspection | null;
+export declare function mapSquareCoordinate(square: Pick<MapSquare, 'x' | 'y'>): string;
+/**
+ * The 3D model's scene, with no drawing. It uses only what the map JSON has:
+ * terrain, elevation, environment, walls, ramps and ziplines. Blocking follows
+ * the game's rule: indoor goes up to the map's highest elevation, outdoor takes
+ * one elevation. Walls, water and obscuring have no height in the data: those
+ * are conventions.
+ */
+export declare const MAP_SCENE_LEVEL_HEIGHT = 0.62;
+export declare const MAP_SCENE_BASE_Z = -0.34;
+export interface MapSceneCell extends MapSquare {
+    level: number;
+    /** The square's floor, without the terrain's volume. */
+    floor: number;
+    top: number;
+}
+export interface MapSceneWall {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    type: string;
+    z0: number;
+    z1: number;
+}
+export interface MapSceneRamp {
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    from: number;
+    to: number;
+}
+export interface MapSceneLine {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    z: number;
+}
+export interface MapScene {
+    width: number;
+    height: number;
+    cells: MapSceneCell[];
+    walls: MapSceneWall[];
+    ramps: MapSceneRamp[];
+    ziplines: MapSceneLine[];
+    maxTop: number;
+}
+export declare function mapSceneCell(scene: Pick<MapScene, 'width' | 'height' | 'cells'>, x: number, y: number): MapSceneCell | null;
+export declare function buildMapScene(map: HCMapJson): MapScene;
+export interface MapCamera {
+    azimuth: number;
+    tilt: number;
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+export interface MapViewport {
+    width: number;
+    height: number;
+}
+export declare const MAP_DEFAULT_CAMERA: MapCamera;
+/** 90 is the flat view from above. Below the minimum the board becomes a line. */
+export declare const MAP_TILT_RANGE: readonly [6, 90];
+export declare const MAP_ZOOM_RANGE: readonly [1, 6];
+export declare const clampMapValue: (value: number, min: number, max: number) => number;
+export interface MapProjection {
+    scale: number;
+    sin: number;
+    cos: number;
+    point(x: number, y: number, z: number): [number, number];
+    /** Larger = closer to the viewer. */
+    depth(x: number, y: number): number;
+    /** From the screen to the map, on a plane at height `z`. */
+    ground(px: number, py: number, z: number): [number, number];
+}
+export declare function makeMapProjection(scene: MapScene, camera: MapCamera, viewport: MapViewport): MapProjection;
+/** The map's center may go as far as any of its corners reaches the middle of the screen. */
+export declare function clampMapPan(scene: MapScene, camera: MapCamera, viewport: MapViewport): MapCamera;
+/** Zooms keeping the point at `anchor` (measured from the screen's center) still. */
+export declare function zoomMapCamera(scene: MapScene, camera: MapCamera, viewport: MapViewport, factor: number, anchor?: {
+    x: number;
+    y: number;
+}): MapCamera;
+/** A square's four sides: the edge's points, the neighbor and the normal. */
+export declare const MAP_CELL_SIDES: readonly [{
+    readonly ax: 0;
+    readonly ay: 1;
+    readonly bx: 0;
+    readonly by: 0;
+    readonly dx: -1;
+    readonly dy: 0;
+}, {
+    readonly ax: 1;
+    readonly ay: 0;
+    readonly bx: 1;
+    readonly by: 1;
+    readonly dx: 1;
+    readonly dy: 0;
+}, {
+    readonly ax: 0;
+    readonly ay: 0;
+    readonly bx: 1;
+    readonly by: 0;
+    readonly dx: 0;
+    readonly dy: -1;
+}, {
+    readonly ax: 1;
+    readonly ay: 1;
+    readonly bx: 0;
+    readonly by: 1;
+    readonly dx: 0;
+    readonly dy: 1;
+}];
+/**
+ * From the screen to map coordinates, testing from front to back. Returns the
+ * point in `inspectMap`'s terms, so the tooltip and selection match the 2D board.
+ */
+export declare function pickMapScene(scene: MapScene, view: MapProjection, px: number, py: number): {
+    x: number;
+    y: number;
+} | null;
+type Point = readonly [number, number];
+/**
+ * The target's squares inside the board and their outer outline, in map coordinates.
+ * Corners are where the outline turns or ends: the volume's edges rise there.
+ */
+export declare function mapFootprintOutline({ x, y, width, height, cells }: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    cells?: readonly (readonly boolean[])[] | null;
+}, boardWidth: number, boardHeight: number): {
+    squares: Point[];
+    edges: [Point, Point][];
+    corners: Point[];
+};
+export interface MapSceneFootprint {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    valid: boolean;
+    /** Occupied squares (`cells[y][x]`, from the corner); without it, the whole rectangle. */
+    cells?: readonly (readonly boolean[])[] | null;
+}
+export interface MapSceneHighlight {
+    square?: {
+        x: number;
+        y: number;
+    };
+    line?: {
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+    };
+    /** The target of a piece being moved: floor and volume, cut to the board. */
+    footprint?: MapSceneFootprint;
+}
+export declare function drawMapScene(ctx: CanvasRenderingContext2D, scene: MapScene, view: MapProjection, texture: HTMLCanvasElement, highlight?: MapSceneHighlight | null, { tufts }?: {
+    tufts?: boolean;
+}): void;
+/** The thumbnail's default height, in pixels. */
+export declare const MAP_THUMBNAIL_HEIGHT = 192;
+/**
+ * The map's thumbnail as a PNG data URL: draws with the engine at full resolution
+ * and scales down to `height` pixels. Gets the JSON already fetched; `null` when it
+ * has no dimensions or the browser gives no 2D context.
+ */
+export declare function renderMapThumbnail(json: HCMapJson, height?: number): string | null;
+export interface MapBoardViewProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'onPointerDown' | 'onPointerMove' | 'onPointerLeave'> {
+    /** The hcmaps JSON, already fetched and checked. */
+    map: HCMapJson;
+    /** The drawing's accessible name, in the app's language (the map's name or a generic one). */
+    canvasLabel: string;
+    /** What is inspected: the square is shaded; an edge becomes a line. */
+    selection?: Pick<MapInspection, 'square' | 'line'> | null;
+    /** Pointer over the map, in squares (0..width, 0..height), and the screen point. Touch counts only on press; mouse and pen also while passing over. */
+    onInspect?(x: number, y: number, clientX: number, clientY: number): void;
+    /** The mouse or pen left the map. */
+    onLeave?(): void;
+    /** Drawing failed (a JSON outside the expected format). */
+    onDrawError?(): void;
+}
+/**
+ * The map's 2D board: the hcmaps drawing in a canvas and, over it, the inspection's
+ * highlight. Gets the map already fetched; fetching, translating and deciding what
+ * the tooltip shows are the caller's. Other attributes (role, focus, keyboard,
+ * `aria-*`, `data-*`) go to the container.
+ */
+export declare const MapBoardView: import("react").ForwardRefExoticComponent<MapBoardViewProps & import("react").RefAttributes<HTMLDivElement>>;
+export interface MapBoardPlaceholderProps {
+    /** Read by screen readers while the map loads (e.g. "Loading map"). */
+    label: string;
+}
+/** The map's place while it loads: the empty grid in a map's proportion. The label is visually hidden. */
+export declare function MapBoardPlaceholder({ label }: MapBoardPlaceholderProps): import("react/jsx-runtime").JSX.Element;
+export interface MapSwatchProps {
+    /** The square's fill, as on the board. */
+    fill: string;
+    /** The square's border (the terrain's or the elevation's color). */
+    edge: string;
+    /** Number inside the square (the elevation's level). */
+    children?: number;
+    /** White text, for dark fills. */
+    lightText?: boolean;
+}
+/** A legend square with a map square's fill and border. Decorative. */
+export declare function MapSwatch({ fill, edge, children, lightText }: MapSwatchProps): import("react/jsx-runtime").JSX.Element;
+/** One inspected square, resolved: texts in the app's language and the board's colors. */
+export interface MapTooltipSquare {
+    /** Coordinate (e.g. "H8"); shown only when the title is not the coordinate itself. */
+    coordinate?: string;
+    terrain: {
+        label: string;
+        fill: string;
+        edge: string;
+    };
+    elevation: {
+        level: number;
+        label: string;
+        fill: string;
+        edge: string;
+        lightText?: boolean;
+    };
+    /** The square's environment, e.g. a `MapEnvironmentView`. */
+    environment?: ReactNode;
+    /** Text in place of the environment, when the map does not say (e.g. "Environment unspecified"). */
+    environmentNote?: string;
+    /** Notes, in order (what fills a blocking square, starting area, the square's label). */
+    notes?: readonly string[];
+}
+export interface MapTooltipViewProps {
+    id?: string;
+    /** Screen point (viewport coordinates) the tooltip opens next to. A new object moves it. */
+    anchor: {
+        x: number;
+        y: number;
+    };
+    title: string;
+    /** The wall's color, when the inspected point is a wall. */
+    wallColor?: string;
+    /** One square, or two on an edge between squares. */
+    squares: readonly MapTooltipSquare[];
+}
+/**
+ * The map inspection's tooltip: the title (wall, edge or coordinate) and what is in
+ * each square. It is `position: fixed`, next to `anchor`, without leaving the
+ * screen; to take it out of a container with overflow, the caller portals it.
+ */
+export declare function MapTooltipView({ id, anchor, title, wallColor, squares }: MapTooltipViewProps): import("react/jsx-runtime").JSX.Element;
+export interface MapLegendItem {
+    fill: string;
+    edge: string;
+    /** Visible name, in the app's language; also the item's key. */
+    label: string;
+}
+export interface MapLegendViewProps {
+    items: readonly MapLegendItem[];
+    /** After the items, e.g. the map's environments (`MapEnvironmentView`). */
+    children?: ReactNode;
+}
+/** The 3D model's legend: a small square and the name of each terrain on the map. */
+export declare function MapLegendView({ items, children }: MapLegendViewProps): import("react/jsx-runtime").JSX.Element;
+export type MapEnvironmentKind = 'indoor' | 'outdoor';
+/** The map's types (`indoor`, `outdoor`, `indoorOutdoor`, in any spelling) as environments, without repeats. */
+export declare function mapEnvironments(types: readonly string[]): MapEnvironmentKind[];
+export interface MapEnvironmentViewProps {
+    types: readonly string[];
+    /** Each environment's icon address (black line icons; the dark theme turns them light). */
+    icons: Record<MapEnvironmentKind, string>;
+    /** Each environment's visible name. A game term: HCUI shows it in English in all three languages. */
+    labels: Record<MapEnvironmentKind, string>;
+    className?: string;
+}
+/** The map's environments (indoor / outdoor), each with its icon and name. With no known environment it draws nothing. */
+export declare function MapEnvironmentView({ types, icons, labels, className }: MapEnvironmentViewProps): import("react/jsx-runtime").JSX.Element | null;
 export {};