@ntmats/hc-ui 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-import { type ButtonHTMLAttributes, type HTMLAttributes, type InputHTMLAttributes, type ReactNode } from 'react';
-export type SurfaceTone = 'page' | 'main' | 'content' | 'elevated' | 'overlay';
+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;
+    /** Corner radius of the rounded tones (`content`, `elevated`, `overlay`, `card`): 16, 20 or 24px.
+     * Defaults to `md` (16px), and to `lg` (20px) for `card`, as HCUI's `surface` mixin. */
+    radius?: 'md' | 'lg' | 'xl';
 }
 /** Semantic color role only; placement, elevation and overlay behavior stay local. */
-export declare function Surface({ tone, className, ...props }: SurfaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function Surface({ tone, radius, className, ...props }: SurfaceProps): import("react/jsx-runtime").JSX.Element;
 export interface SegmentedOption<T extends string> {
     value: T;
     label: string;
@@ -21,9 +24,16 @@ export interface SegmentedControlProps<T extends string> extends Omit<HTMLAttrib
     orientation?: 'horizontal' | 'vertical';
     /** Icon-only options: labels stay as accessible names and tooltips. */
     hideLabels?: boolean;
+    /** `static` (default): the chosen option is raised in place. `slide`: one knob slides
+     * under the options, as HCUI's point cost toggle; options are laid out at equal width. */
+    indicator?: 'static' | 'slide';
+    /** Every option as wide as the widest one (or as `optionWidth`). */
+    equalWidth?: boolean;
+    /** Fixed width of each option in px; implies `equalWidth`. */
+    optionWidth?: number;
 }
 /** Controlled, single-choice control with radio semantics and roving focus. */
-export declare function SegmentedControl<T extends string>({ label, value, options, onChange, density, orientation, hideLabels, className, ...props }: SegmentedControlProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare function SegmentedControl<T extends string>({ label, value, options, onChange, density, orientation, hideLabels, indicator, equalWidth, optionWidth, className, style, ...props }: SegmentedControlProps<T>): import("react/jsx-runtime").JSX.Element;
 export type ButtonVariant = 'secondary' | 'primary' | 'outline' | 'danger';
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: ButtonVariant;
@@ -46,18 +56,99 @@ export interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
     /** 36, 40 or 44px. The 36px size keeps a 44px touch target. */
     size?: 'sm' | 'md' | 'lg';
     tone?: 'primary' | 'secondary';
+    /** Fill: `muted` (default, HCUI `icon-button`), `surface` (surface with the card ring
+     * and shadow, HCUI's mobile theme button), `outline` (surface with a 1px border ring,
+     * HCUI's mobile sort button) or `ghost` (no fill until hover). */
+    variant?: 'muted' | 'surface' | 'outline' | 'ghost';
+    /** `circle` (default) or `rounded` (a 12px-radius square, HCUI's desktop utilities). */
+    shape?: 'circle' | 'rounded';
     /** Toggle state (`aria-pressed`); omit for a plain action. */
     selected?: boolean;
+    /** When set, the icon is keyed by it and enters with a short turn and fade each time it
+     * changes (and on first render), as HCUI's theme button swaps sun and moon. */
+    iconKey?: string | number;
 }
 /** Round icon-only button (back, close, options). */
 export declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
-export interface ChipProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+interface ChipBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     /** Toggle state for filters; omit for a plain action chip. */
     selected?: boolean;
     icon?: ReactNode;
+    /**
+     * `md` (default): 36px, 13px text (HCUI `chip`). `sm`: 36px, 12px text and 12px padding (HCUI's
+     * desktop filter pills and sort trigger). `xs`: 26px, 11px text, muted fill without ring (HCUI's
+     * desktop quick filters and chosen-value tags); selected turns to the contrast fill.
+     */
+    size?: 'md' | 'sm' | 'xs';
+    /** `outline` (default), or `quiet`: lighter ring and secondary text, bolder once applied (HCUI's rule filter pills). */
+    variant?: 'outline' | 'quiet';
+    /** A filter with values applied: a 1.5px ring in the primary text color (and primary, bolder text when `quiet`). */
+    applied?: boolean;
+    /**
+     * Muted number after the label, such as how many results a quick filter keeps. A number
+     * shows as given, 0 included (HCUI's quick filters show "0"); hidden when `undefined`, `null`, `false` or `''`.
+     */
+    count?: ReactNode;
+    /**
+     * Filled badge after the label: how many values a filter has applied. Shows 0 too; pass
+     * `undefined` (e.g. `badge={n || undefined}`) to hide it when nothing is applied.
+     */
+    badge?: ReactNode;
+    /**
+     * Down chevron at the end. On by default when the chip opens a popup (`aria-haspopup`,
+     * which `Menu` and `Popover` give their trigger); `aria-expanded="true"` draws the ring.
+     */
+    chevron?: boolean;
+    /**
+     * Adds a separate remove button (×) after the text. The chip then renders as a `span`
+     * holding the main button (ref, `onClick`, `aria-pressed`; a plain `span` when there is
+     * no `onClick`, as a chosen-value tag) and the remove button. `className` and `style` go on the `span`.
+     * Requires `clearLabel`.
+     */
+    onClear?: (event: MouseEvent<HTMLButtonElement>) => void;
+    /** Accessible name and tooltip of the remove button (e.g. "Remover Batman"); required with `onClear`. */
+    clearLabel?: string;
 }
