zabi-components 8.0.0 → 8.1.0

package/dist/util/photo.js

@@ -0,0 +1,206 @@
+/**
+ * Public types and pure helpers for `PhotoGrid` and `PhotoViewer`.
+ *
+ * Everything a gesture means is worked out here, on numbers: where a pinch
+ * leaves the photo, how far it may be panned, whether a swipe turns the page.
+ * The components only feed pointers in and apply the result, so the
+ * arithmetic can be tested without a browser.
+ */
+export function photoKey(photo) {
+    return photo.id ?? photo.src;
+}
+export const PHOTO_GRID_STRINGS = {
+    addPhoto: "Add photo",
+    photoName: (position, total) => `Photo ${position} of ${total}`,
+    morePhotos: (count) => `${count} more ${count === 1 ? "photo" : "photos"}`,
+    openPhoto: (name) => `Open ${name}`,
+    keyboardHint: "Use the arrow keys to move between photos.",
+};
+export const PHOTO_VIEWER_STRINGS = {
+    close: "Close",
+    previous: "Previous photo",
+    next: "Next photo",
+    counter: (position, total) => `${position} / ${total}`,
+    position: (position, total) => `${position} of ${total}`,
+    loading: "Loading photo",
+    loadError: "The photo could not be loaded.",
+    retry: "Try again",
+    moreActions: "More actions",
+    showMore: "More",
+    showLess: "Less",
+    photoName: (position, total) => `Photo ${position} of ${total}`,
+};
+/** How many actions the viewer's bar shows before the rest go into a menu. */
+export const MAX_BAR_ACTIONS = 3;
+/** The actions shown in the bar, and those that go into the menu. */
+export function splitActions(actions, max = MAX_BAR_ACTIONS) {
+    if (actions.length <= max)
+        return { bar: [...actions], menu: [] };
+    // One place in the bar goes to the menu's own button.
+    return { bar: actions.slice(0, max - 1), menu: actions.slice(max - 1) };
+}
+/** An index held inside a list of `count` photos; -1 for an empty list. */
+export function clampIndex(index, count) {
+    if (count <= 0)
+        return -1;
+    if (!Number.isFinite(index))
+        return 0;
+    return Math.min(Math.max(Math.trunc(index), 0), count - 1);
+}
+/** What the grid shows of `total` photos under `max`, and how many the last tile stands for. */
+export function visibleCount(total, max) {
+    if (max === undefined || !Number.isFinite(max) || max < 1 || total <= max) {
+        return { shown: total, hidden: 0 };
+    }
+    const shown = Math.floor(max);
+    return { shown, hidden: total - shown };
+}
+export const REST = { scale: 1, x: 0, y: 0 };
+export const MIN_SCALE = 1;
+export const MAX_SCALE = 4;
+/** What a double tap zooms to. */
+export const DOUBLE_TAP_SCALE = 2.5;
+/** Under this a released pinch goes back to the fitted photo. */
+const SNAP_TO_FIT = 1.02;
+export const isZoomed = (transform) => transform.scale > 1.001;
+/** The largest size a photo of `photo` px takes inside `view` without being cropped. */
+export function fitSize(photo, view) {
+    if (photo.width <= 0 || photo.height <= 0 || view.width <= 0 || view.height <= 0) {
+        return { width: 0, height: 0 };
+    }
+    const ratio = Math.min(view.width / photo.width, view.height / photo.height);
+    return { width: photo.width * ratio, height: photo.height * ratio };
+}
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+/**
+ * The transform with its pan held to the photo's edges: an edge of the photo
+ * never comes further in than the edge of the screen, and a side that is
+ * narrower than the screen stays centred. `fit` is the photo's size at scale 1.
+ */
+export function clampPan(transform, fit, view) {
+    const scale = clamp(transform.scale, MIN_SCALE, MAX_SCALE);
+    const maxX = Math.max(0, (fit.width * scale - view.width) / 2);
+    const maxY = Math.max(0, (fit.height * scale - view.height) / 2);
+    // `|| 0`: a clamp to a limit of zero can leave -0, which is not what "centred" should print as.
+    return {
+        scale,
+        x: clamp(transform.x, -maxX, maxX) || 0,
+        y: clamp(transform.y, -maxY, maxY) || 0,
+    };
+}
+/**
+ * Zooms to `scale` so that the point of the photo under `point` stays under
+ * it. `point` is measured from the centre of the screen.
+ */
+export function zoomAbout(transform, scale, point, fit, view) {
+    const next = clamp(scale, MIN_SCALE, MAX_SCALE);
+    const ratio = next / transform.scale;
+    return clampPan({
+        scale: next,
+        x: point.x - (point.x - transform.x) * ratio,
+        y: point.y - (point.y - transform.y) * ratio,
+    }, fit, view);
+}
+export function pinchSample(first, second) {
+    return {
+        centre: { x: (first.x + second.x) / 2, y: (first.y + second.y) / 2 },
+        distance: Math.hypot(second.x - first.x, second.y - first.y),
+    };
+}
+/**
+ * Where a pinch has taken the photo: scaled by how much the fingers have
+ * spread, about the point that was between them when it began, and moved with
+ * that point. Points are measured from the centre of the screen.
+ */
+export function pinchTransform(start, from, now, fit, view) {
+    if (from.distance <= 0)
+        return clampPan(start, fit, view);
+    const zoomed = zoomAbout(start, start.scale * (now.distance / from.distance), from.centre, fit, view);
+    return clampPan({
+        scale: zoomed.scale,
+        x: zoomed.x + (now.centre.x - from.centre.x),
+        y: zoomed.y + (now.centre.y - from.centre.y),
+    }, fit, view);
+}
+/** A pinch let go a hair above the fitted size is the fitted size. */
+export function settleZoom(transform, fit, view) {
+    return transform.scale < SNAP_TO_FIT ? REST : clampPan(transform, fit, view);
+}
+/** A double tap: in to 2.5 times about the tap from the fitted photo, and back to fitted from any zoom. */
+export function doubleTapTransform(transform, point, fit, view) {
+    return isZoomed(transform) ? REST : zoomAbout(transform, DOUBLE_TAP_SCALE, point, fit, view);
+}
+/** The photo moved by `delta` px, held to its edges. */
+export function panBy(transform, delta, fit, view) {
+    return clampPan({ scale: transform.scale, x: transform.x + delta.x, y: transform.y + delta.y }, fit, view);
+}
+/** One step of the keyboard or the wheel: in or out by half again, about the centre. */
+export const ZOOM_STEP = 1.5;
+// ---------------------------------------------------------------------------
+// Taps and swipes
+// ---------------------------------------------------------------------------
+/** Movement under this many px is a press, not a drag. */
+export const TAP_SLOP = 8;
+/** A press shorter than this is a tap, and two taps closer together than this are a double tap. */
+export const TAP_MS = 300;
+/** Two taps further apart than this are two taps. */
+export const DOUBLE_TAP_RADIUS = 32;
+export function isDoubleTap(previous, now) {
+    if (!previous)
+        return false;
+    return (now.time - previous.time <= TAP_MS &&
+        Math.hypot(now.point.x - previous.point.x, now.point.y - previous.point.y) <= DOUBLE_TAP_RADIUS);
+}
+/**
+ * Which way a drag on the fitted photo is going, once it has gone far enough
+ * to tell: `x` turns the page, `down` closes, and null is not yet known. A
+ * drag upwards is neither, and stays null.
+ */
+export function dragAxis(delta, slop = TAP_SLOP) {
+    const horizontal = Math.abs(delta.x);
+    const vertical = Math.abs(delta.y);
+    if (Math.max(horizontal, vertical) < slop)
+        return null;
+    if (horizontal >= vertical)
+        return "x";
+    return delta.y > 0 ? "down" : null;
+}
+/** Part of the screen's width a slow swipe has to cross to turn the page. */
+export const TURN_DISTANCE = 0.25;
+/** Part of the screen's height a slow swipe down has to cross to close. */
+export const CLOSE_DISTANCE = 0.2;
+/**
+ * What a horizontal swipe does when the finger lifts. A flick decides by its
+ * direction; a slow one by how far it went. Swiping left shows the next
+ * photo, and the previous one in a right-to-left layout. At either end there
+ * is nothing to turn to.
+ */
+export function swipeTurn(options) {
+    const { distance, velocity, width, index, count, rtl = false, flick } = options;
+    let direction = 0;
+    if (Math.abs(velocity) >= flick)
+        direction = velocity < 0 ? 1 : -1;
+    else if (Math.abs(distance) >= width * TURN_DISTANCE)
+        direction = distance < 0 ? 1 : -1;
+    // A flick against the way the photo was dragged is a change of mind.
+    if (direction !== 0 && distance !== 0 && Math.sign(distance) === direction)
+        direction = 0;
+    if (rtl && direction !== 0)
+        direction = direction === 1 ? -1 : 1;
+    const target = index + direction;
+    return target < 0 || target >= count ? 0 : direction;
+}
+/** Whether a swipe down closes the viewer when the finger lifts. */
+export function swipeCloses(options) {
+    const { distance, velocity, height, flick } = options;
+    if (distance <= 0)
+        return false;
+    return velocity >= flick || (distance >= height * CLOSE_DISTANCE && velocity > -flick);
+}
+/**
+ * How far a drag past the first or last photo moves it: a third of the
+ * finger's travel, so it gives but does not come away.
+ */
+export function resist(distance) {
+    return distance / 3;
+}

