@hardlydifficult/document-generator 1.1.12 → 1.1.13

package/README.md

@@ -11,284 +11,260 @@ npm install @hardlydifficult/document-generator
 ## Quick Start
 
 ```typescript
-import { Document } from '@hardlydifficult/document-generator';
+import { Document } from "@hardlydifficult/document-generator";
 
-const document = new Document()
-  .header("Weekly Report")
-  .text("Summary of this week's **key highlights**.")
-  .list(["Completed feature A", "Fixed bug B", "Started project C"])
-  .divider()
-  .link("View details", "https://example.com")
-  .context("Generated on 2025-01-15");
+const doc = new Document({
+  header: "Release Notes",
+  sections: [
+    { title: "New Features", content: "Ship onboarding flow\nFix retry bug" },
+  ],
+  context: { Network: "mainnet", Status: "active" },
+});
 
-// Output as markdown
-console.log(document.toMarkdown());
+console.log(doc.toMarkdown());
+// # Release Notes
+//
+// **New Features**
+// Ship onboarding flow
+// Fix retry bug
+//
+// ---
+//
+// *Network: mainnet, Status: active*
+
+console.log(doc.toSlack());
+// *Release Notes*
+//
+// **New Features**
+// Ship onboarding flow
+// Fix retry bug
+//
+// ────────────────
+//
+// Network: mainnet, Status: active
+```
 
-// Output as Slack mrkdwn
-console.log(document.toSlackText());
+## Core Document API
 
-// Output as plain text
-console.log(document.toPlainText());
-```
+The `Document` class provides a fluent, chainable builder for structured content.
 
-## Core Blocks
+### Constructor
 
-Build documents by chaining block methods. All methods return `this` for fluent composition.
+Creates a new document, optionally initialized with header, sections, and context.
 
 ```typescript
-const doc = new Document()
-  .header("Title")                           // # Title
-  .text("Paragraph with **bold** text")      // Supports inline markdown
-  .list(["Item 1", "Item 2"])                // Bulleted list
-  .divider()                                 // Horizontal line
-  .link("Click here", "https://example.com") // Hyperlink
-  .code("const x = 1;")                      // Inline or multiline code
-  .image("https://example.com/img.png")      // Image with optional alt text
-  .context("Footer text");                   // Italicized context
+const doc = new Document({
+  header: "My Report",
+  sections: [
+    { title: "Summary", content: "All systems operational" },
+    { content: "No issues found" },
+  ],
+  context: { Network: "mainnet", Status: "active" },
+});
 ```
 
-### Inline Markdown
+### Block Methods
 
-Text blocks support standard markdown formatting that auto-converts per platform:
+These methods add specific block types and return `this` for chaining.
 
 ```typescript
-new Document().text('This has **bold**, *italic*, and ~~strikethrough~~ text.');
+const doc = new Document()
+  .header("Title")
+  .text("Content")
+  .list(["Item 1", "Item 2"])
+  .divider()
+  .context("Context text")
+  .link("Visit Site", "https://example.com")
+  .code("const x = 1;")
+  .image("https://example.com/image.png", "Alt text");
 ```
 
-- **Markdown/Discord:** `**bold**`, `*italic*`, `~~strike~~` (unchanged)
-- **Slack:** Converts to `*bold*`, `_italic_`, `~strike~`
-- **Plain text:** Formatting stripped, text only
+### Convenience Methods
 
-## Structured Content
+#### `section(title, content?, options?)`
 
-### Sections
-
-Add titled sections with optional content (string or list of items):
+Renders section titles as bold with optional content.
 
 ```typescript
-// Legacy style: header + divider
-doc.section("My Section");
-
-// With string content
-doc.section("Summary", "All systems operational");
+doc.section("Summary").text("All systems green");
+// Output: **Summary**\nAll systems green
 
-// With list items
-doc.section("Today", ["Ship feature", "Fix bug", "Review PR"]);
+doc.section("Today", ["Ship onboarding", "Fix flaky test"]);
+// Output: **Today**\n- Ship onboarding\n- Fix flaky test
 
