plotleaf 0.1.0 → 0.2.0

package/examples/onboarding/report.md

@@ -0,0 +1,42 @@
+---
+title: PLG Onboarding
+description: A fictional product onboarding report with prepared funnel and plan data.
+---
+
+# PLG Onboarding
+
+A fictional product's onboarding performance, **6 April–28 June 2026**. All values and comparisons are synthetic, prepared by the example author.
+
+:::grid{columns="4"}
+::metric{label="Signups" value="12480" comparison="18.2% vs previous quarter" direction="up" sentiment="positive"}
+::metric{label="Activated teams" value="7612" comparison="24.1% vs previous quarter" direction="up" sentiment="positive"}
+::metric{label="Converted" value="1284" comparison="11.4% vs previous quarter" direction="up" sentiment="positive"}
+::metric{label="Conversion rate" value="0.10288461538461538" format="percent" comparison="0.8 pt vs previous quarter" direction="up" sentiment="positive"}
+:::
+
+:::grid{columns="2"}
+::area{data="./signups.json" x="week" y="signups" xType="date" title="Signups by week"}
+::funnel{data="./funnel.json" stage="stage" value="teams" total="baseline" share="share" status="status" title="Funnel by stage"}
+:::
+
+## Activation mix
+
+**7,612 teams** activated. Pro accounts for the largest share; each category below is mutually exclusive. Funnel percentages use **41,200 visitors** as the explicit denominator. The KPI conversion rate uses **12,480 signups**, so it answers a different question.
+
+::::grid{columns="2"}
+::donut{data="./plans.json" category="plan" value="teams" title="Activated teams by plan"}
+:::table{data="./plans.json" title="Activated teams"}
+::column{field="plan" label="Plan"}
+::column{field="teams" label="Teams" format="number"}
+:::
+::::
+
+### Key findings
+
+- **Activation is the next opportunity.** Its below-target status is supplied by the author; the renderer does not infer it from the rate.
+- **Conversion needs attention.** The author marked this stage at risk against the fictional team's own operating targets.
+- **Pro leads the mix.** Plan counts add to the same 7,612 activated teams shown in the KPI and funnel.
+
+:::callout{title="About this example"}
+All data, comparisons, statuses and findings are fictional. This report has no live filters or data connections. The funnel preserves the prepared stage order and never guesses a denominator or business status.
+:::

package/examples/onboarding/signups.json

@@ -0,0 +1,50 @@
+[
+  {
+    "week": "2026-04-06",
+    "signups": 700
+  },
+  {
+    "week": "2026-04-13",
+    "signups": 800
+  },
+  {
+    "week": "2026-04-20",
+    "signups": 770
+  },
+  {
+    "week": "2026-04-27",
+    "signups": 850
+  },
+  {
+    "week": "2026-05-04",
+    "signups": 980
+  },
+  {
+    "week": "2026-05-11",
+    "signups": 1050
+  },
+  {
+    "week": "2026-05-18",
+    "signups": 1040
+  },
+  {
+    "week": "2026-05-25",
+    "signups": 1120
+  },
+  {
+    "week": "2026-06-01",
+    "signups": 1180
+  },
+  {
+    "week": "2026-06-08",
+    "signups": 1160
+  },
+  {
+    "week": "2026-06-15",
+    "signups": 1230
+  },
+  {
+    "week": "2026-06-22",
+    "signups": 1600
+  }
+]

package/package.json

@@ -1,9 +1,17 @@
 {
   "name": "plotleaf",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Beautiful, interactive reports from Markdown and JSON. Built for agents.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LoueeD/plotleaf.git"
+  },
+  "homepage": "https://github.com/LoueeD/plotleaf#readme",
+  "bugs": {
+    "url": "https://github.com/LoueeD/plotleaf/issues"
+  },
   "bin": {
     "plotleaf": "./dist/cli.js"
   },
@@ -22,6 +30,8 @@
     "examples/storefront/*.json",
     "examples/adoption/*.md",
     "examples/adoption/*.json",
+    "examples/onboarding/*.md",
+    "examples/onboarding/*.json",
     "skills/plotleaf/SKILL.md",
     "README.md",
     "LICENSE",

package/schema/components.json

@@ -9,6 +9,8 @@
     "datasets": 64,
     "rows": 100000,
     "chartRows": 10000,
+    "donutSlices": 8,
+    "funnelStages": 20,
     "tableRows": 1000,
     "tableColumns": 40
   },
@@ -32,6 +34,8 @@
         "line",
         "area",
         "bar",
+        "donut",
+        "funnel",
         "table",
         "callout"
       ],
@@ -286,6 +290,135 @@
       },
       "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": [
@@ -411,6 +544,8 @@
     "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

@@ -11,9 +11,9 @@ Use an installed `plotleaf` CLI or `npx plotleaf`. In an unpublished source chec
 
 ## 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 initial components are `grid`, `metric`, `line`, `area`, `bar`, `table`, `column` and `callout`.
+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, donut/funnel, image cells and executable/custom components are future capabilities, not supported syntax.
+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
 
@@ -51,6 +51,18 @@ Literal attributes are quoted strings, decoded by the component schema. `::` is
 - 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