From 4578d4f25ac1de2acbceab162c8212745a74cf60 Mon Sep 17 00:00:00 2001 From: Simon H <5968653+dummdidumm@users.noreply.github.com> Date: Fri, 11 Oct 2024 02:05:38 +0200 Subject: [PATCH] docs: generate pages for compiler/runtime warnings/errors (#13557) * docs: generate pages for compiler/runtime warnings/errors Ideally each warning has accompanying details so that it doesn't look so empty on the final site, but that can happen separately * fix * sort alphabetically, code ticks for headings * only uppercase first word * regenerate * generate codes using [!NOTE], remove any backticks and escape `<` characters * some prose preceeding the list of compiler warnings * bring over prose from Svelte 4 a11y warnings * fix * lint * remove backticks from headers, now that they are getting rendered * Revert "remove backticks from headers, now that they are getting rendered" This reverts commit c2952818488267e900f060d2eab58b354f97524b. * back to normal headers/code blocks * fix * separate authored from generated stuff * newlines --------- Co-authored-by: Rich Harris --- .../98-reference/.generated/client-errors.md | 129 +++ .../.generated/client-warnings.md | 98 ++ .../98-reference/.generated/compile-errors.md | 945 ++++++++++++++++++ .../.generated/compile-warnings.md | 817 +++++++++++++++ .../98-reference/.generated/server-errors.md | 5 + .../98-reference/.generated/shared-errors.md | 23 + .../.generated/shared-warnings.md | 17 + .../docs/98-reference/30-compiler-errors.md | 5 + .../docs/98-reference/30-compiler-warnings.md | 21 + .../docs/98-reference/30-runtime-errors.md | 15 + .../docs/98-reference/30-runtime-warnings.md | 11 + .../svelte/messages/compile-warnings/a11y.md | 296 ++++++ .../svelte/scripts/process-messages/index.js | 27 +- 13 files changed, 2406 insertions(+), 3 deletions(-) create mode 100644 documentation/docs/98-reference/.generated/client-errors.md create mode 100644 documentation/docs/98-reference/.generated/client-warnings.md create mode 100644 documentation/docs/98-reference/.generated/compile-errors.md create mode 100644 documentation/docs/98-reference/.generated/compile-warnings.md create mode 100644 documentation/docs/98-reference/.generated/server-errors.md create mode 100644 documentation/docs/98-reference/.generated/shared-errors.md create mode 100644 documentation/docs/98-reference/.generated/shared-warnings.md create mode 100644 documentation/docs/98-reference/30-compiler-errors.md create mode 100644 documentation/docs/98-reference/30-compiler-warnings.md create mode 100644 documentation/docs/98-reference/30-runtime-errors.md create mode 100644 documentation/docs/98-reference/30-runtime-warnings.md diff --git a/documentation/docs/98-reference/.generated/client-errors.md b/documentation/docs/98-reference/.generated/client-errors.md new file mode 100644 index 0000000000..52580f0300 --- /dev/null +++ b/documentation/docs/98-reference/.generated/client-errors.md @@ -0,0 +1,129 @@ +### bind_invalid_checkbox_value + +``` +Using `bind:value` together with a checkbox input is not allowed. Use `bind:checked` instead +``` + +### bind_invalid_export + +``` +Component %component% has an export named `%key%` that a consumer component is trying to access using `bind:%key%`, which is disallowed. Instead, use `bind:this` (e.g. `<%name% bind:this={component} />`) and then access the property on the bound component instance (e.g. `component.%key%`) +``` + +### bind_not_bindable + +``` +A component is attempting to bind to a non-bindable property `%key%` belonging to %component% (i.e. `<%name% bind:%key%={...}>`). To mark a property as bindable: `let { %key% = $bindable() } = $props()` +``` + +### component_api_changed + +``` +%parent% called `%method%` on an instance of %component%, which is no longer valid in Svelte 5. See https://svelte-5-preview.vercel.app/docs/breaking-changes#components-are-no-longer-classes for more information +``` + +### component_api_invalid_new + +``` +Attempted to instantiate %component% with `new %name%`, which is no longer valid in Svelte 5. If this component is not under your control, set the `compatibility.componentApi` compiler option to `4` to keep it working. See https://svelte-5-preview.vercel.app/docs/breaking-changes#components-are-no-longer-classes for more information +``` + +### derived_references_self + +``` +A derived value cannot reference itself recursively +``` + +### each_key_duplicate + +``` +Keyed each block has duplicate key at indexes %a% and %b% +``` + +``` +Keyed each block has duplicate key `%value%` at indexes %a% and %b% +``` + +### effect_in_teardown + +``` +`%rune%` cannot be used inside an effect cleanup function +``` + +### effect_in_unowned_derived + +``` +Effect cannot be created inside a `$derived` value that was not itself created inside an effect +``` + +### effect_orphan + +``` +`%rune%` can only be used inside an effect (e.g. during component initialisation) +``` + +### effect_update_depth_exceeded + +``` +Maximum update depth exceeded. This can happen when a reactive block or effect repeatedly sets a new value. Svelte limits the number of nested updates to prevent infinite loops +``` + +### hydration_failed + +``` +Failed to hydrate the application +``` + +### invalid_snippet + +``` +Could not `{@render}` snippet due to the expression being `null` or `undefined`. Consider using optional chaining `{@render snippet?.()}` +``` + +### lifecycle_legacy_only + +``` +`%name%(...)` cannot be used in runes mode +``` + +### props_invalid_value + +``` +Cannot do `bind:%key%={undefined}` when `%key%` has a fallback value +``` + +### props_rest_readonly + +``` +Rest element properties of `$props()` such as `%property%` are readonly +``` + +### rune_outside_svelte + +``` +The `%rune%` rune is only available inside `.svelte` and `.svelte.js/ts` files +``` + +### state_descriptors_fixed + +``` +Property descriptors defined on `$state` objects must contain `value` and always be `enumerable`, `configurable` and `writable`. +``` + +### state_prototype_fixed + +``` +Cannot set prototype of `$state` object +``` + +### state_unsafe_local_read + +``` +Reading state that was created inside the same derived is forbidden. Consider using `untrack` to read locally created state +``` + +### state_unsafe_mutation + +``` +Updating state inside a derived is forbidden. If the value should not be reactive, declare it without `$state` +``` diff --git a/documentation/docs/98-reference/.generated/client-warnings.md b/documentation/docs/98-reference/.generated/client-warnings.md new file mode 100644 index 0000000000..7eb94df912 --- /dev/null +++ b/documentation/docs/98-reference/.generated/client-warnings.md @@ -0,0 +1,98 @@ +### binding_property_non_reactive + +``` +`%binding%` is binding to a non-reactive property +``` + +``` +`%binding%` (%location%) is binding to a non-reactive property +``` + +### console_log_state + +``` +Your `console.%method%` contained `$state` proxies. Consider using `$inspect(...)` or `$state.snapshot(...)` instead +``` + +When logging a [proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy), browser devtools will log the proxy itself rather than the value it represents. In the case of Svelte, the 'target' of a `$state` proxy might not resemble its current value, which can be confusing. + +The easiest way to log a value as it changes over time is to use the [`$inspect`](https://svelte-5-preview.vercel.app/docs/runes#$inspect) rune. Alternatively, to log things on a one-off basis (for example, inside an event handler) you can use [`$state.snapshot`](https://svelte-5-preview.vercel.app/docs/runes#$state-snapshot) to take a snapshot of the current value. + +### event_handler_invalid + +``` +%handler% should be a function. Did you mean to %suggestion%? +``` + +### hydration_attribute_changed + +``` +The `%attribute%` attribute on `%html%` changed its value between server and client renders. The client value, `%value%`, will be ignored in favour of the server value +``` + +### hydration_html_changed + +``` +The value of an `{@html ...}` block changed between server and client renders. The client value will be ignored in favour of the server value +``` + +``` +The value of an `{@html ...}` block %location% changed between server and client renders. The client value will be ignored in favour of the server value +``` + +### hydration_mismatch + +``` +Hydration failed because the initial UI does not match what was rendered on the server +``` + +``` +Hydration failed because the initial UI does not match what was rendered on the server. The error occurred near %location% +``` + +### invalid_raw_snippet_render + +``` +The `render` function passed to `createRawSnippet` should return HTML for a single element +``` + +### lifecycle_double_unmount + +``` +Tried to unmount a component that was not mounted +``` + +### ownership_invalid_binding + +``` +%parent% passed a value to %child% with `bind:`, but the value is owned by %owner%. Consider creating a binding between %owner% and %parent% +``` + +### ownership_invalid_mutation + +``` +Mutating a value outside the component that created it is strongly discouraged. Consider passing values to child components with `bind:`, or use a callback instead +``` + +``` +%component% mutated a value owned by %owner%. This is strongly discouraged. Consider passing values to child components with `bind:`, or use a callback instead +``` + +### state_proxy_equality_mismatch + +``` +Reactive `$state(...)` proxies and the values they proxy have different identities. Because of this, comparisons with `%operator%` will produce unexpected results +``` + +`$state(...)` creates a [proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) of the value it is passed. The proxy and the value have different identities, meaning equality checks will always return `false`: + +```svelte + +``` + +To resolve this, ensure you're comparing values where both values were created with `$state(...)`, or neither were. Note that `$state.raw(...)` will _not_ create a state proxy. diff --git a/documentation/docs/98-reference/.generated/compile-errors.md b/documentation/docs/98-reference/.generated/compile-errors.md new file mode 100644 index 0000000000..1b8511a6f6 --- /dev/null +++ b/documentation/docs/98-reference/.generated/compile-errors.md @@ -0,0 +1,945 @@ +### animation_duplicate + +``` +An element can only have one 'animate' directive +``` + +### animation_invalid_placement + +``` +An element that uses the `animate:` directive must be the only child of a keyed `{#each ...}` block +``` + +### animation_missing_key + +``` +An element that uses the `animate:` directive must be the only child of a keyed `{#each ...}` block. Did you forget to add a key to your each block? +``` + +### attribute_contenteditable_dynamic + +``` +'contenteditable' attribute cannot be dynamic if element uses two-way binding +``` + +### attribute_contenteditable_missing + +``` +'contenteditable' attribute is required for textContent, innerHTML and innerText two-way bindings +``` + +### attribute_duplicate + +``` +Attributes need to be unique +``` + +### attribute_empty_shorthand + +``` +Attribute shorthand cannot be empty +``` + +### attribute_invalid_event_handler + +``` +Event attribute must be a JavaScript expression, not a string +``` + +### attribute_invalid_multiple + +``` +'multiple' attribute must be static if select uses two-way binding +``` + +### attribute_invalid_name + +``` +'%name%' is not a valid attribute name +``` + +### attribute_invalid_sequence_expression + +``` +Sequence expressions are not allowed as attribute/directive values in runes mode, unless wrapped in parentheses +``` + +### attribute_invalid_type + +``` +'type' attribute must be a static text value if input uses two-way binding +``` + +### attribute_unquoted_sequence + +``` +Attribute values containing `{...}` must be enclosed in quote marks, unless the value only contains the expression +``` + +### bind_invalid_expression + +``` +Can only bind to an Identifier or MemberExpression +``` + +### bind_invalid_name + +``` +`bind:%name%` is not a valid binding +``` + +``` +`bind:%name%` is not a valid binding. %explanation% +``` + +### bind_invalid_target + +``` +`bind:%name%` can only be used with %elements% +``` + +### bind_invalid_value + +``` +Can only bind to state or props +``` + +### bindable_invalid_location + +``` +`$bindable()` can only be used inside a `$props()` declaration +``` + +### block_duplicate_clause + +``` +%name% cannot appear more than once within a block +``` + +### block_invalid_continuation_placement + +``` +{:...} block is invalid at this position (did you forget to close the preceeding element or block?) +``` + +### block_invalid_elseif + +``` +'elseif' should be 'else if' +``` + +### block_invalid_placement + +``` +{#%name% ...} block cannot be %location% +``` + +### block_unclosed + +``` +Block was left open +``` + +### block_unexpected_character + +``` +Expected a `%character%` character immediately following the opening bracket +``` + +### block_unexpected_close + +``` +Unexpected block closing tag +``` + +### component_invalid_directive + +``` +This type of directive is not valid on components +``` + +### const_tag_cycle + +``` +Cyclical dependency detected: %cycle% +``` + +### const_tag_invalid_expression + +``` +{@const ...} must consist of a single variable declaration +``` + +### const_tag_invalid_placement + +``` +`{@const}` must be the immediate child of `{#snippet}`, `{#if}`, `{:else if}`, `{:else}`, `{#each}`, `{:then}`, `{:catch}`, `` or `` +``` + +### constant_assignment + +``` +Cannot assign to %thing% +``` + +### constant_binding + +``` +Cannot bind to %thing% +``` + +### css_empty_declaration + +``` +Declaration cannot be empty +``` + +### css_expected_identifier + +``` +Expected a valid CSS identifier +``` + +### css_global_block_invalid_combinator + +``` +A `:global` selector cannot follow a `%name%` combinator +``` + +### css_global_block_invalid_declaration + +``` +A top-level `:global {...}` block can only contain rules, not declarations +``` + +### css_global_block_invalid_list + +``` +A `:global` selector cannot be part of a selector list with more than one item +``` + +### css_global_block_invalid_modifier + +``` +A `:global` selector cannot modify an existing selector +``` + +### css_global_block_invalid_modifier_start + +``` +A `:global` selector can only be modified if it is a descendant of other selectors +``` + +### css_global_invalid_placement + +``` +`:global(...)` can be at the start or end of a selector sequence, but not in the middle +``` + +### css_global_invalid_selector + +``` +`:global(...)` must contain exactly one selector +``` + +### css_global_invalid_selector_list + +``` +`:global(...)` must not contain type or universal selectors when used in a compound selector +``` + +### css_nesting_selector_invalid_placement + +``` +Nesting selectors can only be used inside a rule or as the first selector inside a lone `:global(...)` +``` + +### css_selector_invalid + +``` +Invalid selector +``` + +### css_type_selector_invalid_placement + +``` +`:global(...)` must not be followed by a type selector +``` + +### debug_tag_invalid_arguments + +``` +{@debug ...} arguments must be identifiers, not arbitrary expressions +``` + +### declaration_duplicate + +``` +`%name%` has already been declared +``` + +### declaration_duplicate_module_import + +``` +Cannot declare a variable with the same name as an import inside ` +- ++ +``` + +### svelte_element_invalid_this + +``` +`this` should be an `{expression}`. Using a string attribute value will cause an error in future versions of Svelte +``` + +### svelte_self_deprecated + +``` +`` is deprecated — use self-imports (e.g. `import %name% from './%basename%'`) instead +``` + +### unknown_code + +``` +`%code%` is not a recognised code +``` + +``` +`%code%` is not a recognised code (did you mean `%suggestion%`?) +``` diff --git a/documentation/docs/98-reference/.generated/server-errors.md b/documentation/docs/98-reference/.generated/server-errors.md new file mode 100644 index 0000000000..f325b5349a --- /dev/null +++ b/documentation/docs/98-reference/.generated/server-errors.md @@ -0,0 +1,5 @@ +### lifecycle_function_unavailable + +``` +`%name%(...)` is not available on the server +``` diff --git a/documentation/docs/98-reference/.generated/shared-errors.md b/documentation/docs/98-reference/.generated/shared-errors.md new file mode 100644 index 0000000000..1a2bcf8d2d --- /dev/null +++ b/documentation/docs/98-reference/.generated/shared-errors.md @@ -0,0 +1,23 @@ +### invalid_default_snippet + +``` +Cannot use `{@render children(...)}` if the parent component uses `let:` directives. Consider using a named snippet instead +``` + +### lifecycle_outside_component + +``` +`%name%(...)` can only be used during component initialisation +``` + +### store_invalid_shape + +``` +`%name%` is not a store with a `subscribe` method +``` + +### svelte_element_invalid_this_value + +``` +The `this` prop on `` must be a string, if defined +``` diff --git a/documentation/docs/98-reference/.generated/shared-warnings.md b/documentation/docs/98-reference/.generated/shared-warnings.md new file mode 100644 index 0000000000..4ff3f89e6d --- /dev/null +++ b/documentation/docs/98-reference/.generated/shared-warnings.md @@ -0,0 +1,17 @@ +### dynamic_void_element_content + +``` +`` is a void element — it cannot have content +``` + +### state_snapshot_uncloneable + +``` +Value cannot be cloned with `$state.snapshot` — the original value was returned +``` + +``` +The following properties cannot be cloned with `$state.snapshot` — the return value contains the originals: + +%properties% +``` diff --git a/documentation/docs/98-reference/30-compiler-errors.md b/documentation/docs/98-reference/30-compiler-errors.md new file mode 100644 index 0000000000..ae22029155 --- /dev/null +++ b/documentation/docs/98-reference/30-compiler-errors.md @@ -0,0 +1,5 @@ +--- +title: 'Compiler errors' +--- + +@include .generated/compile-errors.md diff --git a/documentation/docs/98-reference/30-compiler-warnings.md b/documentation/docs/98-reference/30-compiler-warnings.md new file mode 100644 index 0000000000..43ba71250f --- /dev/null +++ b/documentation/docs/98-reference/30-compiler-warnings.md @@ -0,0 +1,21 @@ +--- +title: 'Compiler warnings' +--- + +Svelte warns you at compile time if it catches potential mistakes, such as writing inaccessible markup. + +Some warnings may be incorrect in your concrete use case. You can disable such false positives by placing a `` comment above the line that causes the warning. Example: + +```svelte + + +``` + +You can list multiple rules in a single comment (separated by commas), and add an explanatory note (in parentheses) alongside them: + +```svelte + +
...
+``` + +@include .generated/compile-warnings.md diff --git a/documentation/docs/98-reference/30-runtime-errors.md b/documentation/docs/98-reference/30-runtime-errors.md new file mode 100644 index 0000000000..43ce989587 --- /dev/null +++ b/documentation/docs/98-reference/30-runtime-errors.md @@ -0,0 +1,15 @@ +--- +title: 'Runtime errors' +--- + +## Client errors + +@include .generated/client-errors.md + +## Server errors + +@include .generated/server-errors.md + +## Shared errors + +@include .generated/shared-errors.md diff --git a/documentation/docs/98-reference/30-runtime-warnings.md b/documentation/docs/98-reference/30-runtime-warnings.md new file mode 100644 index 0000000000..3e040eb06f --- /dev/null +++ b/documentation/docs/98-reference/30-runtime-warnings.md @@ -0,0 +1,11 @@ +--- +title: 'Runtime warnings' +--- + +## Client errors + +@include .generated/client-errors.md + +## Shared errors + +@include .generated/shared-errors.md diff --git a/packages/svelte/messages/compile-warnings/a11y.md b/packages/svelte/messages/compile-warnings/a11y.md index a1f8a6da5d..938c0a103d 100644 --- a/packages/svelte/messages/compile-warnings/a11y.md +++ b/packages/svelte/messages/compile-warnings/a11y.md @@ -2,14 +2,36 @@ > Avoid using accesskey +Enforce no `accesskey` on element. Access keys are HTML attributes that allow web developers to assign keyboard shortcuts to elements. Inconsistencies between keyboard shortcuts and keyboard commands used by screen reader and keyboard-only users create accessibility complications. To avoid complications, access keys should not be used. + + +```svelte + +
+``` + ## a11y_aria_activedescendant_has_tabindex > An element with an aria-activedescendant attribute should have a tabindex value +An element with `aria-activedescendant` must be tabbable, so it must either have an inherent `tabindex` or declare `tabindex` as an attribute. + +```svelte + +
+``` + ## a11y_aria_attributes > `<%name%>` should not have aria-* attributes +Certain reserved DOM elements do not support ARIA roles, states and properties. This is often because they are not visible, for example `meta`, `html`, `script`, `style`. This rule enforces that these DOM elements do not contain the `aria-*` props. + +```svelte + + +``` + ## a11y_autocomplete_valid > '%value%' is an invalid value for 'autocomplete' on `` @@ -18,10 +40,30 @@ > Avoid using autofocus +Enforce that `autofocus` is not used on elements. Autofocusing elements can cause usability issues for sighted and non-sighted users alike. + +```svelte + + +``` + ## a11y_click_events_have_key_events > Visible, non-interactive elements with a click event must be accompanied by a keyboard event handler. Consider whether an interactive element such as `