-/** Filter or option chip. Selected chips are filled with the accent color. */
+/** `Chip` props: with `onClear`, `clearLabel` is required, so the remove button always has a name. */
+export type ChipProps = ChipBaseProps & ({
+    onClear?: undefined;
+    clearLabel?: string;
+} | {
+    onClear?: (event: MouseEvent<HTMLButtonElement>) => void;
+    clearLabel: string;
+});
+/**
+ * Filter or option chip. Selected chips are filled with the accent color. As a filter
+ * trigger it takes a `badge` with the number of values applied, `applied`, and the
+ * chevron and ring of an open popup; `onClear` adds a remove button.
+ */
 export declare const Chip: import("react").ForwardRefExoticComponent<ChipProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface FilterBarProps extends HTMLAttributes<HTMLDivElement> {
+    /** Accessible name of the group (e.g. "Filtros"). */
+    label: string;
+    /** Before the filters, on the same line (a search field, "Filtros avançados"). */
+    start?: ReactNode;
+    /** After the filters, at the end of the line (a sort menu, a view toggle). */
+    end?: ReactNode;
+    /** Under the line: chosen-value tags, "Limpar tudo". */
+    footer?: ReactNode;
+    /**
+     * `wrap`: the filters wrap onto more lines (desktop). `scroll`: one line that scrolls
+     * sideways with a hidden scrollbar (phones). `auto` (default): `scroll` below 960px and
+     * `wrap` from 960px, by a CSS media query (HCUI's cut).
+     */
+    layout?: 'wrap' | 'scroll' | 'auto';
+    /** Space between filters: 8px (`comfortable`, default) or 4px (`compact`, HCUI's desktop quick filters). */
+    density?: 'comfortable' | 'compact';
+    /** A band that sticks to the top of the scrolling panel, with the surface fill and 8px above and below (HCUI's desktop filter bar). The offset is `--hc-filter-bar-top`. */
+    sticky?: boolean;
+}
+/**
+ * Layout of a row of filters (`Chip`s) with optional `start`, `end` and `footer` slots.
+ * Presentation only: which filters exist, their values, the search rules and persistence
+ * are the caller's. A scrolling row bleeds into the page gutter by `--hc-filter-bar-bleed`.
+ */
+export declare const FilterBar: import("react").ForwardRefExoticComponent<FilterBarProps & import("react").RefAttributes<HTMLDivElement>>;
 export interface FieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /** Accessible name. Visible above the field unless `hideLabel` is set. */
     label: string;
@@ -84,3 +175,1424 @@ export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
  * enclosing region announces loading once (role="status" + label).
  */
 export declare function Skeleton({ width, height, circle, className, style, ...props }: SkeletonProps): import("react/jsx-runtime").JSX.Element;
+interface MeterOwnProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children' | 'role'> {
+    /** Current amount, such as a team's points. May exceed `max`. */
+    value: number;
+    /** The limit the value is measured against; the minimum is 0. */
+    max: number;
+    /** Spoken value (`aria-valuetext`); defaults to `"<value> / <max>"`. */
+    valueText?: string;
+    /** Bar height in px: 3 (HCUI's mobile team bar), 4 (desktop sidebar draft) or 5 (team rules bar). */
+    thickness?: 3 | 4 | 5;
+    /** Track behind the fill: `muted` (bg-muted), `border` (color-border) or `none` (fill only). */
+    track?: 'muted' | 'border' | 'none';
+    /** Leading end of the fill: rounded, or cut square against the track. */
+    cap?: 'round' | 'square';
+    /**
+     * Above the limit: `clamp` fills the whole bar; `mark` scales the bar to the value
+     * and draws a 2px line where the limit is, in the text color so it shows over the danger fill.
+     */
+    overflow?: 'clamp' | 'mark';
+    /** `auto` turns `over` (danger) when value > max; `default` and `over` force a tone. */
+    tone?: 'auto' | 'default' | 'over';
+    /** Transition the fill's width (none under reduced motion). */
+    animated?: boolean;
+}
+export type MeterProps = MeterOwnProps & (
+/** `label` is the accessible name; the visible text ("375 / 300 pts") stays with the caller. */
+{
+    label: string;
+    decorative?: false;
+}
+/** Hidden from assistive technology, for when the numbers are already next to it. */
+ | {
+    decorative: true;
+    label?: string;
+});
+/**
+ * Bar of a value against a limit (`role="meter"`), with an over-the-limit tone. It
+ * renders only spans, so it fits inside a button. Placement (absolute, grid) is the caller's.
+ */
+export declare const Meter: import("react").ForwardRefExoticComponent<MeterProps & import("react").RefAttributes<HTMLSpanElement>>;
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
+    /** 20px (touch lists, sheets) or 16px (dense desktop lists). */
+    size?: 'sm' | 'md';
+    /** Mixed state. Visual only: the value still comes from `checked`. */
+    indeterminate?: boolean;
+}
+/**
+ * Native checkbox laid transparently over a drawn box, so keyboard, focus, form
+ * and `<label>` behave as usual. Wrap it in a `<label>` (the whole row becomes the
+ * target) or pass `aria-label`; the caller supplies the text.
+ */
+export declare const Checkbox: import("react").ForwardRefExoticComponent<CheckboxProps & import("react").RefAttributes<HTMLInputElement>>;
+export interface DialogProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'title' | 'open' | 'onClose' | 'onCancel'> {
+    /** Controlled: the dialog shows while `open` is true and plays its exit before unmounting. */
+    open: boolean;
+    /**
+     * Asked to close: Esc and a backdrop click (when `dismissible`) and the close
+     * button. The dialog stays open until the caller sets `open` to false.
+     */
+    onClose: () => void;
+    /** Visible heading; it names the dialog (`aria-labelledby`). */
+    title: ReactNode;
+    /** Short text under the title; it describes the dialog (`aria-describedby`). */
+    description?: ReactNode;
+    children?: ReactNode;
+    /** Slot for the buttons (Cancel | Confirm). */
+    actions?: ReactNode;
+    /** Shows a close button with this accessible name. No close button by default. */
+    closeLabel?: string;
+    /** Icon for the close button; an inline X by default. */
+    closeIcon?: ReactNode;
+    /** `sm`: 400px confirmation (HCUI ConfirmDialog). `md`: 440px panel with header, scrolling body and footer (HCUI Sheet on desktop). */
+    size?: 'sm' | 'md';
+    /** Esc and a backdrop click ask to close. Default true. */
+    dismissible?: boolean;
+}
+/**
+ * Centered modal dialog on the native `<dialog>` and `showModal()`: the browser
+ * keeps it in the top layer, makes the rest of the page inert and traps Tab.
+ * The caller owns `open` and the texts; the dialog only asks to close.
+ */
+export declare const Dialog: import("react").ForwardRefExoticComponent<DialogProps & import("react").RefAttributes<HTMLDialogElement>>;
+export type SheetPresentation = 'bottom' | 'center' | 'auto';
+export interface SheetProps extends Omit<DialogProps, 'size' | 'actions' | 'description' | 'closeLabel'> {
+    /** Accessible name of the close button, which every sheet shows. */
+    closeLabel: string;
+    /** Slot under the scrolling body, for the buttons (Clear | Done). */
+    footer?: ReactNode;
+    /**
+     * `bottom`: rises from the bottom edge, full width, with a grabber and drag to close.
+     * `center`: the centered panel (`Dialog size="md"`). `auto` (default): `bottom` below
+     * 960px and `center` from 960px, by a CSS media query (HCUI's cut).
+     */
+    presentation?: SheetPresentation;
+    /** Maximum width of the centered panel, in px. Default 440. */
+    width?: number;
+}
+/**
+ * Modal sheet on the `Dialog` base (native `<dialog>`, `showModal()`): the same focus,
+ * Tab trap, Esc, focus return, scroll lock, stacking and controlled `open`/`onClose`.
+ * At the bottom it has a grabber, drag to close (past 20% of its height or a quick
+ * flick) and drag up from the grabber or header to full height; content that has
+ * scrolled down scrolls back before the sheet moves.
+ */
+export declare const Sheet: import("react").ForwardRefExoticComponent<SheetProps & import("react").RefAttributes<HTMLDialogElement>>;
+export interface SheetOption<T extends string> {
+    value: T;
+    label: ReactNode;
+    /** Second line, in a muted color. */
+    hint?: ReactNode;
+    /** Decorative icon before the text; pass it already sized (18px in HCUI). */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+interface SheetChoiceProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange' | 'role'> {
+    /** Accessible name of the group. */
+    label: string;
+    /** The chosen value; one that matches no option leaves the group with none chosen. */
+    value: T;
+    /** NoInfer: `T` comes from `value` and `options`, so a state setter cannot widen it to string. */
+    onChange: (value: NoInfer<T>) => void;
+}
+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;
+export interface SheetChipsProps<T extends string> extends SheetChoiceProps<T> {
+    options: readonly {
+        value: T;
+        label: ReactNode;
+        disabled?: boolean;
+    }[];
+}
+/** Single-choice group of `Chip`s that wrap (HCUI's SheetChips), for inside a sheet. */
+export declare function SheetChips<T extends string>({ label, options, value, onChange, className, ...props }: SheetChipsProps<T>): import("react/jsx-runtime").JSX.Element;
+export type PopupSide = 'bottom' | 'top';
+export type PopupAlign = 'start' | 'end';
+/** Props a trigger receives: spread them on the element that opens the popup. */
+export interface PopupTriggerProps {
+    ref: (node: HTMLElement | null) => void;
+    'aria-haspopup': 'menu' | 'dialog';
+    'aria-expanded': boolean;
+    'aria-controls': string | undefined;
+    onClick: (event: MouseEvent<HTMLElement>) => void;
+    onKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+}
+/** An element (it gets the props merged in) or a render function that spreads them. */
+export type PopupTrigger = ReactElement | ((props: PopupTriggerProps, state: {
+    open: boolean;
+}) => ReactNode);
+interface PopupBaseProps {
+    /** Controlled open state; omit it (and use `defaultOpen`) to let the popup own it. */
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** Preferred side; it flips when there is no room. Default `bottom`. */
+    side?: PopupSide;
+    /** Edge shared with the trigger; it flips when there is no room. Default `end`. */
+    align?: PopupAlign;
+    /**
+     * Render in a portal: `true` uses the trigger's open `<dialog>` (so it stays in the
+     * top layer) or `document.body`; an element is used as is. The portal keeps
+     * `data-hc-ds` and the trigger's `data-theme`. Default false: the popup is placed
+     * right after the trigger and inherits everything.
+     */
+    portal?: boolean | HTMLElement;
+    /** Theme for the portal; read from the trigger's scope by default. */
+    theme?: 'light' | 'dark';
+    /** Class of the wrapper around the trigger (the popup's positioning box). */
+    anchorClassName?: string;
+}
+type Rect = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+/** Keeps the preferred side and edge when the popup fits; otherwise flips to the roomier one. */
+export declare function placePopup(trigger: Rect, size: {
+    width: number;
+    height: number;
+}, boundary: Rect, side: PopupSide, align: PopupAlign): {
+    side: PopupSide;
+    align: PopupAlign;
+};
+export interface MenuProps extends PopupBaseProps, Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'children'> {
+    /** Accessible name of the menu (`aria-label`). */
+    label: string;
+    /** The button that opens it. It gets `aria-haspopup="menu"`, `aria-expanded`, `aria-controls` and the handlers. */
+    trigger: PopupTrigger;
+    children: ReactNode;
+}
+/**
+ * Menu button: actions (`MenuItem`), one choice (`MenuRadioGroup` + `MenuItemRadio`),
+ * toggles (`MenuItemCheckbox`), `MenuSeparator` and `MenuLabel`. Arrows, Home/End and
+ * typing move between items; Enter/Space choose; Esc closes and returns focus to the
+ * trigger; Tab closes and moves on; a press outside closes.
+ */
+export declare const Menu: import("react").ForwardRefExoticComponent<MenuProps & import("react").RefAttributes<HTMLDivElement>>;
+interface MenuItemBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'role' | 'onSelect'> {
+    /** Decorative icon at the end of the row; pass it already sized (15px in HCUI). */
+    icon?: ReactNode;
+    /** Second line in muted, smaller text. */
+    hint?: ReactNode;
+    /** Destructive action: drawn in the danger color. */
+    danger?: boolean;
+}
+export interface MenuItemProps extends MenuItemBaseProps {
+    /** Runs the action. Call `event.preventDefault()` to keep the menu open. */
+    onSelect?: (event: MouseEvent<HTMLButtonElement>) => void;
+}
+/** An action (`menuitem`). It closes the menu; focus returns to the trigger unless the action moved it. */
+export declare const MenuItem: import("react").ForwardRefExoticComponent<MenuItemProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface MenuRadioGroupProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'onChange'> {
+    value: T;
+    onValueChange: (value: NoInfer<T>) => void;
+    /** Accessible name of the group, when the menu holds more than one. */
+    label?: string;
+}
+/** One choice among `MenuItemRadio`s, such as a sort order. */
+export declare function MenuRadioGroup<T extends string>({ value, onValueChange, label, className, children, ...props }: MenuRadioGroupProps<T>): import("react/jsx-runtime").JSX.Element;
+export interface MenuItemRadioProps extends MenuItemBaseProps {
+    value: string;
+}
+/** A `menuitemradio`: the chosen one is bold with a check. Choosing closes the menu and returns focus to the trigger. */
+export declare const MenuItemRadio: import("react").ForwardRefExoticComponent<MenuItemRadioProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface MenuItemCheckboxProps extends MenuItemBaseProps {
+    checked: boolean;
+    onCheckedChange: (checked: boolean) => void;
+    /** Close after toggling. Default false, so several toggles take one opening. */
+    closeOnSelect?: boolean;
+}
+/** A `menuitemcheckbox`: toggles in place, with a check while on. */
+export declare const MenuItemCheckbox: import("react").ForwardRefExoticComponent<MenuItemCheckboxProps & import("react").RefAttributes<HTMLButtonElement>>;
+/** A line between groups of items. */
+export declare function MenuSeparator({ className, ...props }: Omit<HTMLAttributes<HTMLDivElement>, 'role'>): import("react/jsx-runtime").JSX.Element;
+/** Plain text inside the menu, such as a question before a destructive choice. Not focusable. */
+export declare function MenuLabel({ className, ...props }: HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+export interface SortOption<T extends string> {
+    value: T;
+    label: string;
+    /** Second line in the menu. */
+    hint?: ReactNode;
+    disabled?: boolean;
+}
+export interface SortMenuProps<T extends string> extends Omit<MenuProps, 'label' | 'trigger' | 'children' | 'onChange'> {
+    /** Name of the menu, and of the trigger with the current choice ("Ordenar: A–Z"). */
+    label: string;
+    value: T;
+    options: readonly SortOption<T>[];
+    onChange: (value: NoInfer<T>) => void;
+    /** Marks the choice as a filter in effect (the ring of an applied filter). */
+    applied?: boolean;
+    /** Trigger size, as `Chip`. Default `sm` (HCUI's desktop sort trigger). */
+    size?: ChipProps['size'];
+    /** Class of the trigger `Chip`. */
+    triggerClassName?: string;
+}
+/**
+ * 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.
+ */
+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'> {
+    /** Accessible name of the dialog (`aria-label`). */
+    label: string;
+    /** The button that opens it. It gets `aria-haspopup="dialog"`, `aria-expanded`, `aria-controls` and the click handler. */
+    trigger: PopupTrigger;
+    /** Free content; a function receives `close` (focus goes back to the trigger). */
+    children: ReactNode | ((api: {
+        close: () => void;
+    }) => ReactNode);
+    /** Move focus to the first focusable element inside when it opens. Default false: focus stays on the trigger. */
+    autoFocus?: boolean;
+}
+/**
+ * Non-modal dialog anchored to its trigger, with the same placement and dismissal as
+ * `Menu`: Esc closes and returns focus to the trigger, a press outside closes. Tab is
+ * not trapped. The caller supplies the content and its texts. Esc is taken before it
+ * reaches the content (so an enclosing Dialog stays open): a field inside cannot use it.
+ */
+export declare const Popover: import("react").ForwardRefExoticComponent<PopoverProps & import("react").RefAttributes<HTMLDivElement>>;
+export type TableSortDirection = 'ascending' | 'descending';
+export interface TableColumn<Row> {
+    /** Stable id of the column; it is what `sort.key` and `onSort` name. */
+    key: string;
+    /** Header text (or node). For a sortable column it is the name of the sort button. */
+    header: ReactNode;
+    /** What the column shows for a row: free content (an avatar and a name, a formatted number). */
+    cell: (row: Row, index: number) => ReactNode;
+    /** `start` (default), `center` or `end`. Numeric columns default to `end`. */
+    align?: 'start' | 'center' | 'end';
+    /** Figures line up: tabular numbers, aligned to the end unless `align` says otherwise. */
+    numeric?: boolean;
+    /** Column width (a number is px), set on the header cell. Cells are border-box. */
+    width?: number | string;
+    /** The cell names its row: rendered as `<th scope="row">`. With `onRowClick`, its content goes in the row button. */
+    rowHeader?: boolean;
+    /** The header becomes a button that calls `onSort(key)`, and the cell gets `aria-sort`. */
+    sortable?: boolean;
+    /** Text color of the header and the cells: `muted` (a rank) or `secondary` (a category). */
+    tone?: 'muted' | 'secondary';
+    /** Class for the header and every cell of the column (e.g. to hide it in a narrow container). */
+    className?: string;
+}
+export interface TableProps<Row> extends Omit<HTMLAttributes<HTMLTableElement>, 'children' | 'onClick'> {
+    columns: readonly TableColumn<Row>[];
+    rows: readonly Row[];
+    /** Stable key of a row. */
+    rowKey: (row: Row, index: number) => string;
+    /** The column the rows are sorted by, and in which direction. The order of `rows` is the caller's. */
+    sort?: {
+        key: string;
+        direction: TableSortDirection;
+    } | null;
+    /** A sortable header was pressed. The caller decides the new order (toggle, default direction). */
+    onSort?: (key: string) => void;
+    /** The header row sticks to the top of the scrolling ancestor, at `--hc-table-sticky-top` (0 by default). */
+    stickyHeader?: boolean;
+    /** Rows react to a press, and the `rowHeader` cell becomes a button for the keyboard. */
+    onRowClick?: (row: Row, index: number) => void;
+    /** Key of the selected row (the one open in a side panel): filled and marked `aria-current` on its row button. */
+    selectedKey?: string | null;
+}
+/**
+ * Dense data table: a semantic `<table>` whose columns come from props. Presentation only:
+ * the rows, their order and what a press does are the caller's. Sortable headers are buttons
+ * and carry `aria-sort`; `onSort` reports the press.
+ */
+export declare const Table: <Row>(props: TableProps<Row> & {
+    ref?: Ref<HTMLTableElement>;
+}) => ReactElement;
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export interface PageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Page title. */
+    title: ReactNode;
+    /** Heading level of the title: 1 (default), 2 or 3. The look does not change. */
+    level?: HeadingLevel;
+    /** Muted number after the title, inside the heading (e.g. how many teams). Hidden when 0, null or false. */
+    count?: ReactNode;
+    /** At the end of the line: buttons, a menu. */
+    actions?: ReactNode;
+    /** Keeps the heading for assistive technology only, where the page shows its own title. */
+    visuallyHidden?: boolean;
+}
+/** Desktop page header: one line with the title (22px, semibold) and actions at the end. */
+export declare const PageHeader: import("react").ForwardRefExoticComponent<PageHeaderProps & import("react").RefAttributes<HTMLElement>>;
+export interface PanelHeaderStep {
+    label: string;
+    /** Goes back to this step. The last step is the current one and is never a button. */
+    onSelect?: () => void;
+}
+export interface PanelHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+    /** Panel or section title. With `trail`, the last step is the title instead. */
+    title?: ReactNode;
+    /** Heading level of the title: 2 by default. The look does not change. */
+    level?: HeadingLevel;
+    /**
+     * `bar` (default): the header bar of a side panel (52px, a line under it, 13px text).
+     * `section`: a section title (17px, HCUI's `section-title`), with no bar.
+     */
+    variant?: 'bar' | 'section';
+    /** Small uppercase line above the title (HCUI's `eyebrow`). */
+    eyebrow?: ReactNode;
+    /** Muted line under the title. */
+    subtitle?: ReactNode;
+    /** The subtitle follows the title on the same line (baseline), cut with an ellipsis, instead of under it. */
+    subtitleInline?: boolean;
+    /** Decorative icon before the title, in a 36px muted circle (`section`); pass it sized (18px in HCUI). */
+    icon?: ReactNode;
+    /** Steps of a trail (breadcrumb): earlier steps go back with `onSelect`; the last is the title (`aria-current="location"`). */
+    trail?: readonly PanelHeaderStep[];
+    /** Accessible name of the trail's `nav` (e.g. "Trilha do painel"). */
+    trailLabel?: string;
+    /** At the end of the line, before the close button. */
+    actions?: ReactNode;
+    /** Shows a close button (an inline X, or `closeIcon`) that calls it. */
+    onClose?: () => void;
+    /** Accessible name of the close button; give it with `onClose` (e.g. "Fechar painel"). */
+    closeLabel?: string;
+    /** Tooltip of the close button, when it says more than the name (e.g. "Fechar painel (Esc)"). */
+    closeTitle?: string;
+    closeIcon?: ReactNode;
+}
+/** Header of a panel or section: title (or a trail), optional eyebrow, subtitle, icon, actions and close button. */
+export declare const PanelHeader: import("react").ForwardRefExoticComponent<PanelHeaderProps & import("react").RefAttributes<HTMLElement>>;
+export type ListRowProps = ButtonHTMLAttributes<HTMLButtonElement>;
+/**
+ * A tappable list row (HCUI's `list-row` mixin): full width, at least 56px, 8px 16px of padding,
+ * a 12px gap between its children, a translucent veil on hover and press and the focus ring inside.
+ * The content and its semantics (`aria-pressed`, `role="option"`) are the caller's.
+ */
+export declare const ListRow: import("react").ForwardRefExoticComponent<ListRowProps & import("react").RefAttributes<HTMLButtonElement>>;
+export interface CommandPaletteItem {
+    /** Unique among all items. */
+    key: string;
+    label: ReactNode;
+    /** Second, muted line (code, points, a description), cut with an ellipsis. */
+    detail?: ReactNode;
+    /** Slot in a 32px box before the text: an avatar, an icon, a swatch. */
+    icon?: ReactNode;
+    /** Enter or a click. The palette does not close by itself: close it here when it should. */
+    onSelect: () => void;
+    /** ⌘Enter / Ctrl+Enter (HCUI: add the unit to the team). Without it, ⌘Enter selects. */
+    onAltSelect?: () => void;
+    /** Replaces the palette's `altHint` for this item. */
+    altHint?: ReactNode;
+}
+export interface CommandPaletteGroup {
+    key: string;
+    /** Small uppercase title above the group; it names the group. Without it the items follow the previous group. */
+    heading?: ReactNode;
+    items: readonly CommandPaletteItem[];
+}
+export interface CommandPaletteHint {
+    /** Each key is drawn in its own `<kbd>`. */
+    keys: readonly ReactNode[];
+    label: ReactNode;
+}
+export interface CommandPaletteProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'open' | 'onClose' | 'onCancel' | 'children' | 'onChange'> {
+    /** Controlled: shown while true. Esc and a backdrop click call `onClose`. */
+    open: boolean;
+    onClose: () => void;
+    /** Accessible name of the dialog and of the list. */
+    label: string;
+    /** Accessible name of the search field; `label` by default. */
+    inputLabel?: string;
+    placeholder?: string;
+    /** The search text (controlled). A new query makes the first item active. */
+    query: string;
+    onQueryChange: (query: string) => void;
+    /** Results already searched, filtered and capped by the caller, in order. */
+    groups: readonly CommandPaletteGroup[];
+    /** Icon at the start of the field; Iconoir's Search (20px) by default. */
+    searchIcon?: ReactNode;
+    /** While searching: this text shows at the end of the field and the list is `aria-busy`. */
+    loading?: ReactNode;
+    /** Message at the top of the list (nothing found); the caller decides when. */
+    empty?: ReactNode;
+    /** Key shown on the active item (HCUI: ↵). */
+    selectHint?: ReactNode;
+    /** Shown on the active item when it has `onAltSelect` (HCUI: ⌘↵ add). */
+    altHint?: ReactNode;
+    /** Keyboard hints in the footer; no footer without them. */
+    hints?: readonly CommandPaletteHint[];
+    /** Class for the scrolling list (HCUI reserves its scrollbar gutter there). */
+    listClassName?: string;
+}
+/**
+ * HCUI's desktop ⌘K palette: a modal `<dialog>` (`showModal()`, focus in the field,
+ * Esc and the backdrop ask to close, focus returns, page scroll locked) with a search
+ * field that is a combobox over a listbox of groups. Focus stays in the field; arrows
+ * (wrapping), Home and End move the active item (`aria-activedescendant`), which scrolls
+ * into view; Enter selects, ⌘/Ctrl+Enter takes the alternative; the pointer activates the
+ * 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';
+    /** 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 CARD_WIDTH = 375;
+export declare const CARD_HEIGHT = 525;
+export declare const BACK_TABLE_HEIGHT = 440;
+/** Position of each value of the bystander's dial: every row goes 24px down and 7px right. */
+export declare const 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 nextDistribution(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 backCount(pages: number[]): number;
+/** Cursor position on the card (0 to 1) → tilt, parallax (-1 to 1) and shine (%). */
+export declare function tiltAt(x: number, y: number, damping?: number): {
+    rotateX: number;
+    rotateY: number;
+    parallaxX: number;
+    parallaxY: number;
+    shineX: number;
+    shineY: number;
+};
+type CardTilt = ReturnType<typeof tiltAt>;
+/** The finished values each moving part of the card takes, ready for `style`. */
+export declare function tiltStyles(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 devicePosition(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 requestMotionAccess(): 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 TILE_SIZE = 64;
+export declare const ELEVATION_TILE_COLORS: string[];
+export declare const TERRAIN_TILE_COLORS: Record<string, string>;
+export declare const TERRAIN_EDGE_COLORS: Record<string, string>;
+export declare const ELEVATION_EDGE_COLOR = "#FF0000";
+export declare const INDOOR_EDGE_COLOR = "#FFFF00";
+export declare const 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 elevationLevel(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 squareCoordinate(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 LEVEL_HEIGHT = 0.62;
+export declare const BASE_Z = -0.34;
+export interface SceneCell extends MapSquare {
+    level: number;
+    /** The square's floor, without the terrain's volume. */
+    floor: number;
+    top: number;
+}
+export interface SceneWall {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    type: string;
+    z0: number;
+    z1: number;
+}
+export interface SceneRamp {
+    x: number;
+    y: number;
+    dx: number;
+    dy: number;
+    from: number;
+    to: number;
+}
+export interface SceneLine {
+    x0: number;
+    y0: number;
+    x1: number;
+    y1: number;
+    z: number;
+}
+export interface MapScene {
+    width: number;
+    height: number;
+    cells: SceneCell[];
+    walls: SceneWall[];
+    ramps: SceneRamp[];
+    ziplines: SceneLine[];
+    maxTop: number;
+}
+export declare function sceneCell(scene: Pick<MapScene, 'width' | 'height' | 'cells'>, x: number, y: number): SceneCell | null;
+export declare function buildMapScene(map: HCMapJson): MapScene;
+export interface MapCamera {
+    azimuth: number;
+    tilt: number;
+    zoom: number;
+    panX: number;
+    panY: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+}
+export declare const DEFAULT_CAMERA: MapCamera;
+/** 90 is the flat view from above. Below the minimum the board becomes a line. */
+export declare const TILT_RANGE: readonly [6, 90];
+export declare const ZOOM_RANGE: readonly [1, 6];
+export declare const clamp: (value: number, min: number, max: number) => number;
+export interface Projection {
+    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 makeProjection(scene: MapScene, camera: MapCamera, viewport: Viewport): Projection;
+/** The map's center may go as far as any of its corners reaches the middle of the screen. */
+export declare function clampPan(scene: MapScene, camera: MapCamera, viewport: Viewport): MapCamera;
+/** Zooms keeping the point at `anchor` (measured from the screen's center) still. */
+export declare function zoomCamera(scene: MapScene, camera: MapCamera, viewport: Viewport, 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 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 pickScene(scene: MapScene, view: Projection, 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 footprintOutline({ 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 SceneFootprint {
+    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 SceneHighlight {
+    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?: SceneFootprint;
+}
+export declare function drawMapScene(ctx: CanvasRenderingContext2D, scene: MapScene, view: Projection, texture: HTMLCanvasElement, highlight?: SceneHighlight | 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 {};