@knpkv/confluence-to-markdown 0.2.0 → 0.4.1

package/src/ast/InlineNode.ts

@@ -0,0 +1,323 @@
+/**
+ * Inline AST node types for text-level content.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+
+/**
+ * Optional raw Confluence HTML for exact roundtrip preservation.
+ * When present, the Confluence serializer will output this instead of reconstructing.
+ *
+ * @category InlineNode
+ */
+export const RawConfluence = Schema.optional(Schema.String)
+
+/**
+ * Plain text content.
+ *
+ * @example
+ * ```typescript
+ * import { Text } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const text = new Text({ value: "Hello world" })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Text extends Schema.TaggedClass<Text>()("Text", {
+  value: Schema.String
+}) {}
+
+/**
+ * Inline code span.
+ *
+ * @example
+ * ```typescript
+ * import { InlineCode } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const code = new InlineCode({ value: "const x = 1" })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class InlineCode extends Schema.TaggedClass<InlineCode>()("InlineCode", {
+  value: Schema.String
+}) {}
+
+/**
+ * Line break element.
+ *
+ * @example
+ * ```typescript
+ * import { LineBreak } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const br = new LineBreak({})
+ * ```
+ *
+ * @category InlineNode
+ */
+export class LineBreak extends Schema.TaggedClass<LineBreak>()("LineBreak", {}) {}
+
+/**
+ * Unsupported inline element - preserves raw content for round-tripping.
+ *
+ * @example
+ * ```typescript
+ * import { UnsupportedInline } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const unknown = new UnsupportedInline({
+ *   raw: "<custom-tag>content</custom-tag>",
+ *   source: "confluence"
+ * })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class UnsupportedInline extends Schema.TaggedClass<UnsupportedInline>()("UnsupportedInline", {
+  raw: Schema.String,
+  source: Schema.Literal("confluence", "markdown")
+}) {}
+
+/**
+ * Emoticon/emoji element.
+ *
+ * @example
+ * ```typescript
+ * import { Emoticon } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const emoji = new Emoticon({
+ *   shortname: ":grinning:",
+ *   emojiId: "1f600",
+ *   fallback: "😀"
+ * })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Emoticon extends Schema.TaggedClass<Emoticon>()("Emoticon", {
+  shortname: Schema.String,
+  emojiId: Schema.String,
+  fallback: Schema.String,
+  rawConfluence: RawConfluence
+}) {}
+
+/**
+ * User mention element.
+ *
+ * @example
+ * ```typescript
+ * import { UserMention } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const mention = new UserMention({ accountId: "557058:..." })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class UserMention extends Schema.TaggedClass<UserMention>()("UserMention", {
+  accountId: Schema.String,
+  rawConfluence: RawConfluence
+}) {}
+
+/**
+ * Date/time element.
+ *
+ * @example
+ * ```typescript
+ * import { DateTime } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const date = new DateTime({ datetime: "2026-01-01" })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class DateTime extends Schema.TaggedClass<DateTime>()("DateTime", {
+  datetime: Schema.String,
+  rawConfluence: RawConfluence
+}) {}
+
+/**
+ * Underlined text.
+ *
+ * @category InlineNode
+ */
+export class Underline extends Schema.TaggedClass<Underline>()("Underline", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Subscript text.
+ *
+ * @category InlineNode
+ */
+export class Subscript extends Schema.TaggedClass<Subscript>()("Subscript", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Superscript text.
+ *
+ * @category InlineNode
+ */
+export class Superscript extends Schema.TaggedClass<Superscript>()("Superscript", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Strikethrough text.
+ *
+ * @category InlineNode
+ */
+export class Strikethrough extends Schema.TaggedClass<Strikethrough>()("Strikethrough", {
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Colored text with CSS color value.
+ *
+ * @category InlineNode
+ */
+export class ColoredText extends Schema.TaggedClass<ColoredText>()("ColoredText", {
+  color: Schema.String,
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+/**
+ * Highlighted text with background color.
+ *
+ * @category InlineNode
+ */
+export class Highlight extends Schema.TaggedClass<Highlight>()("Highlight", {
+  backgroundColor: Schema.String,
+  children: Schema.suspend(() => Schema.Array(InlineNodeBase))
+}) {}
+
+// Forward declaration for recursive types
+// Define InlineNode union schema first (without recursive types)
+const InlineNodeBase = Schema.Union(
+  Text,
+  InlineCode,
+  LineBreak,
+  Emoticon,
+  UserMention,
+  DateTime,
+  UnsupportedInline
+)
+
+/**
+ * Inline node children schema - use this for recursive inline content.
+ *
+ * @category InlineNode
+ */
+export const InlineNodeChildren: Schema.Schema<ReadonlyArray<InlineNode>> = Schema.suspend(
+  () => Schema.Array(InlineNode)
+)
+
+/**
+ * Strong/bold text.
+ *
+ * @example
+ * ```typescript
+ * import { Strong, Text } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const bold = new Strong({ children: [new Text({ value: "important" })] })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Strong extends Schema.TaggedClass<Strong>()("Strong", {
+  children: Schema.Array(InlineNodeBase)
+}) {}
+
+/**
+ * Emphasized/italic text.
+ *
+ * @example
+ * ```typescript
+ * import { Emphasis, Text } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const italic = new Emphasis({ children: [new Text({ value: "emphasized" })] })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Emphasis extends Schema.TaggedClass<Emphasis>()("Emphasis", {
+  children: Schema.Array(InlineNodeBase)
+}) {}
+
+/**
+ * Hyperlink with optional title.
+ *
+ * @example
+ * ```typescript
+ * import { Link, Text } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const link = new Link({
+ *   href: "https://example.com",
+ *   title: "Example",
+ *   children: [new Text({ value: "Click here" })]
+ * })
+ * ```
+ *
+ * @category InlineNode
+ */
+export class Link extends Schema.TaggedClass<Link>()("Link", {
+  href: Schema.String,
+  title: Schema.optional(Schema.String),
+  children: Schema.Array(InlineNodeBase),
+  rawConfluence: RawConfluence
+}) {}
+
+/**
+ * Union of all inline node types.
+ *
+ * @category InlineNode
+ */
+export const InlineNode = Schema.Union(
+  Text,
+  Strong,
+  Emphasis,
+  InlineCode,
+  Link,
+  LineBreak,
+  Emoticon,
+  UserMention,
+  DateTime,
+  Underline,
+  Subscript,
+  Superscript,
+  Strikethrough,
+  ColoredText,
+  Highlight,
+  UnsupportedInline
+)
+
+/**
+ * Type for inline nodes.
+ *
+ * @category Types
+ */
+export type InlineNode =
+  | Text
+  | Strong
+  | Emphasis
+  | InlineCode
+  | Link
+  | LineBreak
+  | Emoticon
+  | UserMention
+  | DateTime
+  | Underline
+  | Subscript
+  | Superscript
+  | Strikethrough
+  | ColoredText
+  | Highlight
+  | UnsupportedInline
+
+/**
+ * Schema type helper for InlineNode.
+ *
+ * @category Types
+ */
+export type InlineNodeSchema = typeof InlineNode

package/src/ast/MacroNode.ts

@@ -0,0 +1,245 @@
+/**
+ * Confluence macro AST node types.
+ *
+ * @module
+ */
+import * as Schema from "effect/Schema"
+import {
+  CodeBlock,
+  Heading,
+  Image,
+  Paragraph,
+  RawConfluence,
+  SchemaVersion,
+  Table,
+  ThematicBreak,
+  UnsupportedBlock
+} from "./BlockNode.js"
+
+// Reuse SimpleBlockNode for macro children
+const SimpleBlockNode = Schema.Union(
+  Heading,
+  Paragraph,
+  CodeBlock,
+  ThematicBreak,
+  Image,
+  Table,
+  UnsupportedBlock
+)
+
+/**
+ * Supported panel type names.
+ * Single source of truth for all panel macros.
+ *
+ * @category MacroNode
+ */
+export const PanelTypes = ["info", "warning", "note", "tip", "error", "panel"] as const
+
+/**
+ * Panel type for info/warning/note macros.
+ *
+ * @category MacroNode
+ */
+export const PanelType = Schema.Literal(...PanelTypes)
+
+/**
+ * Type for panel type.
+ *
+ * @category Types
+ */
+export type PanelType = Schema.Schema.Type<typeof PanelType>
+
+/**
+ * Info/Warning/Note panel macro.
+ *
+ * Represents Confluence info, warning, note, tip, and error panels.
+ * In Markdown, rendered as `:::info`, `:::warning`, etc. container syntax.
+ *
+ * @example
+ * ```typescript
+ * import { InfoPanel, Paragraph, Text } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const panel = {
+ *   _tag: "InfoPanel" as const,
+ *   panelType: "warning" as const,
+ *   title: "Important",
+ *   children: [new Paragraph({ children: [new Text({ value: "Be careful!" })] })]
+ * }
+ * ```
+ *
+ * @category MacroNode
+ */
+export const InfoPanel = Schema.Struct({
+  _tag: Schema.Literal("InfoPanel"),
+  version: SchemaVersion,
+  panelType: PanelType,
+  title: Schema.optional(Schema.String),
+  children: Schema.Array(SimpleBlockNode),
+  rawConfluence: RawConfluence
+})
+
+/**
+ * Type for InfoPanel.
+ *
+ * @category Types
+ */
+export type InfoPanel = Schema.Schema.Type<typeof InfoPanel>
+
+/**
+ * Expand/collapse macro.
+ *
+ * Represents Confluence expand macro for collapsible content.
+ * In Markdown, rendered as `:::details` container syntax.
+ *
+ * @example
+ * ```typescript
+ * import { ExpandMacro, Paragraph, Text } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const expand = {
+ *   _tag: "ExpandMacro" as const,
+ *   title: "Click to expand",
+ *   children: [new Paragraph({ children: [new Text({ value: "Hidden content" })] })]
+ * }
+ * ```
+ *
+ * @category MacroNode
+ */
+export const ExpandMacro = Schema.Struct({
+  _tag: Schema.Literal("ExpandMacro"),
+  version: SchemaVersion,
+  title: Schema.optional(Schema.String),
+  children: Schema.Array(SimpleBlockNode),
+  rawConfluence: RawConfluence
+})
+
+/**
+ * Type for ExpandMacro.
+ *
+ * @category Types
+ */
+export type ExpandMacro = Schema.Schema.Type<typeof ExpandMacro>
+
+/**
+ * Table of contents macro.
+ *
+ * Represents Confluence TOC macro for auto-generated table of contents.
+ * In Markdown, rendered as `[[toc]]` or similar marker.
+ *
+ * @example
+ * ```typescript
+ * import { TocMacro } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const toc = {
+ *   _tag: "TocMacro" as const,
+ *   minLevel: 2,
+ *   maxLevel: 4
+ * }
+ * ```
+ *
+ * @category MacroNode
+ */
+export const TocMacro = Schema.Struct({
+  _tag: Schema.Literal("TocMacro"),
+  version: SchemaVersion,
+  minLevel: Schema.optional(Schema.Number),
+  maxLevel: Schema.optional(Schema.Number),
+  rawConfluence: RawConfluence
+})
+
+/**
+ * Type for TocMacro.
+ *
+ * @category Types
+ */
+export type TocMacro = Schema.Schema.Type<typeof TocMacro>
+
+/**
+ * Code macro with syntax highlighting.
+ *
+ * Represents Confluence code macro with language and options.
+ * Different from CodeBlock in that it preserves Confluence-specific options.
+ *
+ * @example
+ * ```typescript
+ * import { CodeMacro } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const code = {
+ *   _tag: "CodeMacro" as const,
+ *   language: "typescript",
+ *   title: "Example",
+ *   code: "const x = 1",
+ *   lineNumbers: true
+ * }
+ * ```
+ *
+ * @category MacroNode
+ */
+export const CodeMacro = Schema.Struct({
+  _tag: Schema.Literal("CodeMacro"),
+  version: SchemaVersion,
+  language: Schema.optional(Schema.String),
+  title: Schema.optional(Schema.String),
+  code: Schema.String,
+  lineNumbers: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  collapse: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+  firstLine: Schema.optional(Schema.Number),
+  rawConfluence: RawConfluence
+})
+
+/**
+ * Type for CodeMacro.
+ *
+ * @category Types
+ */
+export type CodeMacro = Schema.Schema.Type<typeof CodeMacro>
+
+/**
+ * Status macro (colored label).
+ *
+ * @example
+ * ```typescript
+ * import { StatusMacro } from "@knpkv/confluence-to-markdown/ast"
+ *
+ * const status = {
+ *   _tag: "StatusMacro" as const,
+ *   text: "In Progress",
+ *   color: "Blue"
+ * }
+ * ```
+ *
+ * @category MacroNode
+ */
+export const StatusMacro = Schema.Struct({
+  _tag: Schema.Literal("StatusMacro"),
+  version: SchemaVersion,
+  text: Schema.String,
+  color: Schema.Literal("Grey", "Red", "Yellow", "Green", "Blue"),
+  rawConfluence: RawConfluence
+})
+
+/**
+ * Type for StatusMacro.
+ *
+ * @category Types
+ */
+export type StatusMacro = Schema.Schema.Type<typeof StatusMacro>
+
+/**
+ * Union of all macro node types.
+ *
+ * @category MacroNode
+ */
+export const MacroNode = Schema.Union(
+  InfoPanel,
+  ExpandMacro,
+  TocMacro,
+  CodeMacro,
+  StatusMacro
+)
+
+/**
+ * Type for macro nodes.
+ *
+ * @category Types
+ */
+export type MacroNode = InfoPanel | ExpandMacro | TocMacro | CodeMacro | StatusMacro

package/src/ast/index.ts

@@ -0,0 +1,83 @@
+/**
+ * AST node types for Confluence <-> Markdown conversion.
+ *
+ * @module
+ */
+
+// Inline nodes
+export {
+  ColoredText,
+  DateTime,
+  Emoticon,
+  Emphasis,
+  Highlight,
+  InlineCode,
+  InlineNode,
+  type InlineNode as InlineNodeType,
+  LineBreak,
+  Link,
+  Strikethrough,
+  Strong,
+  Subscript,
+  Superscript,
+  Text,
+  Underline,
+  UnsupportedInline,
+  UserMention
+} from "./InlineNode.js"
+
+// Block nodes
+export {
+  BlockNode,
+  type BlockNode as BlockNodeType,
+  BlockQuote,
+  CodeBlock,
+  Heading,
+  Image,
+  ImageAttachment,
+  type ImageAttachment as ImageAttachmentType,
+  List,
+  ListItem,
+  Paragraph,
+  SchemaVersion,
+  Table,
+  TableCell,
+  TableRow,
+  TaskItem,
+  type TaskItem as TaskItemType,
+  TaskList,
+  type TaskList as TaskListType,
+  TextAlignment,
+  type TextAlignment as TextAlignmentValue,
+  ThematicBreak,
+  UnsupportedBlock
+} from "./BlockNode.js"
+
+// Macro nodes
+export {
+  CodeMacro,
+  type CodeMacro as CodeMacroType,
+  ExpandMacro,
+  type ExpandMacro as ExpandMacroType,
+  InfoPanel,
+  type InfoPanel as InfoPanelType,
+  MacroNode,
+  type MacroNode as MacroNodeType,
+  PanelType,
+  type PanelType as PanelTypeValue,
+  PanelTypes,
+  StatusMacro,
+  type StatusMacro as StatusMacroType,
+  TocMacro,
+  type TocMacro as TocMacroType
+} from "./MacroNode.js"
+
+// Document
+export {
+  Document,
+  type Document as DocumentType,
+  DocumentNode,
+  type DocumentNode as DocumentNodeType,
+  isDocument,
+  makeDocument
+} from "./Document.js"