package/dist/util/portal.d.ts

@@ -0,0 +1,22 @@
+import type { Action } from "svelte/action";
+/**
+ * Where to render the node: `true` for `document.body`, an element, or a
+ * selector. `false` leaves the node where the template put it.
+ */
+export type PortalTarget = boolean | HTMLElement | string;
+/**
+ * Moves an overlay out of its ancestors so none of them can trap it: a
+ * `transform`, `filter` or `contain` ancestor becomes the containing block of a
+ * `position: fixed` child, and an `overflow: hidden` one then clips it.
+ *
+ * SSR-safe by construction: actions never run on the server, so the markup is
+ * rendered in place and moved on mount. The node is removed on destroy, and
+ * Svelte's own teardown of a node that has already gone is a no-op.
+ *
+ * Put it on the single root element of an `{#if}` block. The theme is a `.dark`
+ * class on an ancestor, so a node portalled to `body` keeps it only when the
+ * class sits on `<html>` or `<body>`.
+ *
+ * Usage: `<div use:portal>` or `<div use:portal={enabled}>`.
+ */
+export declare const portal: Action<HTMLElement, PortalTarget | undefined>;

package/dist/util/portal.js

@@ -0,0 +1,50 @@
+function resolveTarget(target) {
+    if (target === false)
+        return null;
+    if (target === true)
+        return document.body;
+    if (typeof target === "string") {
+        return document.querySelector(target);
+    }
+    return target;
+}
+/**
+ * Moves an overlay out of its ancestors so none of them can trap it: a
+ * `transform`, `filter` or `contain` ancestor becomes the containing block of a
+ * `position: fixed` child, and an `overflow: hidden` one then clips it.
+ *
+ * SSR-safe by construction: actions never run on the server, so the markup is
+ * rendered in place and moved on mount. The node is removed on destroy, and
+ * Svelte's own teardown of a node that has already gone is a no-op.
+ *
+ * Put it on the single root element of an `{#if}` block. The theme is a `.dark`
+ * class on an ancestor, so a node portalled to `body` keeps it only when the
+ * class sits on `<html>` or `<body>`.
+ *
+ * Usage: `<div use:portal>` or `<div use:portal={enabled}>`.
+ */
+export const portal = (node, target = true) => {
+    const home = node.parentNode;
+    const homeNext = node.nextSibling;
+    function place(next) {
+        const destination = resolveTarget(next);
+        if (destination) {
+            if (node.parentNode !== destination)
+                destination.appendChild(node);
+        }
+        else if (next === false && home && node.parentNode !== home) {
+            // Back to where the template put it, if that place still exists.
+            home.insertBefore(node, homeNext?.parentNode === home ? homeNext : null);
+        }
+    }
+    place(target);
+    return {
+        update(next = true) {
+            place(next);
+        },
+        destroy() {
+            if (node.parentNode !== home)
+                node.remove();
+        },
+    };
+};

