@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.
@@ -0,0 +1,890 @@
1
+ ---
2
+ name: compiler-diagnostics
3
+ description: Map a barq compiler diagnostic code (BARQ001 to BARQ034) to its repair. Load when a build, the Vite dev overlay, the terminal or a transform result reports BARQ0NN at a file, line and column. Runtime [CODE] findings are in the diagnostics skill of @barqjs/core.
4
+ ---
5
+
6
+ # Repairing barq code from a compiler diagnostic code
7
+
8
+ The barq compiler reports each finding with a stable code, a level (`note`,
9
+ `warning` or `error`) and a position. Find the code's `### BARQ0NN` section
10
+ below: it says what the compiler saw, the repair, and the default level. An
11
+ `error` fails the build. A `warning` or `note` builds, and the code it points
12
+ at is still wrong or slower than it could be, so repair it.
13
+
14
+ Runtime codes such as `[REACTIVE_WRITE_IN_OWNED_SCOPE]` are a different family:
15
+ see `node_modules/@barqjs/core/skills/diagnostics/SKILL.md`.
16
+
17
+ ## How a code arrives
18
+
19
+ - **Terminal and build log**: one line per finding,
20
+ `file:line:col: BARQ0NN level: message`.
21
+ - **Vite dev overlay**: a pill in the corner of the page that lists compiler
22
+ findings with the source they are about. The `overlay` option of `barq()`
23
+ chooses what opens it (`"error"` by default).
24
+ - **`barq check`** from `@barqjs/cli`: every file of the project with no build.
25
+ `npx barq check --json` prints `{ summary, findings }`, each finding shaped as
26
+ below with `skill`, the section of this file for its code. `npx barq check
27
+ --fix` applies the repairs that are one spelling (BARQ001, BARQ002, BARQ003,
28
+ BARQ022, BARQ023 and the renames of BARQ024) and reports what is left.
29
+ - **The compiler's `transform` result**: the `diagnostics` array, one object
30
+ per finding, which serialises to JSON as below. `line` and `column` are
31
+ 1-based. `docs` is the code's page. `fix`, when present, is a list of
32
+ `{ pos, end, text }` edits over the source that repair the finding.
33
+
34
+ ```json
35
+ {
36
+ "code": "BARQ001",
37
+ "severity": "warning",
38
+ "message": "`count` is an accessor, and here the function itself is used as the value. ...",
39
+ "file": "src/App.tsx",
40
+ "line": 3,
41
+ "column": 42,
42
+ "endLine": 3,
43
+ "endColumn": 47,
44
+ "docs": "https://github.com/salamaashoush/barq/blob/main/packages/compiler/docs/BARQ001.md"
45
+ }
46
+ ```
47
+
48
+ A finding with no `code` is a syntax error from the parser: fix the syntax at
49
+ that position.
50
+
51
+ Each code also has a page with the full message and more examples at
52
+ `node_modules/@barqjs/compiler/docs/BARQ0NN.md`.
53
+
54
+ ## When each code is reported
55
+
56
+ - `BARQ001`, `BARQ002`, `BARQ003`, `BARQ011`, `BARQ018` to `BARQ021`: when the
57
+ `diagnostics` option is on. It is on in development builds, and
58
+ `barq({ compiler: { diagnostics: true } })` runs them in a production build.
59
+ - `BARQ004`, `BARQ010`: development builds only.
60
+ - `BARQ012` to `BARQ017`, `BARQ022` to `BARQ034`: every build.
61
+ - `BARQ008`, `BARQ009`: every build, about suppression comments.
62
+
63
+ `BARQ005`, `BARQ006` and `BARQ007` are retired and never reported. A
64
+ suppression comment that names one of them is reported as `BARQ009`: delete the
65
+ comment.
66
+
67
+ ## Setting a level
68
+
69
+ For the whole project, in `vite.config.ts`:
70
+
71
+ ```ts
72
+ import barq from "@barqjs/vite";
73
+ import { defineConfig } from "vite";
74
+
75
+ export default defineConfig({
76
+ plugins: [
77
+ barq({
78
+ compiler: {
79
+ checks: { BARQ004: "suppress", BARQ001: "error" },
80
+ defaultCategory: "warning",
81
+ },
82
+ }),
83
+ ],
84
+ });
85
+ ```
86
+
87
+ A level is `suppress`, `note`, `warning` or `error`. An entry in `checks` wins
88
+ over `strictCss` (which makes `BARQ014` to `BARQ017` errors), which wins over
89
+ `defaultCategory` (every code), which wins over the code's own default. When
90
+ calling the compiler's `transform` directly, `checks` is a list of pairs:
91
+ `checks: [["BARQ004", "suppress"]]`.
92
+
93
+ For one line, write a comment directly above the reported line, with the code
94
+ and a reason of at least 10 characters in parentheses:
95
+
96
+ ```tsx
97
+ // barq-ignore-next-line BARQ001 (the debug panel shows the source text)
98
+ const label = `${count}`;
99
+
100
+ <div>
101
+ {/* barq-ignore-next-line BARQ001 (the debug panel shows the source text) */}
102
+ <pre>{`${count}`}</pre>
103
+ </div>;
104
+ ```
105
+
106
+ Between JSX children the comment must be the `{/* ... */}` form. Repair the
107
+ code first. Suppress only a line that is correct as written, and say why in the
108
+ reason.
109
+
110
+ ## Accessors used as values
111
+
112
+ A signal's read half, a memo and a keyed `<For>` row are accessors: functions
113
+ that return the value. These three codes are about an accessor used without its
114
+ call. A prop is not an accessor: `props.count` and a destructured `count` are
115
+ values, and are never reported here.
116
+
117
+ ### BARQ001
118
+
119
+ Default level: warning.
120
+
121
+ An accessor is used as a value without being called, in a string or in
122
+ arithmetic. It prints its own source text, or gives `NaN`. Call it.
123
+
124
+ ```tsx
125
+ // before
126
+ <p>{`total: ${count}`}</p>
127
+
128
+ // after
129
+ <p>{`total: ${count()}`}</p>
130
+ ```
131
+
132
+ `<p>{count}</p>` and `<div id={count}>` are correct and are not reported.
133
+
134
+ ### BARQ002
135
+
136
+ Default level: warning.
137
+
138
+ An accessor is used as a condition (`if`, `? :`, `&&`, `!`, a loop test). A
139
+ function is always truthy, so one branch never runs. Call it.
140
+
141
+ ```tsx
142
+ // before
143
+ <p>{loading ? "Loading" : "Ready"}</p>
144
+
145
+ // after
146
+ <p>{loading() ? "Loading" : "Ready"}</p>
147
+ ```
148
+
149
+ ### BARQ003
150
+
151
+ Default level: warning.
152
+
153
+ A property is read from the accessor instead of from its value, so the result
154
+ is `undefined` (or `0` for `.length`, which is the function's parameter count).
155
+ Call it first. An accessor has no `.value`, `.set` or `.peek`.
156
+
157
+ ```tsx
158
+ // before
159
+ <p>{user.email}</p>
160
+ <p>{items.length} items</p>
161
+
162
+ // after
163
+ <p>{user().email}</p>
164
+ <p>{items().length} items</p>
165
+ ```
166
+
167
+ ## Lists
168
+
169
+ ### BARQ004
170
+
171
+ Default level: note.
172
+
173
+ A `<For>` row reads a field of its item once, while the row is built, and the
174
+ items may be store objects. A store changes a field in place, the row is kept,
175
+ and it goes on showing the old value. The reads that are reported: a
176
+ destructured row parameter, a read in statements above the row's JSX, a read
177
+ that picks which JSX to return.
178
+
179
+ Read the field in the row's JSX, or key the list and call the row:
180
+
181
+ ```tsx
182
+ // before
183
+ <For each={state.rows}>{({ name }) => <li>{name}</li>}</For>
184
+
185
+ // after
186
+ <For each={state.rows}>{(row) => <li>{row.name}</li>}</For>
187
+
188
+ // or
189
+ <For each={state.rows} keyed={(row) => row.id}>
190
+ {(row) => <li>{row().name}</li>}
191
+ </For>
192
+ ```
193
+
194
+ ### BARQ011
195
+
196
+ Default level: note.
197
+
198
+ `keyed={false}` on a `<For>` whose row holds an element with state of its own
199
+ (`input`, `textarea`, `select`, `video`, `audio`, `details`, `canvas`,
200
+ `dialog`, a custom element). Rows are reused by position, so typed text, the
201
+ caret or playback stays in place when the list reorders and ends up on another
202
+ item. Remove `keyed={false}`, or key by a stable field:
203
+
204
+ ```tsx
205
+ // before
206
+ <For each={todos} keyed={false}>
207
+ {(todo) => <input value={todo().text} />}
208
+ </For>
209
+
210
+ // after
211
+ <For each={todos} keyed={(todo) => todo.id}>
212
+ {(todo) => <input value={todo().text} />}
213
+ </For>
214
+ ```
215
+
216
+ ## Suppression comments
217
+
218
+ ### BARQ008
219
+
220
+ Default level: warning. Stays a warning under `defaultCategory: "error"`.
221
+
222
+ A `barq-ignore-next-line` comment names a code that nothing on the next line
223
+ reports. Delete the comment, or move it directly above the line the diagnostic
224
+ points at (it covers one line, not one statement). Between JSX children write
225
+ it as `{/* barq-ignore-next-line BARQ001 (reason) */}`.
226
+
227
+ ### BARQ009
228
+
229
+ Default level: warning. Stays a warning under `defaultCategory: "error"`.
230
+
231
+ A `barq-ignore-next-line` comment is malformed and silences nothing. The
232
+ message says what is missing: the code, a known code, a reason of at least 10
233
+ characters, or the closing parenthesis. Write the full form:
234
+
235
+ ```tsx
236
+ // before
237
+ // barq-ignore-next-line BARQ001
238
+
239
+ // after
240
+ // barq-ignore-next-line BARQ001 (the debug panel shows the source text)
241
+ ```
242
+
243
+ A comment naming the retired `BARQ005`, `BARQ006` or `BARQ007` is reported
244
+ here too: delete it.
245
+
246
+ ## Components and props
247
+
248
+ ### BARQ010
249
+
250
+ Default level: warning.
251
+
252
+ JSX is passed to a prop that the component (declared in the same file) reads as
253
+ a value: in an attribute, an event handler, a `ref`, or the `each`, `when` or
254
+ `mount` of a flow component. JSX passed as a prop can only be rendered as a
255
+ child, and reading it as a value throws `ScopeMissingError` at run time.
256
+
257
+ Pass a value, or change the component to render the prop as a child:
258
+
259
+ ```tsx
260
+ // before
261
+ function Card(props) {
262
+ return <section title={props.heading}>{props.children}</section>;
263
+ }
264
+ <Card heading={<b>Today</b>}>Hello</Card>;
265
+
266
+ // after: pass a value
267
+ <Card heading="Today">Hello</Card>;
268
+
269
+ // or: render the prop as a child
270
+ function Card(props) {
271
+ return (
272
+ <section>
273
+ <h2>{props.heading}</h2>
274
+ {props.children}
275
+ </section>
276
+ );
277
+ }
278
+ ```
279
+
280
+ ### BARQ018
281
+
282
+ Default level: warning.
283
+
284
+ A component chooses what to return (`if`, `switch`, an early `return`, a
285
+ ternary as the whole return value) from a signal, memo, store or changing prop
286
+ that it reads while its body runs. The body runs once, so the page keeps what
287
+ it showed first. Make the choice inside the returned JSX:
288
+
289
+ ```tsx
290
+ // before
291
+ function Greeting() {
292
+ if (!user()) return <button onClick={() => setUser("salama")}>Sign in</button>;
293
+ return <p>Hello, {user()}</p>;
294
+ }
295
+
296
+ // after
297
+ function Greeting() {
298
+ return (
299
+ <Show when={user()} fallback={<button onClick={() => setUser("salama")}>Sign in</button>}>
300
+ <p>Hello, {user()}</p>
301
+ </Show>
302
+ );
303
+ }
304
+ ```
305
+
306
+ For a prop, wrap the choice in a fragment so it is a JSX expression:
307
+
308
+ ```tsx
309
+ // before
310
+ function Status(props) {
311
+ return props.online ? <b>online</b> : <i>offline</i>;
312
+ }
313
+
314
+ // after
315
+ function Status(props) {
316
+ return <>{props.online ? <b>online</b> : <i>offline</i>}</>;
317
+ }
318
+ ```
319
+
320
+ A value that is read once on purpose says so: `if (!untrack(user)) ...`.
321
+
322
+ ### BARQ019
323
+
324
+ Default level: warning.
325
+
326
+ A setter (`createSignal`, `createStore`, `createOptimistic`,
327
+ `createOptimisticStore`) or an `action` is called while a component body, a
328
+ JSX expression, a memo or the first function of an effect runs. Development
329
+ builds throw `REACTIVE_WRITE_IN_OWNED_SCOPE` at that call. Derive the value, or
330
+ write from an event handler, `onSettled`, or the second function of
331
+ `createEffect`.
332
+
333
+ ```tsx
334
+ // before
335
+ function Counter() {
336
+ const [count, setCount] = createSignal(0);
337
+ setCount(1);
338
+ return <button onClick={() => setCount(count() + 1)}>{count()}</button>;
339
+ }
340
+
341
+ // after
342
+ function Counter() {
343
+ const [count, setCount] = createSignal(1);
344
+ return <button onClick={() => setCount(count() + 1)}>{count()}</button>;
345
+ }
346
+ ```
347
+
348
+ ```tsx
349
+ // before
350
+ const sync = createMemo(() => setTotal(price() * 2));
351
+
352
+ // after
353
+ const total = createMemo(() => price() * 2);
354
+ ```
355
+
356
+ ```tsx
357
+ // a write that follows a change
358
+ createEffect(
359
+ () => price(),
360
+ (value) => {
361
+ setHistory((list) => [...list, value]);
362
+ },
363
+ );
364
+ ```
365
+
366
+ ### BARQ020
367
+
368
+ Default level: warning.
369
+
370
+ A store is destructured in a component body, so each name holds the value its
371
+ property had when the body ran and never updates. Read the property where it
372
+ is used.
373
+
374
+ ```tsx
375
+ // before
376
+ function Badge() {
377
+ const { count, owner } = cart;
378
+ return (
379
+ <p>
380
+ {owner}: {count}
381
+ </p>
382
+ );
383
+ }
384
+
385
+ // after
386
+ function Badge() {
387
+ return (
388
+ <p>
389
+ {cart.owner}: {cart.count}
390
+ </p>
391
+ );
392
+ }
393
+ ```
394
+
395
+ Destructuring props is different and is supported: `const { title } = props`
396
+ stays live.
397
+
398
+ ### BARQ021
399
+
400
+ Default level: warning.
401
+
402
+ An async function passed to `createMemo`, `createProjection`, the function
403
+ forms of `createSignal` and `createStore`, or the first function of
404
+ `createEffect` reads a signal, memo, store or prop after its first `await`.
405
+ That read is not tracked, so the computation does not run again when it
406
+ changes. Read it before the first `await` and keep it in a local.
407
+
408
+ ```tsx
409
+ // before
410
+ const results = createMemo(async () => {
411
+ const response = await fetch("https://example.com/items");
412
+ const items = await response.json();
413
+ return items.filter((item) => item.tag === query());
414
+ });
415
+
416
+ // after
417
+ const results = createMemo(async () => {
418
+ const tag = query();
419
+ const response = await fetch("https://example.com/items");
420
+ const items = await response.json();
421
+ return items.filter((item) => item.tag === tag);
422
+ });
423
+ ```
424
+
425
+ ### BARQ030
426
+
427
+ Default level: error.
428
+
429
+ A prop is assigned (`=`, `+=`, `++`) through `props.name`, a destructured name,
430
+ or a member of what `omit(props, ...)` returns. Props are read-only: the parent
431
+ owns the value. Ask for the change through a function prop, or keep a signal of
432
+ your own.
433
+
434
+ ```tsx
435
+ // before
436
+ function Counter(props: { count: number }) {
437
+ return (
438
+ <button
439
+ onClick={() => {
440
+ props.count = props.count + 1;
441
+ }}
442
+ >
443
+ {props.count}
444
+ </button>
445
+ );
446
+ }
447
+
448
+ // after
449
+ function Counter(props: { count: number; onChange: (next: number) => void }) {
450
+ return <button onClick={() => props.onChange(props.count + 1)}>{props.count}</button>;
451
+ }
452
+ ```
453
+
454
+ ### BARQ031
455
+
456
+ Default level: error.
457
+
458
+ A props destructuring pattern has a shape that cannot stay reactive: a computed
459
+ key (`{ [key]: value }`), a default inside a nested pattern
460
+ (`{ user: { name = "guest" } }`), or a rest element inside a nested pattern
461
+ (`{ user: { id, ...others } }`). Destructure one level and read the rest where
462
+ it is used.
463
+
464
+ ```tsx
465
+ // before
466
+ function Card({ user: { name = "guest" } }: { user: { name?: string } }) {
467
+ return <p>{name}</p>;
468
+ }
469
+
470
+ // after
471
+ function Card({ user }: { user: { name?: string } }) {
472
+ return <p>{user.name ?? "guest"}</p>;
473
+ }
474
+ ```
475
+
476
+ One level (names, renames, defaults, a rest element) is always supported, and
477
+ so is a nested pattern with none of the three shapes.
478
+
479
+ ## Server functions and routes
480
+
481
+ ### BARQ012
482
+
483
+ Default level: error.
484
+
485
+ A module exports a server function (`createServerFn`) together with something
486
+ else, such as a component. The browser build replaces a server-function module
487
+ with request stubs, so it cannot keep any other export. Move the server
488
+ functions into a file that exports nothing else (types are allowed) and import
489
+ them.
490
+
491
+ ```tsx
492
+ // todos.server.ts: every export is a server function
493
+ import { createServerFn } from "@barqjs/start";
494
+
495
+ export const saveTodo = createServerFn({ method: "POST" }).handler(async () => {
496
+ return { saved: true };
497
+ });
498
+ ```
499
+
500
+ ```tsx
501
+ // TodoList.tsx
502
+ import { saveTodo } from "./todos.server.ts";
503
+
504
+ export function TodoList() {
505
+ return <button onClick={() => saveTodo()}>Save</button>;
506
+ }
507
+ ```
508
+
509
+ ### BARQ013
510
+
511
+ Default level: warning.
512
+
513
+ A `<Link to>` or `<NavLink to>` from `@barqjs/router` has a literal, absolute
514
+ path that matches none of the project's routes, so following it shows the
515
+ not-found page. Correct the path, or add the route file. The route pattern
516
+ itself matches too, with `params`:
517
+
518
+ ```tsx
519
+ // before, with routes "/", "/users" and "/users/$id"
520
+ <Link to="/user/7">Profile</Link>
521
+
522
+ // after
523
+ <Link to="/users/7">Profile</Link>
524
+
525
+ // or
526
+ <Link to="/users/$id" params={{ id: "7" }}>
527
+ Profile
528
+ </Link>
529
+ ```
530
+
531
+ ## Styles (`@barqjs/css`)
532
+
533
+ ### BARQ014
534
+
535
+ Default level: error.
536
+
537
+ A `css`, `keyframes` or `globalCss` block is not valid CSS. The message names
538
+ the problem: Sass or Less syntax, `@import`, `@charset` or `@namespace` outside
539
+ `globalCss`, a declaration at the top level of `globalCss` with no selector, or
540
+ an `&` with no parent selector. Write plain CSS.
541
+
542
+ ```tsx
543
+ // before
544
+ const card = css`
545
+ $brand: #3b82f6;
546
+ color: $brand;
547
+ `;
548
+
549
+ // after
550
+ const card = css`
551
+ --brand: #3b82f6;
552
+ color: var(--brand);
553
+ `;
554
+ ```
555
+
556
+ ### BARQ015
557
+
558
+ Default level: note. An error under `strictCss: true`.
559
+
560
+ A `css` block interpolates a value known only at run time, so its CSS is built
561
+ in the browser instead of at build time. Write a custom property in the block
562
+ and set its value on the element.
563
+
564
+ ```tsx
565
+ // before
566
+ const panel = (background: string) => css`
567
+ padding: 12px;
568
+ background: ${background};
569
+ `;
570
+
571
+ // after
572
+ const panel = css`
573
+ padding: 12px;
574
+ background: var(--panel-bg);
575
+ `;
576
+
577
+ function Panel(props) {
578
+ return <div class={panel} style={{ "--panel-bg": props.background }} />;
579
+ }
580
+ ```
581
+
582
+ ### BARQ016
583
+
584
+ Default level: note. An error under `strictCss: true`.
585
+
586
+ An `atoms` call has more than one conditional argument, and the compiler
587
+ compiles one, so the call runs in the browser. Merge the conditions into one
588
+ object, or nest the calls:
589
+
590
+ ```tsx
591
+ // before
592
+ atoms({ color: "red" }, active && { color: "blue" }, wide && { padding: 8 });
593
+
594
+ // after
595
+ atoms(atoms({ color: "red" }, active && { color: "blue" }), wide && { padding: 8 });
596
+ ```
597
+
598
+ ### BARQ017
599
+
600
+ Default level: note. An error under `strictCss: true`.
601
+
602
+ A `@barqjs/css` call (`atoms`, `create`, `defineVars`, `createTheme`,
603
+ `dynamic`) has a value, key or nested object the compiler cannot read in this
604
+ file: an import, a function call, a spread, a parameter. The call runs in the
605
+ browser. Write literals or a `const` declared in the same module. For a value
606
+ that changes, use `var(--name)` and set it through `style`, or a `dynamic`
607
+ group.
608
+
609
+ ```tsx
610
+ // before
611
+ import { theme } from "./theme.ts";
612
+ const card = atoms({ color: theme.brand });
613
+
614
+ // after
615
+ const BRAND = "#3b82f6";
616
+ const card = atoms({ color: BRAND });
617
+ ```
618
+
619
+ ### BARQ032
620
+
621
+ Default level: warning.
622
+
623
+ One `atoms` call (or one `create` group) holds a shorthand barq keeps whole,
624
+ such as `border`, `font`, `flex`, `background` or `transition`, together with
625
+ one of its longhands under the same condition. The two are separate classes, so
626
+ neither replaces the other, and which declaration wins depends on where each
627
+ rule happens to sit in the stylesheet. It can change when another component
628
+ uses either declaration first.
629
+
630
+ Write the shorthand as its longhands, so the later argument replaces exactly
631
+ what it names:
632
+
633
+ ```tsx
634
+ // before
635
+ atoms({ border: "1px solid gray" }, invalid && { borderColor: "red" });
636
+
637
+ // after
638
+ atoms(
639
+ { borderWidth: 1, borderStyle: "solid", borderColor: "gray" },
640
+ invalid && { borderColor: "red" },
641
+ );
642
+ ```
643
+
644
+ A shorthand that splits by counting (`margin`, `padding`, `inset`, `gap`,
645
+ `borderRadius`) is not reported: a later `marginTop` replaces one side.
646
+
647
+ ### BARQ033
648
+
649
+ Default level: note.
650
+
651
+ One `atoms` call (or one `create` group) sets a property under two conditions
652
+ of one tier that can both match one element, with selectors of one weight, and
653
+ writes them in the order the shared stylesheet reverses. Both classes stay on
654
+ the element and the fixed order decides: no interaction pseudo-class first,
655
+ then `:link`, `:visited`, `:focus-within`, `:hover`, `:focus`, `:focus-visible`,
656
+ `:active`, `:disabled`; ties by the condition's hash. The one written first wins
657
+ where both match.
658
+
659
+ Write the pair in the fixed order, or make one rule the other out:
660
+
661
+ ```tsx
662
+ // before
663
+ atoms({ color: { ":hover": "blue", "[data-active]": "red" } });
664
+
665
+ // after
666
+ atoms({ color: { "[data-active]": "red", ":hover": "blue" } });
667
+ // or, so the active colour holds under the pointer
668
+ atoms({ color: { "[data-active]": "red", ":not([data-active]):hover": "blue" } });
669
+ ```
670
+
671
+ Not reported: an attribute equal to two values, two different child positions,
672
+ a selector against its `:not()`, two media ranges of one feature that do not
673
+ meet, two selectors of different specificity, one value under both, two
674
+ pseudo-elements, or a pair the same object settles with a condition that is
675
+ both at once. Every reported pair is listed.
676
+
677
+ ### BARQ034
678
+
679
+ Default level: error.
680
+
681
+ A component destructures a prop with a string default and writes the name as a
682
+ tag. A tag is called as a component, so `"div"` can never render. An element
683
+ chosen at run time is `dynamic`:
684
+
685
+ ```tsx
686
+ // before
687
+ function Box({ as: Tag = "div", ...rest }) {
688
+ return <Tag {...rest} />;
689
+ }
690
+
691
+ // after
692
+ function Box(props) {
693
+ const Tag = dynamic(() => props.as ?? "div");
694
+ return <Tag {...omit(props, "as")} />;
695
+ }
696
+ ```
697
+
698
+ ## Solid 1.x spellings
699
+
700
+ These still parse, would build, and would misbehave at run time, so they are
701
+ errors.
702
+
703
+ ### BARQ022
704
+
705
+ Default level: error.
706
+
707
+ A context is rendered through `.Provider`. A context is its own provider.
708
+
709
+ ```tsx
710
+ // before
711
+ <Theme.Provider value="dark">{props.children}</Theme.Provider>
712
+
713
+ // after
714
+ <Theme value="dark">{props.children}</Theme>
715
+ ```
716
+
717
+ ### BARQ023
718
+
719
+ Default level: error.
720
+
721
+ `classList` is written on an element, where it is an ordinary attribute and
722
+ would be written as `[object Object]`. Pass the map to `class`, which takes a
723
+ string, a map of names to whether each applies, or a list of both.
724
+
725
+ ```tsx
726
+ // before
727
+ <div class="card" classList={{ active: active() }} />
728
+
729
+ // after
730
+ <div class={["card", { active: active() }]} />
731
+ ```
732
+
733
+ ### BARQ024
734
+
735
+ Default level: error.
736
+
737
+ An attribute uses a removed namespace prefix. Replace it by prefix:
738
+
739
+ - `on:x`: `onX={handler}`, or `addEventListener` in a `ref` for a hyphenated
740
+ event name or listener options.
741
+ - `capture:x`, `oncapture:x`: `onXCapture={handler}`.
742
+ - `attr:x`: `x={value}`.
743
+ - `bool:x`: `x={on()}`, where `true` adds the attribute and `false` removes it.
744
+ - `style:x`: a key of the `style` object.
745
+ - `class:x`: a key of the `class` map.
746
+ - `use:x`: `ref={x(options)}`, and `ref={[x(options), y]}` for several.
747
+
748
+ ```tsx
749
+ // before
750
+ <input on:input={props.onInput} />
751
+
752
+ // after
753
+ <input onInput={props.onInput} />
754
+ ```
755
+
756
+ `prop:` and `bind:` keep their meaning and are not reported.
757
+
758
+ ### BARQ025
759
+
760
+ Default level: error.
761
+
762
+ `<Dynamic component={...}>` is rendered. barq has the `dynamic` factory from
763
+ `@barqjs/web` instead. Hoist one to the component body (or to the module when
764
+ the choice reads only module state) and render it with the other props.
765
+
766
+ ```tsx
767
+ // before
768
+ import { Dynamic } from "@barqjs/web";
769
+ const Field = (props) => (
770
+ <Dynamic component={props.editing ? Editor : Viewer} value={props.value} />
771
+ );
772
+
773
+ // after
774
+ import { dynamic } from "@barqjs/web";
775
+ const Field = (props) => {
776
+ const Chosen = dynamic(() => (props.editing ? Editor : Viewer));
777
+ return <Chosen value={props.value} />;
778
+ };
779
+ ```
780
+
781
+ The source may answer with a tag name (`dynamic(() => "h" + props.level)`), or
782
+ with `null`, `undefined` or `false` to render nothing.
783
+
784
+ ## Markup
785
+
786
+ ### BARQ026
787
+
788
+ Default level: error.
789
+
790
+ The JSX nests elements in a way the browser's HTML parser rebuilds, so a
791
+ server-rendered page hydrates against a different tree (a
792
+ `HYDRATION_MISMATCH` and a full re-render). The message names the pair:
793
+
794
+ - a block element such as `<div>` inside a `<p>`;
795
+ - a table part outside its parent (`<tr>` directly in `<table>`, `<td>` in a
796
+ `<div>`), or a non-table element inside a `<tr>`;
797
+ - an element that `<select>`, `<optgroup>` or `<option>` does not take;
798
+ - a second `<a>`, `<button>`, `<form>`, `<li>`, `<dd>` or `<dt>` inside an open
799
+ one;
800
+ - `<html>`, `<head>` or `<body>` inside a page.
801
+
802
+ Move the inner element out, change the outer element, or write the wrapper the
803
+ parser expects (`<tbody>` around rows).
804
+
805
+ ```tsx
806
+ // before
807
+ <p>
808
+ Your order shipped.
809
+ <div class="details">{props.tracking}</div>
810
+ </p>
811
+
812
+ // after
813
+ <div>
814
+ <p>Your order shipped.</p>
815
+ <div class="details">{props.tracking}</div>
816
+ </div>
817
+ ```
818
+
819
+ ## Custom renderers
820
+
821
+ ### BARQ027
822
+
823
+ Default level: error.
824
+
825
+ A `bind:` attribute or a form `action` function is written on an element that a
826
+ custom renderer builds (`target: "universal"`). Both need a document form
827
+ control. Pass the value as a prop and write it back from the host's own event.
828
+
829
+ ```tsx
830
+ // before
831
+ <input bind:value={props.text} />
832
+
833
+ // after
834
+ <input value={props.text} onChange={(next: string) => props.setText(next)} />
835
+ ```
836
+
837
+ For `action`, call the function from the host's event:
838
+ `onSubmit={() => save()}`.
839
+
840
+ ### BARQ028
841
+
842
+ Default level: error.
843
+
844
+ A module compiled with `target: "universal"` is also asked for `ssr`,
845
+ `hydratable` or `interp`, which describe a document. This is about the build
846
+ options, not a line of source. Remove the document option from that module's
847
+ options, or give the custom renderer's files their own `renderers` entry and
848
+ keep `ssr` for the rest:
849
+
850
+ ```ts
851
+ barq({
852
+ ssr: true,
853
+ compiler: {
854
+ renderers: [
855
+ { include: ["src/scene/**"], target: "universal", moduleSource: "/src/renderer.ts" },
856
+ ],
857
+ },
858
+ });
859
+ ```
860
+
861
+ ### BARQ029
862
+
863
+ Default level: warning.
864
+
865
+ Two installed renderers claim the same intrinsic tag (the message names the tag
866
+ and both packages), so the tag compiles for the document. Claim it in the
867
+ application's own configuration, which wins over what a package declares:
868
+
869
+ ```ts
870
+ barq({
871
+ compiler: {
872
+ intrinsics: [{ tags: ["mesh"], target: "universal", moduleSource: "@acme/scene/renderer" }],
873
+ },
874
+ });
875
+ ```
876
+
877
+ ## What the compiler cannot see
878
+
879
+ The checks report only what one file proves, so silence is not a guarantee:
880
+
881
+ - An accessor imported from another module is not known to be one (`BARQ001`
882
+ to `BARQ003`), and `BARQ010` does not follow a prop into a component declared
883
+ in another file.
884
+ - A write inside a helper function the component body calls is not seen by
885
+ `BARQ019`. The runtime reports it as `REACTIVE_WRITE_IN_OWNED_SCOPE`.
886
+ - `BARQ018` counts a prop only where the same file renders the component with
887
+ a value that changes.
888
+ - `BARQ030` and `BARQ031` apply to components: a function with a capitalised
889
+ name that renders JSX, a default export that does, or a function written
890
+ inline at a route's `component` option.