@miadi/episode-ui 0.1.0

package/src/text-editor.tsx

@@ -0,0 +1,230 @@
+"use client"
+
+import { useEffect, useRef, useState } from "react"
+import type { CSSProperties, ReactNode } from "react"
+import {
+  DEFAULT_THEME,
+  themeVars,
+  type EpisodeTextView,
+  type EpisodeUITheme,
+  type FileRevisionView,
+} from "./types.js"
+
+export interface SaveOutcome {
+  ok: boolean
+  /** Present when the file moved under the writer. */
+  conflict?: { currentRevision: FileRevisionView; currentContent?: string }
+  message?: string
+}
+
+export interface EpisodeTextEditorProps {
+  /** Vessel-relative path, shown as the editor's identity. */
+  file: string
+  /** What the host read. `revision.sha256` is the guard carried into the save. */
+  loaded: EpisodeTextView
+  /**
+   * Save. Resolve `{ ok: true }` when it landed, or `{ ok: false, conflict }`
+   * when the vessel refused with 409. Throwing is also handled — the draft is
+   * kept either way.
+   */
+  onSave: (content: string, expectedRevision: string) => Promise<SaveOutcome>
+  /** Re-read the file. Called when a person chooses to reload after a conflict. */
+  onReload?: () => void
+  readOnly?: boolean
+  theme?: EpisodeUITheme
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Edit one text artefact of a vessel.
+ *
+ * The whole point of this component is the conflict path. When someone else
+ * writes the file between load and save, the vessel refuses and hands back the
+ * revision on disk. This editor then:
+ *
+ *  - keeps the draft in the textarea, always, and says so;
+ *  - shows what is on disk now rather than a status code;
+ *  - offers reload as a choice the person makes, never as something that
+ *    happens to their typing.
+ *
+ * A save is never retried automatically. Overwriting someone's work silently is
+ * the failure this guard exists to prevent, and a retry is exactly that.
+ */
+export function EpisodeTextEditor({
+  file,
+  loaded,
+  onSave,
+  onReload,
+  readOnly = false,
+  theme = DEFAULT_THEME,
+  className,
+  style,
+}: EpisodeTextEditorProps) {
+  const [draft, setDraft] = useState(loaded.content)
+  const [baseRevision, setBaseRevision] = useState(loaded.revision.sha256)
+  const [state, setState] = useState<"idle" | "saving" | "saved" | "conflict" | "error">("idle")
+  const [message, setMessage] = useState<string>("")
+  const [theirRevision, setTheirRevision] = useState<FileRevisionView | null>(null)
+  const fileRef = useRef(file)
+
+  // A different file is a different draft; the same file re-read is a new base.
+  useEffect(() => {
+    if (fileRef.current !== file) {
+      fileRef.current = file
+      setDraft(loaded.content)
+      setBaseRevision(loaded.revision.sha256)
+      setState("idle")
+      setMessage("")
+      setTheirRevision(null)
+      return
+    }
+    if (loaded.revision.sha256 !== baseRevision && state !== "conflict") {
+      setDraft(loaded.content)
+      setBaseRevision(loaded.revision.sha256)
+    }
+  }, [file, loaded, baseRevision, state])
+
+  const dirty = draft !== loaded.content || state === "conflict"
+
+  const save = async () => {
+    setState("saving")
+    setMessage("")
+    try {
+      const outcome = await onSave(draft, baseRevision)
+      if (outcome.ok) {
+        setState("saved")
+        setMessage(outcome.message ?? "Saved.")
+        setTheirRevision(null)
+        return
+      }
+      if (outcome.conflict) {
+        setState("conflict")
+        setTheirRevision(outcome.conflict.currentRevision)
+        setMessage(
+          outcome.message ??
+            "This file changed on disk while you were writing. Nothing was overwritten and your draft is still here.",
+        )
+        return
+      }
+      setState("error")
+      setMessage(outcome.message ?? "It could not be saved.")
+    } catch (error) {
+      setState("error")
+      setMessage(error instanceof Error ? error.message : "It could not be saved.")
+    }
+  }
+
+  const reload = () => {
+    setState("idle")
+    setMessage("")
+    setTheirRevision(null)
+    onReload?.()
+  }
+
+  return (
+    <section
+      className={["episode-text-editor", className].filter(Boolean).join(" ")}
+      style={{ ...themeVars(theme), ...style } as CSSProperties}
+      aria-label={`Editing ${file}`}
+    >
+      <header className="episode-text-editor-head">
+        <span className="episode-text-editor-file">{file}</span>
+        <span className={`episode-text-editor-state is-${state}`} role="status" aria-live="polite">
+          {state === "saving" && "Saving…"}
+          {state === "saved" && "Saved"}
+          {state === "conflict" && "Changed on disk"}
+          {state === "error" && "Not saved"}
+          {state === "idle" && (dirty ? "Unsaved changes" : "Up to date")}
+        </span>
+      </header>
+
+      {message && (
+        <p className={`episode-text-editor-message is-${state}`}>
+          {message}
+          {theirRevision && (
+            <span className="episode-text-editor-their-revision">
+              {" "}
+              On disk now: {theirRevision.bytes} bytes, {theirRevision.modifiedAt}.
+            </span>
+          )}
+        </p>
+      )}
+
+      <textarea
+        className="episode-text-editor-field"
+        value={draft}
+        readOnly={readOnly}
+        spellCheck={false}
+        aria-label={`Contents of ${file}`}
+        onChange={(event) => {
+          setDraft(event.target.value)
+          if (state === "saved" || state === "error") setState("idle")
+        }}
+      />
+
+      {!readOnly && (
+        <div className="episode-text-editor-actions">
+          <button type="button" className="episode-text-editor-save" disabled={state === "saving" || !dirty} onClick={save}>
+            Save
+          </button>
+          {state === "conflict" && onReload && (
+            <button type="button" className="episode-text-editor-reload" onClick={reload}>
+              Discard my draft and reload
+            </button>
+          )}
+        </div>
+      )}
+    </section>
+  )
+}
+
+export interface EpisodeTextViewerProps {
+  file: string
+  loaded: EpisodeTextView
+  /**
+   * How to render markdown. The package ships no markdown engine: Miadi
+   * already renders with `react-markdown`, gmtermux with `marked` +
+   * `sanitize-html`, and a second one would be a second sanitisation boundary.
+   * Omit it and the source is shown as-is, which is always safe.
+   */
+  renderMarkdown?: (source: string) => ReactNode
+  theme?: EpisodeUITheme
+  className?: string
+  style?: CSSProperties
+}
+
+/** Read one text artefact — rendered when the host supplies a renderer, else source. */
+export function EpisodeTextViewer({
+  file,
+  loaded,
+  renderMarkdown,
+  theme = DEFAULT_THEME,
+  className,
+  style,
+}: EpisodeTextViewerProps) {
+  const isMarkdown = loaded.contentType === ".md"
+  const [rich, setRich] = useState(Boolean(renderMarkdown) && isMarkdown)
+
+  return (
+    <section
+      className={["episode-text-viewer", className].filter(Boolean).join(" ")}
+      style={{ ...themeVars(theme), ...style } as CSSProperties}
+      aria-label={`Reading ${file}`}
+    >
+      <header className="episode-text-viewer-head">
+        <span className="episode-text-viewer-file">{file}</span>
+        {renderMarkdown && isMarkdown && (
+          <button type="button" className="episode-text-viewer-toggle" onClick={() => setRich((value) => !value)}>
+            {rich ? "Source" : "Rendered"}
+          </button>
+        )}
+      </header>
+      {rich && renderMarkdown ? (
+        <div className="episode-text-viewer-rich">{renderMarkdown(loaded.content)}</div>
+      ) : (
+        <pre className="episode-text-viewer-source">{loaded.content}</pre>
+      )}
+    </section>
+  )
+}

package/src/types.ts

@@ -0,0 +1,125 @@
+/**
+ * The shapes these components take in.
+ *
+ * They are re-declared structurally rather than imported from
+ * `@miadi/episode-vessel` at runtime: a browser bundle must not pull `node:fs`
+ * in, and a host that reaches a vessel over HTTP receives JSON, not the
+ * package's classes. The vessel package is a type-only dependency here, and the
+ * two definitions are kept honest by `test/contract.test.mjs`.
+ */
+
+export type FileKind = "text" | "document" | "media"
+
+export interface EpisodeFileView {
+  relativePath: string
+  name: string
+  kind: FileKind
+  size: number
+  modifiedAt: string
+  previewable: boolean
+  editable: boolean
+  guidance: boolean
+}
+
+export interface FileRevisionView {
+  sha256: string
+  modifiedAt: string
+  bytes: number
+}
+
+export interface EpisodeTextView {
+  content: string
+  contentType: string
+  size: number
+  revision: FileRevisionView
+}
+
+export interface EpisodeCapabilitiesView {
+  browse: boolean
+  read: boolean
+  edit: boolean
+  upload: boolean
+  attachCapture: boolean
+  writeCeremonyNote: boolean
+  attachToCeremony: boolean
+}
+
+export interface CeremonyAttachmentView {
+  relativePath: string
+  attachedBy: string
+  attachedAt: string
+  note?: string
+}
+
+export interface EpisodeShelfEntry {
+  episodePath: string
+  number: number
+  numberLabel: string
+  title: string
+  date: string
+  goal?: string
+  status?: string
+  /** True when the medicine wheel also holds this episode. */
+  registered?: boolean
+}
+
+/** Colours and fonts the host already has. Every component takes the same set. */
+export interface EpisodeUITheme {
+  background: string
+  card: string
+  text: string
+  textDim: string
+  muted: string
+  accent: string
+  border: string
+  success: string
+  warning: string
+  mono: string
+}
+
+export const DEFAULT_THEME: EpisodeUITheme = {
+  background: "#0d0f12",
+  card: "#15181d",
+  text: "#e8e6e1",
+  textDim: "#b3afa6",
+  muted: "#7d7a72",
+  accent: "#ffd700",
+  border: "#2a2e35",
+  success: "#5ac37d",
+  warning: "#e0a458",
+  mono: "ui-monospace, SFMono-Regular, Menlo, monospace",
+}
+
+export function themeVars(theme: EpisodeUITheme): Record<string, string> {
+  return {
+    "--episode-bg": theme.background,
+    "--episode-card": theme.card,
+    "--episode-text": theme.text,
+    "--episode-text-dim": theme.textDim,
+    "--episode-muted": theme.muted,
+    "--episode-accent": theme.accent,
+    "--episode-border": theme.border,
+    "--episode-success": theme.success,
+    "--episode-warning": theme.warning,
+    "--episode-mono": theme.mono,
+  }
+}
+
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return ""
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+}
+
+export function iconFor(file: { name: string; kind: FileKind }): string {
+  const extension = /\.([^.]+)$/.exec(file.name)?.[1]?.toLowerCase() ?? ""
+  if (["m4a", "mp3", "wav", "opus", "aac", "amr", "ogg"].includes(extension)) return "🎙"
+  if (["mp4", "webm", "mov"].includes(extension)) return "🎬"
+  if (extension === "mid") return "🎹"
+  if (extension === "md") return "📘"
+  if (["json", "yaml", "yml"].includes(extension)) return "🧾"
+  if (["html", "htm"].includes(extension)) return "🖼"
+  if (extension === "pdf") return "📕"
+  return "📄"
+}