@gramps-connect/story 0.2.0 → 0.3.0

package/dist/types/editor/PhotosField.d.ts

@@ -0,0 +1,16 @@
+import type { MediaItem, SlideMedia } from "../types";
+import type { EditorStrings } from "./strings";
+export interface PhotosFieldProps {
+    photos: SlideMedia[];
+    media: Record<string, MediaItem>;
+    /** A displayable URL for a media key. */
+    urlFor: (key: string) => Promise<string | null>;
+    strings: EditorStrings;
+    /** True while chosen files are being prepared. */
+    busy?: boolean;
+    onChange: (photos: SlideMedia[], key: string) => void;
+    /** Image files to add at the end, or to put in place of photo `replace`. */
+    onFiles: (files: File[], replace?: number) => void;
+    onDescription: (mediaKey: string, alt: string) => void;
+}
+export declare function PhotosField({ photos, media, urlFor, strings, busy, onChange, onFiles, onDescription }: PhotosFieldProps): import("react").JSX.Element;

package/dist/types/editor/StoryEditor.d.ts

@@ -1,20 +1,23 @@
 import { type ReactNode } from "react";
-import type { MediaItem, StoryDoc } from "../types";
+import type { StoryDoc } from "../types";
 import type { PlayerStrings } from "../player/strings";
 import { type DateTextParser } from "./dates";
