@tangle-network/ui 11.12.0 → 11.13.1

package/dist/editor/document-editor-pane.js

@@ -0,0 +1,199 @@
+"use client";
+import { focusRing } from "../lib/focus.js";
+import { cn } from "../lib/utils.js";
+import { Tabs, TabsContent, TabsList, TabsTrigger } from "../primitives/tabs.js";
+import { ArtifactPane } from "../primitives/artifact-pane.js";
+import { Markdown } from "../markdown/markdown.js";
+import { EditorProvider } from "./editor-provider.js";
+import { CollaboratorsList, TiptapEditor } from "./tiptap-editor.js";
+import { htmlToMarkdown, markdownToHtml, normalizeMarkdown } from "./markdown-conversion.js";
+import { MarkdownDocumentEditor } from "./markdown-document-editor.js";
+import { useCollaborators, useEditorConnection } from "./use-editor.js";
+import { useEffect, useMemo, useState } from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { PencilLine, Save, Users, Wifi, WifiOff } from "lucide-react";
+//#region src/editor/document-editor-pane.tsx
+function connectionTone(state) {
+	switch (state) {
+		case "synced": return "text-[var(--surface-success-text)] border-[var(--surface-success-border)] bg-[var(--surface-success-bg)]";
+		case "connected":
+		case "connecting": return "text-[var(--surface-info-text)] border-[var(--surface-info-border)] bg-[var(--surface-info-bg)]";
+		default: return "text-[var(--surface-warning-text)] border-[var(--surface-warning-border)] bg-[var(--surface-warning-bg)]";
+	}
+}
+function connectionLabel(state) {
+	switch (state) {
+		case "synced": return "Live synced";
+		case "connected": return "Connected";
+		case "connecting": return "Connecting";
+		default: return "Offline";
+	}
+}
+function connectionDescription(state, collaborators, readOnly) {
+	if (readOnly) return state === "disconnected" ? "Live access is paused. You can keep reading while the editor reconnects." : "You are viewing the live document in read-only mode.";
+	switch (state) {
+		case "synced": return collaborators > 0 ? `You and ${collaborators} collaborator${collaborators === 1 ? "" : "s"} are editing the same document.` : "You are editing the live document. Changes sync automatically.";
+		case "connected":
+		case "connecting": return "Connecting the live document. Local edits stay in place while sync catches up.";
+		default: return "Live updates are paused. You can keep editing and reconnect when the transport is healthy again.";
+	}
+}
+function CollaborativeDocumentSurface({ markdown, placeholder, autoFocus, readOnly, className, onChange }) {
+	const { state } = useEditorConnection();
+	const { collaborators } = useCollaborators();
+	const initialContent = useMemo(() => markdownToHtml(markdown), [markdown]);
+	const collaboratorCount = collaborators.length + 1;
+	return /* @__PURE__ */ jsxs("div", {
+		className: cn("flex h-full min-h-0 flex-col gap-3", className),
+		children: [/* @__PURE__ */ jsxs("div", {
+			className: "flex flex-wrap items-center justify-between gap-3 rounded-[var(--radius-lg)] border border-border bg-card px-3 py-2",
+			children: [/* @__PURE__ */ jsxs("div", {
+				className: "min-w-0 space-y-2",
+				children: [/* @__PURE__ */ jsxs("div", {
+					className: "flex flex-wrap items-center gap-2 text-xs text-muted-foreground",
+					children: [/* @__PURE__ */ jsxs("span", {
+						className: cn("inline-flex items-center gap-1.5 rounded-full border px-2.5 py-1 font-medium", connectionTone(state)),
+						children: [state === "disconnected" ? /* @__PURE__ */ jsx(WifiOff, { className: "h-3.5 w-3.5" }) : /* @__PURE__ */ jsx(Wifi, { className: "h-3.5 w-3.5" }), connectionLabel(state)]
+					}), /* @__PURE__ */ jsxs("span", {
+						className: "inline-flex items-center gap-1.5 rounded-full border border-border bg-background px-2.5 py-1",
+						children: [/* @__PURE__ */ jsx(Users, { className: "h-3.5 w-3.5" }), collaborators.length === 0 ? "Solo editing" : `${collaboratorCount} active`]
+					})]
+				}), /* @__PURE__ */ jsx("p", {
+					className: "text-xs text-muted-foreground",
+					children: connectionDescription(state, collaborators.length, readOnly)
+				})]
+			}), /* @__PURE__ */ jsx(CollaboratorsList, { collaborators })]
+		}), /* @__PURE__ */ jsx(TiptapEditor, {
+			initialContent,
+			placeholder,
+			autoFocus,
+			readOnly,
+			className: cn("h-full min-h-[16rem]", className),
+			onUpdate: (editor) => {
+				onChange?.(normalizeMarkdown(htmlToMarkdown(editor.getHTML())));
+			}
+		})]
+	});
+}
+/**
+* DocumentEditorPane — reusable markdown document surface with preview/edit
+* modes and optional collaborative editing backed by Yjs/Hocuspocus.
+*/
+function DocumentEditorPane({ eyebrow, title, subtitle, meta, headerActions, footer, className, contentClassName, headerClassName, hideTitleBlock, tabs, toolbar, markdown = "", savedMarkdown, urlTransform, mode, defaultMode = "preview", onModeChange, backend = "local", placeholder = "Start writing...", autoFocus = false, readOnly = false, onChange, onSave, saving = false, saveLabel = "Save changes", previewClassName, editorClassName, collaboration }) {
+	const [draft, setDraft] = useState(markdown);
+	const [uncontrolledMode, setUncontrolledMode] = useState(defaultMode);
+	const activeMode = mode ?? uncontrolledMode;
+	const isCollaborative = backend === "collaborative" && Boolean(collaboration);
+	const isDirty = normalizeMarkdown(draft) !== normalizeMarkdown(savedMarkdown ?? markdown);
+	const saveStateLabel = readOnly ? "Read only" : isCollaborative ? isDirty ? "Snapshot pending" : "Live document current" : isDirty ? "Unsaved changes" : "Saved";
+	useEffect(() => {
+		setDraft(markdown);
+	}, [markdown]);
+	useEffect(() => {
+		if (mode === void 0) setUncontrolledMode(defaultMode);
+	}, [defaultMode, mode]);
+	const setMode = (nextMode) => {
+		if (mode === void 0) setUncontrolledMode(nextMode);
+		onModeChange?.(nextMode);
+	};
+	const handleChange = (nextMarkdown) => {
+		setDraft(nextMarkdown);
+		onChange?.(nextMarkdown);
+	};
+	const editorToolbar = /* @__PURE__ */ jsxs("div", {
+		className: "flex flex-wrap items-center justify-between gap-3",
+		children: [/* @__PURE__ */ jsxs(TabsList, {
+			variant: "underline",
+			className: "h-auto gap-4 border-0 bg-transparent p-0 text-muted-foreground",
+			children: [/* @__PURE__ */ jsx(TabsTrigger, {
+				value: "preview",
+				variant: "underline",
+				className: "pb-2 data-[state=active]:border-primary data-[state=active]:text-foreground",
+				children: "Preview"
+			}), /* @__PURE__ */ jsxs(TabsTrigger, {
+				value: "edit",
+				variant: "underline",
+				className: "flex items-center gap-2 pb-2 data-[state=active]:border-primary data-[state=active]:text-foreground",
+				children: [/* @__PURE__ */ jsx(PencilLine, { className: "h-3.5 w-3.5" }), isCollaborative ? "Live edit" : "Edit"]
+			})]
+		}), /* @__PURE__ */ jsxs("div", {
+			className: "flex flex-wrap items-center gap-2 text-xs text-muted-foreground",
+			children: [
+				toolbar,
+				/* @__PURE__ */ jsx("span", {
+					className: "rounded-full border border-border bg-card px-2.5 py-1 font-medium",
+					children: isCollaborative ? "Live document" : "Local draft"
+				}),
+				/* @__PURE__ */ jsx("span", {
+					className: "rounded-full border border-border bg-background px-2.5 py-1",
+					children: saveStateLabel
+				}),
+				onSave && !readOnly && /* @__PURE__ */ jsxs("button", {
+					type: "button",
+					onClick: () => void onSave(draft),
+					disabled: saving || !isDirty,
+					className: cn("inline-flex items-center gap-2 rounded-[var(--radius-full)] border border-border bg-card px-3 py-1.5 text-xs font-semibold text-foreground transition-colors hover:border-[var(--border-strong)] hover:text-foreground disabled:cursor-not-allowed disabled:opacity-50", focusRing),
+					children: [/* @__PURE__ */ jsx(Save, { className: "h-3.5 w-3.5" }), saving ? "Saving..." : saveLabel]
+				})
+			]
+		})]
+	});
+	const preview = /* @__PURE__ */ jsx("div", {
+		className: cn("m-4 rounded-[var(--radius-lg)] border border-border bg-card p-5", previewClassName),
+		children: /* @__PURE__ */ jsx(Markdown, {
+			urlTransform,
+			children: draft
+		})
+	});
+	const localEditor = /* @__PURE__ */ jsx(MarkdownDocumentEditor, {
+		value: draft,
+		placeholder,
+		autoFocus,
+		readOnly,
+		onChange: (nextMarkdown) => {
+			handleChange(nextMarkdown);
+		},
+		className: editorClassName
+	});
+	const collaborativeEditor = collaboration ? /* @__PURE__ */ jsx(EditorProvider, {
+		...collaboration,
+		children: /* @__PURE__ */ jsx(CollaborativeDocumentSurface, {
+			markdown: draft,
+			placeholder,
+			autoFocus,
+			readOnly,
+			className: editorClassName,
+			onChange: handleChange
+		})
+	}, collaboration.documentName) : localEditor;
+	return /* @__PURE__ */ jsx(Tabs, {
+		value: activeMode,
+		onValueChange: (nextValue) => setMode(nextValue),
+		className: "h-full",
+		children: /* @__PURE__ */ jsxs(ArtifactPane, {
+			eyebrow,
+			title,
+			subtitle,
+			meta,
+			headerActions,
+			footer,
+			tabs,
+			className,
+			contentClassName,
+			headerClassName,
+			toolbar: editorToolbar,
+			hideTitleBlock,
+			children: [/* @__PURE__ */ jsx(TabsContent, {
+				value: "preview",
+				className: "mt-0 h-full",
+				children: preview
+			}), /* @__PURE__ */ jsx(TabsContent, {
+				value: "edit",
+				className: "mt-0 h-full px-4 py-4",
+				children: isCollaborative ? collaborativeEditor : localEditor
+			})]
+		})
+	});
+}
+//#endregion
+export { DocumentEditorPane };

