# Diagnostics

> Every diagnostic the Unframework compiler reports, by its stable UF code, with what it means and how to fix it.

The compiler reports every problem it finds as a diagnostic, with a stable code such as `UF3013`. A code is never reused or renumbered. The compiler never copies code it has not analysed into an output, so anything it cannot lower to every target is a diagnostic, never a silent difference.

The [CLI](/docs/tooling/cli) and the [bundler plugin](/docs/tooling/bundler-plugin) report codes too, for a config, a project or a build rather than one component, like `UF7003` for an unknown target or `UF7005` when the plugin can't tell your framework. Some of those have no place in a source to point at. They name the file they concern, like `unframework.config.ts` or your Vite config, at its start, and the message says what's wrong, naming a config's field by its JSON pointer.

A diagnostic has a severity, a message that names what was found, the place in the source, help, and, where the rewrite is mechanical, fixes. Only an error stops a component from compiling. A fix is `safe` when it can be applied without a review, and `likely` when it needs one. The compiler links each code to its section on this page.

This file has no `key` on its list item:

<!-- prettier-ignore -->
```tsx [TagList.uf.tsx]
// UF3013 missing-key: a list item without `key`; the likely fix keys it by its index.
export interface TagListProps {
  tags: string[];
}

export default function TagList({ tags }: TagListProps) {
  return (
    <ul>
      {tags.map((tag) => (
        <li>{tag}</li>
      ))}
    </ul>
  );
}
```

The compiler reports it, with a likely fix:

<!-- prettier-ignore -->
```json [diagnostics.json]
[
  {
    "code": "UF3013",
    "severity": "error",
    "message": "A list's element needs a `key`: the frameworks match each item's element across renders by it.",
    "file": "diagnostics/missing-key/TagList.uf.tsx",
    "start": {
      "line": 10,
      "column": 10,
      "offset": 254
    },
    "end": {
      "line": 10,
      "column": 12,
      "offset": 256
    },
    "help": "Key it by something unique and stable in the item: `key={item.id}`.",
    "fixes": [
      {
        "title": "Key the element by its index, `key={index}`",
        "confidence": "likely",
        "edits": [
          {
            "span": {
              "start": 238,
              "end": 238
            },
            "text": ", index"
          },
          {
            "span": {
              "start": 256,
              "end": 256
            },
            "text": " key={index}"
          }
        ]
      }
    ]
  }
]
```

Codes are grouped in bands:

| Band   | Covers                        |
| ------ | ----------------------------- |
| UF1xxx | Syntax and components         |
| UF2xxx | Setup and macros              |
| UF3xxx | JSX and cross-component usage |
| UF4xxx | Portability (capabilities)    |
| UF5xxx | Styles                        |
| UF6xxx | Types                         |
| UF7xxx | Config and tooling            |
| UF8xxx | Plugins                       |
| UF9xxx | Internal                      |

## Syntax and components

### [UF1001]{#UF1001} syntax-error

**Error.** The file is not valid TSX.

The parser could not read the file as TSX. The message names the first problem it met.

Fix the syntax error. Any TypeScript editor shows the same error, because a `.uf.tsx` file
is ordinary TSX.

A raw `}` or `>` in JSX text is a syntax error: write `&#x7D;` or `&gt;`, which every JSX
implementation decodes (none decodes `&rbrace;`), or a string expression (`{"}"}`). The
fix writes the reference where the file then parses. Where it would not, the `}` is more
likely code after an element that is not closed.

### [UF1002]{#UF1002} unsupported-syntax

**Error.** The compiler cannot lower this construct yet.

The construct is part of the source language, but this version of the compiler cannot
lower it to every target yet. The compiler never copies code it has not analysed into an
output, so it reports the construct instead.

Rewrite the code without the construct, or wait for the release that supports it. The
message names the construct, and the milestone that lowers it where one does. Some
constructs are outside the subset because one target cannot read them: Angular's template
language has no block-bodied arrow functions, type assertions, hexadecimal numbers or
`\u{…}` escapes, so template expressions keep to what every target reads alike. Where a
mechanical rewrite exists (`0x10` to `16`, `{ return e; }` to `e`), the fix applies it.

Setup code and handlers are script or class code on every target, which TypeScript checks:
they may use those constructs, but not `var`, labels, `for…in`, classes, generators, `this`,
function declarations and expressions inside other code (write an arrow function), or a type
assertion on the target of a write of state or of a setup `let`, which the outputs respell
(write the target bare). Where the React Compiler cannot compile code the subset admits (a
`throw` in a `try` block, `finally`), React's output opts the component out of it. Their
type annotations are copied as written, so a type query (`typeof mode.value`) names no prop,
binding of the setup or authoring API, which the outputs respell or erase: write the type. A
statement at the top level of a component's body that only does something (`init();`)
belongs in `onMounted` or a function: the setup declares what the component holds. A
watcher's `deep`, `once` and `flush: "sync"`, and its stop handle, are not supported, and
`immediate: false`, `flush: "pre"` and an empty options object, the defaults, are written
as nothing, in a watcher's one canonical form: the fix removes them.

Some attributes wait for a target: a name a target's element types do not declare fails
that target's type-check whatever its value (`writingsuggestions`, `commandfor` and
`dirname` in React's; `popover` and `closedby` in Vue's, which are also the authoring
types; ARIA 1.3's `aria-description` in Vue's and Svelte's), and a bound
`size` or `multiple` on a `<select>`, or `disabled` on an `<option>` or `<optgroup>`,
decides which option starts selected, which some clients settle before they bind it (form
state, M3).

### [UF1101]{#UF1101} no-component

**Error.** The file exports no component.

A `.uf.tsx` file holds components: exported PascalCase functions whose last statement
returns JSX.

<!-- prettier-ignore -->
```tsx
export default function Greeting() {
  return <p>Hello, world!</p>;
}
```

Export a component, or move framework-agnostic code to a plain `.ts` module.

### [UF1102]{#UF1102} invalid-component

**Error.** A component must be a named PascalCase function that returns JSX.

A component is a function whose body is its setup, and whose last statement returns the
JSX that is its template:

<!-- prettier-ignore -->
```tsx
export default function Greeting() {
  return <p>Hello, world!</p>;
}
```

The compiler reports a component without a name (`export default function () { … }`), a
generator, one whose last statement does not return JSX, and one that renders nothing
(`return <></>;`).

A component returns an element or a fragment. A conditional or a list (`return c ? <A /> :
<B />;`) belongs inside one: the fix wraps it in `<>…</>`, which renders the same.

A component is a function declaration. One written as a value, an arrow function or a
function expression in a `const` (`export const Card = (props: CardProps) => …`), is
reported, and still checked as the declaration it would be: the fix declares it as
`export function Card(props: CardProps) { return …; }`, keeping its parameters and body.

It also reports an exported function that returns JSX, as a component does, under a name
that is not PascalCase in ASCII letters and digits (`[A-Z][A-Za-z0-9]*`). JSX reads a tag
that starts with a lower-case letter (`<card>`) as an HTML element, and every target names
files after the component (`Card.vue`, and `card.ts` on Angular, whose selector is
`uf-card`), so its name keeps to the characters every file system and target reads alike.
The fix renames the function where its name is used nowhere else.

### [UF1103]{#UF1103} invalid-export-name

**Error.** A component is exported under a name that is not an identifier.

Every target writes a component's exports as code, and consumers import a component by
name to use it as a JSX tag, so its exported name must be an identifier.

<!-- prettier-ignore -->
```tsx
export { Card as "my card" }; // rejected
export { Card as MyCard };     // accepted
```

### [UF1104]{#UF1104} component-name-collision

**Error.** Two components would write one output file or Angular selector.

Each component compiles to a file named after it: `Card.vue`, and `card.ts` on Angular. Two
components of one module whose names differ only in case, or an imported child whose output
file is another component's, would write one file, since files whose names differ only in case
overwrite each other on case-insensitive file systems (macOS and Windows). So would a shared
`.ts` module named like a component's output file, such as `badge.ts` beside `Badge.uf.tsx`, or
`CardIcon.ts` beside a component or a child `CardIcon`: each output tree holds a copy of the
module beside the components, and an output imports a component's file by its name without the
extension (`./CardIcon`), in kebab-case on Angular (`./card-icon`).

Angular also writes each child as a `uf-<kebab>` selector, and fills each slot through an
attribute directive, such as `ufCardTitle`. A child whose selector is the component's own or
another child's, and two filled slots whose directives share an attribute, would match twice.

Rename one of the components, one of the slots or the shared module.

### [UF1201]{#UF1201} framework-import

**Error.** Components are framework-free.

A `.uf.tsx` component is compiled to every framework, so it cannot import one. The
compiler writes each framework's code for you: hooks in React, refs in Vue, runes in
Svelte, signals in Solid.

Write the component with the authoring API from `@uxfront/unframework` instead:

<!-- prettier-ignore -->
```tsx
import { ref } from "@uxfront/unframework";

export default function Counter() {
  const count = ref(0);
  // …
}
```

### [UF1202]{#UF1202} unresolved-import

**Error.** An imported module cannot be resolved.

A `.uf.tsx` file imports another one's components and injection keys by a relative specifier
that ends in `.uf.tsx`. The compiler reads the imported module's public API through its
resolver: the components it exports, their props, events, models and slots, and its keys. It
reads a shared `.ts` module whose values a component imports, and every relative `.ts` module
that one imports, through the resolver too: every output tree holds a copy of each. This
import names a file the resolver cannot find, a name the file does not export, or a shared
module that imports a file the resolver cannot find, or loads one it cannot follow (an
`import()` of no string, `import.meta.glob`), or the compiler was called without a resolver.

<!-- prettier-ignore -->
```tsx
import Field from "./Field.uf.tsx";       // the default export
import { Fields } from "./Fields.uf.tsx"; // a named export
import { sizes } from "./tokens.ts";      // a shared module's value
```

Check the path and the imported name. The Vite plugin passes a resolver; a direct call of
`compile()` passes one as its `resolve` option.

### [UF1203]{#UF1203} self-import

**Error.** A module does not import itself.

A component renders itself, or another component of its own module, by the name it is
declared with (ADR-0053). An import of the module's own file would give it a second name.

<!-- prettier-ignore -->
```tsx
// Countdown.uf.tsx
import Again from "./Countdown.uf.tsx"; // rejected
<Again from={from - 1} />               // rejected
<Countdown from={from - 1} />           // accepted
```

Remove the import, and render the component by its own name. The likely fix does both, unless
the import binds something other than a component, or the module gives the name to something
else.

### [UF1204]{#UF1204} framework-in-shared-module

**Error.** A shared module imports a framework.

A component may read values and types from a relative `.ts` module, which the compiler copies
into every output tree unchanged (ADR-0070). Every framework's output loads that copy, so it
cannot import a framework, or `@uxfront/unframework`, whose authoring API exists only in `.uf.tsx` and
`.uf.ts` files. This one does, itself or through another `.ts` module it imports. The diagnostic
points at the component's import of the shared module, and the component is compiled for no
target.

Keep a shared module to plain values, types and functions. Move logic that needs reactivity into
a composable in a `.uf.ts` module, which the compiler compiles for each target.

### [UF1205]{#UF1205} import-cycle

**Error.** Components import each other in a cycle.

A component edge is a value import of a component from another `.uf.tsx` module: the import a
parent renders a child by (ADR-0071). These components import each other in a cycle of such
edges, through two or more modules, so none of them can load before the others, and Angular
cannot load them at all. The message names the files of the cycle, and the diagnostic points at
the import that closes it.

An injection key, a type or a shared module imported back closes no cycle, so a consumer may
import its key from the provider that renders it (UF2033).

Break the cycle: declare the components that render each other in one module. A component
renders itself by its own name, without an import (UF1203).

## Setup and macros

### [UF2001]{#UF2001} invalid-props

**Error.** The props parameter is not in a form every target can declare.

A component takes its props as its only parameter, typed by an object type: either
destructured, with optional static defaults, or as one object read as `props.x`.

<!-- prettier-ignore -->
```tsx
export default function Badge({ label, tone = "info" }: BadgeProps) { … }
export function Plain(props: PlainProps) { return <p>{props.label}</p>; }
```

The compiler reports a parameter without a type annotation, a second parameter, a
renamed, nested or computed property in the pattern, a member a props type declares
twice, which TypeScript rejects too, a default on a required prop, a default on a prop
whose type admits `null` (unless the default is `null`: Qwik applies a destructured
default to `null` too), and, in the object form, a use of the object other than reading
one of its members (`props`, `props[key]`, `props.x = …`, `(props).x`) and a name
starting with `$$`: Astro's compiled component declares `$$props`, `$$result`, `$$slots`
and `$$render` where its output declares the object.

Destructure the props by their own names, declare each once, make a prop with a default
optional, and read the object form only through its members.

### [UF2002]{#UF2002} non-static-prop-default

**Error.** A prop's default must be a static value.

Vue hoists `defineProps` defaults out of the component and Angular reads an input's
default before any input is set, so a default cannot read anything: not a prop, not a
global, not a function's result.

A default is a string, number, boolean or `null` literal, a negated number, a template
literal without expressions, or an array or object literal of those (identifier or string
keys, no spreads).

<!-- prettier-ignore -->
```tsx
({ page = 1, tags = ["new"] }: P)        // accepted
({ pageCount = Number.MAX_SAFE_INTEGER }: P) // rejected: reads a global
```

Write the value itself, or compute it in the template (`pageCount ?? 10`).

### [UF2003]{#UF2003} reserved-prop-name

**Error.** A target reserves this name.

Every target declares each prop by its name and reads it in its templates, so a prop's
name keeps to ASCII letters and digits (Angular's expression lexer reads no other
letter), starting with a letter, and none a target gives a meaning of its own:

- `key`, `ref`, `children`, `class`, `style`, `slot`, `is`, `ref_for` and `ref_key`, which
  React, Vue, Svelte or Astro read themselves and never pass to the component;
- `props`, `rawProps`, `constructor` and `Astro`, which the outputs declare beside the
  props, and `Fragment`, which Astro's output imports to render `<>`;
- JavaScript's reserved words, Angular's expression keywords (`as`, `let`, `typeof`, …)
  and the globals expressions may read (`Math`, `String`, …);
- names of events (`onClick`): a component declares its events with `defineEmits`, and the
  outputs name their event props after them (ADR-0012); names starting with `ng` and a
  capital letter (`ngIf`), which Angular reserves for its directives, and names ending in
  `$`, which Qwik reads as a QRL.

