react-cheminfo 0.8.0 → 0.10.0

package/lib/overlay/ui/overlayRowStyles.js

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+/**
+ * One caption-and-control pair on a bar.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The row's rules.
+ */
+export function overlayRowStyle(metrics) {
+    return {
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: Math.max(4, metrics.gap - 2),
+        minHeight: metrics.controlHeight,
+    };
+}
+/**
+ * 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 function overlayGridRowStyle(metrics, nameWidth) {
+    return {
+        display: 'grid',
+        gridTemplateColumns: `${nameWidth}px minmax(0, 1fr)`,
+        alignItems: 'center',
+        columnGap: Math.max(10, metrics.gap + 2),
+        minHeight: metrics.controlHeight,
+        width: '100%',
+    };
+}
+/**
+ * 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 function overlayNameColumnWidth(metrics) {
+    return metrics.labelSize * 8 + 8;
+}
+/** The control's own cell of a panel row. */
+export const OVERLAY_GRID_CELL_STYLE = {
+    display: 'flex',
+    alignItems: 'center',
+    minWidth: 0,
+};
+/**
+ * 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 function overlayNameStyle(metrics, look) {
+    const { help = false, disabled = false } = look;
+    return {
+        color: 'var(--text-muted)',
+        fontSize: metrics.labelSize,
+        fontWeight: 500,
+        whiteSpace: 'nowrap',
+        userSelect: 'none',
+        ...(help ? OVERLAY_HELP_NAME_STYLE : undefined),
+        ...(disabled ? OVERLAY_FADED_NAME_STYLE : undefined),
+    };
+}
+/**
+ * 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 const OVERLAY_HELP_NAME_STYLE = {
+    textDecoration: 'underline dotted var(--border-strong)',
+    textUnderlineOffset: 3,
+    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 const OVERLAY_FADED_NAME_STYLE = {
+    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 function overlayStackedRowStyle(metrics) {
+    return {
+        display: 'inline-flex',
+        flexDirection: 'column',
+        alignItems: 'flex-start',
+        gap: 2,
+        minHeight: metrics.controlHeight,
+    };
+}
+//# sourceMappingURL=overlayRowStyles.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlayRowStyles.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlayRowStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,OAAuB;IACrD,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,UAAU,EAAE,QAAQ;QACpB,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;QACjC,SAAS,EAAE,OAAO,CAAC,aAAa;KACjC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAAuB,EACvB,SAAiB;IAEjB,OAAO;QACL,OAAO,EAAE,MAAM;QACf,mBAAmB,EAAE,GAAG,SAAS,mBAAmB;QACpD,UAAU,EAAE,QAAQ;QACpB,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC;QACxC,SAAS,EAAE,OAAO,CAAC,aAAa;QAChC,KAAK,EAAE,MAAM;KACd,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAuB;IAC5D,OAAO,OAAO,CAAC,SAAS,GAAG,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAED,6CAA6C;AAC7C,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,OAAO,EAAE,MAAM;IACf,UAAU,EAAE,QAAQ;IACpB,QAAQ,EAAE,CAAC;CACqB,CAAC;AAgBnC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAAuB,EACvB,IAAqB;IAErB,MAAM,EAAE,IAAI,GAAG,KAAK,EAAE,QAAQ,GAAG,KAAK,EAAE,GAAG,IAAI,CAAC;IAChD,OAAO;QACL,KAAK,EAAE,mBAAmB;QAC1B,QAAQ,EAAE,OAAO,CAAC,SAAS;QAC3B,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,QAAQ;QACpB,UAAU,EAAE,MAAM;QAClB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;QAC/C,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC,SAAS,CAAC;KACrD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,cAAc,EAAE,uCAAuC;IACvD,mBAAmB,EAAE,CAAC;IACtB,MAAM,EAAE,MAAM;CACkB,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,OAAO,EAAE,GAAG;CACoB,CAAC;AAEnC;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAuB;IAC5D,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,aAAa,EAAE,QAAQ;QACvB,UAAU,EAAE,YAAY;QACxB,GAAG,EAAE,CAAC;QACN,SAAS,EAAE,OAAO,CAAC,aAAa;KACjC,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,51 @@
+/**
+ * What a stepper is drawn with: one sunken track holding two square buttons
+ * and the value between them.
+ *
+ * They are their own module because the three rules are read together — the
+ * track's padding, the button's side and the value's width have to add up to
+ * the control height the rest of the card is built on, and a change to one of
+ * them that is not a change to the others is a bug.
+ */
+import type { CSSProperties } from 'react';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+/**
+ * The two buttons of a stepper and the value between them.
+ *
+ * They are packed tighter than the card's own gap so the three read as one
+ * control rather than as two buttons that happen to sit beside a number.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The stepper's rules.
+ */
+export declare function overlayStepperStyle(metrics: OverlayMetrics): CSSProperties;
+/**
+ * One of a stepper's two buttons.
+ *
+ * Square and unpadded, because a stepper's job is to be pressed repeatedly and
+ * the two buttons should sit within a thumb's width of each other. Blueprint's
+ * own button carries the padding of a button that holds a word, which is what
+ * made `− 2 +` measure ninety-six pixels for a single digit.
+ *
+ * At the end of its range the button fades and stops offering the pointer a
+ * hand. A `disabled` attribute alone stops the click but says nothing before
+ * it: the reader presses `+` on a four-component model, nothing happens, and
+ * the only reading available to them is that the control is broken.
+ * @param metrics - The measurements the card is drawn from.
+ * @param spent - Whether the range has no more room in this direction.
+ * @returns The button's rules.
+ */
+export declare function overlayStepperButtonStyle(metrics: OverlayMetrics, spent: boolean): CSSProperties;
+/**
+ * The value a stepper is showing.
+ *
+ * The digits are tabular and the box is held at the width of the longest value
+ * the range can produce, because a value that changes width as the reader
+ * steps through it drags the buttons out from under the pointer that is
+ * pressing them — and stepping from 9 to 10 is exactly when the reader is
+ * pressing the same button repeatedly.
+ * @param metrics - The measurements the card is drawn from.
+ * @param widest - How many characters the longest value writes.
+ * @returns The value's rules.
+ */
+export declare function overlayNumberValueStyle(metrics: OverlayMetrics, widest: number): CSSProperties;
+//# sourceMappingURL=overlayStepperStyles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlayStepperStyles.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlayStepperStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAU1E;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,OAAO,GACb,aAAa,CAmBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,MAAM,GACb,aAAa,CAaf"}

