html-aria/dist/index.d.ts

Utilities for creating accessible HTML based on the latest ARIA 1.3 specs. Lightweight, performant, tree-shakeable, and 0 dependencies.

/**
 * @see https://html.spec.whatwg.org/multipage/#toc-semantics
 */
type TagName =
  // 4.1 The root element
  | 'html'

  // 4.2 Document metadata
  | 'head'
  | 'title'
  | 'base'
  | 'link'
  | 'meta'
  | 'style'

  // 4.3 Sections
  | 'body'
  | 'article'
  | 'section'
  | 'nav'
  | 'aside'
  | 'h1'
  | 'h2'
  | 'h3'
  | 'h4'
  | 'h5'
  | 'h6'
  | 'hgroup'
  | 'header'
  | 'footer'
  | 'address'

  // 4.4 Grouping Content
  | 'p'
  | 'hr'
  | 'pre'
  | 'blockquote'
  | 'ol'
  | 'ul'
  | 'menu'
  | 'li'
  | 'dl'
  | 'dt'
  | 'dd'
  | 'figure'
  | 'figcaption'
  | 'main'
  | 'search'
  | 'div'

  // 4.5 Text-level semantics
  | 'a'
  | 'em'
  | 'strong'
  | 'small'
  | 's'
  | 'cite'
  | 'q'
  | 'dfn'
  | 'abbr'
  | 'ruby'
  | 'rt'
  | 'rp'
  | 'data'
  | 'time'
  | 'code'
  | 'var'
  | 'samp'
  | 'kbd'
  | 'sub'
  | 'sup'
  | 'i'
  | 'b'
  | 'u'
  | 'mark'
  | 'bdi'
  | 'bdo'
  | 'span'
  | 'br'
  | 'wbr'

  // 4.6 Links
  | 'a'
  | 'area'

  // 4.7 Edits
  | 'ins'
  | 'del'

  // 4.8 Embedded content
  | 'picture'
  | 'source'
  | 'img'
  | 'iframe'
  | 'embed'
  | 'object'
  | 'video'
  | 'audio'
  | 'track'
  | 'map'
  | 'area'
  | 'svg'
  | 'math'

  // 4.9 Tabular data
  | 'table'
  | 'caption'
  | 'colgroup'
  | 'col'
  | 'tbody'
  | 'thead'
  | 'tfoot'
  | 'tr'
  | 'td'
  | 'th'

  // 4.10 Forms
  | 'form'
  | 'label'
  | 'input'
  | 'button'
  | 'select'
  | 'datalist'
  | 'optgroup'
  | 'option'
  | 'textarea'
  | 'output'
  | 'progress'
  | 'meter'
  | 'fieldset'
  | 'legend'

  // 4.11 Interactive elements
  | 'details'
  | 'summary'
  | 'dialog'

  // 4.12 Scripting
  | 'script'
  | 'noscript'
  | 'template'
  | 'slot'
  | 'canvas'
  | 'template'

  // SVG extensions
  | 'animate'
  | 'animateMotion'
  | 'animateTransform'
  | 'circle'
  | 'clipPath'
  | 'defs'
  | 'desc'
  | 'ellipse'
  | 'feBlend'
  | 'feColorMatrix'
  | 'feComponentTransfer'
  | 'feComposite'
  | 'feConvolveMatrix'
  | 'feDiffuseLighting'
  | 'feDisplacementMap'
  | 'feDistantLight'
  | 'feDropShadow'
  | 'feFlood'
  | 'feFuncA'
  | 'feFuncB'
  | 'feFuncG'
  | 'feFuncR'
  | 'feGaussianBlur'
  | 'feImage'
  | 'feMerge'
  | 'feMergeNode'
  | 'feMorphology'
  | 'feOffset'
  | 'fePointLight'
  | 'feSpecularLighting'
  | 'feSpotLight'
  | 'feTile'
  | 'feTurbulence'
  | 'filter'
  | 'foreignObject'
  | 'g'
  | 'image'
  | 'line'
  | 'linearGradient'
  | 'marker'
  | 'mask'
  | 'metadata'
  | 'mpath'
  | 'path'
  | 'pattern'
  | 'polygon'
  | 'polyline'
  | 'radialGradient'
  | 'rect'
  | 'set'
  | 'stop'
  | 'switch'
  | 'symbol'
  | 'text'
  | 'textPath'
  | 'tspan'
  | 'use'
  | 'view';

