@brett_lamy/docstream 1.3.0 → 1.5.0

package/README.md

@@ -416,6 +416,50 @@ or inline it); each inline demo boots its own container (the fullscreen overlay
 boots a second one). `preloadDemos(resolver, srcs)` settles resolver demos before
 the first render (server rendering, static export).
 
+#### Copy a demo, paste it elsewhere (clipboard + demo VFS)
+
+Every demo viewer has a **Copy demo** button. It writes one clipboard item with
+three representations, through react-aria's `useClipboard`:
+
+| Type | Content |
+| --- | --- |
+| `text/plain`, `text/markdown` | renderable docstream Markdown: the block with its files inline (resolver files for `src`-only demos, `meta.json` folded into the tag) |
+| `application/x-docstream+json` (`DOCSTREAM_CLIPBOARD_TYPE`) | `{ kind: "docstream", version: 1, markdown, files: { [src]: DemoFile[] }, meta: { [src]: DemoMeta } }` — the exact Markdown (a `src`-only block stays `src`-only) plus every demo's files and meta |
+
+Pasting into a docstream editor (`@brett_lamy/docstream-editor` 1.5+) recreates
+the demo with its files; pasting anywhere else gets the Markdown. Where the
+browser's copy command is unavailable the button copies the Markdown only
+(editors still parse its inline-file demos).
+
+Pasted demo files live in a **demo VFS** — an in-memory `{ [src]: { files, meta } }`
+store. Give it to a renderer (`demoVFS`) or an editor, or share one between
+several:
+
+```tsx
+import { MarkdownContent, useDemoVFS, useDemoVFSFiles } from "@brett_lamy/docstream"
+
+const vfs = useDemoVFS()                // stable per component; createDemoVFS() outside React
+const files = useDemoVFSFiles(vfs)      // { [src]: DemoFile[] }, re-renders on change — persist it
+<MarkdownContent markdown={page} demoResolver={demoResolver} demoRuntime={demoRuntime} demoVFS={vfs} />
+```
+
+A demo block resolves in this order: the host `demoResolver` when it knows `src`
+→ the block's inline files, else the VFS files for `src`, run by the
+`demoRuntime` (almost-node from `/playground` when installed) → the Code view
+with the "needs runtime" note. `vfs.resolver({ resolver, runtime })` is the same
+layering as a `DemoResolver` (`files` / `meta` from the host when it knows
+`src`, else from the VFS; `load` runs VFS files through the runtime).
+`vfs.subscribe(change => …)`, `get/set/delete/list/files()` manage it directly.
+
+Building blocks (`@brett_lamy/docstream/demo`): `createDocstreamClipboard(doc, { lookup, serialize })`
+/ `createDocstreamClipboardFromMarkdown`, `docstreamClipboardItems` (react-aria
+`DragItem`s), `writeDocstreamClipboard(dataTransfer, clip)`,
+`readDocstreamClipboard(dataTransfer)`, `readDocstreamClipboardItems(dropItems)`,
+`parseDocstreamClipboard(json)`, `docstreamPayloadFromMarkdown`,
+`useDocstreamCopy` / `CopyDemoButton`, and `prefetchDemoSources(resolver, srcs)` +
+`peekDemoSource(resolver, src)` to read a resolver's files synchronously (a copy
+event can't wait).
+
 Tell docstream where demos live with a `DemoResolver`. With Vite, three
 `import.meta.glob` maps are enough:
 
@@ -632,21 +676,51 @@ import { ReactDemo } from "@brett_lamy/docstream/playground"
 
 ## Bundler Notes
 