package/lib/overlay/ui/overlayStepperStyles.js

@@ -0,0 +1,96 @@
+/**
+ * What a stepper is drawn with: one sunken track holding two square buttons
+ * and the value between them.
+ *
+ * They are their own module because the three rules are read together — the
+ * track's padding, the button's side and the value's width have to add up to
+ * the control height the rest of the card is built on, and a change to one of
+ * them that is not a change to the others is a bug.
+ */
+/**
+ * The two buttons of a stepper and the value between them.
+ *
+ * They are packed tighter than the card's own gap so the three read as one
+ * control rather than as two buttons that happen to sit beside a number.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The stepper's rules.
+ */
+export function overlayStepperStyle(metrics) {
+    return {
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 0,
+        height: metrics.controlHeight,
+        padding: 2,
+        borderRadius: metrics.controlRadius,
+        background: 'var(--surface-sunken)',
+    };
+}
+/**
+ * One of a stepper's two buttons.
+ *
+ * Square and unpadded, because a stepper's job is to be pressed repeatedly and
+ * the two buttons should sit within a thumb's width of each other. Blueprint's
+ * own button carries the padding of a button that holds a word, which is what
+ * made `− 2 +` measure ninety-six pixels for a single digit.
+ *
+ * At the end of its range the button fades and stops offering the pointer a
+ * hand. A `disabled` attribute alone stops the click but says nothing before
+ * it: the reader presses `+` on a four-component model, nothing happens, and
+ * the only reading available to them is that the control is broken.
+ * @param metrics - The measurements the card is drawn from.
+ * @param spent - Whether the range has no more room in this direction.
+ * @returns The button's rules.
+ */
+export function overlayStepperButtonStyle(metrics, spent) {
+    const side = metrics.controlHeight - 4;
+    return {
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: side,
+        height: side,
+        padding: 0,
+        border: 'none',
+        borderRadius: Math.max(3, metrics.controlRadius - 2),
+        background: 'transparent',
+        color: spent ? 'var(--text-faint)' : 'var(--text-muted)',
+        font: 'inherit',
+        fontSize: metrics.fontSize + 1,
+        lineHeight: 1,
+        cursor: spent ? 'default' : 'pointer',
+        opacity: spent ? 0.45 : 1,
+    };
+}
+/**
+ * The value a stepper is showing.
+ *
+ * The digits are tabular and the box is held at the width of the longest value
+ * the range can produce, because a value that changes width as the reader
+ * steps through it drags the buttons out from under the pointer that is
+ * pressing them — and stepping from 9 to 10 is exactly when the reader is
+ * pressing the same button repeatedly.
+ * @param metrics - The measurements the card is drawn from.
+ * @param widest - How many characters the longest value writes.
+ * @returns The value's rules.
+ */
+export function overlayNumberValueStyle(metrics, widest) {
+    return {
+        minWidth: Math.max(metrics.fontSize, Math.ceil(widest * metrics.fontSize * CHARACTER_WIDTH)),
+        padding: '0 3px',
+        color: 'var(--text)',
+        fontSize: metrics.fontSize,
+        fontVariantNumeric: 'tabular-nums',
+        textAlign: 'center',
+        userSelect: 'none',
+    };
+}
+/**
+ * How wide one tabular digit is, as a fraction of the type size.
+ *
+ * Six tenths of an em is what the interface faces of every platform the family
+ * runs on set their figures at; a unit written in letters is narrower than
+ * that, so the reserved width errs wide and the buttons never move.
+ */
+const CHARACTER_WIDTH = 0.6;
+//# sourceMappingURL=overlayStepperStyles.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlayStepperStyles.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlayStepperStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAuB;IACzD,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,UAAU,EAAE,QAAQ;QACpB,GAAG,EAAE,CAAC;QACN,MAAM,EAAE,OAAO,CAAC,aAAa;QAC7B,OAAO,EAAE,CAAC;QACV,YAAY,EAAE,OAAO,CAAC,aAAa;QACnC,UAAU,EAAE,uBAAuB;KACpC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAuB,EACvB,KAAc;IAEd,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,GAAG,CAAC,CAAC;IACvC,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,UAAU,EAAE,QAAQ;QACpB,cAAc,EAAE,QAAQ;QACxB,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,IAAI;QACZ,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,MAAM;QACd,YAAY,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,aAAa,GAAG,CAAC,CAAC;QACpD,UAAU,EAAE,aAAa;QACzB,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,mBAAmB;QACxD,IAAI,EAAE,SAAS;QACf,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,CAAC;QAC9B,UAAU,EAAE,CAAC;QACb,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACrC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;KAC1B,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAuB,EACvB,MAAc;IAEd,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,GAAG,CAChB,OAAO,CAAC,QAAQ,EAChB,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,eAAe,CAAC,CACvD;QACD,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE,aAAa;QACpB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,kBAAkB,EAAE,cAAc;QAClC,SAAS,EAAE,QAAQ;QACnB,UAAU,EAAE,MAAM;KACnB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,GAAG,CAAC"}

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

