plotleaf 0.0.0-stage → 0.2.0

package/schema/components.json

@@ -0,0 +1,551 @@
+{
+  "version": 1,
+  "syntax": "markdown-directives",
+  "attributes": "Literal strings decoded according to each property schema. No JavaScript expressions.",
+  "limits": {
+    "markdownBytes": 1048576,
+    "jsonBytes": 10485760,
+    "totalBytes": 26214400,
+    "datasets": 64,
+    "rows": 100000,
+    "chartRows": 10000,
+    "donutSlices": 8,
+    "funnelStages": 20,
+    "tableRows": 1000,
+    "tableColumns": 40
+  },
+  "data": {
+    "shape": "array of flat JSON records",
+    "resolution": "relative to the report directory; local .json files only",
+    "percent": "ratios: 0.12 displays as 12%",
+    "percentagePoints": "point values: 0.8 displays as 0.8 pt",
+    "currency": "major units; omit .00 on whole amounts, preserve nonzero cents",
+    "locale": "en-GB",
+    "timeZone": "UTC"
+  },
+  "components": {
+    "grid": {
+      "description": "A responsive row of one to four components.",
+      "forms": [
+        "container"
+      ],
+      "children": [
+        "metric",
+        "line",
+        "area",
+        "bar",
+        "donut",
+        "funnel",
+        "table",
+        "callout"
+      ],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "columns": {
+            "default": 2,
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 4
+          }
+        },
+        "required": [
+          "columns"
+        ],
+        "additionalProperties": false
+      },
+      "example": ":::grid{columns=\"4\"}\n::metric{label=\"Teams\" value=\"1492\"}\n:::"
+    },
+    "metric": {
+      "description": "A prepared numeric value with optional comparison, direction and sentiment.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "value": {
+            "type": "number"
+          },
+          "format": {
+            "default": "number",
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          },
+          "comparison": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "direction": {
+            "type": "string",
+            "enum": [
+              "up",
+              "down",
+              "flat"
+            ]
+          },
+          "sentiment": {
+            "default": "neutral",
+            "type": "string",
+            "enum": [
+              "positive",
+              "negative",
+              "neutral"
+            ]
+          }
+        },
+        "required": [
+          "label",
+          "value",
+          "format",
+          "sentiment"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::metric{label=\"Conversion\" value=\"0.103\" format=\"percent\"}"
+    },
+    "line": {
+      "description": "An interactive single-series line chart from local JSON.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "x": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "y": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "format": {
+            "default": "number",
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          },
+          "xType": {
+            "default": "category",
+            "type": "string",
+            "enum": [
+              "category",
+              "date",
+              "number"
+            ]
+          },
+          "target": {
+            "type": "number"
+          },
+          "targetLabel": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "required": [
+          "data",
+          "x",
+          "y",
+          "title",
+          "format",
+          "xType"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::line{data=\"./usage.json\" x=\"date\" y=\"teams\" xType=\"date\" title=\"Active teams\"}"
+    },
+    "area": {
+      "description": "A line chart with a restrained area fill.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "x": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "y": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "format": {
+            "default": "number",
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          },
+          "xType": {
+            "default": "category",
+            "type": "string",
+            "enum": [
+              "category",
+              "date",
+              "number"
+            ]
+          },
+          "target": {
+            "type": "number"
+          },
+          "targetLabel": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "required": [
+          "data",
+          "x",
+          "y",
+          "title",
+          "format",
+          "xType"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::area{data=\"./usage.json\" x=\"date\" y=\"teams\" xType=\"date\" title=\"Active teams\" target=\"1600\"}"
+    },
+    "bar": {
+      "description": "An interactive category bar chart with a zero baseline.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "x": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "y": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "format": {
+            "default": "number",
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          }
+        },
+        "required": [
+          "data",
+          "x",
+          "y",
+          "title",
+          "format"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::bar{data=\"./errors.json\" x=\"category\" y=\"count\" title=\"Errors by category\"}"
+    },
+    "donut": {
+      "description": "A part-to-whole donut with a readable legend and native data table.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "category": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "format": {
+            "default": "number",
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          }
+        },
+        "required": [
+          "data",
+          "category",
+          "value",
+          "title",
+          "format"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::donut{data=\"./plans.json\" category=\"plan\" value=\"teams\" title=\"Teams by plan\"}",
+      "dataRules": {
+        "category": "Unique nonblank strings of at most 1000 characters; source order is preserved.",
+        "value": "Finite nonnegative numbers with a finite sum. Nulls and numeric strings are invalid. All-zero values show an empty state.",
+        "maximumRows": 8
+      }
+    },
+    "funnel": {
+      "description": "Ordered stage/progress rows with prepared values, denominators, shares and optional explicit status. Works without JavaScript.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "stage": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "total": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "share": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "status": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "format": {
+            "default": "number",
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          }
+        },
+        "required": [
+          "data",
+          "stage",
+          "value",
+          "total",
+          "share",
+          "title",
+          "format"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::funnel{data=\"./funnel.json\" stage=\"stage\" value=\"teams\" total=\"baseline\" share=\"share\" status=\"status\" title=\"Funnel by stage\"}",
+      "dataRules": {
+        "stage": "Unique nonblank strings of at most 1000 characters; source order is preserved.",
+        "value": "Finite nonnegative number no greater than its row's total.",
+        "total": "Finite positive denominator supplied per row. No denominator is inferred from adjacent stages.",
+        "share": "Prepared ratio from 0 to 1, matching value / total to within 0.0005 (rounding to 0.1 percentage point).",
+        "status": [
+          "on-target",
+          "below-target",
+          "at-risk",
+          "neutral"
+        ],
+        "maximumRows": 20
+      }
+    },
+    "table": {
+      "description": "A semantic sortable table, with inferred or explicitly formatted columns.",
+      "forms": [
+        "leaf",
+        "container"
+      ],
+      "children": [
+        "column"
+      ],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "data": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "required": [
+          "data"
+        ],
+        "additionalProperties": false
+      },
+      "example": ":::table{data=\"./plans.json\" title=\"By plan\"}\n::column{field=\"plan\" label=\"Plan\"}\n::column{field=\"change\" label=\"Δ QoQ\" format=\"percent\" sign=\"always\"}\n:::"
+    },
+    "column": {
+      "description": "An explicit field, label and format inside a table.",
+      "forms": [
+        "leaf"
+      ],
+      "children": [],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "field": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "label": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "format": {
+            "type": "string",
+            "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
+          },
+          "sign": {
+            "default": "auto",
+            "type": "string",
+            "enum": [
+              "auto",
+              "always"
+            ]
+          },
+          "semantics": {
+            "default": "neutral",
+            "type": "string",
+            "enum": [
+              "neutral",
+              "higher-is-better",
+              "lower-is-better"
+            ]
+          }
+        },
+        "required": [
+          "field",
+          "sign",
+          "semantics"
+        ],
+        "additionalProperties": false
+      },
+      "example": "::column{field=\"change\" label=\"Δ QoQ\" format=\"percent\" sign=\"always\" semantics=\"higher-is-better\"}"
+    },
+    "callout": {
+      "description": "A contextual note or warning containing ordinary Markdown.",
+      "forms": [
+        "container"
+      ],
+      "children": [
+        "markdown"
+      ],
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "tone": {
+            "default": "note",
+            "type": "string",
+            "enum": [
+              "note",
+              "warning"
+            ]
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          }
+        },
+        "required": [
+          "tone"
+        ],
+        "additionalProperties": false
+      },
+      "example": ":::callout{title=\"Coverage\"}\nSeven complete days of prepared data.\n:::"
+    }
+  },
+  "rules": [
+    "Use explicit closing fences for containers.",
+    "Components are standalone blocks, not inline/list/blockquote content.",
+    "column is only allowed inside table; grids cannot nest.",
+    "direction and explicitly supplied sentiment require metric comparison text.",
+    "targetLabel requires target.",
+    "Dataset fields are literal own-property keys, not expressions.",
+    "Charts preserve source order; date/number x values must increase.",
+    "Line/area null y values create gaps; bar null y values are invalid.",
+    "Donut category/value fields must differ; category count is bounded, and all-zero values do not create equal slices.",
+    "Funnel fields must differ; shares and denominators are supplied, validated and displayed per row, with no sorting or status inference.",
+    "Filters, maps, images, nested data and executable components are not supported in this release."
+  ]
+}