-This release ships TypeScript and TSX source through ESM exports:
+Since 1.4 the package ships compiled ES modules (ES2022, `react-jsx`) with type
+declarations and declaration maps — one file per source module in `dist/`,
+dependencies left as imports, lazy features (Mermaid, KaTeX, rrweb, the
+playground's almost-node) still behind dynamic `import()`:
 
 ```json
 {
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "./styles.css": "./src/styles.css"
+    "./styles.css": "./dist/styles.css"
   }
 }
 ```
 
-It is validated with Vite and modern TypeScript `moduleResolution: "Bundler"`. Plain Node.js, CommonJS, or tooling that does not transpile TypeScript in dependencies may need a future precompiled JS build.
+No bundler configuration is needed: Vite pre-bundles docstream like any other
+dependency (no `optimizeDeps` entries), Next.js and webpack consume it as plain
+ESM, and your type-check reads `.d.ts` files instead of docstream's sources. The
+`@brett_lamy/docstream/vite` entry is a Node-only Vite plugin; import it from
+`vite.config.ts`, never from browser code.
+
+The TypeScript sources are published too, behind a `source` export condition, for
+monorepos that want to compile docstream from source (e.g. Vite
+`resolve.conditions: ["source", ...]` or TypeScript `customConditions`).
+
+## Migrating to 1.5
+
+No breaking changes. New: **Copy demo** (clipboard with the demo's files and an
+`application/x-docstream+json` payload), the demo VFS (`demoVFS` on the
+renderers, `createDemoVFS` / `useDemoVFS`), and the clipboard helpers above.
+`react-aria` is now a dependency (for `useClipboard`); hosts on
+`react-aria-components` share it. The single-file demo card gains the Copy demo
+button; the multi-file viewer's "Copy demo as Markdown" is now "Copy demo" (the
+same Markdown as `text/plain`, plus the payload).
+
+## Migrating to 1.4
+
+No API changes. Exports now resolve to `dist/*.js` + `dist/*.d.ts` instead of
+`src/*.ts(x)`; drop any `optimizeDeps.include` / `exclude` or
+`transpilePackages` entries you added for docstream, and any `lib` / `types`
+settings you added only so your type-check could compile docstream's sources.
 
 ## Migrating to 1.3
 

package/dist/assets.d.ts

@@ -0,0 +1,3 @@
+export declare function setAssetBase(repo: string | null, branch: string | null, filePath: string | null): void;
+export declare function resolveAsset(src: string): string;
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAMA,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,QAO/F;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIhD"}

package/dist/assets.js

