plotleaf 0.1.0 → 0.3.0

package/schema/components.json

@@ -9,11 +9,18 @@
     "datasets": 64,
     "rows": 100000,
     "chartRows": 10000,
+    "donutSlices": 8,
+    "funnelStages": 20,
     "tableRows": 1000,
-    "tableColumns": 40
+    "tableColumns": 40,
+    "sparklinePoints": 64,
+    "imageFiles": 64,
+    "imageBytes": 1048576,
+    "imageDimension": 4096,
+    "imagePixels": 4000000
   },
   "data": {
-    "shape": "array of flat JSON records",
+    "shape": "array of flat JSON records; explicit table sparkline columns permit bounded numeric/null arrays only in their declared fields",
     "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",
@@ -32,6 +39,8 @@
         "line",
         "area",
         "bar",
+        "donut",
+        "funnel",
         "table",
         "callout"
       ],
@@ -286,6 +295,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": [
@@ -318,7 +456,7 @@
       "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.",
+      "description": "A scalar, local image or bounded sparkline column. Omitted kind means scalar.",
       "forms": [
         "leaf"
       ],
@@ -337,6 +475,24 @@
             "minLength": 1,
             "maxLength": 1000
           },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "scalar",
+              "image",
+              "sparkline"
+            ]
+          },
+          "alt": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
+          "sortBy": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 1000
+          },
           "format": {
             "type": "string",
             "pattern": "^(number|percent|percentage-points|currency:[A-Z]{3})$"
@@ -366,7 +522,12 @@
         ],
         "additionalProperties": false
       },
-      "example": "::column{field=\"change\" label=\"Δ QoQ\" format=\"percent\" sign=\"always\" semantics=\"higher-is-better\"}"
+      "example": "::column{field=\"change\" label=\"Δ QoQ\" format=\"percent\" sign=\"always\" semantics=\"higher-is-better\"}",
+      "dataRules": {
+        "image": "Local static PNG/JPEG path or null. alt names a nonblank string field for each image. Fixed 64 × 48 display box; deduplicated and embedded offline. Paths resolve from the report directory.",
+        "sparkline": "Only explicitly declared sparkline fields may contain arrays: at most 64 finite numbers/nulls, in sample order. Nulls are gaps. Shared observed y scale per column; no aggregation or resampling.",
+        "sortBy": "Optional scalar field for image/sparkline sorting. Without it a rich column has a plain header. Scalar columns sort their own raw values. Sort keys are readable in the export."
+      }
     },
     "callout": {
       "description": "A contextual note or warning containing ordinary Markdown.",
@@ -411,6 +572,9 @@
     "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.",
-    "Filters, maps, images, nested data and executable components are not supported in this release."
+    "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.",
+    "Only explicit image columns can load local static PNG/JPEG; every resource stays within the report root and shared byte limits.",
+    "Filters, maps, arbitrary 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 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. Image/sparkline column kinds require 0.3.0 or newer; check the installed CLI version and schema. Filters, maps, subtotals and executable/custom components remain future capabilities.
 
 ## Author prepared content
 
@@ -43,14 +43,43 @@ An overview of the prepared dataset, its period and relevant findings.
 
 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.
+- Datasets are JSON arrays of flat scalar records, except explicitly declared table sparkline fields. 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.
+- Table records have consistent keys and non-null types per column. Scalar values stay text; rich cells use explicit column kinds, never HTML 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.
+
+## Rich tables (0.3.0 or newer)
+
+```markdown
+:::table{data="./products.json" title="Products"}
+::column{field="image" kind="image" alt="description" label="Preview"}
+::column{field="product" label="Product"}
+::column{field="weekly_orders" kind="sparkline" sortBy="last_week" label="Weekly orders"}
+:::
+```
+
+- Omitted `kind` means scalar. Images require an `alt` field containing a nonblank string for each non-null image; null image cells may have null alternatives. Image fields contain a local static PNG/JPEG path or null, resolved from the Markdown directory. Do not supply SVG, GIF/WebP, remote/data URLs or absolute/hidden/outside-root paths. The display box is 64 × 48; prepare images within the schema's byte/dimension/reference limits.
+- Each unique image is embedded once. Its complete original bytes and metadata are readable by recipients; prepare assets for that disclosure. Alternatives are text, not markup. No image styling or numeric-format properties are supported.
+- Sparkline fields contain at most 64 finite numbers/nulls or null. Only explicitly declared sparkline fields may contain sequences. Use a separate flat dataset for a chart or an inferred/scalar table. Nested objects/arrays and numeric strings are invalid; rows retain consistent keys.
+- Sparkline x positions follow sample order. All rows in the same column share its observed min/max y scale. Nulls are gaps; last-sample labels remain missing when the final sample is null. Empty/all-null series show no invented values. Use `format` for numeric labels; sign/sentiment settings apply only to scalar columns.
+- Rich columns are unsortable unless `sortBy` names a separate scalar field with consistent non-null types. Prepare any sort key explicitly, such as `last_week`; it is readable in the export. The engine does not compare arrays or derive a total/trend. Scalar columns keep their existing raw-value sort.
+- Check image alternatives, line gaps/shared scale, keyboard value disclosures, row sorting, both themes and narrow table scrolling. Images/sparklines remain visible without JavaScript. The fictional catalogue example demonstrates this syntax.
+
 ## Validate, preview and export
 
 ```bash
@@ -59,7 +88,7 @@ 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.
+Repair diagnostics using their code, one-based source location, message and hint, then validate again. Preview watches Markdown, referenced JSON and local table images; 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.