package/dist/editor/editor-lazy.js

@@ -0,0 +1,37 @@
+import { isMissingEditorPeersError } from "./editor-peers.js";
+import { lazy } from "react";
+//#region src/editor/editor-lazy.ts
+/**
+* Builds a `lazy` editor component that a remount can re-attempt.
+*
+* `lazy` caches its first rejection for the life of the component. That is
+* right for a missing peer, which stays missing for the session, and wrong for
+* a transient chunk fetch: one failed network request would otherwise hold the
+* editor broken until a full page reload.
+*
+* The returned function gives the component to render, and a caller must call
+* it on every render: a transient failure replaces the component, and a caller
+* that holds the one it got earlier keeps replaying the cached rejection.
+*
+* A `MissingEditorPeersError` keeps the cached rejection, so the install list
+* reaches the consumer's error boundary once and the loader does not run
+* again. Any other rejection replaces the component, so the next mount — an
+* error boundary that resets, or a remount by the parent — starts a fresh
+* attempt.
+*/
+function retryableLazyEditor(loadComponent) {
+	function build() {
+		return lazy(async () => {
+			try {
+				return { default: await loadComponent() };
+			} catch (error) {
+				if (!isMissingEditorPeersError(error)) current = build();
+				throw error;
+			}
+		});
+	}
+	let current = build();
+	return () => current;
+}
+//#endregion
+export { retryableLazyEditor };