+import { type NewImage } from "./model";
 import { type EditorStrings } from "./strings";
 export interface StoryEditorProps {
-    /** The story to start from. Changing it later has no effect: remount
-     * (a new `key`) to edit another. */
+    /** The story to start from, and its files (paths as in media `src`).
+     * Changing these later has no effect: remount (a new `key`) to edit
+     * another story. */
     initialStory: StoryDoc;
-    /** The story's files, for checking that every media file is there. */
-    files?: {
-        has(path: string): boolean;
-    };
-    /** As for StoryPlayer. */
-    resolveMedia: (key: string, item: MediaItem) => Promise<string | null>;
-    /** Called with the document after every change, undo and redo included. */
-    onChange?: (doc: StoryDoc) => void;
+    initialFiles?: Map<string, Uint8Array>;
+    /** Called with the document and its files after every change, undo and
+     * redo included. The files only grow while editing (an undone photo's
+     * file stays); pruneMedia leaves out what nothing uses when saving. */
+    onChange?: (doc: StoryDoc, files: Map<string, Uint8Array>) => void;
+    /** Turns a chosen image file into what's stored. By default
+     * optimizeImage: 1600px WebP (JPEG where the browser can't), with the
+     * original's metadata left behind. */
+    prepareImage?: (file: Blob) => Promise<NewImage>;
     /** The host's own buttons (Open, Save, ...), at the right of the top bar. */
     toolbar?: ReactNode;
     /** Shown first in the top bar, e.g. ViewerBrand. */
@@ -25,4 +28,6 @@ export interface StoryEditorProps {
     /** Date text -> EDTF. By default gramps-date, in the story's language. */
     parseDateText?: DateTextParser;
 }
-export declare function StoryEditor({ initialStory, files, resolveMedia, onChange, toolbar, brand, dark, strings: stringOverrides, playerStrings, parseDateText, }: StoryEditorProps): import("react").JSX.Element;
+/** The default prepareImage. */
+export declare function prepareImage(file: Blob): Promise<NewImage>;
+export declare function StoryEditor({ initialStory, initialFiles, onChange, prepareImage: prepare, toolbar, brand, dark, strings: stringOverrides, playerStrings, parseDateText, }: StoryEditorProps): import("react").JSX.Element;

package/dist/types/editor/index.d.ts

@@ -1,7 +1,8 @@
-export { StoryEditor, type StoryEditorProps } from "./StoryEditor";
+export { prepareImage, StoryEditor, type StoryEditorProps } from "./StoryEditor";
+export { PhotosField, type PhotosFieldProps } from "./PhotosField";
 export { StoryTextField, type StoryTextFieldProps } from "./StoryTextField";
 export { SlideList, type SlideListProps } from "./SlideList";
 export { DateField, type DateFieldProps } from "./DateField";
 export { suggestEdtf, type DateTextParser } from "./dates";
 export { EDITOR_ENGLISH, type EditorStrings } from "./strings";
-export { addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, moveSlide, nextSlideId, pruneMedia, record, redo, slideDate, startHistory, storyFileName, undo, updateSlide, updateStory, usedMedia, type History, } from "./model";
+export { addImage, addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, findMedia, moveSlide, nextSlideId, pruneMedia, record, redo, setSlidePhotos, slideDate, startHistory, storyFileName, undo, updateMedia, updateSlide, updateStory, usedMedia, type History, type NewImage, } from "./model";

package/dist/types/editor/model.d.ts

@@ -1,4 +1,4 @@
-import type { Slide, StoryDate, StoryDoc } from "../types";
+import type { MediaItem, Slide, SlideMedia, StoryDate, StoryDoc } from "../types";
 /** A story with one empty slide: the smallest valid one. */
 export declare function blankStory(title: string, language?: string): StoryDoc;
 /** "s<n>" past every id already of that form, so it's unique however the
@@ -27,6 +27,31 @@ export declare function updateStory(doc: StoryDoc, patch: Partial<Omit<StoryDoc,
  * date at all. A new precise form drops a `sortYear` it would contradict
  * (the timeline reads sortYear first); the date's other fields stay. */
 export declare function slideDate(previous: StoryDate | undefined, text: string, edtf: string | undefined): StoryDate | undefined;
+/** A prepared image to add to a story (see optimizeImage). */
+export interface NewImage {
+    data: Uint8Array;
+    mime: string;
+    /** File extension, without the dot. */
+    ext: string;
+    width?: number;
+    height?: number;
+}
+/** The media key whose file is exactly these bytes, if any: a photo
+ * that's already in the story, chosen again. */
+export declare function findMedia(doc: StoryDoc, files: Map<string, Uint8Array>, data: Uint8Array): string | undefined;
+/** Adds an image to the story's media (not to any slide), or finds the
+ * identical one already there, so the same photo is stored once. Returns
+ * its media key. */
+export declare function addImage(doc: StoryDoc, files: Map<string, Uint8Array>, image: NewImage, stem?: string): {
+    doc: StoryDoc;
+    files: Map<string, Uint8Array>;
+    key: string;
+};
+/** A slide's photo list; an empty one removes the field. */
+export declare function setSlidePhotos(doc: StoryDoc, index: number, media: SlideMedia[]): StoryDoc;
+/** Changes a media item itself (its description, shared by every slide
+ * that shows it). */
+export declare function updateMedia(doc: StoryDoc, key: string, patch: Partial<MediaItem>): StoryDoc;
 /** Every media key a slide or overlay refers to. */
 export declare function usedMedia(doc: StoryDoc): Set<string>;
 /** The story as it should be saved: media nothing refers to any more left

package/dist/types/editor/strings.d.ts

@@ -30,6 +30,18 @@ export interface EditorStrings {
     noPreciseDate: string;
     place: string;
     photos: string;
+    photosHint: string;
+    addPhoto: string;
+    replacePhoto: string;
+    movePhotoUp: string;
+    movePhotoDown: string;
+    removePhoto: string;
+    caption: string;
+    credit: string;
+    creditHint: string;
+    description: string;
+    descriptionHint: string;
+    photoFailed: (name: string) => string;
     undo: string;
     redo: string;
     present: string;

package/dist/types/player/strings.d.ts

@@ -10,6 +10,8 @@ export interface PlayerStrings {
     historicalMapYear: (year: number) => string;
     noDateStandardMap: string;
     historicalYear: string;
+    /** A photo's thumbnail button, on a slide with several. */
+    photoOf: (n: number, total: number) => string;
 }
 export declare const ENGLISH: PlayerStrings;
 /** The best table for a list of BCP 47 tags, most preferred first:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gramps-connect/story",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Read, write, validate and present .story.zip files: portable, versioned family-history stories.",
   "license": "AGPL-3.0-or-later",
   "type": "module",

package/src/editor/PhotosField.tsx

@@ -0,0 +1,134 @@
+// A slide's photos: add (pick, drop or paste -- pasting is the editor's),
+// replace, reorder and remove them, and write each one's caption, credit
+// and description. The files themselves are the editor's to prepare and
+// store; this only says what was chosen.
+import { useEffect, useRef, useState, type DragEvent } from "react";
+import { ActionIcon, Box, Button, Group, Loader, Stack, Text, TextInput, Tooltip } from "@mantine/core";
+import type { MediaItem, SlideMedia } from "../types";
+import type { EditorStrings } from "./strings";
+
+export interface PhotosFieldProps {
+  photos: SlideMedia[];
+  media: Record<string, MediaItem>;
+  /** A displayable URL for a media key. */
+  urlFor: (key: string) => Promise<string | null>;
+  strings: EditorStrings;
+  /** True while chosen files are being prepared. */
+  busy?: boolean;
+  onChange: (photos: SlideMedia[], key: string) => void;
+  /** Image files to add at the end, or to put in place of photo `replace`. */
+  onFiles: (files: File[], replace?: number) => void;
+  onDescription: (mediaKey: string, alt: string) => void;
+}
+
+const imagesIn = (list: FileList | null | undefined) => [...(list ?? [])].filter((f) => f.type.startsWith("image/"));
+
+function Preview({ mediaKey, urlFor }: { mediaKey: string; urlFor: PhotosFieldProps["urlFor"] }) {
+  const [url, setUrl] = useState<string | null>(null);
+  useEffect(() => {
+    let live = true;
+    void urlFor(mediaKey).then((u) => { if (live) setUrl(u); });
+    return () => { live = false; };
+  }, [mediaKey, urlFor]);
+  return (
+    <Box w={96} h={96} style={{ flex: "none", borderRadius: 6, overflow: "hidden", background: "var(--mantine-color-default-hover)" }}>
+      {url && <img src={url} alt="" style={{ width: "100%", height: "100%", objectFit: "cover", display: "block" }} />}
+    </Box>
+  );
+}
+
+export function PhotosField({ photos, media, urlFor, strings, busy, onChange, onFiles, onDescription }: PhotosFieldProps) {
+  const input = useRef<HTMLInputElement>(null);
+  const replacing = useRef<number | undefined>(undefined);
+  const [dropping, setDropping] = useState(false);
+
+  const pick = (replace?: number) => {
+    replacing.current = replace;
+    input.current?.click();
+  };
+  const set = (i: number, patch: Partial<SlideMedia>, field: string) => {
+    const next = photos.map((p, j) => {
+      if (j !== i) return p;
+      const changed: Record<string, unknown> = { ...p, ...patch };
+      for (const [k, v] of Object.entries(patch)) if (!v) delete changed[k];
+      return changed as unknown as SlideMedia;
+    });
+    onChange(next, `photo:${i}:${field}`);
+  };
+  const move = (from: number, to: number) => {
+    const next = [...photos];
+    const [p] = next.splice(from, 1);
+    next.splice(to, 0, p);
+    onChange(next, "photos");
+  };
+  const onDrop = (e: DragEvent) => {
+    e.preventDefault();
+    setDropping(false);
+    const files = imagesIn(e.dataTransfer.files);
+    if (files.length) onFiles(files);
+  };
+
+  return (
+    <Stack
+      gap="sm"
+      onDragOver={(e) => { if ([...e.dataTransfer.types].includes("Files")) { e.preventDefault(); setDropping(true); } }}
+      onDragLeave={(e) => { if (e.currentTarget === e.target) setDropping(false); }}
+      onDrop={onDrop}
+      style={{
+        borderRadius: 8, padding: dropping ? 8 : 0, margin: dropping ? -8 : 0,
+        outline: dropping ? "2px dashed var(--mantine-primary-color-filled)" : undefined,
+      }}
+    >
+      <Group justify="space-between">
+        <Text size="sm" fw={500}>{strings.photos}</Text>
+        <Group gap="xs">
+          {busy && <Loader size="xs" />}
+          <Button variant="default" size="xs" onClick={() => pick()} disabled={busy}>+ {strings.addPhoto}</Button>
+        </Group>
+      </Group>
+      <input
+        ref={input} type="file" accept="image/*" multiple hidden
+        onChange={(e) => {
+          const files = imagesIn(e.currentTarget.files);
+          e.currentTarget.value = "";
+          if (files.length) onFiles(replacing.current === undefined ? files : files.slice(0, 1), replacing.current);
+        }}
+      />
+      {photos.length === 0 && <Text size="xs" c="dimmed">{strings.photosHint}</Text>}
+      {photos.map((photo, i) => {
+        const item = Object.prototype.hasOwnProperty.call(media, photo.ref) ? media[photo.ref] : undefined;
+        return (
+          <Group key={i} gap="sm" align="flex-start" wrap="nowrap">
+            <Stack gap={4} align="center">
+              <Preview mediaKey={photo.ref} urlFor={urlFor} />
+              <Group gap={4}>
+                <Tooltip label={strings.movePhotoUp}>
+                  <ActionIcon size="sm" variant="default" aria-label={strings.movePhotoUp} disabled={i === 0} onClick={() => move(i, i - 1)}>↑</ActionIcon>
+                </Tooltip>
+                <Tooltip label={strings.movePhotoDown}>
+                  <ActionIcon size="sm" variant="default" aria-label={strings.movePhotoDown} disabled={i === photos.length - 1} onClick={() => move(i, i + 1)}>↓</ActionIcon>
+                </Tooltip>
+              </Group>
+            </Stack>
+            <Stack gap={6} style={{ flex: 1, minWidth: 0 }}>
+              <TextInput size="xs" label={strings.caption} value={photo.caption ?? ""} onChange={(e) => set(i, { caption: e.currentTarget.value }, "caption")} />
+              <TextInput size="xs" label={strings.credit} placeholder={strings.creditHint} value={photo.credit ?? ""} onChange={(e) => set(i, { credit: e.currentTarget.value }, "credit")} />
+              {item && (
+                <TextInput
+                  size="xs" label={strings.description} description={strings.descriptionHint} value={item.alt ?? ""}
+                  onChange={(e) => onDescription(photo.ref, e.currentTarget.value)}
+                />
+              )}
+              <Group gap="xs">
+                <Button variant="subtle" size="compact-xs" onClick={() => pick(i)} disabled={busy}>{strings.replacePhoto}</Button>
+                <Button variant="subtle" size="compact-xs" color="red" onClick={() => onChange(photos.filter((_, j) => j !== i), "photos")}>
+                  {strings.removePhoto}
+                </Button>
+              </Group>
+            </Stack>
+          </Group>
+        );
+      })}
+    </Stack>
+  );
+}

package/src/editor/StoryEditor.tsx

@@ -6,21 +6,23 @@
 //
 // Needs Mantine: wrap it in a MantineProvider and load @mantine/core's
 // stylesheet, as with any Mantine component.
-import { useCallback, useEffect, useMemo, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import {
   ActionIcon, Badge, Box, Button, Divider, Group, Modal, Popover, Select, Stack, Text, TextInput, Tooltip, UnstyledButton,
 } from "@mantine/core";
 import { useMediaQuery } from "@mantine/hooks";
-import type { MediaItem, Slide, StoryDoc } from "../types";
+import type { MediaItem, Slide, SlideMedia, StoryDoc } from "../types";
+import { optimizeImage } from "../image";
 import { validate, type StoryIssue } from "../validate";
 import { StoryPlayer } from "../player/StoryPlayer";
 import type { PlayerStrings } from "../player/strings";
 import { suggestEdtf, type DateTextParser } from "./dates";
 import { DateField } from "./DateField";
 import {
-  addSlide, deleteSlide, duplicateSlide, moveSlide, record, redo, startHistory, undo, updateSlide, updateStory,
-  type History,
+  addImage, addSlide, deleteSlide, findMedia, duplicateSlide, moveSlide, record, redo, setSlidePhotos, startHistory, undo, updateMedia,
+  updateSlide, updateStory, type History, type NewImage,
 } from "./model";
+import { PhotosField } from "./PhotosField";
 import { SlideList } from "./SlideList";
 import { StoryTextField } from "./StoryTextField";
 import { EDITOR_ENGLISH, type EditorStrings } from "./strings";
@@ -30,15 +32,19 @@ const BAR_HEIGHT = 56;
 const STORY = -1;
 
 export interface StoryEditorProps {
-  /** The story to start from. Changing it later has no effect: remount
-   * (a new `key`) to edit another. */
+  /** The story to start from, and its files (paths as in media `src`).
+   * Changing these later has no effect: remount (a new `key`) to edit
+   * another story. */
   initialStory: StoryDoc;
-  /** The story's files, for checking that every media file is there. */
-  files?: { has(path: string): boolean };
-  /** As for StoryPlayer. */
-  resolveMedia: (key: string, item: MediaItem) => Promise<string | null>;
-  /** Called with the document after every change, undo and redo included. */
-  onChange?: (doc: StoryDoc) => void;
+  initialFiles?: Map<string, Uint8Array>;
+  /** Called with the document and its files after every change, undo and
+   * redo included. The files only grow while editing (an undone photo's
+   * file stays); pruneMedia leaves out what nothing uses when saving. */
+  onChange?: (doc: StoryDoc, files: Map<string, Uint8Array>) => void;
+  /** Turns a chosen image file into what's stored. By default
+   * optimizeImage: 1600px WebP (JPEG where the browser can't), with the
+   * original's metadata left behind. */
+  prepareImage?: (file: Blob) => Promise<NewImage>;
   /** The host's own buttons (Open, Save, ...), at the right of the top bar. */
   toolbar?: ReactNode;
   /** Shown first in the top bar, e.g. ViewerBrand. */
@@ -56,7 +62,15 @@ function issueSlide(issue: StoryIssue): number {
   return match ? Number(match[1]) : STORY;
 }
 
-function Thumb({ doc, slide, resolveMedia }: { doc: StoryDoc; slide: Slide; resolveMedia: StoryEditorProps["resolveMedia"] }) {
+type Resolve = (key: string, item: MediaItem) => Promise<string | null>;
+
+/** The default prepareImage. */
+export async function prepareImage(file: Blob): Promise<NewImage> {
+  const image = await optimizeImage(file);
+  return { data: new Uint8Array(await image.blob.arrayBuffer()), mime: image.mime, ext: image.ext, width: image.width, height: image.height };
+}
+
+function Thumb({ doc, slide, resolveMedia }: { doc: StoryDoc; slide: Slide; resolveMedia: Resolve }) {
   const ref = slide.media?.[0]?.ref;
   const item = ref && Object.prototype.hasOwnProperty.call(doc.media, ref) ? doc.media[ref] : undefined;
   const [url, setUrl] = useState<string | null>(null);
@@ -77,8 +91,8 @@ function Thumb({ doc, slide, resolveMedia }: { doc: StoryDoc; slide: Slide; reso
 }
 
 export function StoryEditor({
-  initialStory, files, resolveMedia, onChange, toolbar, brand, dark = false, strings: stringOverrides, playerStrings,
-  parseDateText = suggestEdtf,
+  initialStory, initialFiles, onChange, prepareImage: prepare = prepareImage, toolbar, brand, dark = false,
+  strings: stringOverrides, playerStrings, parseDateText = suggestEdtf,
 }: StoryEditorProps) {
   const strings = useMemo(() => ({ ...EDITOR_ENGLISH, ...stringOverrides }), [stringOverrides]);
   const [history, setHistory] = useState<History>(() => startHistory(initialStory));
@@ -87,12 +101,39 @@ export function StoryEditor({
   const [problemsOpen, setProblemsOpen] = useState(false);
   const wide = useMediaQuery("(min-width: 1000px)", true);
   const doc = history.present;
+  const [files, setFiles] = useState(() => new Map(initialFiles ?? []));
+  const [busy, setBusy] = useState(false);
+  const [photoError, setPhotoError] = useState<string | null>(null);
+  // The latest of each, for work that finishes after a render (photos).
+  const docRef = useRef(doc);
+  docRef.current = doc;
+  const filesRef = useRef(files);
+  filesRef.current = files;
+
+  // A blob: URL per stored file, made once and released with the editor.
+  const urls = useRef(new Map<string, string>());
+  useEffect(() => () => {
+    for (const url of urls.current.values()) URL.revokeObjectURL(url);
+  }, []);
+  const resolveMedia = useCallback<Resolve>(async (_key, item) => {
+    const cached = urls.current.get(item.src);
+    if (cached) return cached;
+    const data = filesRef.current.get(item.src);
+    if (!data) return null;
+    const url = URL.createObjectURL(new Blob([data as Uint8Array<ArrayBuffer>], { type: item.mime }));
+    urls.current.set(item.src, url);
+    return url;
+  }, []);
+  const urlFor = useCallback((key: string) => {
+    const item = Object.prototype.hasOwnProperty.call(docRef.current.media, key) ? docRef.current.media[key] : undefined;
+    return item ? resolveMedia(key, item) : Promise.resolve(null);
+  }, [resolveMedia]);
 
   // Every change goes through here (and so into history and to the host).
   const apply = useCallback((next: StoryDoc, key?: string) => {
     setHistory((h) => record(h, next, key));
   }, []);
-  useEffect(() => { onChange?.(doc); }, [doc, onChange]);
+  useEffect(() => { onChange?.(doc, files); }, [doc, files, onChange]);
 
   const index = selected === STORY ? STORY : Math.min(selected, doc.slides.length - 1);
   const slide = index === STORY ? undefined : doc.slides[index];
@@ -102,6 +143,61 @@ export function StoryEditor({
 
   const issues = useMemo(() => validate(doc, files).errors, [doc, files]);
 
+  /** Prepares image files and puts them on a slide: added at the end, or
+   * in place of photo `replace` (keeping its caption and credit). */
+  const addPhotos = useCallback(async (chosen: File[], slideId: string, replace?: number) => {
+    setBusy(true);
+    setPhotoError(null);
+    // A file already in the story (chosen again) is used as it is;
+    // anything else is prepared first.
+    const chosenImages: (NewImage | string)[] = [];
+    for (const file of chosen) {
+      try {
+        const known = findMedia(docRef.current, filesRef.current, new Uint8Array(await file.arrayBuffer()));
+        chosenImages.push(known ?? await prepare(file));
+      } catch {
+        setPhotoError(strings.photoFailed(file.name || "the image"));
+      }
+    }
+    setBusy(false);
+    if (!chosenImages.length) return;
+    let next = docRef.current;
+    let nextFiles = filesRef.current;
+    const keys: string[] = [];
+    for (const image of chosenImages) {
+      if (typeof image === "string") {
+        keys.push(image);
+        continue;
+      }
+      const added = addImage(next, nextFiles, image);
+      next = added.doc;
+      nextFiles = added.files;
+      keys.push(added.key);
+    }
+    const at = next.slides.findIndex((s) => s.id === slideId);
+    if (at < 0) return;
+    const photos: SlideMedia[] = [...(next.slides[at].media ?? [])];
+    if (replace !== undefined && photos[replace]) photos[replace] = { ...photos[replace], ref: keys[0] };
+    else photos.push(...keys.map((ref) => ({ ref })));
+    setFiles(nextFiles);
+    apply(setSlidePhotos(next, at, photos));
+  }, [apply, prepare, strings]);
+
+  // Pasting an image (outside a text field) adds it to the slide.
+  const slideId = slide?.id;
+  useEffect(() => {
+    if (!slideId) return;
+    const onPaste = (e: ClipboardEvent) => {
+      if ((e.target as HTMLElement | null)?.closest("input, textarea, [contenteditable=true]")) return;
+      const images = [...(e.clipboardData?.files ?? [])].filter((f) => f.type.startsWith("image/"));
+      if (!images.length) return;
+      e.preventDefault();
+      void addPhotos(images, slideId);
+    };
+    window.addEventListener("paste", onPaste);
+    return () => window.removeEventListener("paste", onPaste);
+  }, [slideId, addPhotos]);
+
   // Undo/redo from the keyboard, except where a text field has its own.
   useEffect(() => {
     const onKey = (e: KeyboardEvent) => {
@@ -192,19 +288,13 @@ export function StoryEditor({
           </Text>
         </Stack>
       )}
-      {slide.media && slide.media.length > 0 && (
-        <Stack gap={4}>
-          <Text size="sm" fw={500}>{strings.photos}</Text>
-          <Group gap="sm">
-            {slide.media.map((m, i) => (
-              <Group key={i} gap="xs" wrap="nowrap">
-                <Thumb doc={doc} slide={{ id: "", media: [m] }} resolveMedia={resolveMedia} />
-                <Text size="xs" c="dimmed" maw={200} lineClamp={2}>{m.caption ?? ""}</Text>
-              </Group>
-            ))}
-          </Group>
-        </Stack>
-      )}
+      <PhotosField
+        photos={slide.media ?? []} media={doc.media} urlFor={urlFor} strings={strings} busy={busy}
+        onChange={(photos, key) => apply(setSlidePhotos(doc, index, photos), `${slide.id}:${key}`)}
+        onFiles={(chosen, replace) => void addPhotos(chosen, slide.id, replace)}
+        onDescription={(key, alt) => apply(updateMedia(doc, key, { alt: alt || undefined }), `media:${key}:alt`)}
+      />
+      {photoError && <Text size="xs" c="red" role="alert">{photoError}</Text>}
     </Stack>
   );
 

package/src/editor/index.ts

@@ -1,10 +1,12 @@
-export { StoryEditor, type StoryEditorProps } from "./StoryEditor";
+export { prepareImage, StoryEditor, type StoryEditorProps } from "./StoryEditor";
+export { PhotosField, type PhotosFieldProps } from "./PhotosField";
 export { StoryTextField, type StoryTextFieldProps } from "./StoryTextField";
 export { SlideList, type SlideListProps } from "./SlideList";
 export { DateField, type DateFieldProps } from "./DateField";
 export { suggestEdtf, type DateTextParser } from "./dates";
 export { EDITOR_ENGLISH, type EditorStrings } from "./strings";
 export {
-  addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, moveSlide, nextSlideId, pruneMedia, record, redo,
-  slideDate, startHistory, storyFileName, undo, updateSlide, updateStory, usedMedia, type History,
+  addImage, addSlide, blankStory, COALESCE_MS, deleteSlide, duplicateSlide, findMedia, moveSlide, nextSlideId, pruneMedia, record, redo,
+  setSlidePhotos, slideDate, startHistory, storyFileName, undo, updateMedia, updateSlide, updateStory, usedMedia,
+  type History, type NewImage,
 } from "./model";

package/src/editor/model.ts

@@ -4,7 +4,7 @@
 // know (a newer minor version's, an extension's) ride along untouched:
 // opening and saving a story must never lose anything.
 import { FORMAT_ID, FORMAT_VERSION } from "../version";
-import type { Slide, StoryDate, StoryDoc } from "../types";
+import type { MediaItem, Slide, SlideMedia, StoryDate, StoryDoc } from "../types";
 
 /** A story with one empty slide: the smallest valid one. */
 export function blankStory(title: string, language?: string): StoryDoc {
@@ -100,6 +100,68 @@ export function slideDate(previous: StoryDate | undefined, text: string, edtf: s
   return next;
 }
 
+/** A prepared image to add to a story (see optimizeImage). */
+export interface NewImage {
+  data: Uint8Array;
+  mime: string;
+  /** File extension, without the dot. */
+  ext: string;
+  width?: number;
+  height?: number;
+}
+
+function sameBytes(a: Uint8Array | undefined, b: Uint8Array): boolean {
+  if (!a || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
+
+/** The media key whose file is exactly these bytes, if any: a photo
+ * that's already in the story, chosen again. */
+export function findMedia(doc: StoryDoc, files: Map<string, Uint8Array>, data: Uint8Array): string | undefined {
+  for (const [key, item] of Object.entries(doc.media)) {
+    if (sameBytes(files.get(item.src), data)) return key;
+  }
+  return undefined;
+}
+
+/** Adds an image to the story's media (not to any slide), or finds the
+ * identical one already there, so the same photo is stored once. Returns
+ * its media key. */
+export function addImage(
+  doc: StoryDoc, files: Map<string, Uint8Array>, image: NewImage, stem = "photo",
+): { doc: StoryDoc; files: Map<string, Uint8Array>; key: string } {
+  const existing = findMedia(doc, files, image.data);
+  if (existing) return { doc, files, key: existing };
+  let n = 1;
+  const taken = (key: string) => Object.prototype.hasOwnProperty.call(doc.media, key) || files.has(`media/${key}.${image.ext}`);
+  while (taken(`${stem}-${n}`)) n += 1;
+  const key = `${stem}-${n}`;
+  const src = `media/${key}.${image.ext}`;
+  const item: MediaItem = {
+    src, mime: image.mime,
+    ...(image.width ? { width: image.width } : {}),
+    ...(image.height ? { height: image.height } : {}),
+  };
+  return {
+    doc: { ...doc, media: { ...doc.media, [key]: item } },
+    files: new Map(files).set(src, image.data),
+    key,
+  };
+}
+
+/** A slide's photo list; an empty one removes the field. */
+export function setSlidePhotos(doc: StoryDoc, index: number, media: SlideMedia[]): StoryDoc {
+  return updateSlide(doc, index, { media: media.length ? media : undefined });
+}
+
+/** Changes a media item itself (its description, shared by every slide
+ * that shows it). */
+export function updateMedia(doc: StoryDoc, key: string, patch: Partial<MediaItem>): StoryDoc {
+  if (!Object.prototype.hasOwnProperty.call(doc.media, key)) return doc;
+  return { ...doc, media: { ...doc.media, [key]: patched(doc.media[key], patch) } };
+}
+
 /** Every media key a slide or overlay refers to. */
 export function usedMedia(doc: StoryDoc): Set<string> {
   const used = new Set<string>();

package/src/editor/strings.ts

@@ -33,6 +33,18 @@ export interface EditorStrings {
   noPreciseDate: string;
   place: string;
   photos: string;
+  photosHint: string;
+  addPhoto: string;
+  replacePhoto: string;
+  movePhotoUp: string;
+  movePhotoDown: string;
+  removePhoto: string;
+  caption: string;
+  credit: string;
+  creditHint: string;
+  description: string;
+  descriptionHint: string;
+  photoFailed: (name: string) => string;
   undo: string;
   redo: string;
   present: string;
@@ -73,6 +85,18 @@ export const EDITOR_ENGLISH: EditorStrings = {
   noPreciseDate: "None: this slide stays off the timeline.",
   place: "Place",
   photos: "Photos",
+  photosHint: "Add, drop or paste a photo. It's resized for the screen, and hidden details like camera and location are left out.",
+  addPhoto: "Add photo",
+  replacePhoto: "Replace",
+  movePhotoUp: "Move photo up",
+  movePhotoDown: "Move photo down",
+  removePhoto: "Remove",
+  caption: "Caption",
+  credit: "Credit",
+  creditHint: "Who took it, or where it's from",
+  description: "Description",
+  descriptionHint: "What the photo shows, for anyone who can't see it.",
+  photoFailed: (name) => `Couldn't use ${name}: this browser can't read it as an image.`,
   undo: "Undo",
   redo: "Redo",
   present: "Present",