plotleaf 0.2.0 → 0.3.1

package/README.md

@@ -8,13 +8,40 @@ Beautiful, interactive reports from Markdown and prepared JSON. Built for coding
 
 A report is one Markdown file, optionally accompanied by local JSON datasets. No application, configuration file, account, database or hosted service. Export one HTML file that keeps working offline.
 
+## Start with your coding agent
+
+Copy this into your agent and replace the report brief:
+
+```text
+Create a polished, interactive report with plotleaf.
+
+Report brief: [Describe the report and point to the data you want to use.]
+
+Use Node 22+ and npx; no app scaffolding, Bun or account is needed.
+First run `npx --yes plotleaf --help`. If it lists `guide`, read
+`npx --yes plotleaf guide`. Otherwise read the authoring guide at:
+https://raw.githubusercontent.com/LoueeD/plotleaf/v0.3.0/skills/plotleaf/SKILL.md
+Then run `npx --yes plotleaf schema` for the installed component API.
+
+Use the data I provide; don't invent values or findings. If the brief or
+data is missing, ask for what's needed. Prepare one report.md and any local
+JSON/assets it needs, following the guide and installed schema.
+
+Run `npx --yes plotleaf validate report.md --json` and fix all errors.
+Start `npx --yes plotleaf dev report.md --no-open` and give me the preview URL.
+Build `npx --yes plotleaf build report.md --out report.html` and give me
+the source and portable HTML paths, with any data limitations.
+```
+
+The `guide` command is available in **0.3.1 or newer**. The prompt also works with 0.3.0 through the linked authoring guide.
+
 ## Status
 
 The initial MVP includes validation, live preview/reload, self-contained HTML export and a generated component specification. All bundled examples use fictional data.
 
-Version **0.2.0** adds donut charts and prepared funnel/progress views to the Markdown report language.
+**0.3.0** adds local PNG/JPEG image cells, static sparklines and a cumulative example report. Donut charts and prepared funnel/progress views are available since 0.2.0. Check your installed CLI version or schema before using newer components.
 
-Implemented components: responsive grids, metrics/comparisons, line/area/bar/donut charts, prepared funnel/progress stages, literal chart targets, sortable/formatted tables and callouts. Reports support light/dark system preference, native chart-data disclosures and responsive layouts. Filters, rich table cells, maps and reusable compositions remain planned increments.
+Implemented components: responsive grids, metrics/comparisons, line/area/bar/donut charts, prepared funnel/progress stages, literal chart targets, sortable/formatted tables and callouts. Reports support light/dark system preference, native chart-data disclosures and responsive layouts. Filters, maps, subtotals and reusable compositions remain planned increments.
 
 ## Quick start
 
@@ -30,6 +57,8 @@ npx plotleaf schema
 
 `plotleaf report.md` is an alias for `dev`. `build` defaults to `report.html` beside the source. Relative dataset paths resolve from the Markdown file's directory; an explicit `--out` resolves from the caller's working directory. Exports contain no preview connection and need no source files at viewing time.
 
