From d3d95fbf988ac6f376682f99a3e2c9054a08cb89 Mon Sep 17 00:00:00 2001 From: melihguleyupoglu Date: Mon, 10 Feb 2025 19:04:21 +0300 Subject: [PATCH 1/5] docs: clarify default prop values, attribute behavior and text expressions --- .../docs/01-introduction/xx-props.md | 22 ++++++++++ .../03-template-syntax/01-basic-markup.md | 43 +++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/documentation/docs/01-introduction/xx-props.md b/documentation/docs/01-introduction/xx-props.md index cad854d8785d..3deb03d693c1 100644 --- a/documentation/docs/01-introduction/xx-props.md +++ b/documentation/docs/01-introduction/xx-props.md @@ -26,6 +26,28 @@ You can specify a fallback value for a prop. It will be used if the component's ``` +> [!NOTE] If a prop is explicitly passed as null, the default value will not be used, and null will be assigned instead. However, if the prop is undefined or not provided at all, the default value will be used. + +```svelte + + +

The answer is {answer}

+``` + +```svelte + + + + + + + +``` + To get all properties, use rest syntax: ```svelte diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md index b41dc187c337..12776a6f01fc 100644 --- a/documentation/docs/03-template-syntax/01-basic-markup.md +++ b/documentation/docs/03-template-syntax/01-basic-markup.md @@ -72,6 +72,29 @@ When the attribute name and value match (`name={name}`), they can be replaced wi --> ``` +When passing null or undefined to an attribute, the attribute is omitted from the rendered HTML. + +```svelte + + +
Attributes are not included.
+ +``` + +If an empty string ("") is assigned to an attribute, the attribute remains in the HTML but with an empty value. + +```svelte + + +
Hello
+ +``` + ## Component props By convention, values passed to components are referred to as _properties_ or _props_ rather than _attributes_, which are a feature of the DOM. @@ -154,6 +177,26 @@ A JavaScript expression can be included as text by surrounding it with curly bra {expression} ``` +When using {expression} inside markup, Svelte automatically converts the value to a string before rendering it. The conversion follows JavaScript's standard behavior: + +- Primitive values (number, boolean, string) are directly converted to strings. +- Objects call their .toString() method (if not overridden, it defaults to [object Object]). +- undefined and null are treated as empty strings (""). + +```svelte + + +

{num}

+

{bool}

+

{obj}

+

{empty}

