@barqjs/compiler 0.0.0-stage → 0.2.0-next.0
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 +225 -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 +92 -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/README.md +129 -0
- package/index.d.ts +563 -0
- package/index.js +89 -0
- package/package.json +86 -4
package/docs/BARQ008.md
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# BARQ008: A `barq-ignore-next-line` comment silences nothing on the next line
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This `barq-ignore-next-line` names BARQ001, and nothing on the line below reports it,
|
|
8
|
+
> so the comment does nothing. Delete it, or move it to the line directly above the
|
|
9
|
+
> diagnostic; inside JSX, write it as `{/* barq-ignore-next-line ... */}`.
|
|
10
|
+
|
|
11
|
+
## Failing example
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
// barq-ignore-next-line BARQ001 (the debug panel shows the source text)
|
|
15
|
+
export const Label = () => <p>ok</p>;
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Fixed example
|
|
19
|
+
|
|
20
|
+
```tsx
|
|
21
|
+
export const Label = () => <p>ok</p>;
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Why this rule exists
|
|
25
|
+
|
|
26
|
+
A suppression that silences nothing is a leftover: the code it covered was fixed or moved.
|
|
27
|
+
Left in place, it would hide the next diagnostic with that code on that line without
|
|
28
|
+
anyone deciding that it should.
|
|
29
|
+
|
|
30
|
+
Two things produce this by accident. A comment covers the next line only, not the whole
|
|
31
|
+
statement, so it has to sit directly above the line the diagnostic points at. And between
|
|
32
|
+
JSX children a `//` line is text, so the comment has to be written as
|
|
33
|
+
`{/* barq-ignore-next-line BARQ001 (reason) */}`.
|
|
34
|
+
|
|
35
|
+
## Turning it off
|
|
36
|
+
|
|
37
|
+
This code has no per-line form, because a suppression of a suppression would need its own
|
|
38
|
+
check. It stays a warning even with `defaultCategory: "error"`, so a stale comment cannot
|
|
39
|
+
fail a build. To stop reporting it for the whole project:
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
barq({ compiler: { checks: { BARQ008: "suppress" } } });
|
|
43
|
+
```
|
package/docs/BARQ009.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# BARQ009: A `barq-ignore-next-line` comment is malformed and silences nothing
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This `barq-ignore-next-line` has no reason of at least 10 characters, so it silences
|
|
8
|
+
> nothing. Add one in parentheses: `// barq-ignore-next-line BARQ001 (why this is
|
|
9
|
+
> correct here)`.
|
|
10
|
+
|
|
11
|
+
## Failing example
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
// barq-ignore-next-line BARQ001
|
|
15
|
+
export const Label = () => <p>ok</p>;
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## Fixed example
|
|
19
|
+
|
|
20
|
+
```tsx
|
|
21
|
+
import { createSignal } from "@barqjs/core";
|
|
22
|
+
|
|
23
|
+
const [count] = createSignal(0);
|
|
24
|
+
|
|
25
|
+
// barq-ignore-next-line BARQ001 (the debug panel shows the source text)
|
|
26
|
+
export const source = `${count}`;
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Why this rule exists
|
|
30
|
+
|
|
31
|
+
A suppression comment has to say which diagnostic it silences and why:
|
|
32
|
+
`// barq-ignore-next-line CODE (reason of at least 10 characters)`. Several codes can be
|
|
33
|
+
listed, separated by commas or spaces. Naming the code keeps the comment from hiding an
|
|
34
|
+
unrelated diagnostic that later lands on the same line, and the reason tells the next
|
|
35
|
+
reader why the code is right.
|
|
36
|
+
|
|
37
|
+
A comment that does not fit that form silences nothing, so the diagnostic it was aimed at
|
|
38
|
+
is still reported beside this one. The message says which part is missing: the code, a
|
|
39
|
+
known code, the reason, or the closing parenthesis.
|
|
40
|
+
|
|
41
|
+
## Turning it off
|
|
42
|
+
|
|
43
|
+
This code has no per-line form. It stays a warning even with `defaultCategory: "error"`,
|
|
44
|
+
so a comment cannot fail a build. To stop reporting it for the whole project:
|
|
45
|
+
|
|
46
|
+
```ts
|
|
47
|
+
barq({ compiler: { checks: { BARQ009: "suppress" } } });
|
|
48
|
+
```
|
package/docs/BARQ010.md
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# BARQ010: JSX is passed to a prop the component reads as a value, which throws
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `heading` is JSX here, and `Card` reads `props.heading` as a value in the `title`
|
|
8
|
+
> attribute of an element. JSX cannot be read as a value, so `Card` throws
|
|
9
|
+
> `ScopeMissingError` when it reads the prop. Pass a value instead of JSX, or change
|
|
10
|
+
> `Card` to render the prop as a child: `{props.heading}`.
|
|
11
|
+
|
|
12
|
+
## Failing example
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
function Card(props) {
|
|
16
|
+
return <section title={props.heading}>{props.children}</section>;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export const Page = () => <Card heading={<b>Today</b>}>Hello</Card>;
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Fixed example
|
|
23
|
+
|
|
24
|
+
Pass a value:
|
|
25
|
+
|
|
26
|
+
```tsx
|
|
27
|
+
function Card(props) {
|
|
28
|
+
return <section title={props.heading}>{props.children}</section>;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export const Page = () => <Card heading="Today">Hello</Card>;
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Or keep the JSX and render the prop as a child:
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
function Card(props) {
|
|
38
|
+
return (
|
|
39
|
+
<section>
|
|
40
|
+
<h2>{props.heading}</h2>
|
|
41
|
+
{props.children}
|
|
42
|
+
</section>
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export const Page = () => <Card heading={<b>Today</b>}>Hello</Card>;
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Why this rule exists
|
|
50
|
+
|
|
51
|
+
A prop written as JSX is not a value. It is markup that is built at the place the
|
|
52
|
+
component renders it, so the only thing a component can do with it is render it as a
|
|
53
|
+
child. An attribute, an event handler, a `ref`, and the `each`, `when` or `mount` of a
|
|
54
|
+
flow component all need a value, and barq throws `ScopeMissingError` there instead of
|
|
55
|
+
writing something meaningless into the page.
|
|
56
|
+
|
|
57
|
+
Inside one file the compiler sees both ends, the JSX being passed and the place that
|
|
58
|
+
reads it, so it reports the mismatch before the page runs. It follows a prop that one
|
|
59
|
+
component hands to another in the same file. Across files, or through a spread, only the
|
|
60
|
+
run-time error reports it.
|
|
61
|
+
|
|
62
|
+
## Silencing one line
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
function Card(props) {
|
|
66
|
+
return <section title={props.heading}>{props.children}</section>;
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
// barq-ignore-next-line BARQ010 (this branch is replaced before it renders)
|
|
70
|
+
export const Page = () => <Card heading={<b>Today</b>}>Hello</Card>;
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
74
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ010 (reason) */}` on the line
|
|
75
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
76
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ011.md
ADDED
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# BARQ011: `keyed={false}` keeps element state in place when the list reorders
|
|
2
|
+
|
|
3
|
+
**Level:** note · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `keyed={false}` reuses each row's elements by position, so what the user did inside
|
|
8
|
+
> `<input>` (typed text, the caret, a selection, playback, open or closed) stays in that
|
|
9
|
+
> position when the list reorders and ends up on a different item. Remove
|
|
10
|
+
> `keyed={false}` so a row moves with its item, or key by a stable field: `keyed={(row)
|
|
11
|
+
> => row.id}`.
|
|
12
|
+
|
|
13
|
+
## Failing example
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { For, createSignal } from "@barqjs/core";
|
|
17
|
+
|
|
18
|
+
const [todos] = createSignal([{ id: 1, text: "Write the docs" }]);
|
|
19
|
+
|
|
20
|
+
export const Todos = () => (
|
|
21
|
+
<ul>
|
|
22
|
+
<For each={todos} keyed={false}>
|
|
23
|
+
{(todo) => (
|
|
24
|
+
<li>
|
|
25
|
+
<input value={todo().text} />
|
|
26
|
+
</li>
|
|
27
|
+
)}
|
|
28
|
+
</For>
|
|
29
|
+
</ul>
|
|
30
|
+
);
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Fixed example
|
|
34
|
+
|
|
35
|
+
```tsx
|
|
36
|
+
import { For, createSignal } from "@barqjs/core";
|
|
37
|
+
|
|
38
|
+
const [todos] = createSignal([{ id: 1, text: "Write the docs" }]);
|
|
39
|
+
|
|
40
|
+
export const Todos = () => (
|
|
41
|
+
<ul>
|
|
42
|
+
<For each={todos} keyed={(todo) => todo.id}>
|
|
43
|
+
{(todo) => (
|
|
44
|
+
<li>
|
|
45
|
+
<input value={todo().text} />
|
|
46
|
+
</li>
|
|
47
|
+
)}
|
|
48
|
+
</For>
|
|
49
|
+
</ul>
|
|
50
|
+
);
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Why this rule exists
|
|
54
|
+
|
|
55
|
+
With `keyed={false}` the first row is always the first `<li>`, whichever item is in it.
|
|
56
|
+
What barq writes follows the item, but what the browser keeps inside an element does not:
|
|
57
|
+
the text being typed, the caret, a selection, a `<video>`'s position, an open `<details>`.
|
|
58
|
+
After a reorder or a removal that state sits on a different item.
|
|
59
|
+
|
|
60
|
+
The note looks at elements written directly in the row: `input`, `textarea`, `select`,
|
|
61
|
+
`video`, `audio`, `details`, `canvas`, `dialog` and custom elements. It cannot see inside
|
|
62
|
+
a component used in the row, so its silence does not mean a row holds no such state.
|
|
63
|
+
|
|
64
|
+
## Silencing one line
|
|
65
|
+
|
|
66
|
+
```tsx
|
|
67
|
+
import { For, createSignal } from "@barqjs/core";
|
|
68
|
+
|
|
69
|
+
const [todos] = createSignal([{ id: 1, text: "Write the docs" }]);
|
|
70
|
+
|
|
71
|
+
export const Todos = () => (
|
|
72
|
+
<ul>
|
|
73
|
+
<For each={todos} keyed={false}>
|
|
74
|
+
{(todo) => (
|
|
75
|
+
<li>
|
|
76
|
+
{/* barq-ignore-next-line BARQ011 (this list is append-only) */}
|
|
77
|
+
<input value={todo().text} />
|
|
78
|
+
</li>
|
|
79
|
+
)}
|
|
80
|
+
</For>
|
|
81
|
+
</ul>
|
|
82
|
+
);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
86
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ011 (reason) */}` on the line
|
|
87
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
88
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ012.md
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# BARQ012: A module exports server functions together with other things
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This module exports a server function and also `TodoList`. The browser build replaces
|
|
8
|
+
> a module that exports server functions with request stubs, so it cannot keep anything
|
|
9
|
+
> else the module exports. Move the server functions into a file that exports nothing
|
|
10
|
+
> else, and import them from here.
|
|
11
|
+
|
|
12
|
+
## Failing example
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
import { createServerFn } from "@barqjs/start";
|
|
16
|
+
|
|
17
|
+
export const saveTodo = createServerFn({ method: "POST" }).handler(async () => {
|
|
18
|
+
return { saved: true };
|
|
19
|
+
});
|
|
20
|
+
|
|
21
|
+
export function TodoList() {
|
|
22
|
+
return <button onClick={() => saveTodo()}>Save</button>;
|
|
23
|
+
}
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Fixed example
|
|
27
|
+
|
|
28
|
+
`todos.server.ts`, where every export is a server function. The file name is yours to choose:
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
import { createServerFn } from "@barqjs/start";
|
|
32
|
+
|
|
33
|
+
export const saveTodo = createServerFn({ method: "POST" }).handler(async () => {
|
|
34
|
+
return { saved: true };
|
|
35
|
+
});
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`TodoList.tsx`:
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
import { saveTodo } from "./todos.server.ts";
|
|
42
|
+
|
|
43
|
+
export function TodoList() {
|
|
44
|
+
return <button onClick={() => saveTodo()}>Save</button>;
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Why this rule exists
|
|
49
|
+
|
|
50
|
+
In the browser build, a module whose exports are all server functions is replaced by one
|
|
51
|
+
that exports a request stub under each name. The handler code, its validators and what
|
|
52
|
+
they import (a database client, a secret) never reach the browser. That replacement only
|
|
53
|
+
works when every export can be a stub. A component cannot be one, and keeping the module
|
|
54
|
+
to keep the component would ship the handlers with it, so the build stops.
|
|
55
|
+
|
|
56
|
+
Types (`export type`, `export interface`) do not count as other exports, and neither does
|
|
57
|
+
a server function that is not exported.
|
|
58
|
+
|
|
59
|
+
## Silencing one line
|
|
60
|
+
|
|
61
|
+
```tsx
|
|
62
|
+
import { createServerFn } from "@barqjs/start";
|
|
63
|
+
|
|
64
|
+
export const saveTodo = createServerFn({ method: "POST" }).handler(async () => {
|
|
65
|
+
return { saved: true };
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
// barq-ignore-next-line BARQ012 (this module is only ever imported by server code)
|
|
69
|
+
export function TodoList() {
|
|
70
|
+
return <button onClick={() => saveTodo()}>Save</button>;
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The comment goes above the first export that is not a server function, which is where the
|
|
75
|
+
diagnostic points. Silencing it does not split the module: the browser build then keeps
|
|
76
|
+
the whole file, handlers included, so use it only for a module the browser never imports.
|
|
77
|
+
|
|
78
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
79
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ012 (reason) */}` on the line
|
|
80
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
81
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ013.md
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# BARQ013: `<Link to>` names a path that no route matches
|
|
2
|
+
|
|
3
|
+
**Level:** warning · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `to="/user/7"` matches none of this project's routes, so following this link shows the
|
|
8
|
+
> not-found page. Correct the path, or add a route for it.
|
|
9
|
+
|
|
10
|
+
## Failing example
|
|
11
|
+
|
|
12
|
+
With the routes `/`, `/users` and `/users/$id`:
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
import { Link } from "@barqjs/router";
|
|
16
|
+
|
|
17
|
+
export const Nav = () => <Link to="/user/7">Profile</Link>;
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Fixed example
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { Link } from "@barqjs/router";
|
|
24
|
+
|
|
25
|
+
export const Nav = () => <Link to="/users/7">Profile</Link>;
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The route pattern itself also matches, which is the form to use with `params`:
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
import { Link } from "@barqjs/router";
|
|
32
|
+
|
|
33
|
+
export const Nav = () => (
|
|
34
|
+
<Link to="/users/$id" params={{ id: "7" }}>
|
|
35
|
+
Profile
|
|
36
|
+
</Link>
|
|
37
|
+
);
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Why this rule exists
|
|
41
|
+
|
|
42
|
+
A mistyped path is not an error anywhere else: it type-checks, it renders, and it fails
|
|
43
|
+
only when someone follows the link. This check compares the path with the project's
|
|
44
|
+
routes at build time.
|
|
45
|
+
|
|
46
|
+
It runs when the build knows the routes (file-based routing passes them to the compiler)
|
|
47
|
+
and only for a literal, absolute `to` on a `Link` or `NavLink` imported from
|
|
48
|
+
`@barqjs/router`. A variable, a relative path, an external URL and a `#fragment` are not
|
|
49
|
+
checked.
|
|
50
|
+
|
|
51
|
+
## Silencing one line
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
import { Link } from "@barqjs/router";
|
|
55
|
+
|
|
56
|
+
// barq-ignore-next-line BARQ013 (this path is served by another application)
|
|
57
|
+
export const Nav = () => <Link to="/user/7">Profile</Link>;
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
61
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ013 (reason) */}` on the line
|
|
62
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
63
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ014.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# BARQ014: A `css`, `keyframes` or `globalCss` block is not valid CSS
|
|
2
|
+
|
|
3
|
+
**Level:** error · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This CSS could not be compiled. A Sass variable (`$name: value`) is preprocessor
|
|
8
|
+
> syntax, and `@barqjs/css` compiles plain CSS only. Rewrite it as CSS; for a variable,
|
|
9
|
+
> use a custom property: `--brand: red` and `var(--brand)`.
|
|
10
|
+
|
|
11
|
+
## Failing example
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
import { css } from "@barqjs/css";
|
|
15
|
+
|
|
16
|
+
export const card = css`
|
|
17
|
+
$brand: #3b82f6;
|
|
18
|
+
color: $brand;
|
|
19
|
+
`;
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Fixed example
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import { css } from "@barqjs/css";
|
|
26
|
+
|
|
27
|
+
export const card = css`
|
|
28
|
+
--brand: #3b82f6;
|
|
29
|
+
color: var(--brand);
|
|
30
|
+
`;
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
## Why this rule exists
|
|
34
|
+
|
|
35
|
+
`css`, `keyframes` and `globalCss` blocks are compiled into a stylesheet at build time,
|
|
36
|
+
so a block has to be CSS a browser understands. Sass and Less syntax would be written out
|
|
37
|
+
as rules no browser applies, and the element would lose its styles without any error.
|
|
38
|
+
|
|
39
|
+
Three placement rules are reported under this code as well: `@import`, `@charset` and
|
|
40
|
+
`@namespace` belong in a `globalCss` block; a declaration at the top level of `globalCss`
|
|
41
|
+
needs a selector around it; and `&` needs a parent selector to stand for.
|
|
42
|
+
|
|
43
|
+
## Silencing one line
|
|
44
|
+
|
|
45
|
+
```tsx
|
|
46
|
+
import { css } from "@barqjs/css";
|
|
47
|
+
|
|
48
|
+
// barq-ignore-next-line BARQ014 (kept as written until the Sass migration lands)
|
|
49
|
+
export const card = css`
|
|
50
|
+
$brand: #3b82f6;
|
|
51
|
+
color: $brand;
|
|
52
|
+
`;
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Silencing it does not make the block valid. The call is left as written, and
|
|
56
|
+
`@barqjs/css` meets the same text in the browser.
|
|
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 BARQ014 (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/BARQ015.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# BARQ015: A `css` block interpolates a runtime value, so the browser builds it
|
|
2
|
+
|
|
3
|
+
**Level:** note · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This block interpolates a value that is only known when the program runs, so it cannot
|
|
8
|
+
> be compiled and `@barqjs/css` builds its CSS in the browser instead. To compile it,
|
|
9
|
+
> write `var(--name)` in the block and set the value on the element: `style={{ "--name":
|
|
10
|
+
> value }}`.
|
|
11
|
+
|
|
12
|
+
## Failing example
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
import { css } from "@barqjs/css";
|
|
16
|
+
|
|
17
|
+
export const panel = (background: string) => css`
|
|
18
|
+
padding: 12px;
|
|
19
|
+
background: ${background};
|
|
20
|
+
`;
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Fixed example
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import { css } from "@barqjs/css";
|
|
27
|
+
|
|
28
|
+
const panel = css`
|
|
29
|
+
padding: 12px;
|
|
30
|
+
background: var(--panel-bg);
|
|
31
|
+
`;
|
|
32
|
+
|
|
33
|
+
export function Panel(props) {
|
|
34
|
+
return <div class={panel} style={{ "--panel-bg": props.background() }} />;
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## Why this rule exists
|
|
39
|
+
|
|
40
|
+
A block whose text is fixed is compiled away: its CSS goes into the stylesheet and the
|
|
41
|
+
call becomes a class name. An interpolation that is a literal, or a `const` in the same
|
|
42
|
+
file that holds one, still counts as fixed. Any other value is only known when the
|
|
43
|
+
program runs, so the block's CSS is put together in the browser every time it is
|
|
44
|
+
evaluated, and `@barqjs/css` has to ship the code that does it.
|
|
45
|
+
|
|
46
|
+
Nothing is broken, and the styles still apply. The note marks a block that could be
|
|
47
|
+
static.
|
|
48
|
+
|
|
49
|
+
## Silencing one line
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
import { css } from "@barqjs/css";
|
|
53
|
+
|
|
54
|
+
// barq-ignore-next-line BARQ015 (the colour comes from user settings)
|
|
55
|
+
export const panel = (background: string) => css`
|
|
56
|
+
padding: 12px;
|
|
57
|
+
background: ${background};
|
|
58
|
+
`;
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
62
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ015 (reason) */}` on the line
|
|
63
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
64
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ016.md
ADDED
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
# BARQ016: `atoms` has several conditional arguments, so the browser evaluates it
|
|
2
|
+
|
|
3
|
+
**Level:** note · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> `atoms` has 2 conditional arguments and the compiler handles one, so this call is left
|
|
8
|
+
> as written and `@barqjs/css` works out its classes in the browser each time it runs.
|
|
9
|
+
> Merge the conditions into one object, or apply the second with its own call:
|
|
10
|
+
> `atoms(atoms(base, a && x), b && y)`.
|
|
11
|
+
|
|
12
|
+
## Failing example
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
import { atoms } from "@barqjs/css";
|
|
16
|
+
|
|
17
|
+
export const button = (active: boolean, wide: boolean) =>
|
|
18
|
+
atoms({ color: "red" }, active && { color: "blue" }, wide && { padding: 8 });
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Fixed example
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { atoms } from "@barqjs/css";
|
|
25
|
+
|
|
26
|
+
export const button = (active: boolean, wide: boolean) =>
|
|
27
|
+
atoms(atoms({ color: "red" }, active && { color: "blue" }), wide && { padding: 8 });
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Why this rule exists
|
|
31
|
+
|
|
32
|
+
One conditional argument compiles to a choice between two class strings. Each further
|
|
33
|
+
condition doubles the number of outcomes, and writing all of them out would be larger
|
|
34
|
+
than the call it replaces, so the compiler leaves the call as it is.
|
|
35
|
+
|
|
36
|
+
Nothing is broken: `atoms` produces the same classes in the browser. The note marks a
|
|
37
|
+
call that could be compiled.
|
|
38
|
+
|
|
39
|
+
## Silencing one line
|
|
40
|
+
|
|
41
|
+
```tsx
|
|
42
|
+
import { atoms } from "@barqjs/css";
|
|
43
|
+
|
|
44
|
+
export const button = (active: boolean, wide: boolean) =>
|
|
45
|
+
// barq-ignore-next-line BARQ016 (all four combinations are used)
|
|
46
|
+
atoms({ color: "red" }, active && { color: "blue" }, wide && { padding: 8 });
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
50
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ016 (reason) */}` on the line
|
|
51
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
52
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|
package/docs/BARQ017.md
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# BARQ017: A `@barqjs/css` call cannot be compiled, so the browser evaluates it
|
|
2
|
+
|
|
3
|
+
**Level:** note · [all codes](README.md)
|
|
4
|
+
|
|
5
|
+
## Message
|
|
6
|
+
|
|
7
|
+
> This style object has a value, a key or a nested object the compiler cannot read in
|
|
8
|
+
> this file, such as an imported value or a function call. The call is left as written,
|
|
9
|
+
> and `@barqjs/css` works out its classes in the browser each time it runs. Write
|
|
10
|
+
> literals or a `const` declared in this module; for a value that changes, use
|
|
11
|
+
> `var(--name)` and set it through `style`.
|
|
12
|
+
|
|
13
|
+
## Failing example
|
|
14
|
+
|
|
15
|
+
```tsx
|
|
16
|
+
import { atoms } from "@barqjs/css";
|
|
17
|
+
import { theme } from "./theme.ts";
|
|
18
|
+
|
|
19
|
+
export const card = atoms({ color: theme.brand });
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## Fixed example
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import { atoms } from "@barqjs/css";
|
|
26
|
+
|
|
27
|
+
const BRAND = "#3b82f6";
|
|
28
|
+
|
|
29
|
+
export const card = atoms({ color: BRAND });
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
## Why this rule exists
|
|
33
|
+
|
|
34
|
+
`atoms`, `create`, `defineVars`, `createTheme`, `dynamic` and their layered forms are
|
|
35
|
+
compiled when every value in the call can be read from the file being compiled: literals,
|
|
36
|
+
and `const`s declared in the same module. A value imported from another module, the result
|
|
37
|
+
of a function call, or a spread of arguments cannot be read that way, so the call stays
|
|
38
|
+
and runs in the browser. A `dynamic` group turns each value into one custom property, so a
|
|
39
|
+
`firstThatWorks` list inside one cannot be compiled either: keep the fallback in a `create`
|
|
40
|
+
group passed to `props` beside it.
|
|
41
|
+
|
|
42
|
+
A value bound inside a function, such as a parameter or a local variable, is reported
|
|
43
|
+
with its own message: a value that changes belongs in a `dynamic` group, whose class is
|
|
44
|
+
compiled and whose value is set as a custom property when it arrives.
|
|
45
|
+
|
|
46
|
+
Nothing is broken, and the classes are the same. The note marks a call that could be
|
|
47
|
+
compiled; the message says which part stopped it. To make every CSS note an error, so a
|
|
48
|
+
build proves that no call is left for the browser, set `barq({ compiler: { strictCss: true } })`.
|
|
49
|
+
|
|
50
|
+
## Silencing one line
|
|
51
|
+
|
|
52
|
+
```tsx
|
|
53
|
+
import { atoms } from "@barqjs/css";
|
|
54
|
+
import { theme } from "./theme.ts";
|
|
55
|
+
|
|
56
|
+
// barq-ignore-next-line BARQ017 (the brand colour is shared with another package)
|
|
57
|
+
export const card = atoms({ color: theme.brand });
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The reason in parentheses is required and has to be at least 10 characters. Between JSX
|
|
61
|
+
children, write the comment as `{/* barq-ignore-next-line BARQ017 (reason) */}` on the line
|
|
62
|
+
above: a `//` line there is text and would be rendered on the page. To change the level
|
|
63
|
+
for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
|