@barqjs/compiler 0.2.0-next.0 → 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/README.md +21 -5
- package/docs/BARQ001.md +3 -3
- package/docs/BARQ002.md +2 -2
- package/docs/BARQ003.md +2 -2
- package/docs/BARQ005.md +16 -83
- package/docs/BARQ015.md +1 -1
- package/docs/BARQ018.md +6 -6
- package/docs/BARQ025.md +4 -4
- package/docs/BARQ027.md +1 -1
- package/docs/BARQ028.md +2 -2
- 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 +21 -13
- package/index.d.ts +42 -1
- package/index.js +1 -0
- package/package.json +19 -18
- package/skills/compiler-diagnostics/SKILL.md +890 -0
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ made with `@barqjs/universal`.
|
|
|
10
10
|
|
|
11
11
|
It also generates the file route table, splits route and middleware modules into
|
|
12
12
|
their client and server halves, compiles `@barqjs/css` blocks to a stylesheet,
|
|
13
|
-
and reports mistakes before the code runs:
|
|
13
|
+
and reports mistakes before the code runs: 28 [diagnostics](./docs/README.md),
|
|
14
14
|
each with a stable `BARQ` code, a page that shows the fix, and a required reason
|
|
15
15
|
to silence it.
|
|
16
16
|
|
|
@@ -47,9 +47,11 @@ delegated events.
|
|
|
47
47
|
|
|
48
48
|
Where it differs:
|
|
49
49
|
|
|
50
|
-
- A
|
|
51
|
-
`
|
|
52
|
-
reads
|
|
50
|
+
- A component writes a prop as its value, `props.name` or a destructured
|
|
51
|
+
`{ name }`, and both stay live. The props record holds a Cell per prop, a
|
|
52
|
+
function, and the compiler writes the call that reads it. Solid passes a
|
|
53
|
+
getter on the props object, so destructuring there reads once.
|
|
54
|
+
`cells(props)` gives the record itself, where a Cell is wanted unread.
|
|
53
55
|
- What is reactive is decided from the binding a name resolves to (oxc's
|
|
54
56
|
`SymbolId`), never from how it is spelled. `createSignal` imported under
|
|
55
57
|
another name is still a signal.
|
|
@@ -80,6 +82,11 @@ Passing the accessor itself, `{count}`, is also live. Using it as a value,
|
|
|
80
82
|
`count * 2` or `` `${count}` ``, is a bug that
|
|
81
83
|
[BARQ001](./docs/BARQ001.md) reports.
|
|
82
84
|
|
|
85
|
+
Props are written as values. `props.title` and a destructured
|
|
86
|
+
`{ title, tone = "warm", ...rest }` both follow the prop, because the compiler
|
|
87
|
+
writes each read. An object spread onto a component, `<Chip {...options} />`,
|
|
88
|
+
is an object of values too.
|
|
89
|
+
|
|
83
90
|
## API
|
|
84
91
|
|
|
85
92
|
```ts
|
|
@@ -104,6 +111,13 @@ const { code, map, warnings, diagnostics } = transform(source, {
|
|
|
104
111
|
default, so a page that is never hydrated does not pay for them.
|
|
105
112
|
- `dev`: the development build. Turns on the dev-only diagnostics, template
|
|
106
113
|
labels and source locations.
|
|
114
|
+
- `sourceNames`: carry names and positions into the output for the runtime's
|
|
115
|
+
findings. A signal, memo and store is named after the binding it is declared
|
|
116
|
+
as (`createSignal(0, { name: "count", loc: "src/App.tsx:3:29" })`), a binding
|
|
117
|
+
effect runs under the element and attribute it writes (`li.class`,
|
|
118
|
+
`li.children`, `<Show>`), and every component call carries where it is
|
|
119
|
+
written. Positions are relative to `root` and need a `filename`. Defaults to
|
|
120
|
+
`dev`.
|
|
107
121
|
- `diagnostics`: run the source-level checks. Defaults to `dev`; set it in CI to
|
|
108
122
|
run them on a production build.
|
|
109
123
|
- `checks`, `defaultCategory`, `strictCss`: change the level of a code. See
|
|
@@ -171,7 +185,9 @@ The result:
|
|
|
171
185
|
- `map`: the source map, when asked for.
|
|
172
186
|
- `diagnostics`: structured records with `code`, `severity`, `message`, the
|
|
173
187
|
span (`line`, `column`, `endLine`, `endColumn`, `pos`, `end`) and `docs`, a
|
|
174
|
-
link to the page for the code.
|
|
188
|
+
link to the page for the code. A finding whose repair is one spelling also
|
|
189
|
+
has `fix`: a list of `{ pos, end, text }` edits over the source, UTF-16
|
|
190
|
+
offsets, which `barq check --fix` from `@barqjs/cli` applies.
|
|
175
191
|
- `warnings`: the same set as `file:line:col: CODE level: message` strings.
|
|
176
192
|
- `labels`, `css` and the side outputs the options above ask for.
|
|
177
193
|
|
package/docs/BARQ001.md
CHANGED
|
@@ -31,9 +31,9 @@ export const Total = () => <p>{`total: ${count()}`}</p>;
|
|
|
31
31
|
|
|
32
32
|
An accessor is a function, and JavaScript turns a function into a string or a number
|
|
33
33
|
without complaint: `` `${count}` `` puts the accessor's source text on the page and
|
|
34
|
-
`count * 2` is `NaN`. Neither throws, and TypeScript accepts the string forms.
|
|
35
|
-
|
|
36
|
-
string or a calculation.
|
|
34
|
+
`count * 2` is `NaN`. Neither throws, and TypeScript accepts the string forms. A prop is
|
|
35
|
+
not an accessor: a component writes `props.count` as the value and the compiler writes the
|
|
36
|
+
read, so a prop inside a string or a calculation is correct and is not reported.
|
|
37
37
|
|
|
38
38
|
Passing the accessor itself to JSX is correct and is not reported: `<p>{count}</p>` and
|
|
39
39
|
`<div id={count}>` both stay up to date.
|
package/docs/BARQ002.md
CHANGED
|
@@ -33,8 +33,8 @@ A function is always truthy. `if (loading)`, `loading ? a : b`, `loading && x`,
|
|
|
33
33
|
and a loop that tests an accessor therefore never change with the signal: one branch is
|
|
34
34
|
dead from the start, and a `while (loading)` never ends.
|
|
35
35
|
|
|
36
|
-
A prop is not reported here
|
|
37
|
-
|
|
36
|
+
A prop is not reported here: a component writes `props.label` as the value and the
|
|
37
|
+
compiler writes the read, so `props.label ? a : b` tests what the caller passed.
|
|
38
38
|
|
|
39
39
|
## Silencing one line
|
|
40
40
|
|
package/docs/BARQ003.md
CHANGED
|
@@ -32,8 +32,8 @@ export const Email = () => <p>{user().email}</p>;
|
|
|
32
32
|
The value is behind the call, so `user.email` asks the function for a property it does
|
|
33
33
|
not have and the page shows nothing. Habits from other libraries land here too: an
|
|
34
34
|
accessor has no `.value`, `.set` or `.peek`, and writing goes through the setter that
|
|
35
|
-
`createSignal` returns beside it. A prop
|
|
36
|
-
`props.user
|
|
35
|
+
`createSignal` returns beside it. A prop is different: a component writes it as the value
|
|
36
|
+
and the compiler writes the read, so `props.user.email` is correct and is not reported.
|
|
37
37
|
|
|
38
38
|
`items.length` is reported too, with its own message. Every function has a `length`, so it
|
|
39
39
|
never comes back `undefined`: it is the accessor's parameter count, `0`, and a list that
|
package/docs/BARQ005.md
CHANGED
|
@@ -1,92 +1,25 @@
|
|
|
1
|
-
# BARQ005:
|
|
1
|
+
# BARQ005: removed
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The compiler does not report this code. [All codes](README.md)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
The rule reports at the misuse, and the message names what goes wrong there:
|
|
12
|
-
|
|
13
|
-
- A destructured name used as a value: in a template literal, with an arithmetic,
|
|
14
|
-
concatenating or relational operator, with unary `-`, `+` or `~`, or with a property read
|
|
15
|
-
from it (`text.length`). These are the positions where `props.text` gets
|
|
16
|
-
[BARQ001](BARQ001.md) or [BARQ003](BARQ003.md).
|
|
17
|
-
- A name with a default that is a literal and not a function, `{ tone = "warm" }`, used as
|
|
18
|
-
a value: it is the default when the prop is missing and a function when it is passed, so
|
|
19
|
-
the use is wrong whenever the prop is passed.
|
|
20
|
-
- The same name called, `tone()`: it throws when the prop is missing, because the default
|
|
21
|
-
is not a function.
|
|
22
|
-
- A pattern under a prop's key, `{ user: { name } }` or `{ items: [first] }`: it takes the
|
|
23
|
-
prop's function apart, which is wrong whether the prop is passed or not.
|
|
24
|
-
|
|
25
|
-
## Failing example
|
|
26
|
-
|
|
27
|
-
```tsx
|
|
28
|
-
export function Chip({ text }) {
|
|
29
|
-
return <span>{`#${text}`}</span>;
|
|
30
|
-
}
|
|
31
|
-
```
|
|
32
|
-
|
|
33
|
-
## Fixed example
|
|
5
|
+
BARQ005 warned that a name destructured from a component's props was the prop's Cell, a
|
|
6
|
+
function, and was being used as a value. Destructuring props is supported now: the compiler
|
|
7
|
+
makes each use of a destructured name the read it stands for, so the name is the value its
|
|
8
|
+
type says it is, it follows the prop, and a default applies whenever the prop is
|
|
9
|
+
`undefined`. There is nothing to warn about:
|
|
34
10
|
|
|
35
11
|
```tsx
|
|
36
|
-
export function Chip({ text }) {
|
|
37
|
-
return <span>{`#${text
|
|
12
|
+
export function Chip({ text, tone = "warm" }: { text: string; tone?: string }) {
|
|
13
|
+
return <span data-tone={tone}>{`#${text}`}</span>;
|
|
38
14
|
}
|
|
39
15
|
```
|
|
40
16
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
17
|
+
Two errors cover what destructuring cannot do. [BARQ030](BARQ030.md) reports an assignment
|
|
18
|
+
to a prop, a destructured name included. [BARQ031](BARQ031.md) reports a pattern that
|
|
19
|
+
cannot be kept reactive: a computed key, a default inside a nested pattern, or a rest
|
|
20
|
+
element inside one.
|
|
45
21
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
```tsx
|
|
49
|
-
import { omit } from "@barqjs/core";
|
|
50
|
-
|
|
51
|
-
export function Chip(props) {
|
|
52
|
-
const rest = omit(props, "tone");
|
|
53
|
-
return <span data-tone={props.tone?.() ?? "warm"} {...rest} />;
|
|
54
|
-
}
|
|
55
|
-
```
|
|
56
|
-
|
|
57
|
-
## Why this rule exists
|
|
58
|
-
|
|
59
|
-
A component receives each prop as a Cell: a function it calls to read the current value.
|
|
60
|
-
Destructuring copies those functions into local names, so `text` is a function. That is
|
|
61
|
-
what JSX wants, and it gives the function's source text or `NaN` everywhere a value is
|
|
62
|
-
needed. The checks for `props.name` ([BARQ001](BARQ001.md), [BARQ003](BARQ003.md)) cannot
|
|
63
|
-
follow the copies, so this rule reports the same positions for a destructured name.
|
|
64
|
-
|
|
65
|
-
A default in the pattern, `{ tone = "warm" }`, gives the name two kinds: the string
|
|
66
|
-
`"warm"` when the prop is missing and a function when it is passed. Calling it fails in the
|
|
67
|
-
first case and using it as a value fails in the second. Read such a prop with its default
|
|
68
|
-
where it is used instead:
|
|
69
|
-
|
|
70
|
-
```tsx
|
|
71
|
-
export function Chip({ tone }) {
|
|
72
|
-
return <span data-tone={tone?.() ?? "warm"} />;
|
|
73
|
-
}
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
A default that is itself a function, or a name the rule cannot see the value of, is not
|
|
77
|
-
reported, and neither is a name the component tests with `typeof` or reassigns.
|
|
78
|
-
|
|
79
|
-
## Silencing one line
|
|
80
|
-
|
|
81
|
-
```tsx
|
|
82
|
-
export function Chip({ text }) {
|
|
83
|
-
// barq-ignore-next-line BARQ005 (the debug panel shows the source text)
|
|
84
|
-
const label = `${text}`;
|
|
85
|
-
return <span>{label}</span>;
|
|
86
|
-
}
|
|
87
|
-
```
|
|
22
|
+
## If a comment still names it
|
|
88
23
|
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
92
|
-
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
|
24
|
+
`BARQ005` is not a code the compiler knows, so a comment that names it is reported as
|
|
25
|
+
[BARQ009](BARQ009.md) and silences nothing. Delete the comment.
|
package/docs/BARQ015.md
CHANGED
package/docs/BARQ018.md
CHANGED
|
@@ -28,7 +28,7 @@ import { createSignal } from "@barqjs/core";
|
|
|
28
28
|
const [online] = createSignal(true);
|
|
29
29
|
|
|
30
30
|
function Status(props) {
|
|
31
|
-
return props.online
|
|
31
|
+
return props.online ? <b>online</b> : <i>offline</i>;
|
|
32
32
|
}
|
|
33
33
|
|
|
34
34
|
export const Bar = () => <Status online={online()} />;
|
|
@@ -56,7 +56,7 @@ import { createSignal } from "@barqjs/core";
|
|
|
56
56
|
const [online] = createSignal(true);
|
|
57
57
|
|
|
58
58
|
function Status(props) {
|
|
59
|
-
return <>{props.online
|
|
59
|
+
return <>{props.online ? <b>online</b> : <i>offline</i>}</>;
|
|
60
60
|
}
|
|
61
61
|
|
|
62
62
|
export const Bar = () => <Status online={online()} />;
|
|
@@ -91,10 +91,10 @@ inside the returned element, make the same choice there.
|
|
|
91
91
|
|
|
92
92
|
The rule reports reads of signals, memos, stores and functions that read them. A prop is
|
|
93
93
|
reported only when this file renders the component with a value that changes, such as
|
|
94
|
-
`<Status online={online()} />`: every prop
|
|
95
|
-
caller passes anything that moves, and reading a configuration prop
|
|
96
|
-
type once is ordinary. So a component rendered only from other files is
|
|
97
|
-
its props.
|
|
94
|
+
`<Status online={online()} />`: every prop can change as far as the component can tell,
|
|
95
|
+
whether or not its caller passes anything that moves, and reading a configuration prop
|
|
96
|
+
such as an element type once is ordinary. So a component rendered only from other files is
|
|
97
|
+
not checked for its props.
|
|
98
98
|
|
|
99
99
|
## Silencing one line
|
|
100
100
|
|
package/docs/BARQ025.md
CHANGED
|
@@ -16,7 +16,7 @@ import { Dynamic } from "@barqjs/web";
|
|
|
16
16
|
import { Editor, Viewer } from "./fields";
|
|
17
17
|
|
|
18
18
|
export const Field = (props) => (
|
|
19
|
-
<Dynamic component={props.editing
|
|
19
|
+
<Dynamic component={props.editing ? Editor : Viewer} value={props.value} />
|
|
20
20
|
);
|
|
21
21
|
```
|
|
22
22
|
|
|
@@ -27,8 +27,8 @@ import { dynamic } from "@barqjs/web";
|
|
|
27
27
|
import { Editor, Viewer } from "./fields";
|
|
28
28
|
|
|
29
29
|
export const Field = (props) => {
|
|
30
|
-
const Chosen = dynamic(() => (props.editing
|
|
31
|
-
return <Chosen value={props.value
|
|
30
|
+
const Chosen = dynamic(() => (props.editing ? Editor : Viewer));
|
|
31
|
+
return <Chosen value={props.value} />;
|
|
32
32
|
};
|
|
33
33
|
```
|
|
34
34
|
|
|
@@ -39,7 +39,7 @@ A source may answer with a tag name as well as a component, or with `null`, `und
|
|
|
39
39
|
import { dynamic } from "@barqjs/web";
|
|
40
40
|
|
|
41
41
|
export const Heading = (props) => {
|
|
42
|
-
const Tag = dynamic(() => `h${props.level
|
|
42
|
+
const Tag = dynamic(() => `h${props.level}`);
|
|
43
43
|
return <Tag class="title">{props.children}</Tag>;
|
|
44
44
|
};
|
|
45
45
|
```
|
package/docs/BARQ027.md
CHANGED
|
@@ -24,7 +24,7 @@ export const Field = (props) => <input bind:value={props.text} />;
|
|
|
24
24
|
```tsx
|
|
25
25
|
// compiled with target: "universal"
|
|
26
26
|
export const Field = (props) => (
|
|
27
|
-
<input value={props.text
|
|
27
|
+
<input value={props.text} onChange={(next: string) => props.setText(next)} />
|
|
28
28
|
);
|
|
29
29
|
```
|
|
30
30
|
|
package/docs/BARQ028.md
CHANGED
|
@@ -16,14 +16,14 @@ The same message names `hydratable` (hydration claims the document's server mark
|
|
|
16
16
|
|
|
17
17
|
```tsx
|
|
18
18
|
// compiled with { target: "universal", ssr: true }
|
|
19
|
-
export const Scene = (props) => <box>{props.label
|
|
19
|
+
export const Scene = (props) => <box>{props.label}</box>;
|
|
20
20
|
```
|
|
21
21
|
|
|
22
22
|
## Fixed example
|
|
23
23
|
|
|
24
24
|
```tsx
|
|
25
25
|
// compiled with { target: "universal" }
|
|
26
|
-
export const Scene = (props) => <box>{props.label
|
|
26
|
+
export const Scene = (props) => <box>{props.label}</box>;
|
|
27
27
|
```
|
|
28
28
|
|
|
29
29
|
## Why this rule exists
|
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).
|