react-cheminfo 0.8.0 → 0.10.0

package/lib/overlay/ui/overlayPanelStyles.js

@@ -0,0 +1,193 @@
+/**
+ * The rules a settings panel is drawn with.
+ *
+ * A panel is the one surface in this domain the reader stops and reads rather
+ * than glances at, and everything here follows from that. It says at the top
+ * which figure it belongs to, because a panel that opens behind a cog and
+ * never names itself leaves the reader guessing which of four pictures they
+ * are about to change. It offers a way back, because a configuration nobody
+ * understands any more is worse than the default it replaced. And it keeps its
+ * commands at the foot rather than among its rows, since a button that clears
+ * a selection is not a setting and reading as one costs the reader a mistake.
+ *
+ * The panel brings its own padding, so it belongs in a popover or a card that
+ * has none: nested inside a padded surface, its header rule stops short of
+ * both edges and reads as a mis-drawn line rather than as a header.
+ */
+import { OVERLAY_HELP_NAME_STYLE } from "./overlayRowStyles.js";
+/**
+ * The panel itself: a header, a body, and whatever the figure can be told to
+ * do at the foot.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The panel's rules.
+ */
+export function overlayPanelSurfaceStyle(metrics) {
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        minWidth: OVERLAY_PANEL_MIN_WIDTH,
+        color: 'var(--text)',
+        fontSize: metrics.fontSize,
+        lineHeight: 1.2,
+    };
+}
+/**
+ * The band across the top holding the title and the way back.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The header's rules.
+ */
+export function overlayPanelHeaderStyle(metrics) {
+    return {
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'space-between',
+        gap: metrics.gap,
+        padding: `${metrics.gap + 5}px ${metrics.gap + 8}px ${metrics.gap + 4}px`,
+        borderBottom: '1px solid var(--border)',
+    };
+}
+/**
+ * What the panel is called.
+ *
+ * Full strength and half a step heavier than the rows under it, which is the
+ * least that separates a title from one more caption.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The title's rules.
+ */
+export function overlayPanelTitleStyle(metrics) {
+    return {
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 4,
+        minWidth: 0,
+        color: 'var(--text)',
+        fontSize: metrics.fontSize,
+        fontWeight: 600,
+        whiteSpace: 'nowrap',
+    };
+}
+/**
+ * The way back to the settings the figure came with.
+ *
+ * Plain text rather than a button: it is the one thing in the header that is
+ * not the title, and drawing an outline around it would make it compete with
+ * the settings it undoes. It is faint until pointed at, then the accent, so a
+ * reader who is not looking for it never sees it and one who is finds it where
+ * every other panel keeps it.
+ * @param metrics - The measurements the card is drawn from.
+ * @param hovered - Whether the pointer is over it or the keyboard is on it.
+ * @returns The button's rules.
+ */
+export function overlayPanelResetStyle(metrics, hovered) {
+    return {
+        flex: 'none',
+        padding: 0,
+        border: 'none',
+        background: 'transparent',
+        color: hovered ? 'var(--accent)' : 'var(--text-faint)',
+        font: 'inherit',
+        fontSize: Math.max(10, metrics.labelSize + 1),
+        lineHeight: 1,
+        textDecoration: hovered ? 'underline' : 'none',
+        cursor: 'pointer',
+    };
+}
+/**
+ * The rows themselves, and the sections they are gathered into.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The body's rules.
+ */
+export function overlayPanelBodyStyle(metrics) {
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        rowGap: metrics.gap + 3,
+        padding: `${metrics.gap + 4}px ${metrics.gap + 8}px ${metrics.gap + 7}px`,
+    };
+}
+/**
+ * The one line at the foot that teaches the convention.
+ *
+ * Every name in the panel carries its own explanation and nothing says so; one
+ * sentence, once, is what turns a column of dotted underlines from a rendering
+ * oddity into an offer.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The line's rules.
+ */
+export function overlayPanelHintStyle(metrics) {
+    return {
+        margin: 0,
+        paddingTop: metrics.paddingY,
+        color: 'var(--text-faint)',
+        fontSize: Math.max(10, metrics.labelSize),
+        lineHeight: 1.45,
+    };
+}
+/**
+ * What the figure can be told to do, under a hairline.
+ *
+ * Below the rows and separated from them, because a command among the settings
+ * is a command the reader takes for a setting — and `Clear selection` read as
+ * a setting is a click nobody meant to make.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The footer's rules.
+ */
+export function overlayPanelFooterStyle(metrics) {
+    return {
+        display: 'flex',
+        flexWrap: 'wrap',
+        alignItems: 'center',
+        gap: metrics.gap,
+        padding: `${metrics.gap + 4}px ${metrics.gap + 8}px ${metrics.gap + 5}px`,
+        borderTop: '1px solid var(--border)',
+    };
+}
+/**
+ * One section of a panel: its heading and the rows under it.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The section's rules.
+ */
+export function overlaySectionStyle(metrics) {
+    return {
+        display: 'flex',
+        flexDirection: 'column',
+        rowGap: metrics.gap + 3,
+    };
+}
+/**
+ * What a section of a panel is called.
+ *
+ * Small capitals in the faintest ink the family has, over a hairline: the
+ * heading has to give the eye somewhere to rest without being read as one more
+ * setting, and anything that looks like the names under it is taken for one.
+ * @param metrics - The measurements the card is drawn from.
+ * @param look - See {@link OverlaySectionLook}.
+ * @returns The heading's rules.
+ */
+export function overlaySectionHeadingStyle(metrics, look) {
+    const { divider = true, help = false } = look;
+    return {
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 4,
+        marginTop: divider ? metrics.paddingY : 0,
+        paddingTop: divider ? metrics.gap + 5 : 0,
+        borderTop: divider ? '1px solid var(--border)' : undefined,
+        color: 'var(--text-faint)',
+        fontSize: Math.max(10, metrics.labelSize - 1),
+        fontWeight: 700,
+        letterSpacing: '0.07em',
+        textTransform: 'uppercase',
+        whiteSpace: 'nowrap',
+        ...(help ? OVERLAY_HELP_NAME_STYLE : undefined),
+    };
+}
+/**
+ * How narrow a panel is allowed to get.
+ *
+ * The name column and a segmented pair beside it, which is the widest row a
+ * panel routinely holds; below this the segments wrap and the grid stops being
+ * a grid.
+ */
+const OVERLAY_PANEL_MIN_WIDTH = 208;
+//# sourceMappingURL=overlayPanelStyles.js.map

