@pithyjs/pidl-catalog 0.1.0-beta.0 → 0.1.0-beta.2

package/README.md

@@ -0,0 +1,74 @@
+# @pithyjs/pidl-catalog
+
+Machine-readable component contracts for [PithyJS](https://github.com/PithyJS/pithyjs).
+
+A **PIDL spec** is a JSON document declaring a component's props, types,
+defaults, slots, events and accessibility guarantees. The catalog is what lets
+tooling reason about a component without reading its source: the props panels,
+the AI content projector and the registry generator all read these same files.
+
+Coverage is partial and growing — `IconButton`, `Tooltip`, `Popover`, `NavLink`
+and `ErrorBoundary` have no spec yet.
+
+> **Beta.** Published under the `beta` tag alongside the rest of the PithyJS
+> packages. The spec shape is still moving; pin an exact version.
+
+## Install
+
+```bash
+npm install @pithyjs/pidl-catalog@beta
+```
+
+## What is in it
+
+Specs ship at `dist/specs/`, organised by atomic level (`atoms/`, `layout/`,
+`organisms/`, `sections/`). Enumerate them from `ALL_PIDL_SPECS` rather than
+relying on a count in prose — this file cannot recount itself when a spec
+lands.
+
+A spec's top level looks like this:
+
+```jsonc
+{
+  "kind": "component",
+  "id": "ui.button",
+  "name": "Button",
+  "level": "atom",
+  "domain": "actions",
+  "description": "...",
+  "props": { /* name -> type, default, constraints */ },
+  "events": { /* ... */ },
+  "slots": { /* ... */ }
+}
+```
+
+## Usage
+
+```ts
+import { ALL_PIDL_SPECS } from '@pithyjs/pidl-catalog';
+```
+
+Design-intelligence tables are separate entry points, so importing one does not
+pull the others:
+
+```ts
+import { COLOR_PSYCHOLOGY_GUIDANCE } from '@pithyjs/pidl-catalog/color-psychology';
+import { MUTATION_VOCABULARY } from '@pithyjs/pidl-catalog/mutation-vocabulary';
+import { DESIGN_INTELLIGENCE_RULES } from '@pithyjs/pidl-catalog/design-intelligence';
+```
+
+Available subpaths: `design-intelligence`, `mutation-vocabulary`, and the
+`*-psychology` tables for `color`, `typography`, `spacing`, `radius`,
+`shadows`, `motion` and `borders`.
+
+## Why it exists
+
+A component library documented only in prose forces every tool that consumes it
+to guess — at which props exist, which values are legal, and which
+accessibility rules are non-negotiable. PIDL makes those machine-checkable, so
+"the model never writes CSS" can be enforced by the build rather than asked for
+in a prompt.
+
+## License
+
+MIT

package/dist/specs/atoms/data/bars.pidl.json

@@ -0,0 +1,315 @@
+{
+    "kind": "component",
+    "id": "ui.bars",
+    "name": "Bars",
+    "displayName": "Bar Chart",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "data",
+    "bidi": true,
+    "description": "Horizontal bar chart for comparing categories against one shared scale. Each row is a category name, a track with a proportional fill, and the value — rows are independent, so no bar is affected by its neighbours. Rendered in DOM rather than SVG so names can ellipsis, numbers can be tabular, and text rescales with the reader's own font size. The drawing is aria-hidden; a visually-hidden data table carries every exact value and is the chart's accessible representation. There is no colour key: every row already carries its own name and number. Loading, empty (no rows at all — an all-zero chart stays ready, because its rows still name themselves), and error states are first-class.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Accessible name",
+            "type": "string",
+            "required": true,
+            "placeholder": "Traffic by source",
+            "description": "Captions the visually-hidden data table screen readers read instead of the graphic. Required — it is the chart's accessible name."
+        },
+        {
+            "name": "bars",
+            "label": "Rows",
+            "type": "BarDatum[] | Signal<BarDatum[]>",
+            "required": true,
+            "reactive": true,
+            "placeholder": [
+                { "label": "Search", "value": 420 },
+                { "label": "Direct", "value": 260 },
+                { "label": "Referral", "value": 130 }
+            ],
+            "description": "Rows in display order. A value must be a finite number >= 0; anything else is counted as zero, warned about in DEV, and still listed in the accessible table.",
+            "itemSchema": {
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Category name. Shown beside the bar, truncated with an ellipsis when the column is too narrow, and used as the row header in the accessible table."
+                },
+                "value": {
+                    "type": "number",
+                    "required": true,
+                    "description": "The quantity. Finite and >= 0."
+                },
+                "color": {
+                    "type": "string",
+                    "editor": { "type": "token-color" },
+                    "enum": [
+                        "primary",
+                        "secondary",
+                        "tertiary",
+                        "success",
+                        "info",
+                        "warning",
+                        "danger",
+                        "categorical-1",
+                        "categorical-2",
+                        "categorical-3",
+                        "categorical-4",
+                        "categorical-5",
+                        "categorical-6"
+                    ],
+                    "description": "Design-token name for this bar. Omit and every row takes the same default slot. Unlike a donut, a bar chart reads perfectly with every row the same colour — the names are already there — so reach for this when a row has a genuine semantic ('danger' for an error count), not to decorate."
+                }
+            }
+        },
+        {
+            "name": "max",
+            "label": "Scale maximum",
+            "type": "number | Signal<number>",
+            "reactive": true,
+            "placeholder": 500,
+            "description": "The value a full-width bar represents. Defaults to the greatest value present, which reads well for one chart and lies across several — a chart of single digits and a chart of millions then look identical. Pass the same max to a row of charts and their bars mean the same thing. A value that is not a finite number greater than zero is not a scale: it is DEV-warned and the derived ceiling is used instead."
+        },
+        {
+            "name": "scale",
+            "label": "Value axis",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["axis", "none"],
+            "default": "axis",
+            "description": "Whether to draw the value axis under the bars. The axis is what STATES the scale: without it a full-width track means 'the ceiling' and the ceiling appears nowhere on screen, so a reader sees that 40 beats 25 but not that 40 is 40% of a budget of 100 — which is the entire point of passing `max`. Ticks land on nice numbers (a power of ten times 1, 2 or 5) so a reader can interpolate between them, and the last tick is the largest that fits AT OR BELOW the ceiling — the ceiling itself only when it is one of them. A max of 100 ends on 100; a derived ceiling of 520 ends on 500, and the full bar runs past that mark, which is itself the reading. Extending the scale past the ceiling instead would mislabel every mark, because the track still ends at the ceiling. Prefer a round max; where it is not round the exact ceiling is still stated in the table's <tfoot>. 'none' drops it: right for a stat tile, where the numbers beside the bars are the reading and the bars are decoration, and for a row of charts under one shared axis. The accessible table is unaffected either way."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Sets the track thickness and the type scale. It does NOT cap the chart's width, unlike the circular charts: a bar's inline extent is its SCALE rather than its size, and capping it at md's 12rem would leave about 3rem of track after the name and the number — not a smaller chart, an unreadable one. The chart fills its column and stays intrinsically fluid, with no breakpoints."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Hides the drawing and the table, shows a pulsing skeleton in the drawing's slot, and sets aria-busy on the drawing's wrapper. Outranks every other state."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Hides the drawing and the table and shows the error message. Outranks the empty state — a failed fetch usually leaves an empty array behind it."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "default": "Chart data unavailable",
+            "reactive": true,
+            "description": "Copy shown in the error state."
+        },
+        {
+            "name": "emptyMessage",
+            "label": "Empty message",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "No data to display",
+            "description": "Copy shown when there are no rows. NOT shown for an all-zero chart, which stays `ready` and draws its named rows at zero width — see the constraint on the empty state."
+        },
+        {
+            "name": "loadingLabel",
+            "label": "Loading message",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "Loading chart…",
+            "description": "Copy shown in the loading state."
+        },
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit element ID on the <figure> root."
+        }
+    ],
+    "events": [],
+    "slots": [],
+    "tokens": {
+        "track.background": "--color-surface-variant",
+        "fill.background": "--color-categorical-1 … --color-categorical-6, or any semantic colour",
+        "fill.background.fallback": "--color-text-muted (only a row whose explicit colour is not a recognised token)",
+        "track.radius": "--radius-xs",
+        "label.color": "--color-text-muted",
+        "value.color": "--color-text",
+        "value.font": "--font-family-mono",
+        "type.size": "--font-size-sm (--font-size-xs at sm, --font-size-body at lg)",
+        "fill.motion.duration": "--motion-duration-slow",
+        "fill.motion.easing": "--motion-easing-emphasized",
+        "status.color": "--color-text-muted",
+        "status.error.color": "--color-danger",
+        "placeholder.background": "--color-surface-variant",
+        "placeholder.radius": "--radius-md",
+        "forced-colors.border": "--border-width-thin"
+    },
+    "spacing": {
+        "internal": {
+            "label-to-track-to-value": {
+                "relationship": "close_friends",
+                "token": "sm",
+                "note": "Three parts of one reading, scanned across as a unit."
+            },
+            "row-to-row": {
+                "relationship": "friends",
+                "token": "md",
+                "note": "Separate categories, compared rather than read in sequence. Deliberately looser than the column gap, so the eye groups each row across before it groups the chart down."
+            },
+            "graphic-to-status": { "relationship": "close_friends", "token": "sm" }
+        }
+    },
+    "constraints": [
+        "Use logical properties only — no left/right, no width/height where inline-size/block-size applies",
+        "Colour is a design-token NAME, never a CSS value — there is no prop through which a hex code can reach a stylesheet",
+        "No function-valued props. Every prop has to be editable and serialisable through PIDL, so there is no formatValue callback; numbers are formatted by the kit's own formatter, which the bar's own value label and the data table both go through so the two cannot disagree",
+        "Rendered in DOM, not SVG. A bar row is text, a rectangle and a numeral — DOM gives text-overflow: ellipsis on a long category name, font-variant-numeric: tabular-nums so the value column does not jitter, and text that rescales with the reader's font setting (WCAG 1.4.4) rather than with a viewBox transform. SVG <text> offers none of the three",
+        "The graphic is aria-hidden — the visually-hidden data table is the accessible representation, so `label` is required",
+        "The chart is width-agnostic: it fills its column and `size` sets thickness and type instead. Capping a bar chart's width caps its scale, which does not shrink it, it breaks it",
+        "The scale maximum is stated as a <tfoot> row in the data table. A bar's length is a ratio and nothing on screen states the denominator, so this is the only route by which a screen reader learns what a full bar means",
+        "A bar past the ceiling is drawn full and the table still reports its true value — the clamp is a drawing decision and may not reach the data",
+        "A non-zero value too small to see is widened to a minimum visible width rather than vanishing. Rows are independent, so widening one moves nothing else; the only number misreported is its own, and only for the category a reader could not otherwise see exists. This is the OPPOSITE of the donut's rule, and deliberately so — an arc that is widened pushes every later arc round the ring",
+        "A value of zero is drawn at no width at all. Nothing is not a sliver, and a zero row still appears in the table",
+        "A chart with NO ROWS renders the empty state; the geometry never divides by zero. A chart whose rows all hold ZERO does NOT: it stays `ready`, because its rows label themselves — an all-zero bar chart still draws a named track and a numeral per category, and going empty would hide a chart a sighted reader can see while stripping those names out of the accessible tree. `<Donut>` and `<StackedBar>` do go empty on the same input, and should: their parts are named only by the key, so a key of zeroes beside a blank track states nothing the status line does not",
+        "The drawing and the data table are hidden together in every non-ready state so the two cannot disagree about whether there is data",
+        "An empty or whitespace-only row label is a MISSING label and becomes 'Series N' — a blank row header is a category a reader can neither name nor look up",
+        "Row colour defaults to ONE slot for every row, not a slot per index. A bar names itself, so a different hue per row encodes nothing — and cycling ran out: ten uncoloured rows, which this spec recommends, produced four palette-exhaustion warnings and drew rows 1-6 categorical with 7-10 neutral. An explicit per-row colour is still honoured, and an unrecognised token still falls back to the neutral mark colour",
+        "No colour key. Every row carries its own name and its own number permanently, so colour here is never the sole carrier of meaning (WCAG 1.4.1) and a key would only restate what is already on screen",
+        "The fill's width transition is inside a motion-safe block, and its width custom property defaults to 0% — an unset fill must read as an empty bar, never as a full one"
+    ],
+    "a11y": [
+        "The drawing carries aria-hidden='true' — it is a picture of the table beside it",
+        "A <table class='u-sr-only'> carries every exact value, captioned with the required `label` prop",
+        "Table headers are scoped: <th scope='col'> in the head, <th scope='row'> per row",
+        "The scale maximum is a <tfoot> row, because a bar length means nothing without the ceiling it is measured against and nothing on screen states it",
+        "Values clamped at the ceiling and widths raised by the visibility floor both appear in the table at their true values — the table is the reading of record wherever the drawing is an approximation",
+        "Zero-value rows appear in the table even though they are drawn at no width",
+        "A chart whose rows ALL hold zero stays 'ready' rather than going 'empty'. The empty state hides the table, which would take those named categories out of the accessible tree and announce 'No data to display' for a chart a sighted reader can see as named tracks at zero. Only genuinely no rows is empty — this deliberately differs from Donut and StackedBar, whose all-zero case really has nothing to draw and no per-part label anywhere",
+        "Colour is never the only encoding: each row carries its name and its number beside the bar, which is why this chart needs no key",
+        "Status messages live in a role='status' region present from first render — a live region inserted when it gains content is often not announced",
+        "aria-busy='true' while loading goes on the drawing's wrapper (.ui-chart-body), NEVER on the root. The role='status' region is a child of the root, and a live region inside an aria-busy subtree has its changes DEFERRED until busy clears — which happens in the same call that blanks the region, so the announcement an AT ends up processing is 'empty'",
+        "forced-color-adjust: none on the fills and the track, restated here because the shared partial's rule selects '.ui-chart-graphic > svg' and this chart has no SVG. In a chart the colour IS the data, so flattening the slots to one system colour would delete the encoding rather than raise contrast; the track gains a CanvasText border so the unfilled remainder stays visible",
+        "Text rescales with the reader's font-size setting rather than with the drawing, which SVG text cannot do (WCAG 1.4.4)",
+        "The fill's growth animation is inside a prefers-reduced-motion: no-preference block"
+    ],
+    "ai": {
+        "synonyms": [
+            "bar chart",
+            "horizontal bar chart",
+            "bar graph",
+            "ranked list",
+            "top categories",
+            "comparison chart",
+            "leaderboard chart",
+            "progress bars",
+            "hbar"
+        ],
+        "avoid": [
+            "Passing a CSS colour — the color field takes a design-token name",
+            "Using it for parts of one whole — that is StackedBar or Donut. These bars are independent quantities, and nothing here sums to anything",
+            "Omitting `max` when two charts are meant to be compared: without it each chart scales to its own largest value and the two are silently incomparable",
+            "Expecting a colour key — there is none, and none is needed: every row is labelled",
+            "Encoding meaning with the semantic palette for arbitrary categories (danger for 'category 3' says category 3 is bad)",
+            "Wrapping it in a fixed narrow column: the chart fills its column and a bar needs width to be a scale",
+            "Relying on the graphic alone for accessibility — the table is the accessible representation and `label` captions it"
+        ],
+        "patterns": [
+            "Basic: <Bars label=\"'Traffic by source'\" bars=\"sources\" />",
+            "Comparable pair: <Bars label=\"'This week'\" bars=\"thisWeek\" max=\"500\" /> beside <Bars label=\"'Last week'\" bars=\"lastWeek\" max=\"500\" />",
+            "Semantic colour: bars=[{ label: 'Failed', value: 12, color: 'danger' }]",
+            "Live: <Bars label=\"'Traffic'\" bars=\"() => sources()\" loading=\"isFetching\" />",
+            "Compact: <Bars label=\"'Traffic by source'\" bars=\"sources\" size=\"'sm'\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Three categories on a derived scale",
+            "pithy": "<Bars label=\"'Traffic by source'\" bars=\"sources\" />",
+            "assertions": [
+                "figure.ui-chart.ui-bars with data-status='ready'",
+                "one .ui-bars-label, .ui-bars-track and .ui-bars-value per row",
+                "the largest row's fill is 100% wide",
+                "no <svg> anywhere",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "shared-scale",
+            "title": "An explicit ceiling makes two charts comparable",
+            "pithy": "<Bars label=\"'Traffic by source'\" bars=\"sources\" max=\"100\" />",
+            "assertions": [
+                "a row worth 40 renders a fill of 40%, not 100%",
+                "the <tfoot> reads 'Scale maximum, 100'"
+            ]
+        },
+        {
+            "id": "over-ceiling",
+            "title": "A value past the ceiling",
+            "pithy": "<Bars label=\"'Budget use'\" bars=\"[{label:'Over',value:150}]\" max=\"100\" />",
+            "assertions": [
+                "the fill is clamped to 100%",
+                "the table and the row's own value label both still read 150"
+            ]
+        },
+        {
+            "id": "long-tail",
+            "title": "A category too small to see",
+            "pithy": "<Bars label=\"'Long tail'\" bars=\"[{label:'Bulk',value:100000},{label:'Speck',value:1}]\" />",
+            "assertions": [
+                "the tiny row is widened to the minimum visible width rather than vanishing",
+                "the table carries its exact value of 1"
+            ]
+        },
+        {
+            "id": "zero-scale",
+            "title": "Named categories that all hold zero",
+            "pithy": "<Bars label=\"'Traffic by source'\" bars=\"allZero\" />",
+            "assertions": [
+                "data-status='ready', NOT 'empty' — a bar row labels itself, so the chart still says something",
+                "every row is drawn at 0% and every row is still a <th> in the table",
+                "no NaN or Infinity anywhere in the markup"
+            ]
+        },
+        {
+            "id": "no-rows",
+            "title": "No rows at all",
+            "pithy": "<Bars label=\"'Traffic by source'\" bars=\"[]\" />",
+            "assertions": [
+                "data-status='empty'",
+                "graphic and table both hidden, role='status' region reads 'No data to display'"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading",
+            "pithy": "<Bars label=\"'Traffic by source'\" bars=\"sources\" loading=\"true\" />",
+            "assertions": [
+                "aria-busy='true' on .ui-chart-body, and absent from the root",
+                "graphic and table both hidden",
+                "role='status' region reads 'Loading chart…'"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background of its own — the rows sit on whatever surface hosts them. Each track uses --color-surface-variant so the unfilled remainder reads as a groove the bar runs in rather than as empty page.",
+        "depth": "Flat. No shadow on the track or the fill: a bar's only job is to encode a length, and a raised edge adds a pixel or two of apparent length that is not data.",
+        "borders": "None in normal rendering — the track's own fill is the boundary. In forced-colors the track gains a CanvasText border and both the fill and the track opt out of colour substitution, because the colour is the data.",
+        "interactivity": "None. There is no hover treatment and nothing is focusable: every row already states its category and its value permanently, so there is no detail left for an interaction to reveal — and anything it did reveal would be unreachable by keyboard and touch. Contrast this with StackedBar and Donut, where hover pairs a mark with its key because the mark alone cannot be named.",
+        "bestPractices": "Use it to compare categories, never to divide a whole — reach for StackedBar or Donut for that. Sort rows by value unless the order itself means something (a timeline, a fixed lifecycle): a bar chart in arbitrary order makes the reader do the ranking the chart exists to do. Pass `max` whenever two charts sit near each other, and whenever the scale should stay still as data changes — without it every chart re-scales on every poll and a growing value can look flat. Keep to a dozen or so rows; past that the chart becomes a list and a table serves better. Leave colour unset unless a row has a genuine semantic — identity encoding matters much less here than in a donut, because the names are already on screen. Always give a specific `label`: it is the caption a screen-reader user hears. Prefer an explicit `emptyMessage` that says what is missing ('No traffic recorded yet') over the generic default."
+    }
+}