@karimsa/mdxserve 0.2.0 → 0.4.0

package/dist/diagram-worker.js

@@ -0,0 +1,17 @@
+// src/diagrams/adapters/validate-worker.ts
+import { parentPort, workerData } from "node:worker_threads";
+import { JSDOM } from "jsdom";
+var dom = new JSDOM("<!doctype html><html><body></body></html>");
+Object.assign(globalThis, { window: dom.window, document: dom.window.document });
+try {
+  const { default: mermaid } = await import("mermaid");
+  mermaid.initialize({ startOnLoad: false, securityLevel: "strict" });
+  await mermaid.parse(workerData.source);
+  parentPort?.postMessage(null);
+} catch (error) {
+  parentPort?.postMessage(
+    (error instanceof Error ? error.message : "Invalid Mermaid").slice(0, 2e3)
+  );
+} finally {
+  dom.window.close();
+}

package/dist/registry.json

@@ -1,6 +1,303 @@
 {
   "version": 1,
   "components": [
+    {
+      "name": "DataTable",
+      "description": "A bordered, sortable, filterable data table with typed columns, unit selection, grouped headers and optional bars.",
+      "whenToUse": "Use for datasets and quantitative comparisons; use native Markdown tables for facts and prose. Required stable document-unique id. Columns have key, label, type (text/number/percent/time/bytes/currency), optional group and bars. Percent values are fractions (0.15 means 15%). Time and bytes require unit; currency requires a format function and numeric data. Bars are opt-in and independently scaled by column. Reader state is local to the document and ID.",
+      "props": {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Required stable ID, unique within this document. Retain it across edits to preserve local sorting, filters and units."
+          },
+          "caption": {
+            "type": "string"
+          },
+          "columns": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "oneOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "group": {
+                      "type": "string"
+                    },
+                    "align": {
+                      "description": "Explicit alignment overrides the column type default.",
+                      "type": "string",
+                      "enum": [
+                        "left",
+                        "center",
+                        "right"
+                      ]
+                    },
+                    "bars": {
+                      "description": "Opt-in magnitude bars; zero is always included in the scale.",
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "type": "string",
+                      "const": "text"
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "type"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "group": {
+                      "type": "string"
+                    },
+                    "align": {
+                      "description": "Explicit alignment overrides the column type default.",
+                      "type": "string",
+                      "enum": [
+                        "left",
+                        "center",
+                        "right"
+                      ]
+                    },
+                    "bars": {
+                      "description": "Opt-in magnitude bars; zero is always included in the scale.",
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "type": "string",
+                      "const": "number"
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "type"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "group": {
+                      "type": "string"
+                    },
+                    "align": {
+                      "description": "Explicit alignment overrides the column type default.",
+                      "type": "string",
+                      "enum": [
+                        "left",
+                        "center",
+                        "right"
+                      ]
+                    },
+                    "bars": {
+                      "description": "Opt-in magnitude bars; zero is always included in the scale.",
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "type": "string",
+                      "const": "percent"
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "type"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "group": {
+                      "type": "string"
+                    },
+                    "align": {
+                      "description": "Explicit alignment overrides the column type default.",
+                      "type": "string",
+                      "enum": [
+                        "left",
+                        "center",
+                        "right"
+                      ]
+                    },
+                    "bars": {
+                      "description": "Opt-in magnitude bars; zero is always included in the scale.",
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "type": "string",
+                      "const": "time"
+                    },
+                    "unit": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "type",
+                    "unit"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "group": {
+                      "type": "string"
+                    },
+                    "align": {
+                      "description": "Explicit alignment overrides the column type default.",
+                      "type": "string",
+                      "enum": [
+                        "left",
+                        "center",
+                        "right"
+                      ]
+                    },
+                    "bars": {
+                      "description": "Opt-in magnitude bars; zero is always included in the scale.",
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "type": "string",
+                      "const": "bytes"
+                    },
+                    "unit": {
+                      "type": "string",
+                      "minLength": 1
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "type",
+                    "unit"
+                  ]
+                },
+                {
+                  "type": "object",
+                  "properties": {
+                    "key": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "label": {
+                      "type": "string",
+                      "minLength": 1
+                    },
+                    "group": {
+                      "type": "string"
+                    },
+                    "align": {
+                      "description": "Explicit alignment overrides the column type default.",
+                      "type": "string",
+                      "enum": [
+                        "left",
+                        "center",
+                        "right"
+                      ]
+                    },
+                    "bars": {
+                      "description": "Opt-in magnitude bars; zero is always included in the scale.",
+                      "type": "boolean"
+                    },
+                    "type": {
+                      "type": "string",
+                      "const": "currency"
+                    },
+                    "format": {
+                      "description": "Required numeric-to-string currency formatter, e.g. value => `$${value}`"
+                    }
+                  },
+                  "required": [
+                    "key",
+                    "label",
+                    "type",
+                    "format"
+                  ]
+                }
+              ]
+            },
+            "description": "Ordered columns: key, label, type; optional group and bars. Time/bytes require a base unit. Percent data uses fractions (0.15 displays 15%). Currency requires format(value)."
+          },
+          "data": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "propertyNames": {
+                "type": "string"
+              },
+              "additionalProperties": {
+                "anyOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "number"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              }
+            }
+          }
+        },
+        "required": [
+          "id",
+          "columns",
+          "data"
+        ]
+      }
+    },
     {
       "name": "Callout",
       "description": "A boxed aside with an icon, used to draw attention to a note or warning inline with the text.",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@karimsa/mdxserve",
-	"version": "0.2.0",
+	"version": "0.4.0",
 	"description": "Serve a directory of Markdown/MDX files, like `serve` but for docs",
 	"license": "MIT",
 	"repository": {
@@ -26,7 +26,7 @@
 	"scripts": {
 		"build": "tsx scripts/build.ts",
 		"registry": "tsx scripts/build-registry.ts",
-		"dev": "tsx scripts/build-registry.ts && tsx src/index.ts serve -w example",
+		"dev": "tsx scripts/build.ts && tsx src/index.ts serve -w example",
 		"typecheck": "tsc --noEmit",
 		"format": "prettier --write .",
 		"format:check": "prettier --check .",
@@ -43,6 +43,7 @@
 		"access": "public"
 	},
 	"dependencies": {
+		"@floating-ui/dom": "1.8.0",
 		"@fontsource-variable/jetbrains-mono": "5.3.0",
 		"@fontsource-variable/manrope": "5.3.0",
 		"@mdx-js/mdx": "3.1.1",
@@ -52,56 +53,95 @@
 		"@tanstack/react-query": "5.101.4",
 		"@tippyjs/react": "4.2.6",
 		"@tiptap/core": "3.29.2",
+		"@tiptap/extension-blockquote": "3.29.2",
+		"@tiptap/extension-bold": "3.29.2",
+		"@tiptap/extension-bubble-menu": "3.29.2",
+		"@tiptap/extension-bullet-list": "3.29.2",
+		"@tiptap/extension-code": "3.29.2",
+		"@tiptap/extension-code-block": "3.29.2",
+		"@tiptap/extension-document": "3.29.2",
+		"@tiptap/extension-dropcursor": "3.29.2",
+		"@tiptap/extension-floating-menu": "3.29.2",
+		"@tiptap/extension-gapcursor": "3.29.2",
+		"@tiptap/extension-hard-break": "3.29.2",
+		"@tiptap/extension-heading": "3.29.2",
+		"@tiptap/extension-horizontal-rule": "3.29.2",
 		"@tiptap/extension-image": "3.29.2",
+		"@tiptap/extension-italic": "3.29.2",
+		"@tiptap/extension-link": "3.29.2",
 		"@tiptap/extension-list": "3.29.2",
+		"@tiptap/extension-list-item": "3.29.2",
+		"@tiptap/extension-list-keymap": "3.29.2",
+		"@tiptap/extension-ordered-list": "3.29.2",
+		"@tiptap/extension-paragraph": "3.29.2",
+		"@tiptap/extension-strike": "3.29.2",
 		"@tiptap/extension-table": "3.29.2",
+		"@tiptap/extension-text": "3.29.2",
+		"@tiptap/extension-underline": "3.29.2",
+		"@tiptap/extensions": "3.29.2",
 		"@tiptap/markdown": "3.29.2",
 		"@tiptap/pm": "3.29.2",
 		"@tiptap/react": "3.29.2",
 		"@tiptap/starter-kit": "3.29.2",
+		"@tiptap/suggestion": "3.29.2",
 		"@trpc/client": "11.18.0",
 		"@trpc/server": "11.18.0",
 		"@trpc/tanstack-react-query": "11.18.0",
 		"@vitejs/plugin-react": "6.0.5",
+		"bytes": "3.1.2",
 		"commander": "15.0.0",
+		"cross-spawn": "7.0.6",
 		"date-fns": "4.4.0",
 		"diff": "9.0.0",
 		"framer-motion": "13.0.0",
 		"hast-util-to-html": "9.0.5",
 		"jotai": "2.20.2",
+		"jsdom": "27.4.0",
 		"lockfile": "1.0.4",
 		"lucide-react": "1.30.0",
 		"mdast-util-from-markdown": "2.0.3",
+		"mdast-util-frontmatter": "2.0.1",
 		"mdast-util-mdx": "3.0.0",
 		"mdast-util-to-hast": "13.2.1",
 		"mdast-util-to-string": "4.0.0",
 		"mermaid": "10.9.8",
+		"micromark-extension-frontmatter": "2.0.0",
 		"micromark-extension-mdxjs": "3.0.0",
 		"minisearch": "7.2.0",
+		"ms": "2.1.3",
 		"node-sqlite3-wasm": "0.8.60",
 		"react": "19.2.8",
 		"react-dom": "19.2.8",
 		"react-hot-toast": "2.6.0",
 		"rehype-pretty-code": "0.14.5",
 		"rehype-slug": "6.0.0",
+		"remark-frontmatter": "5.0.0",
 		"remark-gfm": "4.0.1",
+		"rollup": "4.64.0",
+		"sharp": "0.35.5",
 		"shiki": "4.4.2",
 		"svg-pan-zoom": "3.6.2",
 		"tailwindcss": "4.3.3",
 		"tippy.js": "6.3.7",
 		"trash": "10.1.1",
+		"update-notifier": "7.3.1",
 		"vfile-message": "4.0.3",
 		"vite": "8.2.1",
 		"zod": "4.4.3",
 		"zx": "8.8.5"
 	},
 	"devDependencies": {
+		"@types/bytes": "3.1.6",
+		"@types/cross-spawn": "6.0.6",
+		"@types/jsdom": "30.0.0",
 		"@types/lockfile": "1.0.4",
 		"@types/mdast": "4.0.4",
+		"@types/ms": "2.1.0",
 		"@types/node": "26.2.0",
 		"@types/react": "19.2.18",
 		"@types/react-dom": "19.2.4",
 		"@types/svg-pan-zoom": "3.4.0",
+		"@types/update-notifier": "6.0.8",
 		"@yarnpkg/types": "4.0.1",
 		"esbuild": "0.28.2",
 		"fast-check": "4.9.0",

package/skills/mdxserve/SKILL.md

@@ -30,7 +30,7 @@ add clarity, and prefer features that degrade gracefully everywhere else.
    error on them, and they draw data, which is `<Chart>`'s job (or a table). Mermaid is for a
    flow or a shape, not a dataset.
 4. **Builtin components** (`<Callout>`, `<Tabs>`, `<Badge>`, `<Tooltip>`, `<Button>`, `<Diff>`, `<Card>`,
-   `<Kbd>`, `<FileTree>`, `<Chart>` (bar, line, area, histogram), `<Sparkline>`, `<Screenshot>`) only when they make
+   `<Kbd>`, `<FileTree>`, `<DataTable>`, `<Chart>` (bar, line, area, histogram), `<Sparkline>`, `<Screenshot>`) only when they make
    the content clearer: a warning the reader must not miss, per-OS or per-language variants of the
    same instructions, a status label, a small dataset that's clearer as a shape than a table.
    Outside mdxserve these show as raw tags, so use them sparingly and never for decoration.
@@ -134,6 +134,61 @@ Components contain ordinary Markdown: a `Tab` can hold lists, paragraphs, and co
 Leave a blank line between a component tag and a Markdown block inside it so the block is
 parsed as Markdown.
 
+## Tables: data versus facts
+
+Use **`DataTable` for datasets**: measurements, metrics, budgets, benchmarks, and records
+readers will compare, sort, or filter. Use **native Markdown tables for facts**: option
+references, prose comparisons, and key/value documentation. Native tables get the same
+bordered interface with conservative type detection; they do not automatically get bars.
+Native tables use heading context for generated IDs. Same-header tables within the same
+heading context remain interactive but do not persist preferences; use explicit `DataTable`
+IDs when persistent state is required for those tables.
+Both forms work identically in `.md` and `.mdx`. For documents mainly read elsewhere,
+retain portable Markdown unless richer mdxserve content was requested.
+
+Check `mdxserve components show DataTable` before first use. Supply a stable, descriptive
+`id` unique within the document, and preserve it when updating data. Sorting, filters, and
+unit preferences are saved locally under the document and ID. Give columns stable unique
+`key` values; row objects use those keys. Missing values use `null`, never an invented zero.
+
+```mdx
+<DataTable
+  id="endpoint-performance"
+  caption="Endpoint performance"
+  columns={[
+    { key: "endpoint", label: "Endpoint", type: "text" },
+    { key: "success", label: "Success", type: "percent" },
+    { key: "mean", label: "Mean", type: "time", unit: "ms", group: "Latency", bars: true },
+    { key: "peak", label: "Peak", type: "time", unit: "ms", group: "Latency", bars: true },
+    { key: "payload", label: "Payload", type: "bytes", unit: "B" },
+    { key: "cost", label: "Cost", type: "currency", format: (value) => `$${value.toFixed(2)}` }
+  ]}
+  data={[
+    { endpoint: "/search", success: 0.995, mean: 120, peak: 450, payload: 2048, cost: 12.50 },
+    { endpoint: "/export", success: 0.98, mean: 2400, peak: 8000, payload: 1048576, cost: 25 }
+  ]}
+/>
+```
+
+- `text` uses strings; readers filter with a regular expression, case-insensitive.
+- `number` uses finite numbers; readers filter by inclusive minimum and maximum.
+- `percent` uses **fractions**: `0.15` displays **15%**. Filter inputs use displayed percentage
+  points (`15` or `15%`), not fractions.
+- `time` uses numeric data and a required base `unit` accepted by `ms` (e.g. `ms`, `seconds`,
+  `hours`). One unit is chosen for the entire column; readers can override it. Filters accept
+  durations such as `500ms` or `2s`; bare numbers use the currently displayed unit.
+- `bytes` uses numeric data and a required base `unit` accepted by `bytes` (`B`, `KB`, `MB`,
+  `GB`, `TB`, `PB`). Units are binary (1 KB = 1024 B). The whole column shares a display unit;
+  filters accept `10MB`, or bare numbers in the displayed unit.
+- `currency` keeps numeric data and **requires `format: (value) => string`**. Include the
+  intended currency in that formatter or label. Filters expand `10K`, `2M`, `1B`, and `1T`.
+- Adjacent columns with the same `group` get a shared top-level heading.
+- Optional `align: "left" | "center" | "right"` overrides type-based alignment. Native Markdown tables preserve explicit GFM delimiter alignment.
+- Set `bars: true` only when comparing magnitudes is meaningful. Omit it for IDs, years,
+  ranks, or ambiguous measurements. Each column has its own zero-inclusive scale, fixed
+  across sorting/filtering; negative values extend left of zero. Equal bar lengths across
+  different columns do not imply equal quantities.
+
 ## Plan files
 
 Plans are read in mdxserve and in plain text. Use headings for phases, a task list per phase,