package/skills/plotleaf/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: plotleaf
+description: Create and revise plotleaf Markdown reports from prepared JSON, then validate, preview and export portable interactive HTML. Use for plotleaf report authoring, not development of the reporting engine.
+---
+
+# plotleaf report authoring
+
+Create one Markdown file with optional local JSON datasets. The agent retrieves, analyses and prepares data; plotleaf renders it. Do not scaffold an application or put analysis code, SQL, JavaScript expressions or scripts into the report.
+
+Use an installed `plotleaf` CLI or `npx plotleaf`. In an unpublished source checkout, build it with `bun run build` and use `node dist/cli.js` from the package root instead of fetching an npm release.
+
+## Discover the contract
+
+Run `plotleaf schema` (or `npx plotleaf schema`) for the current machine-readable component/prop specifications, rules and input limits. Prefer that output over remembered syntax. Supported components in 0.2.0 include `grid`, `metric`, `line`, `area`, `bar`, `donut`, `funnel`, `table`, `column` and `callout`. Donut and funnel require plotleaf 0.2.0 or newer; check the installed CLI's schema when using an older version.
+
+Use ordinary Markdown for headings, prose, findings, emphasis, lists, links and dividers. Headings provide sections. Design is built in; do not add custom CSS, raw HTML or framework components. Filters, maps, image/sparkline cells and executable/custom components are future capabilities, not supported syntax.
+
+## Author prepared content
+
+```markdown
+---
+title: Adoption report
+description: Team adoption and growth from prepared data.
+---
+
+# Adoption report
+
+An overview of the prepared dataset, its period and relevant findings.
+
+:::grid{columns="2"}
+::metric{label="Teams" value="1492" comparison="34% vs previous quarter" direction="up" sentiment="positive"}
+::metric{label="Conversion" value="0.103" format="percent"}
+:::
+
+::area{data="./usage.json" x="date" y="teams" xType="date" title="Teams with an alert" target="1600" targetLabel="Target"}
+
+:::table{data="./plans.json" title="By plan"}
+::column{field="plan" label="Plan"}
+::column{field="teams" label="Teams" format="number"}
+::column{field="change" label="Δ QoQ" format="percent" sign="always" semantics="higher-is-better"}
+:::
+```
+
+Literal attributes are quoted strings, decoded by the component schema. `::` is a leaf; `:::` encloses a container. Close every container explicitly. Use a longer outer fence (`::::grid`) when placing another container, such as a table, inside it. Put components at the document root or in allowed component containers, not inline or inside lists/blockquotes. `column` belongs only inside a table. A plain `::table{data="./file.json"}` infers all fields; explicit columns select/order/format fields and exclude unused columns from export.
+
+- Datasets are JSON arrays of flat scalar records. Paths resolve from the Markdown file's directory. Keep them there or in subdirectories; remote, hidden, absolute and outside-root/symlink paths are rejected.
+- Chart fields are literal keys. Charts do not aggregate, join or sort. Prepare a distinct category per bar; date/number x values must be unique and increasing. `xType="date"` accepts real `YYYY-MM-DD` dates or timestamps with an explicit zone. Dates are displayed in UTC.
+- y values are finite JSON numbers. Line/area nulls create gaps; bar nulls are invalid. Missing fields are errors. Empty arrays produce an explicit no-data state and a warning.
+- Table records have consistent keys and non-null types per column. Scalar values stay text; no HTML cell templates. Sorting uses raw values. Use a smaller prepared summary if validation reports table/point limits; the engine never truncates silently.
+- Numeric formats are `number`, `percent`, `percentage-points` and `currency:GBP` (validated ISO code). Percent uses ratios (`0.12` → 12%); percentage-points uses point values (`0.8` → 0.8 pt); currency uses major units. Whole currency amounts omit `.00`; nonzero cents retain two decimal places. Formatting uses `en-GB`.
+- Metrics, comparisons and business sentiment are supplied by the agent. An increase is not automatically positive. Comparison direction and sentiment are independent; both require comparison text when explicitly supplied. Numeric table changes can declare `higher-is-better` or `lower-is-better` semantics.
+- Include data period, provenance and limitations in the prose where they help readers assess the report. Do not invent findings or imply filters/refresh that the file does not provide.
+
+## Part-to-whole and stage views
+
+```markdown
+::donut{data="./plans.json" category="plan" value="teams" title="Teams by plan"}
+::funnel{data="./funnel.json" stage="stage" value="teams" total="baseline" share="share" status="status" title="Funnel by stage"}
+```
+
+- Donuts require at most eight unique, nonblank string categories and finite nonnegative values with a finite sum. Prepare mutually exclusive parts of one whole; group a tail into an explicit Other row before rendering if appropriate. Zero values remain in the legend/data; all-zero data is an empty state, never equal slices.
+- Funnel rows supply value, positive denominator and share explicitly, such as `{"stage":"Activated","teams":25,"baseline":100,"share":0.25,"status":"below-target"}`. Shares use ratios and must match value / total within 0.0005 (rounding to 0.1 percentage point). No baseline means an empty array, not a zero denominator.
+- Funnel stage names are unique nonblank strings, with at most 20 stages in source order. Each stage can have its own denominator; explain that choice in prose. Status values are `on-target`, `below-target`, `at-risk` or `neutral`. Omit the status mapping for neutral styling; the engine never infers business status. All mapped fields must differ.
+- Use the full-value data disclosures to check counts behind compact funnel labels. Both components retain readable HTML data without JavaScript. Keep the denominator of any nearby conversion KPI explicit when it differs from the funnel baseline.
+
+## Validate, preview and export
+
+```bash
+npx plotleaf validate report.md --json
+npx plotleaf dev report.md --no-open
+npx plotleaf build report.md --out ./report.html
+```
+
+Repair diagnostics using their code, one-based source location, message and hint, then validate again. Preview watches Markdown and referenced JSON; an invalid edit displays diagnostics and recovers after repair. Omit `--no-open` to open a browser. No backend/account is required.
+
+Export is one self-contained interactive HTML file. Check it after copying it away from sources and disabling networking. Charts require JavaScript; prose, metrics, tables and native chart-data disclosures remain readable without it. All displayed/embedded values are readable by recipients: collapsing a table or hiding a field visually is not redaction. Prepare sensitive data before rendering; explicit-column tables and chart field projection help avoid exporting unused fields.
+
+Inspect the result at a narrow viewport and in both system themes. Preserve the source's meaning and the product's quiet editorial design when making revisions.