@hardlydifficult/document-generator 1.1.8 → 1.1.10

package/README.md

@@ -1,6 +1,6 @@
 # @hardlydifficult/document-generator
 
-Platform-agnostic document builder with chainable API and built-in output methods.
+Platform-agnostic document builder with chainable API and multi-format output (Markdown, Slack, plain text).
 
 ## Installation
 
@@ -31,91 +31,269 @@ console.log(document.toSlackText());
 console.log(document.toPlainText());
 ```
 
-## API
+## Core Blocks
 
-### `new Document()`
+Build documents by chaining block methods. All methods return `this` for fluent composition.
 
-Create a new document builder. All methods are chainable.
+```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
+```
+
+### Inline Markdown
+
+Text blocks support standard markdown formatting that auto-converts per platform:
+
+```typescript
+new Document().text('This has **bold**, *italic*, and ~~strikethrough~~ text.');
+```
+
+- **Markdown/Discord:** `**bold**`, `*italic*`, `~~strike~~` (unchanged)
+- **Slack:** Converts to `*bold*`, `_italic_`, `~strike~`
+- **Plain text:** Formatting stripped, text only
+
+## Structured Content
 
-### Chainable Methods
+### Sections
 
-| Method | Description |
-|--------|-------------|
-| `.header(text)` | Add a header/title |
-| `.text(content)` | Add text paragraph (supports **bold**, *italic*, ~~strike~~) |
-| `.list(items)` | Add a bulleted list |
-| `.divider()` | Add a horizontal divider |
-| `.context(text)` | Add footer/context text |
-| `.link(text, url)` | Add a hyperlink |
-| `.code(content)` | Add code (auto-detects inline vs multiline) |
-| `.image(url, alt?)` | Add an image |
-| `.section(title, content?, options?)` | Add a section (legacy header+divider, or bold title + body/list) |
-| `.field(label, value, options?)` | Add a single key-value line (e.g., `**ETA:** Tomorrow`) |
+Add titled sections with optional content (string or list of items):
 
-### `document.getBlocks(): Block[]`
+```typescript
+// Legacy style: header + divider
+doc.section("My Section");
+
+// With string content
+doc.section("Summary", "All systems operational");
 
-Get the internal block representation for custom processing.
+// With list items
+doc.section("Today", ["Ship feature", "Fix bug", "Review PR"]);
 
-### String Output Methods
+// With empty state
+doc.section("Blockers", [], { emptyText: "None." });
 
-| Method | Description |
-|--------|-------------|
-| `.toMarkdown()` | Render as standard markdown |
-| `.toSlackText()` | Render as Slack mrkdwn string |
-| `.toSlack()` | Alias for `.toSlackText()` |
-| `.toPlainText()` | Render as plain text (markdown stripped) |
-| `.render(format)` | Render via explicit format (`"markdown"`, `"slack"`, `"plaintext"`) |
+// Ordered list
+doc.section("Steps", ["First", "Second"], { ordered: true });
+```
 
-## Inline Markdown Support
+### Fields and Key-Value Pairs
 
-Text blocks support standard inline markdown that gets auto-converted per platform:
+Add single or multiple key-value lines:
 
 ```typescript
-new Document().text('This has **bold**, *italic*, and ~~strikethrough~~ text.');
+// 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
+```
+
+### Truncated Lists
+
+Display a limited number of items with an "X more" indicator:
+
+```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_
+
+// 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
+});
+```
+
+### Timestamps
+
+Add ISO timestamps with optional emoji and label:
+
+```typescript
+doc.timestamp();
+// Output: 🕐 2024-02-04T12:00:00.000Z
+
+doc.timestamp({ emoji: false });
+// Output: 2024-02-04T12:00:00.000Z
+
+doc.timestamp({ label: "Generated" });
+// Output: Generated 2024-02-04T12:00:00.000Z
+
+doc.timestamp({ date: new Date("2025-01-01") });
+// Output: 🕐 2025-01-01T00:00:00.000Z
 ```
 
-- Standard markdown: `**bold**`, `*italic*`, `~~strike~~`
-- Slack: Converted to `*bold*`, `_italic_`, `~strike~`
-- Discord: Uses standard markdown (no conversion needed)
-- Plain text: Formatting stripped
+## Output Formats
 
-**Note:** Use `.code()` and `.link()` methods for code and links—not markdown syntax.
+Convert documents to different formats with a single method call:
 
-## Code Blocks
+```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
+```
 
-The `.code()` method auto-detects format:
+## Linkification
+
+Transform text in document blocks (headers, paragraphs, lists, context) while preserving code and explicit links:
 
 ```typescript
-// Single line → inline code
-new Document().code('const x = 1');  // → `const x = 1`
+import { Document } from "@hardlydifficult/document-generator";
 