@@ -0,0 +1,20 @@
+// Resolves repo-relative image paths (e.g. "readme-assets/logo.svg") against
+// the raw.githubusercontent.com URL of the file being edited. The AST keeps
+// the original relative src; only rendering resolves it.
+let assetBase = null;
+export function setAssetBase(repo, branch, filePath) {
+    if (!repo || !branch || !filePath) {
+        assetBase = null;
+        return;
+    }
+    const dir = filePath.includes("/") ? filePath.slice(0, filePath.lastIndexOf("/") + 1) : "";
+    assetBase = `https://raw.githubusercontent.com/${repo}/${branch}/${dir}`;
+}
+export function resolveAsset(src) {
+    if (!src || /^(https?:|data:|blob:)/i.test(src))
+        return src;
+    if (!assetBase)
+        return src;
+    return assetBase + src.replace(/^\.\//, "");
+}
+//# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,4EAA4E;AAC5E,yDAAyD;AAEzD,IAAI,SAAS,GAAkB,IAAI,CAAA;AAEnC,MAAM,UAAU,YAAY,CAAC,IAAmB,EAAE,MAAqB,EAAE,QAAuB;IAC9F,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClC,SAAS,GAAG,IAAI,CAAA;QAChB,OAAM;IACR,CAAC;IACD,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC1F,SAAS,GAAG,qCAAqC,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAA;AAC1E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,IAAI,CAAC,GAAG,IAAI,yBAAyB,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,GAAG,CAAA;IAC3D,IAAI,CAAC,SAAS;QAAE,OAAO,GAAG,CAAA;IAC1B,OAAO,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;AAC7C,CAAC"}

package/dist/demo/DemoViewer.d.ts

@@ -0,0 +1,78 @@
+import { type CSSProperties } from "react";
+import type { DemoLayout, DemoNode, DemoViewport } from "../gitbook/ast.js";
+import { type DemoSourceSnapshot } from "./clipboard.js";
+import { type DemoVFS } from "./vfs.js";
+import type { DemoFile, DemoResolver, DemoVariant, InlineDemoRuntime } from "./types.js";
+export interface DemoViewerProps {
+    /** `<page>/<example>` id handed to the resolver. */
+    src: string;
+    /** Defaults to the nearest `demoResolver` provided to a renderer. */
+    resolver?: DemoResolver;
+    title?: string;
+    description?: string;
+    /** Preview height (px number, digits, or any CSS length). */
+    height?: number | string;
+    layout?: DemoLayout;
+    variants?: DemoVariant[];
+    /** Initial viewport of the multi-file preview. */
+    viewport?: DemoViewport;
+    /**
+     * Files carried inline by the block (entry first unless `entry` says otherwise). Used when
+     * no resolver knows `src`, or the resolver fails for it.
+     */
+    files?: DemoFile[];
+    /** Entry among `files`. Defaults to the first file. */
+    entry?: string;
+    /** The block is still streaming in: show its code, but don't run it yet. */
+    streaming?: boolean;
+    /** Runs inline files in the Preview. Defaults to the runtime in context (`demoRuntime`). */
+    runtime?: InlineDemoRuntime;
+    /** Extra npm dependencies for the runtime, merged over `demoDependencies` from context. */
+    dependencies?: Record<string, string>;
+    /**
+     * Demo files held in memory by `src` (pasted demos). Used, like inline files, when the block
+     * has none of its own and no resolver knows `src`. Defaults to the VFS in context (`demoVFS`).
+     */
+    vfs?: DemoVFS;
+    /** Class on the viewer's outer element. (The preview canvas's class is `canvasClassName`.) */
+    className?: string;
+    /** Status shown in the header (`meta.status`). */
+    status?: string;
+    /** Full-bleed canvas without the padded surface (`meta.bleed`). */
+    bleed?: boolean;
+    /** Extra class on the preview canvas (`meta.className`). */
+    canvasClassName?: string;
+    /** Canvas inline style: an object like `meta.surface`, or CSS declarations as in the tag's `surface`. */
+    surface?: Record<string, string | number> | string;
+    /** Width of the variant switch (`meta.variantsWidth`). */
+    variantsWidth?: number | string;
+}
+/**
+ * Resolve demos ahead of rendering (meta, files and component), so the first render — including
+ * server rendering and static export — shows them resolved instead of loading. Failures are
+ * remembered too, so inline-file fallbacks apply immediately.
+ */
+export declare function preloadDemos(resolver: DemoResolver, srcs: string[]): Promise<void>;
+/**
+ * Fetch demos' meta and files (not their components) into the viewer's cache, so
+ * `peekDemoSource` can answer synchronously — e.g. when a copy event needs a demo's files.
+ */
+export declare function prefetchDemoSources(resolver: DemoResolver, srcs: string[]): Promise<void>;
+/** A demo's files (and meta) if the resolver has already delivered them (viewer, `preloadDemos`, `prefetchDemoSources`). */
+export declare function peekDemoSource(resolver: DemoResolver, src: string): DemoSourceSnapshot | undefined;
+export declare const NO_RUNTIME_NOTE = "Live preview needs the playground runtime. The code is shown instead.";
+export declare function DemoViewer(props: DemoViewerProps): import("react").JSX.Element;
+/** Renders a parsed `{% demo %}` block with the resolver and runtime from context. */
+export declare function DemoBlock({ node }: {
+    node: DemoNode;
+}): import("react").JSX.Element;
+export interface DemoFullscreenProps {
+    src: string;
+    resolver?: DemoResolver;
+    variant?: string;
+    className?: string;
+    style?: CSSProperties;
+}
+/** One demo filling the viewport, for a `?demo=<src>` deep link the host routes. */
+export declare function DemoFullscreen({ src, resolver: override, variant, className, style }: DemoFullscreenProps): import("react").JSX.Element;
+//# sourceMappingURL=DemoViewer.d.ts.map

package/dist/demo/DemoViewer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DemoViewer.d.ts","sourceRoot":"","sources":["../../src/demo/DemoViewer.tsx"],"names":[],"mappings":"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"}