The setup's bindings (its constants, `let`s, local functions, refs, models, slots, injected
values and `emit`) are declared beside the props, as members of Angular's class among others,
so their names keep to the same rules as a parameter's (UF3024), and are none of
`constructor`, a name starting with `ng` and a capital letter, one starting with `use` and a
capital letter or a digit (React's lint reads it as a hook, which a handler cannot call) and
one ending in `$`; in the object form, none is a prop's name either. A parameter of a local
function, a handler or a callback is an ASCII identifier too, since Angular's methods and
template statements name it.

On Angular, each prop, model, event and exposed function is a member, an input or an output of
one class, beside the lifecycle hooks (`ngOnInit`, `ngOnChanges`, …), each slot's query
(`titleTemplate`) and the fallthrough `class` and `style` inputs. A model `open` is the input
`open` and the output `openChange`, and an event named like a DOM event is the output
`uf<Name>` (`ufChange`). So two of these names that meet are reported, as is a slot's
directive, exported as `CardTitle`, that shares its name with a type, a key or a component the
module exports.

The outputs also declare types named `Props` and `CSSProperties`, Angular's output imports
its `Component` decorator, which is also a type, and reads TypeScript's `Exclude`, and
Solid's output reads TypeScript's `Partial`, `Record`, `Required` and `Pick`, so a local
type of any of these names is reported. `Props` is accepted as a component's own props
type, when every component whose props reach it takes it as its props type: Astro's
output declares a `Props` of its own for any other.

Rename the prop, the binding or the type.

### [UF2004]{#UF2004} in-place-mutation

**Error.** State is replaced whole, never changed in place.

State is a ref whose value is replaced whole (ADR-0008): `items.value = [...items.value, item]`.
No target's state is deep (Vue's output declares it with `shallowRef`), so a change in place
(`items.value.push(item)`) re-renders none of them: their outputs would never see it.

So client code and getters change in place only a value no state shares: an object or an array
they build themselves (a literal, `new Map()`, a copy written with a spread, or the new array
`slice`, `filter`, `map`, `concat`, `Array.from` or `Object.values` returns, from state too),
and what it holds where the code put a value it built there too (a literal's member written
after its last spread, `{ ...x, tags: [...x.tags] }`, or a container's members where every value
the code writes into them is one, `byKind[kind] = []` or `byKind[kind] ??= []`), but not what it
shares with the value it copies; a deep copy (`structuredClone(…)`, `JSON.parse(…)`) and all it
holds; an element, the handler's event and a global (`document.title`); and a local, a setup
`let`, a loop's variable, an array method's item or a `reduce` callback's accumulator (its
initial value and what the callback returns) that only ever holds one of these, wherever the
component's code writes it. A member assignment (a destructuring's and a loop's target too),
`delete`, `++` or `--` on a member, a method that changes its receiver (`push`, `splice`, `sort`,
`reverse`, … and a `Map`'s or a `Set`'s `set`, `add`, `delete` and `clear`) and `Object.assign`
and its kin are reported on anything else: a ref's value, a prop, a list's item, a constant the
setup declares, a parameter, a member of a copy, or a name that may hold one of them. A module's
top-level `const` changes in place only a value it builds itself, a literal, a `new`, a copy or a
function's local that only ever holds one: a module's values are plain and read-only
(ADR-0070).

<!-- prettier-ignore -->
```tsx
tags.value.push("new");               // rejected
tags.value = [...tags.value, "new"];  // accepted
const copy = [...todos.value];
copy[0].done = true;                  // rejected: the copy shares the item with the ref
const open = todos.value.filter((todo) => !todo.done);
open.sort(byOrder);                   // accepted: `filter` returns a new array
```

Where the result is not used, the likely fix writes the new value whole: `[...x.value, a]`,
`{ ...x.value, key: v }` for an object (never an array, a `Map` or a `Set`), `toSorted`,
`toReversed` and `toSpliced`, `x.value.slice(0, n)` (or `[]`) for an array's `length`, and for a
destructuring assignment of a ref's members (`[x.value[i], x.value[j]] = …`) a copy that the
assignment changes and that is then written whole.

### [UF2005]{#UF2005} misplaced-reactive-call

**Error.** Macros and reactive APIs are called at the top level of the component.

Every target runs a component's setup once, and lowers each macro and reactive API where the
setup calls it: a hook at the top of React's function, a rune in Svelte's script, a signal in
Angular's class. So `ref`, `computed`, `watch`, `watchEffect`, `onMounted`, `onUnmounted`,
`defineEmits`, `useTemplateRef` and `useId` are called at the top level of the component's
body, as a statement or as a `const`'s value: never inside a condition, a loop, a function, a
handler or another API's callback, and never used as a value.

<!-- prettier-ignore -->
```tsx
onMounted(() => {
  watch(open, () => report()); // rejected: a watcher created at every mount
});
watch(open, () => report());   // accepted
```

`nextTick` is a function, not a macro: client code (a handler, a watcher's callback,
`watchEffect`, a lifecycle hook, or a function they call) calls it anywhere. The setup itself
runs before the DOM exists, so it does not call `nextTick`.

### [UF2006]{#UF2006} unbound-macro-result

**Error.** A macro's result is bound by a `const`.

`ref`, `computed`, `useTemplateRef`, `useId` and `defineEmits` return what the component
holds: state, a derived value, a template ref, an id, the `emit` function. Each target declares
it once, under the name a `const` at the top level of the component's body gives it, so a call
whose result nothing binds, or that `let` or destructuring binds, has no counterpart.

<!-- prettier-ignore -->
```tsx
defineEmits<{ close: [] }>();               // rejected
const emit = defineEmits<{ close: [] }>(); // accepted
```

The fix binds `defineEmits`'s result as `const emit`, where the component names nothing
`emit` already.

### [UF2007]{#UF2007} setup-once-read

**Warning.** A setup `const` keeps the value it had when the setup ran.

The setup runs once per instance, so a `const` in it keeps its first value (plan §4.5): a
`const` that reads a prop, a ref or a `computed` does not follow it when it changes. That is
sometimes meant (a creation-time snapshot), and often a mistake.

<!-- prettier-ignore -->
```tsx
const greeting = `Welcome, ${name}`;                  // keeps the first name
const greeting = computed(() => `Welcome, ${name}`);  // follows it
```

The likely fix makes it a `computed`, and reads it as `greeting.value` wherever it is read.
`ref(prop)` seeds state from a prop on purpose, and is not reported.

### [UF2008]{#UF2008} invalid-event-name

**Error.** An event's name is camelCase, apart from the props' names.

Every target spells an event its own way: React's, Solid's and Qwik's components take
`onLevelChange`, Svelte's `onlevelchange`, Angular's an output `levelChange` (ADR-0012). So an
event's name is camelCase in ASCII letters and digits, starting with a lower-case letter, and:

- it does not start as an event prop does (`onSave`): a consumer would listen to `onOnSave`,
  and angular-eslint's `no-output-on-prefix` rejects it;
- no two events differ only in case: Svelte lower-cases an event's prop;
- no prop takes it: a prop is public on every target, and Angular declares a member for each;
  nor does a prop take its Svelte spelling (`onchange` for `change`). A binding of the setup
  may (`function save() { emit("save"); }`): it is the component's own, and Angular renames
  its class member (`onSave`), as the output keeps the event's name;
- it is no keyword of Angular's template expressions (`if`, `as`, `this`, `typeof`, …), no
  global expressions may read (`parseInt`) and not `constructor`: Angular's template statements
  read the event's member by name (`picked.emit(item)`). Angular's lexer reads no other word as
  a keyword, so a JavaScript reserved word such as `delete`, `new` or `default` names an event.

The safe fix renames the event where its camelCase spelling is free (`level-change` to
`levelChange`, `onSave` to `save`): its declaration and every `emit` of it.

### [UF2009]{#UF2009} invalid-emits

**Error.** `defineEmits` takes one type argument: the events, as named tuples.

A component declares its events with one `defineEmits` call, whose one type argument lists
them: an object type literal, or a local `interface` or `type` of one, whose members are the
events, each typed by a named tuple of its payload. Every target reads the events from the
type and declares a parameter for each member of a payload, so each member is named.

<!-- prettier-ignore -->
```tsx
const emit = defineEmits<{ change: [value: number]; close: [] }>(); // accepted
const emit = defineEmits<{ (event: "change", value: number): void }>(); // rejected
```

The compiler reports Vue's call-signature form, runtime arguments (`defineEmits(["change"])`),
a type argument that is no object type, an event that is not a named tuple (`[number]`, a rest
member, an optional event), a payload that names a member twice or puts a required member
after an optional one, and a second `defineEmits`. A payload member's type is one props can
have (strings, numbers, booleans, literals, `null`, `undefined`, arrays and local object types
of them), since Vue declares an event's payload as it declares props.

### [UF2010]{#UF2010} non-reactive-read

**Error.** A setup `let` or a template ref is read where values are tracked.

A template, a getter, an initial value, a watcher's source and `watchEffect` read values that
the targets track, and render or run again when they change. A setup `let` is not reactive:
a template that reads it would never update (React reads a `useRef`, which its lint rejects in
render). A template ref is never a reactive dependency on every target (React's is a `useRef`).

<!-- prettier-ignore -->
```tsx
let clicks = 0;
// …
<p>Clicked {clicks} times</p>  // rejected: hold it in a ref
```

Hold a value a template or an effect reads in a `ref`, and read an element from client code:
`onMounted`, a handler, or `watch(…, { flush: "post" })`. A template or a getter that calls a
function that reads one is UF2014; a `watchEffect` that does is reported here. What a
`watchEffect` hands on to run later (a timer's callback, `onCleanup`'s) runs untracked, and
may read either: the handle of the timer it starts (`onCleanup(() => clearInterval(timer))`),
or an element in a frame.

### [UF2011]{#UF2011} invalid-write

**Error.** State is written in client code, as a statement of its own.

State is a ref, written through its value (`count.value = 1`, `count.value += step`,
`count.value++`), and a setup `let` (`timer = …`) holds what no template reads. Only client
code writes them: a handler, a watcher's callback, `watchEffect`, a lifecycle hook or a
function they call. React, Solid and Angular write state through a setter, so a write is a
statement of its own: the whole of an expression statement, or the whole expression body of
a function whose value the framework drops (a handler, a watcher's callback, `watchEffect`, a
lifecycle hook, an `onCleanup` callback). An arrow passed to another call writes in a block
body, since a call such as `map` or `then` uses its value.

<!-- prettier-ignore -->
```tsx
const flip = () => (on.value = !on.value);    // rejected: the function returns the write
const flip = () => { on.value = !on.value; }; // accepted
total.value = (count.value += 1);              // rejected: a write inside an expression
setTimeout(() => (copied.value = false), 2000); // rejected: write `() => { … }`
```

The fix gives a local function or an arrow whose expression body is a write a block body: a
safe one where the call drops the arrow's value (a timer, `forEach`), a likely one elsewhere,
where the code may need to return what the call uses. What a prop, a `computed`, a template
ref, a constant, a local function, `emit` or a list's item holds is never written: copy a
prop into a ref (`const value = ref(initial)`), and write the state a `computed` is computed
from. A getter and an initial value are pure, and write nothing.

### [UF2012]{#UF2012} conditional-return

**Error.** A component's body returns only at its end.

A component's body is its setup, which every target runs once, and its last statement returns
the template. A `return` before it, conditional or not, would make the setup decide what
renders, which no target's template can follow.

<!-- prettier-ignore -->
```tsx
if (!message) return null; // rejected
return <p>{message}</p>;
```

Move the condition into the JSX: `return <>{message && <p>{message}</p>}</>;`.

### [UF2013]{#UF2013} server-unsafe-effect

**Error.** An immediate watcher's callback is safe to run on the server.

Vue runs an immediate watcher's first callback during the setup, on the server too, and
Angular and Qwik may: the server render must not depend on it, and must not fail. So the
callback, every function in it (the `onCleanup` callbacks included) and the local functions
they call write no state, read no template ref, read none of the browser's globals (every
name lib.dom declares: `document`, `window`, `localStorage`, `location`, `fetch`, `URL`,
`IntersectionObserver`, `HTMLElement`, `requestAnimationFrame`, …) nor the timers
(`setTimeout`, `setInterval`, `queueMicrotask` and their `clear`s), do not `await`, and call no
`nextTick`. Emitting, reading state and props, `console`, `performance` and `crypto` are safe.

<!-- prettier-ignore -->
```tsx
watch(() => query, (value) => { heading.value = value; }, { immediate: true }); // rejected
const heading = computed(() => `Results for ${query}`);                         // accepted
```

An immediate watcher with `flush: "post"` is reported too: its first callback runs before any
DOM exists. Its `onCleanup` is called directly, before any `await`. Derive the value with
`computed`, or write it from `onMounted` and a watcher without `immediate`.

### [UF2014]{#UF2014} impure-function-call

**Error.** A template, a getter or an initial value calls only a pure local function.

Rendering, getters and initial values are pure: the targets run them when they decide to, on
the server too. A template and an initial value call a local function only when it writes
nothing, emits nothing, calls no `nextTick`, is not `async`, reads no template ref and no
setup `let`, and reads only the globals they may (UF3020), itself and through the functions it
calls. A function that reads the clock, chance or the locale is UF3019.

A getter (a `computed`'s, a watcher's source) calls only a function that reads nothing but
constants that read nothing themselves, and other such functions: Qwik hoists those, with
their constants, out of the component, where a getter's closure can reach them.

<!-- prettier-ignore -->
```tsx
function greet() { renders.value += 1; return `Hello, ${name}`; }
<h2>{greet()}</h2>  // rejected: rendering writes state
```

### [UF2015]{#UF2015} conditional-effect-read

**Error.** `watchEffect` reads its reactive values unconditionally.

Vue's `watchEffect` tracks what each run reads, but React's effect and Qwik's `track` list an
effect's dependencies statically: a value read only under a condition would be missed, or
tracked when Vue's would not. So every read of a prop, a ref or a `computed` in a `watchEffect`
lies in the straight-line start of its body: before the first `if`, loop, `switch`, `catch`,
`return`, `throw` or `await` (that `if`'s test, that `switch`'s, `return`'s or `throw`'s value
and that loop's head included: a `for…of`'s iterable, a `for`'s init and test, a `while`'s
test), into plain blocks and a `try` block up to its first call (its callee and arguments
included: what follows runs only where that call does not throw), outside the right side of
`&&`, `||`, `??`, `||=`, `&&=` and `??=` and the branches of `?:`, after no `?.` in its chain (a
later key or argument included), outside a destructuring default, and outside any function
inside it but one it hands on to run later: a function given to a timer, a promise's `then`,
`addEventListener`, an observer or `onCleanup`, written in place or held in a local `const` only
such calls are given, reads its values when it runs, which no target tracks. A local function it
calls reads its reactive values the same way.