@@ -0,0 +1,123 @@
+/**
+ * Every rule the floating chrome is drawn with.
+ *
+ * The domain's one design decision is here rather than spread over sixteen
+ * components: a card floating over a figure is a *quiet* surface. It is
+ * translucent so the reader can see that there is a picture underneath it, it
+ * is separated from the picture by a hairline rather than a shadow the eye
+ * reads as a dialog, and at rest only its ground fades — never its text.
+ *
+ * That last point is why the ground is a layer of its own instead of an
+ * `opacity` on the card. Fading the whole card fades the words with it, and a
+ * label at three-quarters strength over a busy scatter is unreadable exactly
+ * when the reader needs it. So the ground fades to `restingOpacity` and the
+ * content sits above it at full strength.
+ *
+ * Every colour is a family token. Nothing here writes a literal, so a card
+ * over a chart on any site of the family is the site's own grey.
+ */
+import type { CSSProperties } from 'react';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+import type { OverlayPlacement } from '../core/overlayPlacement.ts';
+/** The inert layer covering a figure, which every pointer event passes through. */
+export declare const OVERLAY_LAYER_STYLE: {
+    readonly position: "absolute";
+    readonly inset: 0;
+    readonly pointerEvents: "none";
+    readonly overflow: "hidden";
+};
+/**
+ * Where one card sits over the figure.
+ *
+ * The card takes the pointer back from the layer, so a control can be clicked
+ * while a drag started anywhere else still reaches the figure underneath.
+ *
+ * A docked card is laid out in the flow but is still made `relative`, because
+ * its ground is an absolutely positioned sibling of its content and has to be
+ * held by the card rather than by whatever is positioned further up. Left
+ * `static`, the ground escapes to the nearest positioned ancestor — the figure
+ * — and paints the whole picture in opaque white, and because the ground takes
+ * no pointer events, nothing under it reports being covered. That holds for
+ * the stretched bar too, which is docked in exactly the same way.
+ * @param placement - Which corner it sits in, or whether it is docked outside.
+ * @param metrics - The measurements it is drawn from.
+ * @returns The positioning rules.
+ */
+export declare function overlayCardStyle(placement: OverlayPlacement, metrics: OverlayMetrics): CSSProperties;
+/**
+ * The translucent ground behind a card's content.
+ *
+ * The blur is dropped while the figure is repainting: a backdrop filter is
+ * recomputed every time the pixels behind it change, which during a lasso drag
+ * is every frame, and the flat fill is indistinguishable at these opacities.
+ * @param opacity - How opaque the ground is, 0 to 1.
+ * @param busy - Whether the figure underneath is repainting.
+ * @returns The ground's rules.
+ */
+export declare function overlayGroundStyle(opacity: number, busy: boolean): CSSProperties;
+/**
+ * The row of controls inside a card, above its ground.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The content's rules.
+ */
+export declare function overlayContentStyle(metrics: OverlayMetrics): CSSProperties;
+/**
+ * The controls a card's button opens, behind the strip.
+ *
+ * A column where the strip is a wrapping row, because a card folds exactly
+ * when the figure is narrow, and a row of controls in a popover over a narrow
+ * figure is a row that reaches past the edge of the screen.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The panel's rules.
+ */
+export declare function overlayPanelStyle(metrics: OverlayMetrics): CSSProperties;
+/**
+ * How opaque a card's ground is drawn while nothing is pointing at the figure.
+ *
+ * Floored whatever the caller asks for: under about six tenths the card is a
+ * ghost over a busy scatter, and a control the reader cannot find is worse
+ * than one that costs a little of the picture.
+ * @param asked - The opacity the caller asked for.
+ * @returns The opacity the ground is drawn at.
+ */
+export declare function overlayRestingOpacity(asked: number): number;
+/** What a card's ground fades to when the caller does not say. */
+export declare const OVERLAY_RESTING_OPACITY = 0.74;
+/**
+ * The ground behind a bar that spans the whole width of the figure.
+ *
+ * Solid, unblurred and never faded, where a floating card is translucent: a
+ * strip across the full width is chrome the figure is mounted in rather than
+ * something laid on top of it, and a blurred translucent band over the top of
+ * an embedded figure reads as a rendering fault. The hairline is at the foot
+ * alone, so the bar is separated from the picture it introduces without being
+ * boxed off from the page that is hosting it.
+ */
+export declare const OVERLAY_BAR_GROUND_STYLE: {
+    readonly position: "absolute";
+    readonly inset: 0;
+    readonly borderBottom: "1px solid var(--border)";
+    readonly background: "var(--surface)";
+    readonly pointerEvents: "none";
+};
+/**
+ * The row inside a stretched bar, whose two ends are pushed apart.
+ *
+ * It never wraps. A bar that wrapped would change the figure's height as the
+ * page around it resized, and an embedded figure that moves the host's layout
+ * while it is being read is worse than one whose second-tier controls have
+ * folded away into the button at its end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The row's rules.
+ */
+export declare function overlayBarContentStyle(metrics: OverlayMetrics): CSSProperties;
+/**
+ * One end of a stretched bar.
+ *
+ * Both ends are drawn from the same rule, so the pills at the start and the
+ * controls at the end keep one rhythm across the width between them.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The end's rules.
+ */
+export declare function overlayBarSideStyle(metrics: OverlayMetrics): CSSProperties;
+//# sourceMappingURL=overlayStyles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlayStyles.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlayStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAGpE,mFAAmF;AACnF,eAAO,MAAM,mBAAmB;;;;;CAKE,CAAC;AAEnC;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,EAAE,cAAc,GACtB,aAAa,CAYf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,OAAO,GACZ,aAAa,CAaf;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAY1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAQxE;AAoBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,kEAAkE;AAClE,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAE5C;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB;;;;;;CAMH,CAAC;AAEnC;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAQ7E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAO1E"}

