react-cheminfo 0.9.0 → 0.11.0

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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"}

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

@@ -0,0 +1,54 @@
+/**
+ * What the floating chrome over one figure agrees on.
+ *
+ * Two cards over the same scatter that disagree about how tightly to pack
+ * their controls, or about whether the figure is repainting, read as two
+ * pieces of software sitting on one picture. So the measurements are settled
+ * once by the layer, and every card reads them back from here rather than
+ * deciding for itself.
+ */
+import type { OverlayMetrics, OverlayPointerKind } from '../core/overlayMetrics.ts';
+/** What every control inside an {@link OverlayLayer} reads from it. */
+export interface OverlaySurface {
+    /** The measurements every card and control is drawn from. */
+    metrics: OverlayMetrics;
+    /** Whether the cards are at full strength rather than resting. */
+    awake: boolean;
+    /**
+     * Whether the figure is repainting. While it is, a card drops its backdrop
+     * blur for a flat fill, because a blur is recomputed every time the pixels
+     * behind it change — which during a lasso drag is every frame.
+     */
+    busy: boolean;
+    /** Width of the figure, in pixels; `0` before it has been measured. */
+    width: number;
+    /** What the reader is pointing with. */
+    pointer: OverlayPointerKind;
+}
+/**
+ * The surface a floating control is sitting on.
+ *
+ * A control rendered with no {@link OverlayLayer} above it gets a comfortable,
+ * awake, unmeasured surface, so every component in this domain is usable on
+ * its own and renders correctly to a string.
+ * @returns The surface.
+ */
+export declare function useOverlaySurface(): OverlaySurface;
+/**
+ * Whether the pointer on this page is a finger.
+ *
+ * Returns `false` where `matchMedia` is missing, which is what keeps the
+ * string-rendering tests working — the same guard `useResizeObserver` applies
+ * to a missing `ResizeObserver`.
+ * @returns Whether the pointer is coarse.
+ */
+export declare function useCoarsePointer(): boolean;
+/**
+ * The surface an {@link OverlayLayer} hands down to the cards inside it.
+ *
+ * Published for the layer alone. A control reaches it through
+ * {@link useOverlaySurface}, which is what leaves it with real measurements
+ * when nobody wrapped it in a layer at all.
+ */
+export declare const OverlaySurfaceContext: import("react").Context<OverlaySurface>;
+//# sourceMappingURL=overlaySurface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlaySurface.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlaySurface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EACnB,MAAM,2BAA2B,CAAC;AAGnC,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,OAAO,EAAE,cAAc,CAAC;IACxB,kEAAkE;IAClE,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,wCAAwC;IACxC,OAAO,EAAE,kBAAkB,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAM1C;AAiBD;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB,yCACgB,CAAC"}

package/lib/overlay/ui/overlaySurface.js

