@miadi/episode-ui 0.1.0

package/src/episode-ui.css

@@ -0,0 +1,400 @@
+/**
+ * One stylesheet, plain class names, every colour a custom property the host
+ * sets through `themeVars(theme)`. A surface that wants a different look
+ * overrides the properties or the classes; nothing here is !important and
+ * nothing assumes a framework.
+ *
+ * Touch targets are 40px because the first surface this runs on is a phone.
+ */
+
+.episode-file-browser,
+.episode-text-editor,
+.episode-text-viewer,
+.ceremony-note-editor,
+.ceremony-attachments,
+.episode-shelf {
+  color: var(--episode-text);
+  font-size: 13px;
+  line-height: 1.5;
+}
+
+/* ---------- file browser ---------- */
+
+.episode-file-browser-head {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 8px;
+}
+
+.episode-file-browser-title {
+  margin: 0;
+  font-size: 13px;
+  font-weight: 800;
+  letter-spacing: 0.02em;
+  text-transform: uppercase;
+  color: var(--episode-text-dim);
+}
+
+.episode-file-browser-count,
+.episode-shelf-count {
+  font-family: var(--episode-mono);
+  font-size: 11px;
+  color: var(--episode-muted);
+}
+
+.episode-file-browser-filter,
+.episode-shelf-filter {
+  width: 100%;
+  min-height: 40px;
+  padding: 8px 10px;
+  margin-bottom: 8px;
+  background: var(--episode-bg);
+  color: var(--episode-text);
+  border: 1px solid var(--episode-border);
+  border-radius: 8px;
+  font: inherit;
+}
+
+.episode-file-browser-list,
+.episode-shelf-list,
+.ceremony-attachments-list {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.episode-file-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+
+.episode-file-open {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  min-height: 40px;
+  padding: 6px 9px;
+  background: transparent;
+  color: inherit;
+  border: 1px solid transparent;
+  border-radius: 7px;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.episode-file-open:hover:not(:disabled),
+.episode-shelf-entry:hover {
+  background: var(--episode-card);
+  border-color: var(--episode-border);
+}
+
+.episode-file-open:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
+
+.episode-file-row.is-selected .episode-file-open {
+  background: var(--episode-card);
+  border-color: var(--episode-accent);
+}
+
+.episode-file-row.is-guidance .episode-file-name {
+  color: var(--episode-muted);
+}
+
+.episode-file-icon {
+  flex: none;
+  font-size: 14px;
+}
+
+.episode-file-name {
+  flex: 1;
+  overflow-wrap: anywhere;
+}
+
+.episode-file-meta,
+.ceremony-attachment-meta {
+  flex: none;
+  font-family: var(--episode-mono);
+  font-size: 10.5px;
+  color: var(--episode-muted);
+}
+
+.episode-file-attach,
+.ceremony-attachment-detach,
+.episode-text-viewer-toggle {
+  min-height: 40px;
+  padding: 4px 10px;
+  background: transparent;
+  color: var(--episode-text-dim);
+  border: 1px solid var(--episode-border);
+  border-radius: 999px;
+  font-family: var(--episode-mono);
+  font-size: 10.5px;
+  cursor: pointer;
+}
+
+.episode-file-attach[aria-pressed="true"] {
+  color: var(--episode-accent);
+  border-color: var(--episode-accent);
+}
+
+.episode-file-browser-empty,
+.ceremony-attachments-empty,
+.episode-file-browser-notice {
+  margin: 6px 0 0;
+  color: var(--episode-muted);
+  font-size: 12px;
+}
+
+/* ---------- text editor and viewer ---------- */
+
+.episode-text-editor,
+.episode-text-viewer {
+  border: 1px solid var(--episode-border);
+  border-radius: 10px;
+  background: var(--episode-card);
+  padding: 10px 12px;
+}
+
+.episode-text-editor-head,
+.episode-text-viewer-head,
+.ceremony-note-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-bottom: 8px;
+}
+
+.episode-text-editor-file,
+.episode-text-viewer-file {
+  font-family: var(--episode-mono);
+  font-size: 11.5px;
+  color: var(--episode-text-dim);
+  overflow-wrap: anywhere;
+}
+
+.episode-text-editor-state {
+  flex: none;
+  font-family: var(--episode-mono);
+  font-size: 10.5px;
+  color: var(--episode-muted);
+}
+
+.episode-text-editor-state.is-saved {
+  color: var(--episode-success);
+}
+
+.episode-text-editor-state.is-conflict,
+.episode-text-editor-state.is-error {
+  color: var(--episode-warning);
+}
+
+.episode-text-editor-message {
+  margin: 0 0 8px;
+  padding: 8px 10px;
+  border-radius: 8px;
+  font-size: 12px;
+  background: var(--episode-bg);
+  border: 1px solid var(--episode-border);
+}
+
+.episode-text-editor-message.is-conflict,
+.episode-text-editor-message.is-error {
+  border-color: var(--episode-warning);
+}
+
+.episode-text-editor-their-revision {
+  color: var(--episode-muted);
+  font-family: var(--episode-mono);
+  font-size: 11px;
+}
+
+.episode-text-editor-field,
+.ceremony-note-field {
+  width: 100%;
+  min-height: 220px;
+  padding: 10px;
+  background: var(--episode-bg);
+  color: var(--episode-text);
+  border: 1px solid var(--episode-border);
+  border-radius: 8px;
+  font-family: var(--episode-mono);
+  font-size: 12.5px;
+  line-height: 1.6;
+  resize: vertical;
+}
+
+.episode-text-editor-actions,
+.ceremony-note-actions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  margin-top: 8px;
+  flex-wrap: wrap;
+}
+
+.episode-text-editor-actions button,
+.ceremony-note-actions button {
+  min-height: 40px;
+  padding: 6px 14px;
+  background: var(--episode-accent);
+  color: #1a1a1a;
+  border: none;
+  border-radius: 8px;
+  font: inherit;
+  font-weight: 700;
+  cursor: pointer;
+}
+
+.episode-text-editor-actions button:disabled,
+.ceremony-note-actions button:disabled {
+  opacity: 0.45;
+  cursor: default;
+}
+
+.episode-text-editor-reload {
+  background: transparent !important;
+  color: var(--episode-warning) !important;
+  border: 1px solid var(--episode-warning) !important;
+  font-weight: 400 !important;
+}
+
+.episode-text-viewer-source {
+  margin: 0;
+  max-height: 60vh;
+  overflow: auto;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font-family: var(--episode-mono);
+  font-size: 12.5px;
+  color: var(--episode-text-dim);
+}
+
+.episode-text-viewer-rich {
+  font-size: 14px;
+  line-height: 1.65;
+}
+
+/* ---------- ceremony ---------- */
+
+.ceremony-note-label {
+  font-size: 12px;
+  font-weight: 700;
+  color: var(--episode-text-dim);
+}
+
+.ceremony-note-state {
+  font-family: var(--episode-mono);
+  font-size: 10.5px;
+  color: var(--episode-muted);
+}
+
+.ceremony-note-state.is-saved {
+  color: var(--episode-success);
+}
+
+.ceremony-note-message.is-error {
+  color: var(--episode-warning);
+}
+
+.ceremony-attachments {
+  margin-top: 10px;
+}
+
+.ceremony-attachments-title {
+  display: block;
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.03em;
+  text-transform: uppercase;
+  color: var(--episode-muted);
+  margin-bottom: 5px;
+}
+
+.ceremony-attachment {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.ceremony-attachment-open {
+  min-height: 40px;
+  padding: 2px 0;
+  background: none;
+  border: none;
+  color: var(--episode-accent);
+  font-family: var(--episode-mono);
+  font-size: 12px;
+  text-align: left;
+  cursor: pointer;
+  overflow-wrap: anywhere;
+}
+
+.ceremony-attachment-open:disabled {
+  color: var(--episode-text-dim);
+  cursor: default;
+}
+
+.ceremony-attachment-note {
+  width: 100%;
+  color: var(--episode-text-dim);
+  font-size: 12px;
+}
+
+/* ---------- shelf ---------- */
+
+.episode-shelf-entry {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  width: 100%;
+  min-height: 40px;
+  padding: 8px 10px;
+  background: transparent;
+  color: inherit;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+}
+
+.episode-shelf-number {
+  flex: none;
+  font-family: var(--episode-mono);
+  font-weight: 700;
+  color: var(--episode-accent);
+}
+
+.episode-shelf-body {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.episode-shelf-body small {
+  font-family: var(--episode-mono);
+  font-size: 10.5px;
+  color: var(--episode-muted);
+}
+
+.episode-file-open:focus-visible,
+.episode-file-attach:focus-visible,
+.episode-shelf-entry:focus-visible,
+.ceremony-attachment-open:focus-visible,
+.episode-text-editor-actions button:focus-visible,
+.ceremony-note-actions button:focus-visible {
+  outline: 2px solid var(--episode-accent);
+  outline-offset: 2px;
+}

package/src/file-browser.tsx

@@ -0,0 +1,154 @@
+"use client"
+
+import { useMemo, useState } from "react"
+import type { CSSProperties } from "react"
+import {
+  DEFAULT_THEME,
+  formatBytes,
+  iconFor,
+  themeVars,
+  type EpisodeCapabilitiesView,
+  type EpisodeFileView,
+  type EpisodeUITheme,
+} from "./types.js"
+
+export interface EpisodeFileBrowserProps {
+  files: EpisodeFileView[]
+  capabilities: EpisodeCapabilitiesView
+  /** The file currently open, by `relativePath`. */
+  selected?: string | null
+  onSelect?: (file: EpisodeFileView) => void
+  /** Offered per file when the caller can act on a ceremony. */
+  onAttach?: (file: EpisodeFileView) => void
+  /** Already attached to the ceremony in context, by `relativePath`. */
+  attached?: string[]
+  theme?: EpisodeUITheme
+  title?: string
+  /** Shown when the vessel holds no listable file. */
+  emptyLabel?: string
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * The files in one vessel, as a list a person can act on.
+ *
+ * It fetches nothing. The host lists the files and says what this person may
+ * do; the browser decides only what to show and raises intent. A capability
+ * that is absent removes its control rather than disabling it — a button a
+ * person can never press is noise, not information.
+ */
+export function EpisodeFileBrowser({
+  files,
+  capabilities,
+  selected = null,
+  onSelect,
+  onAttach,
+  attached = [],
+  theme = DEFAULT_THEME,
+  title = "Files in this episode",
+  emptyLabel = "This episode folder holds no readable file yet.",
+  className,
+  style,
+}: EpisodeFileBrowserProps) {
+  const [query, setQuery] = useState("")
+
+  const shown = useMemo(() => {
+    const needle = query.trim().toLowerCase()
+    if (!needle) return files
+    return files.filter((file) => file.relativePath.toLowerCase().includes(needle))
+  }, [files, query])
+
+  if (!capabilities.browse) return null
+
+  const attachedSet = new Set(attached)
+
+  return (
+    <section
+      className={["episode-file-browser", className].filter(Boolean).join(" ")}
+      style={{ ...themeVars(theme), ...style } as CSSProperties}
+      aria-label={title}
+    >
+      <header className="episode-file-browser-head">
+        <h3 className="episode-file-browser-title">{title}</h3>
+        <span className="episode-file-browser-count">
+          {files.length} {files.length === 1 ? "file" : "files"}
+        </span>
+      </header>
+
+      {files.length > 6 && (
+        <input
+          className="episode-file-browser-filter"
+          type="search"
+          value={query}
+          placeholder="Filter by name"
+          aria-label="Filter files"
+          onChange={(event) => setQuery(event.target.value)}
+        />
+      )}
+
+      {files.length === 0 ? (
+        <p className="episode-file-browser-empty">{emptyLabel}</p>
+      ) : (
+        <ul className="episode-file-browser-list">
+          {shown.map((file) => {
+            const isSelected = file.relativePath === selected
+            const canOpen = capabilities.read && (file.previewable || file.kind !== "text")
+            return (
+              <li
+                key={file.relativePath}
+                className={[
+                  "episode-file-row",
+                  isSelected ? "is-selected" : "",
+                  file.guidance ? "is-guidance" : "",
+                ]
+                  .filter(Boolean)
+                  .join(" ")}
+              >
+                <button
+                  type="button"
+                  className="episode-file-open"
+                  disabled={!canOpen}
+                  aria-current={isSelected ? "true" : undefined}
+                  onClick={() => onSelect?.(file)}
+                >
+                  <span className="episode-file-icon" aria-hidden="true">
+                    {iconFor(file)}
+                  </span>
+                  <span className="episode-file-name">{file.relativePath}</span>
+                  <span className="episode-file-meta">
+                    {formatBytes(file.size)}
+                    {file.editable && capabilities.edit ? " · editable" : ""}
+                    {file.kind === "document" ? " · download" : ""}
+                    {file.guidance ? " · guidance" : ""}
+                  </span>
+                </button>
+                {onAttach && capabilities.attachToCeremony && (
+                  <button
+                    type="button"
+                    className="episode-file-attach"
+                    aria-pressed={attachedSet.has(file.relativePath)}
+                    title={
+                      attachedSet.has(file.relativePath)
+                        ? "On this ceremony's table"
+                        : "Name this file as being on the ceremony's table"
+                    }
+                    onClick={() => onAttach(file)}
+                  >
+                    {attachedSet.has(file.relativePath) ? "on the table" : "attach"}
+                  </button>
+                )}
+              </li>
+            )
+          })}
+        </ul>
+      )}
+
+      {!capabilities.read && (
+        <p className="episode-file-browser-notice">
+          Sign in to read these files. What is here is listed for everyone; what it says is not.
+        </p>
+      )}
+    </section>
+  )
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * @miadi/episode-ui — the episode-vessel experience, as React.
+ *
+ * gmtermux proved this experience on a phone in vanilla JS
+ * (`web/lib/file-browser.js`, `web/lib/fullscreen-editor.js`,
+ * `web/lib/episode-shelf-filter.js`) where no React surface could reach it. The
+ * Miadi episode room meanwhile rendered its files as text it could not open.
+ * These components are that experience in a form both can hold.
+ *
+ * The contract, in one line: **data and callbacks in, intent out.** No
+ * component fetches, holds a URL or token, knows a chronicle root, or decides
+ * what a person is allowed to do. The host resolves capabilities (see
+ * `@miadi/episode-vessel/permissions`) and remains the authority; a capability
+ * here decides only what is offered.
+ *
+ * Styles are one stylesheet of plain classes over CSS custom properties:
+ * `import "@miadi/episode-ui/styles.css"`, or write your own against the same
+ * class names.
+ */
+
+export { EpisodeFileBrowser, type EpisodeFileBrowserProps } from "./file-browser.js"
+export {
+  EpisodeTextEditor,
+  EpisodeTextViewer,
+  type EpisodeTextEditorProps,
+  type EpisodeTextViewerProps,
+  type SaveOutcome,
+} from "./text-editor.js"
+export {
+  CeremonyNoteEditor,
+  CeremonyAttachments,
+  type CeremonyNoteEditorProps,
+  type CeremonyAttachmentsProps,
+} from "./ceremony.js"
+export { EpisodeShelfFilter, type EpisodeShelfFilterProps } from "./shelf-filter.js"
+export {
+  DEFAULT_THEME,
+  themeVars,
+  formatBytes,
+  iconFor,
+  type FileKind,
+  type EpisodeFileView,
+  type FileRevisionView,
+  type EpisodeTextView,
+  type EpisodeCapabilitiesView,
+  type CeremonyAttachmentView,
+  type EpisodeShelfEntry,
+  type EpisodeUITheme,
+} from "./types.js"

package/src/shelf-filter.tsx

@@ -0,0 +1,98 @@
+"use client"
+
+import { useMemo, useState } from "react"
+import type { CSSProperties } from "react"
+import { DEFAULT_THEME, themeVars, type EpisodeShelfEntry, type EpisodeUITheme } from "./types.js"
+
+export interface EpisodeShelfFilterProps {
+  episodes: EpisodeShelfEntry[]
+  selected?: string | null
+  onSelect?: (episode: EpisodeShelfEntry) => void
+  /** Render each entry yourself when the host has its own card. */
+  renderEntry?: (episode: EpisodeShelfEntry, selected: boolean) => React.ReactNode
+  placeholder?: string
+  theme?: EpisodeUITheme
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Find an episode by number, title or slug.
+ *
+ * `349`, `ep349`, `episode 349` and a word from the title all reach the same
+ * vessel — on a phone, typing the number is the fastest way there, and it was
+ * the first thing gmtermux's shelf learned.
+ */
+export function EpisodeShelfFilter({
+  episodes,
+  selected = null,
+  onSelect,
+  renderEntry,
+  placeholder = "Find an episode by number or title",
+  theme = DEFAULT_THEME,
+  className,
+  style,
+}: EpisodeShelfFilterProps) {
+  const [query, setQuery] = useState("")
+
+  const shown = useMemo(() => {
+    const needle = query.trim().toLowerCase().replace(/^(?:ep(?:isode)?\s*)/, "")
+    if (!needle) return episodes
+    return episodes.filter((episode) =>
+      [
+        String(episode.number),
+        episode.numberLabel,
+        episode.title,
+        episode.episodePath,
+        episode.goal ?? "",
+      ]
+        .join(" ")
+        .toLowerCase()
+        .includes(needle),
+    )
+  }, [episodes, query])
+
+  return (
+    <div
+      className={["episode-shelf", className].filter(Boolean).join(" ")}
+      style={{ ...themeVars(theme), ...style } as CSSProperties}
+    >
+      <input
+        className="episode-shelf-filter"
+        type="search"
+        value={query}
+        placeholder={placeholder}
+        aria-label={placeholder}
+        onChange={(event) => setQuery(event.target.value)}
+      />
+      <span className="episode-shelf-count">
+        {shown.length} of {episodes.length}
+      </span>
+      <ul className="episode-shelf-list">
+        {shown.map((episode) => {
+          const isSelected = episode.episodePath === selected
+          return (
+            <li key={episode.episodePath} className={isSelected ? "is-selected" : undefined}>
+              {renderEntry ? (
+                renderEntry(episode, isSelected)
+              ) : (
+                <button type="button" className="episode-shelf-entry" onClick={() => onSelect?.(episode)}>
+                  <span className="episode-shelf-number">{episode.numberLabel}</span>
+                  <span className="episode-shelf-body">
+                    <strong>{episode.title}</strong>
+                    {episode.goal && <span>{episode.goal}</span>}
+                    <small>
+                      {episode.date}
+                      {episode.status ? ` · ${episode.status}` : ""}
+                      {episode.registered === false ? " · vessel only" : ""}
+                    </small>
+                  </span>
+                </button>
+              )}
+            </li>
+          )
+        })}
+      </ul>
+    </div>
+  )
+}