@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.
@@ -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
+ ```
@@ -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).
@@ -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).
@@ -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).
@@ -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).
@@ -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).
@@ -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).
@@ -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).
@@ -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).