plotleaf 0.1.0 → 0.2.0

package/dist/assets/styles.css

@@ -15,6 +15,14 @@
   --series-fill-end: rgba(79, 178, 239, 0);
   --tooltip: #ffffff;
   --target: #969ba2;
+  --slice-1: #429ee4;
+  --slice-2: #64afa1;
+  --slice-3: #8696b8;
+  --slice-4: #d4a05b;
+  --slice-5: #7984be;
+  --slice-6: #90c7df;
+  --slice-7: #b39581;
+  --slice-8: #a4acb9;
   font-family:
     ui-sans-serif,
     -apple-system,
@@ -42,6 +50,14 @@
     --series-fill-end: rgba(72, 158, 224, 0);
     --tooltip: #25272c;
     --target: #878d97;
+    --slice-1: #65b5ed;
+    --slice-2: #80c5b6;
+    --slice-3: #a2b2d0;
+    --slice-4: #e1b575;
+    --slice-5: #a1a9de;
+    --slice-6: #a1d8eb;
+    --slice-7: #c5aa99;
+    --slice-8: #b7bfcd;
   }
 }
 * {
@@ -251,6 +267,163 @@ code {
 .chart-data caption {
   font-size: 15px;
 }
+.funnel-stages {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  max-width: none;
+  display: grid;
+  gap: 16px;
+}
+.funnel-stage {
+  --stage-fill: var(--series);
+  margin: 0;
+  min-width: 0;
+  font-size: 16px;
+  line-height: 1.5;
+  font-variant-numeric: tabular-nums;
+}
+.funnel-stage[data-status="on-target"] {
+  --stage-fill: var(--positive);
+}
+.funnel-stage[data-status="below-target"] {
+  --stage-fill: var(--warning);
+}
+.funnel-stage[data-status="at-risk"] {
+  --stage-fill: var(--negative);
+}
+.funnel-heading,
+.funnel-values {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 2px 12px;
+}
+.funnel-heading {
+  justify-content: space-between;
+  gap: 4px 16px;
+  overflow-wrap: anywhere;
+}
+.funnel-values {
+  color: var(--muted);
+}
+.funnel-values strong {
+  font-weight: 550;
+}
+.funnel-stage meter {
+  display: block;
+  appearance: none;
+  width: 100%;
+  height: 10px;
+  margin-block-start: 8px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--soft);
+}
+.funnel-stage meter::-webkit-meter-bar {
+  height: 10px;
+  border: 0;
+  border-radius: 999px;
+  background: var(--soft);
+  box-shadow: none;
+}
+.funnel-stage meter::-webkit-meter-optimum-value,
+.funnel-stage meter::-webkit-meter-suboptimum-value,
+.funnel-stage meter::-webkit-meter-even-less-good-value {
+  border-radius: 999px;
+  background: var(--stage-fill);
+}
+.funnel-stage meter::-moz-meter-bar {
+  border-radius: 999px;
+  background: var(--stage-fill);
+}
+.funnel-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  margin-block-start: 5px;
+  color: var(--muted);
+  font-size: 12px;
+}
+.funnel-status::before {
+  content: "";
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: var(--stage-fill);
+}
+.donut-layout {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 12px 24px;
+}
+.donut-plot {
+  flex: 1 1 180px;
+  min-width: 0;
+  max-width: 300px;
+  height: 260px;
+}
+.donut-legend {
+  flex: 1 1 210px;
+  min-width: 0;
+  max-width: 500px;
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.5;
+  font-variant-numeric: tabular-nums;
+}
+.donut-legend li {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto auto;
+  align-items: baseline;
+  gap: 8px 14px;
+  margin: 0;
+  padding-block: 10px;
+}
+.donut-key {
+  display: flex;
+  align-items: baseline;
+  gap: 9px;
+  overflow-wrap: anywhere;
+}
+.donut-swatch {
+  flex: 0 0 8px;
+  height: 8px;
+  border-radius: 50%;
+}
+.donut-swatch[data-slice="1"] {
+  background: var(--slice-1);
+}
+.donut-swatch[data-slice="2"] {
+  background: var(--slice-2);
+}
+.donut-swatch[data-slice="3"] {
+  background: var(--slice-3);
+}
+.donut-swatch[data-slice="4"] {
+  background: var(--slice-4);
+}
+.donut-swatch[data-slice="5"] {
+  background: var(--slice-5);
+}
+.donut-swatch[data-slice="6"] {
+  background: var(--slice-6);
+}
+.donut-swatch[data-slice="7"] {
+  background: var(--slice-7);
+}
+.donut-swatch[data-slice="8"] {
+  background: var(--slice-8);
+}
+.donut-value {
+  color: var(--ink);
+}
+.donut-share {
+  color: var(--muted);
+}
 .table-scroll {
   max-width: 100%;
   overflow: auto;

package/dist/cli.js

@@ -66,6 +66,14 @@ ${d.hint}` : ""}`).join(`
 import path2 from "node:path";
 import { open, realpath, stat } from "node:fs/promises";
 
+// src/shared/payload.ts
+var funnelStatuses = {
+  "on-target": "On target",
+  "below-target": "Below target",
+  "at-risk": "At risk",
+  neutral: "Neutral"
+};
+
 // src/shared/limits.ts
 var limits = {
   markdownBytes: 1024 ** 2,
@@ -74,6 +82,8 @@ var limits = {
   datasets: 64,
   rows: 1e5,
   chartRows: 1e4,
+  donutSlices: 8,
+  funnelStages: 20,
   tableRows: 1000,
   tableColumns: 40
 };
@@ -207,13 +217,15 @@ class DataResolver {
     for (const block of blocks) {
       if (block.type !== "component")
         continue;
-      if (block.name === "line" || block.name === "area" || block.name === "bar" || block.name === "table") {
+      if (block.name === "line" || block.name === "area" || block.name === "bar" || block.name === "donut" || block.name === "funnel" || block.name === "table") {
         const rows = await this.load(block.props.data, block);
         if (rows) {
           if (!rows.length)
             this.diagnostics.add("W_DATA_EMPTY", `${block.props.data} is empty; a no-data state will be shown.`, block.position, "Field validation requires at least one record.", "warning");
           if (block.name === "table")
             this.resolveTable(block, rows);
+          else if (block.name === "donut" || block.name === "funnel")
+            this.resolveParts(block, rows);
           else
             this.resolveChart(block, rows);
         }
@@ -265,6 +277,71 @@ class DataResolver {
     }
     block.rows = rows.map((row) => Object.fromEntries([...new Set([x, y])].map((key) => [key, row[key]])));
   }
+  resolveParts(block, rows) {
+    const props = block.props;
+    const maximum = block.name === "donut" ? limits.donutSlices : limits.funnelStages;
+    const fields = block.name === "donut" ? [block.props.category, props.value] : [
+      block.props.stage,
+      props.value,
+      block.props.total,
+      block.props.share,
+      ...block.props.status ? [block.props.status] : []
+    ];
+    const fail = (code, message, hint) => {
+      this.diagnostics.add(code, `${props.data}: ${message}`, block.position, hint);
+    };
+    if (rows.length > maximum) {
+      fail("E_DATA_LIMIT", `${block.name} supports at most ${maximum} rows.`, "Prepare a smaller summary; plotleaf does not group or truncate data.");
+      return;
+    }
+    if (fields.some((field) => !this.field(rows, field, block)))
+      return;
+    const seen = new Set;
+    let sum = 0;
+    for (const [index, row] of rows.entries()) {
+      const name = row[fields[0]];
+      const value = row[props.value];
+      if (typeof name !== "string" || !name.trim() || name.length > 1000) {
+        fail("E_DATA_TYPE", `Row ${index + 1}: ${JSON.stringify(fields[0])} must be a nonblank string of at most 1000 characters.`, "Supply a short, explicit label for every category or stage.");
+        return;
+      }
+      if (seen.has(name)) {
+        fail("E_DATA_ORDER", `Row ${index + 1}: category/stage labels must be unique.`, "Prepare distinct labels; source order is preserved.");
+        return;
+      }
+      seen.add(name);
+      if (typeof value !== "number" || value < 0) {
+        fail("E_DATA_TYPE", `Row ${index + 1}: ${JSON.stringify(props.value)} must be a nonnegative number.`, "Use finite JSON numbers, not nulls or numeric strings.");
+        return;
+      }
+      if (block.name === "donut") {
+        sum += value;
+        if (!Number.isFinite(sum)) {
+          fail("E_DATA_VALUE", "The donut total exceeds the finite numeric range.", "Prepare values in smaller units before rendering.");
+          return;
+        }
+      } else {
+        const total = row[block.props.total];
+        const share = row[block.props.share];
+        if (typeof total !== "number" || total <= 0 || value > total || typeof share !== "number" || share < 0 || share > 1) {
+          fail("E_DATA_VALUE", `Row ${index + 1}: total must be positive, value must not exceed total, and share must be a number from 0 to 1.`, "Supply each stage's denominator and prepared ratio explicitly; use an empty array when no baseline exists.");
+          return;
+        }
+        if (Math.abs(share - value / total) > 0.0005 + Number.EPSILON) {
+          fail("E_DATA_VALUE", `Row ${index + 1}: share does not match value / total.`, "Prepare a ratio consistent with the displayed values; rounding to 0.1 percentage point is supported.");
+          return;
+        }
+        if (block.props.status) {
+          const status = row[block.props.status];
+          if (typeof status !== "string" || !Object.hasOwn(funnelStatuses, status)) {
+            fail("E_DATA_VALUE", `Row ${index + 1}: status must be ${Object.keys(funnelStatuses).join(", ")}.`, "Supply business status explicitly, or omit the status property for neutral styling.");
+            return;
+          }
+        }
+      }
+    }
+    block.rows = rows.map((row) => Object.fromEntries(fields.map((field) => [field, row[field]])));
+  }
   resolveTable(block, rows) {
     if (rows.length > limits.tableRows) {
       this.diagnostics.add("E_DATA_LIMIT", `Table exceeds ${limits.tableRows} rows.`, block.position, "Provide a prepared summary table; rows are never silently truncated.");
@@ -330,7 +407,16 @@ var line = z.strictObject({
 var registry = {
   grid: {
     forms: ["container"],
-    children: ["metric", "line", "area", "bar", "table", "callout"],
+    children: [
+      "metric",
+      "line",
+      "area",
+      "bar",
+      "donut",
+      "funnel",
+      "table",
+      "callout"
+    ],
     description: "A responsive row of one to four components.",
     schema: z.strictObject({
       columns: z.number().int().min(1).max(4).default(2)
@@ -374,6 +460,48 @@ var registry = {
     schema: z.strictObject(chart),
     example: '::bar{data="./errors.json" x="category" y="count" title="Errors by category"}'
   },
+  donut: {
+    forms: ["leaf"],
+    children: [],
+    description: "A part-to-whole donut with a readable legend and native data table.",
+    schema: z.strictObject({
+      data: text,
+      category: text,
+      value: text,
+      title: text,
+      format: format.default("number")
+    }),
+    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: limits.donutSlices
+    },
+    example: '::donut{data="./plans.json" category="plan" value="teams" title="Teams by plan"}'
+  },
+  funnel: {
+    forms: ["leaf"],
+    children: [],
+    description: "Ordered stage/progress rows with prepared values, denominators, shares and optional explicit status. Works without JavaScript.",
+    schema: z.strictObject({
+      data: text,
+      stage: text,
+      value: text,
+      total: text,
+      share: text,
+      status: text.optional(),
+      title: text,
+      format: format.default("number")
+    }),
+    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: Object.keys(funnelStatuses),
+      maximumRows: limits.funnelStages
+    },
+    example: '::funnel{data="./funnel.json" stage="stage" value="teams" total="baseline" share="share" status="status" title="Funnel by stage"}'
+  },
   table: {
     forms: ["leaf", "container"],
     children: ["column"],
@@ -432,7 +560,8 @@ function componentSpec() {
         forms: entry.forms,
         children: entry.children,
         props: z.toJSONSchema(entry.schema),
-        example: entry.example
+        example: entry.example,
+        ..."dataRules" in entry ? { dataRules: entry.dataRules } : {}
       }
     ])),
     rules: [
@@ -444,6 +573,8 @@ function componentSpec() {
       "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."
     ]
   };
@@ -467,6 +598,11 @@ function decodeProps(name, attributes) {
     };
   const props = result.data;
   const errors = [];
+  if (name === "donut" || name === "funnel") {
+    const fields = Object.entries(props).filter(([key, value]) => ["category", "stage", "value", "total", "share", "status"].includes(key) && value !== undefined).map(([, value]) => value);
+    if (new Set(fields).size !== fields.length)
+      errors.push(`${name} field properties must reference different dataset fields.`);
+  }
   if ("format" in props && props.format?.startsWith("currency:") && !Intl.supportedValuesOf("currency").includes(props.format.slice(9)))
     errors.push(`Unknown ISO currency code ${props.format.slice(9)}.`);
   if (name === "metric" && !props.comparison && (attributes.direction !== undefined || attributes.sentiment !== undefined))
@@ -732,7 +868,8 @@ var serializer = unified2().use(rehypeSanitize, {
     "figure",
     "figcaption",
     "button",
-    "caption"
+    "caption",
+    "meter"
   ],
   attributes: {
     ...defaultSchema.attributes,
@@ -751,10 +888,16 @@ var serializer = unified2().use(rehypeSanitize, {
       "dataRaw",
       "dataColumns",
       "dataSentiment",
-      "dataTone"
+      "dataTone",
+      "dataStatus",
+      "dataSlice"
     ],
     button: ["type", "disabled", "ariaLabel", "dataColumn"],
     section: ["className", "ariaLabel"],
+    meter: ["min", "max", "value", "className", "ariaLabel"],
+    ul: ["className", "role"],
+    ol: ["start", "className", "role"],
+    li: ["className", "dataStatus"],
     th: ["scope", "ariaSort", "className"],
     td: ["className", "dataRaw"]
   }
@@ -812,6 +955,15 @@ function table(rows, columns, title, id, sortable = true) {
     ])
   ]);
 }
+function dataDisclosure(rows, columns, title, id) {
+  return h("details", { className: ["chart-data"] }, [
+    h("summary", {}, [
+      t("View data"),
+      h("span", { className: ["visually-hidden"] }, [t(` for ${title}`)])
+    ]),
+    table(rows, columns, title, `${id}-data`, false)
+  ]);
+}
 function renderContent(report) {
   let sequence = 0;
   const payload = { charts: [] };
@@ -913,6 +1065,10 @@ function renderContent(report) {
           ];
         case "column":
           return [];
+        case "funnel":
+          return renderFunnel(block, id);
+        case "donut":
+          return renderDonut(block, id);
         case "line":
         case "area":
         case "bar":
@@ -920,6 +1076,156 @@ function renderContent(report) {
       }
     });
   }
+  function renderFunnel(block, id) {
+    const { stage, value, total, share, status, title, format } = block.props;
+    const rows = block.rows ?? [];
+    const columns = [
+      { field: stage, label: label(stage), sign: "auto", semantics: "neutral" },
+      {
+        field: value,
+        label: label(value),
+        format,
+        sign: "auto",
+        semantics: "neutral"
+      },
+      {
+        field: total,
+        label: label(total),
+        format,
+        sign: "auto",
+        semantics: "neutral"
+      },
+      {
+        field: share,
+        label: "Share",
+        format: "percent",
+        sign: "auto",
+        semantics: "neutral"
+      },
+      ...status ? [
+        {
+          field: status,
+          label: "Status",
+          sign: "auto",
+          semantics: "neutral"
+        }
+      ] : []
+    ];
+    return [
+      h("figure", { className: ["chart", "funnel"] }, [
+        h("figcaption", { id: `${id}-title` }, [t(title)]),
+        ...rows.length ? [
+          h("ol", { className: ["funnel-stages"], role: "list" }, rows.map((row) => {
+            const state = status ? row[status] : "neutral";
+            const rate = formatValue(row[share], "percent");
+            const amount = formatValue(row[value], format, "auto", true);
+            const denominator = formatValue(row[total], format, "auto", true);
+            return h("li", { className: ["funnel-stage"], dataStatus: state }, [
+              h("div", { className: ["funnel-heading"] }, [
+                h("span", { className: ["funnel-label"] }, [
+                  t(row[stage])
+                ]),
+                h("span", { className: ["funnel-values"] }, [
+                  h("strong", {}, [t(rate)]),
+                  h("span", {}, [t(`${amount} / ${denominator}`)])
+                ])
+              ]),
+              h("meter", {
+                min: "0",
+                max: "1",
+                value: String(row[share]),
+                ariaLabel: `${row[stage]}: ${rate}, ${formatValue(row[value], format)} of ${formatValue(row[total], format)}${status ? `, ${funnelStatuses[state]}` : ""}`
+              }, [t(rate)]),
+              ...status ? [
+                h("span", { className: ["funnel-status"] }, [
+                  t(funnelStatuses[state])
+                ])
+              ] : []
+            ]);
+          }))
+        ] : [
+          h("p", { className: ["empty-state"] }, [
+            t("No data to display.")
+          ])
+        ],
+        ...rows.length ? [
+          dataDisclosure(rows.map((row) => status ? {
+            ...row,
+            [status]: funnelStatuses[row[status]]
+          } : row), columns, title, id)
+        ] : []
+      ])
+    ];
+  }
+  function renderDonut(block, id) {
+    const { category, value, title, format } = block.props;
+    const rows = block.rows ?? [];
+    const total = rows.reduce((sum, row) => sum + row[value], 0);
+    if (total > 0)
+      payload.charts.push({
+        id,
+        kind: "donut",
+        title,
+        format,
+        rows: rows.map((row) => [
+          row[category],
+          row[value]
+        ])
+      });
+    return [
+      h("figure", { className: ["chart", "donut"] }, [
+        h("figcaption", { id: `${id}-title` }, [t(title)]),
+        ...total > 0 ? [
+          h("div", { className: ["donut-layout"] }, [
+            h("div", {
+              className: ["chart-plot", "donut-plot"],
+              id,
+              dataPlotleafChart: "",
+              role: "img",
+              ariaLabel: `${title}. Values and shares follow in the legend and data table.`
+            }),
+            h("ul", { className: ["donut-legend"], role: "list" }, rows.map((row, index) => h("li", {}, [
+              h("span", { className: ["donut-key"] }, [
+                h("span", {
+                  className: ["donut-swatch"],
+                  dataSlice: index + 1,
+                  ariaHidden: "true"
+                }),
+                h("span", {}, [t(row[category])])
+              ]),
+              h("span", { className: ["donut-value"] }, [
+                t(formatValue(row[value], format))
+              ]),
+              h("span", { className: ["donut-share"] }, [
+                t(formatValue(row[value] / total, "percent"))
+              ])
+            ])))
+          ])
+        ] : [
+          h("p", { className: ["empty-state"] }, [
+            t(rows.length ? "No non-zero values to display." : "No data to display.")
+          ])
+        ],
+        ...rows.length ? [
+          dataDisclosure(rows, [
+            {
+              field: category,
+              label: label(category),
+              sign: "auto",
+              semantics: "neutral"
+            },
+            {
+              field: value,
+              label: label(value),
+              format,
+              sign: "auto",
+              semantics: "neutral"
+            }
+          ], title, id)
+        ] : []
+      ])
+    ];
+  }
   function renderChart(block, id) {
     const { x, y, title, format } = block.props;
     const xType = block.name === "bar" ? "category" : block.props.xType;
@@ -964,17 +1270,7 @@ function renderContent(report) {
             t("No data to display.")
           ])
         ],
-        ...rows.length ? [
-          h("details", { className: ["chart-data"] }, [
-            h("summary", {}, [
-              t("View data"),
-              h("span", { className: ["visually-hidden"] }, [
-                t(` for ${title}`)
-              ])
-            ]),
-            table(rows, columns, title, `${id}-data`, false)
-          ])
-        ] : []
+        ...rows.length ? [dataDisclosure(rows, columns, title, id)] : []
       ])
     ];
   }
@@ -1235,10 +1531,18 @@ data: ${revision}
 // package.json
 var package_default = {
   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"
   },
@@ -1257,6 +1561,8 @@ var package_default = {
     "examples/storefront/*.json",
     "examples/adoption/*.md",
     "examples/adoption/*.json",
+    "examples/onboarding/*.md",
+    "examples/onboarding/*.json",
     "skills/plotleaf/SKILL.md",
     "README.md",
     "LICENSE",

package/examples/onboarding/funnel.json

@@ -0,0 +1,30 @@
+[
+  {
+    "stage": "Visited",
+    "teams": 41200,
+    "baseline": 41200,
+    "share": 1.0,
+    "status": "on-target"
+  },
+  {
+    "stage": "Signed up",
+    "teams": 12480,
+    "baseline": 41200,
+    "share": 0.3029126213592233,
+    "status": "on-target"
+  },
+  {
+    "stage": "Activated",
+    "teams": 7612,
+    "baseline": 41200,
+    "share": 0.18475728155339805,
+    "status": "below-target"
+  },
+  {
+    "stage": "Converted",
+    "teams": 1284,
+    "baseline": 41200,
+    "share": 0.03116504854368932,
+    "status": "at-risk"
+  }
+]

package/examples/onboarding/plans.json

@@ -0,0 +1,14 @@
+[
+  {
+    "plan": "Pro",
+    "teams": 5100
+  },
+  {
+    "plan": "Team",
+    "teams": 1900
+  },
+  {
+    "plan": "Free",
+    "teams": 612
+  }
+]