more

documentation/docs/01-introduction/03-svelte-files.md

@@ -0,0 +1,66 @@
+---
+title: .svelte files
+---
+
+Components are the building blocks of Svelte applications. They are written into `.svelte` files, using a superset of HTML.
+
+All three sections — script, styles and markup — are optional.
+
+<!-- prettier-ignore -->
+```svelte
+/// file: MyComponent.svelte
+<script module>
+	// module-level logic goes here
+	// (you will rarely use this)
+</script>
+
+<script>
+	// instance-level logic goes here
+</script>
+
+<!-- markup (zero or more items) goes here -->
+
+<style>
+	/* styles go here */
+</style>
+```
+
+## `<script>`
+
+A `<script>` block contains JavaScript (or TypeScript, when adding the `lang="ts"` attribute) that runs when a component instance is created. Variables declared (or imported) at the top level can be referenced in the component's markup.
+
+In addition to normal JavaScript, you can use _runes_ to declare [component props]($props) and add reactivity to your component. Runes are covered in the next section.
+
+<!-- TODO describe behaviour of `export` -->
+
+## `<script module>`
+
+A `<script>` tag with a `module` attribute runs once when the module first evaluates, rather than for each component instance. Variables declared in this block can be referenced elsewhere in the component, but not vice versa.
+
+You can `export` bindings from this block, and they will become exports of the compiled module. You cannot `export default`, since the default export is the component itself.
+
+```svelte
+<script module>
+	let total = 0;
+</script>
+
+<script>
+	total += 1;
+	console.log(`instantiated ${total} times`);
+</script>
+```
+
+## `<style>`
+
+CSS inside a `<style>` block will be scoped to that component.
+
+```svelte
+<style>
+	p {
+		/* this will only affect <p> elements in this component */
+		color: burlywood;
+	}
+</style>
+```
+
+For more information regarding styling, read the documentation around [styles and classes](styles-and-classes).

documentation/docs/01-introduction/04-svelte-js-files.md

@@ -0,0 +1,7 @@
+---
+title: .svelte.js and .svelte.ts files
+---
+
+Besides `.svelte` files, Svelte also operates on `.svelte.js` and `.svelte.ts` files.
+
+These behave like any other `.js` or `.ts` module, except that you can use runes. This is useful for creating reusable reactive logic, or sharing reactive state across your app.

documentation/docs/01-introduction/xx-props.md

@@ -0,0 +1,139 @@
+---
+title: Public API of a component
+---
+
+### Public API of a component
+
+Svelte uses the `$props` rune to declare _properties_ or _props_, which means describing the public interface of the component which becomes accessible to consumers of the component.
+
+> [!NOTE] `$props` is one of several runes, which are special hints for Svelte's compiler to make things reactive.
+
+```svelte
+<script>
+	let { foo, bar, baz } = $props();
+
+	// Values that are passed in as props
+	// are immediately available
+	console.log({ foo, bar, baz });
+</script>
+```
+
+You can specify a fallback value for a prop. It will be used if the component's consumer doesn't specify the prop on the component when instantiating the component, or if the passed value is `undefined` at some point.
+
+```svelte
+<script>
+	let { foo = 'optional default initial value' } = $props();
+</script>
+```
+
+To get all properties, use rest syntax:
+
+```svelte
+<script>
+	let { a, b, c, ...everythingElse } = $props();
+</script>
+```
+
+You can use reserved words as prop names.
+
+```svelte
+<script>
+	// creates a `class` property, even
+	// though it is a reserved word
+	let { class: className } = $props();
+</script>
+```
+
+If you're using TypeScript, you can declare the prop types:
+
+```svelte
+<script lang="ts">
+	interface Props {
+		required: string;
+		optional?: number;
+		[key: string]: unknown;
+	}
+
+	let { required, optional, ...everythingElse }: Props = $props();
+</script>
+```
+
+If you're using JavaScript, you can declare the prop types using JSDoc:
+
+```svelte
+<script>
+	/** @type {{ x: string }} */
+	let { x } = $props();
+
+	// or use @typedef if you want to document the properties:
+
+	/**
+	 * @typedef {Object} MyProps
+	 * @property {string} y Some documentation
+	 */
+
+	/** @type {MyProps} */
+	let { y } = $props();
+</script>
+```
+
+If you export a `const`, `class` or `function`, it is readonly from outside the component.
+
+```svelte
+<script>
+	export const thisIs = 'readonly';
+
+	export function greet(name) {
+		alert(`hello ${name}!`);
+	}
+</script>
+```
+
+Readonly props can be accessed as properties on the element, tied to the component using [`bind:this` syntax](bindings#bind:this).
+
+### Reactive variables
+
+To change component state and trigger a re-render, just assign to a locally declared variable that was declared using the `$state` rune.
+
+Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect.
+
+```svelte
+<script>
+	let count = $state(0);
+
+	function handleClick() {
+		// calling this function will trigger an
+		// update if the markup references `count`
+		count = count + 1;
+	}
+</script>
+```
+
+Svelte's `<script>` blocks are run only when the component is created, so assignments within a `<script>` block are not automatically run again when a prop updates.
+
+```svelte
+<script>
+	let { person } = $props();
+	// this will only set `name` on component creation
+	// it will not update when `person` does
+	let { name } = person;
+</script>
+```
+
+If you'd like to react to changes to a prop, use the `$derived` or `$effect` runes instead.
+
+```svelte
+<script>
+	let count = $state(0);
+
+	let double = $derived(count * 2);
+
+	$effect(() => {
+		if (count > 10) {
+			alert('Too high!');
+		}
+	});
+</script>
+```
+
+For more information on reactivity, read the documentation around runes.