type VirtualAncestorList = VirtualElement[];

/**
 * 6.4 Translatable Attributes
 * The HTML specification states that other specifications can define
 * translatable attributes. The language and directionality of each attribute
 * value is the same as the language and directionality of the element.
 *
 * To be understandable by assistive technology users, the values of the
 * following states and properties are translatable attributes and should be
 * translated when a page is localized:
 * @see https://www.w3.org/TR/wai-aria-1.3/#translatable-attributes
 */
type TranslatableAttributes = 'aria-label' | 'aria-placeholder' | 'aria-roledescription' | 'aria-valuetext';

/**
 * 6.5 Global States and Properties
 * Some states and properties are applicable to all host language elements
 * regardless of whether a role is applied. The following global states and
 * properties are supported by all roles and by all base markup elements unless
 * otherwise prohibited. If a role prohibits use of any global states or
 * properties, those states or properties are listed as prohibited in the
 * characteristics table included in the section that defines the role.
 * @see https://www.w3.org/TR/wai-aria-1.3/#global_states
 */
type GlobalAttribute =
  | 'aria-atomic'
  | 'aria-braillelabel'
  | 'aria-brailleroledescription'
  | 'aria-busy'
  | 'aria-controls'
  | 'aria-current'
  | 'aria-describedby'
  | 'aria-description'
  | 'aria-details'
  // | 'aria-disabled' // @deprecated for global use in ARIA 1.2
  | 'aria-dropeffect'
  // | 'aria-errormessage' // @deprecated for global use in ARIA 1.2
  | 'aria-flowto'
  | 'aria-grabbed'
  // | 'aria-haspopup' // @deprecated for global use in ARIA 1.2
  | 'aria-hidden'
  // | 'aria-invalid' // @deprecated for global use in ARIA 1.2
  | 'aria-keyshortcuts'
  | 'aria-label'
  | 'aria-labelledby'
  | 'aria-live'
  | 'aria-owns'
  | 'aria-relevant'
  | 'aria-roledescription';

/**
 * 6.6.1 Widget Attributes
 * This section contains attributes specific to common user interface elements
 * found on GUI systems or in rich internet applications which receive user
 * input and process user actions. These attributes are used to support the
 * widget roles.
 * @see https://www.w3.org/TR/wai-aria-1.3/#attrs_widgets
 */
type WidgetAttribute =
  | 'aria-autocomplete'
  | 'aria-checked'
  | 'aria-disabled'
  | 'aria-errormessage'
  | 'aria-expanded'
  | 'aria-haspopup'
  | 'aria-hidden'
  | 'aria-invalid'
  | 'aria-label'
  | 'aria-level'
  | 'aria-modal'
  | 'aria-multiline'
  | 'aria-multiselectable'
  | 'aria-orientation'
  | 'aria-placeholder'
  | 'aria-pressed'
  | 'aria-readonly'
  | 'aria-required'
  | 'aria-selected'
  | 'aria-sort'
  | 'aria-valuemax'
  | 'aria-valuemin'
  | 'aria-valuenow'
  | 'aria-valuetext';

/**
 * 6.6.2 Live Region Attributes
 * This section contains attributes specific to live regions in rich internet
 * applications. These attributes MAY be applied to any element. The purpose
 * of these attributes is to indicate that content changes might occur without
 * the element having focus, and to provide assistive technologies with
 * information on how to process those content updates. Some roles specify a
 * default value for the aria-live attribute specific to that role. An example
 * of a live region is a ticker section that lists updating stock quotes. User
 * agents MAY ignore changes triggered by direct user action on an element
 * inside a live region (e.g., editing the value of a text field).
 * @see https://www.w3.org/TR/wai-aria-1.3/#attrs_liveregions
 */
