@gramps-connect/story 0.1.3 → 0.3.0

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

@@ -0,0 +1,80 @@
+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
+ * story's other ids were made. */
+export declare function nextSlideId(doc: StoryDoc): string;
+/** A new empty slide after `index`; returns the story and the new slide's
+ * index. */
+export declare function addSlide(doc: StoryDoc, index: number): {
+    doc: StoryDoc;
+    index: number;
+};
+/** A copy of the slide right after it, with its own id. */
+export declare function duplicateSlide(doc: StoryDoc, index: number): {
+    doc: StoryDoc;
+    index: number;
+};
+/** Removes a slide, unless it's the only one (a story has at least one). */
+export declare function deleteSlide(doc: StoryDoc, index: number): {
+    doc: StoryDoc;
+    index: number;
+};
+export declare function moveSlide(doc: StoryDoc, from: number, to: number): StoryDoc;
+export declare function updateSlide(doc: StoryDoc, index: number, patch: Partial<Slide>): StoryDoc;
+export declare function updateStory(doc: StoryDoc, patch: Partial<Omit<StoryDoc, "slides" | "media">>): 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 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
+ * out, and the files only those that are still used. */
+export declare function pruneMedia(doc: StoryDoc, files: Map<string, Uint8Array>): {
+    doc: StoryDoc;
+    files: Map<string, Uint8Array>;
+};
+/** "Josef Meyer" -> "Josef Meyer.story.zip", minus characters some file
+ * systems refuse. */
+export declare function storyFileName(title: string): string;
+/** 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 declare const COALESCE_MS = 1500;
+export declare function startHistory(doc: StoryDoc): History;
+export declare function record(history: History, next: StoryDoc, key?: string, now?: number): History;
+export declare function undo(history: History): History;
+export declare function redo(history: History): History;

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

@@ -0,0 +1,52 @@
+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 declare const EDITOR_ENGLISH: EditorStrings;

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

@@ -28,6 +28,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;
 }
-export declare function StoryPlayer({ story, resolveMedia, dark, colors: colorOverrides, strings: stringOverrides, onClose, keyboard, onSlideChange, renderMapModeControl, brand, initialSlide, }: StoryPlayerProps): import("react").JSX.Element;
+export declare function StoryPlayer({ story, resolveMedia, dark, colors: colorOverrides, strings: stringOverrides, onClose, keyboard, onSlideChange, renderMapModeControl, brand, actions, initialSlide, }: StoryPlayerProps): import("react").JSX.Element;

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.1.3",
+  "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",
@@ -31,6 +31,11 @@
       "types": "./dist/types/player/index.d.ts",
       "default": "./dist/player.js"
     },
+    "./editor": {
+      "source": "./src/editor/index.ts",
+      "types": "./dist/types/editor/index.d.ts",
+      "default": "./dist/editor.js"
+    },
     "./embed": "./dist/embed.js",
     "./schema/1.0": "./spec/1.0/story.schema.json",
     "./package.json": "./package.json"
@@ -51,17 +56,20 @@
     "build:site": "node scripts/build.mjs && node scripts/build-site.mjs",
     "prepack": "node scripts/build.mjs",
     "generate": "node scripts/generate-validator.mjs",
-    "test": "tsx --test src/__tests__/*.test.ts",
+    "test": "tsx --conditions=source --test src/__tests__/*.test.ts",
     "typecheck": "tsc --noEmit",
-    "test:browser": "node scripts/test-image.mjs && node scripts/test-player.mjs && npm run build:site && node scripts/test-embed.mjs && node scripts/test-site.mjs",
+    "test:browser": "node scripts/test-image.mjs && node scripts/test-player.mjs && npm run build:site && node scripts/test-embed.mjs && node scripts/test-site.mjs && node scripts/test-editor.mjs",
     "test:pack": "node scripts/test-pack.mjs",
     "test:python": "${PYTHON:-python3} -m unittest discover -s python && tsx scripts/test-python.ts"
   },
   "dependencies": {
-    "fflate": "^0.8.3",
-    "@openhistoricalmap/maplibre-gl-dates": "^1.4.0"
+    "@gramps-connect/gramps-date": "^0.1.0",
+    "@openhistoricalmap/maplibre-gl-dates": "^1.4.0",
+    "fflate": "^0.8.3"
   },
   "devDependencies": {
+    "@mantine/core": "^8.3.18",
+    "@mantine/hooks": "^8.3.18",
     "@types/geojson": "^7946.0.16",
     "@types/node": "^26.1.2",
     "@types/react": "^18.3.12",
@@ -76,11 +84,19 @@
     "typescript": "^7.0.2"
   },
   "peerDependencies": {
+    "@mantine/core": "^8",
+    "@mantine/hooks": "^8",
     "maplibre-gl": ">=5",
     "react": "^18.2 || ^19",
     "react-dom": "^18.2 || ^19"
   },
   "peerDependenciesMeta": {
+    "@mantine/core": {
+      "optional": true
+    },
+    "@mantine/hooks": {
+      "optional": true
+    },
     "maplibre-gl": {
       "optional": true
     },

package/src/editor/DateField.tsx

@@ -0,0 +1,95 @@
+// A slide's date: the text readers see, and its precise form (EDTF), which
+// follows the text as it's typed until someone changes it by hand.
+import { useEffect, useRef, useState } from "react";
+import { Anchor, Group, Stack, Text, TextInput } from "@mantine/core";
+import type { StoryDate } from "../types";
+import { edtfYearRange } from "../player/dates";
+import type { DateTextParser } from "./dates";
+import { slideDate } from "./model";
+import type { EditorStrings } from "./strings";
+
+export interface DateFieldProps {
+  value: StoryDate | undefined;
+  language: string | undefined;
+  parse: DateTextParser;
+  strings: EditorStrings;
+  onChange: (date: StoryDate | undefined) => void;
+}
+
+/** Keyed by slide in the parent, so `following` starts over per slide. */
+export function DateField({ value, language, parse, strings, onChange }: DateFieldProps) {
+  // Whether the precise form is worked out from the text. Unknown (null)
+  // until the stored one has been compared with what the text gives.
+  const [following, setFollowing] = useState<boolean | null>(value?.edtf ? null : true);
+  const latest = useRef(value);
+  latest.current = value;
+  const request = useRef(0);
+
+  useEffect(() => {
+    if (following !== null) return;
+    let live = true;
+    void parse(value?.text ?? "", language).then((edtf) => {
+      if (live) setFollowing(edtf === value?.edtf);
+    });
+    return () => { live = false; };
+    // Once, for the stored date.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  const follow = (text: string) => {
+    const id = ++request.current;
+    void parse(text, language).then((edtf) => {
+      // Only the latest text's answer, and only onto the date as it is now.
+      if (id !== request.current || latest.current?.text !== text) return;
+      onChange(slideDate(latest.current, text, edtf));
+    });
+  };
+
+  const onText = (text: string) => {
+    onChange(slideDate(latest.current, text, latest.current?.edtf));
+    if (following !== false) follow(text);
+  };
+
+  const edtf = value?.edtf ?? "";
+  const understood = !edtf || edtfYearRange(edtf) !== null;
+  let note: string;
+  if (edtf && !understood) note = strings.preciseDateNotUnderstood;
+  else if (!edtf) note = strings.noPreciseDate;
+  else if (following) note = strings.preciseDateFollows;
+  else note = strings.preciseDateHint;
+
+  return (
+    <Stack gap={6}>
+      <TextInput
+        label={strings.date}
+        description={strings.dateHint}
+        value={value?.text ?? ""}
+        onChange={(e) => onText(e.currentTarget.value)}
+      />
+      {value?.text && (
+        <Group gap="sm" align="flex-end" wrap="nowrap">
+          <TextInput
+            label={strings.preciseDate}
+            size="xs"
+            w={200}
+            value={edtf}
+            error={!understood}
+            styles={{ input: { fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace" } }}
+            onChange={(e) => {
+              setFollowing(false);
+              onChange(slideDate(latest.current, latest.current?.text ?? "", e.currentTarget.value.trim() || undefined));
+            }}
+          />
+          <Stack gap={0} pb={4}>
+            <Text size="xs" c={understood ? "dimmed" : "red"}>{note}</Text>
+            {following === false && (
+              <Anchor component="button" type="button" size="xs" onClick={() => { setFollowing(true); follow(value.text); }}>
+                {strings.matchDateAsWritten}
+              </Anchor>
+            )}
+          </Stack>
+        </Group>
+      )}
+    </Stack>
+  );
+}

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/SlideList.tsx

@@ -0,0 +1,54 @@
+// A list of slides to pick from and reorder by dragging -- generic over
+// what a slide is, so any story editor can use it with its own rows.
+import { useState, type ReactNode } from "react";
+import { Stack, UnstyledButton } from "@mantine/core";
+
+export interface SlideListProps<T> {
+  items: T[];
+  selected: number;
+  onSelect: (index: number) => void;
+  /** Called when a row is dropped somewhere else. */
+  onMove: (from: number, to: number) => void;
+  getKey: (item: T, index: number) => string;
+  renderItem: (item: T, index: number) => ReactNode;
+  label?: string;
+}
+
+export function SlideList<T>({ items, selected, onSelect, onMove, getKey, renderItem, label }: SlideListProps<T>) {
+  const [dragging, setDragging] = useState<number | null>(null);
+  const [over, setOver] = useState<number | null>(null);
+  const end = () => { setDragging(null); setOver(null); };
+
+  return (
+    <Stack gap={4} role="listbox" aria-label={label}>
+      {items.map((item, i) => {
+        const isSelected = i === selected;
+        // A line on the side the row will land: below when moving down.
+        const dropLine = over === i && dragging !== null && dragging !== i
+          ? (dragging < i ? { borderBottom: "2px solid var(--mantine-primary-color-filled)" } : { borderTop: "2px solid var(--mantine-primary-color-filled)" })
+          : {};
+        return (
+          <UnstyledButton
+            key={getKey(item, i)}
+            role="option"
+            aria-selected={isSelected}
+            draggable
+            onClick={() => onSelect(i)}
+            onDragStart={(e) => { setDragging(i); e.dataTransfer.effectAllowed = "move"; e.dataTransfer.setData("text/plain", String(i)); }}
+            onDragOver={(e) => { if (dragging === null) return; e.preventDefault(); setOver(i); }}
+            onDrop={(e) => { e.preventDefault(); if (dragging !== null && dragging !== i) onMove(dragging, i); end(); }}
+            onDragEnd={end}
+            style={{
+              display: "block", width: "100%", padding: "6px 8px", borderRadius: 6,
+              background: isSelected ? "var(--mantine-primary-color-light)" : undefined,
+              opacity: dragging === i ? 0.5 : 1,
+              ...dropLine,
+            }}
+          >
+            {renderItem(item, i)}
+          </UnstyledButton>
+        );
+      })}
+    </Stack>
+  );
+}