@particle-academy/fancy-code 0.14.0 → 0.15.1

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { RefObject, ReactNode, CSSProperties } from 'react';
+import { RefObject, ReactNode, CSSProperties, ComponentType } from 'react';
 import { ThemeColors, DiffAnnotations, LineChangeType, Token, Tokenizer } from '@particle-academy/fancy-file-commons';
 export { ThemeColors, Token, TokenType, Tokenizer, languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, FauxClientProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
@@ -379,6 +379,12 @@ interface FileViewerProps {
      * and full screen, revealed on hover): `variant`, a controlled `zoom`, …
      */
     frameProps?: Partial<FauxClientProps>;
+    /**
+     * An Office file's contents, already read on the server (dark-slide /
+     * holy-sheet / last-word), for the viewer registered with
+     * `registerOfficeViewer`. Preferred over reading `src` in the browser.
+     */
+    document?: unknown;
     className?: string;
     style?: CSSProperties;
 }
@@ -399,11 +405,53 @@ interface FileViewerProps {
  * <FileViewer filename="logo.png" src={url} style={{ height: 360 }} />
  * ```
  */
-declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, line, column, highlightLines, minHeight, maxHeight, mediaProps, view, frameProps, className, style, }: FileViewerProps): react.JSX.Element;
+declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, line, column, highlightLines, minHeight, maxHeight, mediaProps, view, frameProps, document, className, style, }: FileViewerProps): react.JSX.Element;
 declare namespace FileViewer {
     var displayName: string;
 }
 
+/** What a registered Office viewer is given. */
+interface OfficeViewerProps {
+    /** The file's contents as our reader returns them (a dark-slide deck, a holy-sheet workbook, a last-word doc). */
+    document: unknown;
+    filename?: string;
+    /** Passed through from `FileViewer`, for viewers that sit in the FauxClient frame. */
+    frameProps?: Partial<FauxClientProps>;
+}
+interface OfficeViewerOptions {
+    /**
+     * Read the raw file in the browser, for when the app has only a URL. Give it
+     * our JS reader, e.g. `(bytes) => new PptxReader().read(bytes)`. Without it,
+     * a file with no server-read `document` gets the download card.
+     */
+    read?: (bytes: Uint8Array) => unknown;
+}
+interface Registration {
+    View: ComponentType<OfficeViewerProps>;
+    read?: (bytes: Uint8Array) => unknown;
+}
+/**
+ * Show one Office format in `FileViewer` with a kit viewer. Call once at app
+ * start, per format you want:
+ *
+ * ```ts
+ * import { registerOfficeViewer } from "@particle-academy/fancy-code";
+ * import { DeckFileView } from "@particle-academy/fancy-slides";
+ * import { PptxReader } from "@particle-academy/dark-slide";
+ *
+ * registerOfficeViewer("pptx", DeckFileView, { read: (b) => new PptxReader().read(b) });
+ * ```
+ *
+ * A registry rather than an import because fancy-code must not depend on the
+ * slide or sheet packages: an app that has neither (and does not want them)
+ * would otherwise fail to build on a file type it never opens.
+ */
+declare function registerOfficeViewer(kind: OfficeKind, View: ComponentType<OfficeViewerProps>, options?: OfficeViewerOptions): void;
+/** The viewer registered for a format, if any. */
+declare function officeViewerFor(kind: OfficeKind): Registration | undefined;
+/** Forget every registration (tests, hot reload). */
+declare function clearOfficeViewers(): void;
+
 /**
  * Diff-gutter model — the pure mapping between fancy-file-commons line
  * annotations and what the CodeEditor gutter renders per line-number row.
@@ -503,4 +551,4 @@ interface CodeEditorInputTagProps extends Omit<InputTagProps, "adapter"> {
  */
 declare function CodeEditorInputTag(props: CodeEditorInputTagProps): react.JSX.Element;
 
-export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type ResolveFileKindInput, type ThemeDefinition, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type DocumentFormat, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type OfficeKind, type OfficeViewerOptions, type OfficeViewerProps, type ResolveFileKindInput, type ThemeDefinition, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { RefObject, ReactNode, CSSProperties } from 'react';
+import { RefObject, ReactNode, CSSProperties, ComponentType } from 'react';
 import { ThemeColors, DiffAnnotations, LineChangeType, Token, Tokenizer } from '@particle-academy/fancy-file-commons';
 export { ThemeColors, Token, TokenType, Tokenizer, languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { MediaKind, MediaViewerProps, FauxClientProps, InputTagProps, InputTagTriggers, InputTagAdapter } from '@particle-academy/react-fancy';
@@ -379,6 +379,12 @@ interface FileViewerProps {
      * and full screen, revealed on hover): `variant`, a controlled `zoom`, …
      */
     frameProps?: Partial<FauxClientProps>;
+    /**
+     * An Office file's contents, already read on the server (dark-slide /
+     * holy-sheet / last-word), for the viewer registered with
+     * `registerOfficeViewer`. Preferred over reading `src` in the browser.
+     */
+    document?: unknown;
     className?: string;
     style?: CSSProperties;
 }
@@ -399,11 +405,53 @@ interface FileViewerProps {
  * <FileViewer filename="logo.png" src={url} style={{ height: 360 }} />
  * ```
  */
-declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, line, column, highlightLines, minHeight, maxHeight, mediaProps, view, frameProps, className, style, }: FileViewerProps): react.JSX.Element;
+declare function FileViewer({ filename, mime, src, value, onChange, readOnly, theme, fileKind, lineNumbers, wordWrap, line, column, highlightLines, minHeight, maxHeight, mediaProps, view, frameProps, document, className, style, }: FileViewerProps): react.JSX.Element;
 declare namespace FileViewer {
     var displayName: string;
 }
 
