@gramps-connect/story 0.1.3 → 0.2.0

package/src/editor/StoryTextField.tsx

@@ -0,0 +1,61 @@
+// A plain Textarea plus Bold/Italic buttons that wrap the selection in the
+// story format's `**`/`*` markers -- the only formatting a slide's text has
+// (parseStoryText is the matching reader), so no rich-text editor.
+import { useRef } from "react";
+import { Button, Group, Stack, Text, Textarea } from "@mantine/core";
+
+/** Wraps the textarea's selection in `marker` (or unwraps it, if the
+ * selection is already exactly `marker…marker`); with nothing selected,
+ * inserts an empty pair and leaves the cursor between them. */
+function applyMarker(el: HTMLTextAreaElement, marker: string, value: string, onChange: (v: string) => void) {
+  const start = el.selectionStart ?? value.length;
+  const end = el.selectionEnd ?? value.length;
+  if (start === end) {
+    onChange(value.slice(0, start) + marker + marker + value.slice(end));
+    requestAnimationFrame(() => {
+      el.focus();
+      el.setSelectionRange(start + marker.length, start + marker.length);
+    });
+    return;
+  }
+  const selected = value.slice(start, end);
+  const alreadyWrapped = selected.length > marker.length * 2 && selected.startsWith(marker) && selected.endsWith(marker);
+  const replacement = alreadyWrapped ? selected.slice(marker.length, selected.length - marker.length) : `${marker}${selected}${marker}`;
+  onChange(value.slice(0, start) + replacement + value.slice(end));
+}
+
+export interface StoryTextFieldProps {
+  label: string;
+  value: string;
+  onChange: (value: string) => void;
+  boldLabel?: string;
+  italicLabel?: string;
+  minRows?: number;
+}
+
+export function StoryTextField({ label, value, onChange, boldLabel = "Bold", italicLabel = "Italic", minRows = 3 }: StoryTextFieldProps) {
+  const ref = useRef<HTMLTextAreaElement>(null);
+  return (
+    <Stack gap={4}>
+      <Group gap="xs">
+        <Text size="sm" fw={500}>{label}</Text>
+        <Button
+          variant="default" size="compact-xs" fw={700} aria-label={boldLabel} title={boldLabel}
+          onClick={() => ref.current && applyMarker(ref.current, "**", value, onChange)}
+        >
+          B
+        </Button>
+        <Button
+          variant="default" size="compact-xs" fs="italic" aria-label={italicLabel} title={italicLabel}
+          onClick={() => ref.current && applyMarker(ref.current, "*", value, onChange)}
+        >
+          i
+        </Button>
+      </Group>
+      <Textarea
+        ref={ref} aria-label={label} autosize minRows={minRows} maxRows={14} value={value}
+        onChange={(e) => onChange(e.currentTarget.value)}
+      />
+    </Stack>
+  );
+}

package/src/editor/dates.ts

@@ -0,0 +1,21 @@
+// A date as typed ("about 1850", "um 1850") to its precise form (EDTF),
+// read the way Gramps reads dates, in the story's language: the player
+// needs the precise form for the timeline and for picking historical maps.
+import { loadLocale, parseDate, resolveLocaleCode, toEdtf } from "@gramps-connect/gramps-date";
+
+/** Turns date text into EDTF, or undefined when the text isn't a date
+ * that has one ("spring 1850", a non-Gregorian date). */
+export type DateTextParser = (text: string, language: string | undefined) => Promise<string | undefined>;
+
+/** The default parser: gramps-date in the story's language (loaded on first
+ * use), English when the story has none or gramps-date doesn't know it. */
+export const suggestEdtf: DateTextParser = async (text, language) => {
+  if (!text.trim()) return undefined;
+  const code = (language && resolveLocaleCode(language.replace(/-/g, "_"))) || "en";
+  if (code !== "en" && !(await loadLocale(code))) return undefined;
+  try {
+    return toEdtf(parseDate(text, { locale: code }));
+  } catch {
+    return undefined;
+  }
+};

package/src/editor/index.ts

@@ -0,0 +1,10 @@
+export { StoryEditor, type StoryEditorProps } from "./StoryEditor";
+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";

package/src/editor/model.ts

@@ -0,0 +1,167 @@
+// 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 { Slide, 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;
+}
+
+/** 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,82 @@
+// 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;
+  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",
+  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;
 }
 
@@ -201,7 +204,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(
@@ -371,6 +374,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}