{
  "tag": "ed-rating",
  "kind": "component",
  "summary": "Ratings give users a way to quickly view and provide feedback.",
  "status": "experimental",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/rating/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/rating/usage/",
  "playwright": "getByTestId('…')",
  "dependencies": [
    "ed-icon"
  ],
  "use": [
    "Quick, single-scale feedback — how good a product, service, or experience was on one dimension",
    "A read-only display of a score or an average rating at a glance"
  ],
  "notFor": [
    {
      "when": "A precise or continuous value (an exact percentage, amount, or fine-grained score)",
      "instead": "a [Slider](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/slider) or [Number Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/number-input)"
    },
    {
      "when": "Multi-criteria feedback (rating cleanliness, service, and value separately)",
      "instead": "a form with one rating per criterion"
    },
    {
      "when": "A long scale of ten or more points",
      "instead": "a [Slider](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/slider) or [Number Input](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/number-input)"
    },
    {
      "when": "The only channel when nuance matters",
      "instead": "pair it with a comment field in a form"
    }
  ],
  "rules": [
    {
      "id": "rating/reselect-clears",
      "rule": "Make sure users understand they can remove a rating by selecting the current value again — never leave them unaware of it — and never rely on the control being unable to return to an empty state.",
      "why": "Selecting the symbol that equals the current value clears the rating back to none (zero). This lets users undo a rating, but it surprises people who expect re-selecting to do nothing."
    },
    {
      "id": "rating/small-scale",
      "rule": "Keep the scale small and ordinal — around five symbols is the norm and the default.",
      "check": "warning"
    },
    {
      "id": "rating/whole-steps-for-input",
      "rule": "Use whole-symbol steps for input, especially on touch and small screens — half-symbol input there only when the task genuinely needs sub-whole precision.",
      "check": "warning"
    },
    {
      "id": "rating/fractional-averages",
      "rule": "Reserve fractional (half-symbol) precision mainly for displaying averages, where rounding to a whole symbol would lose meaning. When precision matters, never display an average as rounded whole symbols — show the fractional fill or the number.",
      "check": "warning"
    },
    {
      "id": "rating/accessible-label",
      "rule": "Always give the control a descriptive text label for assistive technology, even where the meaning \"looks obvious\" from context.",
      "why": "The label is not shown on screen, so users of screen readers depend on it.",
      "check": "error"
    },
    {
      "id": "rating/visible-required-and-errors",
      "rule": "Surface requiredness and validation errors in nearby visible text when the rating is mandatory.",
      "why": "Unlike other form controls, it renders no label, hint, or error message of its own.",
      "check": "warning"
    },
    {
      "id": "rating/average-with-count",
      "rule": "Pair a displayed average with the number of ratings behind it, so the score has context.",
      "check": "warning"
    },
    {
      "id": "rating/word-labels",
      "rule": "Give word feedback as the user hovers or selects (\"Terrible\" … \"Excellent\") — never rely on the symbols alone to convey what each level means.",
      "check": "warning"
    },
    {
      "id": "rating/fitting-symbols",
      "rule": "Choose symbols that fit the concept — stars for quality or satisfaction, hearts for favoriting or liking."
    },
    {
      "id": "rating/symbol-size",
      "rule": "Keep symbols large enough to tap comfortably, and scale them with the surrounding text size.",
      "check": "error"
    },
    {
      "id": "rating/readonly-not-disabled",
      "rule": "Use read-only for a value the user can never change, and disabled only when it could become editable under some condition — never disabled styling to present a permanent, unchangeable score."
    },
    {
      "id": "rating/default-density",
      "rule": "Keep `density` at its default. Choose `compact` or `spacious` only deliberately for a specifically tighter or looser layout, or `compact` for a control inside a [Data Grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid) — never to fine-tune spacing case by case.",
      "why": "The default suits standard forms and layouts, and it is the intended spacing for almost every screen.",
      "check": "warning"
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "name",
        "property": "name",
        "type": "null | string",
        "default": "null",
        "description": "The name of the rating, submitted as a name/value pair with form data."
      },
      {
        "name": "label",
        "property": "label",
        "type": "string",
        "default": "''",
        "description": "A label that describes the rating to assistive devices."
      },
      {
        "name": "value",
        "property": "value",
        "type": "number",
        "description": "The current rating. Reading it gives a value that sits within `0`–`max` and on the `precision`\ngrid, whatever was written — the same correction a range control applies, except that `0` stays\nreachable here: it is this control's empty state, and `required` rests on it. So anything\nunusable becomes `0` rather than the middle of the range."
      },
      {
        "name": "default-value",
        "property": "defaultValue",
        "type": "number",
        "default": "0",
        "description": "The default value of the form control. Used to reset the rating to its initial value."
      },
      {
        "name": "max",
        "property": "max",
        "type": "number",
        "description": "The highest rating to show."
      },
      {
        "name": "precision",
        "property": "precision",
        "type": "number",
        "default": "1",
        "description": "The precision at which the rating will increase and decrease. For example, to allow half-star ratings, set this\nattribute to `0.5`."
      },
      {
        "name": "readonly",
        "property": "readonly",
        "type": "boolean",
        "default": "false",
        "description": "Makes the rating readonly."
      },
      {
        "name": "required",
        "property": "required",
        "type": "boolean",
        "default": "false",
        "description": "Makes the rating a required field — a value of 0 counts as missing."
      },
      {
        "name": "error",
        "property": "error",
        "type": "null | string",
        "default": "null",
        "description": "Blocks form submission — with a localized generic message when set to an empty string, with the\ngiven text otherwise — and sets the `error` custom state. `ed-rating` renders no message area\nand brings no error styling, so the constraint is the only effect a user notices; style\n`:state(error)` to show one."
      },
      {
        "name": "warning",
        "property": "warning",
        "type": "null | string",
        "default": "null",
        "description": "Sets the `warning` custom state and does not block form submission. `ed-rating` renders no\nmessage area and brings no warning styling, so the message text is never shown; style\n`:state(warning)` to show one."
      },
      {
        "name": "ai",
        "property": "ai",
        "type": "boolean",
        "default": "false",
        "description": "Sets the `ai` custom state until the user interacts. `ed-rating` brings no AI styling, so the\nstate is the only effect; style `:state(ai)` to show one."
      },
      {
        "name": "hint",
        "property": "hint",
        "type": "string",
        "default": "''",
        "description": "Has no effect on `ed-rating`, which renders no hint area. Put explanatory text next to the\nrating instead."
      },
      {
        "name": "icon",
        "property": "icon",
        "type": "string",
        "default": "'favorite'",
        "description": "The icon name for inactive (unselected) symbols."
      },
      {
        "name": "active-icon",
        "property": "activeIcon",
        "type": "string",
        "default": "'favorite_filled'",
        "description": "The icon name for active (selected) symbols."
      },
      {
        "name": "density",
        "property": "density",
        "type": "'compact' | 'default' | 'spacious'",
        "default": "'default'",
        "description": "The component's density."
      },
      {
        "name": "disabled",
        "property": "disabled",
        "type": "boolean",
        "description": "Disables the form control. HTML treats a control as disabled when either its own `disabled` is\nset or an ancestor `<fieldset>` is disabled, so reading this reports the combined state while\nwriting it sets only this element's own. Keeping the two apart is what lets a fieldset be\nre-enabled without clearing a disabled state the consumer set in the meantime."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [
      {
        "name": "form",
        "type": "HTMLFormElement | null",
        "description": "By default, form controls are associated with the nearest containing `<form>` element. This attribute allows you\nto place the form control outside of a form and associate it with the form that has this `id`. The form must be in\nthe same document or shadow root for this to work."
      },
      {
        "name": "validationTarget",
        "type": "undefined | HTMLElement",
        "description": "Override this to change where constraint validation popups are anchored."
      }
    ],
    "methods": [
      {
        "name": "setCustomValidity",
        "parameters": [
          {
            "name": "message",
            "type": "string"
          }
        ],
        "description": "Do not use this when creating a \"Validator\". This is intended for end users of components.\nWe track manually defined custom errors so we don't clear them on accident in our validators."
      },
      {
        "name": "resetValidity",
        "description": "Reset validity is a way of removing manual custom errors and native validation."
      }
    ],
    "events": [
      {
        "name": "change",
        "react": "onChange",
        "description": "Emitted when the rating's value changes."
      },
      {
        "name": "ed-hover",
        "react": "onEdHover",
        "type": "{ phase: 'start' | 'move' | 'end', value: number }",
        "description": "Emitted when the user hovers over a value. The `phase` property indicates when hovering starts, moves to a new value, or ends. The `value` property tells what the rating's value would be if the user were to commit to the hovered value."
      },
      {
        "name": "ed-invalid",
        "react": "onEdInvalid",
        "description": "Emitted when the form control has been checked for validity and its constraints aren't satisfied."
      }
    ],
    "slots": [],
    "cssProperties": [
      {
        "name": "--ed-rating-symbol-color",
        "description": "The inactive color for symbols."
      },
      {
        "name": "--ed-rating-symbol-color-active",
        "description": "The active color for symbols."
      },
      {
        "name": "--ed-rating-symbol-spacing",
        "description": "The spacing to use around symbols."
      }
    ],
    "parts": [
      {
        "name": "base",
        "description": "The component's base wrapper."
      }
    ],
    "states": [
      {
        "name": "disabled",
        "description": "Applied when the rating is disabled."
      },
      {
        "name": "error",
        "description": "Applied when the rating carries the error hint state. `ed-rating` brings no error styling of its own — style this state to show one."
      },
      {
        "name": "warning",
        "description": "Applied when the rating carries the warning hint state. Unstyled by default."
      },
      {
        "name": "ai",
        "description": "Applied when the rating carries the AI hint state, until the user interacts. Unstyled by default."
      },
      {
        "name": "required",
        "description": "The control is required."
      },
      {
        "name": "optional",
        "description": "The control is not required."
      },
      {
        "name": "invalid",
        "description": "The value fails constraint validation, whether or not the user has touched the control yet."
      },
      {
        "name": "valid",
        "description": "The value passes constraint validation."
      },
      {
        "name": "user-invalid",
        "description": "Invalid, and the user has interacted with the control. This is the one to style for an error: it behaves like the platform's `:user-invalid`, so an untouched field is not marked wrong before the user has had a chance to fill it in."
      },
      {
        "name": "user-valid",
        "description": "Valid, and the user has interacted with the control."
      },
      {
        "name": "dirty",
        "description": "The user has interacted with the control."
      }
    ]
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/rating/rating.js';",
  "react": {
    "component": "EdRating",
    "import": "import EdRating from '@eurodata/eurodata-ui/dist/react/rating/index.js';"
  }
}