package/dist/util/pull-to-refresh.d.ts

@@ -0,0 +1,26 @@
+/** Public types and pure helpers for `PullToRefresh`. */
+/** The words a `PullToRefresh` says by itself. */
+export interface PullToRefreshStrings {
+    /** Shown while the list is being pulled, short of the threshold. */
+    pull: string;
+    /** Shown once letting go would refresh. */
+    release: string;
+    /** Shown, and announced, while the refresh runs. */
+    refreshing: string;
+    /** Announced when it has finished. */
+    done: string;
+    /** The button that refreshes without the gesture. */
+    refresh: string;
+}
+export declare const DEFAULT_PULL_TO_REFRESH_STRINGS: PullToRefreshStrings;
+/**
+ * How far the indicator has come out for a finger that has travelled
+ * `distance` px: half as far, so the list feels held, and never more than one
+ * and a half times the threshold.
+ */
+export declare function pullDistance(distance: number, threshold: number): number;
+/**
+ * What scrolls the element: its nearest ancestor that scrolls on the block
+ * axis, or the page.
+ */
+export declare function scrollContainerOf(element: HTMLElement): HTMLElement;

package/dist/util/pull-to-refresh.js

@@ -0,0 +1,30 @@
+/** Public types and pure helpers for `PullToRefresh`. */
+export const DEFAULT_PULL_TO_REFRESH_STRINGS = {
+    pull: "Pull to refresh",
+    release: "Release to refresh",
+    refreshing: "Refreshing",
+    done: "Updated",
+    refresh: "Refresh",
+};
+/**
+ * How far the indicator has come out for a finger that has travelled
+ * `distance` px: half as far, so the list feels held, and never more than one
+ * and a half times the threshold.
+ */
+export function pullDistance(distance, threshold) {
+    return Math.max(0, Math.min(distance / 2, threshold * 1.5));
+}
+/**
+ * What scrolls the element: its nearest ancestor that scrolls on the block
+ * axis, or the page.
+ */
+export function scrollContainerOf(element) {
+    for (let parent = element.parentElement; parent; parent = parent.parentElement) {
+        if (parent === document.body || parent === document.documentElement)
+            break;
+        const overflow = getComputedStyle(parent).overflowY;
+        if (overflow === "auto" || overflow === "scroll" || overflow === "overlay")
+            return parent;
+    }
+    return document.scrollingElement ?? document.documentElement;
+}

