{
  "tag": "ed-toolbar",
  "kind": "component",
  "summary": "The action and state zone above a collection or record — search, actions, view controls,\nand the row that shows what the view is narrowed to.",
  "status": "experimental",
  "level": "organism",
  "since": "1.0",
  "docs": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/toolbar/",
  "usage": "https://test-apps.eurodata.de/a/eurodata-ui/docs/components/toolbar/usage/",
  "playwright": "getByTestId('…')",
  "dependencies": [
    "ed-button",
    "ed-dropdown",
    "ed-dropdown-item",
    "ed-divider",
    "ed-icon",
    "ed-tooltip"
  ],
  "use": [
    "The row above a list of invoices or employees holding the main action, search and view controls, so a clerk finds everything in one place",
    "Showing a clerk which filters currently narrow a list and how many records match, with a way to clear them",
    "Actions that apply to the selected records of a table, such as approve or export, enabled only once something is selected"
  ],
  "notFor": [
    {
      "when": "Page title, breadcrumb or navigation to other areas",
      "instead": "a [Header](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/header) or a [Breadcrumb](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/breadcrumb)"
    },
    {
      "when": "Actions that belong to a single row",
      "instead": "a row action inside a [Data Grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid)"
    }
  ],
  "rules": [
    {
      "id": "toolbar/text-labels",
      "rule": "Give every button in the toolbar a visible text label alongside its icon — never an icon-only button anywhere in the bar.",
      "why": "Icon-only buttons are not acceptable in eurodata products: our usability research confirms users overlook and misuse them, including experienced users who have worked with a product for years.",
      "check": "error"
    },
    {
      "id": "toolbar/label",
      "rule": "Name what the actions apply to in `label`, not the widget — \"Invoices\", never \"Toolbar\" or \"Actions\".",
      "check": "error"
    },
    {
      "id": "toolbar/one-per-collection",
      "rule": "Keep one toolbar per collection; a master-detail screen may have one per pane.",
      "check": "warning"
    },
    {
      "id": "toolbar/accent-first",
      "rule": "Put the accent action first, and never a secondary action to the left of it.",
      "check": "warning"
    },
    {
      "id": "toolbar/one-accent-per-screen",
      "rule": "Use at most one accent button per scope, as [Button](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/button)'s `button/one-accent-per-scope` defines it — never a second one because the screen has a second toolbar: toolbars on the same surface share its scope.",
      "why": "The toolbar sees only itself, so this one stays with you.",
      "check": "warning"
    },
    {
      "id": "toolbar/secondary-plain",
      "rule": "Give secondary actions a plain appearance; reserve outlined for an action that is a near-equal alternative to the accent one.",
      "check": "error"
    },
    {
      "id": "toolbar/action-order",
      "rule": "Order the remaining actions by frequency of use, and keep that order identical across screens of the same module."
    },
    {
      "id": "toolbar/filter-button-in-view",
      "rule": "Put the button that opens the filter panel in the `view` slot, beside the quick filters it extends.",
      "why": "It decides what is shown, and there it never collapses into the overflow menu.",
      "check": "warning"
    },
    {
      "id": "toolbar/actions-only",
      "rule": "Put nothing but actions in the default slot. If you genuinely need a select or a badge there, **handle the disappearing yourself** — the toolbar will move it into the menu, where it cannot function.",
      "why": "A select or a badge there turns into an unusable menu entry as soon as the bar collapses.",
      "check": "warning"
    },
    {
      "id": "toolbar/destructive-last",
      "rule": "Place destructive actions last, behind a [Divider](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/divider): in the bar, it keeps them apart from the safe ones as [Button](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/button)'s `button/separate-destructive` asks. Don't hide the divider yourself — the bar hides it wherever it would separate nothing (leading, trailing, or once the action behind it has collapsed) and shows it again as soon as a visible action stands on either side.",
      "check": "error"
    },
    {
      "id": "toolbar/full-action-labels",
      "rule": "Never shorten an action label to save width: the bar handles the width itself.",
      "why": "The label is what makes the action findable in the overflow menu, where the surrounding context is gone.",
      "check": "warning"
    },
    {
      "id": "toolbar/unavailable-actions",
      "rule": "Disable an action that is currently unavailable — one that needs a selection, say — rather than hiding it, and name the reason in an `ed-tooltip` whose `for` points at the action's id, as [Button](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/button)'s `button/explain-disabled` asks. Place the tooltip outside the toolbar, never in its action slot.",
      "why": "A bar whose contents change with the state has to be re-read every time. A tooltip in the action slot counts as an action, gets measured, and ends up as an empty entry in the overflow menu.",
      "check": "error"
    },
    {
      "id": "toolbar/enable-possible",
      "rule": "Check that an action requiring a selection sits above something that can be selected.",
      "why": "An action no state could ever enable does not belong in the bar."
    },
    {
      "id": "toolbar/spacing-from-layout",
      "rule": "Let the surrounding layout set the spacing below the toolbar.",
      "why": "A margin on the component itself loses to any page reset.",
      "check": "error"
    },
    {
      "id": "toolbar/flex-item-sizing",
      "rule": "Give the toolbar `flex: 1` — in a grid, a track such as `1fr` — and `min-inline-size: 0` when it sits in a flex row or a grid, so it can move actions into the menu.",
      "why": "Without them it keeps its natural width, as any flex or grid item does.",
      "check": "error"
    },
    {
      "id": "toolbar/counter-wording",
      "rule": "Word the counter as [Data Grid](https://test-apps.eurodata.de/a/eurodata-ui/docs/components/data-grid) prescribes for its own — the total by default (\"13 entries\"), \"4 of 13 entries\" when filtered, and the selection after it when rows are selected (\"13 entries · 2 selected\").",
      "why": "A filtered count without its reference point reads as the whole dataset."
    },
    {
      "id": "toolbar/sticky-wrapper",
      "rule": "Check first whether the toolbar needs to stick at all — where the layout caps its own height so only the Data Grid body scrolls, the bar has nowhere to go — and where it does not stick, none of what follows is needed. To keep it in view on a scrolling page, wrap it in an element of your own and put all four of `position: sticky`, `inset-block-start`, an opaque background and a `z-index` on that wrapper.",
      "why": "The bar carries no sticky mode of its own: without the offset nothing sticks, and without the background the content scrolls through it.",
      "check": "error"
    },
    {
      "id": "toolbar/no-row-actions-or-page-identity",
      "rule": "Never put row-level actions, the page title or the breadcrumb into the toolbar.",
      "check": "error"
    },
    {
      "id": "toolbar/one-density",
      "rule": "Never mix densities in the bar — see [Form Controls](https://test-apps.eurodata.de/a/eurodata-ui/docs/theming/form-controls/usage/)' `form-controls/default-density`.",
      "why": "Controls of different heights make a restless row, and the bar centers them rather than aligning what the eye reads as one line.",
      "check": "error"
    },
    {
      "id": "toolbar/internal-attributes",
      "rule": "Never style or query against `data-ed-toolbar-overflowed` or `data-ed-toolbar-lines`; treat them as internal.",
      "why": "The toolbar writes both itself — the first onto your own actions — and takes them back off again.",
      "check": "error",
      "covered": true
    },
    {
      "id": "toolbar/search-width",
      "rule": "Give the search field the width it should have on a full-width bar, and never count on it giving up width before anything else.",
      "why": "It keeps the width you give it until the bar breaks into lines, and only then is it stretched to fill its own line."
    },
    {
      "id": "toolbar/field-labels",
      "rule": "Give a field in the bar no visible label: its value or its placeholder names it — \"Client: Miller Ltd\", \"Search invoices\" — and `aria-label` gives it its name.",
      "why": "The bar is one line high, and a label above a field makes it three lines tall beside a one-line button."
    }
  ],
  "api": {
    "attributes": [
      {
        "name": "label",
        "property": "label",
        "type": "string",
        "default": "''",
        "description": "An accessible name for the control row. Not displayed, but announced by assistive technology —\nname what the actions apply to (e.g. \"Invoices\"), not the widget."
      },
      {
        "name": "dir",
        "property": "dir",
        "type": "string"
      },
      {
        "name": "lang",
        "property": "lang",
        "type": "string"
      }
    ],
    "properties": [],
    "methods": [],
    "events": [],
    "slots": [
      {
        "name": "",
        "description": "Actions: anything that acts on what the page is about — creating, exporting, deleting — or opens a surface to do so. Typically `<ed-button>`, `<ed-dropdown>` and `<ed-divider>` elements."
      },
      {
        "name": "search",
        "description": "The search field, always first at the leading edge. Typically `<ed-input type=\"search\">`."
      },
      {
        "name": "view",
        "description": "Controls that decide what is shown: context selectors, quick filters, the button that opens a filter panel, view switches. They never collapse into the overflow menu. Typically `<ed-select>`, `<ed-radio-group appearance=\"button\">` or an `<ed-button>` for the filter panel."
      },
      {
        "name": "meta",
        "description": "Entry and selection counts, wrapped in an element — a bare text node cannot be assigned to a named slot, so use `<span slot=\"meta\">`."
      },
      {
        "name": "filters",
        "description": "Active filters and the reset that clears them."
      }
    ],
    "cssProperties": [
      {
        "name": "--ed-toolbar-gap",
        "default": "var(--ed-space-2)",
        "description": "The gap between controls on the control row."
      },
      {
        "name": "--ed-toolbar-row-gap",
        "default": "var(--ed-space-2)",
        "description": "The gap between the control row and the state row."
      },
      {
        "name": "--ed-toolbar-state-min-height",
        "default": "the height of a compact ed-button",
        "description": "The minimum height of the state row. It keeps the content below from shifting when the first filter and its reset arrive beside a counter, and when the last filter is removed **and a counter remains** — with no counter the row is empty and collapses entirely, which is intended. Raise it when the row holds something taller than a compact button."
      }
    ],
    "parts": [
      {
        "name": "base",
        "description": "The component's base wrapper, holding both rows."
      },
      {
        "name": "controls",
        "description": "The control row: search, actions and view controls on one line."
      },
      {
        "name": "search",
        "description": "The container around the `search` slot."
      },
      {
        "name": "actions",
        "description": "The container around the default slot."
      },
      {
        "name": "overflow",
        "description": "The dropdown holding the actions that no longer fit."
      },
      {
        "name": "overflow-trigger",
        "description": "The button that opens the overflow menu."
      },
      {
        "name": "view",
        "description": "The container around the `view` slot."
      },
      {
        "name": "state",
        "description": "The state row, rendered only while `meta` or `filters` has content."
      },
      {
        "name": "state-divider",
        "description": "The separator between the counter and the filters, rendered only while both carry content."
      },
      {
        "name": "meta",
        "description": "The container around the `meta` slot."
      },
      {
        "name": "filters",
        "description": "The container around the `filters` slot."
      }
    ],
    "states": []
  },
  "import": "import '@eurodata/eurodata-ui/dist/components/toolbar/toolbar.js';",
  "react": {
    "component": "EdToolbar",
    "import": "import EdToolbar from '@eurodata/eurodata-ui/dist/react/toolbar/index.js';"
  }
}