@frontmeans/doqry

Document query notation for CSS selectors

Usage no npm install needed!

<script type="module">
  import frontmeansDoqry from 'https://cdn.skypack.dev/@frontmeans/doqry';
</script>

README

Document Query Notation

NPM Build Status Code Quality Coverage GitHub Project API Documentation

Structured CSS Selectors

Doqry represents CSS selectors as data structures rather than trying to parse selectors text.

Structured CSS selector is one of:

  • raw CSS selector text,
  • CSS selector part, or
  • an array consisting of strings, parts, and their combinators.

Raw CSS selector text is never interpreted and is used verbatim.

CSS combinator is one of: >, +, or ~.

CSS selector part is a structure representing selectors like element-name#id.class1.classN[attr1][attr2]:pseudo-class::pseudo-element. Each selector part is represented by corresponding property:

  • Element selector: { e: 'element-name' } for element-name.
  • Element selector in XML namespace: { ns: 'ns-prefix', e: 'element-name' } for ns-prefix | element-name.
  • Universal element selector: { e: '*' }, which is the same as {} for *.
  • Universal element selector in XML namespace: { ns: 'ns-prefix', e: '*' }, which is the same as { ns: 'ns-prefix' } for ns-prefix | *.
  • Element identifier: { i: 'element-id' } for #element-id.
  • Element class: { c: 'class-name' } for .class-name.
  • Multiple element classes: { c: ['class-1', 'class-2'] } for .class-1.class-2.
  • Attribute selector: { u: ['disabled'] } for [disabled], { u: ['lang', '|=', 'en'] } for [lang |= "en"].
  • Pseudo-element: { e: 'li', u: ['::', 'after'] } for li::after.
  • Pseudo-class: { u: [':', 'host', { c: 'active' }] } for :host(.active), { u: [':', 'is', [{ e: 'ul' }, '>', { e: 'li' }], [{ c: 'menu'}, { c: 'menu-item'}]] } for :is(ul > li, .menu > .menu-item)
  • Additional selectors: { e: 'a', s: '[href^=https://]:visited' } for a[href^=https://]:visited.
  • Raw CSS selector: { s: '.my-selector' } for .my-selector.

Selector part may combine multiple properties. Parts may be combined too. E.g. [{ e: 'ul', c: 'unstyled' }, '>', { e: 'li' }] corresponds to ul.unstyled > li CSS selector.

Qualifiers

CSS selector may include qualifiers. Qualifiers do not correspond to CSS selectors directly. Instead, they are used internally to classify selectors. E.g. they may represent at-rule selectors.

Qualifiers represented by $ property of structured CSS selector part, that may contain either one qualifier, or an array of qualifiers: { c: 'sr-only', $: '@media=screen' }.

Each qualifier is a string in the <name>[=<value>] format, where the <name> may be qualified and consist of multiple colon-separated parts like block:visibility:hidden.

The presence of q1:q2:q3=v qualifier means the same as presence of q1, q1:q2, q1:q2:q3, and q1:q2:q3=v qualifiers.

API

The following operations over structure CSS selectors supported:

  • doqryDisplayText(selector) - Converts selector to textual representation including qualifiers.
  • doqryEqual(first, second) - Checks whether the first selector equals to the second one.
  • doqryPicker(selector) - Normalizes selector representation and converts it to CSS picker.
  • doqryText(selector, format?) - Converts selector to textual representation in the given format. By default, converts to representation that can be used in CSS (i.e. without qualifiers).