-// With empty state
 doc.section("Blockers", [], { emptyText: "None." });
-
-// Ordered list
-doc.section("Steps", ["First", "Second"], { ordered: true });
+// Output: **Blockers**\n- None.
 ```
 
-### Fields and Key-Value Pairs
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `emptyText` | `string` | _none_ | Fallback when content is empty |
+| `ordered` | `boolean` | `false` | Render list as numbered instead of bullets |
+| `divider` | `boolean` | `false` | Insert divider before section output |
+
+#### `field(label, value, options?)`
 
-Add single or multiple key-value lines:
+Renders a single key-value pair.
 
 ```typescript
-// Single field
 doc.field("ETA", "Tomorrow");
-// Output: **ETA**: Tomorrow
-
-// Multiple fields
-doc.keyValue({ Network: "mainnet", Status: "active" });
-// Output: **Network**: mainnet\n**Status**: active
-
-// With styling options
-doc.keyValue(
-  { Name: "Alice", Role: "Admin" },
-  { style: "bullet", separator: " =", bold: false }
-);
-// Output: • Name = Alice\n• Role = Admin
+// Output: **ETA:** Tomorrow
+
+doc.field("Blockers", "", { emptyText: "None." });
+// Output: **Blockers:** None.
 ```
 
-### Truncated Lists
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `emptyText` | `string` | _none_ | Fallback when value is empty |
+| `separator` | `string` | `":"` | Separator between label and value |
+| `bold` | `boolean` | `true` | Whether to bold the label |
 
-Display a limited number of items with an "X more" indicator:
+#### `keyValue(data, options?)`
+
+Formats an object as key-value lines.
 
 ```typescript
-doc.truncatedList(
-  ["Item 1", "Item 2", "Item 3", "Item 4", "Item 5"],
-  { limit: 3 }
-);
-// Output:
-// • Item 1
-// • Item 2
-// • Item 3
-// _... and 2 more_
+doc.keyValue({ Name: "Alice", Role: "Admin" });
+// Output: **Name:** Alice\n**Role:** Admin
 
-// Custom formatting
-const users = [{ name: "Alice" }, { name: "Bob" }, { name: "Charlie" }];
-doc.truncatedList(users, {
-  limit: 2,
-  format: (u) => u.name,
-  moreText: (n) => `Plus ${n} others`,
-  ordered: true
-});
+doc.keyValue({ A: "1", B: "2" }, { style: "bullet" });
+// Output: • **A**: 1\n• **B**: 2
 ```
 
-### Timestamps
-
-Add ISO timestamps with optional emoji and label:
-
-```typescript
-doc.timestamp();
-// Output: 🕐 2024-02-04T12:00:00.000Z
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `style` | `"plain" \| "bullet" \| "numbered"` | `"plain"` | List style |
+| `separator` | `string` | `":"` | Key-value separator |
+| `bold` | `boolean` | `true` | Bold the keys |
 
-doc.timestamp({ emoji: false });
-// Output: 2024-02-04T12:00:00.000Z
+#### `truncatedList(items, options?)`
 
-doc.timestamp({ label: "Generated" });
-// Output: Generated 2024-02-04T12:00:00.000Z
+Renders a list with automatic truncation.
 
-doc.timestamp({ date: new Date("2025-01-01") });
-// Output: 🕐 2025-01-01T00:00:00.000Z
+```typescript
+doc.truncatedList(["a", "b", "c", "d", "e"], { limit: 3 });
+// Output:
+// • a
+// • b
+// • c
+// _... and 2 more_
 ```
 
-## Output Formats
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `limit` | `number` | `10` | Maximum items to show |
+| `format` | `(item, index) => string` | `String` | Custom formatter |
+| `moreText` | `(remaining) => string` | `_... and N more_` | Truncation text |
+| `ordered` | `boolean` | `false` | Numbered list |
+
+#### `timestamp(options?)`
 