package/dist/editor/editor-loading.js

@@ -0,0 +1,21 @@
+"use client";
+import { cn } from "../lib/utils.js";
+import { jsx } from "react/jsx-runtime";
+//#region src/editor/editor-loading.tsx
+/**
+* Stands in for an editor while its optional peers load. The editors reach
+* tiptap through a dynamic import, so an editor's first frame waits for that
+* chunk. The live region announces the wait, which a screen reader has no
+* other way to notice. Callers put their own minimum height first, so a
+* caller-supplied className still wins.
+*/
+function EditorLoadingPlaceholder({ className }) {
+	return /* @__PURE__ */ jsx("div", {
+		role: "status",
+		"aria-live": "polite",
+		className: cn("flex w-full items-center justify-center rounded-lg border border-border border-dashed bg-muted text-muted-foreground text-sm", className),
+		children: "Loading editor…"
+	});
+}
+//#endregion
+export { EditorLoadingPlaceholder };

package/dist/editor/editor-peers.d.ts

@@ -0,0 +1,6 @@
+import "@hocuspocus/provider";
+import "yjs";
+import "@tiptap/extension-collaboration";
+import "@tiptap/extension-collaboration-caret";
+import "@tiptap/react";
+import "@tiptap/starter-kit";

package/dist/editor/editor-peers.js