+/** What a registered Office viewer is given. */
+interface OfficeViewerProps {
+    /** The file's contents as our reader returns them (a dark-slide deck, a holy-sheet workbook, a last-word doc). */
+    document: unknown;
+    filename?: string;
+    /** Passed through from `FileViewer`, for viewers that sit in the FauxClient frame. */
+    frameProps?: Partial<FauxClientProps>;
+}
+interface OfficeViewerOptions {
+    /**
+     * Read the raw file in the browser, for when the app has only a URL. Give it
+     * our JS reader, e.g. `(bytes) => new PptxReader().read(bytes)`. Without it,
+     * a file with no server-read `document` gets the download card.
+     */
+    read?: (bytes: Uint8Array) => unknown;
+}
+interface Registration {
+    View: ComponentType<OfficeViewerProps>;
+    read?: (bytes: Uint8Array) => unknown;
+}
+/**
+ * Show one Office format in `FileViewer` with a kit viewer. Call once at app
+ * start, per format you want:
+ *
+ * ```ts
+ * import { registerOfficeViewer } from "@particle-academy/fancy-code";
+ * import { DeckFileView } from "@particle-academy/fancy-slides";
+ * import { PptxReader } from "@particle-academy/dark-slide";
+ *
+ * registerOfficeViewer("pptx", DeckFileView, { read: (b) => new PptxReader().read(b) });
+ * ```
+ *
+ * A registry rather than an import because fancy-code must not depend on the
+ * slide or sheet packages: an app that has neither (and does not want them)
+ * would otherwise fail to build on a file type it never opens.
+ */
+declare function registerOfficeViewer(kind: OfficeKind, View: ComponentType<OfficeViewerProps>, options?: OfficeViewerOptions): void;
+/** The viewer registered for a format, if any. */
+declare function officeViewerFor(kind: OfficeKind): Registration | undefined;
+/** Forget every registration (tests, hot reload). */
+declare function clearOfficeViewers(): void;
+
 /**
  * Diff-gutter model — the pure mapping between fancy-file-commons line
  * annotations and what the CodeEditor gutter renders per line-number row.
@@ -503,4 +551,4 @@ interface CodeEditorInputTagProps extends Omit<InputTagProps, "adapter"> {
  */
 declare function CodeEditorInputTag(props: CodeEditorInputTagProps): react.JSX.Element;
 
-export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type ResolveFileKindInput, type ThemeDefinition, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, type CodeEditorContextValue, CodeEditorInputTag, type CodeEditorInputTagProps, type CodeEditorPanelProps, type CodeEditorProps, type CodeEditorStatusBarProps, type CodeEditorToolbarProps, type DocumentFormat, type FileKind, FileViewer, type FileViewerProps, type GutterDiffMark, type LanguageDefinition, MarkdownEditor, type MarkdownEditorMode, type MarkdownEditorProps, type OfficeKind, type OfficeViewerOptions, type OfficeViewerProps, type ResolveFileKindInput, type ThemeDefinition, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, useMemo, useState, useCallback, useRef, useEffect, useSyncExternalStore, useContext } from 'react';
-import { cn, useControllableState, ContentRenderer, resolveMediaType, FauxClient, MediaViewer, textareaAdapter, InputTag } from '@particle-academy/react-fancy';
+import { cn, useControllableState, ContentRenderer, resolveMediaType, FauxClient, MediaViewer, Callout, textareaAdapter, InputTag } from '@particle-academy/react-fancy';
 import { annotateLines, highlightCode, tok, tokenizeHtml, LIGHT_COLORS, DARK_COLORS, languageFromFilename } from '@particle-academy/fancy-file-commons';
 export { languageFromFilename } from '@particle-academy/fancy-file-commons';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -1720,6 +1720,18 @@ function MarkdownEditor({
   );
 }
 MarkdownEditor.displayName = "MarkdownEditor";