package/dist/util/radio-keys.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Where a key moves the selection in a radio group laid out in a row, as
+ * Rating and SegmentedControl are. Kept out of the components so it can be
+ * tested without a DOM.
+ *
+ * It is the native radio contract: Right and Down go to the next option, Left
+ * and Up to the previous one, both wrap, and Left and Right swap in a
+ * right-to-left layout.
+ *
+ * `current` is the option that has focus, which is not always the selected
+ * one: a screen reader's cursor can put focus on any radio, and the keys then
+ * move from where the user is. It is -1 when focus is on none of them: the
+ * next option is then the first, and the previous one the last.
+ *
+ * `hasSelection` is false while the group is empty. A forward key then selects
+ * the focused option itself instead of stepping over it, so Right on an empty
+ * rating gives one star, not two.
+ *
+ * Returns -1 for a key that is not a navigation key, or when there is nothing
+ * to move to.
+ */
+export declare function radioKeyIndex(key: string, current: number, count: number, rtl?: boolean, hasSelection?: boolean): number;
+/** Whether `node` is laid out right to left. */
+export declare function isRtl(node: Element): boolean;

package/dist/util/radio-keys.js

@@ -0,0 +1,49 @@
+/**
+ * Where a key moves the selection in a radio group laid out in a row, as
+ * Rating and SegmentedControl are. Kept out of the components so it can be
+ * tested without a DOM.
+ *
+ * It is the native radio contract: Right and Down go to the next option, Left
+ * and Up to the previous one, both wrap, and Left and Right swap in a
+ * right-to-left layout.
+ *
+ * `current` is the option that has focus, which is not always the selected
+ * one: a screen reader's cursor can put focus on any radio, and the keys then
+ * move from where the user is. It is -1 when focus is on none of them: the
+ * next option is then the first, and the previous one the last.
+ *
+ * `hasSelection` is false while the group is empty. A forward key then selects
+ * the focused option itself instead of stepping over it, so Right on an empty
+ * rating gives one star, not two.
+ *
+ * Returns -1 for a key that is not a navigation key, or when there is nothing
+ * to move to.
+ */
+export function radioKeyIndex(key, current, count, rtl = false, hasSelection = true) {
+    if (count <= 0)
+        return -1;
+    if (key === "Home")
+        return 0;
+    if (key === "End")
+        return count - 1;
+    let delta = 0;
+    if (key === "ArrowDown")
+        delta = 1;
+    else if (key === "ArrowUp")
+        delta = -1;
+    else if (key === "ArrowRight")
+        delta = rtl ? -1 : 1;
+    else if (key === "ArrowLeft")
+        delta = rtl ? 1 : -1;
+    if (delta === 0)
+        return -1;
+    if (current < 0 || current >= count)
+        return delta > 0 ? 0 : count - 1;
+    if (!hasSelection && delta > 0)
+        return current;
+    return (current + delta + count) % count;
+}
+/** Whether `node` is laid out right to left. */
+export function isRtl(node) {
+    return getComputedStyle(node).direction === "rtl";
+}