@@ -0,0 +1,155 @@
+//#region src/editor/editor-peers.ts
+const DOCUMENT_PEERS_MISSING = "@tangle-network/ui/editor needs its optional editor peers. Install @tiptap/react and @tiptap/starter-kit.";
+const PROVIDER_PEERS_MISSING = "@tangle-network/ui/editor needs its optional collaboration transport peers. Install @hocuspocus/provider and yjs.";
+const COLLABORATION_PEERS_MISSING = "@tangle-network/ui/editor needs its optional collaboration peers. Install @tiptap/react, @tiptap/starter-kit, @tiptap/extension-collaboration, @tiptap/extension-collaboration-caret, @hocuspocus/provider and yjs.";
+/**
+* A peer the editor needs is absent, or resolved to a stub that carries none
+* of the members the editor calls. The condition holds for the rest of the
+* session, because a package does not install itself mid-run.
+*/
+var MissingEditorPeersError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "MissingEditorPeersError";
+	}
+};
+/**
+* True for the error above. The name carries the answer, so a duplicated copy
+* of this module in a consumer's bundle still reports its own error correctly.
+*/
+function isMissingEditorPeersError(error) {
+	return error instanceof Error && error.name === "MissingEditorPeersError";
+}
+/** The messages a bundler or a runtime gives for a module it cannot resolve. */
+const RESOLUTION_FAILURE = /could not resolve|cannot find (?:module|package)|can't resolve|failed to resolve|module not found/i;
+/**
+* True when the rejection says the package is not installed. Only such an
+* error gets the install list: a transient chunk-fetch failure that reads as
+* "install the peers" sends the reader to the wrong fix. An error this
+* predicate does not match keeps its own message, so it can only
+* under-report.
+*/
+function isMissingPeerError(error) {
+	return error instanceof Error && RESOLUTION_FAILURE.test(error.message);
+}
+/**
+* Hands an `import()` rejection on unchanged. esbuild reports an unresolvable
+* literal `import()` as a build error and defers it to run time only when the
+* call carries a `.catch()`, so every peer import attaches this handler. It
+* changes nothing at run time.
+*/
+function rethrow(error) {
+	throw error;
+}
+/**
+* Every optional peer the `./editor` entry needs at run time. The loaders
+* import all but `@tiptap/core`, which the tiptap packages need in turn: a
+* consumer that resolves it to nothing breaks the same way, so a failure that
+* names it is a missing peer too. `scripts/validate-dist.mjs` holds the same
+* list and rejects a build where the two disagree.
+*/
+const DEFERRED_PEERS = [
+	"@tiptap/core",
+	"@tiptap/react",
+	"@tiptap/starter-kit",
+	"@tiptap/extension-collaboration",
+	"@tiptap/extension-collaboration-caret",
+	"@hocuspocus/provider",
+	"yjs"
+];
+/** Every deferred peer a resolution failure names. */
+function unresolvedPeersFrom(error) {
+	if (!(error instanceof Error)) return [];
+	const named = DEFERRED_PEERS.filter((name) => error.message.includes(name));
+	return named.filter((name) => !named.some((other) => other !== name && other.includes(name)));
+}
+/**
+* Turns a rejection that names an unresolved peer into the install-list error,
+* and keeps the original as its cause. Any other rejection passes through, so
+* a transient chunk fetch keeps its own message and stays retryable.
+*/
+function asMissingEditorPeersError(error, missingMessage) {
+	if (!isMissingPeerError(error)) return error;
+	const unresolved = unresolvedPeersFrom(error);
+	if (unresolved.length === 0) return error;
+	return new MissingEditorPeersError(missingMessage + (unresolved.length === 1 ? ` ${unresolved[0]} did not resolve.` : ""), { cause: error });
+}
+async function loadPeers(load, missingMessage) {
+	try {
+		return await load();
+	} catch (error) {
+		throw asMissingEditorPeersError(error, missingMessage);
+	}
+}
+/**
+* True for a tiptap extension the editor can configure. A bundler can stub a
+* missing optional peer as a silent namespace whose default export is an empty
+* object, which is defined but carries no `configure`. Reading the member the
+* factories call separates that shape from a real extension.
+*/
+function isConfigurableExtension(value) {
+	return typeof value?.configure === "function";
+}
+/**
+* Reads the members the editor calls, so a stub namespace fails with the
+* install list, and not as an undefined-property crash in the middle of a
+* render.
+*/
+function assertDocumentEditorPeers(peers, missingMessage) {
+	if (typeof peers.react.useEditor !== "function" || peers.react.EditorContent === void 0 || !isConfigurableExtension(peers.starterKit.default)) throw new MissingEditorPeersError(missingMessage);
+}
+function assertEditorProviderPeers(peers, missingMessage) {
+	if (typeof peers.hocuspocus.HocuspocusProvider !== "function" || typeof peers.yjs.Doc !== "function") throw new MissingEditorPeersError(missingMessage);
+}
+function assertCollaborationPeers(peers) {
+	assertDocumentEditorPeers(peers, COLLABORATION_PEERS_MISSING);
+	assertEditorProviderPeers(peers, COLLABORATION_PEERS_MISSING);
+	if (!isConfigurableExtension(peers.collaboration.default) || !isConfigurableExtension(peers.collaborationCaret.default)) throw new MissingEditorPeersError(COLLABORATION_PEERS_MISSING);
+}
+async function importDocumentEditorPeers() {
+	const [react, starterKit] = await Promise.all([import("@tiptap/react").catch(rethrow), import("@tiptap/starter-kit").catch(rethrow)]);
+	return {
+		react,
+		starterKit
+	};
+}
+async function importEditorProviderPeers() {
+	const [hocuspocus, yjs] = await Promise.all([import("@hocuspocus/provider").catch(rethrow), import("yjs").catch(rethrow)]);
+	return {
+		hocuspocus,
+		yjs
+	};
+}
+/** Resolve the collaboration transport's peers, or throw and name them. */
+async function loadEditorProviderPeers() {
+	const peers = await loadPeers(importEditorProviderPeers, PROVIDER_PEERS_MISSING);
+	assertEditorProviderPeers(peers, PROVIDER_PEERS_MISSING);
+	return peers;
+}
+/** Resolve the local markdown editor's peers, or throw and name them. */
+async function loadDocumentEditorPeers() {
+	const peers = await loadPeers(importDocumentEditorPeers, DOCUMENT_PEERS_MISSING);
+	assertDocumentEditorPeers(peers, DOCUMENT_PEERS_MISSING);
+	return peers;
+}
+/** Resolve the collaborative editor's peers, or throw and name them. */
+async function loadCollaborationPeers() {
+	const peers = await loadPeers(async () => {
+		const [documentPeers, providerPeers, collaboration, collaborationCaret] = await Promise.all([
+			importDocumentEditorPeers(),
+			importEditorProviderPeers(),
+			import("@tiptap/extension-collaboration").catch(rethrow),
+			import("@tiptap/extension-collaboration-caret").catch(rethrow)
+		]);
+		return {
+			...documentPeers,
+			...providerPeers,
+			collaboration,
+			collaborationCaret
+		};
+	}, COLLABORATION_PEERS_MISSING);
+	assertCollaborationPeers(peers);
+	return peers;
+}
+//#endregion
+export { MissingEditorPeersError, asMissingEditorPeersError, isMissingEditorPeersError, isMissingPeerError, loadCollaborationPeers, loadDocumentEditorPeers, loadEditorProviderPeers };