<!-- prettier-ignore -->
```tsx
watchEffect(() => {
  const enabled = live.value;
  if (enabled) emit("search", query.value); // rejected: read under a condition
});
```

Read every value first, into locals, or watch explicit sources with `watch`. The same holds
for a watcher's getter, and a `computed` a watcher's source reaches, whose value may be an
object or an array: React compares those by identity, and recomputes them when any listed
dependency changes.

### [UF2016]{#UF2016} unknown-api

**Error.** The import is not part of unframework's API.

A component imports the authoring API by name from `"@uxfront/unframework"`: `ref`, `computed`,
`watch`, `watchEffect`, `onMounted`, `onUnmounted`, `nextTick`, `defineEmits`,
`defineModel`, `defineSlots`, `defineExpose`, `defineOptions`, `provide`, `inject`,
`useTemplateRef` and `useId`, and the package's types. The compiler recognises each API by the
binding its import declares, and erases the import, so a namespace or a default import, an
import that imports nothing, a value imported from a subpath (`@uxfront/unframework/jsx-runtime` holds
types only) and a name the package does not export as an API mean nothing.

Vue's APIs that unframework writes another way are reported with their canonical form:
`reactive` (state is a `ref`, replaced whole), `toRefs` (props are destructured in the
signature), `watchPostEffect` (`watch(…, { flush: "post" })`) and others.

### [UF2017]{#UF2017} invalid-emit

**Error.** An emit is a statement that names an event the component declares.

`emit` tells the component's parent that something happened. Each target writes every emit as
a call of its own (a callback prop, an Angular output), and what that call returns differs
(Qwik's is a promise). So an emit is a statement of its own, in client code, of an event
`defineEmits` declares, named by a string, with as many arguments as the event's payload
takes, none spread.

<!-- prettier-ignore -->
```tsx
emit("change", count.value); // accepted
emit("changed");             // rejected: no such event
const saved = emit("save");  // rejected: an emit is a statement
```

`emit` itself is only called. A handler that is `emit` (`onClick={emit}`) is UF3029.

### [UF2018]{#UF2018} early-dom-read

**Error.** A watcher that reads the DOM runs after it updates.

A watcher runs before the DOM updates, unless it says `flush: "post"`: Vue's and Svelte's read
the DOM as it was, React's and Solid's as it is now. So a watcher's callback that reads a
template ref or the DOM through a global, itself or through the functions it calls, runs with
`flush: "post"`, after the DOM updates on every target. The globals that read what a render
changes are `document` (but its `title`, `cookie`, visibility and listeners), `window` whole or
through its document, layout and scroll (`window.scrollY`, `window.innerWidth`),
`getComputedStyle` and `getSelection`. Storage, `navigator`, `history`, `location`, `fetch`, the
timers and the observers read nothing a render changes: a watcher that persists a value
(`localStorage.setItem(…)`) or writes the URL needs nothing.

<!-- prettier-ignore -->
```tsx
watch(items, () => {
  emit("rendered", list.value?.childElementCount ?? 0); // rejected: Vue reads the old list
});
watch(items, () => { … }, { flush: "post" });           // accepted
```

The likely fix adds `{ flush: "post" }`. `watchEffect` runs after the DOM updates on every
target, and needs nothing. What a callback reads after `await nextTick()`, which every path
to the read passes, reads the updated DOM on every target, and needs nothing either.

### [UF2019]{#UF2019} erased-type-reference

**Error.** A copied annotation names an authoring type.

The compiler erases the import from `"@uxfront/unframework"`, and copies the annotations of setup code
and props into the outputs, where nothing declares `Ref`, `OnCleanup` or the package's other
types: an output that copied one would not type-check.

<!-- prettier-ignore -->
```tsx
watch(user, (value, previous, onCleanup: OnCleanup) => { … }); // rejected
watch(user, (value, previous, onCleanup) => { … });            // accepted
```

Leave the annotation out where TypeScript infers the type: the likely fix removes it from a
callback's parameter and from a `const` with an initial value. Elsewhere, write the type
itself.

### [UF2020]{#UF2020} unwatchable-source

**Error.** A watcher watches a ref, a getter or an array of them.

A watcher's source says what it watches: a `ref` or a `computed` itself, a getter that reads
what it watches, or an array of them. A prop's value, a ref's value (`count.value`) and a
constant are values taken once, which nothing can watch; a template ref is never a reactive
dependency on every target.

<!-- prettier-ignore -->
```tsx
watch(page, (value) => …);       // rejected: a prop's value
watch(() => page, (value) => …); // accepted
```

The safe fixes watch a getter of a prop (`() => page`) and a ref itself (`count.value` to
`count`).

### [UF2021]{#UF2021} untyped-state

**Error.** State and a setup `let` have a type the outputs can declare.

React's `useState`, Solid's `createSignal`, Angular's `signal` and fields declare a value's
type from what the source gives them. So `ref()` with neither a type argument nor an initial
value holds `undefined` and nothing else to them, and a setup `let` without an annotation and
without an initial value (or with only `undefined` or `null`) has no type at all. A setup `let`
without an initial value holds `undefined` until code assigns it, and React's `useRef` and
Qwik's `useSignal` declare it so: its annotation admits `undefined`, with a `!` too.

<!-- prettier-ignore -->
```tsx
const selected = ref();          // rejected
const selected = ref<string>();  // accepted
let timer;                       // rejected
let timer: ReturnType<typeof setTimeout>; // rejected
let timer: ReturnType<typeof setTimeout> | undefined; // accepted
```

State that may hold a function is reported too: React's setter calls a function it is given
as an updater, and `useState` one as its initialiser. Keep the function in a local function,
and in state what decides it.

### [UF2022]{#UF2022} function-value

**Error.** A local function is called, or passed as a call's argument in client code.

The targets write a local function their own way: Angular as a method of its class, Qwik as a
QRL. So code calls a local function; client code also passes one as a call's argument
(`setTimeout(tick, 100)`), which Angular's output wraps. A template, a getter and an initial
value only call one, and pass a function only as an arrow function written in the call
(`items.filter((item) => item.on)`).

A watcher's, an effect's or a hook's callback, and a watcher's getter, are written in place:

<!-- prettier-ignore -->
```tsx
onMounted(focusField);              // rejected
onMounted(() => focusField());      // accepted
```

The safe fix wraps a local function passed to `onMounted`, `onUnmounted`, `watch` or
`watchEffect` by name in an arrow function that passes it the callback's arguments.

### [UF2023]{#UF2023} read-before-declaration

**Error.** Code the setup runs reads only what is declared before it.

React's and Solid's outputs evaluate an initial value, a getter (`useMemo`, Solid's eager
`createMemo`), a watcher's source and an immediate watcher's first callback where the source
declares them, in order: one that reads a binding declared after it throws a `ReferenceError`
there, while Vue's lazy `computed` hides it. So that code, and the local functions it calls,
read and call only the props and the bindings declared before it.

<!-- prettier-ignore -->
```tsx
const total = computed(() => net.value + tax.value); // rejected: `tax` comes next
const tax = computed(() => net.value * 0.2);
```

Declare what it reads first. A `function` declaration is hoisted, so code may call one declared
after it, as long as what that function reads and calls is declared before the code; an arrow
function in a `const` is not hoisted. Client code (handlers, callbacks, hooks) runs later, and
may read any binding. A module computes its top-level `const`s in order too, as it loads, so a
constant's value reads only the constants declared before it, itself or through the functions
it calls; only a function's body, which runs once called, may read one declared after it.

### [UF2024]{#UF2024} unsafe-local-call

**Error.** A local function that touches state is called directly, and never recursively.

Qwik's output makes a local function that touches state (reads or writes a binding, emits,
reads a template ref) a QRL, whose calls it awaits. So client code calls such a function
directly in the body of a handler, a callback, a hook or a local function, in an `async`
arrow function, or in a callback that runs later (a timer's, a promise's `then`,
`onCleanup`'s), never inside an arrow function that runs at once and whose result counts (an
array method's callback, a comparator). It passes the function only to a call that runs it
later (`setTimeout`, `addEventListener`) or never runs it (`removeEventListener`,
`clearTimeout`). A function that returns a promise (`async`, or annotated `Promise<…>`) may be
called and passed anywhere: a QRL's call gives a promise of the same value, so
`await Promise.all(files.map(upload))` collects the same results. Local functions never call
themselves, directly or through each other.

<!-- prettier-ignore -->
```tsx
function markAllRead() {
  unread.value.forEach((subject) => markRead(subject)); // rejected
}
```

Call it from the body itself, or compute the new state at once and write it.

### [UF2025]{#UF2025} non-canonical-call

**Error.** `nextTick` is called bare and awaited, never given a callback or used as a value.

`await nextTick()` is the one way to wait for the DOM to update (ADR-0007). Vue and Svelte
also run a callback given to `nextTick` once the DOM has updated, but React's, Angular's and
Qwik's outputs declare `nextTick` as a function that returns a promise and takes no callback,
which would never run.

<!-- prettier-ignore -->
```tsx
function copy() {
  done.value = true;
  nextTick(() => emit("copied")); // rejected
}
async function copy() {
  done.value = true;
  await nextTick();               // accepted
  emit("copied");
}
```

Make the function `async`, await `nextTick()`, and write the callback's code after it. The
safe fix does so where the call is the last statement of a handler, an `onMounted` callback,
a watcher's callback that is not immediate, or a local function nothing calls, and the
callback is an arrow function without parameters.
`nextTick().then(…)` stays: every target's `nextTick` returns a promise.

Each target writes its own call in place of `nextTick()`, so `nextTick` is also called bare:
not passed or stored as a value (`.then(nextTick)`, `const wait = nextTick`), which leaves no
call to replace (write `() => nextTick()` where a function is passed), and not called through
parentheses, an assertion or type arguments (`(nextTick)()`), which the safe fix writes bare.

### [UF2026]{#UF2026} unsafe-teardown

**Error.** Teardown code reads no template ref, and does not wait.

The targets tear a component down in different orders. Vue empties a template ref while it
removes the elements, before `onUnmounted` runs, and React detaches it before an effect's
cleanup runs; Svelte, Angular and Qwik still hold the element there. So an `onUnmounted`
callback, a watcher's or `watchEffect`'s `onCleanup` callback, and the local functions they
run (call, or pass to a call that runs them, now or later) read no template ref: what they
would see depends on the target. A listener they remove (`removeEventListener(type, onClick)`)
does not run there: it reads the element when its event fires, while the component is mounted.

An `onUnmounted` callback is not `async`, and calls no `async` local function: Vue drops an
emit once the component is unmounted, and the other targets deliver it.

<!-- prettier-ignore -->
```tsx
onUnmounted(() => {
  emit("closed", grid.value?.childElementCount ?? 0); // rejected
});
```

Read the element in the callback that sets up the work (`onMounted`, the watcher's callback)
and keep it in a local or a setup `let`, which the teardown reads. Do the async work before
the component unmounts.

### [UF2027]{#UF2027} self-triggering-effect

**Error.** `watchEffect` writes no state it reads.

Vue ignores what an effect writes while it runs, so a `watchEffect` that writes a ref it
reads runs once for each change. Svelte, Solid, Angular, Qwik and React track what the effect
reads, and run it again after its own write, without end: Svelte and Solid throw, Angular
stops its change detection, and Qwik's page freezes. Only what runs while the effect runs
counts: its code up to an `await`, the same part of the local functions it runs at once, and
the `computed` values it reads; `count.value++` reads `count` as it writes it. A function it
hands to a timer, `then`, `addEventListener`, an observer or `onCleanup`, written in place,
held in a local `const` or named (`setInterval(tick, 1000)`), and what follows an `await`, run
after it, which no target tracks.

<!-- prettier-ignore -->
```tsx
watchEffect(() => {
  history.value = [...history.value, count.value]; // rejected
});
watch(count, (value) => {
  history.value = [...history.value, value];       // accepted
});
```

Watch the sources with `watch`, whose callback is untracked: it reads and writes what it
needs.

### [UF2028]{#UF2028} invalid-model

**Error.** `defineModel` takes a free name and static options.

`const open = defineModel<boolean>("open", { default: false })` declares a model: a prop a
parent may bind two ways with `v-model:open`. Every target names the prop and its update event
after the model, so the name is a camelCase string literal, and the options, `default` and
`required`, are static values, as a prop's default is. The name is also free: a component
declares each model once, apart from its props, and from an event named `openChange`, whose
callback (`onOpenChange`, and `onOpenChange$` on Qwik) would be the model's too.

<!-- prettier-ignore -->
```tsx
const open = defineModel<boolean>({ default: false });         // rejected
const open = defineModel<boolean>("open", { default: false }); // accepted
```

Name the model, and rename it where the name is taken. The safe fix names a nameless model
`"value"`.

### [UF2029]{#UF2029} invalid-slots

**Error.** `defineSlots` declares optional slots, named apart from props, models and events.

`const slots = defineSlots<{ default?(): Element; item?(props: { item: Item }): Element }>()`
declares the slots a parent may fill, in one call. Each member is optional, since a parent may
leave any slot empty, and a method whose one parameter, if it has one, is a scoped slot's props.
Each slot is declared once, with a camelCase name.

React, Solid, Qwik and Astro pass a slot as a prop, so a slot's name differs from every prop's
and model's, and from an event's callback (`onClose` for `close`). React, Svelte and Solid pass
the default slot as `children`, so no other slot takes that name.

Make each member an optional method, and rename a slot whose name is taken. The likely fix
renames a `children` slot to `content`.

### [UF2030]{#UF2030} invalid-expose

**Error.** `defineExpose` takes an object of the component's local functions.

`defineExpose({ focus, clear })` lists what a parent may call through a ref on the component.
Each target exposes functions in its own way (an imperative handle, a public method, a
signal), so the argument is an object literal of the component's local functions, each in
shorthand: no state, no computed value and no function written in place.

<!-- prettier-ignore -->
```tsx
defineExpose({ focus, count });                      // rejected: `count` is a ref
defineExpose({ focus: () => input.value?.focus() }); // rejected
defineExpose({ focus, clear });                      // accepted
```

Declare each exposed function in the setup, and list it by name.

### [UF2031]{#UF2031} invalid-options

**Error.** `defineOptions` takes a static `{ inheritAttrs: false }`.

`defineOptions({ inheritAttrs: false })` stops a parent's `class` and `style` from falling
through to the component's root. It is the one option every target can honour, and the
compiler must know it when the component compiles, so the argument is that object literal and
nothing else.

Remove any other option, or the call where fallthrough should stay on.

### [UF2032]{#UF2032} invalid-context

**Error.** `provide` and `inject` take an injection key, `inject` first.

`provide(ThemeKey, theme)` and `const theme = inject(ThemeKey, fallback)` share a value with
every descendant. Each target turns the key into its own context (a React or Solid context, an
Angular `InjectionToken`, a Qwik context id), so the first argument is an injection key, by
its name, never a string, and the key types the call, which takes no type arguments. A
component provides each key once. One that injects and provides a key reads its parent's
value, as in Vue, so its `inject` comes before its `provide`.

A key of a `Ref`, a `ComputedRef` or a `ModelRef`, such as `InjectionKey<Ref<number>>`, shares
the ref itself, which stays reactive where it is injected. So `provide` and `inject`'s
fallback take a binding of the setup by its name: a `ref`, a `computed` or a model for a
`Ref`, a `computed` for a `ComputedRef`, and a model for a `ModelRef`. Its `inject` takes that
fallback, which code reads where no ancestor provides the key.

<!-- prettier-ignore -->
```tsx
provide(ThemeKey, theme);
const parent = inject(ThemeKey); // rejected: after its `provide`
```

Pass the key itself, move the `inject` before the `provide`, and give a ref's key a ref.

### [UF2033]{#UF2033} invalid-injection-key

**Error.** An injection key is an exported `InjectionKey` `Symbol` of a `.uf.tsx` module.

Each target writes a key in its own form into the output of the module whose component
provides it. So a key is an exported top-level `const` of a `.uf.tsx` module, declared alone,
typed `InjectionKey<T>` with the type of what it provides, and initialised with `Symbol` and a
string literal that describes it.

<!-- prettier-ignore -->
```tsx
export const ThemeKey: InjectionKey<Theme> = Symbol("acme.theme");
```

Passing anything else to `provide` or `inject`, such as a string or a value imported from a
shared `.ts` module, is UF2032: a key lives in the `.uf.tsx` module that provides it. Qwik uses
the description as the context's id, so two keys with one description collide: give each key a
namespaced description.

### [UF2034]{#UF2034} context-write

**Error.** An injected value is read-only.

`inject` gives the value an ancestor provides. A write to it would change the provider's state
behind its back on some targets and nothing on others, so code never writes an injected value,
nor one of its members.

Provide a function beside the value, and call it to ask the provider to change its state.

### [UF2035]{#UF2035} invalid-composable

**Error.** A composable is a named `use*` export that returns a shorthand object.

A `.uf.ts` module holds composables: named exports whose names start with `use` and an
upper-case letter, each a setup under the rules of a component's, with no JSX (ADR-0069). Each
parameter is annotated, and its type says how the body reads it: a value once, a getter
(`() => T`) as it changes, and a callback from client code. The last statement returns a
shorthand object of the state, derived values, functions and constants a caller may use.

<!-- prettier-ignore -->
```ts
import { ref } from "@uxfront/unframework";

export function useToggle(initial: boolean) {
  const on = ref(initial);
  function toggle() {
    on.value = !on.value;
  }
  return { on, toggle };
}
```

A composable cannot call `useId`, `useTemplateRef`, `provide`, `inject`, a `define*` macro or
another composable, be a default export, or return anything but a shorthand object. Move what
needs them into the component that calls the composable, and pass it in as an argument.

### [UF2036]{#UF2036} composable-result-write

**Error.** A ref a composable returns is read-only to its caller.

A component reads a ref a composable returns through `.value`, and never writes it: on some
targets the caller holds the value its render reads, apart from the composable's state, so a
write would change one and not the other (ADR-0069).

Return a function from the composable that changes its state, and call it:

<!-- prettier-ignore -->
```tsx
const { on, toggle } = useToggle(false);
on.value = true; // rejected
toggle();        // accepted
```

### [UF2037]{#UF2037} invalid-directive

**Error.** A directive is a top-level `const` that `defineDirective` initialises.

A directive packages a behaviour an element takes (ADR-0099). It is declared once, at the
top level of a module: `const vName = defineDirective<T>({ … })`, with a name that is `v`
and an upper-case letter. A `.uf.ts` module exports it, and a component imports it by name.
A component's own `.uf.tsx` module may declare one for its components alone.

<!-- prettier-ignore -->
```ts
import { defineDirective } from "@uxfront/unframework";

export const vAutofocus = defineDirective<boolean>({
  mounted(el, value) {
    if (value) el.focus();
  },
});
```

The type argument, the value's type, is required, and the object holds the hooks as
methods: `mounted(el, value)`, `updated(el, value, oldValue)` and `unmounted(el)`, at least
one of them, with parameters that take their types from the type arguments. The hooks run
in the browser only, so they read their parameters, their own names, the browser's globals,
the module's constants and the values it imports. They never call the authoring API or read
a component's state. The names of Vue's own directives, like `vShow`, are reserved.

### [UF2038]{#UF2038} nested-await

**Error.** An `await` in the setup is the whole value of a `const`.

An async component awaits at the top level of its setup, and only as the whole value of a
`const` that declares one name (ADR-0101). Each target lowers that declaration its own way:
Vue and Svelte await it in place, React and Solid run the awaits in a function of their own,
Angular continues the setup after them and Qwik reads each through a derived value. An
`await` inside a larger expression, a destructuring, a `let`, a bare statement, a block or
a condition has no such form on every target.

<!-- prettier-ignore -->
```tsx
const user = await loadUser(props.id);       // accepted
const { name } = await loadUser(props.id);   // rejected
const name = (await loadUser(props.id)).name; // rejected
```

Declare each awaited value with a `const` of its own, and read its members after it. An
`await` inside a function the setup declares, such as a handler, is client code, and stays
allowed.

### [UF2039]{#UF2039} late-await

**Error.** The awaits open the setup, and read only props and module values.

An async component's awaits come first in its setup, before any state, constant, function,
watcher, hook, `provide`, `inject`, `useId`, template ref, model or composable call, and an
awaited expression reads only props, the module's values, globals and the values awaited
before it (ADR-0101). React and Solid run the awaits in a function of their own, outside
the component's render, and Qwik runs the body again up to each await, so the setup's other
items are not there yet.

<!-- prettier-ignore -->
```tsx
const user = await loadUser(props.id);
const team = await loadTeam(user.teamId); // accepted: it reads an earlier await
const visits = ref(user.visits);          // accepted: the items follow the awaits
```

Move the `await` above the other items, and compute what it needs from the props there.
The macros `defineEmits`, `defineSlots`, `defineExpose` and `defineOptions` may sit
anywhere, but an awaited expression never reads `emit`, a slot or a model.

## JSX and cross-component usage

### [UF3001]{#UF3001} unknown-element

**Error.** The element is not an HTML element.

Lower-case JSX tags are HTML elements, and the compiler emits them unchanged into every
target. A tag that HTML does not define, an obsolete one (`<center>`, `<marquee>`) or one
in the wrong case (`<dIV>`) would be read differently by each framework: Vue resolves it
as a component, Angular rejects it, and the browser renders an unknown element.

Inside an `<svg>`, tags are SVG elements in SVG's own case (`linearGradient`,
`clipPath`): an HTML element there, or an SVG element outside an `<svg>`, is reported too.

Use the HTML or SVG element; a misspelt case has a fix. Components are PascalCase
(`<Card>`).

### [UF3002]{#UF3002} reserved-element

**Error.** A component cannot render this element.

Some elements belong to the document or to a framework's template syntax, not to a
component's markup:

- `<html>`, `<head>` and `<body>` are the document's; the browser drops them inside one.
- `<title>`, `<meta>`, `<link>` and `<base>` describe the document: React moves them into
  the `<head>`, and the other frameworks leave them in place.
- `<script>` and `<style>` hold code the compiler cannot analyse; Vue and Angular drop them.
  A component's styles are a stylesheet it imports. This holds inside an `<svg>` too.
- `<template>`, `<slot>`, `<component>`, `<transition>` and Angular's `<ng-…>` elements
  are template syntax in one framework or another.
- SVG's animation elements (`<animate>`, `<animateMotion>`, `<animateTransform>`, `<set>`
  and `<discard>`) make the rendering depend on time, and `<animate>` and `<set>` can set
  any attribute, a `javascript:` `href` included.

