@slotted/react 0.0.0-stage → 0.1.0-beta.1

package/dist/docs/rating.json

@@ -0,0 +1,1082 @@
+{
+  "family": "rating",
+  "ui": "rating",
+  "binding": "react",
+  "catalog": {
+    "group": "Forms",
+    "summary": "Star rating input, display and summary."
+  },
+  "axes": {
+    "size": [
+      "sm",
+      "md",
+      "lg"
+    ],
+    "tone": [
+      "accent",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "variant": [
+      "full",
+      "compact",
+      "histogram"
+    ],
+    "summaryVariant": [
+      "bars",
+      "spectrum"
+    ]
+  },
+  "members": {
+    "rating": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "tone": "warning",
+        "max": 5,
+        "step": 1,
+        "clearable": true
+      },
+      "capabilities": [
+        "value",
+        "appearance",
+        "size",
+        "disabled",
+        "invalid",
+        "required",
+        "readOnly",
+        "wiring"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "readonly",
+        "invalid",
+        "checked"
+      ],
+      "parts": [
+        "root",
+        "symbols",
+        "item",
+        "input",
+        "symbol",
+        "fill",
+        "value"
+      ]
+    },
+    "ratingDisplay": {
+      "nativeElement": "div",
+      "defaults": {
+        "size": "md",
+        "tone": "warning",
+        "max": 5,
+        "variant": "full"
+      },
+      "capabilities": [
+        "measurement",
+        "appearance",
+        "size",
+        "content"
+      ],
+      "states": [
+        "default"
+      ],
+      "parts": [
+        "root",
+        "symbols",
+        "item",
+        "symbol",
+        "fill",
+        "value",
+        "histogram",
+        "bar",
+        "count"
+      ]
+    },
+    "ratingSummary": {
+      "nativeElement": "section",
+      "defaults": {
+        "size": "md",
+        "tone": "warning",
+        "max": 5,
+        "filterable": false,
+        "variant": "bars"
+      },
+      "capabilities": [
+        "measurement",
+        "appearance",
+        "size",
+        "content",
+        "selection"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "disabled",
+        "pressed"
+      ],
+      "parts": [
+        "root",
+        "aggregate",
+        "value",
+        "scale",
+        "insight",
+        "count",
+        "distribution",
+        "level",
+        "level-label",
+        "track",
+        "indicator",
+        "level-count",
+        "plot",
+        "field",
+        "columns",
+        "column",
+        "bar",
+        "interval",
+        "mean",
+        "mean-label",
+        "axis",
+        "tick",
+        "tick-label",
+        "tick-share",
+        "sentiment",
+        "bucket",
+        "swatch"
+      ]
+    }
+  },
+  "docs": {
+    "rating": {
+      "imports": {
+        "source": "import { Rating, RatingDisplay, RatingProvider, RatingSummary } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div, or the element render returns",
+          "required": true,
+          "purpose": "The radio group. Carries data-ui=\"rating\", data-size, data-tone, data-max, data-step at half steps, data-disabled, data-readonly, data-invalid and data-dragging while a finger scrubs, and the keydown that answers the arrows, Home, End, Backspace and Delete."
+        },
+        {
+          "part": "symbols",
+          "element": "div",
+          "required": true,
+          "purpose": "The row of symbols. It never wraps: ten symbols at 240 pixels stay one row and each item shrinks to a square, because the star inside reads the item’s width. On the input member it is the surface a finger scrubs along, with touch-action: pan-y so the page still scrolls vertically."
+        },
+        {
+          "part": "item",
+          "element": "span",
+          "required": true,
+          "purpose": "One symbol’s square. On the display it carries --slotted-rating-fill, the lit share from nought to one; on the input member it carries data-checked when it holds the checked radio."
+        },
+        {
+          "part": "input",
+          "element": "input type=\"radio\"",
+          "required": true,
+          "purpose": "One value. Every radio shares the generated or written name, so Tab, Space and submission are the platform’s. At half steps each item holds two: the half radio first, with data-half, stacked above the whole one so the inline-start half of the symbol asks for the half value."
+        },
+        {
+          "part": "symbol",
+          "element": "span",
+          "required": true,
+          "purpose": "The unlit shape: the star glyph, or what renderSymbol returns, filled with the secondary surface so an unlit star reads as a shape rather than as an outline."
+        },
+        {
+          "part": "fill",
+          "element": "span",
+          "required": true,
+          "purpose": "The same shape again, painted in the tone’s solid step and clipped to the lit share. Half a star is this layer clipped at the middle; the transition of the clip follows the direction of the change."
+        },
+        {
+          "part": "value",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The caption: a word for the value, or for the value under the pointer when caption is a function. It is hidden from assistive technology, because each radio’s own name already says the number."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "number | null",
+          "defaultValue": "—",
+          "appliesTo": "Rating",
+          "description": "Present means controlled, for the life of the component; null is a controlled empty value. Put on the grid of the scale: 3,2 on a whole scale is 4"
+        },
+        {
+          "name": "defaultValue",
+          "type": "number | null",
+          "defaultValue": "null",
+          "appliesTo": "Rating",
+          "description": "The value an uncontrolled rating starts from, read once"
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "5",
+          "appliesTo": "all members, RatingProvider",
+          "description": "How many symbols, or how many levels a summary reads from counts"
+        },
+        {
+          "name": "step",
+          "type": "1 | 0.5",
+          "defaultValue": "1",
+          "appliesTo": "Rating",
+          "description": "A whole symbol or half of one. Finer fractions are declined: a third of a 20-pixel star is below the minimum target"
+        },
+        {
+          "name": "clearable",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Rating, RatingProvider",
+          "description": "Whether a press on the checked star, Backspace and Delete empty the value"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "all members, RatingProvider",
+          "description": "The step the symbols and the text sit at. The symbol does not follow density; the text does"
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "warning",
+          "appliesTo": "all members, RatingProvider",
+          "description": "The colour a lit symbol takes. secondary is declined: its solid step is a ground, and a star lit in it reads as unlit"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Rating",
+          "description": "Unstated rather than false. Every radio is disabled natively; the value stays readable"
+        },
+        {
+          "name": "readOnly",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Rating",
+          "description": "Unstated rather than false. Every change is refused, every radio keeps its tab stop, and aria-readonly is written"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Rating",
+          "description": "Unstated rather than false. Writes aria-required on the group, never the native attribute"
+        },
+        {
+          "name": "invalid",
+          "type": "boolean",
+          "defaultValue": "from the field, or false",
+          "appliesTo": "Rating",
+          "description": "Unstated rather than false. Writes aria-invalid and data-invalid"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "defaultValue": "generated",
+          "appliesTo": "Rating",
+          "description": "The submission name every radio shares. Generated with useId when it is not written"
+        },
+        {
+          "name": "form",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "Rating",
+          "description": "The form the radios submit with"
+        },
+        {
+          "name": "caption",
+          "type": "ReactNode | ((state: { value, preview }) => ReactNode)",
+          "defaultValue": "—",
+          "appliesTo": "Rating",
+          "description": "A word for the value in the value part. A function follows the pointer"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the language in force",
+          "appliesTo": "all members",
+          "description": "The locale every number is written in: 4,6 and 1.284 in pt-BR"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<RatingMessages>",
+          "defaultValue": "—",
+          "appliesTo": "all members",
+          "description": "Words laid over the language in force, key by key: every string the family writes"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: RatingRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Rating",
+          "description": "Substitutes the div root and hands it every attribute and handler"
+        },
+        {
+          "name": "renderSymbol",
+          "type": "(state: { index, fill }) => ReactNode",
+          "defaultValue": "<Icon><Glyph name=\"star\" /></Icon>",
+          "appliesTo": "Rating",
+          "description": "Replaces the symbol. It is drawn in the unlit layer and in the lit one, so it lights the way the star does"
+        },
+        {
+          "name": "RatingProvider",
+          "type": "{ size, tone, max, clearable, insightThresholds }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once. insightThresholds merges key by key; the instance always wins. The words and the locale come from SlottedProvider"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "Rating",
+          "description": "Reaches the root element"
+        },
+        {
+          "name": "handle",
+          "type": "Ref<{ focus(): void }>",
+          "defaultValue": "—",
+          "appliesTo": "Rating",
+          "description": "focus() moves focus to the checked radio, or to the first when the value is empty"
+        }
+      ],
+      "events": [
+        {
+          "name": "onValueChange",
+          "payload": "(value: number | null, request: ChangeRequest<number | null>)",
+          "when": "Before the value moves. reason is pointer for a press or a scrub, keyboard for an arrow, Home, End or a Space the keyboard synthesised, and clear for a press on the checked star or Backspace and Delete. cancel() refuses the move. A request equal to the value held is not emitted."
+        },
+        {
+          "name": "onPreviewChange",
+          "payload": "(value: number | null)",
+          "when": "When the pointer moves over a radio, with its value, and with null when the pointer leaves the group. It is an event, not a state model: nothing the consumer owns has moved."
+        },
+        {
+          "name": "onKeyDown, onPointerDown, onPointerOver, onPointerLeave",
+          "payload": "the element’s own events",
+          "when": "Composed with the family’s: the consumer’s handler runs first, and a preventDefault() in onKeyDown keeps the key from the family."
+        }
+      ],
+      "accessibility": [
+        "The pattern is the WAI-ARIA APG’s Rating Radio Group: a radiogroup of native radios that share a name, each named by the itemLabel message — 3,5 de 5 — so the number is heard on every stop. Tab and Space are the platform’s.",
+        "The arrows depart from the radio example on purpose: they stop at both ends instead of wrapping, as the APG’s rating slider, Ark, MUI and Mantine do, because a rating that falls from five to one on one keystroke too many is a defect. Home and End reach the ends, and the inline arrows swap in a right-to-left document.",
+        "Read-only has no platform answer for a radio, so the change is refused on the click a pointer and Space share, aria-readonly is announced, and every radio keeps its tab stop. aria-required and aria-invalid are written on the group; the native required is not, because it would engage the browser’s own validation.",
+        "In the light and dark schemes a star does not reach 3:1 against the page: the value is always in the accessible name and may be written beside the stars, and the high-contrast scheme and forced colours draw lit and unlit stars as distinct shapes with a contrasting edge.",
+        "Under a coarse pointer each target grows to 44 pixels, and a finger can scrub along the row without losing vertical scrolling."
+      ]
+    },
+    "ratingDisplay": {
+      "imports": {
+        "source": "import { Rating, RatingDisplay, RatingProvider, RatingSummary } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "div role=\"img\", or the element render returns",
+          "required": true,
+          "purpose": "One image with one name. aria-label says the value, the scale and the count once, from displayLabel or displayLabelWithCount; data-variant is written for compact and histogram."
+        },
+        {
+          "part": "symbols",
+          "element": "div",
+          "required": true,
+          "purpose": "The row of symbols. It never wraps: ten symbols at 240 pixels stay one row and each item shrinks to a square, because the star inside reads the item’s width. On the input member it is the surface a finger scrubs along, with touch-action: pan-y so the page still scrolls vertically."
+        },
+        {
+          "part": "item",
+          "element": "span",
+          "required": true,
+          "purpose": "One symbol’s square. On the display it carries --slotted-rating-fill, the lit share from nought to one; on the input member it carries data-checked when it holds the checked radio."
+        },
+        {
+          "part": "symbol",
+          "element": "span",
+          "required": true,
+          "purpose": "The unlit shape: the star glyph, or what renderSymbol returns, filled with the secondary surface so an unlit star reads as a shape rather than as an outline."
+        },
+        {
+          "part": "fill",
+          "element": "span",
+          "required": true,
+          "purpose": "The same shape again, painted in the tone’s solid step and clipped to the lit share. Half a star is this layer clipped at the middle; the transition of the clip follows the direction of the change."
+        },
+        {
+          "part": "value",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The number, always to one place in the locale’s digits — 4,6 in pt-BR — and in tabular figures, so a column of displays lines up. showValue={false} removes it."
+        },
+        {
+          "part": "histogram",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The histogram variant’s bars, one per level, lowest first. Present only when distribution is."
+        },
+        {
+          "part": "bar",
+          "element": "span",
+          "required": false,
+          "purpose": "One level of the histogram, its height --slotted-rating-share: the level’s count divided by the largest count, so the tallest bar is always full."
+        },
+        {
+          "part": "count",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "How many ratings the value is made of, in the locale’s grouping — (1.284) beside five stars, 1.284 in a histogram row. Present only when count is."
+        }
+      ],
+      "api": [
+        {
+          "name": "value",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "RatingDisplay",
+          "description": "The value reported, any fraction, clamped to the scale"
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "5",
+          "appliesTo": "all members, RatingProvider",
+          "description": "How many symbols, or how many levels a summary reads from counts"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "all members, RatingProvider",
+          "description": "The step the symbols and the text sit at. The symbol does not follow density; the text does"
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "warning",
+          "appliesTo": "all members, RatingProvider",
+          "description": "The colour a lit symbol takes. secondary is declined: its solid step is a ground, and a star lit in it reads as unlit"
+        },
+        {
+          "name": "variant",
+          "type": "'full' | 'compact' | 'histogram'",
+          "defaultValue": "full",
+          "appliesTo": "RatingDisplay",
+          "description": "Every symbol, or one star beside the number, or one star and a bar per level"
+        },
+        {
+          "name": "count",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "RatingDisplay",
+          "description": "How many ratings. Written beside the number and added to the accessible name"
+        },
+        {
+          "name": "distribution",
+          "type": "readonly number[]",
+          "defaultValue": "—",
+          "appliesTo": "RatingDisplay",
+          "description": "Counts per level, lowest first, drawn by the histogram variant"
+        },
+        {
+          "name": "showValue",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "RatingDisplay",
+          "description": "Whether the number is written beside the symbols"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the language in force",
+          "appliesTo": "all members",
+          "description": "The locale every number is written in: 4,6 and 1.284 in pt-BR"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<RatingMessages>",
+          "defaultValue": "—",
+          "appliesTo": "all members",
+          "description": "Words laid over the language in force, key by key: every string the family writes"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: RatingRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "RatingDisplay",
+          "description": "Substitutes the div root and hands it every attribute and handler"
+        },
+        {
+          "name": "renderSymbol",
+          "type": "(state: { index, fill }) => ReactNode",
+          "defaultValue": "<Icon><Glyph name=\"star\" /></Icon>",
+          "appliesTo": "RatingDisplay",
+          "description": "Replaces the symbol. It is drawn in the unlit layer and in the lit one, so it lights the way the star does"
+        },
+        {
+          "name": "RatingProvider",
+          "type": "{ size, tone, max, clearable, insightThresholds }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once. insightThresholds merges key by key; the instance always wins. The words and the locale come from SlottedProvider"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLDivElement>",
+          "defaultValue": "—",
+          "appliesTo": "RatingDisplay",
+          "description": "Reaches the root element"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "The display is one image: role=\"img\" with an aria-label from displayLabel or displayLabelWithCount — Avaliação 4,6 de 5, 1.284 avaliações — and every symbol, number and count inside is hidden, so the value is said once.",
+        "The value is written in the locale’s digits and, as a label read aloud, a whole value is written whole: 4 de 5, not 4,0 de 5.",
+        "A partial star is a clip of one shape, never a colour alone; the number beside it is the reading that does not depend on seeing the fraction."
+      ]
+    },
+    "ratingSummary": {
+      "imports": {
+        "source": "import { Rating, RatingDisplay, RatingProvider, RatingSummary } from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "section, or the element render returns",
+          "required": true,
+          "purpose": "A region named by its aria-label. data-variant is summary for bars and spectrum for the spectrum, which also writes --slotted-rating-mean, --slotted-rating-low and --slotted-rating-high from summariseRatings."
+        },
+        {
+          "part": "aggregate",
+          "element": "div",
+          "required": true,
+          "purpose": "The figure a page leads with: the mean, its scale, the stars (bars) or the conclusion (spectrum), and the count. With nothing rated it writes no figure and no scale."
+        },
+        {
+          "part": "value",
+          "element": "span",
+          "required": false,
+          "purpose": "The mean to one place, at the key-figure step. Absent while nothing is rated."
+        },
+        {
+          "part": "scale",
+          "element": "span",
+          "required": false,
+          "purpose": "The scale beside the figure, from the scale message: de 5."
+        },
+        {
+          "part": "insight",
+          "element": "span",
+          "required": false,
+          "purpose": "The spectrum’s one conclusion as a pill in its tone: divided (warning), few (secondary), consensus (success) or mixed (secondary). Removed by showInsight={false} and while nothing is rated."
+        },
+        {
+          "part": "count",
+          "element": "span",
+          "required": true,
+          "purpose": "How many ratings, and in the spectrum the margin of the mean — or the interval, in words, when the margin reaches half a star."
+        },
+        {
+          "part": "distribution",
+          "element": "ul",
+          "required": false,
+          "purpose": "The bars variant’s levels, highest first, named by distributionLabel."
+        },
+        {
+          "part": "level",
+          "element": "button aria-pressed with filterable, div role=\"group\" otherwise",
+          "required": false,
+          "purpose": "One level, named by levelLabel with its count and share. Filtering, it is a toggle, disabled when nobody gave that rating, with data-pressed while pressed."
+        },
+        {
+          "part": "level-label",
+          "element": "span",
+          "required": false,
+          "purpose": "The level’s number and a star."
+        },
+        {
+          "part": "track",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The bar’s full length."
+        },
+        {
+          "part": "indicator",
+          "element": "span",
+          "required": false,
+          "purpose": "The level’s share of the total, as --slotted-rating-share."
+        },
+        {
+          "part": "level-count",
+          "element": "span",
+          "required": false,
+          "purpose": "The level’s count in the locale’s grouping."
+        },
+        {
+          "part": "plot",
+          "element": "div",
+          "required": false,
+          "purpose": "The spectrum’s drawing: the field above the axis."
+        },
+        {
+          "part": "field",
+          "element": "div",
+          "required": false,
+          "purpose": "The area the columns, the interval and the mean share, on the axis of the scale."
+        },
+        {
+          "part": "columns",
+          "element": "div",
+          "required": false,
+          "purpose": "The columns, lowest level first, as the axis reads."
+        },
+        {
+          "part": "column",
+          "element": "button aria-pressed with filterable, div role=\"group\" otherwise",
+          "required": false,
+          "purpose": "One level of the spectrum, its height --slotted-rating-share against the largest level, named and pressed as a level is."
+        },
+        {
+          "part": "bar",
+          "element": "span",
+          "required": false,
+          "purpose": "The painted column inside the target, which keeps its full height."
+        },
+        {
+          "part": "interval",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The 95% interval of the mean, from --slotted-rating-low to --slotted-rating-high, clamped to the scale."
+        },
+        {
+          "part": "mean",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The mean’s mark on the axis, at --slotted-rating-mean."
+        },
+        {
+          "part": "mean-label",
+          "element": "span",
+          "required": false,
+          "purpose": "The mean to one place, above its mark."
+        },
+        {
+          "part": "axis",
+          "element": "div aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The scale under the columns: one tick per level."
+        },
+        {
+          "part": "tick",
+          "element": "span",
+          "required": false,
+          "purpose": "One level on the axis."
+        },
+        {
+          "part": "tick-label",
+          "element": "span",
+          "required": false,
+          "purpose": "The level’s number and a star."
+        },
+        {
+          "part": "tick-share",
+          "element": "span",
+          "required": false,
+          "purpose": "The level’s share of the total, as a whole percent."
+        },
+        {
+          "part": "sentiment",
+          "element": "p",
+          "required": false,
+          "purpose": "The three buckets in one line: the upper two levels positive, the middle neutral, the lower two negative."
+        },
+        {
+          "part": "bucket",
+          "element": "span",
+          "required": false,
+          "purpose": "One bucket, its share in strong, with data-tone success, secondary or danger."
+        },
+        {
+          "part": "swatch",
+          "element": "span aria-hidden=\"true\"",
+          "required": false,
+          "purpose": "The bucket’s colour key."
+        }
+      ],
+      "api": [
+        {
+          "name": "counts",
+          "type": "readonly number[]",
+          "defaultValue": "—",
+          "appliesTo": "RatingSummary",
+          "description": "How many ratings each level holds, lowest level first; a negative or fractional count is dropped to its whole non-negative part"
+        },
+        {
+          "name": "max",
+          "type": "number",
+          "defaultValue": "5",
+          "appliesTo": "all members, RatingProvider",
+          "description": "How many symbols, or how many levels a summary reads from counts"
+        },
+        {
+          "name": "variant",
+          "type": "'bars' | 'spectrum'",
+          "defaultValue": "bars",
+          "appliesTo": "RatingSummary",
+          "description": "One bar per level beside the figure, or columns on the axis with the mean and its interval"
+        },
+        {
+          "name": "filterable",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "RatingSummary",
+          "description": "Whether each level is a toggle that filters"
+        },
+        {
+          "name": "selectedLevels",
+          "type": "readonly number[]",
+          "defaultValue": "—",
+          "appliesTo": "RatingSummary",
+          "description": "The pressed levels. Present means controlled"
+        },
+        {
+          "name": "defaultSelectedLevels",
+          "type": "readonly number[]",
+          "defaultValue": "[]",
+          "appliesTo": "RatingSummary",
+          "description": "The levels an uncontrolled summary starts pressed"
+        },
+        {
+          "name": "showInsight",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "RatingSummary",
+          "description": "Whether the spectrum writes its conclusion"
+        },
+        {
+          "name": "insightThresholds",
+          "type": "Partial<RatingInsightThresholds>",
+          "defaultValue": "{ divided: 0.25, few: 30, margin: 0.5, consensus: 0.8 }",
+          "appliesTo": "RatingSummary, RatingProvider",
+          "description": "Where the conclusions are drawn, merged over the provider’s"
+        },
+        {
+          "name": "size",
+          "type": "'sm' | 'md' | 'lg'",
+          "defaultValue": "md",
+          "appliesTo": "all members, RatingProvider",
+          "description": "The step the symbols and the text sit at. The symbol does not follow density; the text does"
+        },
+        {
+          "name": "tone",
+          "type": "'accent' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "warning",
+          "appliesTo": "all members, RatingProvider",
+          "description": "The colour a lit symbol takes. secondary is declined: its solid step is a ground, and a star lit in it reads as unlit"
+        },
+        {
+          "name": "locale",
+          "type": "string",
+          "defaultValue": "the language in force",
+          "appliesTo": "all members",
+          "description": "The locale every number is written in: 4,6 and 1.284 in pt-BR"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<RatingMessages>",
+          "defaultValue": "—",
+          "appliesTo": "all members",
+          "description": "Words laid over the language in force, key by key: every string the family writes"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props: RatingRootProps) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "RatingSummary",
+          "description": "Substitutes the section root and hands it every attribute and handler"
+        },
+        {
+          "name": "RatingProvider",
+          "type": "{ size, tone, max, clearable, insightThresholds }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "The decisions an application takes once. insightThresholds merges key by key; the instance always wins. The words and the locale come from SlottedProvider"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "RatingSummary",
+          "description": "Reaches the section"
+        }
+      ],
+      "events": [
+        {
+          "name": "onSelectedLevelsChange",
+          "payload": "(levels: readonly number[], request: ChangeRequest<readonly number[]>)",
+          "when": "Before the pressed levels move, with the levels in ascending order. reason is pointer for a press and keyboard for Enter or Space. cancel() refuses the move."
+        }
+      ],
+      "accessibility": [
+        "The summary is a region named by its aria-label. The figure, the scale and the count are text; the stars beside them are one image with its own name.",
+        "Each level is named in full by levelLabel — 5 estrelas: 1.052 avaliações, 82% — so a reader hears the level, its count and its share without reading the bar. Filtering, each is a toggle with aria-pressed, disabled where nobody rated.",
+        "The spectrum’s axis, its interval and its mean are hidden: the count line says the margin or the interval in words, and the conclusion is text in a pill, never a colour alone."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-subtle",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-gap-lg",
+    "--slotted-control-gap-md",
+    "--slotted-control-gap-sm",
+    "--slotted-control-height-sm",
+    "--slotted-control-icon-size-sm",
+    "--slotted-control-invalid-edge-width",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-foreground",
+    "--slotted-duration-instant",
+    "--slotted-duration-long",
+    "--slotted-duration-medium",
+    "--slotted-duration-short",
+    "--slotted-easing-enter",
+    "--slotted-easing-exit",
+    "--slotted-easing-standard",
+    "--slotted-focus-ring-color",
+    "--slotted-focus-ring-color-invalid",
+    "--slotted-focus-ring-offset",
+    "--slotted-focus-ring-width",
+    "--slotted-font-size-4xl",
+    "--slotted-font-size-xs",
+    "--slotted-font-weight-medium",
+    "--slotted-font-weight-regular",
+    "--slotted-font-weight-semibold",
+    "--slotted-highlight-tint-opacity",
+    "--slotted-line-height-4xl",
+    "--slotted-line-height-md",
+    "--slotted-line-height-xs",
+    "--slotted-radius-full",
+    "--slotted-radius-sm",
+    "--slotted-radius-xs",
+    "--slotted-rating-active-background",
+    "--slotted-rating-bar-color",
+    "--slotted-rating-bar-size",
+    "--slotted-rating-edge",
+    "--slotted-rating-empty-color",
+    "--slotted-rating-gap",
+    "--slotted-rating-hover-background",
+    "--slotted-rating-invalid-color",
+    "--slotted-rating-invalid-edge-width",
+    "--slotted-rating-lit-color",
+    "--slotted-rating-symbol-size",
+    "--slotted-space-1",
+    "--slotted-space-10",
+    "--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-surface-inverse",
+    "--slotted-target-comfortable",
+    "--slotted-target-min",
+    "--slotted-text",
+    "--slotted-text-inverse",
+    "--slotted-text-muted",
+    "--slotted-tone-accent-solid",
+    "--slotted-tone-danger-border",
+    "--slotted-tone-danger-solid",
+    "--slotted-tone-danger-surface",
+    "--slotted-tone-danger-text",
+    "--slotted-tone-secondary-border",
+    "--slotted-tone-secondary-subtle-active",
+    "--slotted-tone-secondary-subtle-hover",
+    "--slotted-tone-secondary-surface",
+    "--slotted-tone-success-border",
+    "--slotted-tone-success-solid",
+    "--slotted-tone-success-surface",
+    "--slotted-tone-success-text",
+    "--slotted-tone-warning-border",
+    "--slotted-tone-warning-solid",
+    "--slotted-tone-warning-surface",
+    "--slotted-tone-warning-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One rating with every prop on the controls below the canvas. Hover previews the value and the caption follows it; press the lit star again and the value empties.",
+      "language": "tsx",
+      "source": "<Rating aria-label=\"Sua avaliação\" defaultValue={4} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "half",
+      "title": "Half steps",
+      "note": "step={0.5} puts two radios in each star: the half radio sits above the whole one, so the inline-start half of a star asks for the half value. Ten arrow stops for five stars is the cost.",
+      "language": "tsx",
+      "source": "<Rating aria-label=\"Avaliação por meios pontos\" defaultValue={3.5} step={0.5} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Read-only, disabled and invalid",
+      "note": "Read-only keeps every tab stop and the lit stars, and refuses every change; disabled dims the row and leaves the value readable; invalid writes aria-invalid and reddens the focus ring.",
+      "language": "tsx",
+      "source": "<Rating aria-label=\"Sua nota anterior\" defaultValue={4} readOnly />;\n<Rating aria-label=\"Avaliação encerrada\" defaultValue={2} disabled />;\n<Rating aria-label=\"Avaliação obrigatória\" invalid required />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "field",
+      "title": "Inside a field",
+      "note": "The field names the group through aria-labelledby, says its description and error through aria-describedby, and hands down size, disabled, required and invalid. A checkbox beside it is the answer for a question that may not apply.",
+      "language": "tsx",
+      "source": "<Field required>\n  <FieldLabel>Qualidade do som</FieldLabel>\n  <Rating />\n  <FieldDescription>De uma a cinco estrelas.</FieldDescription>\n</Field>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "labels",
+      "title": "Words for the value",
+      "note": "caption as a function receives the value held and the value under the pointer, so the word follows the pointer and settles back. Each radio keeps its own number as its accessible name, through the itemLabel message.",
+      "language": "tsx",
+      "source": "const WORDS = ['Péssimo', 'Ruim', 'Regular', 'Bom', 'Excelente'];\n\n<Rating\n  aria-label=\"Atendimento\"\n  caption={({ preview, value }) => {\n    const shown = preview ?? value;\n    return shown === null ? 'Sem nota' : WORDS[shown - 1];\n  }}\n  defaultValue={4}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "keyboard",
+      "title": "The keyboard",
+      "note": "Tab lands on the checked star, or on the first. The arrows move one step and stop at both ends instead of wrapping; Home and End reach them; Backspace and Delete empty the value. The inline arrows swap in a right-to-left document.",
+      "language": "tsx",
+      "source": "<Rating\n  aria-label=\"Entrega\"\n  defaultValue={3}\n  onValueChange={(value, request) => console.log(value, request.reason)}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "touch",
+      "title": "A finger along the row",
+      "note": "A finger or a pen dragged along the stars asks for the value under it, and only when that value changes; the root carries data-dragging so the fill follows without easing. A mouse does not scrub: it previews on hover and chooses on press.",
+      "language": "tsx",
+      "source": "<Rating aria-label=\"Arraste para avaliar\" max={10} size=\"lg\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "A reported value on the controls below the canvas. It is one image: the stars, the number and the count are hidden, and the name says all three once.",
+      "language": "tsx",
+      "source": "<RatingDisplay count={1284} value={4.6} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "fractions",
+      "title": "Any fraction",
+      "note": "Each star is lit by its own share of the value, so 4,6 lights six tenths of the fifth star and 2,25 a quarter of the third — the display draws what the input member cannot offer.",
+      "language": "tsx",
+      "source": "<RatingDisplay value={4.6} />;\n<RatingDisplay value={3.5} />;\n<RatingDisplay value={2.25} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "compact",
+      "title": "Compact",
+      "note": "One star, the number and the count, for a card or a table cell with no room for five. The name still says the whole value and the scale.",
+      "language": "tsx",
+      "source": "<RatingDisplay count={1284} size=\"sm\" value={4.6} variant=\"compact\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "histogram",
+      "title": "Histogram in a list",
+      "note": "Five bars beside the number, each the share of the largest level, so a reader comparing products sees that 3,3 from a split audience and 3,3 from a lukewarm one are different products.",
+      "language": "tsx",
+      "source": "<RatingDisplay count={8} distribution={[3, 0, 1, 0, 4]} value={3.25} variant=\"histogram\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "count",
+      "title": "With and without a count",
+      "note": "count is written in the locale’s grouping and added to the accessible name; without it the name says only the value. A product nobody rated shows zero, not an empty row.",
+      "language": "tsx",
+      "source": "<RatingDisplay count={1284} value={4.6} />;\n<RatingDisplay value={3.5} />;\n<RatingDisplay count={0} value={0} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "Ten symbols in a narrow column shrink rather than wrap, another locale changes the separators, and a different symbol comes through renderSymbol, drawn in both the unlit and the lit layer.",
+      "language": "tsx",
+      "source": "<RatingDisplay max={10} value={7.5} />;\n<RatingDisplay count={1284} locale=\"en-US\" value={4.6} />;\n<RatingDisplay\n  renderSymbol={() => (\n    <Icon>\n      <Glyph name=\"dot\" />\n    </Icon>\n  )}\n  value={3}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "The bars variant: the mean as a figure, its scale, the stars and the count, then one bar per level, highest first, each the level’s share of the total.",
+      "language": "tsx",
+      "source": "<RatingSummary aria-label=\"Avaliações dos clientes\" counts={[9, 18, 47, 158, 1052]} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "filter",
+      "title": "Levels that filter",
+      "note": "filterable turns each level into a toggle with aria-pressed; a level nobody chose is disabled. The pressed levels are a state model of their own, controlled or not, with the reason pointer or keyboard.",
+      "language": "tsx",
+      "source": "const [levels, setLevels] = useState<readonly number[]>([5]);\n\n<RatingSummary\n  aria-label=\"Filtrar avaliações\"\n  counts={[9, 18, 47, 158, 1052]}\n  filterable\n  onSelectedLevelsChange={setLevels}\n  selectedLevels={levels}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "spectrum",
+      "title": "Spectrum",
+      "note": "The same counts on the axis of the scale: a column per level, the mean, its 95% interval and the three buckets. Few readings widen the interval until the count says the mean is uncertain.",
+      "language": "tsx",
+      "source": "<RatingSummary\n  aria-label=\"Resumo das avaliações\"\n  counts={[9, 18, 47, 158, 1052]}\n  variant=\"spectrum\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "insight",
+      "title": "The conclusion",
+      "note": "The first conclusion that holds: divided when both ends pass a quarter, few under thirty readings or with a margin of half a star, consensus when four in five are positive, mixed otherwise. Thresholds come from the provider or the instance.",
+      "language": "tsx",
+      "source": "<RatingSummary counts={[40, 12, 10, 14, 60]} variant=\"spectrum\" />;\n<RatingSummary counts={[1, 0, 2, 3, 4]} variant=\"spectrum\" />;\n<RatingSummary\n  counts={[9, 18, 47, 158, 1052]}\n  insightThresholds={{ consensus: 0.95 }}\n  variant=\"spectrum\"\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "empty",
+      "title": "Nothing rated yet",
+      "note": "No figure and no scale: an absent mean is not a nought. The stars stay unlit, the count says why, and the conclusion is withheld.",
+      "language": "tsx",
+      "source": "<RatingSummary aria-label=\"Sem avaliações\" counts={[0, 0, 0, 0, 0]} />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "narrow",
+      "title": "At a phone’s width",
+      "note": "The aggregate and the distribution stand side by side while both fit and stack when they do not; the spectrum keeps its axis and lets the count wrap.",
+      "language": "tsx",
+      "source": "<Measure>\n  <RatingSummary aria-label=\"Avaliações\" counts={[9, 18, 47, 158, 1052]} />\n</Measure>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}