package/dist/editor/editor-provider.d.ts

@@ -0,0 +1,97 @@
+import "./editor-peers.js";
+import { ReactNode } from "react";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import * as Y from "yjs";
+//#region src/editor/editor-provider.d.ts
+/**
+ * Connection state for the Hocuspocus provider.
+ */
+export type ConnectionState = "disconnected" | "connecting" | "connected" | "synced";
+/**
+ * Collaborator information from awareness.
+ */
+export interface Collaborator {
+  clientId: number;
+  user: {
+    name: string;
+    color: string;
+    userId?: string;
+  };
+}
+/**
+ * Editor context value exposed to children.
+ */
+export interface EditorContextValue {
+  /** The Y.Doc instance for collaboration */
+  doc: Y.Doc;
+  /** The Hocuspocus provider instance */
+  provider: HocuspocusProvider | null;
+  /** Current connection state */
+  connectionState: ConnectionState;
+  /** List of active collaborators */
+  collaborators: Collaborator[];
+  /** Whether the document is synced with the server */
+  isSynced: boolean;
+  /** Connect to the collaboration server */
+  connect: () => void;
+  /** Disconnect from the collaboration server */
+  disconnect: () => void;
+}
+/**
+ * User information for presence/awareness.
+ */
+export interface EditorUser {
+  name: string;
+  color?: string;
+  userId?: string;
+}
+export interface EditorTokenRefreshResult {
+  token: string;
+  expiresAt?: number;
+}
+/**
+ * Props for EditorProvider.
+ */
+export interface EditorProviderProps {
+  /** WebSocket URL for the Hocuspocus server */
+  websocketUrl: string;
+  /** Document name (e.g., "doc:my-document") */
+  documentName: string;
+  /** JWT token for authentication */
+  token: string;
+  /** Unix timestamp (seconds) when the current token expires */
+  tokenExpiresAt?: number;
+  /** Current user information for awareness */
+  user: EditorUser;
+  /** Auto-connect on mount (default: true) */
+  autoConnect?: boolean;
+  /** Reconnect on disconnect (default: true) */
+  autoReconnect?: boolean;
+  /** Max reconnect attempts (default: 5) */
+  maxReconnectAttempts?: number;
+  /** Callback when connection state changes */
+  onConnectionChange?: (state: ConnectionState) => void;
+  /** Callback when sync completes */
+  onSync?: () => void;
+  /** Callback on authentication error */
+  onAuthError?: (error: Error) => void;
+  /** Optional token refresh callback used before reconnect/auth retry */
+  onRefreshToken?: () => Promise<EditorTokenRefreshResult | string>;
+  /** Children components */
+  children: ReactNode;
+}
+/**
+ * EditorProvider wraps children with Hocuspocus collaboration context.
+ * Manages WebSocket connection, Y.Doc, and awareness state. Loads `yjs` and
+ * `@hocuspocus/provider` — and no tiptap package — before it renders children,
+ * because every child hook reads a context that only the loaded provider can
+ * supply. A consumer that drives its own editor from that context therefore
+ * needs those two peers alone.
+ */
+export declare function EditorProvider(props: EditorProviderProps): import("react").JSX.Element;
+/**
+ * Hook to access the editor context.
+ * Must be used within an EditorProvider.
+ */
+export declare function useEditorContext(): EditorContextValue;
+//#endregion