@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 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: 26 [diagnostics](./docs/README.md),
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 prop crosses a component boundary as a Cell, a function the component calls:
51
- `props.name()`. Solid passes a getter on the props object and the component
52
- reads `props.name`.
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. The same
35
- applies to a prop, which is a Cell: write `props.count()`, not `props.count`, inside a
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, because `props.label ? a : b` is how a component asks whether
37
- an optional prop was passed at all.
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 works the same way: `props.user.email` has to be
36
- `props.user().email`.
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: A destructured prop is used as a value, or called where it may not be a function
1
+ # BARQ005: removed
2
2
 
3
- **Level:** warning · [all codes](README.md)
3
+ The compiler does not report this code. [All codes](README.md)
4
4
 
5
- ## Message
6
-
7
- > `text` comes from destructuring the props, so it is the prop's Cell, a function you call,
8
- > and here the function itself is used as the value. In a string it prints its own source
9
- > text and in arithmetic it gives `NaN`. Call it: `text()`.
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()}`}</span>;
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
- Writing a destructured name where a function is accepted is correct and is not reported:
42
- `{text}` as a JSX child or attribute, `text` passed to another function, `text()` anywhere.
43
- A truthiness test such as `text ? … : …` asks whether the prop was passed, as it does for
44
- `props.text`, and is not reported either.
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
- To pass the remaining props on, leave out the ones the component reads with `omit`:
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
- The reason in parentheses is required and has to be at least 10 characters. Between JSX
90
- children, write the comment as `{/* barq-ignore-next-line BARQ005 (reason) */}` on the line
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
@@ -31,7 +31,7 @@ const panel = css`
31
31
  `;
32
32
 
33
33
  export function Panel(props) {
34
- return <div class={panel} style={{ "--panel-bg": props.background() }} />;
34
+ return <div class={panel} style={{ "--panel-bg": props.background }} />;
35
35
  }
36
36
  ```
37
37
 
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() ? <b>online</b> : <i>offline</i>;
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() ? <b>online</b> : <i>offline</i>}</>;
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 is a function you call, whether or not its
95
- caller passes anything that moves, and reading a configuration prop such as an element
96
- type once is ordinary. So a component rendered only from other files is not checked for
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() ? Editor : Viewer} value={props.value()} />
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() ? Editor : Viewer));
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()} onChange={(next: string) => props.setText(next)} />
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()}</box>;
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()}</box>;
26
+ export const Scene = (props) => <box>{props.label}</box>;
27
27
  ```
28
28
 
29
29
  ## Why this rule exists
@@ -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).
@@ -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).
@@ -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).
@@ -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).
@@ -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).