Greatsword

1. Introduction

This is a diff spec against Selectors Level 4.

1.1. Module Interactions

This module extends the set of selectors defined for CSS in [selectors-4].

2. Location Pseudo-classes

2.1. The Local Link Pseudo-class :local-link

The :local-link pseudo-class allows authors to style hyperlinks based on the users current location within a site and to differentiate site-internal versus site-external links.

The (non-functional) :local-link pseudo-class represents an element that is the source anchor of a hyperlink whose target’s absolute URL matches the element’s own document URL. Any fragment identifiers are stripped before matching the document’s URL against the link’s URL; otherwise all portions of the URL are considered.

For example, the following rule prevents links targeting the current page from being underlined when they are part of the navigation list:

nav :local-link { text-decoration: none; }

As a functional pseudo-class, :local-link() can also accept a non-negative integer as its sole argument, which, if the document’s URL belongs to a hierarchical scheme, indicates the number of path levels to match:

:local-link(0) represents a link element whose target is in the same origin as the document’s URL
:local-link(1) represents a link element whose target has the same origin and first path segment
:local-link(2) represents a link element whose target has the same origin, first, and second path segments
etc.

The following example styles all site-external links with a dashed underline.

:not(:local-link(0)) { text-decoration-style: dashed; }

Path segments are portions of the URL’s path that are separated by forward slashes (/). If a segment is missing from the document’s URL, a pseudo-class requiring that segment to match does not match anything.

So, given the links:

<a href="http://www.example.com">Home</a>
<a href="http://www.example.com/2011">2011</a>
<a href="http://www.example.com/2011/03">March</a>
<a href="http://www.example.com/2011/03/">March</a>
<a href="http://www.example.com/2011/03/21">21 March</a>
<a href="https://www.example.com/2011/03/">March</a>
<a href="http://example.com/2011/03/">March</a>

and the styles:

a:local-link {...}
a:local-link(0) {...}
a:local-link(1) {...}
a:local-link(2) {...}
a:local-link(3) {...}
a:local-link(4) {...}

If the document’s URL is http://www.example.com/2011/03/:

Link 1 would receive Style B
Link 2 would receive Styles B and C
Link 3 would receive Styles B, C, and D
Link 4 would also receive Styles A, B, C, D, and E
Link 5 would receive Styles B, C, and D
Link 6 would remain unstyled
Link 7 would remain unstyled
Style F would not be applied to anything

The "origin" of the URL is defined by RFC 6454, Section 4. The username, password, query string, and fragment portions of the URL are not considered when matching against :local-link(n). If the document’s URL does not belong to a hierarchical scheme, the functional pseudo-class matches nothing.

It’s clear that, if the document URL has at least N segments, then :local-link(N) only matches links whose URL has at least N segments. (This lets you assign consistent semantics to :local-link so that, for example, :local-link(2) means a "within-repo" link on GitHub.) What about if the document url has less than N segments, and the link is same-page? Should "null segments" count as matching, or not?

3. User Action Pseudo-classes

3.1. The Interest Pseudo-classes: :interest-source and :interest-target

A common UI feature is the ability for the user to "show interest" in certain elements (an interest source), and the UI to respond to that interest by showing additional information in another element (the interest target), typically a popup. For example, hovering a username on a page might bring up an information card for that user; or long-pressing a link might bring up a preview of the link’s destination. Whenever this happens, the first element