@@ -0,0 +1,85 @@
+/**
+ * What the floating chrome over one figure agrees on.
+ *
+ * Two cards over the same scatter that disagree about how tightly to pack
+ * their controls, or about whether the figure is repainting, read as two
+ * pieces of software sitting on one picture. So the measurements are settled
+ * once by the layer, and every card reads them back from here rather than
+ * deciding for itself.
+ */
+import { createContext, useContext, useSyncExternalStore } from 'react';
+import { overlayMetrics } from "../core/overlayMetrics.js";
+/**
+ * The surface a floating control is sitting on.
+ *
+ * A control rendered with no {@link OverlayLayer} above it gets a comfortable,
+ * awake, unmeasured surface, so every component in this domain is usable on
+ * its own and renders correctly to a string.
+ * @returns The surface.
+ */
+export function useOverlaySurface() {
+    return useContext(OverlaySurfaceContext);
+}
+/**
+ * Whether the pointer on this page is a finger.
+ *
+ * Returns `false` where `matchMedia` is missing, which is what keeps the
+ * string-rendering tests working — the same guard `useResizeObserver` applies
+ * to a missing `ResizeObserver`.
+ * @returns Whether the pointer is coarse.
+ */
+export function useCoarsePointer() {
+    return useSyncExternalStore(subscribeToPointerKind, readPointerKind, readFinePointer);
+}
+/**
+ * What a control gets when there is no layer above it.
+ *
+ * Awake rather than resting: a card with nobody watching the pointer on its
+ * behalf would otherwise sit at three-quarters strength for ever, with no way
+ * for the reader to bring it up.
+ */
+const UNWRAPPED_SURFACE = {
+    metrics: overlayMetrics('comfortable', 'fine'),
+    awake: true,
+    busy: false,
+    width: 0,
+    pointer: 'fine',
+};
+/**
+ * The surface an {@link OverlayLayer} hands down to the cards inside it.
+ *
+ * Published for the layer alone. A control reaches it through
+ * {@link useOverlaySurface}, which is what leaves it with real measurements
+ * when nobody wrapped it in a layer at all.
+ */
+export const OverlaySurfaceContext = createContext(UNWRAPPED_SURFACE);
+function subscribeToPointerKind(onChange) {
+    if (typeof globalThis.matchMedia !== 'function')
+        return doNothing;
+    const query = globalThis.matchMedia(COARSE_POINTER_QUERY);
+    query.addEventListener('change', onChange);
+    return () => {
+        query.removeEventListener('change', onChange);
+    };
+}
+function readPointerKind() {
+    if (typeof globalThis.matchMedia !== 'function')
+        return false;
+    return globalThis.matchMedia(COARSE_POINTER_QUERY).matches;
+}
+/**
+ * What a server render is told the pointer is.
+ *
+ * Nothing can be asked about the pointer while the markup is being written,
+ * and guessing a finger would hand the largest controls to every reader whose
+ * first paint comes from the server.
+ * @returns Always `false`.
+ */
+function readFinePointer() {
+    return false;
+}
+function doNothing() {
+    // Nothing was subscribed to, so there is nothing to unsubscribe from.
+}
+const COARSE_POINTER_QUERY = '(pointer: coarse)';
+//# sourceMappingURL=overlaySurface.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlaySurface.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlaySurface.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,OAAO,CAAC;AAMxE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAoB3D;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,UAAU,CAAC,qBAAqB,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB;IAC9B,OAAO,oBAAoB,CACzB,sBAAsB,EACtB,eAAe,EACf,eAAe,CAChB,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAmB;IACxC,OAAO,EAAE,cAAc,CAAC,aAAa,EAAE,MAAM,CAAC;IAC9C,KAAK,EAAE,IAAI;IACX,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,CAAC;IACR,OAAO,EAAE,MAAM;CAChB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAChC,aAAa,CAAiB,iBAAiB,CAAC,CAAC;AAEnD,SAAS,sBAAsB,CAAC,QAAoB;IAClD,IAAI,OAAO,UAAU,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,KAAK,GAAG,UAAU,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC;IAC1D,KAAK,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,OAAO,GAAG,EAAE;QACV,KAAK,CAAC,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe;IACtB,IAAI,OAAO,UAAU,CAAC,UAAU,KAAK,UAAU;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,UAAU,CAAC,UAAU,CAAC,oBAAoB,CAAC,CAAC,OAAO,CAAC;AAC7D,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,eAAe;IACtB,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAS,SAAS;IAChB,sEAAsE;AACxE,CAAC;AAED,MAAM,oBAAoB,GAAG,mBAAmB,CAAC"}

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

