Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify default prop values, attribute behavior and text expressions #15257

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 42 additions & 2 deletions documentation/docs/01-introduction/xx-props.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,11 +43,51 @@ You can specify a fallback value for a prop. It will be used if the component's

<Nested answer={42} /> <!-- answer is set to 42 -->
<Nested answer={null} /> <!-- answer is set to null (default value is not used)-->
<Nested /> <!-- answer is set to default value -->
<Nested answer={undefined}/> <!-- answer is set to default value -->
<Nested /> <!-- answer is set 3 (default value) -->
<Nested answer={undefined}/> <!-- answer is set 3 (default value) -->

```

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sorry, I didn't make myself clear. I meant deep destructuring assignment, but it turns out that it is forbidden.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should i remove the example?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I think it's unnecessary here.


```svelte
<script>
let count = 3;
</script>

<!-- App.svelte -->
<First {count} />
```

```svelte
<script>
export let count;
</script>

<!-- First.svelte -->
<p>First: {count}</p>
<Second {count} />
```

```svelte
<script>
export let count;
</script>

<!-- Second.svelte -->
<p>Second: {count}</p>
<Third {count} />
```

```svelte
<script>
export let count;
</script>

<!-- Third.svelte -->
<p>Third: {count}</p>
```

To get all properties, use rest syntax:

```svelte
Expand Down
14 changes: 10 additions & 4 deletions documentation/docs/03-template-syntax/01-basic-markup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
<script>
let emptyStr = "";
let num = 1;
let bool = false;
let obj = { key: "value" };
let objToStr = obj.toString();
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant this:

<script lang="ts">
    let obj1 = { toString: () => "str" };
</script>

<p>{obj1}</p> <!-- Renders as: <p>str</p> -->

And add a link to MDN.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, ok. My bad. So you want me to override the toString function right?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add this instead of objToStr.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should i add the MDN link to documents? Or you just share with me for the reference?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now let's wait for what the team says.

let empty = undefined;
</script>
let nul = null;


<p>{emptyStr}</p> <!-- Renders as: <p></p> -->
<p>{num}</p> <!-- Renders as: <p>1</p> -->
<p>{bool}</p> <!-- Renders as: <p>false</p> -->
<p>{obj}</p> <!-- Renders as: <p>[object Object]</p> -->
<p>{objToStr}</p> <!-- Renders as: <p>[object Object]</p> -->
<p>{empty}</p> <!-- Renders as: <p></p> (empty string) -->
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add an example with an empty string, null, and an object with the toString method.
Perhaps it's better to shorten the example by removing the script tag.

<p>{nul}</p> <!-- Renders as: <p></p> -->
```

Curly braces can be included in a Svelte template by using their [HTML entity](https://developer.mozilla.org/docs/Glossary/Entity) strings: `&lbrace;`, `&lcub;`, or `&#123;` for `{` and `&rbrace;`, `&rcub;`, or `&#125;` for `}`.
Expand Down