type LiveRegionAttribute = 'aria-atomic' | 'aria-busy' | 'aria-live' | 'aria-relevant';

/**
 * 6.6.3 Drag-and-Drop Attributes
 * This section lists attributes which indicate information about drag-and-drop
 * interface elements, such as draggable elements and their drop targets. Drop
 * target information will be rendered visually by the author and provided to
 * assistive technologies through an alternate modality.
 * @see https://www.w3.org/TR/wai-aria-1.3/#attrs_dragdrop
 */
type DragAndDropAttribute = 'aria-dropeffect' | 'aria-grabbed';

/**
 * 6.6.4 Relationship Attributes
 * This section lists attributes that indicate relationships or associations
 * between elements which cannot be readily determined from the document
 * structure.
 * @see https://www.w3.org/TR/wai-aria-1.3/#attrs_relationships
 */
type RelationshipAttribute =
  | 'aria-activedescendant'
  | 'aria-colcount'
  | 'aria-colindex'
  | 'aria-colindextext'
  | 'aria-colspan'
  | 'aria-controls'
  | 'aria-describedby'
  | 'aria-details'
  | 'aria-errormessage'
  | 'aria-flowto'
  | 'aria-labelledby'
  | 'aria-owns'
  | 'aria-posinset'
  | 'aria-rowcount'
  | 'aria-rowindex'
  | 'aria-rowindextext'
  | 'aria-rowspan'
  | 'aria-setsize';

type ARIAAttribute =
  | GlobalAttribute
  | WidgetAttribute
  | LiveRegionAttribute
  | DragAndDropAttribute
  | RelationshipAttribute;

type AttributeCategory = 'global' | 'widget' | 'liveregion' | 'draganddrop' | 'relationship';
type NameProhibitedAttributes =
  | 'aria-braillelabel'
  | 'aria-brailleroledescription'
  | 'aria-label'
  | 'aria-labelledby'
  | 'aria-roledescription';
/** Value representing either `true` or `false`. The default value for this value type is `false` unless otherwise specified. */
type TrueFalseAttribute = { type: 'true/false'; default: boolean; values?: never };
/** Value representing `true`, `false`, `mixed`, or `undefined` values. The default value for this value type is `undefined` unless otherwise specified. */
type TristateAttribute = { type: 'tristate'; default: string | undefined; values?: never };
/**
 * Value representing `true`, `false`, or `undefined` (not applicable). The default
 * value for this value type is `undefined` unless otherwise specified. For
 * example, an element with aria-expanded set to `false` is not currently
 * expanded; an element with aria-expanded set to `undefined` is not expandable.
 */
type TrueFalseUndefinedAttribute = { type: 'true/false/undefined'; default: undefined; values?: never };
/** Reference to the ID of another element in the same document */
type IDRefAttribute = { type: 'idRef'; default?: never; values?: never };
/** A list of one or more ID references. */
type IDRefListAttribute = { type: 'idRefList'; default?: never; values?: never };
/** A numerical value without a fractional component. */
type IntegerAttribute = { type: 'integer'; default?: never; values?: never };
/** Any real numerical value. */
type NumberAttribute = { type: 'number'; default?: never; values?: never };
/** Unconstrained value type. */
type StringAttribute = { type: 'string'; default?: never; values?: never };
/** One of a limited set of allowed values. The default value is defined in each attribute's Values table, as specified in the Attribute Values section. */
type TokenAttribute = { type: 'token'; default: string | undefined; values: string[] };
/** A list of one or more tokens. */
type TokenListAttribute = { type: 'tokenList'; default: string | undefined; values: string[] };

type AttributeData = { category: AttributeCategory[] } & (
  | TrueFalseAttribute
  | TristateAttribute
  | TrueFalseUndefinedAttribute
  | IDRefAttribute
  | IDRefListAttribute
  | IntegerAttribute
  | NumberAttribute
  | StringAttribute
  | TokenAttribute
  | TokenListAttribute
);