package/lib/overlay/ui/overlayStyles.js

@@ -0,0 +1,203 @@
+/**
+ * Every rule the floating chrome is drawn with.
+ *
+ * The domain's one design decision is here rather than spread over sixteen
+ * components: a card floating over a figure is a *quiet* surface. It is
+ * translucent so the reader can see that there is a picture underneath it, it
+ * is separated from the picture by a hairline rather than a shadow the eye
+ * reads as a dialog, and at rest only its ground fades — never its text.
+ *
+ * That last point is why the ground is a layer of its own instead of an
+ * `opacity` on the card. Fading the whole card fades the words with it, and a
+ * label at three-quarters strength over a busy scatter is unreadable exactly
+ * when the reader needs it. So the ground fades to `restingOpacity` and the
+ * content sits above it at full strength.
+ *
+ * Every colour is a family token. Nothing here writes a literal, so a card
+ * over a chart on any site of the family is the site's own grey.
+ */
+import { overlayCornerStyle } from "../core/overlayPlacement.js";
+/** The inert layer covering a figure, which every pointer event passes through. */
+export const OVERLAY_LAYER_STYLE = {
+    position: 'absolute',
+    inset: 0,
+    pointerEvents: 'none',
+    overflow: 'hidden',
+};
+/**
+ * Where one card sits over the figure.
+ *
+ * The card takes the pointer back from the layer, so a control can be clicked
+ * while a drag started anywhere else still reaches the figure underneath.
+ *
+ * A docked card is laid out in the flow but is still made `relative`, because
+ * its ground is an absolutely positioned sibling of its content and has to be
+ * held by the card rather than by whatever is positioned further up. Left
+ * `static`, the ground escapes to the nearest positioned ancestor — the figure
+ * — and paints the whole picture in opaque white, and because the ground takes
+ * no pointer events, nothing under it reports being covered. That holds for
+ * the stretched bar too, which is docked in exactly the same way.
+ * @param placement - Which corner it sits in, or whether it is docked outside.
+ * @param metrics - The measurements it is drawn from.
+ * @returns The positioning rules.
+ */
+export function overlayCardStyle(placement, metrics) {
+    if (placement === 'stretch')
+        return OVERLAY_STRETCHED_CARD_STYLE;
+    const corner = overlayCornerStyle(placement, metrics.inset);
+    return {
+        ...corner,
+        position: corner.position === 'absolute' ? 'absolute' : 'relative',
+        display: 'inline-flex',
+        maxWidth: `calc(100% - ${metrics.inset * 2}px)`,
+        borderRadius: 'var(--radius)',
+        pointerEvents: 'auto',
+        isolation: 'isolate',
+    };
+}
+/**
+ * The translucent ground behind a card's content.
+ *
+ * The blur is dropped while the figure is repainting: a backdrop filter is
+ * recomputed every time the pixels behind it change, which during a lasso drag
+ * is every frame, and the flat fill is indistinguishable at these opacities.
+ * @param opacity - How opaque the ground is, 0 to 1.
+ * @param busy - Whether the figure underneath is repainting.
+ * @returns The ground's rules.
+ */
+export function overlayGroundStyle(opacity, busy) {
+    return {
+        position: 'absolute',
+        inset: 0,
+        borderRadius: 'var(--radius)',
+        border: '1px solid var(--border)',
+        background: 'var(--surface)',
+        boxShadow: 'var(--shadow-sm)',
+        backdropFilter: busy ? undefined : 'blur(8px) saturate(1.4)',
+        opacity,
+        transition: 'opacity 120ms ease-out',
+        pointerEvents: 'none',
+    };
+}
+/**
+ * The row of controls inside a card, above its ground.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The content's rules.
+ */
+export function overlayContentStyle(metrics) {
+    return {
+        position: 'relative',
+        display: 'flex',
+        flexWrap: 'wrap',
+        alignItems: 'center',
+        gap: metrics.gap,
+        padding: `${metrics.paddingY}px ${metrics.paddingX}px`,
+        color: 'var(--text)',
+        fontSize: metrics.fontSize,
+        lineHeight: 1.2,
+    };
+}
+/**
+ * The controls a card's button opens, behind the strip.
+ *
+ * A column where the strip is a wrapping row, because a card folds exactly
+ * when the figure is narrow, and a row of controls in a popover over a narrow
+ * figure is a row that reaches past the edge of the screen.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The panel's rules.
+ */
+export function overlayPanelStyle(metrics) {
+    return {
+        ...overlayContentStyle(metrics),
+        flexWrap: 'nowrap',
+        flexDirection: 'column',
+        alignItems: 'stretch',
+        minWidth: 168,
+    };
+}
+/**
+ * A bar that spans the whole width of the figure.
+ *
+ * It takes the width rather than hugging its contents, since the two ends are
+ * only pushed apart once there is width between them to push into. It carries
+ * no corner radius of its own: a rounded strip flush against the top of a
+ * figure leaves two slivers of the page showing through its corners, which
+ * reads as a gap in the chrome rather than as a rounded card.
+ */
+const OVERLAY_STRETCHED_CARD_STYLE = {
+    position: 'relative',
+    display: 'flex',
+    width: '100%',
+    maxWidth: '100%',
+    pointerEvents: 'auto',
+    isolation: 'isolate',
+};
+/**
+ * How opaque a card's ground is drawn while nothing is pointing at the figure.
+ *
+ * Floored whatever the caller asks for: under about six tenths the card is a
+ * ghost over a busy scatter, and a control the reader cannot find is worse
+ * than one that costs a little of the picture.
+ * @param asked - The opacity the caller asked for.
+ * @returns The opacity the ground is drawn at.
+ */
+export function overlayRestingOpacity(asked) {
+    if (!Number.isFinite(asked))
+        return OVERLAY_RESTING_OPACITY;
+    return Math.min(1, Math.max(0.6, asked));
+}
+/** What a card's ground fades to when the caller does not say. */
+export const OVERLAY_RESTING_OPACITY = 0.74;
+/**
+ * The ground behind a bar that spans the whole width of the figure.
+ *
+ * Solid, unblurred and never faded, where a floating card is translucent: a
+ * strip across the full width is chrome the figure is mounted in rather than
+ * something laid on top of it, and a blurred translucent band over the top of
+ * an embedded figure reads as a rendering fault. The hairline is at the foot
+ * alone, so the bar is separated from the picture it introduces without being
+ * boxed off from the page that is hosting it.
+ */
+export const OVERLAY_BAR_GROUND_STYLE = {
+    position: 'absolute',
+    inset: 0,
+    borderBottom: '1px solid var(--border)',
+    background: 'var(--surface)',
+    pointerEvents: 'none',
+};
+/**
+ * The row inside a stretched bar, whose two ends are pushed apart.
+ *
+ * It never wraps. A bar that wrapped would change the figure's height as the
+ * page around it resized, and an embedded figure that moves the host's layout
+ * while it is being read is worse than one whose second-tier controls have
+ * folded away into the button at its end.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The row's rules.
+ */
+export function overlayBarContentStyle(metrics) {
+    return {
+        ...overlayContentStyle(metrics),
+        flexWrap: 'nowrap',
+        justifyContent: 'space-between',
+        width: '100%',
+        minWidth: 0,
+    };
+}
+/**
+ * One end of a stretched bar.
+ *
+ * Both ends are drawn from the same rule, so the pills at the start and the
+ * controls at the end keep one rhythm across the width between them.
+ * @param metrics - The measurements the bar is drawn from.
+ * @returns The end's rules.
+ */
+export function overlayBarSideStyle(metrics) {
+    return {
+        display: 'flex',
+        alignItems: 'center',
+        gap: metrics.gap,
+        minWidth: 0,
+    };
+}
+//# sourceMappingURL=overlayStyles.js.map

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

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