package/lib/overlay/ui/overlayPanelStyles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayPanelStyles.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlayPanelStyles.ts"],"names":[],"mappings":"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"}

package/lib/overlay/ui/overlayPillKeys.d.ts

@@ -0,0 +1,19 @@
+/**
+ * How a keyboard moves along a row of pills.
+ *
+ * A pill group is a list laid out sideways, so the arrows that mean something
+ * to the reader are the horizontal ones — and the shared list navigation is
+ * written for a column. Rather than a second key handler that would drift from
+ * it, the two horizontal keys are read as the vertical ones and everything
+ * else is handed straight over: `Home` and `End` reach the two ends, the
+ * selection is clamped at both, and a key the list has no use for is left to
+ * the page.
+ */
+import type { ListNavigationHandlerOptions, ListNavigationKeyEvent } from '../../hooks/ui/listNavigation.ts';
+/**
+ * Move a pill group's selection from a keyboard event.
+ * @param event - The keyboard event, synthetic or native.
+ * @param options - See {@link ListNavigationHandlerOptions}.
+ */
+export declare function handleOverlayPillKey(event: ListNavigationKeyEvent, options: ListNavigationHandlerOptions): void;
+//# sourceMappingURL=overlayPillKeys.d.ts.map

package/lib/overlay/ui/overlayPillKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayPillKeys.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlayPillKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,4BAA4B,EAC5B,sBAAsB,EACvB,MAAM,kCAAkC,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,sBAAsB,EAC7B,OAAO,EAAE,4BAA4B,GACpC,IAAI,CAYN"}