/**
 * 5.3.1 Abstract Roles
 * The following roles are used to support the WAI-ARIA Roles Model for the
 * purpose of defining general role concepts.
 *
 * Abstract roles are used for the ontology. Authors MUST NOT use abstract roles in content.
 * @see https://www.w3.org/TR/wai-aria-1.2/#abstract_roles
 * @deprecated Abstract roles should NOT be used, and are included only for completeness.
 */
type AbstractRole =
  | 'command'
  | 'composite'
  | 'input'
  | 'landmark'
  | 'range'
  | 'roletype'
  | 'section'
  | 'sectionhead'
  | 'select'
  | 'structure'
  | 'widget'
  | 'window';

/**
 * 5.3.2 Widget Roles
 * The following roles act as standalone user interface widgets or as part of
 * larger, composite widgets.
 * @see https://www.w3.org/TR/wai-aria-1.2/#widget_roles
 */
type WidgetRole =
  | 'button'
  | 'checkbox'
  | 'gridcell'
  | 'link'
  | 'menuitem'
  | 'menuitemcheckbox'
  | 'menuitemradio'
  | 'option'
  | 'progressbar'
  | 'radio'
  | 'row' // (when in a treegrid)
  | 'scrollbar'
  | 'searchbox'
  | 'separator' // (when focusable)
  | 'slider'
  | 'spinbutton'
  | 'switch'
  | 'tab'
  | 'tabpanel'
  | 'textbox'
  | 'treeitem'

  // Composite widgets
  | 'combobox'
  | 'grid'
  | 'listbox'
  | 'menu'
  | 'menubar'
  | 'radiogroup'
  | 'tablist'
  | 'tree'
  | 'treegrid';

/**
 * 5.3.3 Document Structure Roles
 * The following roles describe structures that organize content in a page.
 * Document structures are not usually interactive.
 * @see https://www.w3.org/TR/wai-aria-1.2/#document_structure_roles
 */
type DocumentStructureRole =
  | 'application'
  | 'article'
  | 'blockquote'
  | 'caption'
  | 'cell'
  | 'code'
  | 'columnheader'
  | 'comment'
  | 'definition'
  | 'deletion'
  | 'directory'
  | 'document'
  | 'emphasis'
  | 'feed'
  | 'figure'
  | 'generic'
  | 'group'
  | 'heading'
  | 'img'
  | 'image' // alias of "img"
  | 'insertion'
  | 'list'
  | 'listitem'
  | 'mark'
  | 'math'
  | 'meter'
  | 'none'
  | 'note'
  | 'paragraph'
  | 'presentation'
  | 'row'
  | 'rowgroup'
  | 'rowheader'
  | 'sectionheader'
  | 'sectionfooter'
  | 'separator' // (when NOT focusable)
  | 'strong'
  | 'subscript'
  | 'suggestion'
  | 'superscript'
  | 'table'
  | 'term'
  | 'time'
  | 'toolbar'
  | 'tooltip';

/**
 * 5.3.4 Landmark Roles
 * The following roles are regions of the page intended as navigational
 * landmarks. All of these roles inherit from the landmark base type and all
 * are imported from the Role Attribute [ROLE-ATTRIBUTE]. The roles are
 * included here in order to make them clearly part of the WAI-ARIA Roles
 * Model.
 * @see https://www.w3.org/TR/wai-aria-1.2/#landmark_roles
 */
type LandmarkRole =
  | 'banner'
  | 'complementary'
  | 'contentinfo'
  | 'form'
  | 'main'
  | 'navigation'
  | 'region'
  | 'search';

/**
 * 5.3.5 Live Region Roles
 * The following roles are live regions and may be modified by live region
 * attributes.
 * @see https://www.w3.org/TR/wai-aria-1.2/#live_region_roles
 */
type LiveRegionRole = 'alert' | 'log' | 'marquee' | 'status' | 'timer';

/**
 * 5.3.6 Window Roles
 * The following roles act as windows within the browser or application.
 * @see https://www.w3.org/TR/wai-aria-1.2/#window_roles
 */
type WindowRole = 'alertdialog' | 'dialog';

/**
 * Graphics Roles extensions
 * @see https://www.w3.org/TR/graphics-aria-1.0/#roles
 */