+For agent discovery, `npx plotleaf guide` (0.3.1+) prints the bundled report-authoring guide as Markdown, and `npx plotleaf schema` prints the component specification as JSON. The guide is the same `skills/plotleaf/SKILL.md` shipped with the package. These commands print documentation without creating files, changing project configuration or starting a server; once installed, they read local package content.
+
 ## A report
 
 ```markdown
@@ -79,7 +108,7 @@ Attributes are literal values, not JavaScript. Keep leaf directives on one line
 
 Numbers, comparisons, trends and findings are prepared by the author. `percent` uses ratios (`0.12` → 12%); `percentage-points` uses point values (`0.8` → 0.8 pt); `currency:GBP` uses major units. Whole currency amounts omit `.00`; nonzero cents retain two decimal places. Formatting is `en-GB`; date display is UTC. An increase does not imply positive business sentiment.
 
-Use `schema` for current property schemas, child rules and input limits. The installed package includes `schema/components.json`, generated from the validation registry, and `skills/plotleaf/SKILL.md`, a reusable report-authoring guide. Public examples under `examples/storefront/`, `examples/adoption/` and `examples/onboarding/` contain only fictional data.
+Use `schema` for current property schemas, child rules and input limits. The installed package includes `schema/components.json`, generated from the validation registry, and `skills/plotleaf/SKILL.md`, a reusable report-authoring guide. Public examples under `examples/storefront/`, `examples/adoption/`, `examples/onboarding/` and `examples/catalog/` contain only fictional data. Catalogue illustrations are original, purpose-built raster assets.
 
 ## Donut and funnel
 
@@ -94,9 +123,26 @@ Funnel data supplies each stage explicitly, for example `{"stage":"Activated","t
 
 Try the fictional `examples/onboarding/report.md` from a source checkout. See [M3 contracts and tradeoffs](https://github.com/LoueeD/plotleaf/blob/main/docs/m3-visualizations.md).
 
+## Image and sparkline columns
+
+```markdown
+:::table{data="./products.json" title="Product performance"}
+::column{field="image" label="Preview" kind="image" alt="description"}
+::column{field="product" label="Product"}
+::column{field="weekly_orders" label="Weekly orders" kind="sparkline" sortBy="last_week"}
+::column{field="revenue" label="Revenue" format="currency:USD"}
+:::
+```
+
+An image value is a relative PNG/JPEG path or null; `alt` names its row's text-alternative field. The fixed thumbnail box is 64 × 48. Images are bounded, validated and embedded once per unique content hash, with no source paths or runtime requests. Remote/data URLs, active SVG and animated images are rejected.
+
+Only explicitly declared sparkline fields may contain arrays: at most 64 finite numbers/nulls in sample order. Rows share the observed y scale for that column. Nulls create gaps; a last-sample label and native value disclosure remain readable without JavaScript. Charts and scalar/inferred tables keep the flat scalar data contract.
+
+Rich headers are plain text unless `sortBy` names a scalar field; scalar columns retain raw-value sorting. Alternatives, explicit sort keys and embedded image metadata are readable in the export. Try the fictional `examples/catalog/report.md` from a source build. See [M4 contracts](https://github.com/LoueeD/plotleaf/blob/main/docs/m4-rich-tables.md) for limits and validation details.
+
 ## Data and security boundaries
 
-Prepare JSON arrays of flat scalar records. Charts preserve input order and do not calculate, join or aggregate data. Date/number x values must be unique and increasing; line/area nulls are gaps and bar nulls are errors. Tables sort raw typed values. Explicit table columns also select the fields exported; an inferred table includes every source field.
+Prepare JSON arrays of flat scalar records; only explicitly declared sparkline fields permit bounded numeric/null sequences. Charts preserve input order and do not calculate, join or aggregate data. Date/number x values must be unique and increasing; line/area nulls are gaps and bar nulls are errors. Tables sort raw typed values. Explicit table columns also select the fields exported; an inferred table includes every source field.
 
 Local JSON must stay within the report directory, including after resolving symlinks. Raw HTML, remote assets/data, executable components and report-authored code are rejected. Script/data escaping, sanitization, size limits and safe output writes are part of compilation. Invalid reports do not replace an existing export.
 
@@ -110,14 +156,14 @@ Use Bun 1.4.4 for development and Node 22+ for the published CLI/runtime checks:
 bun install --frozen-lockfile
 bun run build
 
-node dist/cli.js examples/storefront/report.md
+node dist/cli.js examples/report.md
 node dist/cli.js validate examples/storefront/report.md --json
 node dist/cli.js build examples/storefront/report.md
 ```
 
-The first CLI command opens a browser and watches the Markdown and referenced JSON. Add `--no-open` to print the URL without launching a browser. Ctrl-C stops the server. A failed edit shows diagnostics and recovers after you fix it.
+The first CLI command opens a browser and watches the Markdown, referenced JSON and local table images. Add `--no-open` to print the URL without launching a browser. Ctrl-C stops the server. A failed edit shows diagnostics and recovers after you fix it.
 
-Open `examples/storefront/report.html` after export, or try the narrative example in `examples/adoption/report.md`.
+Use `bun run dev` for the cumulative review report in `examples/report.md`. It keeps metrics/comparisons, area/line/bar/donut charts, targets, funnel stages, scalar tables, image cells, sparklines, prose and callouts together as milestones are added. It reuses the focused examples' datasets and image assets; their separate periods and populations remain explicit. Focused examples, including the narrative report in `examples/adoption/report.md`, remain available.
 
 ## Development and verification
 

package/dist/assets/base.js

@@ -1 +1 @@
-(()=>{var d=new Intl.Collator("en-GB",{numeric:!0,sensitivity:"base"});for(let a of document.querySelectorAll("table[data-plotleaf-table]")){let r=a.tBodies[0];if(!r)continue;let i=[...r.rows],s=-1,n=!1;for(let o of a.querySelectorAll("thead button[data-column]"))o.disabled=!1,o.addEventListener("click",()=>{let u=Number(o.dataset.column);n=s===u?!n:!1,s=u;let c=i.map((e,t)=>({row:e,index:t,value:JSON.parse(e.cells[u]?.dataset.raw??"null")}));c.sort((e,t)=>{if(e.value===null||t.value===null)return e.value===t.value?e.index-t.index:e.value===null?1:-1;let l=typeof e.value==="number"&&typeof t.value==="number"?e.value-t.value:d.compare(String(e.value),String(t.value));return(n?-l:l)||e.index-t.index}),r.replaceChildren(...c.map((e)=>e.row)),a.querySelectorAll("thead th").forEach((e)=>{let t=e.contains(o);e.setAttribute("aria-sort",t?n?"descending":"ascending":"none");let l=e.querySelector(".sort-indicator");if(l)l.textContent=t?n?"↓":"↑":"↕"})})}})();
+(()=>{var d=new Intl.Collator("en-GB",{numeric:!0,sensitivity:"base"});for(let a of document.querySelectorAll("table[data-plotleaf-table]")){let r=a.tBodies[0];if(!r)continue;let i=[...r.rows],u=-1,n=!1;for(let o of a.querySelectorAll("thead button[data-column]"))o.disabled=!1,o.addEventListener("click",()=>{let s=Number(o.dataset.column);n=u===s?!n:!1,u=s;let c=i.map((e,t)=>({row:e,index:t,value:JSON.parse(e.cells[s]?.dataset.raw??"null")}));c.sort((e,t)=>{if(e.value===null||t.value===null)return e.value===t.value?e.index-t.index:e.value===null?1:-1;let l=typeof e.value==="number"&&typeof t.value==="number"?e.value-t.value:d.compare(String(e.value),String(t.value));return(n?-l:l)||e.index-t.index}),r.replaceChildren(...c.map((e)=>e.row)),a.querySelectorAll("thead th[aria-sort]").forEach((e)=>{let t=e.contains(o);e.setAttribute("aria-sort",t?n?"descending":"ascending":"none");let l=e.querySelector(".sort-indicator");if(l)l.textContent=t?n?"↓":"↑":"↕"})})}})();

package/dist/assets/charts.js

@@ -1,4 +1,4 @@
-(()=>{var eD=Object.defineProperty;var tD=(t)=>t;function rD(t,e){this[t]=tD.bind(null,e)}var iD=(t,e)=>{for(var r in e)eD(t,r,{get:e[r],enumerable:!0,configurable:!0,set:rD.bind(e,r)})};var ft={};iD(ft,{Arc:()=>Ao,BezierCurve:()=>Co,BoundingRect:()=>ae,Circle:()=>To,CompoundPath:()=>el,Ellipse:()=>Tf,Group:()=>we,HOVER_LAYER_FOR_INCREMENTAL:()=>ca,HOVER_LAYER_FROM_THRESHOLD:()=>nd,HOVER_LAYER_NO:()=>id,Image:()=>_t,IncrementalDisplayable:()=>$v,Line:()=>Ht,LinearGradient:()=>Eo,OrientedBoundingRect:()=>Pf,Path:()=>ie,Point:()=>fe,Polygon:()=>Ef,Polyline:()=>fn,RadialGradient:()=>jv,Rect:()=>De,Ring:()=>Cf,Sector:()=>dr,Text:()=>Qe,WH:()=>pn,XY:()=>ai,applyTransform:()=>Rf,calcZ2Range:()=>BL,clipPointsByRect:()=>aS,clipRectByRect:()=>oS,createIcon:()=>kf,decomposeTransform:()=>UL,ensureCopyRect:()=>Lo,ensureCopyTransform:()=>Uf,expandOrShrinkRect:()=>Oo,extendPath:()=>eS,extendShape:()=>Jx,getCurrentCanvasPainter:()=>FL,getShapeClass:()=>tS,getTransform:()=>nS,groupTransition:()=>od,initProps:()=>$e,isBoundingRectAxisAligned:()=>zf,isElementRemoved:()=>fa,lineLineIntersect:()=>sS,linePolygonIntersect:()=>RL,makeImage:()=>Nf,makePath:()=>rl,mergePath:()=>iS,payloadDisableAnimation:()=>zL,registerShape:()=>mr,removeElement:()=>Do,removeElementWithFadeOut:()=>cn,resizePath:()=>ad,retrieveZInfo:()=>il,setTooltipConfig:()=>Bf,subPixelOptimize:()=>PL,subPixelOptimizeLine:()=>pa,subPixelOptimizeRect:()=>LL,transformDirection:()=>IL,traverseElements:()=>Ci,traverseUpdateZ:()=>nl,updateProps:()=>Ve});var nD=new Intl.Collator("en-GB",{numeric:!0,sensitivity:"base"});for(let t of document.querySelectorAll("table[data-plotleaf-table]")){let e=t.tBodies[0];if(!e)continue;let r=[...e.rows],i=-1,n=!1;for(let a of t.querySelectorAll("thead button[data-column]"))a.disabled=!1,a.addEventListener("click",()=>{let o=Number(a.dataset.column);n=i===o?!n:!1,i=o;let s=r.map((l,u)=>({row:l,index:u,value:JSON.parse(l.cells[o]?.dataset.raw??"null")}));s.sort((l,u)=>{if(l.value===null||u.value===null)return l.value===u.value?l.index-u.index:l.value===null?1:-1;let f=typeof l.value==="number"&&typeof u.value==="number"?l.value-u.value:nD.compare(String(l.value),String(u.value));return(n?-f:f)||l.index-u.index}),e.replaceChildren(...s.map((l)=>l.row)),t.querySelectorAll("thead th").forEach((l)=>{let u=l.contains(a);l.setAttribute("aria-sort",u?n?"descending":"ascending":"none");let f=l.querySelector(".sort-indicator");if(f)f.textContent=u?n?"↓":"↑":"↕"})})}/*! *****************************************************************************
+(()=>{var eD=Object.defineProperty;var tD=(t)=>t;function rD(t,e){this[t]=tD.bind(null,e)}var iD=(t,e)=>{for(var r in e)eD(t,r,{get:e[r],enumerable:!0,configurable:!0,set:rD.bind(e,r)})};var ft={};iD(ft,{Arc:()=>Ao,BezierCurve:()=>Co,BoundingRect:()=>ae,Circle:()=>To,CompoundPath:()=>el,Ellipse:()=>Tf,Group:()=>we,HOVER_LAYER_FOR_INCREMENTAL:()=>ca,HOVER_LAYER_FROM_THRESHOLD:()=>nd,HOVER_LAYER_NO:()=>id,Image:()=>_t,IncrementalDisplayable:()=>$v,Line:()=>Ht,LinearGradient:()=>Eo,OrientedBoundingRect:()=>Pf,Path:()=>ie,Point:()=>fe,Polygon:()=>Ef,Polyline:()=>fn,RadialGradient:()=>jv,Rect:()=>De,Ring:()=>Cf,Sector:()=>dr,Text:()=>Qe,WH:()=>pn,XY:()=>ai,applyTransform:()=>Rf,calcZ2Range:()=>BL,clipPointsByRect:()=>aS,clipRectByRect:()=>oS,createIcon:()=>kf,decomposeTransform:()=>UL,ensureCopyRect:()=>Lo,ensureCopyTransform:()=>Uf,expandOrShrinkRect:()=>Oo,extendPath:()=>eS,extendShape:()=>Jx,getCurrentCanvasPainter:()=>FL,getShapeClass:()=>tS,getTransform:()=>nS,groupTransition:()=>od,initProps:()=>$e,isBoundingRectAxisAligned:()=>zf,isElementRemoved:()=>fa,lineLineIntersect:()=>sS,linePolygonIntersect:()=>RL,makeImage:()=>Nf,makePath:()=>rl,mergePath:()=>iS,payloadDisableAnimation:()=>zL,registerShape:()=>mr,removeElement:()=>Do,removeElementWithFadeOut:()=>cn,resizePath:()=>ad,retrieveZInfo:()=>il,setTooltipConfig:()=>Bf,subPixelOptimize:()=>PL,subPixelOptimizeLine:()=>pa,subPixelOptimizeRect:()=>LL,transformDirection:()=>IL,traverseElements:()=>Ci,traverseUpdateZ:()=>nl,updateProps:()=>Ve});var nD=new Intl.Collator("en-GB",{numeric:!0,sensitivity:"base"});for(let t of document.querySelectorAll("table[data-plotleaf-table]")){let e=t.tBodies[0];if(!e)continue;let r=[...e.rows],i=-1,n=!1;for(let a of t.querySelectorAll("thead button[data-column]"))a.disabled=!1,a.addEventListener("click",()=>{let o=Number(a.dataset.column);n=i===o?!n:!1,i=o;let s=r.map((l,u)=>({row:l,index:u,value:JSON.parse(l.cells[o]?.dataset.raw??"null")}));s.sort((l,u)=>{if(l.value===null||u.value===null)return l.value===u.value?l.index-u.index:l.value===null?1:-1;let f=typeof l.value==="number"&&typeof u.value==="number"?l.value-u.value:nD.compare(String(l.value),String(u.value));return(n?-f:f)||l.index-u.index}),e.replaceChildren(...s.map((l)=>l.row)),t.querySelectorAll("thead th[aria-sort]").forEach((l)=>{let u=l.contains(a);l.setAttribute("aria-sort",u?n?"descending":"ascending":"none");let f=l.querySelector(".sort-indicator");if(f)f.textContent=u?n?"↓":"↑":"↕"})})}/*! *****************************************************************************
 Copyright (c) Microsoft Corporation.
 
 Permission to use, copy, modify, and/or distribute this software for any

package/dist/assets/styles.css

@@ -470,6 +470,77 @@ tbody tr:last-child td {
 .numeric {
   text-align: end;
 }
+.image-definitions {
+  position: absolute;
+  width: 0;
+  height: 0;
+  overflow: hidden;
+}
+.table-image {
+  display: block;
+  width: 64px;
+  height: 48px;
+  border-radius: 4px;
+  outline: 1px solid var(--rule);
+  outline-offset: -1px;
+  background: var(--page);
+}
+.sparkline-cell {
+  display: inline-grid;
+  grid-template-columns: 112px minmax(3ch, auto);
+  align-items: center;
+  gap: 2px 12px;
+  font-variant-numeric: tabular-nums;
+}
+.sparkline-chart {
+  display: block;
+  width: 112px;
+  height: 32px;
+  color: var(--series);
+}
+.sparkline-chart path {
+  stroke: currentColor;
+  stroke-width: 1.8px;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  fill: none;
+}
+.sparkline-chart circle {
+  fill: currentColor;
+}
+.sparkline-last {
+  color: var(--ink);
+}
+.sparkline-empty {
+  font-size: 12px;
+  color: var(--muted);
+  white-space: normal;
+}
+.sparkline-data {
+  grid-column: 1 / -1;
+  text-align: start;
+  font-size: 12px;
+  line-height: 1.5;
+  white-space: normal;
+  max-width: 190px;
+  color: var(--muted);
+}
+.sparkline-data summary {
+  cursor: pointer;
+  width: fit-content;
+  padding-block: 3px;
+  min-height: 24px;
+}
+.sparkline-values {
+  margin: 8px 0;
+  padding-inline-start: 26px;
+  max-height: 180px;
+  overflow: auto;
+  overflow-wrap: anywhere;
+}
+.sparkline-values li {
+  margin-block: 0;
+}
 th button {
   border: 0;
   background: transparent;