@slotted/angular 0.0.0-stage → 0.1.0-beta.0

package/docs/stat-card.json

@@ -0,0 +1,529 @@
+{
+  "family": "stat-card",
+  "ui": "stat-card",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Key figure with label, change and trend."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "fill": [
+      "outline",
+      "elevated",
+      "subtle",
+      "plain"
+    ],
+    "layout": [
+      "inline",
+      "stacked"
+    ],
+    "status": [
+      "ready",
+      "empty",
+      "error"
+    ],
+    "goodWhen": [
+      "up",
+      "down",
+      "none"
+    ],
+    "tone": [
+      "neutral",
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "trend": [
+      "up",
+      "down",
+      "flat"
+    ]
+  },
+  "members": {
+    "stat-card": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "fill": "outline",
+        "layout": "inline",
+        "status": "ready",
+        "goodWhen": "up",
+        "loading": false
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "status",
+        "loading",
+        "content"
+      ],
+      "states": [
+        "default",
+        "loading"
+      ],
+      "parts": [
+        "root",
+        "body",
+        "header",
+        "label",
+        "status",
+        "action",
+        "figure",
+        "value",
+        "unit",
+        "delta",
+        "indicator",
+        "comparison",
+        "period",
+        "trend",
+        "message"
+      ]
+    }
+  },
+  "docs": {
+    "stat-card": {
+      "imports": {
+        "source": "import {\n  SlStatCard,\n  SlStatCardHeader,\n  SlStatCardLabel,\n  SlStatCardStatus,\n  SlStatCardAction,\n  SlStatCardFigure,\n  SlStatCardValue,\n  SlStatCardUnit,\n  SlStatCardDelta,\n  SlStatCardComparison,\n  SlStatCardPeriod,\n  SlStatCardTrend,\n  SlStatCardMessage,\n  provideStatCardDefaults,\n} from '@slotted/angular/stat-card';",
+        "selector": "[slStatCard] · [slStatCardLabel] · [slStatCardValue] · [slStatCardDelta] · [slStatCardTrend] · …",
+        "exportAs": "slStatCard · slStatCardValue · slStatCardDelta · slStatCardTrend · …"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div",
+          "required": true,
+          "purpose": "The frame and the query container: role=\"group\" named by the label, carrying size, fill, layout, status, goodWhen, the derived tone and the loading state. Floored at ten rem; under that it overflows its column rather than shrinking."
+        },
+        {
+          "part": "body",
+          "element": "div",
+          "required": true,
+          "purpose": "The grid, rendered by slStatCard one element inside the host: header on top, figure and trend on the row that grows, message at the bottom."
+        },
+        {
+          "part": "header",
+          "element": "div",
+          "required": false,
+          "purpose": "The name, a status beside it and an action at the end, wrapping on the baseline."
+        },
+        {
+          "part": "label",
+          "element": "span",
+          "required": false,
+          "purpose": "The name of the metric, in the muted step. Carries the id the root is named by."
+        },
+        {
+          "part": "status",
+          "element": "span",
+          "required": false,
+          "purpose": "A slot beside the name for a badge or a status indicator."
+        },
+        {
+          "part": "action",
+          "element": "span",
+          "required": false,
+          "purpose": "The end of the header, for your own link or button. Stays on the first line when the name wraps, set on the name’s own size and line so the header keeps its height whichever face has loaded."
+        },
+        {
+          "part": "figure",
+          "element": "div",
+          "required": false,
+          "purpose": "The value line and the comparison under it. The value and the delta share a baseline; a delta with no room drops under the value."
+        },
+        {
+          "part": "value",
+          "element": "span",
+          "required": false,
+          "purpose": "The number, in the size step’s type, proportional figures, never truncated. A dash while empty or failed; a placeholder while loading."
+        },
+        {
+          "part": "unit",
+          "element": "span",
+          "required": false,
+          "purpose": "The unit, a step down, wherever you put it inside the value: $ before, % after. The value spaces it from the figure by its own gap on either side."
+        },
+        {
+          "part": "delta",
+          "element": "span",
+          "required": false,
+          "purpose": "The change: the indicator, the direction a screen reader hears, and the signed number, in the tone derived from goodWhen. Carries data-trend and data-tone."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The mark beside the delta: trending-up, turned over for a fall, minus for no change. Painted from the delta’s ink and kept under forced colours."
+        },
+        {
+          "part": "comparison",
+          "element": "p",
+          "required": false,
+          "purpose": "The prose under the figure: what the value was. Hidden while there is no value."
+        },
+        {
+          "part": "period",
+          "element": "span",
+          "required": false,
+          "purpose": "The period the comparison names, inside the comparison."
+        },
+        {
+          "part": "trend",
+          "element": "div",
+          "required": false,
+          "purpose": "Where a sparkline goes: beside the figure, or under it when stacked or under 220 pixels. Hands the sparkline the card’s tone and ground; a block placeholder while loading; hidden under forty pixels."
+        },
+        {
+          "part": "message",
+          "element": "p",
+          "required": false,
+          "purpose": "What is said in place of a missing or failed value. Hidden otherwise; in the danger tone on error."
+        }
+      ],
+      "api": [
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "slStatCard",
+          "description": "The figure’s type and the card’s inset"
+        },
+        {
+          "name": "fill",
+          "type": "'outline' | 'elevated' | 'subtle' | 'plain'",
+          "defaultValue": "outline",
+          "appliesTo": "slStatCard",
+          "description": "The frame: a hairline, a shadow, a sunken fill, or none at all"
+        },
+        {
+          "name": "layout",
+          "type": "'inline' | 'stacked'",
+          "defaultValue": "inline",
+          "appliesTo": "slStatCard",
+          "description": "The trend beside the figure, or on its own row under it"
+        },
+        {
+          "name": "status",
+          "type": "'ready' | 'empty' | 'error'",
+          "defaultValue": "ready",
+          "appliesTo": "slStatCard",
+          "description": "Whether there is a value to show, and if not, why. The layout is kept either way"
+        },
+        {
+          "name": "loading",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slStatCard",
+          "description": "The value is on its way: every part stands in with a placeholder and the root is aria-busy"
+        },
+        {
+          "name": "goodWhen",
+          "type": "'up' | 'down' | 'none'",
+          "defaultValue": "up",
+          "appliesTo": "slStatCard, slStatCardDelta",
+          "description": "Which way is good for this metric. The tone of a change is derived from it, never from the sign"
+        },
+        {
+          "name": "delta",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard",
+          "description": "The change, as the first delta reads it: a fraction for a percentage. Stated on the root so the card knows its tone before its delta renders"
+        },
+        {
+          "name": "tone",
+          "type": "'neutral' | 'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard, slStatCardDelta",
+          "description": "An explicit tone, which wins over the derived one. On the root it is what the trend hands its sparkline"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard",
+          "description": "BCP 47, for every number the card formats; the language in force when absent"
+        },
+        {
+          "name": "formatOptions",
+          "type": "Intl.NumberFormatOptions",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard, slStatCardValue, slStatCardDelta",
+          "description": "How a number is written. On the root, the default for the value and the delta"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<StatCardMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard",
+          "description": "Words laid over the language in force, key by key: up, down and flat, heard before the delta; empty, shown in place of a missing value"
+        },
+        {
+          "name": "value",
+          "type": "number | string",
+          "defaultValue": "—",
+          "appliesTo": "slStatCardValue, slStatCardDelta",
+          "description": "A number the card formats, or text as written. On a delta, unset means the root’s delta"
+        },
+        {
+          "name": "format",
+          "type": "'percent' | 'decimal'",
+          "defaultValue": "percent",
+          "appliesTo": "slStatCardDelta",
+          "description": "percent reads the value as a fraction; decimal reads it as it is. The sign is shown except on nought"
+        }
+      ],
+      "composition": [
+        {
+          "name": "projected content",
+          "type": "ng-content",
+          "defaultValue": "—",
+          "appliesTo": "slStatCardValue, slStatCardDelta",
+          "description": "Your own rendering after the formatted number: a unit, or the whole text when value is unset"
+        },
+        {
+          "name": "[slStatCard…]",
+          "type": "attribute selectors",
+          "defaultValue": "—",
+          "appliesTo": "your elements",
+          "description": "Every part is a directive on the element you wrote: a heading for the label, an anchor for the action, a p for the comparison"
+        },
+        {
+          "name": "exportAs",
+          "type": "template reference",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard, slStatCardValue, slStatCardDelta, slStatCardTrend, …",
+          "description": "Reaches the instance: the derived tone, the trend, the formatted text"
+        },
+        {
+          "name": "slStatCardTrend",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "slStatCard",
+          "description": "Takes an slSparkline and hands it the card’s tone through --slotted-sparkline-color and its ground for the marker’s ring; a tone or series on the sparkline still wins"
+        },
+        {
+          "name": "aria-label, aria-labelledby, id",
+          "type": "attributes",
+          "defaultValue": "—",
+          "appliesTo": "your elements",
+          "description": "A name or an id you wrote on the host or on the label wins over the generated one"
+        },
+        {
+          "name": "trendOf, toneOf",
+          "type": "function",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "The two derivations, exported for a delta you format yourself"
+        },
+        {
+          "name": "provideStatCardDefaults",
+          "type": "StatCardDefaults",
+          "defaultValue": "—",
+          "appliesTo": "Application",
+          "description": "Sets goodWhen, size, fill, layout and formatOptions once, in a route or the application config; an input still wins"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The root is a group named by its label through aria-labelledby, so a reader who lands on the action inside it hears which metric it belongs to. There is no APG pattern for a statistic; a group with a name is what the platform offers a labelled region that is not a landmark.",
+        "The delta reads its direction before its number — “up +12.4%” — from a visually hidden word, because a sign is a glyph some readers skip and “12.4%” alone does not say which way. The indicator is aria-hidden; it repeats what the word says.",
+        "The tone is never the only channel: the indicator turns, the word is read, the sign is written. A rise that is bad and a rise that is good differ in colour and in nothing a reader without colour loses.",
+        "While loading the root carries aria-busy=\"true\" and every placeholder is a skeleton, hidden and inert. One announcement for a whole dashboard is an slSkeletonRegion around it, which is the platform’s own answer rather than one per card.",
+        "A missing or failed value is a dash and a message, in the DOM and in the tree; a card never announces a stale number as current.",
+        "The value is never truncated. A number wider than the trend’s room takes the room; a number wider than the card breaks; nothing is clipped or hidden behind an ellipsis."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-subtle",
+    "--slotted-border-width-thin",
+    "--slotted-control-icon-size-md",
+    "--slotted-control-icon-size-sm",
+    "--slotted-font-family-sans",
+    "--slotted-font-size-2xl",
+    "--slotted-font-size-3xl",
+    "--slotted-font-size-4xl",
+    "--slotted-font-size-md",
+    "--slotted-font-size-sm",
+    "--slotted-font-size-xl",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-semibold",
+    "--slotted-line-height-2xl",
+    "--slotted-line-height-3xl",
+    "--slotted-line-height-4xl",
+    "--slotted-line-height-md",
+    "--slotted-line-height-sm",
+    "--slotted-line-height-xl",
+    "--slotted-line-height-xs",
+    "--slotted-radius-lg",
+    "--slotted-radius-none",
+    "--slotted-shadow-md",
+    "--slotted-space-1",
+    "--slotted-space-11",
+    "--slotted-space-12",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-5",
+    "--slotted-space-6",
+    "--slotted-space-7",
+    "--slotted-space-8",
+    "--slotted-space-9",
+    "--slotted-sparkline-block-size",
+    "--slotted-sparkline-block-size-lg",
+    "--slotted-sparkline-block-size-sm",
+    "--slotted-stat-card-background",
+    "--slotted-stat-card-background-subtle",
+    "--slotted-stat-card-border-color",
+    "--slotted-stat-card-border-width",
+    "--slotted-stat-card-color",
+    "--slotted-stat-card-color-muted",
+    "--slotted-stat-card-delta-font-size",
+    "--slotted-stat-card-delta-font-size-lg",
+    "--slotted-stat-card-delta-font-size-sm",
+    "--slotted-stat-card-indicator-size",
+    "--slotted-stat-card-indicator-size-lg",
+    "--slotted-stat-card-label-font-size",
+    "--slotted-stat-card-label-font-size-lg",
+    "--slotted-stat-card-label-font-size-sm",
+    "--slotted-stat-card-label-line-height",
+    "--slotted-stat-card-label-line-height-lg",
+    "--slotted-stat-card-label-line-height-sm",
+    "--slotted-stat-card-min-inline-size",
+    "--slotted-stat-card-padding-block",
+    "--slotted-stat-card-padding-block-lg",
+    "--slotted-stat-card-padding-block-sm",
+    "--slotted-stat-card-padding-inline",
+    "--slotted-stat-card-padding-inline-lg",
+    "--slotted-stat-card-padding-inline-sm",
+    "--slotted-stat-card-prose-font-size",
+    "--slotted-stat-card-prose-font-size-lg",
+    "--slotted-stat-card-prose-line-height",
+    "--slotted-stat-card-prose-line-height-lg",
+    "--slotted-stat-card-radius",
+    "--slotted-stat-card-region-gap",
+    "--slotted-stat-card-region-gap-lg",
+    "--slotted-stat-card-region-gap-sm",
+    "--slotted-stat-card-shadow",
+    "--slotted-stat-card-shadow-elevated",
+    "--slotted-stat-card-trend-gap",
+    "--slotted-stat-card-trend-gap-lg",
+    "--slotted-stat-card-trend-gap-sm",
+    "--slotted-stat-card-trend-inline-size",
+    "--slotted-stat-card-trend-inline-size-lg",
+    "--slotted-stat-card-trend-inline-size-sm",
+    "--slotted-stat-card-value-font-size",
+    "--slotted-stat-card-value-font-size-lg",
+    "--slotted-stat-card-value-font-size-sm",
+    "--slotted-stat-card-value-line-height",
+    "--slotted-stat-card-value-line-height-lg",
+    "--slotted-stat-card-value-line-height-sm",
+    "--slotted-surface-raised",
+    "--slotted-surface-sunken",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-text",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-text",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One card, driven by the controls: move delta across nought and switch goodWhen to watch the tone follow the meaning; switch status and loading to see the layout hold.",
+      "language": "html",
+      "source": "<div slStatCard [delta]=\"0.124\" goodWhen=\"up\">\n  <div slStatCardHeader><span slStatCardLabel>Open orders</span></div>\n  <div slStatCardFigure>\n    <span slStatCardValue [value]=\"1510\"></span>\n    <span slStatCardDelta></span>\n    <p slStatCardComparison>from 1,343 <span slStatCardPeriod>last week</span></p>\n  </div>\n  <div slStatCardTrend><span slSparkline [data]=\"orders\" label=\"Open orders\" area></span></div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "anatomy",
+      "title": "Every part in its place",
+      "note": "A label with a live badge and a details link, a value with its unit, a delta, the comparison and its period, and a sparkline in the trend region: the whole family on one card, with the message part waiting for a status that needs it.",
+      "language": "html",
+      "source": "<div slStatCard [delta]=\"0.032\" goodWhen=\"up\">\n  <div slStatCardHeader>\n    <span slStatCardLabel>Fill rate</span>\n    <span slStatCardStatus><span slBadge tone=\"success\" variant=\"soft\">Live</span></span>\n    <span slStatCardAction><a slLink href=\"/reports/fill-rate\">Details</a></span>\n  </div>\n  <div slStatCardFigure>\n    <span slStatCardValue>96.1<span slStatCardUnit>%</span></span>\n    <span slStatCardDelta></span>\n    <p slStatCardComparison>from 92.9% <span slStatCardPeriod>vs. previous quarter</span></p>\n  </div>\n  <div slStatCardTrend><span slSparkline [data]=\"fillRate\" label=\"Fill rate\" area></span></div>\n  <p slStatCardMessage>No data for this period yet.</p>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "good-when",
+      "title": "The tone comes from the meaning, not the sign",
+      "note": "A rise in fill rate and a fall in stockouts are both success; a rise in lead time and a fall in orders are both danger; a flat change and a metric with no valence stay neutral, and the sparkline in the trend follows the delta.",
+      "language": "html",
+      "source": "<div slStatCard [delta]=\"0.18\" goodWhen=\"down\">\n  <div slStatCardHeader><span slStatCardLabel>Average lead time</span></div>\n  <div slStatCardFigure>\n    <span slStatCardValue>4.6<span slStatCardUnit>days</span></span>\n    <span slStatCardDelta></span>\n  </div>\n</div>\n\n<!-- A count nobody wants more or less of. -->\n<div slStatCard [delta]=\"0.094\" goodWhen=\"none\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "Three sizes of figure",
+      "note": "sm sets the value at 20 pixels for a row of eight, md at 24 for the four a dashboard opens with, lg at 32 — the step the type scale gained for it — for the one metric a page leads with. The trend column widens with the step.",
+      "language": "html",
+      "source": "<div slStatCard size=\"sm\">…</div>\n<div slStatCard size=\"md\">…</div>\n<div slStatCard size=\"lg\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "fill",
+      "title": "Four frames",
+      "note": "outline is the hairline card; elevated lifts on a shadow and keeps the hairline for forced colours; subtle recedes onto the sunken surface; plain has no frame and no inset, for a table cell or a row divided by rules where a second edge would be a box in a box.",
+      "language": "html",
+      "source": "<div slStatCard fill=\"outline\">…</div>\n<div slStatCard fill=\"elevated\">…</div>\n<div slStatCard fill=\"subtle\">…</div>\n<div slStatCard fill=\"plain\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "layout",
+      "title": "The trend beside the figure, or under it",
+      "note": "inline puts the sparkline in a column beside the value, centred on the figure; stacked gives it the full width on the last row, level with the bottom of every card in the row. Under 220 pixels a card stacks on its own and drops the value one step.",
+      "language": "html",
+      "source": "<div slStatCard layout=\"inline\">…</div>\n<div slStatCard layout=\"stacked\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "loading",
+      "title": "The layout is kept while the value is on its way",
+      "note": "Every text part stands in with a placeholder of its own line height and the trend with a block the sparkline’s height, so nothing moves when the numbers arrive; the previous value is not shown as if it were current.",
+      "language": "html",
+      "source": "<div slStatCard [loading]=\"pending()\">\n  <div slStatCardHeader><span slStatCardLabel>Open orders</span></div>\n  <div slStatCardFigure>\n    <span slStatCardValue [value]=\"orders().total\"></span>\n    <span slStatCardDelta [value]=\"orders().delta\"></span>\n  </div>\n  <div slStatCardTrend><span slSparkline [data]=\"orders().series\"></span></div>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "status",
+      "title": "A value that is missing, and one that failed",
+      "note": "empty and error keep the card’s frame and height, put a dash where the value was, drop the delta, the comparison and the trend, and show the message — in the danger tone when the metrics service did not answer.",
+      "language": "html",
+      "source": "<div slStatCard [status]=\"error() ? 'error' : 'empty'\">\n  <div slStatCardHeader><span slStatCardLabel>Churn</span></div>\n  <div slStatCardFigure><span slStatCardValue></span></div>\n  <p slStatCardMessage>\n    {{ error() ? 'The metrics service did not answer.' : 'No data for this period yet.' }}\n  </p>\n</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "row",
+      "title": "A row of metrics, as a dashboard opens",
+      "note": "Four cards in a grid with different content — a wrapped delta, no delta, bars instead of a line — keep their labels level at the top and their trends level at the bottom; below, three plain cards in one framed row separated by rules.",
+      "language": "html",
+      "source": "<div slGrid [columns]=\"4\" [gap]=\"4\">\n  <div slStatCard [delta]=\"0.124\">…</div>\n  <div slStatCard [delta]=\"0.032\">…</div>\n  <div slStatCard [delta]=\"0.003\" goodWhen=\"down\">…</div>\n  <div slStatCard>…</div>\n</div>\n\n<!-- Plain and small, in a framed rail; set once with provideStatCardDefaults. -->\n<div slStatCard fill=\"plain\" size=\"sm\" [delta]=\"0.081\">…</div>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A German label that wraps to three lines and keeps its badge on the first; a currency value too wide for the trend, which gives way instead of the number breaking; a card at 200 pixels that stacks; a right-to-left document where the sign stays in front and the marks turn.",
+      "language": "html",
+      "source": "<span\n  slStatCardValue\n  [value]=\"1234567890\"\n  [formatOptions]=\"{ style: 'currency', currency: 'BRL', notation: 'compact' }\"\n></span>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "The card is a group named by its label, so the details link inside it is “Details, Fill rate”; the delta reads “up +3.2%” with the direction said before the sign; the sparkline is an image described in the same numbers; the words are those of the language in force.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideSlotted({ locale: 'pt-BR', catalogs: { 'pt-BR': PT_BR } })],\n});\n",
+      "verdict": "excerpt"
+    }
+  ]
+}