@open-press/core 0.7.1 → 1.0.0

package/src/openpress/workbench/inspector/useInspectorComments.ts

@@ -0,0 +1,254 @@
+import { useCallback, useEffect, useMemo, useState, type FormEvent, type RefObject } from "react";
+import type { SourceBlock } from "../../document-model";
+import type { InlineSavedComment, InspectorCommentStatus, PendingCommentsStatus } from "../workbenchTypes";
+import { formatInspectorCommentStatus } from "../workbenchFormatters";
+import { clearInspectorComment, fetchInspectorComments } from "./inspectorModel";
+import { createInspectorCommentDraft, submitInspectorComment, updateInspectorComment } from "./inspectorModel";
+import type { InspectorState, PendingComment } from "./inspectorModel";
+import { getInlineSavedCommentForTarget, resolveInlineSavedComment } from "./inlineCommentModel";
+
+export interface UseInspectorCommentsOptions {
+  devMode: boolean;
+  inspector: InspectorState;
+  sourceBlockMap: Record<string, SourceBlock>;
+  sourceBlocksByPath: Record<string, SourceBlock[]>;
+  sourceContainerRef: RefObject<HTMLDivElement | null>;
+  onSelectWorkspacePage: (pageIndex: number, options?: { behavior?: ScrollBehavior }) => void;
+}
+
+export interface InspectorComments {
+  pendingComments: PendingComment[];
+  commentsStatus: PendingCommentsStatus;
+  commentsError: string;
+  inspectorCommentText: string;
+  inspectorCommentStatus: InspectorCommentStatus;
+  inspectorCommentStatusMessage: string;
+  inspectorCommentDisabled: boolean;
+  inlineSavedComments: InlineSavedComment[];
+  activeInlineSavedComment: InlineSavedComment | null;
+  setInspectorCommentText: (value: string) => void;
+  refreshPendingComments: () => Promise<void>;
+  clearPendingComment: (id: string) => Promise<void>;
+  handleSubmitInspectorComment: (event?: FormEvent<HTMLFormElement>) => Promise<void>;
+  handleOpenInlineSavedComment: (comment: InlineSavedComment) => void;
+  handleRemoveInlineSavedComment: (comment: InlineSavedComment) => Promise<void>;
+  handleSelectPendingComment: (comment: PendingComment) => void;
+}
+
+export function useInspectorComments({
+  devMode,
+  inspector,
+  sourceBlockMap,
+  sourceBlocksByPath,
+  sourceContainerRef,
+  onSelectWorkspacePage,
+}: UseInspectorCommentsOptions): InspectorComments {
+  const [inspectorCommentText, setInspectorCommentText] = useState("");
+  const [inspectorCommentStatus, setInspectorCommentStatus] = useState<InspectorCommentStatus>("idle");
+  const [inspectorCommentError, setInspectorCommentError] = useState("");
+  const [inlineSavedCommentId, setInlineSavedCommentId] = useState<string | null>(null);
+  const [pendingComments, setPendingComments] = useState<PendingComment[]>([]);
+  const [commentsStatus, setCommentsStatus] = useState<PendingCommentsStatus>("idle");
+  const [commentsError, setCommentsError] = useState("");
+
+  const inlineSavedComments = useMemo(
+    () => pendingComments.flatMap((comment, index) => (
+      resolveInlineSavedComment(comment, sourceBlocksByPath)
+        .map((inlineComment) => ({ ...inlineComment, markerLabel: String(index + 1) }))
+    )),
+    [pendingComments, sourceBlocksByPath],
+  );
+
+  const activeInlineSavedComment = getInlineSavedCommentForTarget(
+    inlineSavedComments,
+    inspector.selectedTarget,
+    inlineSavedCommentId,
+  );
+
+  const inspectorCommentDisabled =
+    !inspector.selectedBlock || !inspectorCommentText.trim() || inspectorCommentStatus === "submitting";
+  // Memoize the status message so its identity is stable while only
+  // composer text changes — the toolbar and other consumers that depend
+  // on it can then memoize without keystrokes invalidating their cache.
+  const inspectorCommentStatusMessage = useMemo(
+    () => formatInspectorCommentStatus(inspectorCommentStatus, inspectorCommentError),
+    [inspectorCommentStatus, inspectorCommentError],
+  );
+
+  const refreshPendingComments = useCallback(async () => {
+    if (!devMode) return;
+    setCommentsStatus("loading");
+    setCommentsError("");
+    try {
+      const comments = await fetchInspectorComments();
+      setPendingComments(comments);
+      setCommentsStatus("ready");
+    } catch (error) {
+      setCommentsStatus("failed");
+      setCommentsError(error instanceof Error ? error.message : String(error));
+    }
+  }, [devMode]);
+
+  const clearPendingComment = useCallback(async (id: string) => {
+    setCommentsStatus("clearing");
+    setCommentsError("");
+    try {
+      await clearInspectorComment({ id });
+      setPendingComments((comments) => comments.filter((comment) => comment.id !== id));
+      setInlineSavedCommentId((currentId) => (currentId === id ? null : currentId));
+      setCommentsStatus("ready");
+    } catch (error) {
+      setCommentsStatus("failed");
+      setCommentsError(error instanceof Error ? error.message : String(error));
+    }
+  }, []);
+
+  const handleSubmitInspectorComment = useCallback(async (event?: FormEvent<HTMLFormElement>) => {
+    event?.preventDefault();
+    if (inspectorCommentDisabled || !inspector.selectedBlock) return;
+    setInspectorCommentStatus("submitting");
+    setInspectorCommentError("");
+    try {
+      const note = inspectorCommentText.trim();
+      const placement = inspector.selectedTarget?.placement ?? "block";
+      if (activeInlineSavedComment) {
+        const result = await updateInspectorComment({
+          id: activeInlineSavedComment.id,
+          note,
+          placement,
+        });
+        setInlineSavedCommentId(result.comment?.id ?? activeInlineSavedComment.id);
+      } else {
+        const draft = createInspectorCommentDraft({
+          block: inspector.selectedBlock,
+          entity: inspector.selectedObjectEntity,
+          target: inspector.selectedTarget,
+          note,
+          placement,
+        });
+        const result = await submitInspectorComment({ draft });
+        if (result.comment?.id) {
+          setInlineSavedCommentId(result.comment.id);
+        }
+      }
+      setInspectorCommentText("");
+      setInspectorCommentStatus("saved");
+      void refreshPendingComments();
+    } catch (error) {
+      setInspectorCommentStatus("failed");
+      setInspectorCommentError(error instanceof Error ? error.message : String(error));
+    }
+  }, [
+    activeInlineSavedComment,
+    inspector.selectedBlock,
+    inspector.selectedObjectEntity,
+    inspector.selectedTarget,
+    inspector.selectedTarget?.placement,
+    inspectorCommentDisabled,
+    inspectorCommentText,
+    refreshPendingComments,
+  ]);
+
+  const handleOpenInlineSavedComment = useCallback((comment: InlineSavedComment) => {
+    setInlineSavedCommentId(comment.id);
+    setInspectorCommentText(comment.note);
+    setInspectorCommentStatus("idle");
+    setInspectorCommentError("");
+  }, []);
+
+  const handleRemoveInlineSavedComment = useCallback(async (comment: InlineSavedComment) => {
+    setInspectorCommentStatus("submitting");
+    setInspectorCommentError("");
+    try {
+      await clearInspectorComment({ id: comment.id });
+      setPendingComments((comments) => comments.filter((item) => item.id !== comment.id));
+      setInlineSavedCommentId((currentId) => (currentId === comment.id ? null : currentId));
+      setInspectorCommentText("");
+      setInspectorCommentStatus("idle");
+      inspector.selectTarget(null);
+      void refreshPendingComments();
+    } catch (error) {
+      setInspectorCommentStatus("failed");
+      setInspectorCommentError(error instanceof Error ? error.message : String(error));
+    }
+  }, [inspector, refreshPendingComments]);
+
+  const handleSelectPendingComment = useCallback((comment: PendingComment) => {
+    const inlineComment = inlineSavedComments.find((item) => item.id === comment.id)
+      ?? resolveInlineSavedComment(comment, sourceBlocksByPath)[0];
+    if (!inlineComment?.blockId) return;
+
+    const sourceBlock = sourceBlockMap[inlineComment.blockId];
+    if (typeof sourceBlock?.pageIndex === "number") {
+      onSelectWorkspacePage(sourceBlock.pageIndex, { behavior: "smooth" });
+    }
+
+    inspector.selectSelection({
+      objectId: inlineComment.objectId,
+      blockId: inlineComment.blockId,
+      placement: inlineComment.placement,
+    });
+    handleOpenInlineSavedComment(inlineComment);
+
+    window.requestAnimationFrame(() => {
+      const selector = inlineComment.objectId
+        ? `[data-openpress-object-id="${cssEscape(inlineComment.objectId)}"]`
+        : `[data-openpress-block-id="${cssEscape(inlineComment.blockId!)}"]`;
+      sourceContainerRef.current?.querySelector<HTMLElement>(selector)?.scrollIntoView({
+        behavior: "smooth",
+        block: "center",
+      });
+    });
+  }, [
+    handleOpenInlineSavedComment,
+    inlineSavedComments,
+    inspector,
+    onSelectWorkspacePage,
+    sourceBlockMap,
+    sourceBlocksByPath,
+    sourceContainerRef,
+  ]);
+
+  // Reset composer state when the inspector selection changes.
+  useEffect(() => {
+    setInspectorCommentStatus("idle");
+    setInspectorCommentError("");
+    setInspectorCommentText("");
+  }, [inspector.selectedBlockId, inspector.selectedTarget?.placement]);
+
+  // Drop the inline saved id if its comment is no longer reachable.
+  useEffect(() => {
+    if (inlineSavedCommentId && !activeInlineSavedComment) {
+      setInlineSavedCommentId(null);
+    }
+  }, [activeInlineSavedComment, inlineSavedCommentId]);
+
+  // Initial + dev-mode refresh of pending comments.
+  useEffect(() => {
+    if (!devMode) return;
+    void refreshPendingComments();
+  }, [devMode, refreshPendingComments]);
+
+  return {
+    pendingComments,
+    commentsStatus,
+    commentsError,
+    inspectorCommentText,
+    inspectorCommentStatus,
+    inspectorCommentStatusMessage,
+    inspectorCommentDisabled,
+    inlineSavedComments,
+    activeInlineSavedComment,
+    setInspectorCommentText,
+    refreshPendingComments,
+    clearPendingComment,
+    handleSubmitInspectorComment,
+    handleOpenInlineSavedComment,
+    handleRemoveInlineSavedComment,
+    handleSelectPendingComment,
+  };
+}
+
+function cssEscape(value: string) {
+  return globalThis.CSS?.escape ? globalThis.CSS.escape(value) : value.replace(/["\\]/g, "\\$&");
+}

package/src/openpress/workbench/mentions/MentionSuggestionList.tsx

@@ -0,0 +1,41 @@
+import type { ComposerMentionItem } from "./useComposerMentions";
+
+export interface MentionSuggestionListProps {
+  className: string;
+  suggestions: ComposerMentionItem[];
+  highlightedIndex: number;
+  ariaLabel: string;
+  onHighlight: (index: number) => void;
+  onSelect: (item: ComposerMentionItem) => void;
+}
+
+export function MentionSuggestionList({
+  className,
+  suggestions,
+  highlightedIndex,
+  ariaLabel,
+  onHighlight,
+  onSelect,
+}: MentionSuggestionListProps) {
+  if (suggestions.length === 0) return null;
+
+  return (
+    <div className={className} role="listbox" aria-label={ariaLabel}>
+      {suggestions.map((item, index) => (
+        <button
+          type="button"
+          role="option"
+          aria-selected={index === highlightedIndex}
+          data-highlighted={index === highlightedIndex ? "true" : undefined}
+          key={`${item.kind}-${item.value}`}
+          onMouseDown={(event) => event.preventDefault()}
+          onMouseEnter={() => onHighlight(index)}
+          onClick={() => onSelect(item)}
+        >
+          <span>{item.label}</span>
+          <small>{item.meta}</small>
+        </button>
+      ))}
+    </div>
+  );
+}

package/src/openpress/workbench/mentions/index.ts

@@ -0,0 +1,2 @@
+export * from "./useComposerMentions";
+export * from "./MentionSuggestionList";

package/src/openpress/{composerMentions.ts → workbench/mentions/useComposerMentions.ts}

@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useState, type KeyboardEvent, type RefObject } from "react";
+import { clampNumber } from "../../shared";
 
 export type ComposerMentionItem = {
   trigger: "@" | "/";
@@ -176,10 +177,6 @@ function mentionMatches(item: ComposerMentionItem, query: string) {
     || item.meta.toLowerCase().includes(normalizedQuery);
 }
 
-function clampNumber(value: number, min: number, max: number) {
-  return Math.min(Math.max(value, min), Math.max(min, max));
-}
-
 const MENTION_PREFIX_DEFINITIONS: Array<{ kind: "media" | "chapter" | "section" | "component"; meta: string }> = [
   { kind: "media", meta: "prefix · images" },
   { kind: "chapter", meta: "prefix · chapters" },

package/src/openpress/workbench/panels/Panel.tsx

@@ -0,0 +1 @@
+export { Panel } from "../../shared/Panel";

package/src/openpress/workbench/panels/PendingCommentsPanel.tsx

@@ -0,0 +1,80 @@
+import { memo } from "react";
+import { Trash2 } from "lucide-react";
+import type { PendingComment } from "../inspector";
+import {
+  formatCommentTimestamp,
+  formatCommentsCount,
+} from "../workbenchFormatters";
+import type { PendingCommentsStatus } from "../workbenchTypes";
+import { Panel } from "./Panel";
+
+function PendingCommentsPanelImpl({
+  comments,
+  status,
+  error,
+  onClear,
+  onSelect,
+}: {
+  comments: PendingComment[];
+  status: PendingCommentsStatus;
+  error: string;
+  onClear: (id: string) => Promise<void>;
+  onSelect?: (comment: PendingComment) => void;
+}) {
+  const busy = status === "loading" || status === "clearing";
+
+  return (
+    <Panel
+      className="openpress-comments-panel openpress-comments-panel--embedded openpress-panel--compact"
+      data-openpress-comments-panel
+      aria-label="待處理註解"
+    >
+      <Panel.Header>
+        <div className="openpress-panel-heading-stack">
+          <Panel.Kicker>Comments</Panel.Kicker>
+          <Panel.Title>待處理註解</Panel.Title>
+          <Panel.Description>{formatCommentsCount(comments.length, status)}</Panel.Description>
+        </div>
+      </Panel.Header>
+
+      <Panel.Body>
+        {error ? <Panel.Error>{error}</Panel.Error> : null}
+
+        {comments.length === 0 && status !== "loading" ? (
+          <Panel.Empty role="status">目前沒有註解</Panel.Empty>
+        ) : (
+          <ol className="openpress-comments-list" aria-label="待處理註解列表">
+            {comments.map((comment) => (
+              <li className="openpress-comment-entry" data-openpress-comment-id={comment.id} key={comment.id}>
+                <button
+                  type="button"
+                  className="openpress-comment-entry__jump"
+                  onClick={() => onSelect?.(comment)}
+                  aria-label={`跳到註解 ${comment.id}`}
+                >
+                  <p className="openpress-comment-entry__note" title={comment.note}>{comment.note}</p>
+                  <p className="openpress-comment-entry__meta">
+                    <code>{comment.path}:{comment.line}</code>
+                    {comment.timestamp ? <span>{formatCommentTimestamp(comment.timestamp)}</span> : null}
+                  </p>
+                </button>
+                <button
+                  type="button"
+                  className="openpress-comment-entry__clear"
+                  onClick={() => void onClear(comment.id)}
+                  disabled={busy}
+                  aria-label={`清除註解 ${comment.id}`}
+                >
+                  <Trash2 aria-hidden="true" />
+                </button>
+              </li>
+            ))}
+          </ol>
+        )}
+      </Panel.Body>
+    </Panel>
+  );
+}
+
+export const PendingCommentsPanel = memo(PendingCommentsPanelImpl);
+PendingCommentsPanel.displayName = "PendingCommentsPanel";

package/src/openpress/workbench/panels/WorkbenchControlPanel.tsx

@@ -0,0 +1,29 @@
+import { Fragment, type ReactNode } from "react";
+
+// A WorkbenchPanel is a self-contained renderable slot in the workbench
+// control surface. Each panel owns its own props by capturing them in render;
+// the host (HtmlWorkbench) supplies the list and decides ordering.
+export interface WorkbenchPanel {
+  id: string;
+  render: () => ReactNode;
+}
+
+export interface WorkbenchControlPanelProps {
+  panels: WorkbenchPanel[];
+  className?: string;
+  ariaLabel?: string;
+}
+
+export function WorkbenchControlPanel({
+  panels,
+  className = "openpress-control-panel",
+  ariaLabel = "控制面板",
+}: WorkbenchControlPanelProps) {
+  return (
+    <div className={className} data-openpress-control-panel aria-label={ariaLabel}>
+      {panels.map((panel) => (
+        <Fragment key={panel.id}>{panel.render()}</Fragment>
+      ))}
+    </div>
+  );
+}

package/src/openpress/workbench/panels/index.ts

@@ -0,0 +1,3 @@
+export * from "./Panel";
+export * from "./PendingCommentsPanel";
+export * from "./WorkbenchControlPanel";