package/lib/overlay/ui/overlayPillKeys.js

@@ -0,0 +1,33 @@
+/**
+ * How a keyboard moves along a row of pills.
+ *
+ * A pill group is a list laid out sideways, so the arrows that mean something
+ * to the reader are the horizontal ones — and the shared list navigation is
+ * written for a column. Rather than a second key handler that would drift from
+ * it, the two horizontal keys are read as the vertical ones and everything
+ * else is handed straight over: `Home` and `End` reach the two ends, the
+ * selection is clamped at both, and a key the list has no use for is left to
+ * the page.
+ */
+import { handleListNavigationKey } from "../../hooks/ui/listNavigation.js";
+/**
+ * Move a pill group's selection from a keyboard event.
+ * @param event - The keyboard event, synthetic or native.
+ * @param options - See {@link ListNavigationHandlerOptions}.
+ */
+export function handleOverlayPillKey(event, options) {
+    handleListNavigationKey({
+        key: SIDEWAYS_KEYS[event.key] ?? event.key,
+        target: event.target,
+        // Written out rather than spread from the event: `preventDefault` lives
+        // on the event's prototype, and a copy made by spreading arrives without
+        // it — at which point the page scrolls under every arrow key.
+        preventDefault: () => event.preventDefault(),
+    }, options);
+}
+/** The keys a sideways list is walked with, in the terms a column is. */
+const SIDEWAYS_KEYS = {
+    ArrowLeft: 'ArrowUp',
+    ArrowRight: 'ArrowDown',
+};
+//# sourceMappingURL=overlayPillKeys.js.map

package/lib/overlay/ui/overlayPillKeys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayPillKeys.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlayPillKeys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAE3E;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAA6B,EAC7B,OAAqC;IAErC,uBAAuB,CACrB;QACE,GAAG,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG;QAC1C,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,wEAAwE;QACxE,yEAAyE;QACzE,8DAA8D;QAC9D,cAAc,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,cAAc,EAAE;KAC7C,EACD,OAAO,CACR,CAAC;AACJ,CAAC;AAED,yEAAyE;AACzE,MAAM,aAAa,GAAqC;IACtD,SAAS,EAAE,SAAS;IACpB,UAAU,EAAE,WAAW;CACxB,CAAC"}

package/lib/overlay/ui/overlayPillStyles.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The rules the package's one segmented control is drawn with.
+ *
+ * A sunken track with the choice in force lifted out of it: the same device
+ * whether it is moving between a figure's views or picking one setting inside
+ * a card, and it is written here rather than in either component so the two
+ * cannot drift into looking like two different controls.
+ *
+ * Nothing here is filled with the site's accent. The strongest colour on the
+ * page belongs to the data, and a saturated block of it in the chrome above a
+ * scatter pulls the eye off the picture the reader came for — so the choice in
+ * force is told apart by being *raised* rather than by being coloured.
+ *
+ * The raising is said three ways at once — a lighter ground, darker ink, a
+ * heavier weight, and only then a shadow — because a reader who has asked the
+ * operating system for high contrast is shown no shadow at all, and a control
+ * whose one signal was the shadow then says nothing about which choice is in
+ * force.
+ */
+import type { CSSProperties } from 'react';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+/**
+ * How big a segmented group is drawn.
+ *
+ * `strip` is the figure's own tab bar, at the full height of a control.
+ * `setting` is one question inside a card, a little smaller so it reads as
+ * something the figure is set with rather than as a second tab bar.
+ */
+export type OverlaySegmentedSize = 'strip' | 'setting';
+/** How one segment stands among the others. */
+export interface OverlayPillLook {
+    /** Whether it is the choice in force. */
+    selected: boolean;
+    /**
+     * Whether it cannot be picked.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Which of the two sizes the group is drawn at.
+     * @default 'strip'
+     */
+    size?: OverlaySegmentedSize;
+}
+/**
+ * The sunken track the segments sit in.
+ *
+ * It carries no outline. A hairline around a group that is already a shade
+ * darker than the card is a fourth container edge in a bar that has room for
+ * one, and the sinking alone is what tells the reader the segments belong
+ * together.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The track's rules.
+ */
+export declare function overlayPillGroupStyle(metrics: OverlayMetrics, size?: OverlaySegmentedSize): CSSProperties;
+/**
+ * One segment.
+ *
+ * Its height is the track's less the band of track left showing above and
+ * below it, so the choice in force reads as a tile lying *in* the track rather
+ * than as a block that has covered it over.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayPillLook}.
+ * @returns The segment's rules.
+ */
+export declare function overlayPillStyle(metrics: OverlayMetrics, look: OverlayPillLook): CSSProperties;
+/**
+ * The count after a segment's label.
+ *
+ * The digits are tabular, so a row of counts does not shuffle the labels
+ * sideways as the numbers behind them change.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param selected - Whether it is on the choice in force.
+ * @returns The count's rules.
+ */
+export declare function overlayPillCountStyle(metrics: OverlayMetrics, selected: boolean): CSSProperties;
+//# sourceMappingURL=overlayPillStyles.d.ts.map