type GraphicsRole = 'graphics-document' | 'graphics-object' | 'graphics-symbol';

/**
 * Digital Publishing Roles extensions
 * @see https://www.w3.org/TR/dpub-aria-1.1/#roles
 */
type DigitalPublishingRole =
  | 'doc-abstract'
  | 'doc-acknowledgments'
  | 'doc-afterword'
  | 'doc-appendix'
  | 'doc-backlink'
  | 'doc-biblioentry'
  | 'doc-bibliography'
  | 'doc-biblioref'
  | 'doc-chapter'
  | 'doc-colophon'
  | 'doc-conclusion'
  | 'doc-cover'
  | 'doc-cover'
  | 'doc-credit'
  | 'doc-credits'
  | 'doc-dedication'
  | 'doc-endnote'
  | 'doc-endnotes'
  | 'doc-epigraph'
  | 'doc-epilogue'
  | 'doc-errata'
  | 'doc-example'
  | 'doc-footnote'
  | 'doc-foreword'
  | 'doc-glossary'
  | 'doc-glossref'
  | 'doc-index'
  | 'doc-introduction'
  | 'doc-noteref'
  | 'doc-notice'
  | 'doc-pagebreak'
  | 'doc-pagefooter'
  | 'doc-pageheader'
  | 'doc-pagelist'
  | 'doc-part'
  | 'doc-preface'
  | 'doc-prologue'
  | 'doc-pullquote'
  | 'doc-qna'
  | 'doc-subtitle'
  | 'doc-tip'
  | 'doc-toc';

type ARIARole =
  | WidgetRole
  | DocumentStructureRole
  | LandmarkRole
  | LiveRegionRole
  | WindowRole
  | GraphicsRole
  | DigitalPublishingRole;

/** Useful in places where the DOM isn’t available, e.g. SSR */
interface VirtualElement {
  tagName: TagName;
  attributes?: Record<string, string | number | boolean | null | undefined>;
}

/** Common options */
interface Options {
    /**
     * Important: Each node in the subtree is consulted only once. If text has
     * been collected from a descendant, but is referenced by another IDREF in
     * some descendant node, then that second, or subsequent, reference is not
     * followed. This is done to avoid infinite loops.
     * @see https://www.w3.org/TR/accname-1.2/#computation-steps
     */
    nodesReferenced: Set<Element | VirtualElement>;
}
/**
 * Get [acc]essible name & description.
 * Per spec, a missing name is represented as an empty string ("").  Name and
 * description must be calculated together, to ensure descriptions are not
 * redundant.
 *
 * @see https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation
 */
declare function getAccNameAndDescription(element: Element | VirtualElement, { nodesReferenced }?: Options): {
    name: string;
    description: string | undefined;
};

/**
 * Return the representation(s) of a role in HTML, if any.
 */
declare function getElements(role: ARIARole): VirtualElement[] | undefined;

/** Given an HTML element, returns a list of required aria-* attributes for that element */
declare function getRequiredAttributes(role: ARIARole): ARIAAttribute[];
/** Helper function for getRequiredttributes that returns a boolean instead */
declare function isRequiredAttribute(attribute: string, role: ARIARole): boolean;

