{"_id":"@ascii-graphs/renderer-confluence","name":"@ascii-graphs/renderer-confluence","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ascii-graphs/renderer-confluence","version":"0.1.0","description":"Native Confluence Cloud documents for portable ASCII charts","keywords":["ascii","charts","confluence","adf","text","accessibility"],"author":{"name":"Juan Víctor Izquierdo"},"repository":{"type":"git","url":"git+https://github.com/juanviizquierdo/ascii_graphs.git"},"type":"module","sideEffects":false,"license":"MIT","engines":{"node":">=20"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"dependencies":{"@ascii-graphs/core":"0.1.0","@ascii-graphs/renderer-text":"0.1.0"},"devDependencies":{"tsup":"^8.5.0","typescript":"^5.8.3"},"publishConfig":{"access":"public","provenance":true,"tag":"latest"},"gitHead":"a29f15ab1ec7ab8ee4a5ce57364e0ca311ec3a78","scripts":{"build":"tsup src/index.ts --format esm --dts --clean","typecheck":"tsc --noEmit"},"_id":"@ascii-graphs/renderer-confluence@0.1.0","bugs":{"url":"https://github.com/juanviizquierdo/ascii_graphs/issues"},"homepage":"https://github.com/juanviizquierdo/ascii_graphs#readme","_integrity":"sha512-I7GZQeQIw5Ht10cnKChRFkr23rJmEf7sVHqUeDtvuKxeI8DV/0TcQ5F8+5JQHfavSITej6RKgwdlRvx/+QDMPA==","_resolved":"/tmp/ascii-graphs-release-33103858320.QRClYi/artifacts/ascii-graphs-renderer-confluence-0.1.0.tgz","_from":"file:/tmp/ascii-graphs-release-33103858320.QRClYi/artifacts/ascii-graphs-renderer-confluence-0.1.0.tgz","_nodeVersion":"25.2.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-I7GZQeQIw5Ht10cnKChRFkr23rJmEf7sVHqUeDtvuKxeI8DV/0TcQ5F8+5JQHfavSITej6RKgwdlRvx/+QDMPA==","shasum":"eb4fedb137380709213bebce5c1ba5bdae274c59","tarball":"https://registry.npmjs.org/@ascii-graphs/renderer-confluence/-/renderer-confluence-0.1.0.tgz","fileCount":5,"unpackedSize":24680,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIARJETmDx1F0hACQnOMA8twwaQGmS3tTKRf2HNq9GMnUAiBbXyajJ1YsTX8KRnqK/cQQxOTgv3rqiNP0uGtI1u2l2A=="}]},"_npmUser":{"name":"izquierdojv","email":"izquierdojv@gmail.com"},"directories":{},"maintainers":[{"name":"izquierdojv","email":"izquierdojv@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/renderer-confluence_0.1.0_1787899891821_0.24687144597930688"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-28T06:51:31.539Z","0.1.0":"2026-08-28T06:51:31.967Z","modified":"2026-08-28T06:51:32.223Z"},"maintainers":[{"name":"izquierdojv","email":"izquierdojv@gmail.com"}],"description":"Native Confluence Cloud documents for portable ASCII charts","homepage":"https://github.com/juanviizquierdo/ascii_graphs#readme","keywords":["ascii","charts","confluence","adf","text","accessibility"],"repository":{"type":"git","url":"git+https://github.com/juanviizquierdo/ascii_graphs.git"},"author":{"name":"Juan Víctor Izquierdo"},"bugs":{"url":"https://github.com/juanviizquierdo/ascii_graphs/issues"},"license":"MIT","readme":"# @ascii-graphs/renderer-confluence\n\nRender any ASCII Graphs `CellGrid` as a native Confluence Cloud document in\nAtlassian Document Format (ADF). No Marketplace app, image upload, or external\nhosting is needed. Every chart supports native text colors with\n`mode: \"richText\"`. The default is a monochrome code block; icicle partitions\nalso support filled tables.\n\n```ts\nimport { bar, layout } from \"@ascii-graphs/core\";\nimport { renderConfluence } from \"@ascii-graphs/renderer-confluence\";\n\nconst grid = layout(\n  bar({\n    title: \"Deployments by region\",\n    data: [\n      { label: \"Europe\", value: 42 },\n      { label: \"Americas\", value: 31 },\n    ],\n  }),\n  { width: 56, charset: \"unicode\" },\n);\n\nconst document = renderConfluence(grid, { mode: \"richText\" });\n```\n\n`renderConfluence` returns a JSON-serializable object with `type: \"doc\"`,\n`version: 1`, and a `content` array. Labels remain literal ADF text, including\nquotes, Markdown fences, and HTML characters. Without options, the chart is a\nplain-text `codeBlock` with wrapping explicitly disabled and line numbers\nhidden.\n\n## Options\n\n| Option       | Default          | Meaning                                                                        |\n| ------------ | ---------------- | ------------------------------------------------------------------------------ |\n| `mode`       | `\"codeBlock\"`    | `\"codeBlock\"` or colored `\"richText\"` for any grid; `\"table\"` for icicle bands |\n| `theme`      | Semantic palette | Text colors in rich-text mode; band backgrounds in table mode; six-digit hex   |\n| `tableWidth` | `960`            | Table width in pixels, an integer from 48 to 1800                              |\n\n`theme` requires `mode: \"richText\"` or `mode: \"table\"`; it is rejected in the\ndefault mode so a request for colors cannot silently produce a plain snippet.\n`tableWidth` requires `mode: \"table\"`.\n\n| `accessibility`    | Content after the chart                                   |\n| ------------------ | --------------------------------------------------------- |\n| `\"both\"` (default) | Visible description, table caption, and native data table |\n| `\"description\"`    | Visible description                                       |\n| `\"table\"`          | Table caption and native data table                       |\n| `\"none\"`           | Chart only                                                |\n\nThe table uses the grid's semantic source data, so full labels and values remain\navailable even when the visual chart is narrow. Missing values become empty\ncells; zero remains `0`. These are visible alternatives, not hidden ARIA\ncontent.\n\n## Colors for every chart\n\n```ts\nconst document = renderConfluence(grid, {\n  mode: \"richText\",\n  theme: { series1: \"#2563EB\", positive: \"#0F766E\" },\n  accessibility: \"both\",\n});\n```\n\nRich-text mode reads each cell's semantic foreground and bold style, so it works\nwith bars, lines, heatmaps, trees, maps, partitions, and every other chart. It\ndoes not require band metadata or chart-specific options. Adjacent cells with\nthe same style become a single text run with native `textColor` and `strong`\nmarks. Rows use `hardBreak`; spaces become non-breaking spaces to avoid HTML\nwhitespace collapse. Trailing whitespace is trimmed as in the text renderer.\n\nThe theme supports `muted`, `accent`, `positive`, `negative`, and\n`series1`–`series4`. Unstyled cells retain the page's text color. Descriptions\nand source tables use the same accessibility options as the other modes.\n\n**Layout tradeoff:** ADF does not allow `textColor` together with inline `code`\nor inside a code block. Rich text preserves glyphs and row breaks, but\nConfluence controls its fonts and wrapping, so exact monospace alignment is not\nguaranteed. Use the default code-block mode when exact text geometry matters\nmore than color. For both exact geometry and color, a separate image workflow is\nneeded. Check the rendered page before relying on rich-text alignment.\n\nThe\n[colored line-chart request](../../examples/integrations/confluence-rich-text.json)\nis ready for the JSON bridge.\n\n## Native filled capacity bands\n\n```ts\nimport { layout, partition } from \"@ascii-graphs/core\";\nimport { renderConfluence } from \"@ascii-graphs/renderer-confluence\";\n\nconst capacity = layout(\n  partition({\n    mode: \"icicle\",\n    root: {\n      label: \"Capacity\",\n      value: 100,\n      color: \"positive\",\n      children: [\n        {\n          label: \"Allocated\",\n          value: 60,\n          color: \"series2\",\n          children: [{ label: \"Used\", value: 35, color: \"series3\" }],\n        },\n        { label: \"Reserve\", value: 40, color: \"muted\" },\n      ],\n    },\n  }),\n  { width: 100 },\n);\n\nconst document = renderConfluence(capacity, {\n  mode: \"table\",\n  tableWidth: 1000,\n  theme: {\n    positive: \"#8ED04E\",\n    series2: \"#B8A1FF\",\n    series3: \"#FFE44D\",\n    muted: \"#FFFFFF\",\n  },\n});\n```\n\nThis uses native `tableCell.attrs.background`, merged cells, explicit column\nwidths, and centered paragraphs. It reads `CellGrid.bands` supplied by the core\nlayout, never attempts to reconstruct values from ASCII glyphs. The band\nboundaries share the grid's horizontal scale, including leading, intermediate,\nand trailing unused space. Each hierarchy level becomes one table row.\n\nLabels and the optional title remain complete even when the text chart would\ntruncate them. `labelAlign` from the partition controls left, center, or right\nalignment. Black or white label text is selected for contrast against each\nbackground. Gaps have no background override or text. Zero-width nodes remain in\nthe source data table, and a chart with no visible bands keeps its textual empty\nstate instead of emitting an invalid empty table.\n\nThe default backgrounds use the same semantic palette as the HTML renderer. Any\nof `muted`, `accent`, `positive`, `negative`, and `series1`–`series4` can be\noverridden with a six-digit hex value. CSS names, variables, and arbitrary CSS\nare not accepted. The chart table and optional source data table are separate;\n`accessibility: \"none\"` removes only the extra description and source table.\n\n**Supported scope:** table mode currently requires an icicle partition grid with\nband metadata. Other chart types throw a helpful error in this mode; continue\nusing `mode: \"richText\"` for their colors or `mode: \"codeBlock\"` for plain text.\nExisting plain exports are unchanged.\n\n**Appearance:** this is a native table rendering with solid backgrounds, not a\ncolored code block or a pixel-identical copy of the HTML chart. Confluence\ncontrols fonts, cell padding, borders, label wrapping, and theme mapping. Column\nwidths use `displayMode: \"fixed\"`; narrow columns and long labels can still\nencounter editor constraints. Increase grid resolution or table width when\nneeded, and verify the saved page in the intended Confluence client.\n\nThe\n[colored compute-capacity request](../../examples/charts/partition-confluence.json)\nis ready for the JSON bridge.\n\n## Send through an LLM's Confluence tool\n\nFor Atlassian Rovo's `createConfluencePage` or `updateConfluencePage`, pass\n`contentFormat: \"adf\"` and `body: JSON.stringify(document)` alongside the tool's\nsite and page/space arguments. Code-block mode gives explicit control over\nwrapping; a Markdown-only connector may not preserve that setting.\n\nFor the Confluence Cloud REST API v2, the same document goes in a different\nenvelope:\n\n```ts\nconst body = {\n  representation: \"atlas_doc_format\",\n  value: JSON.stringify(document),\n};\n// Include `body` with the other required fields in a page create/update request.\n```\n\nThe renderer does not authenticate, make network calls, or publish pages. When\nupdating an existing page, read and preserve its current document and merge the\ngenerated `content` nodes into the intended section. Sending this chart-only\ndocument as the entire page body would replace the page's other content.\n\n## Limits and compatibility\n\n- This targets **Confluence Cloud ADF**, not Data Center storage XML or wiki\n  markup.\n- Code-block mode preserves text and Unicode shapes, without color. Rich-text\n  mode colors any chart's glyphs; table mode maps icicle band colors to native\n  cell backgrounds. None embeds ANSI, HTML styling, or interactivity. Exact\n  appearance depends on Confluence.\n- Snippets are editable text snapshots. Keep the chart specification in your\n  workflow and regenerate the output when data changes; editing the companion\n  table does not automatically redraw the chart.\n- If a connector rewrites the ADF or a viewer ignores snippet attributes, verify\n  wrapping is off. Start with 48–64 columns for typical documentation pages.\n- This package generates the documented ADF structure. Local tests do not\n  replace a round-trip rendering check in your Confluence site.\n\nFor an exact image of the HTML colors and typography, a separate integration\ncould render the existing HTML to a PNG and attach it, or use a Forge macro for\ncustom rendering. Neither is implemented here.\n\nSee the\n[Confluence integration guide](../../examples/integrations/confluence.md) for a\nJSON-only LLM workflow and API examples.\n\nReferences:\n[ADF codeBlock](https://developer.atlassian.com/cloud/jira/platform/apis/document/nodes/codeBlock/),\n[ADF table cells](https://developer.atlassian.com/cloud/jira/platform/apis/document/nodes/table_cell/),\n[ADF table sizing](https://developer.atlassian.com/cloud/jira/platform/apis/document/nodes/table/),\n[ADF text color](https://developer.atlassian.com/cloud/jira/platform/apis/document/marks/textColor/),\n[ADF inline code](https://developer.atlassian.com/cloud/jira/platform/apis/document/marks/code/),\n[Cloud page API](https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/),\n[Cloud code snippets](https://support.atlassian.com/confluence-cloud/docs/insert-elements-into-a-page/).\n","readmeFilename":"README.md","_rev":"1-d0cb83c0e0394b2844d9af1e6e1e3d77"}