package/lib/overlay/ui/overlayPillStyles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayPillStyles.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlayPillStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvD,+CAA+C;AAC/C,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,IAAI,CAAC,EAAE,oBAAoB,CAAC;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,cAAc,EACvB,IAAI,GAAE,oBAA8B,GACnC,aAAa,CAWf;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,eAAe,GACpB,aAAa,CAuBf;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,OAAO,GAChB,aAAa,CAOf"}

package/lib/overlay/ui/overlayPillStyles.js

@@ -0,0 +1,140 @@
+/**
+ * The rules the package's one segmented control is drawn with.
+ *
+ * A sunken track with the choice in force lifted out of it: the same device
+ * whether it is moving between a figure's views or picking one setting inside
+ * a card, and it is written here rather than in either component so the two
+ * cannot drift into looking like two different controls.
+ *
+ * Nothing here is filled with the site's accent. The strongest colour on the
+ * page belongs to the data, and a saturated block of it in the chrome above a
+ * scatter pulls the eye off the picture the reader came for — so the choice in
+ * force is told apart by being *raised* rather than by being coloured.
+ *
+ * The raising is said three ways at once — a lighter ground, darker ink, a
+ * heavier weight, and only then a shadow — because a reader who has asked the
+ * operating system for high contrast is shown no shadow at all, and a control
+ * whose one signal was the shadow then says nothing about which choice is in
+ * force.
+ */
+/**
+ * The sunken track the segments sit in.
+ *
+ * It carries no outline. A hairline around a group that is already a shade
+ * darker than the card is a fourth container edge in a bar that has room for
+ * one, and the sinking alone is what tells the reader the segments belong
+ * together.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The track's rules.
+ */
+export function overlayPillGroupStyle(metrics, size = 'strip') {
+    return {
+        boxSizing: 'border-box',
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: OVERLAY_TRACK_GAP,
+        height: trackHeight(metrics, size),
+        padding: OVERLAY_TRACK_PADDING,
+        borderRadius: trackRadius(metrics),
+        background: 'var(--surface-sunken)',
+    };
+}
+/**
+ * One segment.
+ *
+ * Its height is the track's less the band of track left showing above and
+ * below it, so the choice in force reads as a tile lying *in* the track rather
+ * than as a block that has covered it over.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param look - See {@link OverlayPillLook}.
+ * @returns The segment's rules.
+ */
+export function overlayPillStyle(metrics, look) {
+    const { selected, disabled = false, size = 'strip' } = look;
+    return {
+        boxSizing: 'border-box',
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        gap: 4,
+        height: trackHeight(metrics, size) - OVERLAY_TRACK_PADDING * 2,
+        padding: `0 ${segmentPaddingX(metrics, size)}px`,
+        border: 'none',
+        borderRadius: trackRadius(metrics) - OVERLAY_TRACK_PADDING,
+        background: selected ? 'var(--surface)' : 'transparent',
+        color: selected ? 'var(--text)' : 'var(--text-muted)',
+        boxShadow: selected ? 'var(--shadow-sm)' : undefined,
+        font: 'inherit',
+        fontSize: metrics.fontSize,
+        fontWeight: selected ? 600 : 500,
+        lineHeight: 1,
+        whiteSpace: 'nowrap',
+        cursor: disabled ? 'default' : 'pointer',
+        opacity: disabled ? 0.6 : 1,
+    };
+}
+/**
+ * The count after a segment's label.
+ *
+ * The digits are tabular, so a row of counts does not shuffle the labels
+ * sideways as the numbers behind them change.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param selected - Whether it is on the choice in force.
+ * @returns The count's rules.
+ */
+export function overlayPillCountStyle(metrics, selected) {
+    return {
+        fontSize: Math.max(9, metrics.labelSize - 1),
+        fontVariantNumeric: 'tabular-nums',
+        fontWeight: 500,
+        opacity: selected ? 0.85 : 0.75,
+    };
+}
+/**
+ * The band of track showing around a segment, on every side.
+ *
+ * Two pixels: enough that the lifted tile is read as sitting inside something,
+ * and little enough that the group still stands as tall as the controls beside
+ * it.
+ */
+const OVERLAY_TRACK_PADDING = 2;
+/** What is left between two segments, which is the track showing through. */
+const OVERLAY_TRACK_GAP = 2;
+/**
+ * How tall the track stands.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The height in pixels.
+ */
+function trackHeight(metrics, size) {
+    if (size === 'strip')
+        return metrics.controlHeight;
+    return Math.max(20, metrics.controlHeight - 4);
+}
+/**
+ * The track's corner.
+ *
+ * Two pixels rounder than a control of the same height, because the segment
+ * inside it takes that pair back and a tile with a square corner in a rounded
+ * track reads as a misfit rather than as a lift.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @returns The radius in pixels.
+ */
+function trackRadius(metrics) {
+    return metrics.controlRadius + 2;
+}
+/**
+ * The room each side of a segment's label.
+ *
+ * The type does not shrink with the smaller size — a control that is quieter
+ * should take less room, not become harder to read — so only the room around
+ * the words goes.
+ * @param metrics - The measurements the chrome is drawn from.
+ * @param size - Which of the two sizes it is drawn at.
+ * @returns The padding in pixels.
+ */
+function segmentPaddingX(metrics, size) {
+    return size === 'strip' ? metrics.paddingX + 2 : metrics.paddingX;
+}
+//# sourceMappingURL=overlayPillStyles.js.map