type RoleType = 'abstract' | 'widget' | 'document' | 'landmark' | 'liveregion' | 'window' | 'graphics' | 'digitalpublishing';
interface RoleData {
    /**
     * A list of roles which are allowed on an accessibility child (simplified as "child") of the element with this role.
     * @see https://w3c.github.io/aria/#mustContain
     */
    allowedChildRoles: ARIARole[];
    /**
     * The DOM descendants are presentational.
     * @see https://w3c.github.io/aria/#childrenArePresentational
     */
    childrenPresentational: boolean;
    /**
     * Default values for role supported ARIA attributes (if any)
     * @see https://www.w3.org/TR/wai-aria-1.3/#implictValueForRole
     *
     * OR
     *
     * Fallback values for role required ARIA attributes (if any)
     * @see https://www.w3.org/TR/wai-aria-1.3/#document-handling_author-errors_states-properties
     *
     * ARIA attribute defaults independent of role constraints are not exposed here.
     */
    defaultAttributeValues: Record<string, boolean | number | string>;
    /** Which HTML elements inherit this role, if any (note: attributes may be necessary) */
    elements: VirtualElement[];
    name: ARIARole;
    /**
     * @see https://w3c.github.io/aria/#namefromauthor
     * @see https://w3c.github.io/aria/#namefromcontent
     * @see https://w3c.github.io/aria/#namefromprohibited
     */
    nameFrom: 'author' | 'authorAndContents' | 'contents' | 'prohibited';
    /** Role that require an accessible name. */
    nameRequired: boolean;
    /**
     * aria-* attributes that are explicitly prohibited for this role, and are considered an error if set.
     * @see https://www.w3.org/TR/wai-aria-1.3/#prohibitedattributes
     */
    prohibited: ARIAAttribute[];
    /**
     * If given, states that this role can only exist within this container
     * @see https://www.w3.org/TR/wai-aria-1.3/#scope
     */
    requiredParentRoles: ARIARole[];
    /**
     * aria-* attributes that MUST be set for this role.
     * @see https://www.w3.org/TR/wai-aria-1.3/#requiredState
     */
    required: ARIAAttribute[];
    superclasses: (ARIARole | AbstractRole)[];
    subclasses: (ARIARole | AbstractRole)[];
    /**
     * aria-* attributes that MAY be set for this role.
     * Note: this includes required attributes, supported attributes, and inherited attributes from superclass role types.
     * @see https://www.w3.org/TR/wai-aria-1.3/#supportedState
     * @see https://www.w3.org/TR/wai-aria-1.3/#inheritedattributes
     */
    supported: ARIAAttribute[];
    type: RoleType[];
}
declare const widgetRoles: Record<WidgetRole, RoleData>;
declare const documentRoles: Record<DocumentStructureRole, RoleData>;
declare const landmarkRoles: Record<LandmarkRole, RoleData>;
declare const liveRegionRoles: Record<LiveRegionRole, RoleData>;
declare const windowRoles: Record<WindowRole, RoleData>;
declare const graphicsRoles: Record<GraphicsRole, RoleData>;
declare const digitalPublishingRoles: Record<DigitalPublishingRole, RoleData>;
declare const roles: Record<ARIARole, RoleData>;
declare const ALL_ROLES: ARIARole[];
declare const NO_ROLES: ARIARole[];

interface GetRoleOptions {
    /**
     * Not needed in DOM environments.
     * For Node.js, when we can’t traverse the DOM, provide the hierarchy upward, going from closest to furthest.
     * E.g. the following HTML:
     *
     * ```html
     * <table>
     *   <tbody>
     *     <tr>
     *       <td></td>
     *     </tr>
     *   </tbody>
     * </table>
     * ```
     * Could be represented as:
     *
     * ```ts
     * getRole(
     *   { tagName: 'td' },
     *   { ancestors: [{ tagName: 'tr' }, { tagName: 'tbody' }, { tagName: 'table' }] },
     * );
     * ```
     *
     * Note: This list does _not_ have to be complete; simply listing out the significant elements that
     * affect a11y.
     * @see https://github.com/drwpow/html-aria/tree/dom-support#nodejs-vs-dom-behavior
     */
    ancestors?: VirtualAncestorList;
    /** Ignore role attribute in calculation to get the intrinsic role. Needed in some fallback scenarios. */
    ignoreRoleAttribute?: boolean;
}
/**
 * Get the corresponding ARIA role for a given HTML element.
 * `undefined` means “no corresponding role”.
 * This traverses the DOM when available.
 * @see https://www.w3.org/TR/html-aria/
 */
declare function getRole(element: Element | VirtualElement, options?: GetRoleOptions): RoleData | undefined;

/**
 * Given an ARIA role returns a list of supported/inherited aria-* attributes.
 */
declare function getSupportedAttributes(element: Element | VirtualElement, options?: GetRoleOptions): ARIAAttribute[];
/**
 * Helper function for getSupportedAttributes that returns a boolean instead
 */
