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

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

@@ -0,0 +1,328 @@
+{
+    "kind": "component",
+    "id": "ui.line-area",
+    "name": "LineArea",
+    "displayName": "Area Chart",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "data",
+    "bidi": true,
+    "description": "One series over an ordered category axis, drawn as a line with the area beneath it filled. The chart for a single trend — how one quantity moved across a sequence a reader already understands as ordered: weeks, releases, cohorts. 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. The drawing and the axis are both aria-hidden; a visually-hidden data table carries every exact reading and is the chart's accessible representation. Readings may be negative. A non-finite reading is a hole the line breaks across rather than drawing through. Loading, empty (no reading anywhere — an all-zero series stays ready, because a flat line is a real answer) and error states are first-class.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Accessible name",
+            "type": "string",
+            "required": true,
+            "placeholder": "Sessions per week",
+            "description": "Captions the visually-hidden data table screen readers read instead of the graphic. Required — it is the chart's accessible name."
+        },
+        {
+            "name": "values",
+            "label": "Readings",
+            "type": "number[] | Signal<number[]>",
+            "required": true,
+            "reactive": true,
+            "placeholder": [120, 138, 131, 164, 152, 187],
+            "description": "The readings, in axis order. Each must be a finite number; either sign is allowed, unlike the bar and donut charts. A non-finite entry is treated as a HOLE — the line breaks across it rather than drawing a straight run through data nobody measured — is DEV-warned, and is listed in the accessible table as an em dash."
+        },
+        {
+            "name": "labels",
+            "label": "Category names",
+            "type": "string[] | Signal<string[]>",
+            "required": true,
+            "reactive": true,
+            "placeholder": ["W1", "W2", "W3", "W4", "W5", "W6"],
+            "description": "Category names, in axis order — one per reading. The labels define the axis: more labels than readings means the trailing points have not reported yet and are drawn as holes; more readings than labels means the extra points take a positional stand-in name. Past eight categories the axis shows every other label, always keeping the first and the last."
+        },
+        {
+            "name": "color",
+            "label": "Series colour",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger",
+                "categorical-1",
+                "categorical-2",
+                "categorical-3",
+                "categorical-4",
+                "categorical-5",
+                "categorical-6"
+            ],
+            "default": "categorical-1",
+            "description": "Design-token name for the line, its fill and its marker. A trend is a quantity, not a verdict, so the default is a categorical slot rather than a semantic colour — reach for 'danger' or 'success' only when the series genuinely means one."
+        },
+        {
+            "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 when the data goes below it. May be negative. Pass one to hold the scale still as data changes, or to make two charts comparable. 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 plus 8% headroom, which keeps the peak's marker inside the plot instead of clipping it in half. A reading past this is drawn ON the top edge and DEV-warned; the accessible table still reports its true value."
+        },
+        {
+            "name": "caption",
+            "label": "Caption",
+            "type": "string | Signal<string>",
+            "reactive": true,
+            "placeholder": "sessions",
+            "description": "Small caption under the plot naming what is counted — 'sessions', 'p95 ms'. Dropped below 8rem of chart width, where words stop fitting; the data table names the unit for a screen reader either way. Unlike the circular charts, size='sm' does NOT make this inert, because this chart clears the per-size width cap."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Sets the type scale of the axis and the caption. It does NOT cap the chart's width, unlike the circular charts: a line chart's inline extent is its TIME AXIS, and capping it at md's 12rem would put twelve weekly readings 16px apart. '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."
+        },
+        {
+            "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 is no reading anywhere. NOT shown for an all-zero series, which stays ready and draws a flat line 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 (only when an explicit colour is not a recognised token)",
+        "area.fill": "the same token as the line, at 13% opacity",
+        "dot.fill": "the same token as the 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'",
+        "caption.color": "--color-text-muted",
+        "caption.size": "--font-size-xs (--font-size-sm at lg)",
+        "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. Any more air reads as a second element below the chart."
+            },
+            "axis-to-caption": {
+                "relationship": "close_friends",
+                "token": "sm",
+                "note": "One reads as a caption of the other, with the axis row already between them."
+            },
+            "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 go through the kit's own formatter, which the data table uses too",
+        "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, so the plot cannot be DOM. Axis labels can be, and must be: SVG <text> has no text-overflow: ellipsis, no font-variant-numeric: tabular-nums, and scales with the viewBox transform rather than with the reader's font setting (WCAG 1.4.4)",
+        "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 wrong by (i+0.5)/N against i/(N-1), which for five points is 27 of 540 user units and reads as belonging to the next category",
+        "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 would remove the cue along with the characters and leave a silently wrong category name",
+        "The final axis label flips its box direction rather than its text alignment. Under text-align: end an over-long label overflows the START edge, where no ellipsis is ever painted — the truncation then happens in silence",
+        "The graphic and the axis are both 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 line chart's width is its time axis, and capping it compresses the axis rather than shrinking the chart",
+        "A SINGLE reading is centred and carried by its marker, with no line and no area. `i / (n - 1)` is 0/0 for one observation, which is a metric's first day rather than a pathological input; a line through one point is not a line",
+        "A non-finite reading BREAKS the line rather than being bridged. Drawing a straight run through missing data reads as a measurement that was taken",
+        "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. The clamp is a drawing decision and may not reach the data",
+        "An inverted or collapsed domain (min >= max) is not a domain — it is DEV-warned and the derived one is used, rather than drawing the chart upside down or dividing by nothing",
+        "A series whose readings are ALL zero stays `ready` and draws a flat line along the floor. The axis still names every point and the table still carries every reading, so going empty would hide a chart a sighted reader can see. Only 'no reading anywhere' is empty. <Donut> and <StackedBar> go empty on the same input, and should: their parts of a zero whole have nothing to draw and no label anywhere but the key",
+        "The <tfoot> states the PLOTTED RANGE, never a total. Adding Monday's queue depth to Tuesday's produces a number that is not a quantity of anything. It also deliberately does not state the drawing's domain, unlike <Bars>: a bar's LENGTH is its reading so its ceiling is a missing denominator, where a line chart's readings are all in the table already and the domain is a property of the aria-hidden picture",
+        "The drawing and the data table are hidden together in every non-ready state so the two cannot disagree about whether there is data",
+        "The 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 carries aria-hidden='true' too: every name on it is already a <th scope='row'> in the table, and exposing both reads the category list twice without the readings attached",
+        "A <table class='u-sr-only'> carries 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 missing reading appears in the table 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 in the table at its true value — the table is the reading of record wherever the drawing is an approximation",
+        "The <tfoot> states the plotted range, which stays true under an explicit min/max and when the data is empty",
+        "Axis text rescales with the reader's font-size setting rather than with the drawing, which SVG text cannot do (WCAG 1.4.4)",
+        "Colour is not the sole encoding: there is one series, and the chart's own label names it",
+        "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",
+        "In forced-colors the 13%-opacity area fill is dropped rather than left as a band of noise; the stroke keeps its colour, because in a chart the colour IS the data",
+        "The caption is aria-hidden — the table's own <caption> already carries the chart's name",
+        "The line's shape transition is inside a prefers-reduced-motion: no-preference block"
+    ],
+    "ai": {
+        "synonyms": [
+            "area chart",
+            "filled line chart",
+            "trend chart",
+            "sparkline",
+            "time series",
+            "trend over time",
+            "growth chart",
+            "usage over time",
+            "single-series line"
+        ],
+        "avoid": [
+            "Passing a CSS colour — the color prop takes a design-token name",
+            "Using it for several series — a second wash reads as a third colour that means nothing. Use Line, which takes up to six",
+            "Using it for unordered categories — a line implies a sequence, and 'Search, Direct, Referral' is not one. Use Bars",
+            "Using it for parts of one whole — that is StackedBar or Donut",
+            "Omitting min/max when two charts are meant to be compared, or when the scale should stay still as data changes: without them the domain follows the data and a growing value can look flat",
+            "Passing labels and values of different lengths without meaning to — the shorter one decides where the readings stop and the longer one decides the axis",
+            "Wrapping it in a narrow fixed column: the chart fills its column, and a compressed time axis is unreadable",
+            "Relying on the graphic alone for accessibility — the table is the accessible representation and `label` captions it"
+        ],
+        "patterns": [
+            "Basic: <LineArea label=\"'Sessions per week'\" values=\"weekly\" labels=\"weeks\" />",
+            "Stable scale: <LineArea label=\"'Sessions'\" values=\"weekly\" labels=\"weeks\" min=\"0\" max=\"500\" />",
+            "Named unit: <LineArea label=\"'Sessions per week'\" values=\"weekly\" labels=\"weeks\" caption=\"'sessions'\" />",
+            "Live: <LineArea label=\"'Sessions'\" values=\"() => weekly()\" labels=\"weeks\" loading=\"isFetching\" />",
+            "Signed: values=[-4, 2, -1, 6] draws below the axis, which Bars and Donut cannot"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Six weekly readings on a derived scale",
+            "pithy": "<LineArea label=\"'Sessions per week'\" values=\"weekly\" labels=\"weeks\" />",
+            "assertions": [
+                "figure.ui-chart.ui-line-area with data-status='ready'",
+                "one .ui-line-area-line, one .ui-line-area-fill closed with Z, and exactly one .ui-line-area-dot",
+                "the marker sits on the LAST reading",
+                "six .ui-chart-axis-label elements, none of them SVG text",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "single-reading",
+            "title": "A metric's first day",
+            "pithy": "<LineArea label=\"'Sessions per week'\" values=\"[42]\" labels=\"['W1']\" />",
+            "assertions": [
+                "the marker is centred and no path is emitted at all",
+                "no NaN anywhere in the markup — `i / (n - 1)` is 0/0 for one point",
+                "data-status='ready'"
+            ]
+        },
+        {
+            "id": "hole",
+            "title": "A week with no reading",
+            "pithy": "<LineArea label=\"'Sessions'\" values=\"[1,2,NaN,3,4]\" labels=\"weeks\" />",
+            "assertions": [
+                "the line's `d` carries TWO subpaths — it breaks rather than bridging",
+                "the table's third row reads an em dash, not 0",
+                "a single DEV warning names the index"
+            ]
+        },
+        {
+            "id": "clamped",
+            "title": "A spike past an explicit ceiling",
+            "pithy": "<LineArea label=\"'Sessions'\" values=\"[150]\" labels=\"['W1']\" min=\"0\" max=\"100\" />",
+            "assertions": [
+                "the marker is drawn at y=0, the top of the plot",
+                "the table still reads 150",
+                "a DEV warning says the reading is outside min/max"
+            ]
+        },
+        {
+            "id": "all-zero",
+            "title": "A week when nothing happened",
+            "pithy": "<LineArea label=\"'Sessions'\" values=\"[0,0,0]\" labels=\"weeks\" />",
+            "assertions": [
+                "data-status='ready', NOT 'empty' — a flat line is a real answer",
+                "every y coordinate sits on the plot floor",
+                "no NaN or Infinity anywhere in the markup"
+            ]
+        },
+        {
+            "id": "empty",
+            "title": "No readings at all",
+            "pithy": "<LineArea label=\"'Sessions'\" values=\"[]\" labels=\"[]\" />",
+            "assertions": [
+                "data-status='empty'",
+                "graphic and table both hidden, role='status' region reads 'No data to display'"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading",
+            "pithy": "<LineArea label=\"'Sessions'\" values=\"weekly\" labels=\"weeks\" 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 plot sits on whatever surface hosts it. Four grid rules in --color-border give the eye a height reference without competing with the line; the fill is the series' own colour at 13%, which reads as belonging to the stroke above it rather than as a second colour, and works with every palette slot in both themes where a fixed tint would not.",
+        "depth": "Flat. No shadow under the line and no gradient in the fill: both add apparent height that is not data, and a gradient in particular makes the same value look different at different points along the axis. The only layering is order — grid, then fill, then stroke, then the terminal marker.",
+        "borders": "None around the figure. The marker carries a hairline of --color-surface so it reads as a terminus of the line rather than as a blob sitting on it; in forced-colors that becomes Canvas, and the fill is dropped entirely because at 13% it is invisible there anyway.",
+        "interactivity": "None. Nothing is focusable and there is no hover treatment: the axis names every point, the table carries every value, and a tooltip would put readings somewhere keyboard and touch users cannot reach. If a reader needs per-point numbers on screen, the chart is being asked to be a table.",
+        "bestPractices": "Use it for ONE trend over an ordered sequence — weeks, releases, cohorts. For several trends use Line; for unordered categories use Bars; for parts of a whole use StackedBar or Donut. Keep to about a dozen points: past eight the axis starts showing every other label, and past twenty the line is texture rather than a trend. Pass min and max whenever the scale should stay still as data changes, and whenever two charts sit near each other — without them each chart re-scales on every poll and a growing value can look flat. Start min at zero unless the data goes below it: a scale that starts at the smallest reading exaggerates every wobble. Give the chart room; it is width-agnostic on purpose, and a compressed time axis is the one way to make a correct trend unreadable. Always give a specific label, and prefer an emptyMessage that says what is missing ('No sessions recorded yet') over the generic default."
+    }
+}