@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,68 @@
1
+ # BARQ026: Markup the browser's HTML parser builds differently from the JSX
2
+
3
+ **Level:** error · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `<div>` cannot be inside a `<p>`: the browser's HTML parser closes the paragraph at
8
+ > `<div>`, so the `<div>` lands after the `<p>` and the `</p>` that follows opens an empty
9
+ > one. A server-rendered page then hydrates against a tree that is not the one this JSX
10
+ > builds, which is a hydration mismatch and a full re-render in the browser. Move the `<div>`
11
+ > out of the `<p>`, or change the outer element (a `<div>` in place of a `<p>`, a `<span>` in
12
+ > place of an inner link).
13
+
14
+ The first sentence names what the parser does at that element. The other shapes it reports:
15
+
16
+ - a table part outside its parent, or anything but its parts inside a table: `<tr>`
17
+ directly in a `<table>` (the parser adds a `<tbody>`), `<td>` in a `<div>` (the parser
18
+ drops the tag), `<div>` in a `<tr>` (the parser moves it before the table).
19
+ - an element `<select>`, `<optgroup>` or `<option>` does not take.
20
+ - a second `<a>`, `<button>`, `<form>`, `<li>`, `<nobr>`, `<dd>` or `<dt>` inside an open one,
21
+ which the parser closes first.
22
+ - `<html>`, `<head>`, `<body>` and the obsolete `<frame>`, `<frameset>`, `<plaintext>`, which
23
+ are never an element of their own inside a page.
24
+
25
+ ## Failing example
26
+
27
+ ```tsx
28
+ export const Notice = (props) => (
29
+ <p>
30
+ Your order shipped.
31
+ <div class="details">{props.tracking}</div>
32
+ </p>
33
+ );
34
+ ```
35
+
36
+ ## Fixed example
37
+
38
+ ```tsx
39
+ export const Notice = (props) => (
40
+ <div>
41
+ <p>Your order shipped.</p>
42
+ <div class="details">{props.tracking}</div>
43
+ </div>
44
+ );
45
+ ```
46
+
47
+ ## Why this rule exists
48
+
49
+ A server render writes the markup as a string, and the browser parses that string with the
50
+ HTML parser, which repairs what HTML does not allow instead of keeping it. The page the
51
+ browser builds from `<p><div>…</div></p>` is `<p></p><div>…</div><p></p>`. Hydration then
52
+ walks a tree that is not the one the component builds, reports a mismatch, throws the
53
+ server's markup away and renders the page again. A client-only render does not show it,
54
+ because it builds elements one by one and never asks the parser.
55
+
56
+ The check follows JSX within one component: an element's children, and JSX that a
57
+ conditional, a `&&` or a list callback places where it stands. A component's children start
58
+ again, because the component decides where they go.
59
+
60
+ ## Silencing one line
61
+
62
+ ```tsx
63
+ // barq-ignore-next-line BARQ026 (rendered on the client only, never hydrated)
64
+ export const Legacy = () => <p><div>kept for an old stylesheet</div></p>;
65
+ ```
66
+
67
+ The reason in parentheses is required and has to be at least 10 characters. To change the
68
+ level for the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,53 @@
1
+ # BARQ027: A `bind:` or a form `action` is written for a custom renderer
2
+
3
+ **Level:** error · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `bind:` is a two-way binding to a document form control, and this element is built by a
8
+ > custom renderer, which has none. Pass the value as a prop and write it back from the
9
+ > host's own event: `value={text()}` with `onChange={(next) => setText(next)}`.
10
+
11
+ For `action` on a `<form>`, the message says that the action is a document form's submit
12
+ handler or URL and suggests calling it from the host's own event, such as
13
+ `onSubmit={() => save()}`.
14
+
15
+ ## Failing example
16
+
17
+ ```tsx
18
+ // compiled with target: "universal"
19
+ export const Field = (props) => <input bind:value={props.text} />;
20
+ ```
21
+
22
+ ## Fixed example
23
+
24
+ ```tsx
25
+ // compiled with target: "universal"
26
+ export const Field = (props) => (
27
+ <input value={props.text} onChange={(next: string) => props.setText(next)} />
28
+ );
29
+ ```
30
+
31
+ ## Why this rule exists
32
+
33
+ An element a custom renderer builds (in a module compiled with `target: "universal"`, a
34
+ file a `renderers` entry gives to one, or the children of a `boundaries` component whose
35
+ target is `universal`) has every attribute and event written as one `setProp` call on the
36
+ host's node, and the host decides what a name means. `bind:` needs two facts only a document form
37
+ control has: the property a user edits (`value`, `checked`, `valueAsNumber`) and the event
38
+ that reports the edit (`input`, `change`). A form `action` is the document's submit,
39
+ which a scene graph or a terminal does not have. Neither has a meaning the compiler could
40
+ write for an arbitrary host, so the module would build an element that silently never
41
+ updates, and the build fails instead. A literal `action="/save"` is an ordinary property
42
+ and is not reported.
43
+
44
+ ## Silencing one line
45
+
46
+ ```tsx
47
+ // barq-ignore-next-line BARQ027 (the host reads this name itself in a later version)
48
+ export const Field = (props) => <input bind:value={props.text} />;
49
+ ```
50
+
51
+ The reason in parentheses is required and has to be at least 10 characters. Silencing the
52
+ code does not make the binding work: nothing is emitted for it. To change the level for the
53
+ whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,56 @@
1
+ # BARQ028: A module compiled for a custom renderer is also asked for `ssr`, `hydratable` or `interp`
2
+
3
+ **Level:** error · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `ssr: true` was asked for together with `target: "universal"`, and the string backend
8
+ > renders the document's markup, which a custom host does not have. It was turned off for
9
+ > this module. Remove it from this module's options, or give the files of the custom
10
+ > renderer their own entry in `renderers`, which leaves `ssr` to the rest of the build.
11
+
12
+ The same message names `hydratable` (hydration claims the document's server markup) or
13
+ `interp` (the reference backend walks the document).
14
+
15
+ ## Failing example
16
+
17
+ ```tsx
18
+ // compiled with { target: "universal", ssr: true }
19
+ export const Scene = (props) => <box>{props.label}</box>;
20
+ ```
21
+
22
+ ## Fixed example
23
+
24
+ ```tsx
25
+ // compiled with { target: "universal" }
26
+ export const Scene = (props) => <box>{props.label}</box>;
27
+ ```
28
+
29
+ ## Why this rule exists
30
+
31
+ `ssr`, `hydratable` and `interp` each choose how a module reaches the document: as a string
32
+ of markup, as a client that claims that markup, or through the reference backend's walk. A
33
+ module compiled for a custom renderer reaches its own host instead, so asking for both is a
34
+ configuration that cannot mean anything. The compiler turns the document option off and
35
+ fails the build, so the mistake is seen rather than compiled into a bundle that ignores
36
+ half of what it was told.
37
+
38
+ An app that renders the document on the server and a custom host in the browser keeps
39
+ `ssr` and `hydratable` for its document files and gives the others a `renderers` entry,
40
+ which is not reported: the build's document options describe its document files, and the
41
+ files an entry gives to a custom renderer are not among them.
42
+
43
+ ```ts
44
+ barq({
45
+ ssr: true,
46
+ compiler: {
47
+ renderers: [{ include: ["src/scene/**"], target: "universal", moduleSource: "/src/renderer.ts" }],
48
+ },
49
+ });
50
+ ```
51
+
52
+ ## Turning it off
53
+
54
+ This code is about the options a module is compiled with rather than a line of it, so there
55
+ is no line to silence. To change the level for the whole project, see
56
+ [the index](README.md#changing-a-level-for-the-whole-project).
@@ -0,0 +1,57 @@
1
+ # BARQ029: Two renderers claim the same intrinsic tag
2
+
3
+ **Level:** warning · [all codes](README.md)
4
+
5
+ ## Message
6
+
7
+ > `<mesh>` is claimed by two renderers, `@acme/scene/renderer` and `@acme/other/renderer`, so
8
+ > it compiles for the document. Claim it in your own `intrinsics` configuration, which wins over
9
+ > what a package declares.
10
+
11
+ For a tag that no entry names and the document does not have, the message says that two
12
+ renderers claim every such tag (both declare `claimUnknown: true`).
13
+
14
+ ## Failing example
15
+
16
+ ```tsx
17
+ // two installed packages both list "mesh" under barq.intrinsics
18
+ export const Box = () => <mesh />;
19
+ ```
20
+
21
+ ## Fixed example
22
+
23
+ ```tsx
24
+ // the application's own intrinsics entry gives "mesh" to one of them
25
+ export const Box = () => <mesh />;
26
+ ```
27
+
28
+ ## Why this rule exists
29
+
30
+ A tree of intrinsic elements written outside every boundary builds through the renderer that
31
+ claims its root tag, so `function Box() { return <mesh /> }` is a scene object wherever it is
32
+ declared. When two renderers claim the tag, nothing in the source says which one the author
33
+ meant, and picking either would build the tree on a host the author may not render it into.
34
+ The tree compiles for the document instead, as it would with no renderer installed, and the
35
+ warning names both claimants.
36
+
37
+ An `intrinsics` entry in the application's own configuration takes the tag from every package
38
+ that declares it:
39
+
40
+ ```ts
41
+ barq({
42
+ compiler: {
43
+ intrinsics: [{ tags: ["mesh"], target: "universal", moduleSource: "@acme/scene/renderer" }],
44
+ },
45
+ });
46
+ ```
47
+
48
+ ## Silencing one line
49
+
50
+ ```tsx
51
+ // barq-ignore-next-line BARQ029 (this tree is only rendered in the document)
52
+ export const Box = () => <mesh />;
53
+ ```
54
+
55
+ The reason in parentheses is required and has to be at least 10 characters. Silencing the code
56
+ does not choose a renderer: the tree still compiles for the document. To change the level for
57
+ the whole project, see [the index](README.md#changing-a-level-for-the-whole-project).
@@ -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).