Merge pull request #41 from spences10/faeture/add-definitions

Author: spences10

.changeset/stupid-eels-wink.md

@@ -0,0 +1,5 @@
+---
+'mcp-svelte-docs': patch
+---
+
+update defninitions

definitions/$app.forms.md

@@ -0,0 +1,30 @@
+# $app/forms Definition
+
+**Definition:** Client helpers for progressive form enhancement and
+action results.
+
+**Syntax:**
+`import { enhance, applyAction, deserialize } from '$app/forms'`
+
+**Functions:**
+
+- `enhance(form, submit?)` — use:enhance or programmatic; optional
+  callback per submit
+- `applyAction(result)` — apply an `ActionResult` to the current page
+- `deserialize(text)` — parse ActionResult from a fetch response
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { enhance } from '$app/forms';
+</script>
+
+<form method="POST" use:enhance>
+  <!-- ... -->
+</form>
+```
+
+## Related
+
+- `enhance`, `actions`, `fail`

definitions/$app.navigation.md

@@ -0,0 +1,36 @@
+# $app/navigation Definition
+
+**Definition:** Client utilities for navigation and invalidation.
+
+**Syntax:**
+`import { goto, invalidate, invalidateAll, beforeNavigate, afterNavigate, onNavigate, preloadData, preloadCode, refreshAll, pushState, replaceState, disableScrollHandling } from '$app/navigation'`
+
+**Functions:**
+
+- `goto(href, opts?)` — programmatic navigation
+- `invalidate(urlOrPredicate)` — re-run `load` for resources
+- `invalidateAll()` — re-run all active `load` functions
+- `beforeNavigate(cb)` / `afterNavigate(cb)` — navigation lifecycle
+  (call during component init)
+- `onNavigate(cb)` — pre-navigation hook (call during component init);
+  can await before completing and return cleanup
+- `preloadData(href)` — preload route code and run load
+- `preloadCode(pathname)` — preload route modules only
+- `refreshAll({ includeLoadFunctions? })` — refresh remote functions
+  and optionally rerun load
+- `pushState(url, state)` / `replaceState(url, state)` — shallow
+  routing state
+- `disableScrollHandling()` — disable router scroll handling for the
+  update
+
+## Example
+
+```ts
+import { goto, invalidate } from '$app/navigation';
+await goto('/dashboard');
+await invalidate((url) => url.pathname.startsWith('/api'));
+```
+
+## Related
+
+- `$app/stores`, `$app/forms`

definitions/$app.paths.md

@@ -0,0 +1,31 @@
+# $app/paths Definition
+
+**Definition:** Helpers for base/assets paths and resolving URLs or
+route IDs respecting `config.kit.paths`.
+
+**Syntax:** `import { asset, resolve } from '$app/paths'`
+
+**API:**
+
+- `asset(file)` — resolve URL for assets in `static/` honoring
+  `paths.assets` (2.26+)
+- `resolve(pathOrRoute, params?)` — resolve pathname or route ID with
+  params honoring base path (2.26+)
+- Deprecated: `assets`, `base`, `resolveRoute`
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { asset, resolve } from '$app/paths';
+  const img: string = asset('/logo.png');
+  const url: string = resolve('/blog/[slug]', { slug: 'hello-world' });
+</script>
+
+<img src={img} alt="logo" />
+<a href={url}>Post</a>
+```
+
+## Related
+
+- `configuration#paths`, `$app/navigation`

definitions/$app.server.md

@@ -0,0 +1,36 @@
+# $app/server Definition
+
+**Definition:** Server-only utilities for remote functions and server
+helpers: `getRequestEvent`, `read`, and creators for `query`, `form`,
+`command`, `prerender` (experimental ≥2.27).
+
+**Syntax:**
+`import { getRequestEvent, read, query, form, command, prerender } from '$app/server'`
+
+**API:**
+
+- `getRequestEvent()` — current RequestEvent (sync in environments
+  without AsyncLocalStorage)
+- `read(asset)` — read imported asset contents as a Response
+- `query/schema` — create server query (supports validation, batch,
+  `.refresh()/.set()`)
+- `form` — create spreadable form object with progressive enhancement
+- `command` — create server mutation callable from code (not during
+  render)
+- `prerender` — create build-time data function (with `inputs`,
+  `dynamic`)
+
+## Example
+
+```ts
+import { getRequestEvent, query } from '$app/server';
+
+export const me = query(async () => {
+	const { cookies, locals } = getRequestEvent();
+	return await locals.userFrom(cookies.get('sessionid'));
+});
+```
+
+## Related
+
+- `remote-functions`, `hooks.server.handleValidationError`

definitions/$app.state.md