+
+// src/office-viewers.ts
+var registry = /* @__PURE__ */ new Map();
+function registerOfficeViewer(kind, View, options = {}) {
+  registry.set(kind, { View, read: options.read });
+}
+function officeViewerFor(kind) {
+  return registry.get(kind);
+}
+function clearOfficeViewers() {
+  registry.clear();
+}
 var OFFICE_EXT = { docx: "docx", xlsx: "xlsx", xlsm: "xlsx", pptx: "pptx" };
 var OFFICE_MIME = {
   "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
@@ -1779,6 +1791,7 @@ function FileViewer({
   mediaProps,
   view = "rendered",
   frameProps,
+  document,
   className,
   style
 }) {
@@ -1811,7 +1824,17 @@ function FileViewer({
         "data-office-kind": resolved.officeKind,
         className: cn("overflow-hidden", className),
         style,
-        children: /* @__PURE__ */ jsx(MediaViewer, { src: src ?? "", mime, alt: filename, className: "h-full w-full" })
+        children: /* @__PURE__ */ jsx(
+          OfficeFile,
+          {
+            kind: resolved.officeKind,
+            document,
+            src,
+            mime,
+            filename,
+            frameProps
+          }
+        )
       }
     );
   }
@@ -1871,6 +1894,57 @@ function FileViewer({
   );
 }
 FileViewer.displayName = "FileViewer";
+function OfficeFile({
+  kind,
+  document,
+  src,
+  mime,
+  filename,
+  frameProps
+}) {
+  const registration = officeViewerFor(kind);
+  const read = registration?.read;
+  const [state, setState] = useState({ status: "idle" });
+  useEffect(() => {
+    if (!registration || document !== void 0 || !src || !read) return;
+    let live = true;
+    setState({ status: "reading" });
+    fetch(src).then(async (response) => {
+      if (!response.ok) throw new Error(`The file could not be fetched (${response.status}).`);
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      const doc = read(bytes);
+      if (live) setState({ status: "read", document: doc });
+    }).catch((error) => {
+      if (live) setState({ status: "failed", message: error instanceof Error ? error.message : String(error) });
+    });
+    return () => {
+      live = false;
+    };
+  }, [registration, document, src, read]);
+  const fallback = /* @__PURE__ */ jsx(MediaViewer, { src: src ?? "", mime, alt: filename, className: "h-full w-full" });
+  if (!registration) return fallback;
+  const View = registration.View;
+  if (document !== void 0) return /* @__PURE__ */ jsx(View, { document, filename, frameProps });
+  if (state.status === "read") return /* @__PURE__ */ jsx(View, { document: state.document, filename, frameProps });
+  if (state.status === "reading") {
+    return /* @__PURE__ */ jsxs("div", { className: "flex h-full items-center justify-center p-6 text-sm text-zinc-500", children: [
+      "Opening ",
+      filename ?? "the file",
+      "\u2026"
+    ] });
+  }
+  if (state.status === "failed") {
+    return /* @__PURE__ */ jsxs("div", { className: "flex h-full flex-col gap-2 p-2", children: [
+      /* @__PURE__ */ jsxs(Callout, { color: "red", children: [
+        filename ?? "This file",
+        " could not be opened: ",
+        state.message
+      ] }),
+      fallback
+    ] });
+  }
+  return fallback;
+}
 var ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
 function textToHtml(text) {
   return text.replace(/\r\n?/g, "\n").split(/\n{2,}/).filter((block) => block.trim() !== "").map((block) => `<p>${block.replace(/[&<>"']/g, (c) => ESCAPES[c]).replace(/\n/g, "<br>")}</p>`).join("");
@@ -2002,6 +2076,6 @@ function CodeEditorInputTag(props) {
   return /* @__PURE__ */ jsx(InputTag, { adapter, ...props });
 }
 
-export { CodeEditor, CodeEditorInputTag, FileViewer, MarkdownEditor, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, registerLanguage, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
+export { CodeEditor, CodeEditorInputTag, FileViewer, MarkdownEditor, clearOfficeViewers, diffMarkColor, diffRemovedColor, getLanguage, getRegisteredLanguages, getRegisteredThemes, getTheme, gutterDiffMark, hasDeletedAtEnd, officeViewerFor, registerLanguage, registerOfficeViewer, registerTheme, renderMarkdown, resolveFileKind, tokenizeMarkdown, useCodeEditor, useCodeEditorInputTagAdapter };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map