@barqjs/compiler 0.0.0-stage → 0.2.0-next.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +241 -2
- package/docs/BARQ001.md +55 -0
- package/docs/BARQ002.md +53 -0
- package/docs/BARQ003.md +58 -0
- package/docs/BARQ004.md +116 -0
- package/docs/BARQ005.md +25 -0
- package/docs/BARQ006.md +23 -0
- package/docs/BARQ008.md +43 -0
- package/docs/BARQ009.md +48 -0
- package/docs/BARQ010.md +76 -0
- package/docs/BARQ011.md +88 -0
- package/docs/BARQ012.md +81 -0
- package/docs/BARQ013.md +63 -0
- package/docs/BARQ014.md +61 -0
- package/docs/BARQ015.md +64 -0
- package/docs/BARQ016.md +52 -0
- package/docs/BARQ017.md +63 -0
- package/docs/BARQ018.md +116 -0
- package/docs/BARQ019.md +109 -0
- package/docs/BARQ020.md +78 -0
- package/docs/BARQ021.md +79 -0
- package/docs/BARQ022.md +57 -0
- package/docs/BARQ023.md +55 -0
- package/docs/BARQ024.md +58 -0
- package/docs/BARQ025.md +74 -0
- package/docs/BARQ026.md +68 -0
- package/docs/BARQ027.md +53 -0
- package/docs/BARQ028.md +56 -0
- package/docs/BARQ029.md +57 -0
- package/docs/BARQ030.md +65 -0
- package/docs/BARQ031.md +61 -0
- package/docs/BARQ032.md +68 -0
- package/docs/BARQ033.md +81 -0
- package/docs/BARQ034.md +55 -0
- package/docs/README.md +137 -0
- package/index.d.ts +604 -0
- package/index.js +90 -0
- package/package.json +87 -4
- package/skills/compiler-diagnostics/SKILL.md +890 -0
package/docs/BARQ026.md
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# BARQ026: Markup the browser's HTML parser builds differently from the JSX
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `<div>` cannot be inside a `<p>`: the browser's HTML parser closes the paragraph at
|
|
8
|
+
> `<div>`, so the `<div>` lands after the `<p>` and the `</p>` that follows opens an empty
|
|
9
|
+
> one. A server-rendered page then hydrates against a tree that is not the one this JSX
|
|
10
|
+
> builds, which is a hydration mismatch and a full re-render in the browser. Move the `<div>`
|
|
11
|
+
> out of the `<p>`, or change the outer element (a `<div>` in place of a `<p>`, a `<span>` in
|
|
12
|
+
> place of an inner link).
|
|
13
|
+
|
|
14
|
+
The first sentence names what the parser does at that element. The other shapes it reports:
|
|
15
|
+
|
|
16
|
+
- a table part outside its parent, or anything but its parts inside a table: `<tr>`
|
|
17
|
+
directly in a `<table>` (the parser adds a `<tbody>`), `<td>` in a `<div>` (the parser
|
|
18
|
+
drops the tag), `<div>` in a `<tr>` (the parser moves it before the table).
|
|
19
|
+
- an element `<select>`, `<optgroup>` or `<option>` does not take.
|
|
20
|
+
- a second `<a>`, `<button>`, `<form>`, `<li>`, `<nobr>`, `<dd>` or `<dt>` inside an open one,
|
|
21
|
+
which the parser closes first.
|
|
22
|
+
- `<html>`, `<head>`, `<body>` and the obsolete `<frame>`, `<frameset>`, `<plaintext>`, which
|
|
23
|
+
are never an element of their own inside a page.
|
|
24
|
+
|
|
25
|
+
## Failing example
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
export const Notice = (props) => (
|
|
29
|
+
<p>
|
|
30
|
+
Your order shipped.
|
|
31
|
+
<div class="details">{props.tracking}</div>
|
|
32
|
+
</p>
|
|
33
|
+
);
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Fixed example
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
export const Notice = (props) => (
|
|
40
|
+
<div>
|
|
41
|
+
<p>Your order shipped.</p>
|
|
42
|
+
<div class="details">{props.tracking}</div>
|
|
43
|
+
</div>
|
|
44
|
+
);
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Why this rule exists
|
|
48
|
+
|
|
49
|
+
A server render writes the markup as a string, and the browser parses that string with the
|
|
50
|
+
HTML parser, which repairs what HTML does not allow instead of keeping it. The page the
|
|
51
|
+
browser builds from `<p><div>…</div></p>` is `<p></p><div>…</div><p></p>`. Hydration then
|
|
52
|
+
walks a tree that is not the one the component builds, reports a mismatch, throws the
|
|
53
|
+
server's markup away and renders the page again. A client-only render does not show it,
|
|
54
|
+
because it builds elements one by one and never asks the parser.
|
|
55
|
+
|
|
56
|
+
The check follows JSX within one component: an element's children, and JSX that a
|
|
57
|
+
conditional, a `&&` or a list callback places where it stands. A component's children start
|
|
58
|
+
again, because the component decides where they go.
|
|
59
|
+
|
|
60
|
+
## Silencing one line
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
// barq-ignore-next-line BARQ026 (rendered on the client only, never hydrated)
|
|
64
|
+
export const Legacy = () => <p><div>kept for an old stylesheet</div></p>;
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The reason in parentheses is required and has to be at least 10 characters. To change the
|
|
68
|
+
level for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ027.md
ADDED
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
# BARQ027: A `bind:` or a form `action` is written for a custom renderer
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `bind:` is a two-way binding to a document form control, and this element is built by a
|
|
8
|
+
> custom renderer, which has none. Pass the value as a prop and write it back from the
|
|
9
|
+
> host's own event: `value={text()}` with `onChange={(next) => setText(next)}`.
|
|
10
|
+
|
|
11
|
+
For `action` on a `<form>`, the message says that the action is a document form's submit
|
|
12
|
+
handler or URL and suggests calling it from the host's own event, such as
|
|
13
|
+
`onSubmit={() => save()}`.
|
|
14
|
+
|
|
15
|
+
## Failing example
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
// compiled with target: "universal"
|
|
19
|
+
export const Field = (props) => <input bind:value={props.text} />;
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Fixed example
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
// compiled with target: "universal"
|
|
26
|
+
export const Field = (props) => (
|
|
27
|
+
<input value={props.text} onChange={(next: string) => props.setText(next)} />
|
|
28
|
+
);
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Why this rule exists
|
|
32
|
+
|
|
33
|
+
An element a custom renderer builds (in a module compiled with `target: "universal"`, a
|
|
34
|
+
file a `renderers` entry gives to one, or the children of a `boundaries` component whose
|
|
35
|
+
target is `universal`) has every attribute and event written as one `setProp` call on the
|
|
36
|
+
host's node, and the host decides what a name means. `bind:` needs two facts only a document form
|
|
37
|
+
control has: the property a user edits (`value`, `checked`, `valueAsNumber`) and the event
|
|
38
|
+
that reports the edit (`input`, `change`). A form `action` is the document's submit,
|
|
39
|
+
which a scene graph or a terminal does not have. Neither has a meaning the compiler could
|
|
40
|
+
write for an arbitrary host, so the module would build an element that silently never
|
|
41
|
+
updates, and the build fails instead. A literal `action="/save"` is an ordinary property
|
|
42
|
+
and is not reported.
|
|
43
|
+
|
|
44
|
+
## Silencing one line
|
|
45
|
+
|
|
46
|
+
```tsx
|
|
47
|
+
// barq-ignore-next-line BARQ027 (the host reads this name itself in a later version)
|
|
48
|
+
export const Field = (props) => <input bind:value={props.text} />;
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The reason in parentheses is required and has to be at least 10 characters. Silencing the
|
|
52
|
+
code does not make the binding work: nothing is emitted for it. To change the level for the
|
|
53
|
+
whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ028.md
ADDED
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
# BARQ028: A module compiled for a custom renderer is also asked for `ssr`, `hydratable` or `interp`
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `ssr: true` was asked for together with `target: "universal"`, and the string backend
|
|
8
|
+
> renders the document's markup, which a custom host does not have. It was turned off for
|
|
9
|
+
> this module. Remove it from this module's options, or give the files of the custom
|
|
10
|
+
> renderer their own entry in `renderers`, which leaves `ssr` to the rest of the build.
|
|
11
|
+
|
|
12
|
+
The same message names `hydratable` (hydration claims the document's server markup) or
|
|
13
|
+
`interp` (the reference backend walks the document).
|
|
14
|
+
|
|
15
|
+
## Failing example
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
// compiled with { target: "universal", ssr: true }
|
|
19
|
+
export const Scene = (props) => <box>{props.label}</box>;
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Fixed example
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
// compiled with { target: "universal" }
|
|
26
|
+
export const Scene = (props) => <box>{props.label}</box>;
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Why this rule exists
|
|
30
|
+
|
|
31
|
+
`ssr`, `hydratable` and `interp` each choose how a module reaches the document: as a string
|
|
32
|
+
of markup, as a client that claims that markup, or through the reference backend's walk. A
|
|
33
|
+
module compiled for a custom renderer reaches its own host instead, so asking for both is a
|
|
34
|
+
configuration that cannot mean anything. The compiler turns the document option off and
|
|
35
|
+
fails the build, so the mistake is seen rather than compiled into a bundle that ignores
|
|
36
|
+
half of what it was told.
|
|
37
|
+
|
|
38
|
+
An app that renders the document on the server and a custom host in the browser keeps
|
|
39
|
+
`ssr` and `hydratable` for its document files and gives the others a `renderers` entry,
|
|
40
|
+
which is not reported: the build's document options describe its document files, and the
|
|
41
|
+
files an entry gives to a custom renderer are not among them.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
barq({
|
|
45
|
+
ssr: true,
|
|
46
|
+
compiler: {
|
|
47
|
+
renderers: [{ include: ["src/scene/**"], target: "universal", moduleSource: "/src/renderer.ts" }],
|
|
48
|
+
},
|
|
49
|
+
});
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Turning it off
|
|
53
|
+
|
|
54
|
+
This code is about the options a module is compiled with rather than a line of it, so there
|
|
55
|
+
is no line to silence. To change the level for the whole project, see
|
|
56
|
+
[the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ029.md
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
# BARQ029: Two renderers claim the same intrinsic tag
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `<mesh>` is claimed by two renderers, `@acme/scene/renderer` and `@acme/other/renderer`, so
|
|
8
|
+
> it compiles for the document. Claim it in your own `intrinsics` configuration, which wins over
|
|
9
|
+
> what a package declares.
|
|
10
|
+
|
|
11
|
+
For a tag that no entry names and the document does not have, the message says that two
|
|
12
|
+
renderers claim every such tag (both declare `claimUnknown: true`).
|
|
13
|
+
|
|
14
|
+
## Failing example
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
// two installed packages both list "mesh" under barq.intrinsics
|
|
18
|
+
export const Box = () => <mesh />;
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Fixed example
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
// the application's own intrinsics entry gives "mesh" to one of them
|
|
25
|
+
export const Box = () => <mesh />;
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Why this rule exists
|
|
29
|
+
|
|
30
|
+
A tree of intrinsic elements written outside every boundary builds through the renderer that
|
|
31
|
+
claims its root tag, so `function Box() { return <mesh /> }` is a scene object wherever it is
|
|
32
|
+
declared. When two renderers claim the tag, nothing in the source says which one the author
|
|
33
|
+
meant, and picking either would build the tree on a host the author may not render it into.
|
|
34
|
+
The tree compiles for the document instead, as it would with no renderer installed, and the
|
|
35
|
+
warning names both claimants.
|
|
36
|
+
|
|
37
|
+
An `intrinsics` entry in the application's own configuration takes the tag from every package
|
|
38
|
+
that declares it:
|
|
39
|
+
|
|
40
|
+
```ts
|
|
41
|
+
barq({
|
|
42
|
+
compiler: {
|
|
43
|
+
intrinsics: [{ tags: ["mesh"], target: "universal", moduleSource: "@acme/scene/renderer" }],
|
|
44
|
+
},
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Silencing one line
|
|
49
|
+
|
|
50
|
+
```tsx
|
|
51
|
+
// barq-ignore-next-line BARQ029 (this tree is only rendered in the document)
|
|
52
|
+
export const Box = () => <mesh />;
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The reason in parentheses is required and has to be at least 10 characters. Silencing the code
|
|
56
|
+
does not choose a renderer: the tree still compiles for the document. To change the level for
|
|
57
|
+
the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ030.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# BARQ030: A prop is assigned, and props are read-only
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> A prop is assigned here, and props are read-only: the component that passed it owns the
|
|
8
|
+
> value. Call a function prop to ask for the change, or keep a signal of your own and write
|
|
9
|
+
> to that.
|
|
10
|
+
|
|
11
|
+
## Failing example
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
export function Counter(props: { count: number }) {
|
|
15
|
+
return (
|
|
16
|
+
<button
|
|
17
|
+
type="button"
|
|
18
|
+
onClick={() => {
|
|
19
|
+
props.count = props.count + 1;
|
|
20
|
+
}}
|
|
21
|
+
>
|
|
22
|
+
{props.count}
|
|
23
|
+
</button>
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Fixed example
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
export function Counter(props: { count: number; onChange: (next: number) => void }) {
|
|
32
|
+
return (
|
|
33
|
+
<button type="button" onClick={() => props.onChange(props.count + 1)}>
|
|
34
|
+
{props.count}
|
|
35
|
+
</button>
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Why this rule exists
|
|
41
|
+
|
|
42
|
+
A component reads its props as values, and each read asks the component that passed the
|
|
43
|
+
prop for the current one. Nothing stands behind a prop for an assignment to change: the
|
|
44
|
+
write would land on the component's own record, the parent would never hear of it, and
|
|
45
|
+
the next read would answer with what was written instead of what the parent passes.
|
|
46
|
+
|
|
47
|
+
The rule reports an assignment, `+=` and its relatives, and `++` and `--`, on `props.name`,
|
|
48
|
+
on a name bound by destructuring the props, and on a member of what `omit(props, …)`
|
|
49
|
+
answers with. Writing into the VALUE a prop holds, `props.user.name = "salama"`, is not
|
|
50
|
+
reported: that object belongs to whoever made it.
|
|
51
|
+
|
|
52
|
+
## Silencing one line
|
|
53
|
+
|
|
54
|
+
```tsx
|
|
55
|
+
export function Counter(props: { count: number }) {
|
|
56
|
+
// barq-ignore-next-line BARQ030 (the record is this component's own in this test)
|
|
57
|
+
props.count = 0;
|
|
58
|
+
return <output>{props.count}</output>;
|
|
59
|
+
}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
63
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ030 (reason) */}` on the line
|
|
64
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
65
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ031.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# BARQ031: A props pattern binds a name that cannot be kept reactive
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This props pattern cannot be kept reactive: a computed key, a default inside a nested
|
|
8
|
+
> pattern, or a rest element inside one. Destructure one level, or read the prop from
|
|
9
|
+
> `props` where it is used.
|
|
10
|
+
|
|
11
|
+
## Failing example
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
export function Card({ user: { name = "guest" } }: { user: { name?: string } }) {
|
|
15
|
+
return <p>{name}</p>;
|
|
16
|
+
}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Fixed example
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
export function Card({ user }: { user: { name?: string } }) {
|
|
23
|
+
return <p>{user.name ?? "guest"}</p>;
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Why this rule exists
|
|
28
|
+
|
|
29
|
+
A name bound by destructuring a component's props is not a copy. The compiler makes each
|
|
30
|
+
use of it the read it stands for, so `{ title }` follows the prop as `props.title` does, a
|
|
31
|
+
default applies whenever the prop is `undefined`, and `...rest` carries the props the
|
|
32
|
+
pattern did not name.
|
|
33
|
+
|
|
34
|
+
Three shapes have no read to stand for:
|
|
35
|
+
|
|
36
|
+
- A computed key, `{ [key]: value }`, names a prop only when the component runs.
|
|
37
|
+
- A default inside a nested pattern, `{ user: { name = "guest" } }`, would have to be made
|
|
38
|
+
once per value of `user`, and the pattern has nowhere to keep it.
|
|
39
|
+
- A rest element inside a nested pattern, `{ user: { id, ...others } }`, copies the value's
|
|
40
|
+
remaining fields, and a copy does not follow the prop.
|
|
41
|
+
|
|
42
|
+
A pattern with one of them is left as JavaScript reads it, which is a copy made once when
|
|
43
|
+
the component runs, of a record whose members are not the values the types describe. So
|
|
44
|
+
the rule is an error rather than advice.
|
|
45
|
+
|
|
46
|
+
Destructuring one level is always supported: names, renames, defaults and a rest element.
|
|
47
|
+
So is a nested pattern with none of the three, `{ user: { name }, items: [first] }`.
|
|
48
|
+
|
|
49
|
+
## Silencing one line
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
// barq-ignore-next-line BARQ031 (this function is called by hand with a plain object)
|
|
53
|
+
export function Card({ user: { name = "guest" } }: { user: { name?: string } }) {
|
|
54
|
+
return <p>{name}</p>;
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
59
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ031 (reason) */}` on the line
|
|
60
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
61
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ032.md
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# BARQ032: A shorthand that cannot be split is merged with one of its longhands
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `border` and `border-top-color` are merged here, and `border` is a shorthand whose
|
|
8
|
+
> values are told apart by type, so it is kept whole and does not give way to
|
|
9
|
+
> `border-top-color` or replace it. Both classes stay on the element and the order of the
|
|
10
|
+
> stylesheet decides between them, which is not the order they are passed in. Write
|
|
11
|
+
> `border` as its longhands instead, as `border` is `border-width`, `border-style` and
|
|
12
|
+
> `border-color`.
|
|
13
|
+
|
|
14
|
+
## Failing example
|
|
15
|
+
|
|
16
|
+
```tsx
|
|
17
|
+
import { atoms } from "@barqjs/css";
|
|
18
|
+
|
|
19
|
+
export const field = (invalid: boolean) =>
|
|
20
|
+
atoms({ border: "1px solid gray" }, invalid && { borderColor: "red" });
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Fixed example
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { atoms } from "@barqjs/css";
|
|
27
|
+
|
|
28
|
+
export const field = (invalid: boolean) =>
|
|
29
|
+
atoms(
|
|
30
|
+
{ borderWidth: 1, borderStyle: "solid", borderColor: "gray" },
|
|
31
|
+
invalid && { borderColor: "red" },
|
|
32
|
+
);
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Why this rule exists
|
|
36
|
+
|
|
37
|
+
`atoms` promises that the order arguments are passed in decides which declaration wins.
|
|
38
|
+
It keeps that promise by giving each property one class and keeping the last class per
|
|
39
|
+
property.
|
|
40
|
+
|
|
41
|
+
A shorthand such as `margin` is split into its sides by counting values, so a later
|
|
42
|
+
`marginTop` replaces one side. `border`, `font`, `flex`, `background`, `transition` and
|
|
43
|
+
the other shorthands whose values are told apart by type cannot be split that way, so
|
|
44
|
+
each stays one class of its own. `border` and `border-color` are then two properties to
|
|
45
|
+
the merge: neither replaces the other, and both classes reach the element.
|
|
46
|
+
|
|
47
|
+
Which one wins is the cascade's answer. Both rules have the same specificity, so the
|
|
48
|
+
later rule in the stylesheet wins, and an atom is written where the first call to use it
|
|
49
|
+
stood. The result can match the order you passed today and stop matching when another
|
|
50
|
+
component uses either declaration first.
|
|
51
|
+
|
|
52
|
+
The same holds under a condition: `border` and `borderColor` both under `:hover` are
|
|
53
|
+
reported, and a base `border` beside a `:hover` `borderColor` is not, since the hover
|
|
54
|
+
rule has the higher specificity.
|
|
55
|
+
|
|
56
|
+
## Silencing one line
|
|
57
|
+
|
|
58
|
+
```tsx
|
|
59
|
+
import { atoms } from "@barqjs/css";
|
|
60
|
+
|
|
61
|
+
export const frame =
|
|
62
|
+
// barq-ignore-next-line BARQ032 (the border colour is the same in both)
|
|
63
|
+
atoms({ border: "1px solid gray" }, { borderColor: "gray" });
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The reason in parentheses is required and has to be at least 10 characters. To change the
|
|
67
|
+
level for the whole project, see
|
|
68
|
+
[the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ033.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# BARQ033: Two conditions on one property are written in the order the stylesheet reverses
|
|
2
|
+
|
|
3
|
+
**Level:** note · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `color` is set under `.&:hover` and then under `.&[data-active]`, and both can match one
|
|
8
|
+
> element. One stylesheet serves every call, so it cannot keep this call's order: it puts
|
|
9
|
+
> `.&[data-active]` first, and where both match `.&:hover` wins although it is written
|
|
10
|
+
> earlier. Write them in that order, so the code reads the way the page behaves, or make
|
|
11
|
+
> one rule the other out.
|
|
12
|
+
|
|
13
|
+
## Failing example
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { atoms } from "@barqjs/css";
|
|
17
|
+
|
|
18
|
+
export const tab = atoms({
|
|
19
|
+
color: { ":hover": "blue", "[data-active]": "red" },
|
|
20
|
+
});
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Fixed example
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { atoms } from "@barqjs/css";
|
|
27
|
+
|
|
28
|
+
export const tab = atoms({
|
|
29
|
+
color: { "[data-active]": "red", ":hover": "blue" },
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Or, when the active tab should keep its colour under the pointer, rule the hover out:
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { atoms } from "@barqjs/css";
|
|
37
|
+
|
|
38
|
+
export const tab = atoms({
|
|
39
|
+
color: { "[data-active]": "red", ":not([data-active]):hover": "blue" },
|
|
40
|
+
});
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Why this rule exists
|
|
44
|
+
|
|
45
|
+
Passing order decides for one property under one condition: a later argument replaces an
|
|
46
|
+
earlier one. Two different conditions are two classes, and both stay on the element. When
|
|
47
|
+
both match and their selectors weigh the same, the stylesheet's order decides, and one
|
|
48
|
+
stylesheet serves every call on the page, so it cannot follow each call's own order.
|
|
49
|
+
|
|
50
|
+
The order is fixed instead, within one tier: a condition with no interaction
|
|
51
|
+
pseudo-class first, then `:link`, `:visited`, `:focus-within`, `:hover`, `:focus`,
|
|
52
|
+
`:focus-visible`, `:active`, and `:disabled` last; two conditions of one place go by
|
|
53
|
+
their hash. Among rules about something under the element, one under an at-rule comes
|
|
54
|
+
after one under none. This note fires when one object writes such a pair the other way round,
|
|
55
|
+
which is the one case where the order you wrote visibly loses.
|
|
56
|
+
|
|
57
|
+
It does not fire when the pair cannot both apply as written: one attribute equal to two
|
|
58
|
+
values or starting with two prefixes that do not start each other, two different child
|
|
59
|
+
positions, a selector against its `:not()`, or two media queries over ranges of one
|
|
60
|
+
feature that do not meet, such as `(width < 48rem)` against `(width >= 48rem)`, compared
|
|
61
|
+
in pixels where the units convert. Nor when specificity decides, when both set the same
|
|
62
|
+
value, when the two are different pseudo-elements, or when the same object also gives the
|
|
63
|
+
property a condition that is both at once, `":is(.dark *)[data-selected]"` beside
|
|
64
|
+
`":is(.dark *)"` and `"[data-selected]"`, which outweighs either and decides where both
|
|
65
|
+
match.
|
|
66
|
+
|
|
67
|
+
Every such pair in a call is reported, not only the first.
|
|
68
|
+
|
|
69
|
+
## Silencing one line
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
import { atoms } from "@barqjs/css";
|
|
73
|
+
|
|
74
|
+
export const tab =
|
|
75
|
+
// barq-ignore-next-line BARQ033 (the hover colour is meant to win)
|
|
76
|
+
atoms({ color: { ":hover": "blue", "[data-active]": "red" } });
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The reason in parentheses is required and has to be at least 10 characters. To change the
|
|
80
|
+
level for the whole project, see
|
|
81
|
+
[the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ034.md
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# BARQ034: A tag names a prop whose default is a string, which is not a component
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This tag names a prop whose default is a string, and a tag is called as a component, so the
|
|
8
|
+
> default can never render. An element chosen at run time is `dynamic`:
|
|
9
|
+
> `const Tag = dynamic(() => props.as ?? "div")`, then `<Tag />`.
|
|
10
|
+
|
|
11
|
+
## Failing example
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
export function Box({ as: Tag = "div", ...rest }: { as?: string; children?: unknown }) {
|
|
15
|
+
return <Tag {...rest} />;
|
|
16
|
+
}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## Fixed example
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import { omit } from "@barqjs/core";
|
|
23
|
+
import { dynamic } from "@barqjs/web";
|
|
24
|
+
|
|
25
|
+
export function Box(props: { as?: string; children?: unknown }) {
|
|
26
|
+
const Tag = dynamic(() => props.as ?? "div");
|
|
27
|
+
return <Tag {...omit(props, "as")} />;
|
|
28
|
+
}
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Why this rule exists
|
|
32
|
+
|
|
33
|
+
A capitalised tag is a component: `<Tag />` is compiled to a call of whatever `Tag` holds, and
|
|
34
|
+
a tag that names a prop calls the prop's value. A string is not a function, so the default
|
|
35
|
+
throws the first time the caller leaves the prop out, and a caller passing `"span"` throws the
|
|
36
|
+
same way.
|
|
37
|
+
|
|
38
|
+
`dynamic` is how an element or a component chosen at run time is written: it takes a source
|
|
39
|
+
that answers either, renders an element for a string, and replaces what it rendered when the
|
|
40
|
+
source changes.
|
|
41
|
+
|
|
42
|
+
A lowercase tag is never a binding: `<tag />` is an element named `tag`, whatever a pattern
|
|
43
|
+
bound under that name.
|
|
44
|
+
|
|
45
|
+
## Silencing one line
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
export function Box({ as: Tag = "div" }) {
|
|
49
|
+
// barq-ignore-next-line BARQ034 (every caller passes a component as `as`)
|
|
50
|
+
return <Tag />;
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
The reason in parentheses is required and has to be at least 10 characters. To change the
|
|
55
|
+
level for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|