@@ -0,0 +1,37 @@
+# $app/state Definition
+
+**Definition:** Read-only state module providing `page`, `navigating`,
+and `updated` for reactive routing and version info. Supersedes
+`$app/stores` in Kit ≥2.12.
+
+**Syntax:** `import { page, navigating, updated } from '$app/state'`
+
+**API:**
+
+- `page` — reactive object for `url`, `params`, `data`, `form`,
+  `route`, `status`, `error`
+- `navigating` — navigation info (`from`, `to`, `type`, `delta`, null
+  on server or idle)
+- `updated` — object with `current: boolean` and
+  `check(): Promise<boolean>`
+
+Note: `$app/state` values update reactively only via runes (e.g.
+`$derived`).
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { page, navigating, updated } from '$app/state';
+  const path = $derived(page.url.pathname);
+</script>
+
+<h1>{path}</h1>
+{#if navigating?.to}
+  <p>Navigating…</p>
+{/if}
+```
+
+## Related
+
+- `$app/navigation`, `$app/stores`

definitions/$app.stores.md

@@ -0,0 +1,30 @@
+# $app/stores Definition
+
+**Definition:** Client-accessible Svelte stores reflecting navigation
+state.
+
+Note: Deprecated in SvelteKit 2.12+ in favor of `$app/state` (use
+identical APIs via runes). Existing apps may still use `$app/stores`.
+
+**Syntax:** `import { page, navigating, updated } from '$app/stores'`
+
+**Stores:**
+
+- `page` — `Readable<Page>` with params, route, data
+- `navigating` — `Readable<Navigating | null>`
+- `updated` — `Readable<boolean> & { check(): Promise<boolean> }`
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { page, navigating, updated } from '$app/stores';
+  $: title = $page.url.pathname;
+</script>
+<h1>{title}</h1>
+{#if $navigating}<p>Loading…</p>{/if}
+```
+
+## Related
+
+- `$app/state`, `$app/navigation`, `load`

definitions/$derived.by.md

@@ -12,10 +12,10 @@ computations
 
 ## Examples
 
-```js
+```ts
 // Expensive computation that should be memoized
-let items = $state([1, 2, 3, 4, 5]);
-let filter = $state('even');
+let items: number[] = $state([1, 2, 3, 4, 5]);
+let filter: 'even' | 'odd' = $state('even');
 
 const expensiveResult = $derived.by(() => {
 	console.log('Computing expensive result...');
@@ -47,7 +47,7 @@ const processedData = $derived.by(() => {
 
 // When you need multiple statements
 const validation = $derived.by(() => {
-	const errors = [];
+	const errors: string[] = [];
 
 	if (items.length === 0) {
 		errors.push('Items cannot be empty');
@@ -62,6 +62,28 @@ const validation = $derived.by(() => {
 		errors,
 	};
 });
+
+// Override a derived temporarily (e.g., optimistic UI)
+let likes = $derived(post.likes);
+async function like() {
+	likes += 1; // override
+	try {
+		await sendLike();
+	} catch {
+		likes -= 1; // rollback on error
+	}
+}
+
+// Destructuring: each piece remains reactive
+let { a, b } = $derived(getPair()); // each remains reactive
+
+// Dependency control
+let total2 = $derived.by(() => {
+	// anything read synchronously is a dependency
+	return items.reduce((s, n) => s + n, 0);
+});
+
+// To exempt values from tracking, use untrack(...)
 ```
 
 ## Related

definitions/$env.dynamic.private.md

@@ -0,0 +1,23 @@
+# $env/dynamic/private Definition
+
+**Definition:** Runtime (dynamic) private environment variables
+available on the server. Excludes variables with `publicPrefix` and
+includes those with `privatePrefix` (if configured).
+
+**Syntax:** `import { env } from '$env/dynamic/private'`
+
+**Notes:**
+
+- Server-only; cannot be imported in client code.
+- In dev, includes vars from `.env`; in prod, depends on adapter.
+
+## Example
+
+```ts
+import { env } from '$env/dynamic/private';
+const secret = env.SECRET_API_KEY;
+```
+
+## Related
+
+- `$env/static/private`, `$env/dynamic/public`

definitions/$env.dynamic.public.md

@@ -0,0 +1,23 @@
+# $env/dynamic/public Definition
+
+**Definition:** Runtime (dynamic) public environment variables safe
+for client usage. Includes only variables with `publicPrefix` (default
+`PUBLIC_`).
+
+**Syntax:** `import { env } from '$env/dynamic/public'`
+
+**Notes:**
+
+- Public dynamic vars are sent from server to client; prefer
+  `$env/static/public` when possible.
+
+## Example
+
+```ts
+import { env } from '$env/dynamic/public';
+const base = env.PUBLIC_BASE_URL;
+```
+
+## Related
+
+- `$env/static/public`, `$env/dynamic/private`