### [UF3003]{#UF3003} invalid-nesting

**Error.** The browser or a framework would repair this markup.

The HTML parser repairs some nesting: a `<div>` closes an open `<p>`, a `<tr>` directly in
a `<table>` gets a `<tbody>`, text in a table moves out of it, and a void element such as
`<br>` cannot hold children. Server-rendered HTML then becomes a different tree from the
one a client renderer builds, and Svelte, Vue and React each report it. Svelte's compiler
also drops whitespace on its own inside a `<select>` or a `<datalist>`.

The rules see through conditionals, lists and fragments: rows that a `.map` renders
directly in a `<table>` get a `<tbody>` too. An expression renders text, so it cannot sit
where text cannot (a table part, a `<select>`), and inside an `<svg>` only `<text>`,
`<tspan>`, `<textPath>`, `<title>` and `<desc>` render text. Svelte drops whitespace-only
text in SVG outside a `<text>`, so it is reported there too. SVG's `<title>` and `<desc>`
hold text only: the HTML parser and Vue read an element inside them as HTML, and React
as SVG.

The parser reads an `<iframe>`'s content as raw text, decoding no character reference and
reading no comment, so text other than whitespace, an expression or a conditional there
renders the servers' escapes and markers as text, which a client render does not. A
browser never shows that content: remove it.

Write the markup the parser keeps: wrap rows in `<tbody>`, use a `<div>` where a
paragraph would contain blocks, and put options on lines of their own.

### [UF3004]{#UF3004} non-canonical-attribute

**Error.** The attribute is not written in its canonical form.

Each attribute has one way to be written (P3):

- HTML names, in lower case: `class`, `for`, `tabindex`, not `className`, `htmlFor` or
  `tabIndex`.
- A boolean attribute without a value: `disabled`, not `disabled=""` or
  `disabled="disabled"`. Its presence turns it on: `disabled="false"` is still disabled.
- A value for every other attribute: in JSX a bare attribute means the string `"true"`,
  which is only meaningful for ARIA states, `data-*` and true/false attributes.
- Numbers in canonical form (`3`, `0.5`): some renderers set these attributes as DOM
  properties, which rewrites any other spelling.
- No `class` rather than an empty one: Vue renders `class=""`, the others leave it out.
  (Whitespace between class names needs no fix: the compiler writes one space.)
- A literal as a literal: `title="x"`, not `title={"x"}`; `disabled`, not
  `disabled={true}`; no attribute rather than `{false}`, `{null}` or `{undefined}`;
  `class="a b"`, not `class={["a", "b"]}`; the attributes themselves, not a spread of an
  object literal.
- Style keys in camel case (`marginTop`), as React's and Vue's style objects write them.
- `href`, not SVG's old `xlink:href`.
- `key`, in lower case, on a list's element: in JSX `KEY` is an attribute; and `ref`, in
  lower case.
- A listener named as Vue names it, `on` and the DOM event's name: `onKeydown` and
  `onDblclick`, not React's `onKeyDown` or `onDoubleClick`, nor `onclick` in lower case.
- No spread that renders nothing: of a type that declares no keys, or of a source that a
  condition around the spread shows is absent (`{attrs ? null : <p {...attrs} />}`).
