{
  "$schema": "../manifest.schema.json",
  "schemaVersion": "1.0.0",
  "name": "ds-autocomplete",
  "description": "Autocomplete input field with suggestions",
  "docUrl": "https://design.soracom.io/design-system/elements/autocomplete/",
  "category": "elements",
  "htmlElements": [
    "div"
  ],
  "isWebComponent": false,
  "modifiers": {
    "layout": {
      "support": "custom",
      "values": [
        "--inline",
        "--top",
        "--bottom",
        "--viewport"
      ]
    },
    "state": {
      "support": "subset",
      "values": [
        "--loading"
      ]
    }
  },
  "structure": {
    "parts": {
      "inputComponent": {
        "element": "input",
        "alternativeElements": [
          "div"
        ],
        "selector": ".ds-input",
        "required": true,
        "position": [
          "first"
        ]
      },
      "control": {
        "element": "input",
        "selector": "input",
        "required": true
      },
      "toggle": {
        "element": "button",
        "selector": ".ds-button",
        "optional": true,
        "position": [
          "after inputComponent"
        ]
      },
      "options": {
        "element": "ul",
        "alternativeElements": [
          "div"
        ],
        "selector": ".ds-menu, .__list, [role=\"listbox\"], [role=\"grid\"]",
        "required": true,
        "position": [
          "last"
        ]
      }
    },
    "patterns": {
      "listbox": "<div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"false\" aria-controls=\"{id}\" aria-autocomplete=\"list\" aria-haspopup=\"listbox\"><input type=\"text\" autocomplete=\"off\"></div><ul class=\"__list\" id=\"{id}\" role=\"listbox\"><li role=\"option\">{option}</li></ul></div>",
      "with-toggle": "<div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"false\" aria-controls=\"{id}\" aria-autocomplete=\"list\" aria-haspopup=\"listbox\"><input type=\"text\" autocomplete=\"off\"></div><button class=\"ds-button --plain --addon --icon-ui-arrow-down\" type=\"button\" aria-expanded=\"false\" aria-controls=\"{id}\" aria-haspopup=\"listbox\"><span>Show options</span></button><ul class=\"__list\" id=\"{id}\" role=\"listbox\"><li role=\"option\">{option}</li></ul></div>",
      "popover": "<div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"false\" aria-controls=\"{id}\" aria-autocomplete=\"list\" aria-haspopup=\"listbox\"><input type=\"text\" autocomplete=\"off\"></div><ul class=\"__list\" id=\"{id}\" role=\"listbox\" popover><li role=\"option\">{option}</li></ul></div>"
    }
  },
  "attributes": {
    "type": {
      "description": "Native input type for the autocomplete text control.",
      "values": [
        "text",
        "search"
      ],
      "default": "text",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "name": {
      "description": "Form field name submitted with the selected or entered value.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "value": {
      "description": "Initial value for the autocomplete control.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "placeholder": {
      "description": "Placeholder text shown when the autocomplete control is empty.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "autocomplete": {
      "description": "Browser autocomplete hint for the text control. Use off when SDS suggestions provide the values.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "disabled": {
      "description": "Disables the autocomplete text control.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "readonly": {
      "description": "Makes the autocomplete text control read-only.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "required": {
      "description": "Marks the autocomplete text control as required for native form validation.",
      "appliesTo": [
        {
          "part": "control",
          "elements": [
            "input"
          ]
        }
      ]
    },
    "popover": {
      "description": "Enables native popover behavior on the autocomplete options list.",
      "default": "auto",
      "appliesTo": [
        {
          "part": "options",
          "elements": [
            "ul",
            "div"
          ]
        }
      ]
    }
  },
  "dataAttributes": [
    {
      "name": "data-ds-message",
      "description": "Displays status or empty-state message text on the autocomplete options list.",
      "valueType": "string"
    }
  ],
  "accessibility": {
    "roleContracts": [
      {
        "name": "combobox",
        "description": "Identifies the autocomplete input component and exposes its popup state.",
        "required": true,
        "appliesTo": [
          {
            "part": "inputComponent",
            "elements": [
              "input",
              "div"
            ]
          }
        ]
      },
      {
        "name": "listbox",
        "description": "Identifies the popup containing autocomplete options.",
        "appliesTo": [
          {
            "part": "options",
            "elements": [
              "ul",
              "div"
            ]
          }
        ]
      },
      {
        "name": "grid",
        "description": "Identifies a grid popup used for structured autocomplete options.",
        "appliesTo": [
          {
            "part": "options",
            "elements": [
              "ul",
              "div"
            ]
          }
        ]
      }
    ],
    "ariaAttributeContracts": [
      {
        "name": "aria-expanded",
        "description": "Reports whether the autocomplete options list is open.",
        "values": [
          "true",
          "false"
        ],
        "appliesTo": [
          {
            "part": "inputComponent",
            "elements": [
              "input",
              "div"
            ]
          },
          {
            "part": "toggle",
            "elements": [
              "button"
            ]
          }
        ]
      },
      {
        "name": "aria-controls",
        "description": "References the autocomplete options list.",
        "appliesTo": [
          {
            "part": "inputComponent",
            "elements": [
              "input",
              "div"
            ]
          },
          {
            "part": "toggle",
            "elements": [
              "button"
            ]
          }
        ]
      },
      {
        "name": "aria-autocomplete",
        "description": "Describes how autocomplete suggestions are provided.",
        "values": [
          "list",
          "both",
          "inline",
          "none"
        ],
        "appliesTo": [
          {
            "part": "inputComponent",
            "elements": [
              "input",
              "div"
            ]
          }
        ]
      },
      {
        "name": "aria-haspopup",
        "description": "Identifies the controlled popup as a listbox or grid.",
        "values": [
          "listbox",
          "grid"
        ],
        "appliesTo": [
          {
            "part": "inputComponent",
            "elements": [
              "input",
              "div"
            ]
          },
          {
            "part": "toggle",
            "elements": [
              "button"
            ]
          }
        ]
      },
      {
        "name": "aria-activedescendant",
        "description": "References the active option while DOM focus remains on the text control.",
        "appliesTo": [
          {
            "part": "inputComponent",
            "elements": [
              "input",
              "div"
            ]
          }
        ]
      }
    ],
    "notes": [
      "Application code must synchronize aria-expanded from the popover toggle event so showPopover(), hidePopover(), light dismissal, and Escape remain reflected.",
      "Application code remains responsible for option roles and selection, active-descendant tracking, focus management, and keyboard navigation.",
      "Non-inline autocomplete lists require CSS Anchor Positioning; browsers without the required features are unsupported.",
      "The --inline variant is an in-flow list and should not use the native popover pattern."
    ]
  },
  "examples": [
    {
      "name": "basic",
      "html": "<div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"false\" aria-controls=\"ac-list\" aria-autocomplete=\"list\"><input type=\"text\" placeholder=\"Search...\" autocomplete=\"off\"></div><button class=\"ds-button --plain --addon --icon-ui-arrow-down\"></button><ul class=\"__list\" id=\"ac-list\" role=\"listbox\"><li role=\"option\">Option 1</li><li role=\"option\">Option 2</li><li role=\"option\">Option 3</li></ul></div>"
    },
    {
      "name": "with-filter",
      "html": "<div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"true\" aria-controls=\"ac-filter-list\" aria-autocomplete=\"list\"><input type=\"text\" placeholder=\"Filter items...\" autocomplete=\"off\"></div><ul class=\"__list\" id=\"ac-filter-list\" role=\"listbox\"><li role=\"option\">Apple</li><li role=\"option\">Banana</li><li role=\"option\">Cherry</li></ul></div>"
    },
    {
      "name": "popover",
      "html": "<div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"false\" aria-controls=\"ac-popover-list\" aria-autocomplete=\"list\" aria-haspopup=\"listbox\"><input type=\"text\" placeholder=\"Search...\" autocomplete=\"off\"></div><ul class=\"__list\" id=\"ac-popover-list\" role=\"listbox\" popover><li role=\"option\">Option 1</li><li role=\"option\">Option 2</li><li role=\"option\">Option 3</li></ul></div>"
    },
    {
      "name": "inline",
      "html": "<div class=\"ds-autocomplete --inline\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"true\" aria-controls=\"ac-inline-list\" aria-autocomplete=\"list\"><input type=\"text\" placeholder=\"Search...\" autocomplete=\"off\"></div><ul class=\"__list\" id=\"ac-inline-list\" role=\"listbox\"><li role=\"option\">Option 1</li><li role=\"option\">Option 2</li></ul></div>"
    },
    {
      "name": "withLabel",
      "html": "<label class=\"ds-field\"><div class=\"ds-text --label\">Select Item</div><div class=\"ds-autocomplete\"><div class=\"ds-input\" role=\"combobox\" aria-expanded=\"false\" aria-controls=\"ac-field-list\" aria-autocomplete=\"list\"><input type=\"text\" placeholder=\"Search...\" autocomplete=\"off\"></div><ul class=\"__list\" id=\"ac-field-list\" role=\"listbox\"><li role=\"option\">Option 1</li><li role=\"option\">Option 2</li></ul></div></label>"
    }
  ]
}