I've been reading the CSS/selector specs lately. I'm interested both as a
framework implementer, designing and implementing jQuery-like functionality
for Meteor, and as an app developer who looks forward to the days when
browsers provide the APIs we want.
Coming into the new Selectors API, I was really hoping to discover that the
proposed find and findAll methods behaved essentially like the jQuery
calls. Put simply, in running elem.find(div p), both the div and the
p in question would have to be descendants of elem (as well as each
other) in order to match. In running elem.find( div p), there would be
the additional constraint that only immediate descendants of elem would be
considered as candidates for the div. Unfortunately, this didn't seem to
be the case... until I read the spec about a half dozen more times, and I
realized it was! If I'm reading it right, the spec does work this way and
is additionally much more flexible about the relationship between the
element, the scoping element (or elements), and the selector. From reading
the list archives, I get the feeling that few web developers who come
across the spec understand this much.
First of all, I want to offer some encouragement. The names find and
findAll are great, and their functionality is exactly what web developers
will expect and appreciate. It's familiar and practical. And as long as
in basic cases like element.find(a b c + d), it's required that all of a,
b, c, and d descend from the element, I am happy with whatever scope
selectors and edge cases are necessary or desirable.
However, the spec is very hard to understand. I've read several specs
cover-to-cover (Java VM, ECMAScript, JPEG) and I think there is a lot of
low-hanging fruit in this short document (Selectors API Level 2) -- ways to
improve its clarity and enlist your readers more in support of this spec.
Some feedback from a reader, for what it's worth.
6.2 - ... first matching Element node within the subtrees...
Don't define a new term subtrees which just means descendants. Say,
... first matching Element node that is a descendant of the context
object.
The main take-away from section 6.2 should be that find/findAll use a
*different algorithm* from querySelector/querySelectorAll, or the same
algorithm with a different setting (relative=true). This point is almost
entirely lost. I think the intent is for the reader to perform a sort of
dispatch on type when the algorithm in 6.5 is invoked, but it's confusing
because you can't really look at a selector and a relative selector and
tell them apart, and certainly not before parsing them. Isn't a relative
selector (string) just a selector (string) optionally preceded by a
combinator? It seems to me that find() and querySelector() *do different
things*, conceptually; for example, the former will add an implicit :scope
to your selector and the latter won't. It's nothing to do with their
arguments. Given the same arguments, they will do different things.
To make it concrete by analogy, how would you interpret this spec (or short
of that, how does it feel to read and try to understand)?
===
Definitions: Chairs are made of wood. Generalized Chairs are made of
wood, metal or plastic.
The VARNISH function accepts a chair.
The PAINT function accepts a generalized chair.
VARNISH must coat its input with transparent, Acme brand varnish.
PAINT must coat its input with liquid.
When either method is invoked, the implementation must perform Algorithm
Coat.
Algorithm Coat:
1) If the input is a wooden chair, coat it with varnish.
2) Otherwise, if the input is a generalized chair, coat it with paint whose
color matches the chair's referential color context.
===
Here are the stumbling blocks:
- If you try to simulate the algorithm, it's a head-scratcher. Aren't
wooden chairs also generalized chairs? How do we get to step 2 to paint a
wooden chair? Are we really supposed to varnish or paint based on whether
the chair is known-to-be-wood or merely incidentally-wood, or is painting
wooden chairs not possible?
- Presumably, painting was invented to support new chair materials and
achieve color-coordinated finishes, yet there is barely a functional
description of what PAINT does, let alone the intent. PAINT must coat its
input with liquid is the closest thing we have to a definition.
- We're describing these two functions along three axes, but the
information is so spread out that it is hard to integrate.
The ideal in clarity, which admittedly is not always possible with the need
to specify algorithms and share them between sections, is something like:
===
The VARNISH function accepts a chair and coats it with transparent, Acme
brand varnish.
The PAINT function accepts a generalized chair and coats it with paint
whose color matches the chair's referential color context.
===
That's a breath of fresh air.
However, there are many other options, like:
===
The VARNISH function accepts a chair as its argument.
The PAINT
