@brett_lamy/docstream 1.8.0 → 1.9.1

package/src/gitbook/properties.ts

@@ -0,0 +1,49 @@
+import { isMap, isScalar, parseDocument } from "yaml"
+import type { DocumentPropertiesNode } from "./ast"
+
+export type DocumentPropertyValue = string | number | boolean | null | DocumentPropertyValue[] | { [key: string]: DocumentPropertyValue }
+export interface ParsedDocumentProperties {
+  values: Record<string, DocumentPropertyValue>
+  error?: string
+}
+
+/** Read properties without throwing on an incomplete or invalid document. YAML is never executed. */
+export function readDocumentProperties(properties: DocumentPropertiesNode): ParsedDocumentProperties {
+  try {
+    const doc = parseDocument(properties.yaml)
+    if (doc.errors.length) return { values: {}, error: doc.errors[0].message }
+    if (doc.contents && !isMap(doc.contents)) return { values: {}, error: "Document properties must be a YAML mapping." }
+    const values = (doc.toJS({ maxAliasCount: 100 }) ?? {}) as Record<string, DocumentPropertyValue>
+    // Cyclic aliases can be preserved as YAML, but cannot be represented by editable JSON-like values.
+    JSON.stringify(values)
+    return { values }
+  } catch (error) {
+    return { values: {}, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/** Change one property while retaining the other keys, comments, scalar styles and frontmatter delimiters. */
+export function setDocumentProperty(properties: DocumentPropertiesNode, key: string, value: DocumentPropertyValue): DocumentPropertiesNode {
+  const doc = parseDocument(properties.yaml)
+  const parsed = readDocumentProperties(properties)
+  if (parsed.error) throw new Error(parsed.error)
+  const previous = doc.get(key, true)
+  const range = isScalar(previous) ? previous.range : undefined
+  doc.set(key, value)
+  const yaml = doc.toString().replace(/\n$/, "")
+  const next = parseDocument(yaml).get(key, true)
+  // A scalar edit is a source-range patch, leaving every other byte (including flow-list spacing) alone.
+  if (range && isScalar(next) && next.range) {
+    return { ...properties, yaml: properties.yaml.slice(0, range[0]) + yaml.slice(next.range[0], next.range[1]) + properties.yaml.slice(range[1]) }
+  }
+  return { ...properties, yaml }
+}
+
+/** Remove one property; the frontmatter remains available for adding more. */
+export function removeDocumentProperty(properties: DocumentPropertiesNode, key: string): DocumentPropertiesNode {
+  const doc = parseDocument(properties.yaml)
+  const parsed = readDocumentProperties(properties)
+  if (parsed.error) throw new Error(parsed.error)
+  doc.delete(key)
+  return { ...properties, yaml: doc.toString().replace(/\n$/, "") }
+}

package/src/gitbook/serialize.ts

@@ -27,6 +27,7 @@ import { attr } from "./attrs"
 import { normalizeLabel, serializeInline, serializeReference, withDocumentDefinitions } from "./inline"
 import { plainText } from "./inline"
 import { parseBlocks } from "./parse"
+import { taskMarker } from "./tasks"
 
 /** A `{% tag %}…{% endtag %}` container, block or item. */
 export type TaggedNode = HintNode | TabsNode | TabNode | StepperNode | StepNode | ColumnsNode | ColumnNode | UpdatesNode | UpdateNode
@@ -114,7 +115,9 @@ export function serializeMarkdown(doc: DocumentNode): string {
   documentCitations = citations
   try {
     return withDocumentDefinitions(defs, () => {
-      let out = doc.children.map((b, k) => `${blankLines(b, k ? 1 : 0)}${serializeBlock(b)}\n`).join("")
+      const properties = doc.properties
+      let out = properties ? `${properties.opening ?? "---"}\n${properties.yaml}${properties.yaml ? "\n" : ""}${properties.closing ?? "---"}\n` : ""
+      out += doc.children.map((b, k) => `${blankLines(b, k ? 1 : 0)}${serializeBlock(b)}\n`).join("")
       // Footnote definitions not placed in the document end it, as a group.
       const trailing = (doc.citations ?? []).filter((c) => !placed.has(c.id))
       if (trailing.length) {
@@ -537,7 +540,7 @@ function inlineToHtml(nodes: Inline[]): string {
 
 function serializeListItem(item: ListItemNode, list: ListNode, idx: number): string {
   const marker = item.marker ?? (list.ordered ? `${(list.start ?? 1) + idx}${list.delimiter ?? "."}` : (list.bullet ?? "-"))
-  const check = list.task ? `[${item.checked ? (item.checkMark ?? "x") : " "}] ` : ""
+  const check = list.task ? `[${taskMarker(item)}] ` : ""
   const [first, ...rest] = item.children
   const firstText = first?.type === "paragraph" ? serializeInline(first.children) : first ? serializeBlock(first) : ""
   const restText = rest.length ? "\n" + indent(serializeBlocks(rest), " ".repeat(item.indent ?? 2)) : ""

package/src/gitbook/tasks.ts

@@ -0,0 +1,25 @@
+import type { ListItemNode, TaskState } from "./ast"
+
+export const TASK_STATES: ReadonlyArray<{ id: TaskState; marker: string; label: string }> = [
+  { id: "pending", marker: " ", label: "Pending" },
+  { id: "in-progress", marker: "~", label: "In progress" },
+  { id: "implemented", marker: "?", label: "Implemented · evidence needed" },
+  { id: "blocked", marker: "b", label: "Blocked" },
+  { id: "parked", marker: "d", label: "Parked · verification debt" },
+  { id: "refuted", marker: "!", label: "Refuted" },
+  { id: "verified", marker: "x", label: "Verified" },
+  { id: "cancelled", marker: "-", label: "Cancelled" },
+]
+
+export function taskStateFromMarker(marker: string): TaskState | undefined {
+  return TASK_STATES.find((state) => state.marker === (marker === "X" ? "x" : marker))?.id
+}
+
+export function getTaskState(item: Pick<ListItemNode, "state" | "checked">): TaskState {
+  return item.state ?? (item.checked ? "verified" : "pending")
+}
+
+/** Explicit state wins; untouched uppercase `[X]` tasks retain their spelling. */
+export function taskMarker(item: Pick<ListItemNode, "state" | "checked" | "checkMark">): string {
+  return item.state ? TASK_STATES.find((state) => state.id === item.state)?.marker ?? " " : item.checked ? item.checkMark ?? "x" : " "
+}

package/src/index.ts

@@ -3,6 +3,13 @@
 export { GitbookStreamdown } from "./streamdown"
 export type { GitbookStreamdownProps } from "./streamdown"
 export { DocsRenderer, MarkdownContent } from "./docs/DocsRenderer"
+export { TaskCheckbox, TASK_STATE_ICONS } from "./docs/TaskCheckbox"
+export type { TaskCheckboxProps, TaskStateChangeHandler } from "./docs/TaskCheckbox"
+export { TASK_STATES, getTaskState, taskMarker, taskStateFromMarker } from "./gitbook/tasks"
+export { DocumentProperties } from "./docs/DocumentProperties"
+export type { DocumentPropertiesProps } from "./docs/DocumentProperties"
+export { readDocumentProperties, removeDocumentProperty, setDocumentProperty } from "./gitbook/properties"
+export type { DocumentPropertyValue, ParsedDocumentProperties } from "./gitbook/properties"
 export type { DocRenderOptions, LivePreviewProps, LivePreviewRenderer, SourceReferenceRenderer } from "./docs/DocsRenderer"
 export { DocPageActions } from "./docs/PageActions"
 export type { DocPageAction, DocPageActionsOptions, DocPageActionsProps } from "./docs/PageActions"

package/src/playground/ReactCodePreview.tsx

@@ -128,6 +128,14 @@ export function useAlmostNodeServer({ files, port = 4173, run, workspaceOptions,
           },
         })
 
+        // The iframe's virtual URL only works once the host page is controlled. Do not
+        // reload the host when a reader opens its first live example.
+        await workspace.container.serverBridge.ensureServiceWorkerReady({ reloadOnFirstControl: false })
+        if (cancelled) {
+          workspace.dispose()
+          return
+        }
+
         const result = await workspace.container.run(`vite --port ${port}`, {
           env: DETACHED_SERVER_ENV,
         })

package/src/streamdown.tsx

@@ -35,6 +35,8 @@ export function GitbookStreamdown({
   demoDependencies,
   demoVFS,
   pageActions,
+  documentProperties,
+  onTaskStateChange,
 }: GitbookStreamdownProps) {
   const content = markdown ?? children ?? ""
   const gitbookDoc = useMemo(
@@ -59,6 +61,8 @@ export function GitbookStreamdown({
         demoDependencies={demoDependencies}
         demoVFS={demoVFS}
         pageActions={isStreaming ? false : pageActions}
+        documentProperties={documentProperties}
+        onTaskStateChange={onTaskStateChange}
       />
     </div>
   )

package/src/styles.css

@@ -1,3 +1,5 @@
+@import "./docs/properties.css";
+@import "./docs/tasks.css";
 
 [data-docstream],
 .docs-article {