-Convert documents to different formats with a single method call:
+Adds a timestamp in context format.
 
 ```typescript
-const doc = new Document()
-  .header("Report")
-  .text("Status: **active**");
-
-doc.toMarkdown();   // # Report\n\nStatus: **active**
-doc.toSlackText();  // *Report*\n\nStatus: *active*
-doc.toSlack();      // Alias for toSlackText()
-doc.toPlainText();  // REPORT\n\nStatus: active
-
-// Or use render() with explicit format
-doc.render("markdown");   // Standard markdown
-doc.render("slack");      // Slack mrkdwn
-doc.render("plaintext");  // Plain text
+doc.timestamp(); // 🕐 2024-02-04T12:00:00.000Z
+doc.timestamp({ emoji: false }); // 2024-02-04T12:00:00.000Z
+doc.timestamp({ label: "Generated" }); // Generated 2024-02-04T...
 ```
 
-## Linkification
-
-Transform text in document blocks (headers, paragraphs, lists, context) while preserving code and explicit links:
-
-```typescript
-import { Document } from "@hardlydifficult/document-generator";
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `date` | `Date` | `new Date()` | Custom date |
+| `emoji` | `boolean` | `true` | Include clock emoji |
+| `label` | `string` | _none_ | Prefix label |
 
-const doc = new Document()
-  .header("Sprint ENG-533")
-  .text("Shipped ENG-533 and reviewed PR#42")
-  .code("ENG-533 inside code is untouched")
-  .link("PR", "https://github.com/example/pull/42");
-
-// Simple function transformer
-doc.linkify((text) => text.replace("ENG-533", "[ENG-533](...)"));
-
-// Linker-style object with platform awareness
-doc.linkify(
-  {
-    linkText: (text, { platform }) => {
-      if (text.includes("ENG-")) {
-        return `[${text}](https://linear.app/...)`;
-      }
-      return text;
-    }
-  },
-  { platform: "slack" }
-);
-```
+### Utility Methods
 
-## Constructor Options
+#### `linkify(transform, options?)`
 
-Initialize a document with pre-populated content:
+Applies transformations to text-bearing blocks (headers, paragraphs, lists, context).
 
 ```typescript
-const doc = new Document({
-  header: "Daily Report",
-  sections: [
-    { title: "Summary", content: "All systems operational" },
-    { content: "No blockers" }
-  ],
-  context: { Network: "mainnet", Status: "active" }
-});
-```
+doc.linkify((text) => text.toUpperCase());
 
-## Utility Methods
+// Example with linkText-style transformer:
+doc.linkify({ linkText: (t) => t.replace("ENG-533", "LINKED") }, { platform: "slack" });
+```
 
-### `isEmpty()`
+#### `isEmpty(): boolean`
 
-Check if document has no blocks:
+Returns `true` if no blocks have been added.
 
 ```typescript
-const doc = new Document();
-doc.isEmpty(); // true
-
-doc.text("Content");
-doc.isEmpty(); // false
+new Document().isEmpty(); // true
+new Document().text("Content").isEmpty(); // false
 ```
 
-### `clone()`
+#### `clone(): Document`
 
-Create a shallow copy of the document:
+Creates a shallow copy.
 
 ```typescript
-const original = new Document().header("Title").text("Content");
-const copy = original.clone();
-
-copy.text("Added to copy");
-// original still has 2 blocks, copy has 3
+const doc1 = new Document().header("Title");
+const doc2 = doc1.clone();
+doc2.text("Extra"); // does not affect doc1
 ```
 
-### `getBlocks()`
+#### `getBlocks(): Block[]`
 
-Access the raw block array for custom processing:
+Returns the internal blocks array for inspection.
 
 ```typescript
-const blocks = doc.getBlocks();
-// blocks: Block[]
+const blocks = new Document().header("Title").getBlocks();
+// [{ type: "header", text: "Title" }]
 ```
 
-### `Document.truncate(text, maxLength)`
+### Output Methods
 
-Static utility to truncate text with ellipsis:
+Render the document to different formats.
 
 ```typescript
-Document.truncate("Hello world", 8); // "Hello..."
-Document.truncate("Hi", 10);         // "Hi"
+const doc = new Document().text("Hello **world**");
+
+doc.toMarkdown(); // "**world**" preserved
+doc.toSlack(); // "*world*" (italic)
+doc.toPlainText(); // "world" (stripped)
+doc.render("slack"); // same as toSlack()
 ```
 
 ## Direct Outputter Functions
 