-// Multiline → code block
-new Document().code('const x = 1;\nconst y = 2;');
-// → ```
-//   const x = 1;
-//   const y = 2;
-//   ```
+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" }
+);
 ```
 
-## Outputters
+## Constructor Options
 
-### `toMarkdown(blocks): string`
+Initialize a document with pre-populated content:
 
-Convert to standard markdown format.
+```typescript
+const doc = new Document({
+  header: "Daily Report",
+  sections: [
+    { title: "Summary", content: "All systems operational" },
+    { content: "No blockers" }
+  ],
+  context: { Network: "mainnet", Status: "active" }
+});
+```
 
-### `toSlackText(blocks): string` / `toSlack(blocks): string`
+## Utility Methods
 
-Convert to Slack mrkdwn format.
+### `isEmpty()`
 
-### `toPlainText(blocks): string`
+Check if document has no blocks:
 
-Convert to plain text, stripping all formatting.
+```typescript
+const doc = new Document();
+doc.isEmpty(); // true
 
-Instance methods are recommended for typical usage; free outputter functions are useful when you already have a `Block[]` array.
+doc.text("Content");
+doc.isEmpty(); // false
+```
+
+### `clone()`
+
+Create a shallow copy of the document:
+
+```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
+```
+
+### `getBlocks()`
+
+Access the raw block array for custom processing:
+
+```typescript
+const blocks = doc.getBlocks();
+// blocks: Block[]
+```
+
+### `Document.truncate(text, maxLength)`
+
+Static utility to truncate text with ellipsis:
+
+```typescript
+Document.truncate("Hello world", 8); // "Hello..."
+Document.truncate("Hi", 10);         // "Hi"
+```
+
+## Direct Outputter Functions
+
+For cases where you already have a `Block[]` array, use outputter functions directly:
+
+```typescript
+import { toMarkdown, toSlackText, toPlainText } from '@hardlydifficult/document-generator';
+
+const blocks = [
+  { type: 'header', text: 'Title' },
+  { type: 'text', content: 'Body' }
+];
+
+toMarkdown(blocks);   // # Title\n\nBody\n\n
+toSlackText(blocks);  // *Title*\n\nBody\n\n
+toPlainText(blocks);  // TITLE\n\nBody\n\n
+```
+
+## Markdown Conversion Utilities
+
+Convert or strip markdown formatting for custom outputters:
+
+```typescript
+import { convertMarkdown, stripMarkdown } from '@hardlydifficult/document-generator';
+
+// Convert to platform-specific format
+convertMarkdown("**bold** and *italic*", "slack");
+// → "*bold* and _italic_"
+
+convertMarkdown("**bold** and *italic*", "markdown");
+// → "**bold** and *italic*"
+
+// Strip all markdown
+stripMarkdown("**bold** and *italic*");
+// → "bold and italic"
+```
 
 ## Block Types
 
-Internal block types for custom processing:
+Internal block structure for advanced use cases:
 
 ```typescript
 type Block =
@@ -150,36 +328,16 @@ const report = new Document()
 await channel.postMessage(report);
 ```
 
-## Linkifying Text Blocks
-
-Apply an issue/PR linker to document text-bearing blocks (`header`, `text`, `list`, `context`) while leaving explicit `code` and `link` blocks unchanged.
-
-```typescript
-import { Document } from "@hardlydifficult/document-generator";
-import { createLinker } from "@hardlydifficult/text";
-
-const linker = createLinker()
-  .linear("fairmint")
-  .githubPr("Fairmint/api");
-
-const doc = new Document()
-  .header("Sprint Update ENG-533")
-  .text("Shipped ENG-533 and reviewed PR#42")
-  .code("ENG-533 inside code is untouched")
-  .link("PR", "https://github.com/Fairmint/api/pull/42")
-  .linkify(linker, { platform: "slack" });
-```
-
-`linkify()` also accepts a simple `(text) => text` transformer function.
-
-## Structured Sections and Fields
-
-For status updates and standups, use `section` and `field` to keep client code concise:
-
-```typescript
-const detail = new Document()
-  .section("Yesterday", ["Reviewed PR #42", "Fixed flaky test"])
-  .section("Today", ["Ship ENG-533", "Pair on migration"])
-  .section("Blockers", [], { emptyText: "None." })
-  .field("ETA", "Tomorrow");
-```
+## Appendix: Platform Differences
+
+| Feature | Markdown | Slack | Plain Text |
+|---------|----------|-------|-----------|
+| **Bold** | `**text**` | `*text*` | text |
+| *Italic* | `*text*` | `_text_` | text |
+| ~~Strike~~ | `~~text~~` | `~text~` | text |
+| Headers | `# Title` | `*Title*` | TITLE |
+| Dividers | `---` | `────────────────` | `────────────────` |
+| Links | `[text](url)` | `<url\|text>` | `text (url)` |
+| Code (inline) | `` `code` `` | `` `code` `` | code |
+| Code (block) | ` ```code``` ` | ` ```code``` ` | code |
+| Images | `![alt](url)` | `Image: <url\|alt>` | `[Image: alt]` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hardlydifficult/document-generator",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -17,5 +17,16 @@
     "typescript": "5.9.3",
     "@types/node": "25.2.3",
     "vitest": "4.0.18"
+  },
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
   }
 }