@ntmats/hc-ui 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,13 +1,18 @@
-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> {
+import { type ButtonHTMLAttributes, type Dispatch, type ForwardRefExoticComponent, type RefAttributes, 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' | 'muted';
+/** Elements a `Surface` may render as. */
+export type SurfaceElement = 'div' | 'section' | 'article' | 'aside' | 'ul' | 'ol' | 'li';
+export interface SurfaceProps extends HTMLAttributes<HTMLElement> {
     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. */
+    /** Corner radius of the rounded tones (`content`, `elevated`, `overlay`, `card`, `muted`): 16, 20 or 24px.
+     * Defaults to `md` (16px), and to `lg` (20px) for `card` and `muted`, as HCUI's `surface` mixin. */
     radius?: 'md' | 'lg' | 'xl';
+    /** Element to render: `div` (default), or `section`, `article`, `aside`, `ul`, `ol`, `li`
+     * (a list drawn as a card). Lists keep the browser's margin, padding and markers: reset them in the caller's class. */
+    as?: SurfaceElement;
 }
 /** Semantic color role only; placement, elevation and overlay behavior stay local. */
-export declare function Surface({ tone, radius, className, ...props }: SurfaceProps): import("react/jsx-runtime").JSX.Element;
+export declare function Surface({ tone, radius, as: Element, className, ...props }: SurfaceProps): import("react/jsx-runtime").JSX.Element;
 export interface SegmentedOption<T extends string> {
     value: T;
     label: string;
@@ -31,12 +36,24 @@ export interface SegmentedControlProps<T extends string> extends Omit<HTMLAttrib
     equalWidth?: boolean;
     /** Fixed width of each option in px; implies `equalWidth`. */
     optionWidth?: number;
+    /** Minimum width of each option in px (HCUI's 92px Coleções/Unidades toggle); a longer label still widens its option. */
+    optionMinWidth?: 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, indicator, equalWidth, optionWidth, className, style, ...props }: SegmentedControlProps<T>): import("react/jsx-runtime").JSX.Element;
-export type ButtonVariant = 'secondary' | 'primary' | 'outline' | 'danger';
+export declare function SegmentedControl<T extends string>({ label, value, options, onChange, density, orientation, hideLabels, indicator, equalWidth, optionWidth, optionMinWidth, className, style, ...props }: SegmentedControlProps<T>): import("react/jsx-runtime").JSX.Element;
+export type ButtonVariant = 'secondary' | 'primary' | 'outline' | 'danger' | 'ghost';
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /**
+     * `secondary` (default, muted fill), `primary`, `outline`, `danger` (filled) or `ghost`
+     * (no fill, only the hover and press veil). A popup trigger (`aria-haspopup`) that is open
+     * (`aria-expanded="true"`) draws a 1.5px ring in the text color, as `Chip` (not on `primary` and `danger`).
+     */
     variant?: ButtonVariant;
+    /**
+     * Text color of the unfilled variants (`secondary`, `outline`, `ghost`): `default` or `danger`
+     * (HCUI's "Fechar e descartar alterações": `variant="ghost" tone="danger"`). Ignored by `primary` and `danger`.
+     */
+    tone?: 'default' | 'danger';
     /** 36, 44 or 52px. */
     size?: 'sm' | 'md' | 'lg';
     /** Decorative icon before the label; pass it already sized (18px in HCUI). */
@@ -46,19 +63,26 @@ 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>>;
+export declare const Button: ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLButtonElement>>;
 export interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children' | 'aria-label'> {
     /** Accessible name and tooltip; required because the button has no text. */
     label: string;
     icon: ReactNode;
-    /** 36, 40 or 44px. The 36px size keeps a 44px touch target. */
-    size?: 'sm' | 'md' | 'lg';
-    tone?: 'primary' | 'secondary';
+    /** 28 (`xs`, dense toolbars and ⋯ triggers), 36, 40 or 44px. `xs` and `sm` keep a 44px touch target. */
+    size?: 'xs' | 'sm' | 'md' | 'lg';
+    /** Icon color: `primary` (default), `secondary` or `muted` (text-muted, HCUI's ⋯ triggers). */
+    tone?: 'primary' | 'secondary' | 'muted';
     /** 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). */
+     * HCUI's mobile sort button) or `ghost` (no fill until hover; an open popup trigger,
+     * `aria-haspopup` with `aria-expanded="true"`, keeps the hover look). */
     variant?: 'muted' | 'surface' | 'outline' | 'ghost';
     /** `circle` (default) or `rounded` (a 12px-radius square, HCUI's desktop utilities). */
     shape?: 'circle' | 'rounded';
@@ -69,7 +93,7 @@ export interface IconButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonEle
     iconKey?: string | number;
 }
 /** Round icon-only button (back, close, options). */
-export declare const IconButton: import("react").ForwardRefExoticComponent<IconButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const IconButton: ForwardRefExoticComponent<IconButtonProps & RefAttributes<HTMLButtonElement>>;
 interface ChipBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
     /** Toggle state for filters; omit for a plain action chip. */
     selected?: boolean;
@@ -80,8 +104,12 @@ interface ChipBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
      * 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';
+    /**
+     * `outline` (default); `quiet`: lighter ring and secondary text, bolder once applied (HCUI's rule
+     * filter pills); `muted`: gray fill without ring (HCUI's search conditions). With `onClear`, a
+     * `muted` chip of `md` or `sm` draws its × at 26px, concentric with the pill's end.
+     */
+    variant?: 'outline' | 'quiet' | 'muted';
     /** A filter with values applied: a 1.5px ring in the primary text color (and primary, bolder text when `quiet`). */
     applied?: boolean;
     /**
@@ -94,6 +122,17 @@ interface ChipBaseProps extends ButtonHTMLAttributes<HTMLButtonElement> {
      * `undefined` (e.g. `badge={n || undefined}`) to hide it when nothing is applied.
      */
     badge?: ReactNode;
+    /**
+     * Where the badge goes: `inline` (default, after the label) or `corner` (on the top right
+     * corner, in the brand color with a ring of `--hc-chip-badge-ring`, default `bg-page`; HCUI's
+     * mobile Meta filter button). A chip with an `icon` and no label is a circle.
+     */
+    badgePlacement?: 'inline' | 'corner';
+    /**
+     * Information, not an action: the chip cannot be pressed (the button is disabled) but keeps
+     * its full color instead of dimming (HCUI's Meta era chip when only one era fits the format).
+     */
+    informative?: boolean;
     /**
      * 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.
@@ -122,7 +161,7 @@ export type ChipProps = ChipBaseProps & ({
  * 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 declare const Chip: ForwardRefExoticComponent<ChipProps & RefAttributes<HTMLButtonElement>>;
 export interface FilterBarProps extends HTMLAttributes<HTMLDivElement> {
     /** Accessible name of the group (e.g. "Filtros"). */
     label: string;
@@ -142,13 +181,25 @@ export interface FilterBarProps extends HTMLAttributes<HTMLDivElement> {
     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;
+    /**
+     * The bar reaches the panel's edges: a negative margin of `--hc-filter-bar-bleed-start` and
+     * `--hc-filter-bar-bleed-end` (both default to `--hc-filter-bar-bleed`, else 0) given back as
+     * padding, so the content stays in place and a sticky band covers the full width (HCUI's
+     * `.desktop-filter-bar`, which content bleeding to the edge passes under).
+     */
+    bleed?: boolean;
+    /**
+     * Class of the row that holds the filters. The row is `position: relative`, so a popup the
+     * caller places with `position: absolute` inside it is anchored to the row (HCUI's "Mais filtros").
+     */
+    rowClassName?: string;
 }
 /**
  * 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 declare const FilterBar: ForwardRefExoticComponent<FilterBarProps & RefAttributes<HTMLDivElement>>;
 export interface FieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
     /** Accessible name. Visible above the field unless `hideLabel` is set. */
     label: string;
@@ -164,7 +215,7 @@ export interface FieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>,
     error?: ReactNode;
 }
 /** Filled pill text field. Value, validation and messages stay with the caller. */
-export declare const Field: import("react").ForwardRefExoticComponent<FieldProps & import("react").RefAttributes<HTMLInputElement>>;
+export declare const Field: ForwardRefExoticComponent<FieldProps & RefAttributes<HTMLInputElement>>;
 export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
     width?: string | number;
     height?: string | number;
@@ -213,7 +264,7 @@ export type MeterProps = MeterOwnProps & (
  * 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 declare const Meter: ForwardRefExoticComponent<MeterProps & RefAttributes<HTMLSpanElement>>;
 export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
     /** 20px (touch lists, sheets) or 16px (dense desktop lists). */
     size?: 'sm' | 'md';
@@ -225,7 +276,7 @@ export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement
  * 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 declare const Checkbox: ForwardRefExoticComponent<CheckboxProps & 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;
@@ -249,17 +300,17 @@ export interface DialogProps extends Omit<HTMLAttributes<HTMLDialogElement>, 'ti
     size?: 'sm' | 'md';
     /** Esc and a backdrop click ask to close. Default true. */
     dismissible?: boolean;
+    /** Class of the body that holds the children (and scrolls in `md`), e.g. to reserve the scrollbar's gutter. */
+    bodyClassName?: string;
 }
 /**
  * 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 declare const Dialog: ForwardRefExoticComponent<DialogProps & 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;
+interface SheetBaseProps extends Omit<DialogProps, 'size' | 'actions' | 'description' | 'closeLabel' | 'title'> {
     /** Slot under the scrolling body, for the buttons (Clear | Done). */
     footer?: ReactNode;
     /**
@@ -271,6 +322,25 @@ export interface SheetProps extends Omit<DialogProps, 'size' | 'actions' | 'desc
     /** Maximum width of the centered panel, in px. Default 440. */
     width?: number;
 }
+/**
+ * `Sheet` props. By default the sheet has a header with the title (its accessible name) and a
+ * close button. `header={false}` drops both: the content brings its own heading and floating
+ * close button (HCUI's unit sheet), and `aria-label` names the dialog. The body then has no
+ * padding, and at the bottom the grabber (drawn above the content) covers its top 16px.
+ */
+export type SheetProps = SheetBaseProps & ({
+    header?: true;
+    /** Visible heading; it names the sheet. */
+    title: ReactNode;
+    /** Accessible name of the close button, which every sheet with a header shows. */
+    closeLabel: string;
+} | {
+    header: false;
+    'aria-label': string;
+    title?: never;
+    closeLabel?: never;
+    closeIcon?: never;
+});
 /**
  * Modal sheet on the `Dialog` base (native `<dialog>`, `showModal()`): the same focus,
  * Tab trap, Esc, focus return, scroll lock, stacking and controlled `open`/`onClose`.
@@ -278,7 +348,7 @@ export interface SheetProps extends Omit<DialogProps, 'size' | 'actions' | 'desc
  * 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 declare const Sheet: ForwardRefExoticComponent<SheetProps & RefAttributes<HTMLDialogElement>>;
 export interface SheetOption<T extends string> {
     value: T;
     label: ReactNode;
@@ -298,24 +368,23 @@ 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;
         label: ReactNode;
         disabled?: boolean;
     }[];
+    /** Size of every chip, as `Chip`'s: `md` (default), `sm` or `xs`. */
+    size?: ChipProps['size'];
 }
 /** 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 declare function SheetChips<T extends string>({ label, options, value, onChange, size, 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. */
@@ -366,6 +435,14 @@ export declare function placePopup(trigger: Rect, size: {
     side: PopupSide;
     align: PopupAlign;
 };
+/**
+ * Where to portal something that floats over `node` (a tip, a tooltip): the open `<dialog>`
+ * around it, else `document.body`. A modal dialog (`Dialog`, `Sheet`) is in the top layer and
+ * makes the rest of the page inert, so a tip portaled to `body` from inside it would stay
+ * behind it and get no touches; inside the dialog it shows above it. `Menu` and `Popover`
+ * with `portal` already do this. On the server (no document) it returns null.
+ */
+export declare function portalContainerFor(node: Element | null | undefined): HTMLElement | null;
 export interface MenuProps extends PopupBaseProps, Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'children'> {
     /** Accessible name of the menu (`aria-label`). */
     label: string;
@@ -379,7 +456,7 @@ export interface MenuProps extends PopupBaseProps, Omit<HTMLAttributes<HTMLDivEl
  * 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>>;
+export declare const Menu: ForwardRefExoticComponent<MenuProps & 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;
@@ -393,7 +470,7 @@ export interface MenuItemProps extends MenuItemBaseProps {
     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 declare const MenuItem: ForwardRefExoticComponent<MenuItemProps & RefAttributes<HTMLButtonElement>>;
 export interface MenuRadioGroupProps<T extends string> extends Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'onChange'> {
     value: T;
     onValueChange: (value: NoInfer<T>) => void;
@@ -406,7 +483,7 @@ 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 declare const MenuItemRadio: ForwardRefExoticComponent<MenuItemRadioProps & RefAttributes<HTMLButtonElement>>;
 export interface MenuItemCheckboxProps extends MenuItemBaseProps {
     checked: boolean;
     onCheckedChange: (checked: boolean) => void;
@@ -414,7 +491,7 @@ export interface MenuItemCheckboxProps extends MenuItemBaseProps {
     closeOnSelect?: boolean;
 }
 /** A `menuitemcheckbox`: toggles in place, with a check while on. */
-export declare const MenuItemCheckbox: import("react").ForwardRefExoticComponent<MenuItemCheckboxProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const MenuItemCheckbox: ForwardRefExoticComponent<MenuItemCheckboxProps & 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. */
@@ -442,7 +519,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'> {
@@ -463,7 +540,7 @@ export interface PopoverProps extends PopupBaseProps, Omit<HTMLAttributes<HTMLDi
  * 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 declare const Popover: ForwardRefExoticComponent<PopoverProps & RefAttributes<HTMLDivElement>>;
 export type TableSortDirection = 'ascending' | 'descending';
 export interface TableColumn<Row> {
     /** Stable id of the column; it is what `sort.key` and `onSort` name. */
@@ -528,7 +605,7 @@ export interface PageHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'titl
     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 declare const PageHeader: ForwardRefExoticComponent<PageHeaderProps & RefAttributes<HTMLElement>>;
 export interface PanelHeaderStep {
     label: string;
     /** Goes back to this step. The last step is the current one and is never a button. */
@@ -567,14 +644,14 @@ export interface PanelHeaderProps extends Omit<HTMLAttributes<HTMLElement>, 'tit
     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 declare const PanelHeader: ForwardRefExoticComponent<PanelHeaderProps & 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 declare const ListRow: ForwardRefExoticComponent<ListRowProps & RefAttributes<HTMLButtonElement>>;
 export interface CommandPaletteItem {
     /** Unique among all items. */
     key: string;
@@ -638,7 +715,7 @@ export interface CommandPaletteProps extends Omit<HTMLAttributes<HTMLDialogEleme
  * 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>>;
+export declare const CommandPalette: ForwardRefExoticComponent<CommandPaletteProps & 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
@@ -680,7 +757,7 @@ export interface MiniDialViewProps {
  * 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 declare const MiniDialView: ForwardRefExoticComponent<MiniDialViewProps & RefAttributes<HTMLSpanElement>>;
 export interface PowerIconViewProps {
     /** Power color (the circle's fill). */
     color: string;
@@ -691,7 +768,7 @@ export interface PowerIconViewProps {
     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 declare const PowerIconView: ForwardRefExoticComponent<PowerIconViewProps & RefAttributes<HTMLSpanElement>>;
 export interface StatGlyphViewProps {
     /** Address of the symbol, already built. */
     src: string;
@@ -700,7 +777,7 @@ export interface StatGlyphViewProps {
     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 declare const StatGlyphView: ForwardRefExoticComponent<StatGlyphViewProps & RefAttributes<HTMLImageElement>>;
 export interface SpecialIconViewProps {
     /** Round white background (the image server's `sp/white.svg`), already built. */
     backgroundSrc: string;
@@ -709,7 +786,7 @@ export interface SpecialIconViewProps {
     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 declare const SpecialIconView: ForwardRefExoticComponent<SpecialIconViewProps & RefAttributes<HTMLSpanElement>>;
 export interface EquipmentIconProps {
     size?: number;
 }
@@ -750,7 +827,7 @@ export interface AvatarViewProps {
  * `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 declare const AvatarView: ForwardRefExoticComponent<AvatarViewProps & RefAttributes<HTMLImageElement>>;
 export interface SetIconViewProps {
     /** Addresses of the set icon, in the order to try. Empty: renders nothing. */
     sources: readonly string[];
@@ -759,7 +836,7 @@ export interface SetIconViewProps {
     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>>;
+export declare const SetIconView: ForwardRefExoticComponent<SetIconViewProps & 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];
@@ -864,6 +941,12 @@ export interface CombatDialViewProps {
     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;
@@ -880,12 +963,12 @@ export interface CombatDialViewProps {
  * 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;
+export declare const CombatDialView: ForwardRefExoticComponent<CombatDialViewProps & 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 BYSTANDER_DIAL_STEP: {
+export declare const PHYSICAL_CARD_BYSTANDER_DIAL_STEP: {
     x: number;
     y: number;
 };
@@ -898,11 +981,11 @@ export declare const BYSTANDER_DIAL_STEP: {
  * `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;
+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 backCount(pages: number[]): number;
+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 tiltAt(x: number, y: number, damping?: number): {
+export declare function physicalCardTiltAt(x: number, y: number, damping?: number): {
     rotateX: number;
     rotateY: number;
     parallaxX: number;
@@ -910,16 +993,16 @@ export declare function tiltAt(x: number, y: number, damping?: number): {
     shineX: number;
     shineY: number;
 };
-type CardTilt = ReturnType<typeof tiltAt>;
+type CardTilt = ReturnType<typeof physicalCardTiltAt>;
 /** The finished values each moving part of the card takes, ready for `style`. */
-export declare function tiltStyles(tilt: CardTilt): {
+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 devicePosition(beta: number, gamma: number, baseline: {
+export declare function physicalCardDevicePosition(beta: number, gamma: number, baseline: {
     beta: number;
     gamma: number;
 }, screenAngle?: number): {
@@ -932,7 +1015,7 @@ export declare function devicePosition(beta: number, gamma: number, baseline: {
  * it; outside iOS it does nothing. A touch the browser refuses leaves the request
  * for the next one.
  */
-export declare function requestMotionAccess(): void;
+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];
@@ -1217,20 +1300,20 @@ export declare function PhysicalCardFocusView({ label, onClose, children }: Phys
  * 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>>;
+export declare const PhysicalCardView: ForwardRefExoticComponent<PhysicalCardViewProps & 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>;
+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;
@@ -1299,7 +1382,7 @@ export declare function mapSquare(map: HCMapJson, x: number, y: number): {
 };
 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 mapElevationLevel(elevation: number | string): number;
 export declare function mapMaxLevel(map: HCMapJson): number;
 export interface MapInspection {
     square: MapSquare;
@@ -1314,7 +1397,7 @@ export interface MapInspection {
 }
 /** 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;
+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
@@ -1322,15 +1405,15 @@ export declare function squareCoordinate(square: Pick<MapSquare, 'x' | 'y'>): st
  * 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 {
+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 SceneWall {
+export interface MapSceneWall {
     x0: number;
     y0: number;
     x1: number;
@@ -1339,7 +1422,7 @@ export interface SceneWall {
     z0: number;
     z1: number;
 }
-export interface SceneRamp {
+export interface MapSceneRamp {
     x: number;
     y: number;
     dx: number;
@@ -1347,7 +1430,7 @@ export interface SceneRamp {
     from: number;
     to: number;
 }
-export interface SceneLine {
+export interface MapSceneLine {
     x0: number;
     y0: number;
     x1: number;
@@ -1357,13 +1440,13 @@ export interface SceneLine {
 export interface MapScene {
     width: number;
     height: number;
-    cells: SceneCell[];
-    walls: SceneWall[];
-    ramps: SceneRamp[];
-    ziplines: SceneLine[];
+    cells: MapSceneCell[];
+    walls: MapSceneWall[];
+    ramps: MapSceneRamp[];
+    ziplines: MapSceneLine[];
     maxTop: number;
 }
-export declare function sceneCell(scene: Pick<MapScene, 'width' | 'height' | 'cells'>, x: number, y: number): SceneCell | null;
+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;
@@ -1372,16 +1455,16 @@ export interface MapCamera {
     panX: number;
     panY: number;
 }
-export interface Viewport {
+export interface MapViewport {
     width: number;
     height: number;
 }
-export declare const DEFAULT_CAMERA: MapCamera;
+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 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 {
+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;
@@ -1391,16 +1474,16 @@ export interface Projection {
     /** 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;
+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 clampPan(scene: MapScene, camera: MapCamera, viewport: Viewport): MapCamera;
+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 zoomCamera(scene: MapScene, camera: MapCamera, viewport: Viewport, factor: number, anchor?: {
+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 CELL_SIDES: readonly [{
+export declare const MAP_CELL_SIDES: readonly [{
     readonly ax: 0;
     readonly ay: 1;
     readonly bx: 0;
@@ -1433,7 +1516,7 @@ export declare const CELL_SIDES: readonly [{
  * 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): {
+export declare function pickMapScene(scene: MapScene, view: MapProjection, px: number, py: number): {
     x: number;
     y: number;
 } | null;
@@ -1442,7 +1525,7 @@ 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 }: {
+export declare function mapFootprintOutline({ x, y, width, height, cells }: {
     x: number;
     y: number;
     width: number;
@@ -1453,7 +1536,7 @@ export declare function footprintOutline({ x, y, width, height, cells }: {
     edges: [Point, Point][];
     corners: Point[];
 };
-export interface SceneFootprint {
+export interface MapSceneFootprint {
     x: number;
     y: number;
     width: number;
@@ -1463,7 +1546,7 @@ export interface SceneFootprint {
     /** Occupied squares (`cells[y][x]`, from the corner); without it, the whole rectangle. */
     cells?: readonly (readonly boolean[])[] | null;
 }
-export interface SceneHighlight {
+export interface MapSceneHighlight {
     square?: {
         x: number;
         y: number;
@@ -1475,9 +1558,9 @@ export interface SceneHighlight {
         y1: number;
     };
     /** The target of a piece being moved: floor and volume, cut to the board. */
-    footprint?: SceneFootprint;
+    footprint?: MapSceneFootprint;
 }
-export declare function drawMapScene(ctx: CanvasRenderingContext2D, scene: MapScene, view: Projection, texture: HTMLCanvasElement, highlight?: SceneHighlight | null, { tufts }?: {
+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. */
@@ -1508,7 +1591,7 @@ export interface MapBoardViewProps extends Omit<HTMLAttributes<HTMLDivElement>,
  * 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 declare const MapBoardView: ForwardRefExoticComponent<MapBoardViewProps & RefAttributes<HTMLDivElement>>;
 export interface MapBoardPlaceholderProps {
     /** Read by screen readers while the map loads (e.g. "Loading map"). */
     label: string;