@gramps-connect/story 0.1.3 → 0.3.0

package/src/editor/model.ts

@@ -0,0 +1,229 @@
+// The editor's changes to a story, as pure functions from one StoryDoc to
+// the next -- never mutating, so undo is just keeping the old ones. Every
+// change spreads the object it touches, so fields this version doesn't
+// 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 { 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 {
+  return {
+    format: FORMAT_ID,
+    version: FORMAT_VERSION,
+    title,
+    ...(language ? { language } : {}),
+    slides: [{ id: "s0", title }],
+    media: {},
+  };
+}
+
+/** "s<n>" past every id already of that form, so it's unique however the
+ * story's other ids were made. */
+export function nextSlideId(doc: StoryDoc): string {
+  let max = -1;
+  for (const slide of doc.slides) {
+    const match = /^s(\d+)$/.exec(slide.id);
+    if (match) max = Math.max(max, Number(match[1]));
+  }
+  let n = max + 1;
+  const ids = new Set(doc.slides.map((s) => s.id));
+  while (ids.has(`s${n}`)) n += 1;
+  return `s${n}`;
+}
+
+function withSlides(doc: StoryDoc, slides: Slide[]): StoryDoc {
+  return { ...doc, slides };
+}
+
+/** A new empty slide after `index`; returns the story and the new slide's
+ * index. */
+export function addSlide(doc: StoryDoc, index: number): { doc: StoryDoc; index: number } {
+  const slides = [...doc.slides];
+  const at = Math.min(Math.max(index + 1, 0), slides.length);
+  slides.splice(at, 0, { id: nextSlideId(doc) });
+  return { doc: withSlides(doc, slides), index: at };
+}
+
+/** A copy of the slide right after it, with its own id. */
+export function duplicateSlide(doc: StoryDoc, index: number): { doc: StoryDoc; index: number } {
+  const slides = [...doc.slides];
+  const copy = structuredClone(slides[index]);
+  copy.id = nextSlideId(doc);
+  slides.splice(index + 1, 0, copy);
+  return { doc: withSlides(doc, slides), index: index + 1 };
+}
+
+/** Removes a slide, unless it's the only one (a story has at least one). */
+export function deleteSlide(doc: StoryDoc, index: number): { doc: StoryDoc; index: number } {
+  if (doc.slides.length <= 1) return { doc, index };
+  const slides = doc.slides.filter((_, i) => i !== index);
+  return { doc: withSlides(doc, slides), index: Math.min(index, slides.length - 1) };
+}
+
+export function moveSlide(doc: StoryDoc, from: number, to: number): StoryDoc {
+  if (from === to || to < 0 || to >= doc.slides.length) return doc;
+  const slides = [...doc.slides];
+  const [slide] = slides.splice(from, 1);
+  slides.splice(to, 0, slide);
+  return withSlides(doc, slides);
+}
+
+/** Sets fields on an object; an undefined value removes the field, so
+ * cleared text doesn't linger as "". */
+function patched<T extends object>(base: T, patch: Partial<T>): T {
+  const next = { ...base } as Record<string, unknown>;
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === undefined) delete next[key];
+    else next[key] = value;
+  }
+  return next as T;
+}
+
+export function updateSlide(doc: StoryDoc, index: number, patch: Partial<Slide>): StoryDoc {
+  const slides = [...doc.slides];
+  slides[index] = patched(slides[index], patch);
+  return withSlides(doc, slides);
+}
+
+export function updateStory(doc: StoryDoc, patch: Partial<Omit<StoryDoc, "slides" | "media">>): StoryDoc {
+  return patched(doc, patch as Partial<StoryDoc>);
+}
+
+/** A slide date from what was typed and its precise form. Empty text is no
+ * 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 function slideDate(previous: StoryDate | undefined, text: string, edtf: string | undefined): StoryDate | undefined {
+  if (!text.trim()) return undefined;
+  const next = patched(previous ?? { text }, { text, edtf: edtf || undefined });
+  if (next.edtf !== previous?.edtf) delete next.sortYear;
+  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>();
+  for (const slide of doc.slides) {
+    for (const m of slide.media ?? []) used.add(m.ref);
+    for (const o of slide.place?.overlays ?? []) used.add(o.media);
+  }
+  return used;
+}
+
+/** The story as it should be saved: media nothing refers to any more left
+ * out, and the files only those that are still used. */
+export function pruneMedia(doc: StoryDoc, files: Map<string, Uint8Array>): { doc: StoryDoc; files: Map<string, Uint8Array> } {
+  const used = usedMedia(doc);
+  const media = Object.fromEntries(Object.entries(doc.media).filter(([key]) => used.has(key)));
+  const srcs = new Set(Object.values(media).map((m) => m.src));
+  return {
+    doc: { ...doc, media },
+    files: new Map([...files].filter(([path]) => srcs.has(path))),
+  };
+}
+
+/** "Josef Meyer" -> "Josef Meyer.story.zip", minus characters some file
+ * systems refuse. */
+export function storyFileName(title: string): string {
+  const safe = title.replace(/[\\/:*?"<>|\u0000-\u001f]+/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+  return `${safe || "story"}.story.zip`;
+}
+
+/** Undo and redo over whole documents. Typing in one field makes one step,
+ * not one per keystroke: a change with the same `key` within COALESCE_MS
+ * of the last replaces it. */
+export interface History {
+  past: StoryDoc[];
+  present: StoryDoc;
+  future: StoryDoc[];
+  lastKey?: string;
+  lastAt?: number;
+}
+
+export const COALESCE_MS = 1500;
+const MAX_STEPS = 200;
+
+export function startHistory(doc: StoryDoc): History {
+  return { past: [], present: doc, future: [] };
+}
+
+export function record(history: History, next: StoryDoc, key?: string, now = Date.now()): History {
+  if (next === history.present) return history;
+  const coalesce = key !== undefined && key === history.lastKey && history.lastAt !== undefined && now - history.lastAt < COALESCE_MS;
+  const past = coalesce ? history.past : [...history.past, history.present].slice(-MAX_STEPS);
+  return { past, present: next, future: [], lastKey: key, lastAt: now };
+}
+
+export function undo(history: History): History {
+  const previous = history.past[history.past.length - 1];
+  if (!previous) return history;
+  return { past: history.past.slice(0, -1), present: previous, future: [history.present, ...history.future] };
+}
+
+export function redo(history: History): History {
+  const [next, ...future] = history.future;
+  if (!next) return history;
+  return { past: [...history.past, history.present], present: next, future };
+}

package/src/editor/strings.ts

@@ -0,0 +1,106 @@
+// The editor's own words. English here; a host with its own translations
+// (Gramps Connect) passes StoryEditor's `strings` instead.
+
+export interface EditorStrings {
+  story: string;
+  storySettings: string;
+  title: string;
+  language: string;
+  languageHint: string;
+  map: string;
+  mapStandard: string;
+  mapHistorical: string;
+  mapAuto: string;
+  mapNone: string;
+  slides: string;
+  untitledSlide: string;
+  addSlide: string;
+  duplicateSlide: string;
+  deleteSlide: string;
+  moveUp: string;
+  moveDown: string;
+  slideTitle: string;
+  text: string;
+  bold: string;
+  italic: string;
+  date: string;
+  dateHint: string;
+  preciseDate: string;
+  preciseDateHint: string;
+  preciseDateFollows: string;
+  preciseDateNotUnderstood: string;
+  matchDateAsWritten: string;
+  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;
+  preview: string;
+  problems: (count: number) => string;
+  openingSlide: string;
+}
+
+export const EDITOR_ENGLISH: EditorStrings = {
+  story: "Story",
+  storySettings: "Title, language and map",
+  title: "Title",
+  language: "Language",
+  languageHint: "The language the story is written in, e.g. en, de or fr-CA. Dates are read in it.",
+  map: "Map",
+  mapStandard: "Today's map",
+  mapHistorical: "Historical maps for each slide's year",
+  mapAuto: "Viewer's choice",
+  mapNone: "No map",
+  slides: "Slides",
+  untitledSlide: "Untitled slide",
+  addSlide: "Add slide",
+  duplicateSlide: "Duplicate",
+  deleteSlide: "Delete",
+  moveUp: "Move up",
+  moveDown: "Move down",
+  slideTitle: "Title",
+  text: "Text",
+  bold: "Bold",
+  italic: "Italic",
+  date: "Date",
+  dateHint: "As readers should see it, e.g. about 1850, 3 May 1850, between 1850 and 1860.",
+  preciseDate: "Precise date (EDTF)",
+  preciseDateHint: "Places the slide on the timeline and picks historical maps.",
+  preciseDateFollows: "Worked out from the date as written.",
+  preciseDateNotUnderstood: "Not a date the timeline can use.",
+  matchDateAsWritten: "Work it out from the date",
+  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",
+  preview: "Preview",
+  problems: (count) => (count === 1 ? "1 problem to fix before saving" : `${count} problems to fix before saving`),
+  openingSlide: "Opening slide",
+};

package/src/player/StoryPlayer.tsx

@@ -44,6 +44,9 @@ export interface StoryPlayerProps {
   renderMapModeControl?: (props: MapModeControlProps) => ReactNode;
   /** Shown before the title, e.g. ViewerBrand on a standalone page. */
   brand?: ReactNode;
+  /** The host's own buttons, at the right of the title bar (before the
+   * close button), e.g. the viewer site's Edit. */
+  actions?: ReactNode;
   initialSlide?: number;
 }
 
@@ -111,15 +114,49 @@ function SlidePhoto({ mediaKey, item, caption, credit, resolveMedia, colors }: {
   );
 }
 
-function SlideContent({ slide, story, resolveMedia, colors }: {
+/** A small button showing one of a slide's photos. */
+function PhotoThumb({ mediaKey, item, label, selected, onSelect, resolveMedia, colors }: {
+  mediaKey: string;
+  item: MediaItem;
+  label: string;
+  selected: boolean;
+  onSelect: () => void;
+  resolveMedia: StoryPlayerProps["resolveMedia"];
+  colors: PlayerColors;
+}) {
+  const [src, setSrc] = useState<string | null>(null);
+  useEffect(() => {
+    let cancelled = false;
+    resolveMedia(mediaKey, item).then((url) => { if (!cancelled) setSrc(url); }, () => {});
+    return () => { cancelled = true; };
+  }, [mediaKey, item, resolveMedia]);
+  return (
+    <button
+      type="button" aria-label={label} title={label} aria-pressed={selected} onClick={onSelect}
+      style={{
+        width: 44, height: 44, padding: 0, borderRadius: 4, overflow: "hidden", cursor: "pointer",
+        border: `2px solid ${selected ? colors.mark : "transparent"}`, background: colors.border,
+        opacity: selected ? 1 : 0.7,
+      }}
+    >
+      {src && <img src={src} alt="" style={{ width: "100%", height: "100%", objectFit: "cover", display: "block" }} />}
+    </button>
+  );
+}
+
+function SlideContent({ slide, story, resolveMedia, colors, strings }: {
   slide: Slide | undefined;
   story: StoryDoc;
   resolveMedia: StoryPlayerProps["resolveMedia"];
   colors: PlayerColors;
+  strings: PlayerStrings;
 }) {
-  // The format allows several photos per slide; the player shows the
-  // first one that exists.
-  const photo = slide?.media?.find((m) => Object.prototype.hasOwnProperty.call(story.media, m.ref));
+  // Every photo whose media exists; with several, thumbnails pick which
+  // one is shown. Keyed by slide in the caller, so each slide starts on
+  // its first photo.
+  const photos = (slide?.media ?? []).filter((m) => Object.prototype.hasOwnProperty.call(story.media, m.ref));
+  const [shown, setShown] = useState(0);
+  const photo = photos[Math.min(shown, photos.length - 1)];
   const eyebrow = [slide?.date?.text, slide?.place?.name].filter(Boolean).join(" · ");
   return (
     <>
@@ -133,6 +170,22 @@ function SlideContent({ slide, story, resolveMedia, colors }: {
           colors={colors}
         />
       )}
+      {photos.length > 1 && (
+        <div style={{ display: "flex", gap: 6, flexWrap: "wrap", justifyContent: "center" }}>
+          {photos.map((m, i) => (
+            <PhotoThumb
+              key={`${i}:${m.ref}`}
+              mediaKey={m.ref}
+              item={story.media[m.ref]}
+              label={strings.photoOf(i + 1, photos.length)}
+              selected={photo === m}
+              onSelect={() => setShown(i)}
+              resolveMedia={resolveMedia}
+              colors={colors}
+            />
+          ))}
+        </div>
+      )}
       <div style={{ display: "flex", flexDirection: "column", gap: 4, alignItems: "center", maxWidth: 640, textAlign: "center" }}>
         {eyebrow && <div dir="auto" style={{ fontSize: 14, color: colors.muted }}>{eyebrow}</div>}
         {slide?.title && <div dir="auto" style={{ fontSize: 20, fontWeight: 700, color: colors.text }}>{slide.title}</div>}
@@ -201,7 +254,7 @@ function NavArrows({ index, total, onPrev, onNext, variant, strings, colors }: {
 
 export function StoryPlayer({
   story, resolveMedia, dark = false, colors: colorOverrides, strings: stringOverrides, onClose,
-  keyboard = true, onSlideChange, renderMapModeControl, brand, initialSlide = 0,
+  keyboard = true, onSlideChange, renderMapModeControl, brand, actions, initialSlide = 0,
 }: StoryPlayerProps) {
   const colors = useMemo(() => ({ ...defaultColors(dark), ...colorOverrides }), [dark, colorOverrides]);
   const strings = useMemo(
@@ -323,7 +376,9 @@ export function StoryPlayer({
     return item ? resolveMedia(key, item) : Promise.resolve(null);
   }, [story, resolveMedia]);
 
-  const content = <SlideContent slide={slide} story={story} resolveMedia={resolveMedia} colors={colors} />;
+  const content = (
+    <SlideContent key={slide?.id ?? index} slide={slide} story={story} resolveMedia={resolveMedia} colors={colors} strings={strings} />
+  );
   const timeline = showTimeline && (
     <TimelineStrip points={datedSlides} currentIndex={index} onSelect={setIndex} colors={colors} />
   );
@@ -371,6 +426,16 @@ export function StoryPlayer({
           </div>
         </div>
       )}
+      {actions && (
+        <div
+          style={{
+            position: "absolute", top: 0, right: onClose ? 60 : 12, height: BAR_HEIGHT, zIndex: 3,
+            display: "flex", alignItems: "center", gap: 8,
+          }}
+        >
+          {actions}
+        </div>
+      )}
       {onClose && (
         <RoundButton
           label={strings.close} size={36} onClick={onClose}

package/src/player/strings.ts

@@ -15,6 +15,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 const ENGLISH: PlayerStrings = {
@@ -28,6 +30,7 @@ export const ENGLISH: PlayerStrings = {
   historicalMapYear: (year) => `Historical map, ${year}`,
   noDateStandardMap: "No date here — standard map",
   historicalYear: "Historical map year",
+  photoOf: (n, total) => `Photo ${n} of ${total}`,
 };
 
 const TABLE: Record<string, PlayerStrings> = {
@@ -43,6 +46,7 @@ const TABLE: Record<string, PlayerStrings> = {
     historicalMapYear: (year) => `Historische Karte, ${year}`,
     noDateStandardMap: "Kein Datum hier — Standardkarte",
     historicalYear: "Jahr der historischen Karte",
+    photoOf: (n, total) => `Foto ${n} von ${total}`,
   },
   es: {
     previous: "Anterior",
@@ -55,6 +59,7 @@ const TABLE: Record<string, PlayerStrings> = {
     historicalMapYear: (year) => `Mapa histórico, ${year}`,
     noDateStandardMap: "Sin fecha aquí — mapa estándar",
     historicalYear: "Año del mapa histórico",
+    photoOf: (n, total) => `Foto ${n} de ${total}`,
   },
   fr: {
     previous: "Précédent",
@@ -67,6 +72,7 @@ const TABLE: Record<string, PlayerStrings> = {
     historicalMapYear: (year) => `Carte historique, ${year}`,
     noDateStandardMap: "Pas de date ici — carte standard",
     historicalYear: "Année de la carte historique",
+    photoOf: (n, total) => `Photo ${n} sur ${total}`,
   },
   nl: {
     previous: "Vorige",
@@ -79,6 +85,7 @@ const TABLE: Record<string, PlayerStrings> = {
     historicalMapYear: (year) => `Historische kaart, ${year}`,
     noDateStandardMap: "Geen datum hier — standaardkaart",
     historicalYear: "Jaar van de historische kaart",
+    photoOf: (n, total) => `Foto ${n} van ${total}`,
   },
 };