+``` + Curly braces can be included in a Svelte template by using their [HTML entity](https://developer.mozilla.org/docs/Glossary/Entity) strings: `{`, `{`, or `{` for `{` and `}`, `}`, or `}` for `}`. If you're using a regular expression (`RegExp`) [literal notation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp#literal_notation_and_constructor), you'll need to wrap it in parentheses. From 3fac864c8ac03e68a150871ddae7018fb8c042f5 Mon Sep 17 00:00:00 2001 From: melihguleyupoglu Date: Mon, 10 Feb 2025 22:54:02 +0300 Subject: [PATCH 2/5] docs: add deep nesting example and explanation about reactivity of expressions --- .../docs/01-introduction/xx-props.md | 44 ++++++++++++++++++- .../03-template-syntax/01-basic-markup.md | 14 ++++-- 2 files changed, 52 insertions(+), 6 deletions(-) diff --git a/documentation/docs/01-introduction/xx-props.md b/documentation/docs/01-introduction/xx-props.md index 3deb03d693c1..54b5ba6a1c49 100644 --- a/documentation/docs/01-introduction/xx-props.md +++ b/documentation/docs/01-introduction/xx-props.md @@ -43,11 +43,51 @@ You can specify a fallback value for a prop. It will be used if the component's - - + + ``` +Deep nesting refers to having components nested within other components across multiple levels. In this setup, props can be passed from parent to child components through several layers. + +```svelte + + + + +``` + +```svelte + + + +

First: {count}

+ +``` + +```svelte + + + +

Second: {count}

+ +``` + +```svelte + + + +

Third: {count}

+``` + To get all properties, use rest syntax: ```svelte diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md index 12776a6f01fc..d4ba6691dd13 100644 --- a/documentation/docs/03-template-syntax/01-basic-markup.md +++ b/documentation/docs/03-template-syntax/01-basic-markup.md @@ -177,24 +177,30 @@ A JavaScript expression can be included as text by surrounding it with curly bra {expression} ``` -When using {expression} inside markup, Svelte automatically converts the value to a string before rendering it. The conversion follows JavaScript's standard behavior: +When using {expression} inside markup, Svelte automatically converts the value to a string before rendering it and makes the expression reactive (similar to wrapping it in $derived). The conversion follows JavaScript's standard behavior: - Primitive values (number, boolean, string) are directly converted to strings. - Objects call their .toString() method (if not overridden, it defaults to [object Object]). -- undefined and null are treated as empty strings (""). +- Undefined and null are treated as empty strings (""). +- Expressions using runes ($state, $derived, etc.) maintain their specific reactive behavior. ```svelte - + let nul = null; + +

{emptyStr}

{num}

{bool}

{obj}

+

{objToStr}

{empty}

+

{nul}

``` Curly braces can be included in a Svelte template by using their [HTML entity](https://developer.mozilla.org/docs/Glossary/Entity) strings: `{`, `{`, or `{` for `{` and `}`, `}`, or `}` for `}`. From e5e675d404fe17a0e6d8f3abda323f0f82edc741 Mon Sep 17 00:00:00 2001 From: melihguleyupoglu Date: Mon, 10 Feb 2025 23:19:57 +0300 Subject: [PATCH 3/5] docs: remove deep nesting example and add override example to expressions --- .../docs/01-introduction/xx-props.md | 44 +------------------ .../03-template-syntax/01-basic-markup.md | 9 ++-- 2 files changed, 6 insertions(+), 47 deletions(-) diff --git a/documentation/docs/01-introduction/xx-props.md b/documentation/docs/01-introduction/xx-props.md index 54b5ba6a1c49..5266c635e8b1 100644 --- a/documentation/docs/01-introduction/xx-props.md +++ b/documentation/docs/01-introduction/xx-props.md @@ -43,51 +43,11 @@ You can specify a fallback value for a prop. It will be used if the component's - - + + ``` -Deep nesting refers to having components nested within other components across multiple levels. In this setup, props can be passed from parent to child components through several layers. - -```svelte - - - - -``` - -```svelte - - - -

First: {count}

- -``` - -```svelte - - - -

Second: {count}

- -``` - -```svelte - - - -

Third: {count}

-``` - To get all properties, use rest syntax: ```svelte diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md index d4ba6691dd13..86c1f7ba79cb 100644 --- a/documentation/docs/03-template-syntax/01-basic-markup.md +++ b/documentation/docs/03-template-syntax/01-basic-markup.md @@ -188,17 +188,16 @@ When using {expression} inside markup, Svelte automatically converts the value t let emptyStr = ""; let num = 1; let bool = false; - let obj = { key: "value" }; - let objToStr = obj.toString(); + let obj1 = { key: "value" }; + let obj2 = { toString: () => "str" }; let empty = undefined; let nul = null; -

{emptyStr}

{num}

{bool}

-

{obj}

-

{objToStr}

+

{obj1}

+

{obj2}

{empty}

{nul}

``` From cf30a6ec0589e29ffa765e8eda7f7dbb2031d900 Mon Sep 17 00:00:00 2001 From: melihguleyupoglu Date: Wed, 12 Feb 2025 22:59:42 +0300 Subject: [PATCH 4/5] docs: enhance expression handling docs with examples and relevant MDN links --- .../03-template-syntax/01-basic-markup.md | 32 +++++++++++++------ 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md index 86c1f7ba79cb..2e7ac0dffa5f 100644 --- a/documentation/docs/03-template-syntax/01-basic-markup.md +++ b/documentation/docs/03-template-syntax/01-basic-markup.md @@ -179,9 +179,15 @@ A JavaScript expression can be included as text by surrounding it with curly bra When using {expression} inside markup, Svelte automatically converts the value to a string before rendering it and makes the expression reactive (similar to wrapping it in $derived). The conversion follows JavaScript's standard behavior: -- Primitive values (number, boolean, string) are directly converted to strings. -- Objects call their .toString() method (if not overridden, it defaults to [object Object]). -- Undefined and null are treated as empty strings (""). +- Primitive values (numbers, booleans, strings) are directly converted to strings. +- Objects are converted based on JavaScript’s type coercion rules: + + - If an object defines a [Symbol.toPrimitive](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, it takes precedence and determines how the object is converted. + - Otherwise, if a [toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) method is present, it is called. If not overridden, it defaults to "[object Object]". + - If toString() is not available or does not return a primitive, JavaScript may fall back to [valueOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf), which may be used if it returns a primitive value. + - Additionally, an object with a [Symbol.toStringTag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property affects how it is represented when coerced to a string. + +- undefined and null are treated as empty strings (""). - Expressions using runes ($state, $derived, etc.) maintain their specific reactive behavior. ```svelte @@ -190,16 +196,22 @@ When using {expression} inside markup, Svelte automatically converts the value t let bool = false; let obj1 = { key: "value" }; let obj2 = { toString: () => "str" }; + let obj3 = { [Symbol.toPrimitive]: () => "primitive" }; + let obj4 = { valueOf: () => 42, toString: () => "str" }; + let obj5 = { [Symbol.toStringTag]: "CustomObject" }; let empty = undefined; let nul = null; -

{emptyStr}

-

{num}

-

{bool}

-

{obj1}

-

{obj2}

-

{empty}

-

{nul}

+

{emptyStr}

+

{num}

+

{bool}

+

{obj1}

+

{obj2}

+

{obj3}

+

{obj4}

+

{obj5}

+

{empty}

+

{nul}

``` Curly braces can be included in a Svelte template by using their [HTML entity](https://developer.mozilla.org/docs/Glossary/Entity) strings: `{`, `{`, or `{` for `{` and `}`, `}`, or `}` for `}`. From 96a39e0d7b81b585eecd7cfcf9013ae4d0c64f2d Mon Sep 17 00:00:00 2001 From: melihguleyupoglu Date: Thu, 13 Feb 2025 11:30:37 +0300 Subject: [PATCH 5/5] docs: add parentheses to method references in expressions section --- documentation/docs/03-template-syntax/01-basic-markup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md index 2e7ac0dffa5f..3a9f5c72caa2 100644 --- a/documentation/docs/03-template-syntax/01-basic-markup.md +++ b/documentation/docs/03-template-syntax/01-basic-markup.md @@ -182,10 +182,10 @@ When using {expression} inside markup, Svelte automatically converts the value t - Primitive values (numbers, booleans, strings) are directly converted to strings. - Objects are converted based on JavaScript’s type coercion rules: - - If an object defines a [Symbol.toPrimitive](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, it takes precedence and determines how the object is converted. + - If an object defines a [Symbol.toPrimitive()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toPrimitive) method, it takes precedence and determines how the object is converted. - Otherwise, if a [toString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString) method is present, it is called. If not overridden, it defaults to "[object Object]". - If toString() is not available or does not return a primitive, JavaScript may fall back to [valueOf()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/valueOf), which may be used if it returns a primitive value. - - Additionally, an object with a [Symbol.toStringTag](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property affects how it is represented when coerced to a string. + - Additionally, an object with a [Symbol.toStringTag()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/toStringTag) property affects how it is represented when coerced to a string. - undefined and null are treated as empty strings (""). - Expressions using runes ($state, $derived, etc.) maintain their specific reactive behavior.