package/dist/util/rating.d.ts

@@ -0,0 +1,22 @@
+/** Types and pure helpers for `Rating`. Kept out of the component so they can be tested without a DOM. */
+/** Every built-in string. Pass a partial object to `strings` to translate. */
+export interface RatingStrings {
+    /**
+     * Accessible name of one star ("4 of 5 stars"), and of a read-only
+     * rating as a whole ("3.5 of 5 stars"). `value` is already formatted.
+     */
+    starLabel: (value: string, max: number) => string;
+    /** Accessible name of the clear button that `clearable` adds. */
+    clearLabel: string;
+    /** Shown, and read, for a read-only rating without a value. */
+    noRating: string;
+}
+export declare const RATING_STRINGS: RatingStrings;
+/** Number of stars: a whole number, at least one. */
+export declare function starCount(max: number): number;
+/** `value` held within 0..max; `null` for no rating or a value that is not a number. */
+export declare function clampRating(value: number | null | undefined, max: number): number | null;
+/** How much of star `star` (counted from 1) is filled, 0 to 1. */
+export declare function starFill(value: number | null, star: number): number;
+/** The value with at most one decimal: 4, 3.5, 3.7. */
+export declare function defaultRatingFormat(value: number): string;

package/dist/util/rating.js

@@ -0,0 +1,26 @@
+/** Types and pure helpers for `Rating`. Kept out of the component so they can be tested without a DOM. */
+export const RATING_STRINGS = {
+    starLabel: (value, max) => `${value} of ${max} stars`,
+    clearLabel: "Clear rating",
+    noRating: "No rating",
+};
+/** Number of stars: a whole number, at least one. */
+export function starCount(max) {
+    return Number.isFinite(max) ? Math.max(1, Math.floor(max)) : 5;
+}
+/** `value` held within 0..max; `null` for no rating or a value that is not a number. */
+export function clampRating(value, max) {
+    if (value === null || value === undefined || !Number.isFinite(value))
+        return null;
+    return Math.max(0, Math.min(max, value));
+}
+/** How much of star `star` (counted from 1) is filled, 0 to 1. */
+export function starFill(value, star) {
+    if (value === null)
+        return 0;
+    return Math.max(0, Math.min(1, value - (star - 1)));
+}
+/** The value with at most one decimal: 4, 3.5, 3.7. */
+export function defaultRatingFormat(value) {
+    return String(Math.round(value * 10) / 10);
+}