declare function isSupportedAttribute(attribute: ARIAAttribute, element: Element | VirtualElement, options?: GetRoleOptions): boolean;
/**
 * Given an ARIA attribute, is the following value valid? Note that for most
 * non-enum attributes, this will probably return true.
 *
 * - `undefined` and `null` return false, as they are non-values.
 * - Numbers will be coerced into strings, and will return true for most non-enum attributes (this library isn’t concerned with number validation).
 */
declare function isValidAttributeValue(attribute: ARIAAttribute, value: unknown): boolean;

interface SupportedRoleOptions {
    /**
     * Much like getRole(), the ancestors determines the intrinsic role. But ancestors
     * also determine _valid_ roles—certain roles MUST NOT contain certain children.
     * For example:
     *
     * - <td> with ancestors ['table'] MAY ONLY be a ['cell'] (all other roles are not supported)
     * - <td> with ancestors ['grid'] or ['treegrid'] MAY ONLY be a ['gridcell'] (all other roles are not supported)
     * - <td> with NO ancestors ([]) will allow any role
     */
    ancestors?: VirtualAncestorList;
}
/**
 * Given an HTML element, returns a list of supported ARIA roles for that element.
 * An empty array means no roles are supported (which is true for some elements!)
 */
declare function getSupportedRoles(element: Element | VirtualElement, options?: SupportedRoleOptions): ARIARole[];
/** Helper function for getSupportedRoles that returns a boolean instead */
declare function isSupportedRole(role: string, element: Element | VirtualElement, options?: SupportedRoleOptions): boolean;

/** Given HTML, can this element be interacted with? */
declare function isInteractive(element: Element | VirtualElement, options?: GetRoleOptions): boolean;

/**
 * Given an ARIA role, return whether or not an accessible name is required.
 * @see https://www.w3.org/TR/wai-aria-1.3/#namecalculation
 */
declare function isNameRequired(role: ARIARole): boolean;

declare const globalAttributes: Record<GlobalAttribute, AttributeData>;
declare const widgetAttributes: Record<WidgetAttribute, AttributeData>;
declare const liveregionAttributes: Record<LiveRegionAttribute, AttributeData>;
declare const draganddropAttributes: Record<DragAndDropAttribute, AttributeData>;
declare const relationshipAttributes: Record<RelationshipAttribute, AttributeData>;
declare const attributes: Record<ARIAAttribute, AttributeData>;
declare const ALL_ATTRIBUTES: ARIAAttribute[];
declare const NO_ATTRIBUTES: ARIAAttribute[];

declare const NO_CORRESPONDING_ROLE: undefined;
interface TagInfo {
    /**
     * Note: this is very likely to be overridden by custom logic! This won’t even
     * apply for half of elements since they are influenced by attribute and
     * Accessibility Tree ancestors.
     */
    defaultRole: ARIARole | undefined;
    /**
     * ⚠️ This is the default set of allowed roles. Many elements have special conditioning
     * that narrow the allowed roles, that’s not easily serializable. That logic can be found
     * in getSupportedRoles().
     */
    supportedRoles: ARIARole[];
    /**
     * If this conflicts with the role’s allowed attributes, this takes precedence.
     */
    supportedAttributesOverride: ARIAAttribute[] | undefined;
    /**
     * If this element doesn’t allow aria-label and related attributes by
     * default (Note: if a `role` is specified, this is ignored!)
     */
    namingProhibited: boolean;
}
declare const tags: Record<TagName, TagInfo>;

/** Parse a list of roles, e.g. role="graphics-symbol img" */
declare function parseTokenList(tokenList: string): string[];
/**
 * Get the first matching value in a tokenlist
 *
 * Note: according to the spec, `role` can not only be a list of
 * spring-separated values; it can contain fallbacks the browser may not
 * understand. According to spec, an arbitrary role is to be ignored, so we take
 * the first match (if any), or `undefined`.
 * @see
 */
declare function firstMatchingToken<T>(tokenList: string, validValues: T[]): T | undefined;
declare function getTagName(element: Element | VirtualElement): TagName;
/**
 * Get attribute from any type of element. Optimized for performance.
 */
