@pithyjs/pidl-catalog 0.1.0-beta.1 → 0.1.0-beta.3

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

@@ -0,0 +1,343 @@
+{
+    "kind": "component",
+    "id": "ui.line",
+    "name": "Line",
+    "displayName": "Line Chart",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "data",
+    "bidi": true,
+    "description": "Up to six named series over one shared category axis, drawn as stroked lines with a marker on every reading. The chart for COMPARING trends: several quantities measured at the same points, on one domain, so their shapes can be read against each other. The plot is SVG because a polyline is a path; the axis labels beneath it are DOM, so a long category name can ellipsis, a numeric axis can use tabular figures, and the type rescales with the reader's own font setting. A colour key is on by default whenever there is more than one series, because a line is named by its colour and by nothing else on screen. The drawing, the axis and the key are all aria-hidden; a visually-hidden data table with one column per series carries every exact reading. Readings may be negative. A non-finite reading is a hole the line breaks across. Loading, empty and error states are first-class.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Accessible name",
+            "type": "string",
+            "required": true,
+            "placeholder": "Latency by region, p95",
+            "description": "Captions the visually-hidden data table screen readers read instead of the graphic. Required — it is the chart's accessible name."
+        },
+        {
+            "name": "series",
+            "label": "Series",
+            "type": "LineSeries[] | Signal<LineSeries[]>",
+            "required": true,
+            "reactive": true,
+            "placeholder": [
+                { "name": "eu-west", "values": [120, 118, 131, 126, 119] },
+                { "name": "us-east", "values": [96, 101, 99, 143, 104] }
+            ],
+            "description": "The lines, in draw order. One to six: past the sixth the categorical palette has no slot, and a seventh series is painted neutral AND dashed rather than being given the first series' colour. Every series is measured against ONE domain, which is what makes their shapes comparable.",
+            "itemSchema": {
+                "name": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Series name. Appears in the key and as a column header in the accessible table — required, because colour alone cannot name a line. An empty or whitespace-only name becomes 'Series N'."
+                },
+                "values": {
+                    "type": "number[]",
+                    "required": true,
+                    "description": "The readings, in axis order. Each must be a finite number; either sign is allowed. A non-finite entry is a hole the line breaks across, listed in the table as an em dash. A series with fewer readings than the axis has categories stops where its data does."
+                },
+                "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 line. Omit to take the categorical palette slot matching the series' index, which is the right default for identity encoding — the key a reader learned once stays true across renders and themes."
+                }
+            }
+        },
+        {
+            "name": "labels",
+            "label": "Category names",
+            "type": "string[] | Signal<string[]>",
+            "required": true,
+            "reactive": true,
+            "placeholder": ["Mon", "Tue", "Wed", "Thu", "Fri"],
+            "description": "Category names, in axis order — shared by every series. The labels define the axis. Past eight categories the axis shows every other label, always keeping the first and the last."
+        },
+        {
+            "name": "min",
+            "label": "Scale minimum",
+            "type": "number | Signal<number>",
+            "reactive": true,
+            "placeholder": 0,
+            "description": "The value drawn at the bottom of the plot. Defaults to zero, or to the lowest reading across every series when the data goes below it. May be negative. A bound that is not a finite number, or a min/max pair that does not increase, is DEV-warned and ignored."
+        },
+        {
+            "name": "max",
+            "label": "Scale maximum",
+            "type": "number | Signal<number>",
+            "reactive": true,
+            "placeholder": 200,
+            "description": "The value drawn at the top of the plot. Defaults to the highest reading across every series plus 12% headroom, so no peak's marker is clipped. A reading past this is drawn ON the top edge and DEV-warned; the table still reports its true value."
+        },
+        {
+            "name": "legend",
+            "label": "Colour key",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["end", "bottom", "none"],
+            "description": "Where the colour key sits. Defaults to 'end' when the first read of `series` holds more than one line and to 'none' when it holds exactly one — colour distinguishes nothing in a single-line chart, and the chart's own label names it. Pass this explicitly when the series count varies at runtime, because the default is decided once, at construction. 'none' is expressible and is never right for a multi-series chart."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Sets the type scale of the axis. It does NOT cap the chart's width, unlike the circular charts: a line chart's inline extent is its TIME AXIS. 'sm' and 'md' share --font-size-xs, which is the design system's smallest step and already the floor for a tabular axis; 'lg' steps up."
+        },
+        {
+            "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. The key keeps its box and loses its text, so the chart does not resize when data arrives."
+        },
+        {
+            "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 no series holds a single reading. NOT shown for all-zero series, which stay ready and draw flat lines along the floor."
+        },
+        {
+            "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": {
+        "line.stroke": "--color-categorical-1 … --color-categorical-6, or any semantic colour",
+        "line.stroke.fallback": "--color-text-muted (a series past the last palette slot, or an unrecognised token)",
+        "dot.fill": "the same token as its line",
+        "dot.separator": "--color-surface",
+        "dot.separator.width": "--border-width-thin",
+        "grid.stroke": "--color-border",
+        "axis.color": "--color-text-muted",
+        "axis.font": "--font-family-mono",
+        "axis.size": "--font-size-xs (--font-size-sm at lg)",
+        "axis.tracking": "typography $letter-spacings 'wide'",
+        "legend.swatch": "the same tokens as the lines",
+        "line.motion.duration": "--motion-duration-slow",
+        "line.motion.easing": "--motion-easing-emphasized",
+        "status.color": "--color-text-muted",
+        "status.error.color": "--color-danger",
+        "placeholder.background": "--color-surface-variant",
+        "placeholder.radius": "--radius-md"
+    },
+    "spacing": {
+        "internal": {
+            "plot-to-axis": {
+                "relationship": "lovers",
+                "token": "xs",
+                "note": "The axis is part of the drawing, not a caption of it."
+            },
+            "drawing-to-key": {
+                "relationship": "acquaintances",
+                "token": "lg",
+                "note": "Two different kinds of thing, read in turn. Inherited from the shared chart body."
+            },
+            "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",
+        "The PLOT is SVG and the AXIS LABELS are DOM, and the split follows the argument rather than the component. A polyline through N readings IS a path; axis labels are text, and SVG <text> has no ellipsis, no tabular figures, and no WCAG 1.4.4 text scaling",
+        "The axis row is a grid of 2(N-1) equal columns, with each inner label spanning two so its centre falls exactly on its point. N equal columns — one per label — is off by (i+0.5)/N against i/(N-1)",
+        "NOTHING outside an axis label may clip it: text-overflow paints its ellipsis at the label's own end edge, so an ancestor overflow: hidden removes the cue along with the characters",
+        "EVERY series is measured against ONE domain. A per-series scale would draw a series peaking at 10 and one peaking at 1000 as the same shape at the same height, which is the one thing a reader will assume it is not",
+        "Every reading gets a marker, unlike LineArea which marks only its terminus. With lines crossing, a marker is what says which line owns a reading AT the crossing, and it is the only thing separating a real observation from a point the eye invents along a straight segment",
+        "Every line is drawn UNDER every marker, so a marker is never buried by a later series' line",
+        "One to six series. Past the sixth the palette has no slot and the series is painted neutral AND dashed and flagged data-overflow — never given a slot already in use, which would be a wrong answer rendered as a key entry. Two overflow series remain ambiguous with each other, which is what the DEV warning says to fix: fold the tail into an explicit 'Other' series",
+        "The key is on by default for more than one series and off for exactly one. A line is identified by its colour and by nothing else on screen, so a multi-series chart without a key fails WCAG 1.4.1; a single-line chart's colour distinguishes nothing and the chart's label names it",
+        "The key's default is decided from the FIRST read of `series`, because a key is structure — the element exists or it does not — and it cannot be added and removed under the reader per signal write. Pass `legend` explicitly when the count varies",
+        "The graphic, the axis and the key are all 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 the type scale instead",
+        "A SINGLE reading is centred and carried by its marker, with no line. `i / (n - 1)` is 0/0 for one observation",
+        "A non-finite reading BREAKS its line rather than being bridged, and gets no marker at all — a marker parked at the origin would read as a reading of zero",
+        "A reading outside an explicit min/max is drawn at the edge of the plot and DEV-warned; the accessible table reports the true value",
+        "An inverted or collapsed domain (min >= max) is DEV-warned and the derived one is used, rather than drawing the chart upside down",
+        "Series whose readings are ALL zero stay `ready` and draw flat lines along the floor. The axis and the key still name everything, so going empty would hide a chart a sighted reader can see. Only 'no reading anywhere' is empty",
+        "The <tfoot> states each series' PLOTTED RANGE, never a total: adding Monday's latency to Tuesday's produces a number that is not a quantity of anything. The key shows the same string, from the same computation, so the two cannot disagree",
+        "The key is painted from the SAME colour resolution as the lines, never a second call — a key painted twice is a key that can disagree with the drawing, quietly",
+        "The <thead> is rebuilt only when the series NAMES change. A head row swapped on every signal write moves a screen reader's cursor out of the table it is reading",
+        "The drawing and the data table are hidden together in every non-ready state so the two cannot disagree about whether there is data",
+        "Each line's shape transition is inside a motion-safe block"
+    ],
+    "a11y": [
+        "The SVG carries aria-hidden='true' — it is a picture of the table beside it",
+        "The axis row and the key are aria-hidden too: both restate what the table's headers already carry, and exposing them would read the dataset twice in a flatter form",
+        "A <table class='u-sr-only'> carries one column per series and every exact reading, captioned with the required `label` prop",
+        "Table headers are scoped: <th scope='col'> in the head, <th scope='row'> per row. A reader moves down a column to follow one series and across a row to compare them at one point — the two readings a sighted reader takes off the drawing",
+        "A missing reading appears as an em dash, never as the zero the geometry substitutes to keep its arithmetic finite",
+        "A reading clamped to the edge of an explicit domain appears at its true value — the table is the reading of record wherever the drawing is an approximation",
+        "The <tfoot> states each series' plotted range, which stays true under an explicit min/max",
+        "Colour is never the sole encoding: the key is on by default for every multi-series chart, and the table names every series in its column headers",
+        "A series past the last palette slot is dashed as well as neutral, so two off-palette lines are still visibly off-palette where two neutral strokes alone would be indistinguishable",
+        "Axis text rescales with the reader's font-size setting rather than with the drawing, which SVG text cannot do (WCAG 1.4.4)",
+        "Status messages live in a role='status' region present from first render",
+        "aria-busy='true' while loading goes on the drawing's wrapper (.ui-chart-body), NEVER on the root. A live region inside an aria-busy subtree has its changes deferred until busy clears, which is the same call that blanks the region",
+        "In forced-colors the lines and markers keep their colours — the colour IS the data, and flattening six slots to one system colour would delete the key rather than raise contrast. The marker's separator becomes Canvas and the overflow dash opts out of substitution",
+        "Each line's shape transition is inside a prefers-reduced-motion: no-preference block"
+    ],
+    "ai": {
+        "synonyms": [
+            "line chart",
+            "line graph",
+            "multi-series line",
+            "trend comparison",
+            "time series comparison",
+            "metrics over time",
+            "series comparison",
+            "multi-line chart"
+        ],
+        "avoid": [
+            "Passing a CSS colour — the color field takes a design-token name",
+            "More than six series: the palette has six slots, and the seventh is drawn neutral and dashed with a DEV warning. Fold the tail into an explicit 'Other' series instead",
+            "Using it for ONE series with a fill — that is LineArea",
+            "Using it for unordered categories — a line implies a sequence. Use Bars",
+            "Using it for parts of one whole — that is StackedBar or Donut",
+            "legend='none' on a multi-series chart: the lines then have no name anywhere a sighted reader can see",
+            "Series measured in different units on one chart — they share a domain, so 'requests' and 'error rate' on one plot compare two things that cannot be compared",
+            "Omitting min/max when the scale should stay still as data changes: without them the domain follows the data and a growing value can look flat",
+            "Relying on the graphic alone for accessibility — the table is the accessible representation and `label` captions it"
+        ],
+        "patterns": [
+            "Basic: <Line label=\"'Latency by region'\" series=\"regions\" labels=\"days\" />",
+            "Key under the plot: <Line label=\"'Latency'\" series=\"regions\" labels=\"days\" legend=\"'bottom'\" />",
+            "Stable scale: <Line label=\"'Latency'\" series=\"regions\" labels=\"days\" min=\"0\" max=\"200\" />",
+            "Semantic colours: series=[{name:'Failed',values:[…],color:'danger'},{name:'Passed',values:[…],color:'success'}]",
+            "Live: <Line label=\"'Latency'\" series=\"() => regions()\" labels=\"days\" loading=\"isFetching\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Two regions over one week",
+            "pithy": "<Line label=\"'Latency by region'\" series=\"regions\" labels=\"days\" />",
+            "assertions": [
+                "figure.ui-chart.ui-line with data-status='ready' and data-legend='end'",
+                "one .ui-line-path per series, one .ui-line-dot per reading",
+                "every line is drawn before every marker",
+                "the key's swatches match the paths' data-color exactly",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "single-series",
+            "title": "One line needs no key",
+            "pithy": "<Line label=\"'Latency'\" series=\"[{name:'eu-west',values:[…]}]\" labels=\"days\" />",
+            "assertions": [
+                "no data-legend attribute and no .ui-chart-legend element",
+                "the chart's own label names the line"
+            ]
+        },
+        {
+            "id": "shared-domain",
+            "title": "One domain, so the shapes compare",
+            "pithy": "<Line label=\"'Two scales'\" series=\"[{name:'small',values:[0,10]},{name:'large',values:[0,100]}]\" labels=\"['a','b']\" />",
+            "assertions": [
+                "the small series' peak rises a tenth as far as the large one's",
+                "both are measured against one derived ceiling"
+            ]
+        },
+        {
+            "id": "palette-overflow",
+            "title": "A seventh series",
+            "pithy": "<Line label=\"'Seven'\" series=\"sevenSeries\" labels=\"days\" />",
+            "assertions": [
+                "the seventh path carries no data-color and data-overflow='true'",
+                "it is drawn neutral and dashed, never in categorical-1",
+                "one DEV warning says the palette has no slot for it"
+            ]
+        },
+        {
+            "id": "hole",
+            "title": "A probe that missed a day",
+            "pithy": "<Line label=\"'Latency'\" series=\"[{name:'eu-west',values:[1,2,NaN,3,4]}]\" labels=\"days\" />",
+            "assertions": [
+                "the line's `d` carries TWO subpaths",
+                "the third marker has no cx and no r at all",
+                "the table's third row reads an em dash"
+            ]
+        },
+        {
+            "id": "empty",
+            "title": "No readings at all",
+            "pithy": "<Line label=\"'Latency'\" series=\"[]\" labels=\"[]\" />",
+            "assertions": [
+                "data-status='empty'",
+                "graphic and table both hidden, role='status' region reads 'No data to display'"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading",
+            "pithy": "<Line label=\"'Latency'\" series=\"regions\" labels=\"days\" loading=\"true\" />",
+            "assertions": [
+                "aria-busy='true' on .ui-chart-body, and absent from the root",
+                "graphic and table both hidden",
+                "the key keeps its box and loses its text, so the chart does not resize on resolve"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background of its own. Three grid rules in --color-border give the eye a height reference across a shallower plot than the area chart's — fewer rules, because several lines crossing already give the plot plenty to carry. Each line takes a categorical slot in index order, so a key a reader learned once stays true across renders and themes.",
+        "depth": "Flat. No shadow under a line and no glow on a marker: both add apparent weight that is not data, and with several lines they make the topmost look more important than the rest. The only layering is order — grid, then every line, then every marker.",
+        "borders": "None around the figure. Each marker carries a hairline of --color-surface so it stays separate from any line crossing behind it; in forced-colors that becomes Canvas. A series past the last palette slot gets a dash rather than a border, because a dash survives colour substitution and is the only thing left distinguishing it.",
+        "interactivity": "None. Nothing is focusable and there is no hover treatment: the key names every series, the axis names every point, and the table carries every value. A tooltip would put readings somewhere keyboard and touch users cannot reach, and a chart that needs one is a chart being asked to be a table.",
+        "bestPractices": "Use it to COMPARE trends measured in the same unit at the same points. One trend is LineArea; unordered categories are Bars; parts of a whole are StackedBar or Donut. Two to four series is the readable range — six is the hard limit and already crowded, and past that the reader is tracing lines rather than reading a chart. Sort the key's order to match the lines' order at the right-hand edge where you can: a reader looks up the last reading first. Pass min and max whenever the scale should stay still as data changes; start min at zero unless the data goes below it, since a scale starting at the smallest reading exaggerates every wobble. Give the chart room — it is width-agnostic on purpose, and a compressed time axis makes crossings unreadable. Reach for the semantic palette only when a series genuinely means pass or fail; for arbitrary series the categorical slots are the right default. Always give a specific label."
+    }
+}