- An enumerated attribute's keyword in lower case (`dir="rtl"`, not `dir="RTL"`), and the
  keyword HTML reads an empty value as (`spellcheck="true"`, `popover="auto"`, a
  `<button>`'s `type="submit"`): the targets' types take only those spellings.

The fix rewrites the attribute where the rewrite is mechanical.

### [UF3005]{#UF3005} reserved-attribute

**Error.** The attribute belongs to a framework.

The attribute is syntax or data of one of the target frameworks, so that framework would
not render it as an attribute:

- Angular binds `bind-*`, `on-*`, `bindon-*`, `ref-*` and `let-*`, consumes `i18n` and
  reserves `ng*` names.
- `slot` and `is` are template syntax in Svelte, Astro and Vue.
- `children`, `dangerouslySetInnerHTML`, `textContent` and React's `suppress…` props are
  framework props, not attributes; write the content as JSX children.
- `data-hk`, `data-astro-*`, `data-v-*`, `data-qwik-*` and `data-uf-*` are attributes
  that frameworks or the compiler add themselves, and ids starting with `uf-id-` are the
  ones the compiler generates.
- `xmlns`, `xmlns:*`, `xml:*` and `xlink:*` (but `xlink:href`, which is `href`) are
  XML's: every target writes SVG's namespace itself, and the HTML parser and the clients
  disagree about namespaced attributes.

### [UF3006]{#UF3006} unknown-attribute

**Error.** The attribute is not an attribute of this element.

Elements take HTML's attributes: the global ones (`id`, `class`, `title`, `hidden`, …),
their own (`href` on `<a>`, `alt` on `<img>`), ARIA's `role` and `aria-*`, and `data-*`.
SVG elements take SVG's attributes, in SVG's own case (`viewBox`, `stroke-width`).
Frameworks treat other names inconsistently: Vue sets a name that matches a DOM property
as that property, and React and Solid give some names meaning of their own.

Use the element's attribute, or a `data-*` attribute for your own data.

A listener (`onClick`) listens to an event an element receives: not one only the window
receives (`onHashchange`), not one no target listens to alike (`onSelectionchange`), with
one option suffix at most (`Capture`, `Once` or `Passive`), and `Passive` only on `wheel`,
`touchstart` and `touchmove`, where it lets scrolling go on.

### [UF3007]{#UF3007} duplicate-attribute

**Error.** The element has the same attribute twice.

Attribute names are case-insensitive in HTML, and `className` is `class`. With the same
attribute twice, React keeps the last value, the HTML parser the first, and Vue and Svelte
fail to compile. Keep one.

A spread sets every key its type declares, so a key that is also written on the element,
or set by another spread, is set twice too. `class` is the exception: one spread's `class`
merges with the element's own. A class name listed twice in one `class` is reported as
well: Angular merges a static class with a bound one through the class list, which drops
the repeat the other targets keep. The fix lists a static class's names once. So is a
second `key` on a list's element: the list has one key.

### [UF3008]{#UF3008} unportable-attribute-value

**Error.** The targets would render this attribute value differently.

Some values cannot be rendered the same way on every target, and some hold code or a
document the compiler cannot analyse, which it never copies into an output:

- `javascript:` URLs run code the compiler cannot analyse, and React blocks them.
  Event handlers are the way to run code.
- `srcdoc` holds an HTML document, scripts included, which the frame runs as the page's
  own origin unless it is sandboxed. A `data:` URL that a frame loads (an `<iframe>`'s or
  an `<embed>`'s `src`, an `<object>`'s `data`) is a document too. Load the document from
  a URL, or write its markup in the component. `data:` images and media, and `blob:` URLs,
  hold no code the page runs, and are accepted.
- An empty `src`, or an empty `href` outside `<a>`: React drops it and warns.
- `hidden="until-found"`: React renders `hidden` as a boolean.
- A number out of range, or not a number, in a numeric attribute (`rows`, `span`,
  `<li value>`): renderers that set the DOM property rewrite or reject it.
- A class name holding whitespace other than ASCII's (a no-break space): Angular splits
  class names there, and the other targets keep it in the name.
- An attribute that React and Qwik type as a number (`tabindex`, `colspan`, `aria-level`)
  with a value that is not one: they write it as a number literal.
- An ARIA value ARIA does not define (`aria-hidden="yes"`, `aria-live="loud"`), or a
  `role` that is not one of ARIA's roles: assistive technology ignores it, and Svelte
  warns about it.
- A value of an enumerated attribute that some target's types do not list (a `<bdo>`'s
  `dir="auto"`, `role="generic"`, `autocomplete="bday"`, a `<button>`'s `type="menu"`):
  that target's output fails its type-check. The message lists the values every target
  takes.

### [UF3009]{#UF3009} ambiguous-jsx-text

**Error.** JSX implementations read this text differently.

JSX does not define its text exactly, and its implementations disagree. Babel (which
Vue's and Solid's JSX use) decodes character references first and then trims the lines,
trimming only spaces and tabs. TypeScript, oxc and esbuild trim the raw lines first, also
trimming Unicode whitespace such as a no-break space, and read U+2028 and U+2029 as line
breaks. So `&#32;` at the end of a line, `&#10;`, a tab, or a raw no-break space next to a
line break means one thing to some tools and another to the rest.

The compiler lowers text only where every implementation agrees. Write such characters
as references (`&nbsp;`), write a space for a tab, and keep a significant space on the
same line as the text it separates. Numeric references the implementations decode
differently (`&#+65;`, a surrogate such as `&#xD83D;`, a number past U+10FFFF) are
reported too, in attribute strings as well.

### [UF3010]{#UF3010} unportable-character

**Error.** HTML would not keep this character.

Each target renders the component's markup on the server as HTML, and the browser parses
it, so a static value must hold only characters the HTML parser keeps as they are:

- a carriage return becomes a line feed (Svelte's compiler converts it too); in a file
  with CRLF line endings, a value written across lines holds one;
- NUL (U+0000) is dropped from text and replaced in attribute values;
- a lone UTF-16 surrogate cannot be encoded in UTF-8;
- the control characters other than whitespace, and the noncharacters, are not allowed
  in an HTML document.

Remove the character. A carriage return from a line ending has a fix.

### [UF3011]{#UF3011} html-only-reference

**Warning.** JSX does not decode this HTML character reference.

JSX decodes only the named character references of XHTML 1.0 (`&amp;`, `&nbsp;`,
`&copy;`), and numeric ones (`&#x2713;`). The names HTML added later (`&check;`,
`&rbrace;`, `&NewLine;`) stay as written: every target renders `&check;` as those seven
characters, where an HTML or Vue template would show ✓.

Write the numeric reference for the character (the fix, where it changes nothing else),
or `&amp;check;` for the text itself.

### [UF3012]{#UF3012} jsx-outside-template

**Error.** JSX can only be in a component's template.

A component's template is the JSX its last statement returns, with the slot functions in
it. The compiler lowers that tree to each target's template, and Vue's, Svelte's and
Angular's templates are not JSX: they have no counterpart for JSX kept in a variable,
returned from a helper, passed as a prop that is not a slot, or used as a value (an
attribute's value, a function's argument, an array's element). JSX can be a child, a
branch of a conditional child (`c ? <A /> : <B />`, `c && <A />`) or the element a `.map`
child renders.

<!-- prettier-ignore -->
```tsx
function renderIcon() {
  return <i class="icon" />; // rejected: a helper that returns JSX
}
```

Inline the JSX where it is used, move it into a slot function, or extract a component.

### [UF3013]{#UF3013} missing-key

**Error.** A list's element needs a key.

A `.map` child renders one element per item, and the frameworks match the elements of
two renders by their `key`. Without one, React warns and the targets disagree about
which element an item keeps.

<!-- prettier-ignore -->
```tsx
{items.map((item) => <li key={item.id}>{item.name}</li>)}
```

Key the element by something unique and stable in the item. The fix keys it by its index,
which is unique but moves with the item: review it.

### [UF3014]{#UF3014} misplaced-key

**Error.** A key belongs on the element a list renders.

`key` is not an attribute: it tells the frameworks which item of a list an element
renders, and only the element a `.map` callback returns has one. Elsewhere React and Vue
use it to remount an element and the others ignore it. A constant `key` on a list's
element gives every item the same key.

The fix removes a misplaced key, and keys a list's element by its index.

### [UF3015]{#UF3015} invalid-list

**Error.** A list is written `source.map((item, index) => <element key={…}>…</element>)`.

A `.map` child lowers to each target's list: Vue's `v-for`, Svelte's `{#each}`, Angular's
`@for`. Its callback is an arrow function with one or two plain parameters, the item and
its index, that returns one element:

<!-- prettier-ignore -->
```tsx
{users.map((user, index) => (
  <li key={user.id}>{index + 1}. {user.name}</li>
))}
```

Read an item's members as `item.name` rather than destructuring it (an entry of
`Object.entries` as `entry[0]` and `entry[1]`), and wrap several elements in one. An item
that renders or not is filtered out before mapping (`users.filter((user) =>
user.active).map(…)`); one that renders one element or another keeps one keyed element
that holds the conditional (`<li key={link.id}>{link.href ? <a …>…</a> :
<span>…</span>}</li>`).

### [UF3016]{#UF3016} non-text-interpolation

**Error.** An expression child must render text.

An expression child renders its value as text. JSX renders `true`, `false` and arrays
its own way, and the template targets render them as text (`{{ true }}` is "true" on
Vue), so an expression child must be a string or a number, or `null` or `undefined`, which
render nothing.

Turn the value into text: `done ? "Done" : "Open"` for a boolean, `.join(", ")` or
`.map(…)` for an array, a member for an object. A literal `{true}` or `{false}` child
renders nothing: remove it.

### [UF3017]{#UF3017} dropped-line-feed

**Error.** The HTML parser drops a line feed at the start of this element.

The HTML parser drops a line feed that starts a `<pre>`, a `<textarea>` or a `<listing>`,
and React's server renderer writes one more to keep it. Server-rendered HTML and a client
render then disagree about the first line.

A text after a conditional or a list that can render nothing starts the element when it
does: React's and Astro's servers then write nothing before it, so the parser drops its
line feed, and the other targets write a comment, which keeps it.

Start the element's text with something other than a line feed.

### [UF3018]{#UF3018} unportable-binding

**Error.** The targets render or type this bound value differently.

A bound value renders by the rules of where it is bound, and the targets agree only for
some kinds of value:

- a boolean attribute (`disabled`) takes a boolean; ARIA's true/false states
  (`aria-hidden`), `draggable` and `spellcheck` also take booleans, as `"true"` and
  `"false"`;
- an attribute some target's types restrict to a list of tokens (`autocomplete`,
  `inputmode`, `role`, `aria-live`, SVG's `fill-rule`) takes a string literal, or a union
  of them, that every target's types accept: the diagnostic lists them;
- `data-*` and other attributes take strings and numbers: Qwik drops `false` there, React
  drops it on some, and the others write `"false"` (write `String(value)`);
- an attribute React and Qwik type as a number (`tabindex`, `colspan`) takes a number, and
  one some target's types declare as a string (`title`, `id`, `aria-label`, SVG's `d`)
  takes a string;
- a class name takes a string, a style value a string, or a number where CSS needs no
  unit (`opacity`, `line-height`): React and Qwik add `px` to other numbers but `0`, and
  Qwik also to SVG's stroke and opacity properties (`stroke-width`), which React leaves
  bare. A literal `0` is the value `0` on any property;
- a list's source is an array, and its key a string or a number that reads the item or
  its index: a key that reads neither is the same for every item, which Vue and Svelte
  reject. It identifies the item within its own list, so it reads no variable of a list
  around it: Angular's `track` reads only its own item, `$index` and the component's
  members. A source that can be absent is defaulted, `(items ?? []).map(…)`, which the
  fix writes for `items?.map(…)`.

`null` and `undefined` leave the attribute or the declaration out everywhere, but for a
`value` some targets set as a property (an `<li>`'s, a `<meter>`'s, an `<option>`'s:
UF1002). Convert the value, or bind it where its kind renders alike.

### [UF3019]{#UF3019} nondeterministic-render

**Error.** Rendering must not depend on time, chance or the machine.

A component renders on the server and again in the browser, and both renders must give
the same markup (plan §4.5): rendering is a function of props, state and slots.
`Date`, `Intl`, `crypto`, `performance`, `globalThis` and `Math.random` read the clock,
chance or the machine, and `toLocaleString`, `toLocaleDateString`, `toLocaleTimeString`,
`toLocaleUpperCase`, `toLocaleLowerCase` and `localeCompare` read the machine's locale.

The rule holds for what rendering reads too: a getter (a `computed`'s, a watcher's source),
an initial value (of a `ref`, a `const`, a `let`), which the setup runs on the server as well,
and a local function a template, a getter or an initial value calls. Client code (a handler,
a watcher's callback, a lifecycle hook) runs only in the browser, and may read them.

Pass the value in as a prop, computed where it is decided, or set it from client code.

### [UF3020]{#UF3020} unresolved-reference

**Error.** The name is no prop, setup binding, list item or global code can read.

An expression in the template reads the component's props, the bindings its setup
declares, the item and index of the lists around it, the parameters of the arrow functions
in it, and a few pure globals: `undefined`, `NaN`, `Infinity`, `Math`, `Number`, `String`,
`Boolean`, `Array`, `Object`, `JSON`, `parseInt`, `parseFloat`, `isNaN`, `isFinite` and the
URI functions. The targets can reach nothing else: Angular's templates see only the
component's members, and the outputs run where `window` may not exist.

Setup code reads more. A getter and an initial value also read `Map`, `Set`, `WeakMap`,
`WeakSet`, `Symbol`, the error constructors and `structuredClone`; client code (a handler,
a watcher's callback, `watchEffect`, a lifecycle hook) also reads every global lib.dom
declares (`document`, `localStorage`, `location`, `history`, `fetch`, `URL`,
`URLSearchParams`, `FormData`, `AbortController`, the observers, `HTMLInputElement`,
`KeyboardEvent`, …), `console`, `Promise`, `Date`, `Intl`, `performance` and `crypto`, since it
runs only in the browser, where every target runs it as written. It reads through `window` the
members whose bare name reads like the component's own (`name`, `status`, `top`, `length`,
`event`, `open`, `close`, `focus`, `innerWidth`, `scrollY`, the `on…` handlers, …), which a
missing declaration or a typo would read silently: the likely fix writes `window.innerWidth`.

A module's top-level `const` reads the module's other constants, the values it imports from
shared `.ts` modules and the globals a getter reads: the module computes it as it loads, on the
server too.

Declare the value as a prop or in the setup, or check the name's spelling.

### [UF3021]{#UF3021} impure-render-expression

**Error.** A template expression must not change anything.

Rendering is a pure function of props, state and slots (plan §4.5): a framework renders
when it decides to, sometimes twice, and Svelte throws when a template expression changes
state. So a template expression cannot assign, update or `delete`, use `this`, `await`,
`yield`, `void` or the comma operator, define a function or a class, or call a method that
changes its receiver: `sort`, `reverse`, `splice`, `push`, `pop`, `shift`, `unshift`,
`fill`, `copyWithin`, and `Object.assign` and its kin.

Use the methods that return a new array: the fix writes `toSorted`, `toReversed` and
`toSpliced`. An arrow function is a call's argument (`items.filter((item) => item.on)`).

The rule is the template's. A handler is no template expression: it runs on an event, and
may write state and emit, as statements of their own (UF2011, UF2017).

### [UF3022]{#UF3022} invalid-class-or-style

**Error.** The class or style is malformed.

A `class` and a `style` are lowered part by part, and every target writes the parts its
own way, so each part must be one the targets read alike:

- class and style objects have plain keys: no computed keys, spreads or methods;
- a style string parses as CSS declarations, and a style sets something;
- each property is one the browsers know (or a custom property, `--gap`): an unknown name
  is almost always a typo, which no browser applies and Solid's lint rejects;
- a custom property's name is in lower case: Angular's compiler and its server renderer
  lowercase it, so `var(--myGap)` would not find `--myGap` there;
- a style sets each property once, and never a shorthand beside one of its longhands
  (`margin` and `marginTop`), or a flow-relative property beside a physical one it can be
  (`marginInlineStart` and `marginLeft`): React's, Solid's and Qwik's style objects cannot
  keep the order that decides the result;
- no `!important`, which React's style objects drop;
- a static value reads the same to Angular's style parser, which knows no escapes or
  comments: a string holds no escaped quote of its own kind (put the other quote around
  it), the parentheses inside strings balance (write `\28` for a lone one), and a comment
  holds no quote, parenthesis or `;`.

Write each property once, with its final value.

### [UF3023]{#UF3023} non-nullable-operand

**Error.** The operand of `??` or `?.` is never null or undefined.

`a ?? b` and `a?.b` act only when `a` is `null` or `undefined`. When `a` can be neither
where it is read, the operator does nothing, and Angular's compiler rejects it (NG8102,
NG8107). `a` can be neither when its type excludes both, or when a condition around it
rules them out as TypeScript narrows it: a test of `a` itself, through `!`, `&&` and `||`,
a comparison with `null`, `undefined` or a value, `typeof`, a member read through `?.`,
`Array.isArray`, or a discriminant of the union `a` belongs to:

<!-- prettier-ignore -->
```tsx
{box.inner && <p title={box.inner?.title}>…</p>} // reported: write `box.inner.title`
```

Remove the operator, which the fix does, or make the prop optional if it can be absent.

Where the targets' checkers may read `a` apart, the compiler reports, as not supported
yet (UF1002), a use that relies on a narrowing some of them do not see: a member, or a
prop of the object form, a condition narrows outside a list's callback (Angular's loops
keep the narrowing, the JSX targets' callbacks forget it); a prop an expression's own
conditional narrows, used in an arrow function in it (Solid copies it with `props.x`,
which the closure forgets); and a prop a list's key uses (Angular's `track` reads the
input again). Testing the value, reading it through `?.`, giving it a value with `??`,
comparing it for equality and writing it into a string read alike everywhere. Where the
compiler does not follow a test (an equality with a value that is no literal), Angular
may narrow `a` and reject the operator, which is reported too. A destructured prop a
conditional child narrows stays narrowed in its branch's lists and arrow functions on
every target. Reading a member of a value a condition shows absent is reported as well.