declare function attr(element: Element | VirtualElement, attribute: string): string | null;
declare const NAME_PROHIBITED_ATTRIBUTES: Set<string>;
/** Logic shared by <header> and <footer> when determining role */
declare function hasLandmarkParent(element: Element | VirtualElement, ancestors?: VirtualAncestorList): boolean;
declare function hasListParent(element: Element | VirtualElement, ancestors?: VirtualAncestorList): boolean;
/** Logic shared by <td> and <th> when determining role */
declare function hasGridParent(element: Element | VirtualElement, ancestors?: VirtualAncestorList): boolean;
interface RemoveProhibitedOptions<P extends ARIAAttribute[]> {
    nameProhibited?: boolean;
    prohibited?: P;
}
declare function hasTableParent(element: Element | VirtualElement, ancestors?: VirtualAncestorList): boolean;
/**
 * Has sectioning content parent
 * @see https://html.spec.whatwg.org/multipage/dom.html#sectioning-content
 */
declare function hasSectioningContentParent(element: Element | VirtualElement, ancestors?: VirtualAncestorList): boolean;
/** Remove prohibited aria-* attributes from a list */
declare function removeProhibited<T extends ARIAAttribute[], P extends ARIAAttribute[]>(attributeList: T, options?: RemoveProhibitedOptions<P>): Exclude<T, keyof P>;
/** Inject new items into an array */
declare function concatDedupeAndSort<T extends string>(list: T[], newItems: T[]): T[];
/** Is this element disabled? */
declare function isDisabled(element: Element | VirtualElement): boolean;
/**
 * Is a given element hidden?
 * @see https://w3c.github.io/accname/#dfn-hidden
 */
declare function isHidden(element: Element | VirtualElement): boolean;
/** Get CSS `content` */
declare function getCSSContent(element: Element | VirtualElement, pseudoElt?: '::before' | '::after' | '::marker'): string | undefined;
/** Get calculated `display` property */
declare function getDisplay(element: Element, pseudoElt?: string | null): string;
/** Get tooltip content */
declare function getTooltip(element: Element | VirtualElement): string;

export { ALL_ATTRIBUTES, ALL_ROLES, NAME_PROHIBITED_ATTRIBUTES, NO_ATTRIBUTES, NO_CORRESPONDING_ROLE, NO_ROLES, attr, attributes, concatDedupeAndSort, digitalPublishingRoles, documentRoles, draganddropAttributes, firstMatchingToken, getAccNameAndDescription, getCSSContent, getDisplay, getElements, getRequiredAttributes, getRole, getSupportedAttributes, getSupportedRoles, getTagName, getTooltip, globalAttributes, graphicsRoles, hasGridParent, hasLandmarkParent, hasListParent, hasSectioningContentParent, hasTableParent, isDisabled, isHidden, isInteractive, isNameRequired, isRequiredAttribute, isSupportedAttribute, isSupportedRole, isValidAttributeValue, landmarkRoles, liveRegionRoles, liveregionAttributes, parseTokenList, relationshipAttributes, removeProhibited, roles, tags, widgetAttributes, widgetRoles, windowRoles };
export type { ARIAAttribute, ARIARole, AbstractRole, AttributeCategory, AttributeData, DigitalPublishingRole, DocumentStructureRole, DragAndDropAttribute, GetRoleOptions, GlobalAttribute, GraphicsRole, IDRefAttribute, IDRefListAttribute, IntegerAttribute, LandmarkRole, LiveRegionAttribute, LiveRegionRole, NameProhibitedAttributes, NumberAttribute, RelationshipAttribute, RemoveProhibitedOptions, RoleData, RoleType, StringAttribute, SupportedRoleOptions, TagInfo, TagName, TokenAttribute, TokenListAttribute, TranslatableAttributes, TristateAttribute, TrueFalseAttribute, TrueFalseUndefinedAttribute, VirtualAncestorList, VirtualElement, WidgetAttribute, WidgetRole, WindowRole };