@@ -0,0 +1,70 @@
+/**
+ * The rules a switch is drawn with.
+ *
+ * A panel's booleans are the settings whose state has to be readable without
+ * touching them: `One scale for all` drawn as a grey chip answers the reader's
+ * only question about it — is it on? — with nothing at all. So on and off are
+ * said twice over, by the colour of the track and by which end the knob is at,
+ * and the target the reader aims at is kept larger than the switch they see.
+ */
+import type { CSSProperties } from 'react';
+import type { OverlayMetrics } from '../core/overlayMetrics.ts';
+/** Every measurement a switch is drawn from. */
+export interface OverlaySwitchTrack {
+    /** Width of the track, in pixels. */
+    width: number;
+    /** Height of the track, in pixels. */
+    height: number;
+    /** Side of the knob, in pixels. */
+    knob: number;
+    /** Room between the knob and the edge of the track, in pixels. */
+    inset: number;
+    /** How far the knob slides when it is turned on, in pixels. */
+    travel: number;
+}
+/**
+ * How big a switch is drawn.
+ *
+ * Three quarters of a control's height, held even so that the knob is centred
+ * on a whole pixel, and half again as wide as it is tall — thirty by eighteen
+ * at the compact size. It follows the control height rather than a constant,
+ * which is what makes it grow with everything else on a phone: a switch a
+ * finger cannot hit is a setting that cannot be changed.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The switch's measurements.
+ */
+export declare function overlaySwitchTrack(metrics: OverlayMetrics): OverlaySwitchTrack;
+/**
+ * The button a switch is, which is bigger than the switch drawn on it.
+ *
+ * The track is eighteen pixels tall and the target is the card's full control
+ * height, so the thing the reader aims at is forty pixels on a phone even
+ * though the thing they see never grows past thirty.
+ * @param metrics - The measurements the card is drawn from.
+ * @param track - The switch's measurements.
+ * @param disabled - Whether it cannot be pressed.
+ * @returns The button's rules.
+ */
+export declare function overlaySwitchStyle(metrics: OverlayMetrics, track: OverlaySwitchTrack, disabled: boolean): CSSProperties;
+/**
+ * The track a switch's knob sits in.
+ *
+ * On and off are told apart by the ground rather than by the position of the
+ * knob alone, because a fourteen-pixel dot twelve pixels to the left of where
+ * it was is not a difference anybody reads across a panel of six settings.
+ * @param track - The switch's measurements.
+ * @param checked - Whether it is on.
+ * @returns The track's rules.
+ */
+export declare function overlaySwitchTrackStyle(track: OverlaySwitchTrack, checked: boolean): CSSProperties;
+/**
+ * The knob a switch slides.
+ *
+ * It slides rather than jumping, so the reader who pressed it sees which of
+ * the two ends it went to instead of only finding the panel changed.
+ * @param track - The switch's measurements.
+ * @param checked - Whether it is on.
+ * @returns The knob's rules.
+ */
+export declare function overlaySwitchKnobStyle(track: OverlaySwitchTrack, checked: boolean): CSSProperties;
+//# sourceMappingURL=overlaySwitchStyles.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlaySwitchStyles.d.ts","sourceRoot":"","sources":["../../../src/overlay/ui/overlaySwitchStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,gDAAgD;AAChD,MAAM,WAAW,kBAAkB;IACjC,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC;IACd,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,GACtB,kBAAkB,CAMpB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,cAAc,EACvB,KAAK,EAAE,kBAAkB,EACzB,QAAQ,EAAE,OAAO,GAChB,aAAa,CAYf;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,OAAO,GACf,aAAa,CAUf;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,kBAAkB,EACzB,OAAO,EAAE,OAAO,GACf,aAAa,CAYf"}

package/lib/overlay/ui/overlaySwitchStyles.js