-For cases where you already have a `Block[]` array, use outputter functions directly:
+Use the outputters directly without `Document` if you have raw blocks.
 
 ```typescript
-import { toMarkdown, toSlackText, toPlainText } from '@hardlydifficult/document-generator';
+import { toMarkdown, toPlainText, toSlackText } from "@hardlydifficult/document-generator";
 
 const blocks = [
-  { type: 'header', text: 'Title' },
-  { type: 'text', content: 'Body' }
+  { type: "header", text: "Title" },
+  { type: "text", content: "Body with **bold**" },
 ];
 
-toMarkdown(blocks);   // # Title\n\nBody\n\n
-toSlackText(blocks);  // *Title*\n\nBody\n\n
-toPlainText(blocks);  // TITLE\n\nBody\n\n
+console.log(toMarkdown(blocks)); // # Title\n\nBody with **bold**
+console.log(toSlackText(blocks)); // *Title*\n\nBody with *bold*
+console.log(toPlainText(blocks)); // TITLE\n\nBody with bold
 ```
 
-## Markdown Conversion Utilities
+## Markdown Conversion
 
-Convert or strip markdown formatting for custom outputters:
+### `convertMarkdown(text, platform)`
+
+Converts inline markdown formatting to target platform syntax.
 
 ```typescript
-import { convertMarkdown, stripMarkdown } from '@hardlydifficult/document-generator';
+convertMarkdown("**bold** and *italic*", "slack"); // "*bold* and _italic_"
+convertMarkdown("~~strike~~", "discord"); // "~~strike~~"
+convertMarkdown("**bold**", "plaintext"); // "bold"
+```
 
-// Convert to platform-specific format
-convertMarkdown("**bold** and *italic*", "slack");
-// → "*bold* and _italic_"
+Supported platforms: `"markdown"`, `"slack"`, `"discord"`, `"plaintext"`
 
-convertMarkdown("**bold** and *italic*", "markdown");
-// → "**bold** and *italic*"
+### `stripMarkdown(text)`
 
-// Strip all markdown
-stripMarkdown("**bold** and *italic*");
-// → "bold and italic"
+Strips all formatting and returns plain text.
+
+```typescript
+stripMarkdown("**bold** and *italic* and ~~strike~~"); // "bold and italic and strike"
 ```
 
 ## Block Types
@@ -307,6 +283,22 @@ type Block =
   | { type: 'image'; url: string; alt?: string };
 ```
 
+## Types
+
+All exported types are listed below:
+
+| Name | Description |
+|--|--|
+| `Block` | Union type of all block types |
+| `HeaderBlock`, `TextBlock`, `ListBlock`, `DividerBlock`, `ContextBlock`, `LinkBlock`, `CodeBlock`, `ImageBlock` | Block structures |
+| `Platform` | `"markdown" \| "slack" \| "discord" \| "plaintext"` |
+| `StringOutputFormat` | `"markdown" \| "slack" \| "plaintext"` |
+| `DocumentOptions`, `DocumentSection` | Constructor options |
+| `SectionOptions`, `FieldOptions`, `KeyValueOptions` | Formatting options |
+| `TruncatedListOptions<T>` | Truncation configuration |
+| `TimestampOptions` | Timestamp configuration |
+| `DocumentLinkifier`, `DocumentLinkTransform`, `DocumentLinkifyOptions` | Link transformation types |
+
 ## Integration with @hardlydifficult/chat
 
 Documents integrate seamlessly with the chat package for Slack and Discord:
@@ -331,7 +323,7 @@ await channel.postMessage(report);
 ## Appendix: Platform Differences
 
 | Feature | Markdown | Slack | Plain Text |
-|---------|----------|-------|-----------|
+|---------|---------|-------|-----------|
 | **Bold** | `**text**` | `*text*` | text |
 | *Italic* | `*text*` | `_text_` | text |
 | ~~Strike~~ | `~~text~~` | `~text~` | text |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/document-generator",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [