@salilvnair/dui 1.0.7 → 1.0.9

package/dist/lib/components/modal/BottomSheetView.d.ts

@@ -1,6 +1,15 @@
 import { ReactNode } from 'react';
 import { DuiSize } from '../../core/DuiTypes';
 export interface BottomSheetViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     open: boolean;
     onClose: () => void;
     title?: string;
@@ -11,4 +20,4 @@ export interface BottomSheetViewProps {
     className?: string;
 }
 /** Mobile-style sheet — drag the handle down past a threshold, or fling it, to dismiss. */
-export declare function BottomSheetView({ open, onClose, title, children, heightRatio, size, className, }: BottomSheetViewProps): import('react').ReactPortal | null;
+export declare function BottomSheetView({ testId, open, onClose, title, children, heightRatio, size, className, }: BottomSheetViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/CommandPaletteView.d.ts

@@ -10,6 +10,15 @@ export interface PaletteCommand {
     action: () => void;
 }
 export interface CommandPaletteViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     open: boolean;
     onClose: () => void;
     commands: PaletteCommand[];
@@ -18,4 +27,4 @@ export interface CommandPaletteViewProps {
     accentColor?: string;
 }
 /** Cmd-K style launcher: fuzzy filter + ↑/↓/Enter/Esc keyboard navigation. */
-export declare function CommandPaletteView({ open, onClose, commands, placeholder, emptyText, accentColor, }: CommandPaletteViewProps): import('react').ReactPortal | null;
+export declare function CommandPaletteView({ testId, open, onClose, commands, placeholder, emptyText, accentColor, }: CommandPaletteViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/ContextMenuView.d.ts

@@ -1,6 +1,15 @@
 export interface ContextMenuItem {
     id: string;
     label: string;
+    /**
+     * A line under the label, for a menu whose entries need explaining.
+     *
+     * Most items do not want one — a menu of verbs reads faster without a
+     * paragraph under each. It earns its place where choosing wrongly costs
+     * something and the label alone cannot say so: an action that pauses a
+     * process, or one that is unavailable and owes the reader a reason.
+     */
+    description?: string;
     icon?: React.ReactNode;
     iconColor?: string;
     shortcut?: string;
@@ -12,6 +21,15 @@ export interface ContextMenuItem {
 }
 export type ContextMenuWidth = 'auto' | 'sm' | 'md' | 'lg' | number;
 export interface ContextMenuViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     items: ContextMenuItem[];
     anchorEl: HTMLElement | null;
     open: boolean;
@@ -25,4 +43,4 @@ export interface ContextMenuViewProps {
     };
     align?: 'auto' | 'left' | 'right';
 }
-export declare function ContextMenuView({ items, anchorEl, open, onClose, width, rounded, matchAnchorWidth, position, align, }: ContextMenuViewProps): import('react').ReactPortal | null;
+export declare function ContextMenuView({ testId, items, anchorEl, open, onClose, width, rounded, matchAnchorWidth, position, align, }: ContextMenuViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/DrawerView.d.ts

@@ -2,6 +2,15 @@ import { ReactNode } from 'react';
 import { DuiSize } from '../../core/DuiTypes';
 export type DrawerEdge = 'left' | 'right' | 'top' | 'bottom';
 export interface DrawerViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     open: boolean;
     onClose: () => void;
     edge?: DrawerEdge;
@@ -12,4 +21,4 @@ export interface DrawerViewProps {
     duiSize?: DuiSize;
     className?: string;
 }
-export declare function DrawerView({ open, onClose, edge, title, children, size, duiSize, className, }: DrawerViewProps): import('react').ReactPortal | null;
+export declare function DrawerView({ testId, open, onClose, edge, title, children, size, duiSize, className, }: DrawerViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/InfoPopupView.d.ts

@@ -12,6 +12,18 @@ export interface InfoPopupViewProps {
     footer?: string;
     wikiLabel?: string;
     wikiHref?: string;
+    /**
+     * Open the docs in the host app instead of the browser.
+     *
+     * `wikiHref` assumes the documentation is a URL. An app whose docs are a
+     * panel of its own has nowhere to point one -- and inside an embedded host
+     * (a VS Code webview, an iframe with no top-level navigation) an anchor to
+     * an internal route does nothing at all, silently. Given this, the footer
+     * becomes a button and the app decides what "open the wiki" means.
+     *
+     * Takes precedence over `wikiHref` when both are given.
+     */
+    onWikiOpen?: () => void;
     width?: number;
 }
-export declare function InfoPopupView({ open, onClose, anchorEl, title, description, items, footer, wikiLabel, wikiHref, width, }: InfoPopupViewProps): import('react').ReactPortal | null;
+export declare function InfoPopupView({ open, onClose, anchorEl, title, description, items, footer, wikiLabel, wikiHref, onWikiOpen, width, }: InfoPopupViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/ModalView.d.ts

@@ -1,13 +1,29 @@
-export type ModalSize = 'sm' | 'md' | 'lg' | 'xl';
+export type ModalSize = 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
 /**
  * 'popout' — centered overlay with backdrop, portalled to document.body (default)
  * 'inline' — bare card with no backdrop, no portal; parent controls positioning
  */
 export type ModalMode = 'popout' | 'inline';
 export interface ModalViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     open: boolean;
     onClose: () => void;
-    title?: string;
+    /**
+     * Rendered in the header at title weight.
+     *
+     * A node rather than a string, so a header can carry two registers on one
+     * line — a subject and a quieter label for what you are doing to it — which
+     * a single styled string cannot express.
+     */
+    title?: React.ReactNode;
     /** Secondary text shown below the title in the header */
     subtitle?: React.ReactNode;
     /** Node rendered to the left of the title block — e.g. a coloured icon circle */
@@ -47,4 +63,4 @@ export interface ModalViewProps {
     /** Extra styles merged onto the body div (e.g. flex column layout for nested flex children) */
     bodyStyle?: React.CSSProperties;
 }
-export declare function ModalView({ open, onClose, title, subtitle, headerIcon, children, footerLeft, footerRight, size, showCloseIcon, headerColor, headerGradient, headerRight, noPadding, elevated, mode, maxHeight, height, bodyStyle, }: ModalViewProps): import("react").JSX.Element | null;
+export declare function ModalView({ testId, open, onClose, title, subtitle, headerIcon, children, footerLeft, footerRight, size, showCloseIcon, headerColor, headerGradient, headerRight, noPadding, elevated, mode, maxHeight, height, bodyStyle, }: ModalViewProps): import("react").JSX.Element | null;

package/dist/lib/components/modal/NotificationCenterView.d.ts

@@ -10,6 +10,15 @@ export interface NotificationItem {
     onClick?: () => void;
 }
 export interface NotificationCenterViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     notifications: NotificationItem[];
     onMarkAllRead?: () => void;
     size?: DuiSize;
@@ -17,4 +26,4 @@ export interface NotificationCenterViewProps {
     className?: string;
 }
 /** Bell icon + dropdown notification list, unread-count badge. */
-export declare function NotificationCenterView({ notifications, onMarkAllRead, size, color, className, }: NotificationCenterViewProps): import("react").JSX.Element;
+export declare function NotificationCenterView({ testId, notifications, onMarkAllRead, size, color, className, }: NotificationCenterViewProps): import("react").JSX.Element;

package/dist/lib/components/modal/PopoverView.d.ts

@@ -2,6 +2,15 @@ import { ReactNode } from 'react';
 import { DuiSize, DuiRadius } from '../../core/DuiTypes';
 export type PopoverPlacement = 'top' | 'bottom' | 'left' | 'right';
 export interface PopoverViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     open: boolean;
     onClose: () => void;
     anchorEl: HTMLElement | null;
@@ -17,4 +26,4 @@ export interface PopoverViewProps {
  * shared conceptually with SelectInputView's dropdown / InfoPopupView, but
  * exposed as a standalone component for any custom popover content.
  */
-export declare function PopoverView({ open, onClose, anchorEl, children, placement, size, borderRadius, color, className, }: PopoverViewProps): import('react').ReactPortal | null;
+export declare function PopoverView({ testId, open, onClose, anchorEl, children, placement, size, borderRadius, color, className, }: PopoverViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/SheetView.d.ts

@@ -0,0 +1,31 @@
+import { ReactNode } from 'react';
+import { SheetEdge } from './sheet-drag';
+export type { SheetEdge };
+export interface SheetViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
+    open: boolean;
+    onClose: () => void;
+    /** Which edge it comes in from. */
+    edge?: SheetEdge;
+    /** Width for `left`/`right`, height for `top`/`bottom`. */
+    size?: number | string;
+    title?: ReactNode;
+    /** Replaces the whole title row, for a header that is more than a string. */
+    header?: ReactNode;
+    footer?: ReactNode;
+    /** The handle, and the drag with it. On by default. */
+    handle?: boolean;
+    /** Clicking the backdrop closes it. On by default. */
+    backdropClose?: boolean;
+    children?: ReactNode;
+    className?: string;
+}
+export declare function SheetView({ testId, open, onClose, edge, size, title, header, footer, handle, backdropClose, children, className, }: SheetViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/SpotlightTourView.d.ts

@@ -6,6 +6,15 @@ export interface SpotlightTourStep {
     content: string;
 }
 export interface SpotlightTourViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     open: boolean;
     steps: SpotlightTourStep[];
     stepIndex: number;
@@ -15,4 +24,4 @@ export interface SpotlightTourViewProps {
     size?: DuiSize;
     color?: string;
 }
-export declare function SpotlightTourView({ open, steps, stepIndex, onNext, onPrev, onClose, size, color, }: SpotlightTourViewProps): import('react').ReactPortal | null;
+export declare function SpotlightTourView({ testId, open, steps, stepIndex, onNext, onPrev, onClose, size, color, }: SpotlightTourViewProps): import('react').ReactPortal | null;

package/dist/lib/components/modal/StackedToastDeckView.d.ts

@@ -6,6 +6,15 @@ export interface ToastDeckEntry {
     color?: string;
 }
 export interface StackedToastDeckViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     toasts: ToastDeckEntry[];
     onDismiss: (id: string) => void;
     size?: DuiSize;
@@ -14,4 +23,4 @@ export interface StackedToastDeckViewProps {
     style?: CSSProperties;
 }
 /** Toasts don't stack vertically — older ones shrink and recede behind the newest like a card deck; click to fan out. */
-export declare function StackedToastDeckView({ toasts, onDismiss, size, width, className, style, }: StackedToastDeckViewProps): import("react").JSX.Element;
+export declare function StackedToastDeckView({ testId, toasts, onDismiss, size, width, className, style, }: StackedToastDeckViewProps): import("react").JSX.Element;

package/dist/lib/components/modal/sheet-drag.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The geometry behind a sheet you can throw away.
+ *
+ * Kept apart from the component because it is the half that can be wrong in a
+ * way nobody notices: a sheet that dismisses at the wrong moment feels
+ * unreliable rather than broken, and that is exactly the kind of thing a test
+ * catches and a demo does not.
+ */
+export type SheetEdge = 'bottom' | 'top' | 'left' | 'right';
+/** Which way a sheet on this edge travels when it leaves. */
+export declare function axisOf(edge: SheetEdge): 'x' | 'y';
+/**
+ * How far the pointer has dragged the sheet *towards its own edge*.
+ *
+ * Never negative. Dragging a bottom sheet upwards does not lift it off the
+ * bottom of the screen — the sheet is already against that edge, and letting it
+ * move would open a gap under it that has nothing in it. Pulling the other way
+ * is a no-op, which is what every native sheet does.
+ */
+export declare function travel(edge: SheetEdge, dx: number, dy: number): number;
+/** The way a sheet on this edge is pulled *away* from its edge — i.e. wider. */
+export declare function opposite(edge: SheetEdge): SheetEdge;
+/**
+ * How wide a sheet becomes when its handle is pulled away from the edge.
+ *
+ * The same handle does both, and which one it is doing is decided by direction
+ * alone: towards the edge it came from is "throw it back out", away from it is
+ * "I want more room". Nothing else on a sheet is a natural place to put a
+ * resize grip, and a second one beside the first would be two 4px targets
+ * doing different things a few pixels apart.
+ *
+ * Clamped at both ends: below `MIN_SIZE` the sheet is a strip with no content
+ * in it, and past `MAX_RATIO` of the window it has covered the thing it is a
+ * detail view *of*.
+ */
+export declare const MIN_SIZE = 320;
+export declare const MAX_RATIO = 0.96;
+export declare function grownTo(from: number, pulled: number, viewport: number): number;
+/** The `transform` for a sheet dragged `moved` pixels off its edge. */
+export declare function offsetStyle(edge: SheetEdge, moved: number): string;
+/** Past this share of its own size, a released sheet keeps going. */
+export declare const DISMISS_RATIO = 0.3;
+/**
+ * Fast enough that it was thrown, in pixels per millisecond.
+ *
+ * A flick is a short, fast drag — it never crosses the distance threshold, and
+ * without this it springs back, which reads as the sheet refusing to close.
+ * 0.5px/ms is about 500px in a second: brisk, not twitchy.
+ */
+export declare const FLING_SPEED = 0.5;
+/**
+ * Does the sheet leave, or spring back?
+ *
+ * Either far enough or fast enough. Requiring both would mean a slow deliberate
+ * drag all the way across still bounced back; requiring distance alone loses
+ * the flick, which is how people actually dismiss these.
+ */
+export declare function shouldDismiss(moved: number, size: number, speed?: number): boolean;
+/** Pixels per millisecond, guarding the zero-duration case. */
+export declare function speedOf(moved: number, ms: number): number;

package/dist/lib/components/modal/sheet-drag.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/components/tabs/PilledTabView.d.ts

@@ -3,6 +3,15 @@ export interface PilledTab {
     label: string;
 }
 export interface PilledTabViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     tabs: PilledTab[];
     activeId: string;
     onChange: (id: string) => void;
@@ -16,4 +25,4 @@ export interface PilledTabViewProps {
     className?: string;
     style?: React.CSSProperties;
 }
-export declare function PilledTabView({ tabs, activeId, onChange, accentColor, mode, className, style, }: PilledTabViewProps): import("react").JSX.Element;
+export declare function PilledTabView({ testId, tabs, activeId, onChange, accentColor, mode, className, style, }: PilledTabViewProps): import("react").JSX.Element;

package/dist/lib/components/tabs/TabBarView.d.ts

@@ -33,6 +33,15 @@ export interface TabBarTab {
     preview?: ReactNode;
 }
 export interface TabBarViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
     tabs: TabBarTab[];
     activeTabId: string;
     onTabClick: (id: string) => void;
@@ -53,4 +62,4 @@ export interface TabBarViewProps {
     height?: number;
     className?: string;
 }
-export declare function TabBarView({ tabs, activeTabId, onTabClick, onTabClose, onAddTab, onTabContextMenu, renamingId, renameValue, onRenameChange, onRenameCommit, onRenameCancel, accentColor, size, height, className, }: TabBarViewProps): import("react").JSX.Element;
+export declare function TabBarView({ testId, tabs, activeTabId, onTabClick, onTabClose, onAddTab, onTabContextMenu, renamingId, renameValue, onRenameChange, onRenameCommit, onRenameCancel, accentColor, size, height, className, }: TabBarViewProps): import("react").JSX.Element;

package/dist/lib/components/tabs/UnderlineTabsView.d.ts

@@ -0,0 +1,41 @@
+import { ReactNode, CSSProperties } from 'react';
+export interface UnderlineTab {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    /** A count beside the label — how many rows are behind this tab. */
+    count?: number | string;
+    disabled?: boolean;
+}
+export interface UnderlineTabsViewProps {
+    /**
+     * A stable hook for tests and automation.
+     *
+     * Lands on this component's root element as `data-testid`. Worth setting on
+     * anything a test drives: several dui inputs render a `contenteditable` div
+     * with a decorative placeholder span, which neither `getByPlaceholder` nor
+     * `getByRole` reliably finds.
+     */
+    testId?: string;
+    tabs: UnderlineTab[];
+    activeId: string;
+    onChange: (id: string) => void;
+    accentColor?: string;
+    /** Draw the hairline the tabs sit on. On by default. */
+    rule?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Sections within one view, marked by an underline.
+ *
+ * The second level of navigation, under a window's own tabs: Board, New issue,
+ * Insights, Repository. Underline rather than pill because these are places
+ * inside the same thing, and a row of filled pills competes with the window
+ * tabs above it for "which of these is the tab bar".
+ *
+ * A count sits inside the tab rather than beside it, and takes the accent only
+ * on the active one — so an inactive section still reports its size without
+ * pulling the eye off the section you are in.
+ */
+export declare function UnderlineTabsView({ testId, tabs, activeId, onChange, accentColor, rule, className, style, }: UnderlineTabsViewProps): import("react").JSX.Element;

package/dist/lib/components/testid.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/core/DuiContext.d.ts

@@ -5,11 +5,11 @@ import { DuiConfig, DuiSize, DuiRadius, DuiWidth, DuiFontStyle } from './DuiType
  * Every prop is optional and falls back to its system default when omitted.
  *
  * @example
- * <DuiProvider size="sm" borderRadius="lg" activeColor="var(--color-primary)">
+ * <DuiProvider size="sm" borderRadius="lg" chipVariant="quiet">
  *   <ButtonView>Save</ButtonView>
  * </DuiProvider>
  */
-export declare function DuiProvider({ size, width, borderRadius, color, defaultColor, activeColor, fontStyle, children, }: {
+export declare function DuiProvider({ size, width, borderRadius, color, defaultColor, activeColor, fontStyle, chipVariant, children, }: {
     size?: DuiSize;
     width?: DuiWidth;
     borderRadius?: DuiRadius | number;
@@ -17,6 +17,8 @@ export declare function DuiProvider({ size, width, borderRadius, color, defaultC
     defaultColor?: string;
     activeColor?: string;
     fontStyle?: DuiFontStyle;
+    /** The look every `BadgeChipView` in the subtree takes. */
+    chipVariant?: string;
     children: ReactNode;
 }): import("react").JSX.Element;
 /**

package/dist/lib/core/DuiTypes.d.ts

@@ -26,4 +26,12 @@ export interface DuiConfig {
     activeColor?: string;
     /** Font style applied to all text within the DUI subtree. */
     fontStyle?: DuiFontStyle;
+    /**
+     * Which of `BadgeChipView`'s looks every chip takes.
+     *
+     * The one setting that changes a mark appearing in twenty screens at once,
+     * which is why it is here rather than argued at each call site. A chip that
+     * needs to differ still says `variant` itself.
+     */
+    chipVariant?: string;
 }

package/dist/lib/core/IconSize.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How big an icon is, decided by what it is doing rather than by eye.
+ *
+ * A survey of one panel found fourteen distinct sizes across a hundred and
+ * sixty-nine icons. Most of those clustered sensibly — the same handful of
+ * numbers doing the same handful of jobs — but the tail was one-offs, and
+ * worse, the same SLOT sometimes rendered at two sizes depending on state: a
+ * tab whose icon was 12px normally and 11px when locked, so the row twitched
+ * as permissions changed.
+ *
+ * Naming the roles is what stops that. A number picked at the call site is a
+ * number nobody can check; a role can be read against its neighbours.
+ *
+ * The values are the ones already dominant in the product — this is a name for
+ * what was mostly happening, not a new scale imposed on it.
+ */
+export declare const IconSize: {
+    /** Inside a badge or chip, where the text is 8px. */
+    readonly chip: 9;
+    /** Beside text in a dense row — a caption, a hint, a status word. */
+    readonly inline: 11;
+    /** The common one: row actions, menu entries, buttons. */
+    readonly action: 12;
+    /** A list item's kind marker, where the icon identifies the row. */
+    readonly item: 13;
+    /** The leading glyph of a file or table row, and headers of that weight. */
+    readonly row: 15;
+    /** Back arrows, tab-strip marks — navigation rather than action. */
+    readonly nav: 16;
+    /** A clickable square standing on its own, like a select-all box. */
+    readonly control: 19;
+    /** A state the panel is reporting, at the size of the thing it interrupts. */
+    readonly state: 20;
+    /** The empty-state medallion. */
+    readonly medallion: 22;
+    /**
+     * The subject of a screen that has nothing else on it.
+     *
+     * A panel-filling loading or empty state is not a row and should not be
+     * drawn like one: at `medallion` inside an 800px-tall empty tab the glyph
+     * reads as a typo rather than as the thing being waited for.
+     */
+    readonly hero: 34;
+};
+export type IconRole = keyof typeof IconSize;

package/dist/lib/core/TerminalPalette.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Terminal palettes, for both grounds.
+ *
+ * The sixteen ANSI slots are a compatibility table, not a design. Left at
+ * their defaults a shell renders `ls` in fluorescent green on pure blue, and
+ * `LS_COLORS` leans on exactly those slots — which is why an ordinary listing
+ * comes back looking like a 1988 BBS.
+ *
+ * ── What a palette owns, and what it does not ──
+ *
+ * It owns the sixteen colours and the FOREGROUND, because the two have to be
+ * chosen together: a palette's plain text is the tone everything else is
+ * contrasted against, and taking it from elsewhere gives you a bright white
+ * body under muted syntax, which reads as unfinished.
+ *
+ * It does NOT own the background. The terminal should look like part of the
+ * panel it sits in rather than a themed box dropped into it, so the ground
+ * comes from the surface and these adapt to it.
+ *
+ * ── Why each has a light variant ──
+ *
+ * Because the same colours do not work on both. Tokyo Night's `#9ece6a` green
+ * is legible on `#16161e` and nearly invisible on white; a light palette needs
+ * darker, more saturated ink for the same contrast. Every entry here is the
+ * published light counterpart of its dark one, not a mechanical darkening.
+ */
+export interface TerminalAnsi {
+    foreground: string;
+    black: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    brightBlack: string;
+    brightRed: string;
+    brightGreen: string;
+    brightYellow: string;
+    brightBlue: string;
+    brightMagenta: string;
+    brightCyan: string;
+    brightWhite: string;
+    cursor: string;
+    selectionBackground: string;
+}
+export interface TerminalPalette {
+    id: string;
+    label: string;
+    /** The colour that stands for this palette in a picker. */
+    swatch: string;
+    dark: TerminalAnsi;
+    light: TerminalAnsi;
+    /**
+     * The light half was computed, not authored.
+     *
+     * Worth carrying because it is worth SAYING: a derived variant is legible
+     * rather than designed, and a reader deciding whether to keep a theme should
+     * know which they are looking at.
+     */
+    lightDerived?: boolean;
+}
+/**
+ * Six, in the order they suit reading a shell.
+ *
+ * All are palettes people already recognise from their own editors, which is
+ * the point: a terminal in someone else's tool should be able to look like the
+ * one they configured for themselves.
+ */
+export declare const TERMINAL_PALETTES: TerminalPalette[];
+/**
+ * A palette resolved for the ground it will sit on.
+ *
+ * The background is passed in rather than chosen: whoever owns the surface
+ * knows what colour it is, and a terminal that picks its own would stop
+ * matching the panel the moment the panel changed.
+ */
+export declare function resolveTerminalTheme(palette: TerminalPalette, mode: 'dark' | 'light', background: string): Record<string, string>;
+/** Which variant a surface wants, from the colour of the surface itself. */
+export declare function groundMode(background: string): 'dark' | 'light';