package/dist/util/ready-made-strings.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The words of the components that come with text of their own: the colour
+ * picker, the ready-made contact form, and the two the docs site is built
+ * from. Each takes its own as `strings`; what is left out stays as it is here.
+ */
+/** `ColorPicker`. */
+export interface ColorPickerStrings {
+    /** Accessible name of the field the hex value is typed in. */
+    hexInput: string;
+    /** Accessible name of the swatch button that opens the picker. */
+    open: string;
+    /** Accessible name of the picker that opens. */
+    picker: string;
+    /** Accessible name of the hue slider in it. */
+    hue: string;
+    /** Accessible name of the colour map: the two sliders below, on one surface. */
+    area: string;
+    /** Accessible name of the map's slider that goes across. */
+    saturation: string;
+    /** Accessible name of the map's slider that goes up and down. */
+    lightness: string;
+    /** The message under the field while what is typed is not a hex colour. */
+    invalidHex: string;
+}
+export declare const DEFAULT_COLOR_PICKER_STRINGS: ColorPickerStrings;
+/** `ContactForm`: every label, placeholder and message of the form. */
+export interface ContactFormStrings {
+    heading: string;
+    nameLabel: string;
+    namePlaceholder: string;
+    emailLabel: string;
+    emailPlaceholder: string;
+    messageLabel: string;
+    messagePlaceholder: string;
+    subscribeLabel: string;
+    submit: string;
+    /** Under a field left empty or filled in wrongly. */
+    nameRequired: string;
+    emailRequired: string;
+    emailInvalid: string;
+    messageRequired: string;
+    /** The box above the fields when the form could not be sent: its three lines. */
+    errorTitle: string;
+    errorMessage: string;
+    errorRecovery: string;
+}
+export declare const DEFAULT_CONTACT_FORM_STRINGS: ContactFormStrings;
+/** `PropsTable`. The caption is the `caption` prop. */
+export interface PropsTableStrings {
+    name: string;
+    type: string;
+    required: string;
+    default: string;
+    description: string;
+    yes: string;
+    no: string;
+    /** Shown instead of the table when there are no props. */
+    empty: string;
+}
+export declare const DEFAULT_PROPS_TABLE_STRINGS: PropsTableStrings;
+/** `ComponentDemo`. */
+export interface ComponentDemoStrings {
+    /** The two tabs, and what the switch between them is called. */
+    preview: string;
+    code: string;
+    showPreview: string;
+    showCode: string;
+}
+export declare const DEFAULT_COMPONENT_DEMO_STRINGS: ComponentDemoStrings;
+/**
+ * Lays `strings` layers over a component's defaults, later layers winning. A
+ * key whose value is `undefined` is skipped, so `strings={{ close: t.close }}`
+ * with `t.close` missing keeps the default instead of blanking it. `null` and
+ * the empty string are kept: those are choices.
+ */
+export declare function mergeStrings<T extends object>(defaults: T, ...layers: Array<Partial<T> | null | undefined>): T;

package/dist/util/ready-made-strings.js

