wip

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

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:

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.

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.

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_

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.

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:

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 `<canvas>` elements, or making network requests. They only run in the browser, not during server-side rendering.

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:

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.

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.

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)):

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++.

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

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

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

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

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

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.

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:

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.

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.

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.

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.

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]

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.

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.

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.

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.

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.

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:

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 `<style>` element containing CSS that belongs to the component. This CSS is _scoped_ by default, meaning that styles will not apply to any elements on the page outside the component in question.

documentation/docs/04-styling/02-global-styles.md

@@ -1,5 +1,6 @@
 ---
 title: Global styles
+use_cases: "app-wide styles, CSS resets, typography, third-party CSS integration"
 ---
 
 ## :global(...)

documentation/docs/04-styling/03-custom-properties.md

@@ -1,5 +1,6 @@
 ---
 title: Custom properties
+use_cases: "theming, design tokens, dynamic CSS variables, component customization"
 ---
 
 You can pass CSS custom properties — both static and dynamic — to components:

documentation/docs/04-styling/04-nested-style-elements.md

@@ -1,5 +1,6 @@
 ---
 title: Nested <style> elements
+use_cases: "dynamic runtime styles, conditional CSS, user-generated styles"
 ---
 
 There can only be one top-level `<style>` tag per component.

documentation/docs/05-special-elements/01-svelte-boundary.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:boundary>
+use_cases: "error boundaries, async loading states, error handling, resilient UIs"
 ---
 
 ```svelte

documentation/docs/05-special-elements/02-svelte-window.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:window>
+use_cases: "window events, scroll handling, keyboard shortcuts, resize detection, online/offline"
 ---
 
 ```svelte

documentation/docs/05-special-elements/03-svelte-document.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:document>
+use_cases: "document events, visibility changes, fullscreen handling, global clicks"
 ---
 
 ```svelte

documentation/docs/05-special-elements/04-svelte-body.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:body>
+use_cases: "body events, mouse enter/leave, global interactions, body classes"
 ---
 
 ```svelte

documentation/docs/05-special-elements/05-svelte-head.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:head>
+use_cases: "SEO, meta tags, page titles, OpenGraph, structured data, external scripts"
 ---
 
 ```svelte

documentation/docs/05-special-elements/06-svelte-element.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:element>
+use_cases: "dynamic HTML elements, CMS rendering, configurable components, polymorphic components"
 ---
 
 ```svelte

documentation/docs/05-special-elements/07-svelte-options.md

@@ -1,5 +1,6 @@
 ---
 title: <svelte:options>
+use_cases: "component configuration, custom elements setup, compiler options, namespace settings"
 ---
 
 ```svelte