A ref, a local function and a handler's event are never null or undefined either:
`count?.value` and `event?.key` are reported, with the fix that writes `.`.

### [UF3024]{#UF3024} shadowed-binding

**Error.** A parameter or a local shadows a name the outputs read, or is never read.

The targets rewrite the names a template expression reads: Solid reads a prop `label` as
`props.label`, and Angular reads the template variable it declares for it,
`@let label = this.label();`. A `.map` or arrow function parameter that has the name of a
prop, of the object form's props parameter, of the item or index of a list around it, of
a global an expression may read (`String`), the name `props` or `rawProps`, a name
starting with `$` (Angular's `@for` declares `$index`, `$count` and others), `Fragment`
(Astro's output imports it to render `<>`) or a name starting with `_` but `_` itself
(Vue's compiled render functions declare `_ctx`, `_cache`, `__props` and helpers such as
`_toDisplayString`) would capture those rewrites or those names. A parameter named after
one of Angular's expression keywords (`as`) cannot be read in its templates at all.
Rename the parameter.

Setup code and handlers follow the same rule for their functions' parameters, and their
`const`s, `let`s and `catch` parameters take no name of a prop, of the props parameter, of a
binding of the setup (`emit` included), of a list variable around them, nor `props` or
`rawProps`: the targets rewrite those names in the code (`count.value` to `count()`, a prop
to `props.label`), and cannot rename a local.

An arrow function's parameter that nothing after it reads fails the outputs' lint
(`no-unused-vars`). The fix removes it. (A list's unread index needs no fix: the targets
leave it out.)

### [UF3025]{#UF3025} unsupported-conditional

**Error.** A conditional child is written `c ? <A /> : <B />` or `c && <A />`.

`x || <B />` and `x ?? <B />` render either the value of `x` or an element, which no
template target can express as one conditional. Write the conditional with `?:`: `x ? x :
<B />` for `||`, and `x != null ? x : <B />` for `??`, which renders `0` and `""` as `??`
does.

<!-- prettier-ignore -->
```tsx
{message ? message : <p>All good.</p>}
{count != null ? count : <p>None yet.</p>}
```

When `x` is a prop or a member of one that renders as text, the fix writes the
conditional.

### [UF3026]{#UF3026} ref-without-value

**Error.** A ref's value is read as `.value`.

A ref (`ref`, `computed`, `useTemplateRef`) holds its value in `.value`, which code reads and
writes: `count.value`. Vue's templates unwrap a ref, so `{count}` renders its value there, but
the other targets keep the value apart (React's `count` is the value, Solid's `count()`,
Angular's `this.count()`), so the compiler reads `count.value` alone, as one name.

<!-- prettier-ignore -->
```tsx
<output>{count}</output>       // rejected
<output>{count.value}</output> // accepted
```

The fix reads `.value`. A ref is passed whole only where an API takes it: a watcher's source
(`watch(count, …)`) and a template ref's element (`ref={input}`). A ref has no member but
`value`, and is never null or undefined (`count?.value` is UF3023).

### [UF3027]{#UF3027} invalid-template-ref

**Error.** A template ref is attached by the `ref` of one element, outside lists.

`useTemplateRef<T>()` declares a template ref, and `ref={input}` on an element attaches it:
once the element is mounted, client code reads it as `input.value`. A template ref holds one
element, so exactly one element attaches it, outside every list: in a list, Vue fills it with
an array of elements and the other targets with the last one.

<!-- prettier-ignore -->
```tsx
const input = useTemplateRef<HTMLInputElement>();
// …
<input ref={input} />
```

The compiler reports a `ref` whose value is no template ref (a string, as Vue writes it, a
callback, another binding), and a template ref attached twice, inside a list, or never.

### [UF3028]{#UF3028} template-ref-use

**Error.** Client code never rebuilds a rendered element by hand.

Every framework renders its elements from state, so client code does not change a rendered
element's structure or its text: `textContent`, `innerHTML`, `innerText`, `outerHTML`,
`outerText`, `append`, `appendChild`, `prepend`, `remove`, `removeChild`, `replaceChild`,
`replaceChildren`, `replaceWith`, `insertBefore`, `insertAdjacentElement`, `insertAdjacentHTML`,
`insertAdjacentText`, `before`, `after` and `normalize` (eslint-plugin-svelte's
`no-dom-manipulating`). Nor does it change the classes of an element whose `class` the template
binds (`classList.add()`, `className`, `setAttribute("class", …)`), or the style of one whose
`style` it binds (`style.color`, `style.setProperty()`): each framework patches what its
template binds its own way, so Angular keeps a class it did not add and Qwik drops a style
property it did not set. Bind the class or the style to state instead, or make the change on an
element whose `class` or `style` the template leaves alone. A class, a style or an attribute
the template does not bind is the code's own on every target (an autosizing textarea's
`style.height`, `setAttribute("aria-busy", …)`, `dataset.x`), and so is any attribute: each
target compares a bound attribute with the value it last wrote, not with the DOM's.

A rendered element is a template ref's, the handler's event's `currentTarget` and `target`, and
any node reached from one (`parentElement`, `firstChild`, `querySelector(…)`, the items of
`querySelectorAll(…)` and `children`, in a loop or an array method's callback), itself or
through a local. An element of a template ref is judged by the elements the ref is attached to,
a listener's `event.currentTarget` by the elements whose listeners run it (a function used as
several listeners, or passed the event, by each of them), its `event.target` by those and what
they hold, and any other by every element of the template. Other properties and methods
(`focus()`, `select()`, `scrollIntoView()`, `showModal()`, `scrollTop`, an input's `value`,
measurements) are fine, as is the document's own `<body>`.

### [UF3029]{#UF3029} invalid-handler

**Error.** A handler is a local function's name or an arrow function.

A listener (`onClick`, `onKeydown`) runs a handler: the name of a function the setup declares
(`onClick={save}`), which receives the event as its first parameter, or an arrow function
written in place (`onClick={(event) => …}`), whose one parameter is the event. Every target
calls either with the event, and Angular makes each a method of its class.

<!-- prettier-ignore -->
```tsx
<button onClick={save}>Save</button>              // accepted
<button onClick={() => remove(item.id)}>×</button> // accepted
<button onClick={save()}>Save</button>            // rejected: runs while rendering
<button onClick="save()">Save</button>            // rejected: code in a string
```

The compiler reports a call, a string, a conditional, a member, a function expression, `emit`,
and a function whose first parameter does not take the event's interface: one it extends, or a
union of interfaces that holds one (`event: MouseEvent | KeyboardEvent` on a function a click
and a key share, whose members are those of the interface both extend). A handler in a list
that reads the list's item or index, and a handler that reads a value a condition around it
narrows (`{user && <button onClick={() => greet(user.name)}>…</button>}`), is one call of a
local function or of `emit`, with arguments Angular's template statements read
(`() => remove(item.id)`): Angular passes the item, or the narrowed value, to its method
there. Writing the value is no read: `{open.value && <button onClick={() => (open.value =
false)}>…</button>}` needs no narrowing, though a compound assignment (`+=`), `++` and a
member's write do read it. A handler's return value is discarded on every target.

### [UF3030]{#UF3030} inaccessible-handler

**Error.** A handler is reachable with the keyboard and announced.

A listener on an element a keyboard user cannot reach, or a screen reader does not announce as
interactive, leaves them without the action. Svelte's compiler warns about it, which fails its
check, so the compiler reports it for every target, judged on the source's listeners as Svelte
5.57.1's accessibility rules judge them:

- `a11y_click_events_have_key_events`: a click handler on a non-interactive element without a
  `keydown`, `keyup` or `keypress` handler;
- `a11y_no_static_element_interactions`: a handler for a mouse, pointer, touch, key or drag
  event on an element with neither semantics nor a role (`<div>`, `<span>`);
- `a11y_no_noninteractive_element_interactions`: a click, mouse button or key handler on a
  non-interactive element or role (`<li>`, `<p>`, `role="listitem"`);
- `a11y_interactive_supports_focus`: a handler on an element with an interactive role
  (`role="button"`) that is not focusable (no `tabindex`);
- `a11y_mouse_events_have_key_events`: `mouseover` without `focus` or `focusin`, `mouseout`
  without `blur` or `focusout`.

Put the handler on a `<button>` or a form control. An element hidden from assistive technology
(`aria-hidden="true"`) and one with `role="presentation"` or `role="none"` are not judged.

### [UF3031]{#UF3031} ref-narrowing

**Error.** A ref's value, or a prop in code, is read into a local before its union is narrowed.

Solid and Angular read a ref's value through a call (`query()`, `this.query()`), and Angular
every input (`this.size()`), which TypeScript never narrows. A narrowing to a value that is
there survives the call: where code relies on a condition or an assignment before it showing a
ref's value, a prop or a member of either present (`if (selected.value) emit("select",
selected.value)`, `if (!draft.value.email) return;`, `selected.value = member;`), the targets
that read it through a call or a mirror assert it (`selected()!`). A narrowing to one kind of a
union does not: a ref's value, a prop or a member of either that is one of several kinds
(`string | number`, `string[] | string`, `"a" | "b"`) or of several object shapes is used where
a condition narrows it (`typeof`, `Array.isArray`, `===`, a discriminant) only as a member every
kind has, a test, an equality's operand, a string's part, or an argument a parameter takes
whole. It is read into a local, returned, assigned, or put in a literal that goes to a call,
only before such a condition, or where the written type of the local, the result or the target
holds every kind.

The same holds for a prop read in a getter, an initial value or client code: React and Solid
read a prop as a property (`props.size`), whose narrowing TypeScript forgets in a nested
function. The template reads props as it always has.

<!-- prettier-ignore -->
```tsx
if (typeof query.value === "string") emit("search", query.value.trim()); // rejected
const text = query.value; if (typeof text === "string") emit("search", text.trim()); // accepted
if (selected.value) emit("select", selected.value); // accepted
```

A conditional child still narrows its branch on every target: Solid passes it an accessor, and
Angular reads it through `@let` (`{typeof value.value === "string" &&
<p>{value.value.trim()}</p>}`). In code, the likely fix reads the value into a local before the
first statement that narrows it, the guard clause or the `if` (`const currentMode = mode; if
(currentMode !== "a") return; …`). A value that an assignment narrows (`value.value = "abc";
value.value.length`) is kept in a local, which the code writes and reads (`const next = "abc";
value.value = next; next.length`).

### [UF3032]{#UF3032} event-parameter-use

**Error.** A handler reads only the members every target's event has.

React passes a handler its synthetic event, which has only some of the DOM event's members:
it lacks `isComposing`, `composedPath`, `stopImmediatePropagation`, `offsetX` and others, and
Qwik passes `currentTarget` apart. So a handler's event is used only as `event.member`, read
or called, for a member both the DOM's and React's event of that listener have (`key`, `code`,
the modifier keys, `button`, `clientX`, `currentTarget`, `target`, `preventDefault()`, …), or
passed whole to a local function's event parameter; never read through a computed member,
destructured, stored or passed elsewhere.

<!-- prettier-ignore -->
```tsx
if (event.key === "Enter" && !event.isComposing) send(); // rejected: React lacks it
```

Read what every target has, or listen natively from `onMounted` through a template ref.

### [UF3033]{#UF3033} deferred-event-control

**Error.** `preventDefault()` and `stopPropagation()` run while the event is dispatched.

`event.preventDefault()` and `event.stopPropagation()` act only while the browser dispatches
the event. A call after an `await`, or in a function the handler hands on (a timer's callback,
a promise's continuation), runs once the browser has acted on the event, on every target: the
form is submitted, the key typed, the click passed on. Every other call runs in place, under
whatever test or `switch` case it is in, beside other statements or after a guard clause.

Qwik runs a handler after the event, and runs at once only the controls it can lift out of
it (`preventdefault:click`, `sync$`): those its tests and guard clauses decide from the event
alone. Where Qwik cannot, it reports `conditional-event-control` (UF4001) at the control.

<!-- prettier-ignore -->
```tsx
async function subscribe(event: SubmitEvent) {
  event.preventDefault(); // accepted
  await save();
  event.preventDefault(); // rejected: the form is submitted by then
}

function onKeydown(event: KeyboardEvent) {
  if (event.key === "ArrowDown") {
    event.preventDefault(); // accepted
    move(1);
  }
  setTimeout(() => event.stopPropagation()); // rejected: the event is over by then
}
```

Call it before the first `await`, under the same test if it is conditional, and in the
handler itself rather than in what it defers.

### [UF3034]{#UF3034} passive-prevent-default

**Error.** A passive listener does not call `preventDefault()`.

A passive listener (`onWheelPassive`, `onTouchstartPassive`, `onTouchmovePassive`) tells the
browser that it never prevents the event's default, so the browser scrolls at once and
ignores its `preventDefault()`. The call prevents nothing on any target, and Angular, which
runs an element's listeners of one event in one listener, runs a passive one beside one that
is not passive in a listener that is not passive, where the call would prevent. So what a
passive listener runs, its handler and the local functions it passes its event to, calls no
`preventDefault()`.

<!-- prettier-ignore -->
```tsx
<div onWheelPassive={(event) => { event.preventDefault(); zoom(event.deltaY); }} /> // rejected
<div onWheel={(event) => { event.preventDefault(); zoom(event.deltaY); }} />        // accepted
```

Remove the call, or make the listener not passive where it must prevent the default. The
safe fix removes the call from a handler written in place, and the listener where the call
is all it does.

### [UF3035]{#UF3035} unknown-prop

**Error.** The component declares no such prop (layer 2).

A component element passes props by name, and the compiler reads the child's declarations
through its resolver. An attribute that is no prop, model or slot of the child, nor `class`,
`style`, `key` or `ref`, is rejected: no target passes an undeclared attribute through to the
child's root.

<!-- prettier-ignore -->
```tsx
<Field lable="Name" /> // rejected: did you mean `label`?
```

Pass a prop the child declares. The likely fix renames the attribute to the closest prop.

### [UF3036]{#UF3036} unknown-event

**Error.** The component declares no such event (layer 2).

`onX` on a component listens to an event the child declares with `defineEmits`, and its
handler receives the event's payload. No target passes a native listener through to the
child's root, so an `onX` the child does not declare is rejected.

Listen to an event the child declares, or to the native event on an element inside the child.
The likely fix renames the listener to the closest event.

### [UF3037]{#UF3037} unknown-model

**Error.** The component declares no such model (layer 2).

`v-model:open` binds a model the child declares with `defineModel`. A name the child does not
declare is rejected.

Bind a model the child declares. The likely fix renames the binding to the closest model.

### [UF3038]{#UF3038} unknown-slot

**Error.** The component declares no such slot (layer 2).

A parent fills the child's default slot with its children, and the other slots with a slot
object, `{{ title: () => <h2>Profile</h2> }}`. A key the child does not declare with
`defineSlots`, or children given to a child with no default slot, is rejected.

Fill a slot the child declares. The likely fix renames the key to the closest slot.

### [UF3039]{#UF3039} literal-outside-union

**Error.** The value is not one of the prop's literals (layer 2).

A prop typed by a union of literals, `tone?: "info" | "warning"`, takes one of them. A literal
outside the union is rejected where the parent writes it.

<!-- prettier-ignore -->
```tsx
<Badge tone="warn" /> // rejected: did you mean "warning"?
```

Pass one of the prop's literals. The likely fix replaces the value with the closest one.

### [UF3040]{#UF3040} invalid-slot-content

**Error.** A slot object holds arrow functions that return JSX.

A parent passes named and scoped slots in one object after the component's children: `{{
title: () => <h2>Profile</h2>, item: ({ item }) => <li>{item.name}</li> }}`. Each member is an
arrow function that returns JSX, whose one parameter, if it has one, is the scoped slot's
props, as a destructuring pattern or an identifier; or it is the parent's own slot, passed on
(`{{ title: slots.title }}`).

Write each slot as an arrow function that returns JSX.

### [UF3041]{#UF3041} invalid-slot-use

**Error.** A slot is rendered, tested or forwarded, and nothing else.

A component renders a slot as a child, `{slots.title?.()}` or `{slots.item?.({ item })}`, with
fallback content after `??`; tests whether the parent filled it with `slots.title` as a
condition; and forwards it in a child's slot object, `{{ title: slots.title }}`. Each target
writes each of these in its own form, so any other use of `slots` is rejected: storing a slot,
calling it in setup code or passing `slots` itself.

Use one of the three forms.

### [UF3042]{#UF3042} invalid-v-model

**Error.** `v-model` binds a ref's value to a form control or a named model.

`v-model={text.value}` binds a form control's state: the value of a text-like `<input>`, a
`<textarea>` or a `<select>`, the checked state of a checkbox or a radio, or an array for a
checkbox group or a `<select multiple>`. `v-model:open={open.value}` binds a model a component
declares. The value is a ref's or a model's `.value`, and `trim`, `lazy` and `number` apply
only to a control that holds text.

<!-- prettier-ignore -->
```tsx
<Toggle v-model={open.value} />      // rejected: the model has no name
<Toggle v-model:open={open.value} /> // accepted
```

Bind a ref's value, name the model on a component, and drop a modifier the control cannot use.
The safe fix names the model of a child that declares one.

### [UF3043]{#UF3043} component-listener-option

**Error.** A component's event takes no listener option.

Capture, once and passive (`onClickCapture`) are options of a DOM listener. A component's
event is no DOM event: the child calls the listener when it emits, so an option suffix on a
component's listener means nothing.

Drop the suffix. The safe fix does.

### [UF3044]{#UF3044} open-dynamic-component

**Error.** `<component is>` chooses from a statically known set.

`<component is={nested.value ? "h3" : "h2"}>` renders one of a set the compiler knows: a tag
literal, a component by its name, a conditional whose leaves are all tags or all components, or
a value typed as a union of tag literals, such as a prop or a `ref`. Angular and the typed
targets write every candidate, so a value only the run time knows is rejected, as is a set that
mixes tags and components.

Write the candidates out in a conditional, or type the value as a union of tag literals.

### [UF3045]{#UF3045} dropped-fallthrough

**Error.** The component renders no `class` or `style` passed to it.

A parent's `class` and `style` on a component fall through to the child's root element, or
pass on to its root component. A child that turns fallthrough off with `defineOptions({
inheritAttrs: false })`, or whose root is a fragment, a conditional or a list, has no root to
take them, so passing them is rejected rather than dropped.

Style an element around the component, or give the child one root element or a prop for its
class.

### [UF3046]{#UF3046} invalid-component-ref

**Error.** A component ref holds what the component exposes.

`ref={field}` on a component holds what the child exposes with `defineExpose`, which client
code calls: `field.value?.focus()`. The ref's type, `useTemplateRef<FieldApi>()`, is an object
type of the exposed functions. A ref on a component that exposes nothing, or whose type names
a member the component does not expose, is rejected.

Expose the function in the child, or remove it from the ref's type.

### [UF3047]{#UF3047} unknown-component

**Error.** The tag names no component in scope.

A PascalCase tag names a component: one imported from a `.uf.tsx` module, one of the same
module, or the component itself. Any other name is rejected.

Import the component, or correct the tag. The likely fix renames the tag to the closest
component in scope.

### [UF3048]{#UF3048} open-spread

**Error.** A spread's keys are the ones its type declares.

A spread renders exactly the keys its object's type declares, each as a bound attribute. Keys
only the run time knows (an index signature, a type the compiler cannot see) cannot be
rendered alike by every target, so such a spread is rejected.

Type the object with its keys, or bind each attribute on its own.

### [UF3049]{#UF3049} reserved-spread-key

**Error.** A spread renders attributes: no listener, `key`, `ref` or `children`.

A spread renders attributes. Listeners, keys, refs and children each have a channel of their
own, which every target writes in its own form, so an object whose type declares an `onX`,
`key`, `ref` or `children` key cannot be spread.

Remove the key from the type, and pass the listener, key, ref or children on their own.

### [UF3050]{#UF3050} undefined-model-binding

**Error.** A model that can be `undefined` is bound to a ref that cannot hold it.

A model with neither a `default` nor `required: true` can be `undefined`, since a parent may
leave it unbound. React's output passes its changes with that type, through an
`onValueChange` that takes `string | undefined`, and a setter of a `string` state does not
type-check there. So a ref bound to it with `v-model:value` holds `undefined` too.

<!-- prettier-ignore -->
```tsx
const value = defineModel<string>("value"); // in Field
const text = ref("");
<Field v-model:value={text.value} />; // rejected
```

Give the model a `default` or `required: true`, or let the ref hold `undefined`:
`ref<string | undefined>(…)`.

### [UF3051]{#UF3051} raw-html

**Warning.** `innerHTML` renders markup that is not escaped.

`innerHTML` sets an element's content to the markup a string holds. The browser parses it
as HTML, and no target escapes or sanitises it, so markup from a user or another site can run
script in the page (cross-site scripting). Every target renders the markup as written.

<!-- prettier-ignore -->
```tsx
<div innerHTML={article.body} />
```

Render only markup you trust, such as your own content, or markup a sanitiser such as
DOMPurify has cleaned. Text is safer as children, `<p>{comment}</p>`, which every target
escapes.

### [UF3052]{#UF3052} raw-html-content

**Error.** `innerHTML` is the whole content of an element that holds content.

The markup `innerHTML` holds replaces the element's content, so it cannot be set beside
children: React and Vue reject both, and the other targets render them differently. It also
needs an element whose content is markup: a void element (`<br>`, `<img>`, `<input>`) holds
no content, and the content of `<textarea>`, `<title>`, `<option>`, `<script>`, `<style>`
and `<iframe>` is text.

Remove the children, or put the markup in an element of its own beside them:

<!-- prettier-ignore -->
```tsx
<section>
  <h2>{title}</h2>
  <div innerHTML={body} />
</section>
```

### [UF3053]{#UF3053} teleport-target

**Error.** `<Teleport>` needs `to`, a static CSS selector.

`<Teleport to>` mounts its content into the element `to` selects, once its component has
mounted. Each target selects that element its own way, from the selector as written, so `to`
is a string literal that selects something. A bound `to`, a template literal with
expressions, an empty string or no `to` at all can't be read when the component compiles.

<!-- prettier-ignore -->
```tsx
<Teleport to="body">
  <div class="toast">{message}</div>
</Teleport>
```

Write the selector as a string: `to="body"` or `to="#overlays"`.

### [UF3054]{#UF3054} teleport-content

**Error.** `<Teleport>` holds exactly one element.

The content of `<Teleport>` is one element, which may hold anything: text, components,
conditionals and lists. Svelte, Angular and Qwik move that one node into `to`, and remove it
when the component unmounts, so text, two elements, a component, a conditional, a list, a
slot or `<component is>` can't be the content itself, and neither can nothing at all.

Wrap the content in an element, and put a condition around the `<Teleport>`, not inside it:

<!-- prettier-ignore -->
```tsx
{open.value && (
  <Teleport to="body">
    <div class="dialog">
      <ConfirmDialog />
    </div>
  </Teleport>
)}
```

### [UF3055]{#UF3055} unknown-directive

**Error.** `v-name` applies no directive the module declares or imports.

An element applies a directive by its name in kebab case: `v-focus-trap` applies
`vFocusTrap` (ADR-0099). The module must declare that name at its top level with
`defineDirective`, or import it from the `.uf.ts` module that exports it. A constant, a
composable or a component of that name is no directive.

<!-- prettier-ignore -->
```tsx
import { vFocusTrap } from "./focusTrap.uf.ts";

<div v-focus-trap={open.value}>…</div>
```

`v-model` is the one built-in directive. Arguments (`v-name:arg`) and modifiers
(`v-name_mod`) are not supported yet.

### [UF3056]{#UF3056} invalid-directive-use

**Error.** A directive takes an element and a value that changes only when it should.

A directive's hooks run on the element it is written on (ADR-0099). A component, a
`<Teleport>`, a `<Transition>`, `<component is>` or a slot has no element of its own there,
so a directive goes on an element inside it.

Every directive takes a value, and its `updated` hook runs after a render in which the value
changed, as `Object.is` compares it. An object or array literal, a function written in place
or a `new` is a fresh value at each render on some targets and the same one on others, so
pass a state, a derived value, a prop, a setup function or a primitive instead:

<!-- prettier-ignore -->
```tsx
const options = computed(() => ({ initial: first.value }));

<div v-focus-trap={options.value}>…</div>
```

### [UF3057]{#UF3057} transition-child

**Error.** `<Transition>` holds one element, or one conditional of elements.

`<Transition>` runs its classes on the element it holds when that element enters or leaves
(ADR-0100). So its child is exactly one element, or one conditional whose every branch is
one element or nothing: `cond && <p />`, `cond ? <p /> : <div />` or an else-if chain.
Text, two nodes, a component, a slot, `<component is>`, a fragment or a list can't be that
child, and neither can nothing at all. The element itself may hold anything.

Wrap a component in an element, and keep the condition inside the `<Transition>`:

<!-- prettier-ignore -->
```tsx
<Transition name="fade">
  {open.value && (
    <div class="panel">
      <Details />
    </div>
  )}
</Transition>
```

### [UF3058]{#UF3058} transition-prop

**Error.** `<Transition>`'s `name` and `appear` are literals.

Each target writes the transition's class names when the component compiles (ADR-0100), so
`name` is a string literal that is not empty and holds no whitespace, and `v` when it is left
out. `appear` is the bare attribute, or `{true}` or `{false}` written as literals. A bound
`name`, a template literal with expressions, an empty `name`, one with whitespace, or a
bound `appear` can't be read then.

<!-- prettier-ignore -->
```tsx
<Transition name="fade" appear>
  <div class="toast">{message}</div>
</Transition>
```

To switch between two transitions, write two `<Transition>` elements in a conditional.

## Portability (capabilities)

### [UF4001]{#UF4001} unsupported-capability

**Warning.** A selected target cannot support a feature the component uses.

Each target declares, for every feature, whether it supports it natively, emulates it
with an inline helper, or cannot support it. The component uses a feature that a selected
target cannot support; the diagnostic points at its first use, and the message names the
feature and the target's reason. For example, Astro renders on the server only, so event
handlers are inert there.

A feature can also be a construct one framework renders differently from HTML and the
other targets. Vue's client, for example, selects the first option of a single-selection
list box (`<select size="2">` without `multiple`), where HTML selects none, so Vue
declares `listbox` unsupported, and the diagnostic points at the list box's `size`.

The severity comes from the target's capability matrix. With `strict: true`, portability
warnings are errors. Remove the feature, or drop the target.

### [UF4002]{#UF4002} sheet-order

**Info.** A selected target may cascade the component's sheets in another order.

Vue, React, Solid, Svelte and Astro load a component's scoped sheet as its module loads,
in import order: a child's sheet before its parent's, and siblings by their imports. Angular
and Qwik attach it when the component first renders: a parent's before its children's, and
siblings in the order they render. Where two sheets' rules of equal specificity match one
element, the later sheet wins, so the winner can differ on those two targets. That happens on
a child's root, which carries its styled parent's attribute too, on content filled into a
child's slot, and under `:deep()` and `:global()` (ADR-0063). The diagnostic points at the
component's stylesheet import, on every target that cascades in render order.

Where one rule must win, give it a higher specificity than the other, or keep the two
components' rules off the same element.

### [UF4003]{#UF4003} component-host

**Info.** A selected target renders an element between a component and its child's root.

Angular renders each child component inside a host element, `uf-<name>`, styled
`display: contents`, so it adds no box, and the page lays out as on the other targets.
Selectors still see it. A parent's rule that reaches a child's root through a combinator
(`.list > .row`, `.a + .row`, `.a ~ .row`) or a structural pseudo-class (`:first-child`,
`:last-child`, `:nth-child()`, `:only-child`) matches the host's place, not the root's, so it
may match differently there. A root Angular binds nothing on (`{{` in an attribute) does not
take the parent's scope attribute either. The diagnostic points at the first child component
a styled component renders.

Match a child's root by its class or its attributes rather than by its place or its parent.

### [UF4004]{#UF4004} generic-slot-props

**Info.** A selected target types a generic scoped slot's props by the type parameter's constraint.

A generic component's scoped slot passes props whose type names one of its type parameters,
such as `item: T` in `function List<T>(props: ListProps<T>)`. React, Vue, Svelte, Solid, Qwik
and Astro type a consumer's fill by the type argument its props give. Angular infers a
component's type parameter from its inputs alone, and a slot's directive cannot infer it, so the
slot's context takes the parameter's constraint, `unknown` where it has none (ADR-0068). The
component renders the same; only a consumer's type checking differs. The diagnostic points at
the slot, or at a consumer's fill of it.

Give the type parameter a constraint that names what consumers read, or accept the looser type
on Angular.

### [UF4005]{#UF4005} composable-effect-order

**Info.** A selected target runs a composable's effects apart from the caller's.

A composable that runs code in the browser (a watcher, an effect or a lifecycle hook) runs it in
its place among the caller's own on Vue, Svelte, Angular and Qwik, in source order. A
composable is a custom hook on React, which runs a component's effects in its own order, and
Solid queues a composable's watchers in its own module. On those two, code that relies on the
order of the composable's effects and the caller's may see another (ADR-0069). The diagnostic
points at the composable's call.

Make each effect depend on the state it reads, not on when another effect ran.

## Styles

### [UF5001]{#UF5001} shared-stylesheet

**Error.** A stylesheet is imported by a module that declares several components.

A sibling stylesheet (`import "./Button.css"`) scopes the elements of one component: the
compiler rewrites its selectors to match that component's scope attribute (ADR-0063). A
module that declares several components gives the sheet no single owner, so it cannot tell
whose elements the selectors mean.

Move each component that needs styles into a module of its own, with its own sheet, and
import it where it is rendered.

### [UF5002]{#UF5002} invalid-stylesheet

**Error.** A stylesheet is not valid CSS.

The compiler parses every imported stylesheet with lightningcss before it scopes it, and
the parser reports an error. The message names it, and the diagnostic points at it in the
sheet. A sheet that does not parse cannot be scoped, and the browsers would each recover
from it differently. An at-rule lightningcss does not know (`@apply`, `@custom-media`) is
reported too: the compiler cannot read its content, so its rules would reach the page
unscoped.

Fix the CSS at the reported place. Remove an unknown at-rule, or compile it to plain CSS
first.

### [UF5003]{#UF5003} unsupported-stylesheet-language

**Error.** A stylesheet is written in a preprocessor's language.

A component imports a `.scss`, `.sass`, `.less`, `.styl` or `.pcss` file. The compiler
scopes plain CSS only, because it reads the sheet itself with lightningcss and attaches the
scoped result to every target, where no preprocessor runs.

Compile the sheet to a `.css` file first, and import that. Nesting, custom properties,
`@layer` and `@media` are CSS, and need no preprocessor.

### [UF5004]{#UF5004} unscopable-selector

**Error.** A selector cannot be scoped to the component.

The compiler scopes every rule of a component's sheet to the component's own elements.
Some selectors cannot be scoped that way:

- `:root`, `html` and `body` outside `:global()`, which match no element of the component;
- `:host`, which only a shadow root has, and no target renders one;
- an empty `:deep()`, `:slotted()` or `:global()`, or one used where it means nothing, such
  as `:slotted()` in a rule with nested rules, or beside a selector it would leave unscoped;
- an empty `:is()` or `:where()`, which matches nothing;
- a namespace prefix (`svg|`, `*|`), which the compiler does not scope;
- a selector that tells an empty `class` or `style` from a missing one (`[class=""]`,
  `[style]`), which the targets render differently (ADR-0044).

Wrap a page-level selector in `:global()`, or move it to a global stylesheet. Select the
element without a namespace prefix, and by a class or a `data-*` attribute instead of an
empty `class` or `style`. Select the component's root by a class instead of `:host`, and give
a `:deep()` or `:slotted()` selector a rule of its own, at the top of the sheet.

### [UF5005]{#UF5005} stylesheet-not-found

**Error.** An imported stylesheet does not exist.

A component imports a sibling stylesheet that the compiler cannot read: no file is at the
path the specifier names, relative to the component's file.

Check the path and its case, which some file systems ignore and others do not, or create
the file.

### [UF5006]{#UF5006} unsupported-virtual-import

**Error.** A module that passes through is imported in a way the compiler cannot keep.

An import whose specifier starts with one of the `passThrough` prefixes (`virtual:` by
default) names a module a bundler plugin registers, such as a styling engine's. Every output
keeps it as written, and that plugin resolves it (plan §4.4). The compiler passes through two
forms only: named imports called in a `class` (`class={button({ size })}`), and a side-effect
import (`import "virtual:theme.css"`). A default, namespace or type-only import, or any other
use of an imported name, would reach the targets unanalysed, and a name that nothing calls
would reach every output as an unused import.

Import the module's class functions by name and call them in a `class`, or import the module
for its effect alone.

## Types

### [UF6001]{#UF6001} unresolved-type

**Error.** A type cannot be resolved.

The compiler reads a component's props, events, models, slots and injection keys from their
types (ADR-0067). It resolves a type the module declares, or one it imports from a relative
`.ts` file, a `.uf.tsx` or `.uf.ts` module, or a package through its `types` and `exports`. This
type names a declaration the type oracle cannot find: a name the module neither declares nor
imports, a file that does not exist, or a package without types.

Check the name, the import's path, and that the package ships its types. Global types other
than TypeScript's own library are not read: import the type instead.

### [UF6002]{#UF6002} unsupported-type-construct

**Error.** The type oracle cannot evaluate this type.

The default type oracle reads types as written, without a type checker (ADR-0067). It resolves
type literals, interfaces and aliases, `extends` chains, intersections, unions, literal unions,
generic declarations, and `Partial`, `Required`, `Pick`, `Omit` and `Readonly`. Conditional and
mapped types, `infer`, `keyof`, `typeof` and template-literal types need a type checker, so it
reports them at their span rather than guess.

Write the type with the constructs above, or compile with the tsgo type oracle,
`@unframework.dev/type-oracle-tsgo`, which resolves every construct through TypeScript.

### [UF6003]{#UF6003} type-not-exported

**Error.** An output must import a type its module does not export.

Each output imports by name the types its props, events and slots name, from the module that
declares them, rather than printing them again (ADR-0067). This type is declared in another
module without `export`, so no output can import it.

Export the type from its module. The likely fix adds `export` to its declaration.

### [UF6004]{#UF6004} props-not-object

**Error.** A props type is not an object type.

A component's props are the members of its props type: an object type literal, an interface,
or an alias, an intersection, an `extends` chain or a utility type that resolves to one
(ADR-0034, ADR-0067). This props type resolves to something else, such as a primitive, a union
of object types, an array or a function, whose members the targets cannot declare as props.

Give the component one object type of props. Write alternatives as optional members, or as a
member whose literal union says which applies.

### [UF6005]{#UF6005} conflicting-members

**Error.** Two declarations give a prop different types.

A props type built from several declarations, by an intersection or an `extends` chain,
declares one member twice, with types that differ, or optional in one and required in the
other. The targets declare each prop once, with one type, so they cannot follow it (ADR-0067).
The diagnostic points at the props annotation, and the message names the member and both
declarations.

Declare the member once, or give both declarations the same type and optionality.

### [UF6006]{#UF6006} generic-instantiation

**Error.** A generic component takes its type arguments from its props.

A generic component, `function List<T>(props: ListProps<T>)`, infers its type arguments from
the props its consumer passes, on every target (ADR-0068). Explicit type arguments on its tag
(`<List<string> items={names} />`) have no form in several frameworks' templates, and a generic
component cannot be a candidate of `<component is>`, whose props no one type argument types.

Remove the type arguments, and pass props whose types give `T`. Render a generic component by
its own tag rather than through `<component is>`.

### [UF6007]{#UF6007} directive-value-type

**Error.** A directive's value has another type than the directive takes.

A directive declared with `defineDirective<T>` takes a value of type `T`, and this value's type
is not assignable to it: `v-focus-trap={1}` where `vFocusTrap` takes `boolean`. TypeScript does
not type a dashed JSX attribute, so the editor accepts it, and some outputs would pass the wrong
value to the directive's hooks.

Only the tsgo type oracle checks it (ADR-0109): `typeOracle: "tsgo"` in the configuration, or
`--type-oracle tsgo`. The default oracle reads types as written and checks no value. The value
is typed where it is written, narrowed by its branch, and with the directive's type as its
context, as an assignment types it, so a template literal or a generic call is typed as the
directive needs.

Pass a value of the type the directive takes, or change the type argument of its
`defineDirective`.

## Config and tooling

### [UF7001]{#UF7001} config-not-loaded

**Error.** The configuration file could not be loaded.

Unframework could not import the configuration file (`unframework.config.ts`, `.mts`, `.js`
or `.mjs`), or the file has no default export. The message names the file and says which.

Fix the file so Node can import it. Node loads a TypeScript configuration by stripping its
types, so the file cannot use syntax that needs compiling, such as an enum or a parameter
property: rewrite the file without that syntax. Then export the configuration as the file's
default: `export default defineConfig({ … })`.

### [UF7002]{#UF7002} config-invalid

**Error.** The configuration has the wrong shape.

A field in the configuration has the wrong type or form, or it isn't a field the configuration
has. A `package.targets` entry that `targets` leaves out counts too. The message points at it
by JSON Pointer.

Fix the field, or remove it. Write the configuration with `defineConfig` from
`@uxfront/unframework/config`: its types let an editor flag a wrong field as you write it.

### [UF7003]{#UF7003} unknown-target

**Error.** The configuration names an unknown target.

The configuration names a target that is not built in. Where a built-in name is close, the
message suggests it.

Use one of the built-in names: `react`, `vue`, `svelte`, `solid`, `angular`, `qwik` or
`astro`.

### [UF7004]{#UF7004} target-options-invalid

**Error.** A target's options are not valid.

An entry in `targetOptions` holds options its target can't take: the target's schema rejects
them, the schema throws on them, or the target has no schema, which means it declares no
options and nothing would read them. The message gives the path of the option.

Fix the option, or remove it. A target that declares no options takes none, so remove them
all, or leave its entry out.

### [UF7005]{#UF7005} target-not-detected

**Error.** The bundler plugin could not detect a target.

The bundler plugin has no `target` option, and none of the plugins in the Vite configuration
belongs to a framework it knows.

Add the framework's Vite plugin to the configuration, or pass `target` to the Unframework
plugin.

### [UF7006]{#UF7006} target-ambiguous

**Error.** The bundler plugin detected more than one target.

The bundler plugin has no `target` option, and the Vite configuration holds the plugins of
two or more frameworks, so it cannot choose a target.

Pass `target` to the Unframework plugin.

### [UF7007]{#UF7007} no-sources

**Error.** No source files were found.

The command found no `.uf.tsx` or `.uf.ts` file under `srcDir`, which is `src` by default.

Add a component there, or set `srcDir` in `unframework.config.ts` to the directory that holds
your components.

### [UF7008]{#UF7008} packager-missing

**Error.** A target's packager is not installed.

`unframework build --package` runs each target's packager, and it could not resolve this
one. React and Solid use `tsdown`, Vue uses `vite`, `@vitejs/plugin-vue` and `vue-tsc`,
Svelte uses `@sveltejs/package`, Angular uses `ng-packagr`, and Qwik uses `vite` and
`@qwik.dev/core`, whose `qwikVite()` runs the build. Svelte and Qwik also need `typescript`,
for their declarations. Unframework does not install them: it resolves them from
`package.resolveFrom`, which is the project root by default.

Install the packager in the project, point `package.resolveFrom` at a directory that has it,
or leave the target out of `package.targets`.

### [UF7009]{#UF7009} packager-failed

**Error.** A target's packager failed.

`unframework build --package` ran a target's packager, and the packager failed.

Fix the problem the packager reports, or leave the target out of `package.targets` while you
do.

### [UF7010]{#UF7010} host-option-incompatible

**Warning.** A host framework option changes how whitespace renders.

Outputs assume the host framework's default whitespace handling, and two options that change
it cannot be set per file: Vue's `template.compilerOptions.whitespace` and Astro's
`compressHTML`. With Vue's `"preserve"`, or an Astro `compressHTML` other than `"jsx"`, a
component can render different whitespace from the other targets.

Remove the option, or set Vue's to `"condense"` and Astro's to `"jsx"`.

### [UF7011]{#UF7011} example-with-props

**Error.** An example declares props.

`unframework visual` renders each `*.example.uf.tsx` file on every target with no props, so
every target renders the same thing (ADR-0087). This example's component declares props,
which no target is given.

Remove the props, and write the values the example shows into it, as the props of the
components it renders. To show several states, render each one, or write an example for each.

### [UF7012]{#UF7012} malformed-example-metadata

**Warning.** An example's metadata tag is malformed.

`unframework preview` reads the doc comment on an example's default export for its
category, title and order (ADR-0110), and its layout in the frame (ADR-0114). One of these
tags is malformed: `@category` or `@title` is empty, `@category` has an empty group, `@order`
isn't a finite number, `@layout` is empty, has a word it doesn't know, sets one thing twice or
gives `none` with other words, or a tag is given twice. The preview uses the value it derives
instead: the category from the example's directory, the title from its file name, no order,
and the centred layout.

Write a value after the tag, such as `@category Components/Actions/Button`, `@title Colors`,
`@order 2` or `@layout column align-start gap-8px`, give each tag once, or remove the tag.
`unframework visual` doesn't read the comment, so its run is the same either way.

## Plugins

### [UF8001]{#UF8001} plugin-failed

**Error.** A compiler plugin failed.

A compiler plugin's `ir` or `output` hook threw, or returned something other than valid IR
or a list of files. Valid IR has the schema's shape and keeps the invariants every target
relies on (`checkInvariants`): component and export names every target can write, HTML
every target renders alike, and no code or document the compiler cannot analyse. The
message points at the first problems by JSON Pointer.

The compiler reports it instead of crashing, and leaves the plugin's step out: hooks
receive a frozen module and frozen files, so a hook changes them by returning new ones,
and a failed hook leaves nothing behind.

Fix the plugin, or remove it from the configuration.

## Internal

### [UF9001]{#UF9001} internal-error

**Error.** The compiler failed unexpectedly.

This is a bug in Unframework. Please open an issue with the file that triggered it:
https://github.com/uxfront-com/unframework/issues/new/choose

### [UF9002]{#UF9002} sourcemap-not-remapped

**Error.** A source map could not follow formatting.

The compiler maps each output before it formats it, then carries the map across by matching
the non-whitespace characters on both sides. It counts only the characters of words, since
the formatter removes punctuation and rewrites numbers. Fewer than 95% of those matched, or a
markup file's code blocks or the markup around them changed in a way it can't follow, so it
reports this instead of a wrong map.

The message says which. A file whose diff outgrows the compiler's bound is UF9003 instead.

This is a bug in Unframework. Please open an issue with the file that triggered it:
https://github.com/uxfront-com/unframework/issues/new/choose

### [UF9003]{#UF9003} sourcemap-skipped

**Warning.** A file ships without a source map.

The compiler carries each output's map through formatting with a diff, and that diff may hold
256 MB. Formatting changed this file too much to fit, so the compiler stopped and left the map
out.

The file still works, only without a map: a stack frame in it shows the output's line, not the
source's. To map it, write the code as the formatter prints it, like `1.5` for `1.50`, so that
formatting changes less. Or move a large table to a shared `.ts` module, which the compiler
copies unchanged.
