Skip to content

Commit 3d7faf3

Browse files
committed
fix: make case sensitivity flags mutually exclusive and document them
Address review feedback on #327: - `attr.insensitive` and `attr.sensitive` now clear each other, along with any capitalized notation held in raws, so a node can no longer claim both case sensitivities at once. This also fixes the pre-existing case where an `s` attribute could not be switched to `i` at all, because the stale `raws.insensitiveFlag` won during serialization. - Only the standard `i`/`I` and `s`/`S` notations are erased, so a non-standard flag preserved in `raws.insensitiveFlag` (e.g. `[a=b y]`) still round-trips. - Drop the redundant double assignment in both setters. - `offsetOf()` now accepts "sensitive". It previously returned -1 for an `s` flag, leaving that flag with no reachable offset. - Document both flags, their mutual exclusivity, the shared spaces slot and `raws.sensitiveFlag` in API.md.
1 parent 6166541 commit 3d7faf3

4 files changed

Lines changed: 169 additions & 13 deletions

File tree

‎API.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -618,6 +618,49 @@ Remains `undefined` if there is no attribute value.
618618

619619
Returns the attribute name qualified with the namespace if one is given.
620620

621+
### `attribute.insensitive` and `attribute.sensitive`
622+
623+
The two case sensitivity flags defined by
624+
[Selectors Level 4](https://www.w3.org/TR/selectors-4/#attribute-case):
625+
626+
* `attribute.insensitive` is `true` for the case insensitive flag, `[href="foo" i]`.
627+
* `attribute.sensitive` is `true` for the explicit case sensitive flag, `[href="foo" s]`.
628+
629+
Both remain `undefined` if the attribute carries no flag at all.
630+
631+
`attribute.insensitiveFlag` and `attribute.sensitiveFlag` are read-only and return
632+
the canonical lowercase flag (`"i"` / `"s"`) when the corresponding boolean is set,
633+
otherwise an empty string.
634+
635+
```css
636+
[href="foo"] /* insensitive: undefined, sensitive: undefined */
637+
[href="foo" i] /* insensitive: true, sensitive: false */
638+
[href="foo" s] /* insensitive: false, sensitive: true */
639+
```
640+
641+
A selector cannot request both case sensitivities at once, so the two properties
642+
are mutually exclusive: setting either one to `true` clears the other, along with
643+
any capitalized notation stored for it in
644+
[`attribute.raws`](#attributeraws).
645+
646+
```js
647+
let attr = parser().astSync('[href="foo" I]').first.first;
648+
attr.sensitive = true;
649+
attr.insensitive; // false
650+
attr.raws.insensitiveFlag; // undefined
651+
attr.toString(); // '[href="foo" s]'
652+
```
653+
654+
Because a flag can only ever appear in one place in the output, the two flags
655+
share a single slot. The whitespace and comments around either flag live in
656+
`attribute.spaces.insensitive` and `attribute.raws.spaces.insensitive`, and
657+
`attribute.offsetOf()` reports the position of that slot under whichever of
658+
`"insensitive"` or `"sensitive"` is actually present.
659+
660+
Non-standard flags are not modeled as booleans. They are preserved verbatim in
661+
`attribute.raws.insensitiveFlag` (see [`attribute.raws`](#attributeraws)) and are
662+
left untouched by both setters.
663+
621664
### `attribute.offsetOf(part)`
622665

623666
Returns the offset of the attribute part specified relative to the
@@ -637,6 +680,10 @@ Returns the attribute name qualified with the namespace if one is given.
637680
* `"operator"` - the match operator of the attribute
638681
* `"value"` - The value (string or identifier)
639682
* `"insensitive"` - the case insensitivity flag
683+
* `"sensitive"` - the explicit case sensitivity flag
684+
685+
The two case sensitivity flags share one slot in the output, so at most one of
686+
`"insensitive"` and `"sensitive"` resolves to an offset; the other returns `-1`.
640687

641688
### `attribute.raws.unquoted`
642689

@@ -675,6 +722,18 @@ or `value` then a property is placed in the raws for that value containing the f
675722
If a comment is embedded within the space between parts of the attribute
676723
then the raw for that space is set accordingly.
677724

725+
The case sensitivity flags are stored here when the source used a notation that
726+
does not round-trip from the boolean alone:
727+
728+
* `attribute.raws.insensitiveFlag` holds `"I"` for `[href="foo" I]`. It also holds
729+
any non-standard flag verbatim — `"y"` for `[href="foo" y]` — which is how such
730+
a flag survives serialization even though neither `attribute.insensitive` nor
731+
`attribute.sensitive` is `true`.
732+
* `attribute.raws.sensitiveFlag` holds `"S"` for `[href="foo" S]`.
733+
734+
The canonical lowercase forms are not stored, since `attribute.insensitive` and
735+
`attribute.sensitive` already render them.
736+
678737
Setting an attribute's property `raws` value to be deleted.
679738

680739
For now, changing the spaces required also updating or removing any of the

‎postcss-selector-parser.d.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -517,7 +517,7 @@ declare namespace parser {
517517
* @param part One of the possible values inside an attribute.
518518
* @returns -1 if the name is invalid or the value doesn't exist in this attribute.
519519
*/
520-
offsetOf(part: "ns" | "namespace" | "attribute" | "attributeNS" | "operator" | "value" | "insensitive"): number;
520+
offsetOf(part: "ns" | "namespace" | "attribute" | "attributeNS" | "operator" | "value" | "insensitive" | "sensitive"): number;
521521
}
522522
function attribute(opts: AttributeOptions): Attribute;
523523
function isAttribute(node: any): node is Attribute;

‎src/__tests__/attributes.mjs‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -496,9 +496,88 @@ test("case sensitive attribute selector", '[href="foo" s]', (t, tree) => {
496496
t.deepEqual(attr.insensitiveFlag, "");
497497
// The `s` flag must be modeled explicitly, not mis-filed into raws.insensitiveFlag.
498498
t.is(attr.raws.insensitiveFlag, undefined);
499+
// Both flags occupy the same slot, so only the one that is present resolves.
500+
t.deepEqual(attr.offsetOf("sensitive"), 12);
501+
t.deepEqual(attr.offsetOf("insensitive"), -1);
499502
t.deepEqual(tree.toString(), '[href="foo" s]');
500503
});
501504

505+
test("case insensitive attribute selector offset", '[href="foo" i]', (t, tree) => {
506+
let attr = tree.atPosition(1, 13);
507+
t.deepEqual(attr.offsetOf("insensitive"), 12);
508+
t.deepEqual(attr.offsetOf("sensitive"), -1);
509+
});
510+
511+
test("case sensitivity flags are mutually exclusive (i to s)", '[href="foo" i]', (t, tree) => {
512+
let attr = tree.atPosition(1, 13);
513+
t.deepEqual(attr.insensitive, true);
514+
515+
attr.sensitive = true;
516+
517+
// `[href="foo" i s]` is not valid CSS, so adopting one flag drops the other.
518+
t.deepEqual(attr.sensitive, true);
519+
t.deepEqual(attr.insensitive, false);
520+
t.deepEqual(attr.sensitiveFlag, "s");
521+
t.deepEqual(attr.insensitiveFlag, "");
522+
t.deepEqual(tree.toString(), '[href="foo" s]');
523+
});
524+
525+
test("case sensitivity flags are mutually exclusive (s to i)", '[href="foo" s]', (t, tree) => {
526+
let attr = tree.atPosition(1, 13);
527+
t.deepEqual(attr.sensitive, true);
528+
529+
attr.insensitive = true;
530+
531+
t.deepEqual(attr.insensitive, true);
532+
t.deepEqual(attr.sensitive, false);
533+
t.deepEqual(attr.insensitiveFlag, "i");
534+
t.deepEqual(attr.sensitiveFlag, "");
535+
t.deepEqual(tree.toString(), '[href="foo" i]');
536+
});
537+
538+
test(
539+
"switching case sensitivity erases the original notation (I to s)",
540+
'[href="foo" I]',
541+
(t, tree) => {
542+
let attr = tree.atPosition(1, 13);
543+
t.deepEqual(attr.raws.insensitiveFlag, "I");
544+
545+
attr.sensitive = true;
546+
547+
t.is(attr.raws.insensitiveFlag, undefined);
548+
t.deepEqual(tree.toString(), '[href="foo" s]');
549+
},
550+
);
551+
552+
test(
553+
"switching case sensitivity erases the original notation (S to i)",
554+
'[href="foo" S]',
555+
(t, tree) => {
556+
let attr = tree.atPosition(1, 13);
557+
t.deepEqual(attr.raws.sensitiveFlag, "S");
558+
559+
attr.insensitive = true;
560+
561+
t.is(attr.raws.sensitiveFlag, undefined);
562+
t.deepEqual(tree.toString(), '[href="foo" i]');
563+
},
564+
);
565+
566+
test("case sensitivity setters keep non standard modifiers", '[href="foo" y]', (t, tree) => {
567+
let attr = tree.atPosition(1, 13);
568+
t.deepEqual(attr.raws.insensitiveFlag, "y");
569+
570+
// Only the standard "i"/"I" notations are erased, so an unrecognised flag kept
571+
// in raws survives the round trip rather than being silently destroyed.
572+
attr.sensitive = true;
573+
t.deepEqual(attr.raws.insensitiveFlag, "y");
574+
t.deepEqual(tree.toString(), '[href="foo" s]');
575+
576+
attr.sensitive = false;
577+
t.deepEqual(attr.raws.insensitiveFlag, "y");
578+
t.deepEqual(tree.toString(), '[href="foo" y]');
579+
});
580+
502581
test("capitalized case sensitive attribute selector", '[href="foo" S]', (t, tree) => {
503582
let attr = tree.atPosition(1, 13);
504583
t.deepEqual(attr.sensitive, true);

‎src/selectors/attribute.js‎

Lines changed: 30 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -261,17 +261,23 @@ export default class Attribute extends Namespace {
261261
* If the case insensitive flag changes, the raw (escaped) value at `attr.raws.insensitiveFlag`
262262
* of the attribute is updated accordingly.
263263
*
264+
* The two case sensitivity flags are mutually exclusive, so setting this flag
265+
* clears `attr.sensitive` and any `s`/`S` in `attr.raws.sensitiveFlag`.
266+
*
264267
* @param {true | false} insensitive true if the attribute should match case-insensitively.
265268
*/
266269
set insensitive(insensitive) {
267-
if (!insensitive) {
268-
this._insensitive = false;
269-
270+
if (insensitive) {
271+
// `[attr=value i s]` is not a thing, so adopting the case-insensitive flag
272+
// drops the explicit case-sensitive flag and its original notation.
273+
this.sensitive = false;
274+
} else if (
275+
this.raws &&
276+
(this.raws.insensitiveFlag === "I" || this.raws.insensitiveFlag === "i")
277+
) {
270278
// "i" and "I" can be used in "this.raws.insensitiveFlag" to store the original notation.
271279
// When setting `attr.insensitive = false` both should be erased to ensure correct serialization.
272-
if (this.raws && (this.raws.insensitiveFlag === "I" || this.raws.insensitiveFlag === "i")) {
273-
this.raws.insensitiveFlag = undefined;
274-
}
280+
this.raws.insensitiveFlag = undefined;
275281
}
276282

277283
this._insensitive = insensitive;
@@ -286,17 +292,22 @@ export default class Attribute extends Namespace {
286292
* If the case sensitive flag changes, the raw (escaped) value at `attr.raws.sensitiveFlag`
287293
* of the attribute is updated accordingly.
288294
*
295+
* The two case sensitivity flags are mutually exclusive, so setting this flag
296+
* clears `attr.insensitive` and any `i`/`I` in `attr.raws.insensitiveFlag`.
297+
*
289298
* @param {true | false} sensitive true if the attribute should match case-sensitively.
290299
*/
291300
set sensitive(sensitive) {
292-
if (!sensitive) {
293-
this._sensitive = false;
294-
301+
if (sensitive) {
302+
// `[attr=value s i]` is not a thing, so adopting the case-sensitive flag
303+
// drops the case-insensitive flag and its original notation. Only the
304+
// standard "i"/"I" notations are erased, so a non-standard flag kept in
305+
// "this.raws.insensitiveFlag" survives and can still be round-tripped.
306+
this.insensitive = false;
307+
} else if (this.raws && (this.raws.sensitiveFlag === "S" || this.raws.sensitiveFlag === "s")) {
295308
// "s" and "S" can be used in "this.raws.sensitiveFlag" to store the original notation.
296309
// When setting `attr.sensitive = false` both should be erased to ensure correct serialization.
297-
if (this.raws && (this.raws.sensitiveFlag === "S" || this.raws.sensitiveFlag === "s")) {
298-
this.raws.sensitiveFlag = undefined;
299-
}
310+
this.raws.sensitiveFlag = undefined;
300311
}
301312

302313
this._sensitive = sensitive;
@@ -374,6 +385,7 @@ export default class Attribute extends Namespace {
374385
* * "operator" - the match operator of the attribute
375386
* * "value" - The value (string or identifier)
376387
* * "insensitive" - the case insensitivity flag;
388+
* * "sensitive" - the explicit case sensitivity flag;
377389
* @param part One of the possible values inside an attribute.
378390
* @returns -1 if the name is invalid or the value doesn't exist in this attribute.
379391
*/
@@ -416,11 +428,17 @@ export default class Attribute extends Namespace {
416428

417429
count += value.length;
418430
count += valueSpaces.after.length;
431+
// Both case sensitivity flags occupy the same slot after the value, so they
432+
// share the "insensitive" spaces. Each name only resolves when its own flag
433+
// is the one actually present.
419434
let insensitiveSpaces = this._spacesFor("insensitive");
420435
count += insensitiveSpaces.before.length;
421436
if (name === "insensitive") {
422437
return this.insensitive ? count : -1;
423438
}
439+
if (name === "sensitive") {
440+
return this.sensitive ? count : -1;
441+
}
424442
return -1;
425443
}
426444

0 commit comments

Comments
 (0)