package/lib/overlay/ui/overlayPillStyles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayPillStyles.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlayPillStyles.ts"],"names":[],"mappings":"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"}

package/lib/overlay/ui/overlayRowStyles.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The rules one caption-and-control pair is drawn with.
+ *
+ * A row is the unit both a bar and a settings panel are built from, and the
+ * two want different geometry out of it. On a bar the caption sits against its
+ * control and the pair hugs its own width, because the bar is a line of
+ * separate things. In a panel every control has to start at the same x, or the
+ * reader has no column to run their eye down and the panel has to be read
+ * rather than scanned. Both shapes are written here so that a row cannot end
+ * up half one and half the other.
+ *
+ * The name is also where a row's help lives. A panel that hangs a question
+ * mark off every control stacks a column of glyphs down its left edge, and the
+ * eye reads that column before it reads any of the words; a dotted underline
+ * on the name says the same thing with no ink of its own, and leaves the words
+ * the widest thing in the panel.
+ */
+import type { CSSProperties } from 'react';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+/**
+ * One caption-and-control pair on a bar.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The row's rules.
+ */
+export declare function overlayRowStyle(metrics: OverlayMetrics): CSSProperties;
+/**
+ * One caption-and-control pair in a settings panel.
+ *
+ * Two columns of fixed width rather than a flexible line: the whole complaint
+ * a panel of ragged rows draws is that every control starts at a different x,
+ * and a name column that is only as wide as the words in it is a column that
+ * moves from panel to panel.
+ * @param metrics - The measurements the card is drawn from.
+ * @param nameWidth - Width of the name column, in pixels.
+ * @returns The row's rules.
+ */
+export declare function overlayGridRowStyle(metrics: OverlayMetrics, nameWidth: number): CSSProperties;
+/**
+ * How wide the name column is.
+ *
+ * Eight characters of the caption's own type plus the room a descender needs:
+ * enough for `Bar order` and `Averages` without wrapping, and derived from the
+ * type size rather than fixed, so a panel a reader has asked for at a larger
+ * size widens its column with its words instead of breaking them.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The width, in pixels.
+ */
+export declare function overlayNameColumnWidth(metrics: OverlayMetrics): number;
+/** The control's own cell of a panel row. */
+export declare const OVERLAY_GRID_CELL_STYLE: {
+    readonly display: "flex";
+    readonly alignItems: "center";
+    readonly minWidth: 0;
+};
+/** How a row's name stands. */
+export interface OverlayNameLook {
+    /**
+     * Whether the name carries the control's explanation.
+     * @default false
+     */
+    help?: boolean;
+    /**
+     * Whether the control it names cannot be reached.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * The name of a control.
+ *
+ * It never wraps: a name breaking over two lines makes the row taller than the
+ * control it names, which reads as a fault in the layout rather than as a long
+ * word. When it carries help it is underlined with dots and takes the help
+ * cursor, which is the one convention that lets every question mark leave the
+ * panel — and it fades with its control, because a name at full strength over
+ * a greyed control reads as half broken rather than as unavailable.
+ * @param metrics - The measurements the card is drawn from.
+ * @param look - See {@link OverlayNameLook}.
+ * @returns The name's rules.
+ */
+export declare function overlayNameStyle(metrics: OverlayMetrics, look: OverlayNameLook): CSSProperties;
+/**
+ * What any name gains when it is the thing carrying the explanation.
+ *
+ * Written apart from {@link overlayNameStyle} because a section heading is a
+ * name too, and the reader has to be taught the convention once rather than
+ * per kind of label.
+ */
+export declare const OVERLAY_HELP_NAME_STYLE: {
+    readonly textDecoration: "underline dotted var(--border-strong)";
+    readonly textUnderlineOffset: 3;
+    readonly cursor: "help";
+};
+/**
+ * What a name gains when its control cannot be reached.
+ *
+ * A control that does not apply is greyed rather than removed, because one
+ * that vanishes teaches the reader nothing about why it went.
+ */
+export declare const OVERLAY_FADED_NAME_STYLE: {
+    readonly opacity: 0.6;
+};
+/**
+ * One caption-and-control pair whose caption sits above the control.
+ *
+ * Reached once the captions are long enough that writing them in front of
+ * their controls would push the card past a third of the figure — at which
+ * point the chrome is hiding more of the picture than the captions are worth.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The stacked row's rules.
+ */
+export declare function overlayStackedRowStyle(metrics: OverlayMetrics): CSSProperties;
+//# sourceMappingURL=overlayRowStyles.d.ts.map

package/lib/overlay/ui/overlayRowStyles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlayRowStyles.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlayRowStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAOtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,MAAM,GAChB,aAAa,CASf;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAEtE;AAED,6CAA6C;AAC7C,eAAO,MAAM,uBAAuB;;;;CAIF,CAAC;AAEnC,+BAA+B;AAC/B,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,eAAe,GACpB,aAAa,CAWf;AAED;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;;;;CAIF,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB;;CAEH,CAAC;AAEnC;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAQ7E"}