@@ -0,0 +1,67 @@
+/**
+ * The words of the components that come with text of their own: the colour
+ * picker, the ready-made contact form, and the two the docs site is built
+ * from. Each takes its own as `strings`; what is left out stays as it is here.
+ */
+export const DEFAULT_COLOR_PICKER_STRINGS = {
+    hexInput: "Hex color input",
+    open: "Open color picker",
+    picker: "Color picker",
+    hue: "Hue slider",
+    area: "Saturation and lightness",
+    saturation: "Saturation",
+    lightness: "Lightness",
+    invalidHex: "Please enter a valid hex color (e.g., #ff0000 or #f00)",
+};
+export const DEFAULT_CONTACT_FORM_STRINGS = {
+    heading: "Get in Touch",
+    nameLabel: "Name",
+    namePlaceholder: "Enter your name",
+    emailLabel: "Email",
+    emailPlaceholder: "Enter your email",
+    messageLabel: "Message",
+    messagePlaceholder: "Enter your message",
+    subscribeLabel: "Subscribe to updates",
+    submit: "Send Message",
+    nameRequired: "Please enter your name.",
+    emailRequired: "Please enter your email address.",
+    emailInvalid: "Please enter a valid email address.",
+    messageRequired: "Please enter a message.",
+    errorTitle: "Something went wrong",
+    errorMessage: "We could not submit your request. Fix the highlighted fields and try again.",
+    errorRecovery: "Recovery action: review your inputs and resubmit.",
+};
+export const DEFAULT_PROPS_TABLE_STRINGS = {
+    name: "Name",
+    type: "Type",
+    required: "Required",
+    default: "Default",
+    description: "Description",
+    yes: "Yes",
+    no: "No",
+    empty: "No documented props.",
+};
+export const DEFAULT_COMPONENT_DEMO_STRINGS = {
+    preview: "Preview",
+    code: "Code",
+    showPreview: "Show preview",
+    showCode: "Show code",
+};
+/**
+ * Lays `strings` layers over a component's defaults, later layers winning. A
+ * key whose value is `undefined` is skipped, so `strings={{ close: t.close }}`
+ * with `t.close` missing keeps the default instead of blanking it. `null` and
+ * the empty string are kept: those are choices.
+ */
+export function mergeStrings(defaults, ...layers) {
+    const merged = { ...defaults };
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        for (const [key, value] of Object.entries(layer)) {
+            if (value !== undefined)
+                merged[key] = value;
+        }
+    }
+    return merged;
+}

package/dist/util/scroll-padding.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `scroll-padding-bottom` on a scrolling box, shared between the things that
+ * lie over its bottom edge.
+ *
+ * Each of them saves what was there and puts it back when it leaves. Done one
+ * by one that goes wrong as soon as two overlap in time: the second saves the
+ * first one's value as "what was there", and if the first leaves first, the
+ * second later restores a value nobody owns any more. Here the box's own
+ * value is saved once, the largest request is what is set, and the box gets
+ * its own value back when the last request is released.
+ */
+/**
+ * Asks for room at the bottom of `container`. `set` gives or changes the
+ * amount in px; `release` withdraws the request. Call it in the browser.
+ */
+export declare function reserveScrollPaddingBottom(container: HTMLElement): {
+    set: (px: number) => void;
+    release: () => void;
+};

package/dist/util/scroll-padding.js

@@ -0,0 +1,44 @@
+/**
+ * `scroll-padding-bottom` on a scrolling box, shared between the things that
+ * lie over its bottom edge.
+ *
+ * Each of them saves what was there and puts it back when it leaves. Done one
+ * by one that goes wrong as soon as two overlap in time: the second saves the
+ * first one's value as "what was there", and if the first leaves first, the
+ * second later restores a value nobody owns any more. Here the box's own
+ * value is saved once, the largest request is what is set, and the box gets
+ * its own value back when the last request is released.
+ */
+const reservations = new WeakMap();
+function apply(container, reservation) {
+    const largest = Math.max(0, ...reservation.requests.values());
+    container.style.scrollPaddingBottom = `${largest}px`;
+}
+/**
+ * Asks for room at the bottom of `container`. `set` gives or changes the
+ * amount in px; `release` withdraws the request. Call it in the browser.
+ */
+export function reserveScrollPaddingBottom(container) {
+    const key = Symbol("scroll-padding");
+    let reservation = reservations.get(container);
+    if (!reservation) {
+        reservation = { original: container.style.scrollPaddingBottom, requests: new Map() };
+        reservations.set(container, reservation);
+    }
+    const mine = reservation;
+    return {
+        set(px) {
+            mine.requests.set(key, px);
+            apply(container, mine);
+        },
+        release() {
+            mine.requests.delete(key);
+            if (mine.requests.size > 0) {
+                apply(container, mine);
+                return;
+            }
+            container.style.scrollPaddingBottom = mine.original;
+            reservations.delete(container);
+        },
+    };
+}