@tristan2828/ui-foundation 4.27.0 → 4.29.0

package/dist/error-reporting/reporter.d.ts

@@ -3,6 +3,11 @@ import type { ClientErrorReport } from "../api/gateway/client-errors.js";
 export type ErrorReportingOptions = {
     /** The frontend build a report names, e.g. the commit (`import.meta.env.VITE_RELEASE`). */
     release?: string;
+    /**
+     * Return true to drop a report: a known noise pattern the package doesn't
+     * filter yet. Sees every report, from every source, before it's sent.
+     */
+    ignore?: (report: ClientErrorReport) => boolean;
 };
 export type ReportSource = ClientErrorReport["source"];
 /** FoundationProviders' prop, as options, or null when reporting is off. */
@@ -10,6 +15,16 @@ export declare function resolveErrorReporting(option: boolean | ErrorReportingOp
 export declare function scrub(text: string, limit: number): string;
 /** `/widgets/7/edit` with `{ id: '7' }` → `/widgets/:id/edit`; a splat → `*`. */
 export declare function routePattern(pathname: string, params: Readonly<Record<string, string | undefined>>): string;
+/**
+ * Whether an uncaught error can't be the app's (#205): `Script error.` with
+ * nothing else, or every frame of its stack (else the event's file) outside
+ * the app's scripts. An error with no location at all is kept: a thrown
+ * string may well be the app's.
+ */
+export declare function fromOutsideApp(error: unknown, event: {
+    message?: string;
+    filename?: string;
+}, page: string): boolean;
 export type ErrorReporter = {
     /** Reports `error` from `source`, unless it's a duplicate or signed out. */
     report: (source: ReportSource, error: unknown, request?: {
@@ -23,8 +38,12 @@ export type ErrorReporter = {
     /** Listens on the window and the query client; returns the undo. */
     install: (queryClient: QueryClient, target: Pick<EventTarget, "addEventListener" | "removeEventListener">) => () => void;
 };
-export declare function createErrorReporter({ options, send, now, }: {
+export declare function createErrorReporter({ options, send, now, page, muted, }: {
     options: ErrorReportingOptions;
     send: (report: ClientErrorReport) => void;
     now?: () => number;
+    /** The page's address, which an injected script's frames carry. */
+    page?: () => string;
+    /** True while nothing should be reported: the page reloading onto a new build. */
+    muted?: () => boolean;
 }): ErrorReporter;

package/dist/error-reporting/reporter.js

@@ -51,12 +51,59 @@ function describe(error) {
         return { type: "ServerError", message: error.message };
     return { type: "Error", message: typeof error === "string" ? error : "A value that isn't an Error was thrown." };
 }
-export function createErrorReporter({ options, send, now = Date.now, }) {
+const EXTENSION_SCHEMES = /^(chrome-extension|moz-extension|safari-extension|safari-web-extension|ms-browser-extension):/i;
+const SCRIPT_FILE = /\.(?:[cm]?js|jsx|[cm]?ts|tsx)$/i;
+// A stack frame's location at the end of its line: `at f (url:1:2)`,
+// `at url:1:2`, `f@url:1:2`, `global code@url:1:2`.
+const FRAME_URL = /([a-z][a-z0-9+.-]*:\/\/[^\s()]+?):\d+(?::\d+)?\)?\s*$/i;
+function stackUrls(stack) {
+    if (!stack)
+        return [];
+    return stack.split("\n").flatMap((line) => {
+        const match = FRAME_URL.exec(line.trim());
+        return match ? [match[1]] : [];
+    });
+}
+/**
+ * Whether `url` is somewhere the app's own code can't be: an extension, or
+ * an address on the page's origin that isn't a script file (a page, as
+ * `/timers/2`, where only an injected or inline script runs).
+ */
+function outsideAppScripts(url, page) {
+    if (EXTENSION_SCHEMES.test(url))
+        return true;
+    let parsed;
+    let origin;
+    try {
+        parsed = new URL(url);
+        origin = new URL(page).origin;
+    }
+    catch {
+        return false;
+    }
+    return parsed.origin === origin && !SCRIPT_FILE.test(parsed.pathname);
+}
+/**
+ * Whether an uncaught error can't be the app's (#205): `Script error.` with
+ * nothing else, or every frame of its stack (else the event's file) outside
+ * the app's scripts. An error with no location at all is kept: a thrown
+ * string may well be the app's.
+ */
+export function fromOutsideApp(error, event, page) {
+    const stack = error instanceof Error ? error.stack : undefined;
+    if (!stack && error == null && /^Script error\.?$/.test(event.message ?? ""))
+        return true;
+    const urls = stackUrls(stack);
+    if (urls.length === 0 && event.filename)
+        urls.push(event.filename);
+    return urls.length > 0 && urls.every((url) => outsideAppScripts(url, page));
+}
+export function createErrorReporter({ options, send, now = Date.now, page = () => globalThis.location?.href ?? "", muted = () => false, }) {
     const lastSent = new Map();
     let route = null;
     let signedIn = false;
     const report = (source, error, request = {}) => {
-        if (!signedIn)
+        if (!signedIn || muted())
             return;
         const described = describe(error);
         const message = scrub(described.message, MAX_MESSAGE);
@@ -67,8 +114,7 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
                 lastSent.delete(key);
         if (lastSent.has(signature))
             return;
-        lastSent.set(signature, at);
-        send({
+        const sent = {
             source,
             type: described.type.slice(0, 200),
             message,
@@ -77,7 +123,11 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
             ...(request.method ? { method: request.method } : {}),
             ...(request.status ? { status: request.status } : {}),
             ...(options.release ? { release: options.release.slice(0, 100) } : {}),
-        });
+        };
+        if (options.ignore?.(sent))
+            return;
+        lastSent.set(signature, at);
+        send(sent);
     };
     const reportAppError = (source, error, method) => {
         if (!isAppError(error) || !REPORTED_KINDS.has(error.kind))
@@ -94,7 +144,9 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
         },
         install: (queryClient, target) => {
             const onError = (event) => {
-                const { error, message } = event;
+                const { error, message, filename } = event;
+                if (fromOutsideApp(error, { message, filename }, page()))
+                    return;
                 report("window", error ?? message);
             };
             const onRejection = (event) => {
@@ -103,6 +155,8 @@ export function createErrorReporter({ options, send, now = Date.now, }) {
                 // ones that are bugs, and the rest are expected.
                 if (isAppError(reason))
                     return;
+                if (fromOutsideApp(reason, {}, page()))
+                    return;
                 report("unhandledrejection", reason);
             };
             target.addEventListener("error", onError);

package/dist/hooks/use-session-clock.d.ts

@@ -8,7 +8,14 @@ export type SessionClockState = {
     paused: boolean;
 };
 export type SessionClockStore = {
-    start: () => void;
+    /** Starts counting from `from` milliseconds (default 0), from any state. */
+    start: (from?: number) => void;
+    /**
+     * Moves a running clock to `elapsed` milliseconds, paused or not, without
+     * changing either; at or past `endsAt` it's `done`. Ignored while idle or
+     * done: `start(from)` begins again from a time.
+     */
+    seek: (elapsed: number) => void;
     pause: () => void;
     resume: () => void;
     /** Back to `idle` at zero. */
@@ -32,11 +39,19 @@ export type SessionClockOptions = {
     /** The elapsed milliseconds at which the session is `done`. Without it, it runs until stopped. */
     endsAt?: number;
 };
-export type SessionClock = SessionClockState & Pick<SessionClockStore, 'start' | 'pause' | 'resume' | 'stop'>;
+export type SessionClock = SessionClockState & Pick<SessionClockStore, 'seek' | 'pause' | 'resume' | 'stop'> & {
+    /** Starts counting from zero, from any state (a click handler as is). */
+    start: () => void;
+    /** Starts counting from `elapsed` milliseconds: a run resumed from storage. */
+    startFrom: (elapsed: number) => void;
+};
 /**
  * A drift-free clock with pause and resume, read from `performance.now()`
  * each animation frame. It re-renders once per frame only while counting.
- * A hidden tab draws no frames, but its time still counts: the first frame
- * back catches up (and reaches `done` if it's due).
+ * A hidden tab draws no frames, but its time still counts: while hidden it
+ * re-renders on a slow tick (once a second at most, for a countdown in the
+ * tab's title), and coming back catches up exactly (and reaches `done` if
+ * it's due). `startFrom(ms)` and `seek(ms)` begin from, and move to, a
+ * given elapsed time.
  */
 export declare function useSessionClock({ running, endsAt }?: SessionClockOptions): SessionClock;

package/dist/hooks/use-session-clock.js

@@ -21,6 +21,7 @@ export function createSessionClock(now) {
         if (counting() && since === null)
             since = now();
     };
+    const clamp = (ms) => Math.min(Math.max(Number.isFinite(ms) ? ms : 0, 0), endsAt ?? Infinity);
     const update = () => {
         let elapsed = banked + (since === null ? 0 : now() - since);
         if (status === 'running' && endsAt !== undefined && elapsed >= endsAt) {
@@ -37,10 +38,18 @@ export function createSessionClock(now) {
             listener();
     };
     return {
-        start() {
+        start(from = 0) {
             status = 'running';
             paused = false;
-            banked = 0;
+            banked = clamp(from);
+            since = null;
+            begin();
+            update();
+        },
+        seek(elapsed) {
+            if (status !== 'running')
+                return;
+            banked = clamp(elapsed);
             since = null;
             begin();
             update();
@@ -86,11 +95,17 @@ export function createSessionClock(now) {
         getSnapshot: () => snapshot,
     };
 }
+// How often a hidden tab reads the time. Browsers slow a background tab's
+// timers (Chrome to once a minute after a while), so this is at most.
+const HIDDEN_TICK_MS = 1000;
 /**
  * A drift-free clock with pause and resume, read from `performance.now()`
  * each animation frame. It re-renders once per frame only while counting.
- * A hidden tab draws no frames, but its time still counts: the first frame
- * back catches up (and reaches `done` if it's due).
+ * A hidden tab draws no frames, but its time still counts: while hidden it
+ * re-renders on a slow tick (once a second at most, for a countdown in the
+ * tab's title), and coming back catches up exactly (and reaches `done` if
+ * it's due). `startFrom(ms)` and `seek(ms)` begin from, and move to, a
+ * given elapsed time.
  */
 export function useSessionClock({ running = true, endsAt } = {}) {
     const [clock] = useState(() => createSessionClock(() => performance.now()));
@@ -105,7 +120,21 @@ export function useSessionClock({ running = true, endsAt } = {}) {
             clock.tick();
             frame = requestAnimationFrame(next);
         });
-        return () => cancelAnimationFrame(frame);
+        let hiddenTick;
+        const onVisibility = () => {
+            clearInterval(hiddenTick);
+            hiddenTick = document.hidden ? setInterval(clock.tick, HIDDEN_TICK_MS) : undefined;
+            clock.tick();
+        };
+        if (document.hidden)
+            hiddenTick = setInterval(clock.tick, HIDDEN_TICK_MS);
+        document.addEventListener('visibilitychange', onVisibility);
+        return () => {
+            cancelAnimationFrame(frame);
+            clearInterval(hiddenTick);
+            document.removeEventListener('visibilitychange', onVisibility);
+        };
     }, [clock, counting]);
-    return { ...state, start: clock.start, pause: clock.pause, resume: clock.resume, stop: clock.stop };
+    const [start] = useState(() => () => clock.start());
+    return { ...state, start, startFrom: clock.start, seek: clock.seek, pause: clock.pause, resume: clock.resume, stop: clock.stop };
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { AppShell, type AppShellProps, type AppShellVersion, type NavEntry, type NavItem, type NavSection } from './components/app/app-shell.js';
+export type { IconComponent } from './components/app/icon-component.js';
 export { CountLink, type CountLinkProps } from './components/app/count-link.js';
 export { DataTable, type DataTableProps, type DataTableWidth, type SortingState } from './components/app/data-table.js';
 export { type RowGroup } from './components/app/table-groups.js';
@@ -31,6 +32,8 @@ export { ProgressRing, type ProgressRingProps } from './components/app/progress-
 export { StepBar, type StepBarProps } from './components/app/step-bar.js';
 export { RatingStar, type RatingStarProps, type RatingStarValue } from './components/app/rating-star.js';
 export { DateField, type DateFieldProps } from './components/app/date-field.js';
+export { ImageField, type ImageFieldProps } from './components/app/image-field.js';
+export { DEFAULT_IMAGE_TYPES, type ImageUpload, type ImageUploadResult } from './lib/image-file.js';
 export { formatPlainDate, type PlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, type ChoiceCellProps, type LinkCellProps, type NameCellProps, } from './components/app/row-edit-cells.js';
 export { WidgetCard, WidgetList, WidgetListItem, type WidgetCardProps, type WidgetListItemProps, } from './components/app/widget-card.js';
@@ -55,4 +58,4 @@ export { usePrefersReducedMotion } from './hooks/use-prefers-reduced-motion.js';
 export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, type PushController, type PushControllerOptions, type PushEnvironment, type PushPermission, type PushStatus, } from './hooks/use-push-permission.js';
 export { cn } from './lib/utils.js';
-export { canVibrate, chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';
+export { canVibrate, cancelCues, chime, hush, say, sequence, unlockAudio, vibrate, type ChimeOptions, type Cue, type CueTime, type SayOptions, type SequenceOptions, } from './lib/audio-cues.js';

package/dist/index.js

@@ -36,6 +36,8 @@ export { ProgressRing } from './components/app/progress-ring.js';
 export { StepBar } from './components/app/step-bar.js';
 export { RatingStar } from './components/app/rating-star.js';
 export { DateField } from './components/app/date-field.js';
+export { ImageField } from './components/app/image-field.js';
+export { DEFAULT_IMAGE_TYPES } from './lib/image-file.js';
 export { formatPlainDate } from './lib/plain-date.js';
 export { ChoiceCell, LinkCell, NameCell, } from './components/app/row-edit-cells.js';
 export { WidgetCard, WidgetList, WidgetListItem, } from './components/app/widget-card.js';
@@ -61,4 +63,4 @@ export { useMuted } from './hooks/use-muted.js';
 export { createPushController, usePushPermission, } from './hooks/use-push-permission.js';
 // Utilities
 export { cn } from './lib/utils.js';
-export { canVibrate, chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';
+export { canVibrate, cancelCues, chime, hush, say, sequence, unlockAudio, vibrate, } from './lib/audio-cues.js';

package/dist/lib/audio-cues.d.ts

@@ -6,10 +6,23 @@ export type ChimeOptions = {
     /** Milliseconds from strike to silence (default 1200). */
     duration?: number;
 };
-export type SequenceOptions = {
+export type CueTime = {
+    /**
+     * When to strike, in `Date.now()` milliseconds, booked on the audio
+     * clock so it's on time in a background tab. Left out, or already past,
+     * it strikes now.
+     */
+    at?: number;
+};
+export type SequenceOptions = CueTime & {
     /** Milliseconds between one chime's strike and the next's (default 180). */
     spacing?: number;
 };
+/** A chime or sequence as booked. */
+export type Cue = {
+    /** Takes back its strikes that haven't sounded yet; one already sounding rings out. */
+    cancel: () => void;
+};
 export type SayOptions = {
     /** A BCP 47 tag; the browser's default voice when left out. */
     lang?: string;
@@ -23,13 +36,17 @@ export type AudioCuesEnvironment = {
     speechSynthesis?: Pick<SpeechSynthesis, 'speak' | 'cancel'>;
     SpeechSynthesisUtterance?: new (text?: string) => SpeechSynthesisUtterance;
     vibrate?: (pattern: number | number[]) => boolean;
+    /** The clock `at` is read on (default `Date.now`). */
+    now?: () => number;
 };
 export type AudioCues = {
     /** Call from the click or tap that starts a session; sound is allowed from then on. */
     unlockAudio: () => void;
-    chime: (options?: ChimeOptions) => void;
-    /** Several chimes in a row (a closing pair), `spacing` apart. */
-    sequence: (chimes: ChimeOptions[], options?: SequenceOptions) => void;
+    chime: (options?: ChimeOptions & CueTime) => Cue;
+    /** Several chimes in a row (a closing pair), `spacing` apart, from `at`. */
+    sequence: (chimes: ChimeOptions[], options?: SequenceOptions) => Cue;
+    /** Takes back every booked strike that hasn't sounded yet. */
+    cancelCues: () => void;
     /** Speaks `text`, cutting off any line still being spoken. */
     say: (text: string, options?: SayOptions) => void;
     /** Stops whatever is being spoken. */
@@ -47,10 +64,15 @@ export declare function createAudioCues(env: AudioCuesEnvironment): AudioCues;
 export declare function canVibrate(): boolean;
 /** Call from the click or tap that starts a session; sound is allowed from then on. */
 export declare const unlockAudio: AudioCues['unlockAudio'];
-/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+/**
+ * A soft sine chime, now or booked `at` a `Date.now()` time; dropped before
+ * unlockAudio() or where there's no Web Audio.
+ */
 export declare const chime: AudioCues['chime'];
-/** Several chimes `spacing` ms apart (a closing pair). */
+/** Several chimes `spacing` ms apart (a closing pair), now or from `at`. */
 export declare const sequence: AudioCues['sequence'];
+/** Takes back every booked chime that hasn't sounded yet: on pause, skip, back or leaving. */
+export declare const cancelCues: AudioCues['cancelCues'];
 /** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
 export declare const say: AudioCues['say'];
 /** Stops whatever is being spoken. */

package/dist/lib/audio-cues.js

@@ -8,20 +8,30 @@
 // here is a no-op where the browser can't make the sound
 // (docs/foundation/timed-screens.md "Sound").
 //
+// A chime can be booked ahead (`at`, #193): it's scheduled on the Web
+// Audio clock, so it strikes on time in a background tab, whose timers
+// and frames the browser slows or stops. cancelCues() takes back every
+// booked strike that hasn't sounded yet (on pause, skip or leaving), so a
+// screen rebooks from its new position.
+//
 // createAudioCues takes the browser's APIs, so the rules are unit tested
 // against fakes (tests/audio-cues.test.ts); the functions exported below
 // are one shared instance over the real ones.
 const ATTACK = 0.015;
 // An exponential ramp can't reach zero, so a chime starts and ends here.
 const SILENT = 0.0001;
+const NO_CUE = { cancel: () => { } };
 export function createAudioCues(env) {
+    const now = env.now ?? Date.now;
     let context = null;
+    // Strikes booked and not yet over, so a cancel can reach them.
+    const booked = new Set();
     // A resume asked for from a click: the context is still "suspended" for
     // a moment, and a chime from that same click should still play.
     let resuming = false;
     const playable = () => context !== null && (context.state === 'running' || resuming);
     const strike = (ctx, { pitch = 660, volume = 0.25, duration = 1200 }, delay) => {
-        const start = ctx.currentTime + delay / 1000;
+        const start = ctx.currentTime + Math.max(delay, 0) / 1000;
         const end = start + Math.max(duration, 50) / 1000;
         const peak = Math.min(Math.max(volume, SILENT), 1);
         const oscillator = ctx.createOscillator();
@@ -34,7 +44,33 @@ export function createAudioCues(env) {
         oscillator.connect(gain).connect(ctx.destination);
         oscillator.start(start);
         oscillator.stop(end + 0.05);
+        const booking = { start, end, oscillator, gain };
+        for (const old of booked)
+            if (old.end < ctx.currentTime)
+                booked.delete(old);
+        booked.add(booking);
+        oscillator.onended = () => booked.delete(booking);
+        return booking;
+    };
+    // Silences a strike that hasn't sounded yet: one already sounding rings out.
+    const unbook = (ctx, booking) => {
+        if (!booked.has(booking))
+            return;
+        if (booking.start <= ctx.currentTime)
+            return;
+        booked.delete(booking);
+        try {
+            booking.gain.disconnect();
+            booking.oscillator.stop();
+        }
+        catch {
+            // Already stopped.
+        }
     };
+    const book = (ctx, strikes) => ({
+        cancel: () => strikes.forEach((booking) => unbook(ctx, booking)),
+    });
+    const delayUntil = (at) => (at === undefined ? 0 : at - now());
     return {
         unlockAudio() {
             if (env.AudioContext) {
@@ -62,16 +98,24 @@ export function createAudioCues(env) {
                 }
             }
         },
-        chime(options = {}) {
+        chime({ at, ...options } = {}) {
             if (!playable() || !context)
-                return;
-            strike(context, options, 0);
+                return NO_CUE;
+            return book(context, [strike(context, options, delayUntil(at))]);
         },
-        sequence(chimes, { spacing = 180 } = {}) {
+        sequence(chimes, { spacing = 180, at } = {}) {
             if (!playable() || !context)
+                return NO_CUE;
+            const ctx = context;
+            const delay = Math.max(delayUntil(at), 0);
+            return book(ctx, chimes.map((options, index) => strike(ctx, options, delay + index * spacing)));
+        },
+        cancelCues() {
+            if (!context)
                 return;
             const ctx = context;
-            chimes.forEach((options, index) => strike(ctx, options, index * spacing));
+            for (const booking of [...booked])
+                unbook(ctx, booking);
         },
         say(text, { lang, rate, volume } = {}) {
             if (!env.speechSynthesis || !env.SpeechSynthesisUtterance)
@@ -133,10 +177,15 @@ function browserCues() {
 }
 /** Call from the click or tap that starts a session; sound is allowed from then on. */
 export const unlockAudio = () => browserCues().unlockAudio();
-/** A soft sine chime; dropped before unlockAudio() or where there's no Web Audio. */
+/**
+ * A soft sine chime, now or booked `at` a `Date.now()` time; dropped before
+ * unlockAudio() or where there's no Web Audio.
+ */
 export const chime = (options) => browserCues().chime(options);
-/** Several chimes `spacing` ms apart (a closing pair). */
+/** Several chimes `spacing` ms apart (a closing pair), now or from `at`. */
 export const sequence = (chimes, options) => browserCues().sequence(chimes, options);
+/** Takes back every booked chime that hasn't sounded yet: on pause, skip, back or leaving. */
+export const cancelCues = () => browserCues().cancelCues();
 /** Speaks a line, cutting off the one before. A no-op without speech synthesis. */
 export const say = (text, options) => browserCues().say(text, options);
 /** Stops whatever is being spoken. */

package/dist/lib/image-file.d.ts

@@ -0,0 +1,37 @@
+/** What an app's upload resolves to: the stored file's id and its addresses. */
+export type ImageUploadResult = {
+    /** The stored file's id, what the record keeps (ImageField's value). */
+    id: string;
+    /** A small version for a thumbnail (ImageField shows it). */
+    thumbUrl: string;
+    /**
+     * The full-size image, for text (`![](url)` in the rich-text editor).
+     * Without it the editor inserts `thumbUrl`.
+     */
+    url?: string;
+};
+/**
+ * The app's upload: sends one file to its own storage and resolves to
+ * where it is, or rejects (an `AppError`, an `Error`: its `message` is
+ * shown).
+ */
+export type ImageUpload = (file: File) => Promise<ImageUploadResult>;
+/** The image types accepted unless a field says otherwise. */
+export declare const DEFAULT_IMAGE_TYPES: readonly string[];
+export type ImageFileRules = {
+    /** MIME types, `image/jpeg`; `image/*` for any image. Defaults to `DEFAULT_IMAGE_TYPES`. */
+    accept?: readonly string[];
+    /** The largest file accepted, in bytes. No limit when unset. */
+    maxSize?: number;
+};
+/** A size as a person reads it: "820 KB", "4.2 MB". */
+export declare function formatBytes(bytes: number): string;
+/** The `accept` attribute for a file input: `image/jpeg,image/png,image/webp`. */
+export declare function acceptAttribute(accept?: readonly string[]): string;
+/**
+ * Why a file can't be uploaded, as a sentence to show under the field, or
+ * null when it can: a type not accepted, or over the size limit.
+ */
+export declare function imageRefusal(file: Pick<File, 'type' | 'size'>, rules?: ImageFileRules): string | null;
+/** What a failed upload says: the rejection's own `message` (an `AppError`'s), else a generic sentence. */
+export declare function uploadFailure(error: unknown, noun?: string): string;

package/dist/lib/image-file.js

@@ -0,0 +1,82 @@
+// Images a person picks, pastes or drops, before they're uploaded: which
+// files are accepted, and why one isn't, in words. Shared by ImageField
+// and the rich-text editor's upload. The upload itself is the app's (an
+// `ImageUpload`): the package knows no endpoint and no storage.
+/** The image types accepted unless a field says otherwise. */
+export const DEFAULT_IMAGE_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
+// How a type is named to a person: "JPEG", not "image/jpeg".
+const TYPE_NAMES = {
+    'image/jpeg': 'JPEG',
+    'image/png': 'PNG',
+    'image/webp': 'WebP',
+    'image/gif': 'GIF',
+    'image/avif': 'AVIF',
+    'image/heic': 'HEIC',
+    'image/heif': 'HEIF',
+    'image/svg+xml': 'SVG',
+    'image/bmp': 'BMP',
+    'image/tiff': 'TIFF',
+    'application/pdf': 'PDF',
+};
+function typeName(type) {
+    if (TYPE_NAMES[type])
+        return TYPE_NAMES[type];
+    if (type === 'image/*')
+        return 'image';
+    const subtype = type.split('/')[1] ?? type;
+    return subtype.replace(/^x-/, '').toUpperCase();
+}
+// "JPEG, PNG or WebP".
+function listOr(names) {
+    return names.length <= 1 ? (names[0] ?? '') : `${names.slice(0, -1).join(', ')} or ${names.at(-1)}`;
+}
+/** A size as a person reads it: "820 KB", "4.2 MB". */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} bytes`;
+    if (bytes < 1024 * 1024)
+        return `${Math.round(bytes / 1024)} KB`;
+    const mb = bytes / (1024 * 1024);
+    return `${mb < 10 ? Math.round(mb * 10) / 10 : Math.round(mb)} MB`;
+}
+function accepts(accept, type) {
+    return accept.some((allowed) => allowed === type || (allowed.endsWith('/*') && type.startsWith(allowed.slice(0, -1))));
+}
+/** The `accept` attribute for a file input: `image/jpeg,image/png,image/webp`. */
+export function acceptAttribute(accept = DEFAULT_IMAGE_TYPES) {
+    return accept.join(',');
+}
+/**
+ * Why a file can't be uploaded, as a sentence to show under the field, or
+ * null when it can: a type not accepted, or over the size limit.
+ */
+export function imageRefusal(file, rules = {}) {
+    const accept = rules.accept ?? DEFAULT_IMAGE_TYPES;
+    if (!accepts(accept, file.type)) {
+        const wanted = listOr(accept.map(typeName));
+        const choose = accept.length === 1 && accept[0] === 'image/*' ? 'Choose an image.' : `Choose a ${wanted} image.`;
+        // A type with a name people know is named; any other file that isn't
+        // an image is just that.
+        const named = TYPE_NAMES[file.type] ?? (file.type.startsWith('image/') ? typeName(file.type) : null);
+        return named ? `That file is ${article(named)} ${named}. ${choose}` : `That file isn't an image. ${choose}`;
+    }
+    if (rules.maxSize !== undefined && file.size > rules.maxSize) {
+        return `That image is ${formatBytes(file.size)}. The limit is ${formatBytes(rules.maxSize)}.`;
+    }
+    return null;
+}
+// "a GIF", "an SVG", "an HEIC": by how the name is said, letter by letter
+// when it's an acronym.
+function article(name) {
+    const spelled = /^[A-Z][A-Z0-9]+$/.test(name);
+    return (spelled ? /^[AEFHILMNORSX]/ : /^[aeiou]/i).test(name) ? 'an' : 'a';
+}
+/** What a failed upload says: the rejection's own `message` (an `AppError`'s), else a generic sentence. */
+export function uploadFailure(error, noun = 'image') {
+    if (error && typeof error === 'object' && 'message' in error) {
+        const message = error.message;
+        if (typeof message === 'string' && message.trim())
+            return message;
+    }
+    return `The ${noun} couldn't be uploaded. Try again.`;
+}

package/dist/lib/markdown-merge.js

@@ -21,7 +21,7 @@
 //   padded, marks it nested differently) and that `meaning` still misses is
 //   written as the editor shows it, as long as nothing in it is lost
 //   (`content`): no text, address or image. A block the editor drops part
-//   of (it doesn't show images) is kept as written, and the guard refuses.
+//   of (until 4.28, every image) is kept as written, and the guard refuses.
 // - Guard: the result must mean exactly what the editor shows. If it
 //   wouldn't (two blocks fusing, say), the merge throws instead of saving
 //   something else; the draft stays on screen.

package/dist/lib/stale-chunk-reload.d.ts

@@ -0,0 +1,14 @@
+export type StaleChunkReload = {
+    /** True from the reload asked for until the page goes: nothing that fails meanwhile is a bug. */
+    isReloading: () => boolean;
+    /** Listens for `vite:preloadError` on `target`; returns the undo. */
+    install: (target: Pick<EventTarget, 'addEventListener' | 'removeEventListener'>) => () => void;
+};
+export declare function createStaleChunkReload({ storage, reload, now, windowMs, }: {
+    storage: () => Pick<Storage, 'getItem' | 'setItem'> | undefined;
+    reload: () => void;
+    now?: () => number;
+    windowMs?: number;
+}): StaleChunkReload;
+/** The one instance over the real window, sessionStorage and reload. */
+export declare function browserStaleChunkReload(): StaleChunkReload;