Note: Exactly what elements are capable of being interest sources, how they’re linked to interest targets, and how "interest" is shown are all host language-defined. In HTML, for example, this is done with the interestfor attribute to indicate an element capable of "showing interest" (being an interest source, and that attribute points to another element intended to show the additional information (the associated interest target) (usually a popover element).

The :interest-source pseudo-class applies to an interest source element that the user is currently "showing interest" in, and the :interest-target pseudo-class applies to the associated interest target of an element matching :interest-source.

Note: :interest-source only matches an interest source the user is currently interested in, not any element that can potentially have interest shown in it. In HTML, for example, just having the interestfor attribute does not make an element match this pseudo-class; the user has to actually indicate interest in it too. Similarly, :interest-target only matches an interest target that is linked to an element the user is currently interested in, not any element pointed to by an interestfor attribute.

4. The Input Pseudo-classes

4.1. Input Value-checking

4.1.1. The Empty-Value Pseudo-class: :blank

The :blank pseudo-class applies to user-input elements whose input value is empty (consists of the empty string or otherwise null input).

Roughly speaking, if a human looked at a printout of the form and would say it’s blank, it matches :blank.

A rule of thumb for interpreting :blank on form controls is:

If the control always submits, and would do so with an empty string, it matches :blank. (Such as HTML’s <input type=text> when its value is empty.)
If it sometimes submits, and is set to not submit, it matches :blank. (Such as HTML’s <input type=checkbox> when not checked.)
If it’s an “action button” (rather than a “toggle button” that represents a state) such as <button>, <input type=submit>, etc., it never matches :blank.

Host languages can specify more precise rules for when form controls match :blank.

5. Time-dimensional Pseudo-classes

These pseudo-classes classify elements with respect to the currently-displayed or active position in some timeline, such as during speech rendering of a document, or during the display of a video using WebVTT to render subtitles.

CSS does not define this timeline; the host language must do so. If there is no timeline defined for an element, these pseudo-classes must not match the element.

Note: Ancestors of a :current element are also :current, but ancestors of a :past or :future element are not necessarily :past or :future as well. A given element matches at most one of :current, :past, or :future.

5.1. The Current-element Pseudo-class: :current

The :current pseudo-class represents the element, or an ancestor of the element, that is currently being displayed.

Its alternate form :current() takes a list of compound selectors as its argument: it represents the :current element that matches the argument or, if that does not match, the innermost ancestor of the :current element that does. (If neither the :current element nor its ancestors match the argument, then the selector does not represent anything.)

For example, the following rule will highlight whichever paragraph or list item is being read aloud in a speech rendering of the document:

:current(p, li, dt, dd) {
  background: yellow;
}

5.2. The Past-element Pseudo-class: :past

The :past pseudo-class represents any element that is defined to occur entirely prior to a :current element. For example, the WebVTT spec defines the :past pseudo-class relative to the current playback position of a media element. If a time-based order of elements is not defined by the document language, then this represents any element that is a (possibly indirect) previous sibling of a :current element.

5.3. The Future-element Pseudo-class: :future

The :future pseudo-class represents any element that is defined to occur entirely after a :current element. For example, the WebVTT spec defines the :future pseudo-class relative to the current playback position of a media element. If a time-based order of elements is not defined by the document language, then this represents any element that is a (possibly indirect) next sibling of a :current element.

6. Exposing custom state: the :state() pseudo-class

The :state( <ident> ) pseudo-class matches custom elements whose states set contains a string that is the selector’s argument’s value.

Tests

parse-state.html (live test) (source)

Note: The "is" matching behavior compares strings by codepoint; notably, it’s case-sensitive. So if "foo" is in the states set, :state(FOO) will not match.

The exact matching behavior of :state() pseudo-class is defined by the host language. For clarity, the concepts explaining this pseudo-class link to the HTML definition; see HTML’s definition for more detail. Other host languages must define how this pseudo-class matches.

7. Heading Structures: the heading pseudo-classes :heading, and :heading()

The (non-functional) :heading pseudo-class matches an element which has a heading level, with respect to the semantics defined by the document language (e.g. [HTML5]).

The specificity of :heading is that of a class.

For example, the following sheet contains a rule applying to all heading elements in the current page:

:heading { text-decoration: underline; }

As a functional pseudo-class, :heading() notation represents elements that have a heading level among matching any of the provided integer values. The syntax is:

:heading() = :heading( <level># )

where <level> is a <number-token> with its type flag set to "integer".

The specificity of :heading() is that of a class.

The following example styles headings with levels between 1 and 3 with a font-weight of 900, while headings with levels 6 onward with font-weight of 500, additionally heading levels 1 and 2 will be underlined, while 3 and beyond will have no text-decoration:

:heading(1, 2, 3) { font-weight: 900; }

:heading(6, 7, 8, 9) { font-weight: 500; }

:heading(1, 2) { text-decoration: underline; }

:heading(3, 4, 5, 6, 7, 8, 9) { text-decoration: none; }

Note: The heading level might be different from an element’s type selector. Thus, a selector h1:heading(3) matches any h1 tag which has an exposed heading level of 3.

Tests

8. Grid-Structural Selectors

The double-association of a cell in a 2D grid (to its row and column) cannot be represented by parentage in a hierarchical markup language. Only one of those associations can be represented hierarchically: the other must be explicitly or implicitly defined in the document language semantics. In both HTML and DocBook, two of the most common hierarchical markup languages, the markup is row-primary (that is, the row associations are represented hierarchically); the columns must be implied. To be able to represent such implied column-based relationships, the column combinator and the :nth-col() and :nth-last-col() pseudo-classes are defined. In a column-primary format, these pseudo-classes match against row associations instead.

8.1. Column combinator (`||`)

The column combinator, which consists of two pipes (||) represents the relationship of a column element to a cell element belonging to the column it represents. Column membership is determined based on the semantics of the document language only: whether and how the elements are presented is not considered. If a cell element belongs to more than one column, it is represented by a selector indicating membership in any of those columns.

The following example makes cells C, E, and G gray.

col.selected || td {
  background: gray;
  color: white;
  font-weight: bold;
}

<table>
  <col span="2">
  <col class="selected">
  <tr><td>A <td>B <td>C
  <tr><td colspan="2">D <td>E
  <tr><td>F <td colspan="2">G
</table>

8.2. :nth-col() pseudo-class

The :nth-col(An+B) pseudo-class notation represents a cell element belonging to a column that has An+B-1 columns before it, for any positive integer or zero value of n. Column membership is determined based on the semantics of the document language only: whether and how the elements are presented is not considered. If a cell element belongs to more than one column, it is represented by a selector indicating any of those columns.

The CSS Syntax Module [CSS3SYN] defines the An+B notation.

8.3. :nth-last-col() pseudo-class

The :nth-last-col(An+B) pseudo-class notation represents a cell element belonging to a column that has An+B-1 columns after it, for any positive integer or zero value of n. Column membership is determined based on the semantics of the document language only: whether and how the elements are presented is not considered. If a cell element belongs to more than one column, it is represented by a selector indicating any of those columns.

The CSS Syntax Module [CSS3SYN] defines the An+B notation.

9. Combinators

9.1. Reference combinators `/ref/`

The reference combinator consists of two slashes with an intervening CSS qualified name, and separates two compound selectors, e.g. A /attr/ B. The element represented by the first compound selector explicitly references the element represented by the second compound selector. Unless the host language defines a different syntax for expressing this relationship, this relationship is considered to exist if the value of the specified attribute on the first element is an IDREF or an ID selector referencing the second element.

Attribute matching for reference combinators follow the same rules as for attribute selectors.

The following example highlights an input element when its <label> is focused or hovered-over:

label:is(:hover, :focus) /for/ input,       /* association by "for" attribute */
label:is(:hover, :focus):not([for]) input { /* association by containment */
  box-shadow: yellow 0 0 10px;
}

10. Changes

10.1. Changes Since Level 4

Additions since Level 4:

Reference combinators (deferred from an earlier draft of Selectors 4)
The functional form of the :local-link pseudo-class (deferred from an earlier draft of Selectors 4)
The :state() pseudo-class
The :heading and :heading() pseudo-classes
The :local-link pseudo-class (deferred from an earlier draft of Selectors 4)
The :interest-source and :interest-target pseudo-classes
The :blank pseudo-class (deferred from an earlier draft of Selectors 4)
The grid-structural (column) selectors (deferred from an earlier draft of Selectors 4)
The time-dimensional pseudo-classes (deferred from an earlier draft of Selectors 4)

11. Acknowledgements

The CSS working group would like to thank everyone who contributed to the previous Selectors specifications over the years, as those specifications formed the basis for this one. In particular, the working group would like to extend special thanks to the following for their specific contributions to Selectors Level 5: Joey Arhar.

Privacy Considerations

Should be copied from Level 4 when appropriate.

Security Considerations

Should be copied from Level 4 when appropriate.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the [email protected] mailing list.

Selectors Level 5

Abstract

Status of this document