From 865d49cc41e2a7329662ceda7204f40132bc303b Mon Sep 17 00:00:00 2001 From: Stanislav Khromov Date: Mon, 29 Sep 2025 00:20:55 +0200 Subject: [PATCH] wip --- documentation/docs/01-introduction/01-overview.md | 1 + documentation/docs/01-introduction/02-getting-started.md | 1 + documentation/docs/01-introduction/03-svelte-files.md | 1 + documentation/docs/01-introduction/04-svelte-js-files.md | 1 + documentation/docs/02-runes/01-what-are-runes.md | 1 + documentation/docs/02-runes/02-$state.md | 1 + documentation/docs/02-runes/03-$derived.md | 1 + documentation/docs/02-runes/04-$effect.md | 1 + documentation/docs/02-runes/05-$props.md | 1 + documentation/docs/02-runes/06-$bindable.md | 1 + documentation/docs/02-runes/07-$inspect.md | 1 + documentation/docs/02-runes/08-$host.md | 1 + documentation/docs/03-template-syntax/01-basic-markup.md | 1 + documentation/docs/03-template-syntax/02-if.md | 1 + documentation/docs/03-template-syntax/03-each.md | 1 + documentation/docs/03-template-syntax/04-key.md | 1 + documentation/docs/03-template-syntax/05-await.md | 1 + documentation/docs/03-template-syntax/06-snippet.md | 1 + documentation/docs/03-template-syntax/07-@render.md | 1 + documentation/docs/03-template-syntax/08-@html.md | 1 + documentation/docs/03-template-syntax/09-@attach.md | 1 + documentation/docs/03-template-syntax/10-@const.md | 1 + documentation/docs/03-template-syntax/11-@debug.md | 1 + documentation/docs/03-template-syntax/12-bind.md | 1 + documentation/docs/03-template-syntax/13-use.md | 1 + documentation/docs/03-template-syntax/14-transition.md | 1 + documentation/docs/03-template-syntax/15-in-and-out.md | 1 + documentation/docs/03-template-syntax/16-animate.md | 1 + documentation/docs/03-template-syntax/17-style.md | 1 + documentation/docs/03-template-syntax/18-class.md | 1 + documentation/docs/03-template-syntax/19-await-expressions.md | 1 + documentation/docs/04-styling/01-scoped-styles.md | 1 + documentation/docs/04-styling/02-global-styles.md | 1 + documentation/docs/04-styling/03-custom-properties.md | 1 + documentation/docs/04-styling/04-nested-style-elements.md | 1 + documentation/docs/05-special-elements/01-svelte-boundary.md | 1 + documentation/docs/05-special-elements/02-svelte-window.md | 1 + documentation/docs/05-special-elements/03-svelte-document.md | 1 + documentation/docs/05-special-elements/04-svelte-body.md | 1 + documentation/docs/05-special-elements/05-svelte-head.md | 1 + documentation/docs/05-special-elements/06-svelte-element.md | 1 + documentation/docs/05-special-elements/07-svelte-options.md | 1 + 42 files changed, 42 insertions(+) diff --git a/documentation/docs/01-introduction/01-overview.md b/documentation/docs/01-introduction/01-overview.md index 5acbe4897b..eb555f5d3a 100644 --- a/documentation/docs/01-introduction/01-overview.md +++ b/documentation/docs/01-introduction/01-overview.md @@ -1,5 +1,6 @@ --- title: Overview +use_cases: "always: understanding Svelte fundamentals, component-based architecture, reactive UI framework basics" --- Svelte is a framework for building user interfaces on the web. It uses a compiler to turn declarative components written in HTML, CSS and JavaScript... diff --git a/documentation/docs/01-introduction/02-getting-started.md b/documentation/docs/01-introduction/02-getting-started.md index e97a46ad34..ec1a7779b4 100644 --- a/documentation/docs/01-introduction/02-getting-started.md +++ b/documentation/docs/01-introduction/02-getting-started.md @@ -1,5 +1,6 @@ --- title: Getting started +use_cases: "always: project setup, creating new Svelte apps, configuring build tools, initial development environment" --- We recommend using [SvelteKit](../kit), which lets you [build almost anything](../kit/project-types). It's the official application framework from the Svelte team and powered by [Vite](https://vite.dev/). Create a new project with: diff --git a/documentation/docs/01-introduction/03-svelte-files.md b/documentation/docs/01-introduction/03-svelte-files.md index cd98652370..600303ced1 100644 --- a/documentation/docs/01-introduction/03-svelte-files.md +++ b/documentation/docs/01-introduction/03-svelte-files.md @@ -1,5 +1,6 @@ --- title: .svelte files +use_cases: "always: component structure, organizing HTML/CSS/JavaScript, single-file components, component templates" --- Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML. diff --git a/documentation/docs/01-introduction/04-svelte-js-files.md b/documentation/docs/01-introduction/04-svelte-js-files.md index 1d3e3dd61a..75bd48ee8f 100644 --- a/documentation/docs/01-introduction/04-svelte-js-files.md +++ b/documentation/docs/01-introduction/04-svelte-js-files.md @@ -1,5 +1,6 @@ --- title: .svelte.js and .svelte.ts files +use_cases: "reusable reactive logic, shared state modules, composable reactive utilities, reactive helper functions" --- Besides `.svelte` files, Svelte also operates on `.svelte.js` and `.svelte.ts` files. diff --git a/documentation/docs/02-runes/01-what-are-runes.md b/documentation/docs/02-runes/01-what-are-runes.md index 59c371eb49..9cf3b4072a 100644 --- a/documentation/docs/02-runes/01-what-are-runes.md +++ b/documentation/docs/02-runes/01-what-are-runes.md @@ -1,5 +1,6 @@ --- title: What are runes? +use_cases: "always: understanding Svelte 5 reactivity, reactive primitives, modern Svelte syntax" --- > [!NOTE] **rune** /ruːn/ _noun_ diff --git a/documentation/docs/02-runes/02-$state.md b/documentation/docs/02-runes/02-$state.md index 741e24fde0..f6006023d2 100644 --- a/documentation/docs/02-runes/02-$state.md +++ b/documentation/docs/02-runes/02-$state.md @@ -1,5 +1,6 @@ --- title: $state +use_cases: "always: reactive variables, component state management, form inputs, counters, toggles, data models" --- The `$state` rune allows you to create _reactive state_, which means that your UI _reacts_ when it changes. diff --git a/documentation/docs/02-runes/03-$derived.md b/documentation/docs/02-runes/03-$derived.md index 0123868c4e..052e958961 100644 --- a/documentation/docs/02-runes/03-$derived.md +++ b/documentation/docs/02-runes/03-$derived.md @@ -1,5 +1,6 @@ --- title: $derived +use_cases: "computed values, calculated properties, derived state, reactive expressions, data transformations" --- Derived state is declared with the `$derived` rune: diff --git a/documentation/docs/02-runes/04-$effect.md b/documentation/docs/02-runes/04-$effect.md index 6c42f55795..2d4972a903 100644 --- a/documentation/docs/02-runes/04-$effect.md +++ b/documentation/docs/02-runes/04-$effect.md @@ -1,5 +1,6 @@ --- title: $effect +use_cases: "side effects, API calls, DOM manipulation, third-party library integration, analytics, canvas drawing, websockets" --- Effects are functions that run when state updates, and can be used for things like calling third-party libraries, drawing on `` elements, or making network requests. They only run in the browser, not during server-side rendering. diff --git a/documentation/docs/02-runes/05-$props.md b/documentation/docs/02-runes/05-$props.md index 222b4831b6..5de41dcfb4 100644 --- a/documentation/docs/02-runes/05-$props.md +++ b/documentation/docs/02-runes/05-$props.md @@ -1,5 +1,6 @@ --- title: $props +use_cases: "always: component inputs, parent-child communication, prop validation, default values, component APIs" --- The inputs to a component are referred to as _props_, which is short for _properties_. You pass props to components just like you pass attributes to elements: diff --git a/documentation/docs/02-runes/06-$bindable.md b/documentation/docs/02-runes/06-$bindable.md index c12c2bf490..61d1789b4e 100644 --- a/documentation/docs/02-runes/06-$bindable.md +++ b/documentation/docs/02-runes/06-$bindable.md @@ -1,5 +1,6 @@ --- title: $bindable +use_cases: "two-way binding, form components, controlled inputs, synchronized state, custom input components" --- Ordinarily, props go one way, from parent to child. This makes it easy to understand how data flows around your app. diff --git a/documentation/docs/02-runes/07-$inspect.md b/documentation/docs/02-runes/07-$inspect.md index 13ac8b79a3..aa6082f7fb 100644 --- a/documentation/docs/02-runes/07-$inspect.md +++ b/documentation/docs/02-runes/07-$inspect.md @@ -1,5 +1,6 @@ --- title: $inspect +use_cases: "development only: debugging reactive state, logging state changes, development tools" --- > [!NOTE] `$inspect` only works during development. In a production build it becomes a noop. diff --git a/documentation/docs/02-runes/08-$host.md b/documentation/docs/02-runes/08-$host.md index ba6f0a5b5b..5b35d271f6 100644 --- a/documentation/docs/02-runes/08-$host.md +++ b/documentation/docs/02-runes/08-$host.md @@ -1,5 +1,6 @@ --- title: $host +use_cases: "web components, custom elements, dispatching custom events, component libraries" --- When compiling a component as a [custom element](custom-elements), the `$host` rune provides access to the host element, allowing you to (for example) dispatch custom events ([demo](/playground/untitled#H4sIAAAAAAAAE41Ry2rDMBD8FSECtqkTt1fHFpSSL-ix7sFRNkTEXglrnTYY_3uRlDgxTaEHIfYxs7szA9-rBizPPwZOZwM89wmecqxbF70as7InaMjltrWFR3mpkQDJ8pwXVnbKkKiwItUa3RGLVtk7gTHQXRDR2lXda4CY1D0SK9nCUk0QPyfrCovsRoNFe17aQOAwGncgO2gBqRzihJXiQrEs2csYOhQ-7HgKHaLIbpRhhBG-I2eD_8ciM4KnnOCbeE5dD2P6h0Dz0-Yi_arNhPLJXBtSGi2TvSXdbpqwdsXvjuYsC1veabvvUTog2ylrapKH2G2XsMFLS4uDthQnq2t1cwKkGOGLvYU5PvaQxLsxOkPmsm97Io1Mo2yUPF6VnOZFkw1RMoopKLKAE_9gmGxyDFMwMcwN-Bx_ABXQWmOtAgAA)): diff --git a/documentation/docs/03-template-syntax/01-basic-markup.md b/documentation/docs/03-template-syntax/01-basic-markup.md index feecfe033e..c95737ec75 100644 --- a/documentation/docs/03-template-syntax/01-basic-markup.md +++ b/documentation/docs/03-template-syntax/01-basic-markup.md @@ -1,5 +1,6 @@ --- title: Basic markup +use_cases: "always: HTML templates, component structure, attributes, events, text interpolation" --- Markup inside a Svelte component can be thought of as HTML++. diff --git a/documentation/docs/03-template-syntax/02-if.md b/documentation/docs/03-template-syntax/02-if.md index 1378733e6f..eee7c9fde5 100644 --- a/documentation/docs/03-template-syntax/02-if.md +++ b/documentation/docs/03-template-syntax/02-if.md @@ -1,5 +1,6 @@ --- title: {#if ...} +use_cases: "conditional rendering, showing/hiding elements, user permissions, feature flags, loading states" --- ```svelte diff --git a/documentation/docs/03-template-syntax/03-each.md b/documentation/docs/03-template-syntax/03-each.md index 006cadd152..7191229225 100644 --- a/documentation/docs/03-template-syntax/03-each.md +++ b/documentation/docs/03-template-syntax/03-each.md @@ -1,5 +1,6 @@ --- title: {#each ...} +use_cases: "lists, arrays, iterations, product listings, user lists, data tables, galleries, menus" --- ```svelte diff --git a/documentation/docs/03-template-syntax/04-key.md b/documentation/docs/03-template-syntax/04-key.md index 10b6ab4358..3299f99b0c 100644 --- a/documentation/docs/03-template-syntax/04-key.md +++ b/documentation/docs/03-template-syntax/04-key.md @@ -1,5 +1,6 @@ --- title: {#key ...} +use_cases: "forcing re-renders, resetting component state, animations on value change" --- ```svelte diff --git a/documentation/docs/03-template-syntax/05-await.md b/documentation/docs/03-template-syntax/05-await.md index 842b3c7e32..2470835679 100644 --- a/documentation/docs/03-template-syntax/05-await.md +++ b/documentation/docs/03-template-syntax/05-await.md @@ -1,5 +1,6 @@ --- title: {#await ...} +use_cases: "async data fetching, loading states, error handling, API calls, promises" --- ```svelte diff --git a/documentation/docs/03-template-syntax/06-snippet.md b/documentation/docs/03-template-syntax/06-snippet.md index 02f58e0f6c..f0081fce0e 100644 --- a/documentation/docs/03-template-syntax/06-snippet.md +++ b/documentation/docs/03-template-syntax/06-snippet.md @@ -1,5 +1,6 @@ --- title: {#snippet ...} +use_cases: "reusable markup, component composition, render props, slot alternatives, template patterns" --- ```svelte diff --git a/documentation/docs/03-template-syntax/07-@render.md b/documentation/docs/03-template-syntax/07-@render.md index ecdf5cc216..7bd47807af 100644 --- a/documentation/docs/03-template-syntax/07-@render.md +++ b/documentation/docs/03-template-syntax/07-@render.md @@ -1,5 +1,6 @@ --- title: {@render ...} +use_cases: "rendering snippets, dynamic content, component composition" --- To render a [snippet](snippet), use a `{@render ...}` tag. diff --git a/documentation/docs/03-template-syntax/08-@html.md b/documentation/docs/03-template-syntax/08-@html.md index 6d8a8be0c6..792886ccbc 100644 --- a/documentation/docs/03-template-syntax/08-@html.md +++ b/documentation/docs/03-template-syntax/08-@html.md @@ -1,5 +1,6 @@ --- title: {@html ...} +use_cases: "raw HTML rendering, CMS content, markdown rendering, rich text, third-party HTML" --- To inject raw HTML into your component, use the `{@html ...}` tag: diff --git a/documentation/docs/03-template-syntax/09-@attach.md b/documentation/docs/03-template-syntax/09-@attach.md index b25fbb32a6..3b0bbaacd7 100644 --- a/documentation/docs/03-template-syntax/09-@attach.md +++ b/documentation/docs/03-template-syntax/09-@attach.md @@ -1,5 +1,6 @@ --- title: {@attach ...} +use_cases: "DOM manipulation, third-party libraries, tooltips, popovers, advanced interactions" --- Attachments are functions that run in an [effect]($effect) when an element is mounted to the DOM or when [state]($state) read inside the function updates. diff --git a/documentation/docs/03-template-syntax/10-@const.md b/documentation/docs/03-template-syntax/10-@const.md index 2a587b7a3d..67beec9cd9 100644 --- a/documentation/docs/03-template-syntax/10-@const.md +++ b/documentation/docs/03-template-syntax/10-@const.md @@ -1,5 +1,6 @@ --- title: {@const ...} +use_cases: "template calculations, local variables in loops, derived values in blocks" --- The `{@const ...}` tag defines a local constant. diff --git a/documentation/docs/03-template-syntax/11-@debug.md b/documentation/docs/03-template-syntax/11-@debug.md index 15e32dcae9..422108849a 100644 --- a/documentation/docs/03-template-syntax/11-@debug.md +++ b/documentation/docs/03-template-syntax/11-@debug.md @@ -1,5 +1,6 @@ --- title: {@debug ...} +use_cases: "development only: debugging templates, inspecting values, troubleshooting" --- The `{@debug ...}` tag offers an alternative to `console.log(...)`. It logs the values of specific variables whenever they change, and pauses code execution if you have devtools open. diff --git a/documentation/docs/03-template-syntax/12-bind.md b/documentation/docs/03-template-syntax/12-bind.md index de57815687..f35b91477a 100644 --- a/documentation/docs/03-template-syntax/12-bind.md +++ b/documentation/docs/03-template-syntax/12-bind.md @@ -1,5 +1,6 @@ --- title: bind: +use_cases: "forms, inputs, two-way binding, checkboxes, selects, textareas, media elements, dimensions" --- Data ordinarily flows down, from parent to child. The `bind:` directive allows data to flow the other way, from child to parent. diff --git a/documentation/docs/03-template-syntax/13-use.md b/documentation/docs/03-template-syntax/13-use.md index 5f5321a1c0..f6381c6ae1 100644 --- a/documentation/docs/03-template-syntax/13-use.md +++ b/documentation/docs/03-template-syntax/13-use.md @@ -1,5 +1,6 @@ --- title: use: +use_cases: "third-party integrations, DOM libraries, custom directives, legacy code integration" --- > [!NOTE] diff --git a/documentation/docs/03-template-syntax/14-transition.md b/documentation/docs/03-template-syntax/14-transition.md index c51175c272..2b83e84720 100644 --- a/documentation/docs/03-template-syntax/14-transition.md +++ b/documentation/docs/03-template-syntax/14-transition.md @@ -1,5 +1,6 @@ --- title: transition: +use_cases: "animations, page transitions, element enter/leave effects, smooth UI changes" --- A _transition_ is triggered by an element entering or leaving the DOM as a result of a state change. diff --git a/documentation/docs/03-template-syntax/15-in-and-out.md b/documentation/docs/03-template-syntax/15-in-and-out.md index f4e37c845e..0911fca588 100644 --- a/documentation/docs/03-template-syntax/15-in-and-out.md +++ b/documentation/docs/03-template-syntax/15-in-and-out.md @@ -1,5 +1,6 @@ --- title: in: and out: +use_cases: "asymmetric animations, different enter/exit effects, one-way transitions" --- The `in:` and `out:` directives are identical to [`transition:`](transition), except that the resulting transitions are not bidirectional — an `in` transition will continue to 'play' alongside the `out` transition, rather than reversing, if the block is outroed while the transition is in progress. If an out transition is aborted, transitions will restart from scratch. diff --git a/documentation/docs/03-template-syntax/16-animate.md b/documentation/docs/03-template-syntax/16-animate.md index a54e37f0b1..78190fad95 100644 --- a/documentation/docs/03-template-syntax/16-animate.md +++ b/documentation/docs/03-template-syntax/16-animate.md @@ -1,5 +1,6 @@ --- title: animate: +use_cases: "list reordering animations, drag and drop, sortable lists, smooth transitions" --- An animation is triggered when the contents of a [keyed each block](each#Keyed-each-blocks) are re-ordered. Animations do not run when an element is added or removed, only when the index of an existing data item within the each block changes. Animate directives must be on an element that is an _immediate_ child of a keyed each block. diff --git a/documentation/docs/03-template-syntax/17-style.md b/documentation/docs/03-template-syntax/17-style.md index aa61cdcde3..269060268f 100644 --- a/documentation/docs/03-template-syntax/17-style.md +++ b/documentation/docs/03-template-syntax/17-style.md @@ -1,5 +1,6 @@ --- title: style: +use_cases: "dynamic styles, inline CSS, responsive design, theming, style calculations" --- The `style:` directive provides a shorthand for setting multiple styles on an element. diff --git a/documentation/docs/03-template-syntax/18-class.md b/documentation/docs/03-template-syntax/18-class.md index db85db4b37..ecce2e54dd 100644 --- a/documentation/docs/03-template-syntax/18-class.md +++ b/documentation/docs/03-template-syntax/18-class.md @@ -1,5 +1,6 @@ --- title: class +use_cases: "dynamic CSS classes, conditional styling, state-based styles, utility classes" --- There are two ways to set classes on elements: the `class` attribute, and the `class:` directive. diff --git a/documentation/docs/03-template-syntax/19-await-expressions.md b/documentation/docs/03-template-syntax/19-await-expressions.md index d3896a5c4e..5dcfa09e31 100644 --- a/documentation/docs/03-template-syntax/19-await-expressions.md +++ b/documentation/docs/03-template-syntax/19-await-expressions.md @@ -1,5 +1,6 @@ --- title: await +use_cases: "async components, SSR with async data, synchronized UI updates, data fetching" --- As of Svelte 5.36, you can use the `await` keyword inside your components in three places where it was previously unavailable: diff --git a/documentation/docs/04-styling/01-scoped-styles.md b/documentation/docs/04-styling/01-scoped-styles.md index eae26d0cb1..e9817404e6 100644 --- a/documentation/docs/04-styling/01-scoped-styles.md +++ b/documentation/docs/04-styling/01-scoped-styles.md @@ -1,5 +1,6 @@ --- title: Scoped styles +use_cases: "always: component-specific styles, CSS encapsulation, preventing style conflicts" --- Svelte components can include a `