@@ -0,0 +1,102 @@
+/**
+ * The rules a switch is drawn with.
+ *
+ * A panel's booleans are the settings whose state has to be readable without
+ * touching them: `One scale for all` drawn as a grey chip answers the reader's
+ * only question about it — is it on? — with nothing at all. So on and off are
+ * said twice over, by the colour of the track and by which end the knob is at,
+ * and the target the reader aims at is kept larger than the switch they see.
+ */
+/**
+ * How big a switch is drawn.
+ *
+ * Three quarters of a control's height, held even so that the knob is centred
+ * on a whole pixel, and half again as wide as it is tall — thirty by eighteen
+ * at the compact size. It follows the control height rather than a constant,
+ * which is what makes it grow with everything else on a phone: a switch a
+ * finger cannot hit is a setting that cannot be changed.
+ * @param metrics - The measurements the card is drawn from.
+ * @returns The switch's measurements.
+ */
+export function overlaySwitchTrack(metrics) {
+    const height = Math.round((metrics.controlHeight * 0.75) / 2) * 2;
+    const width = Math.round((height * 5) / 3);
+    const inset = 2;
+    const knob = height - inset * 2;
+    return { width, height, knob, inset, travel: width - knob - inset * 2 };
+}
+/**
+ * The button a switch is, which is bigger than the switch drawn on it.
+ *
+ * The track is eighteen pixels tall and the target is the card's full control
+ * height, so the thing the reader aims at is forty pixels on a phone even
+ * though the thing they see never grows past thirty.
+ * @param metrics - The measurements the card is drawn from.
+ * @param track - The switch's measurements.
+ * @param disabled - Whether it cannot be pressed.
+ * @returns The button's rules.
+ */
+export function overlaySwitchStyle(metrics, track, disabled) {
+    return {
+        display: 'inline-flex',
+        alignItems: 'center',
+        minWidth: track.width,
+        height: metrics.controlHeight,
+        padding: 0,
+        border: 'none',
+        background: 'transparent',
+        cursor: disabled ? 'default' : 'pointer',
+        opacity: disabled ? 0.6 : 1,
+    };
+}
+/**
+ * The track a switch's knob sits in.
+ *
+ * On and off are told apart by the ground rather than by the position of the
+ * knob alone, because a fourteen-pixel dot twelve pixels to the left of where
+ * it was is not a difference anybody reads across a panel of six settings.
+ * @param track - The switch's measurements.
+ * @param checked - Whether it is on.
+ * @returns The track's rules.
+ */
+export function overlaySwitchTrackStyle(track, checked) {
+    return {
+        position: 'relative',
+        display: 'inline-block',
+        width: track.width,
+        height: track.height,
+        borderRadius: 999,
+        background: checked ? 'var(--accent)' : 'var(--border-strong)',
+        transition: `background ${OVERLAY_SWITCH_TRANSITION}ms ease`,
+    };
+}
+/**
+ * The knob a switch slides.
+ *
+ * It slides rather than jumping, so the reader who pressed it sees which of
+ * the two ends it went to instead of only finding the panel changed.
+ * @param track - The switch's measurements.
+ * @param checked - Whether it is on.
+ * @returns The knob's rules.
+ */
+export function overlaySwitchKnobStyle(track, checked) {
+    return {
+        position: 'absolute',
+        top: track.inset,
+        left: checked ? track.inset + track.travel : track.inset,
+        width: track.knob,
+        height: track.knob,
+        borderRadius: '50%',
+        background: 'var(--surface)',
+        boxShadow: 'var(--shadow-sm)',
+        transition: `left ${OVERLAY_SWITCH_TRANSITION}ms ease`,
+    };
+}
+/**
+ * How long the knob takes to cross.
+ *
+ * Long enough to be seen as a movement and short enough that a reader turning
+ * three settings on in a row never waits for the animation.
+ */
+const OVERLAY_SWITCH_TRANSITION = 150;
+//# sourceMappingURL=overlaySwitchStyles.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"overlaySwitchStyles.js","sourceRoot":"","sources":["../../../src/overlay/ui/overlaySwitchStyles.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC;IAClE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,CAAC,CAAC;IAChB,MAAM,IAAI,GAAG,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;IAChC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,CAAC,EAAE,CAAC;AAC1E,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAuB,EACvB,KAAyB,EACzB,QAAiB;IAEjB,OAAO;QACL,OAAO,EAAE,aAAa;QACtB,UAAU,EAAE,QAAQ;QACpB,QAAQ,EAAE,KAAK,CAAC,KAAK;QACrB,MAAM,EAAE,OAAO,CAAC,aAAa;QAC7B,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,aAAa;QACzB,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACxC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAyB,EACzB,OAAgB;IAEhB,OAAO;QACL,QAAQ,EAAE,UAAU;QACpB,OAAO,EAAE,cAAc;QACvB,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,YAAY,EAAE,GAAG;QACjB,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,sBAAsB;QAC9D,UAAU,EAAE,cAAc,yBAAyB,SAAS;KAC7D,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,KAAyB,EACzB,OAAgB;IAEhB,OAAO;QACL,QAAQ,EAAE,UAAU;QACpB,GAAG,EAAE,KAAK,CAAC,KAAK;QAChB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK;QACxD,KAAK,EAAE,KAAK,CAAC,IAAI;QACjB,MAAM,EAAE,KAAK,CAAC,IAAI;QAClB,YAAY,EAAE,KAAK;QACnB,UAAU,EAAE,gBAAgB;QAC5B,SAAS,EAAE,kBAAkB;QAC7B,UAAU,EAAE,QAAQ,yBAAyB,SAAS;KACvD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,yBAAyB,GAAG,GAAG,CAAC"}