diff --git a/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md b/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md index 954bc4e88a..5437a4fb4c 100644 --- a/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md +++ b/apps/svelte.dev/content/docs/kit/20-core-concepts/20-load.md @@ -664,6 +664,7 @@ To summarize, a `load` function will rerun in the following situations: - It references a property of `url` (such as `url.pathname` or `url.search`) whose value has changed. Properties in `request.url` are _not_ tracked - It calls `url.searchParams.get(...)`, `url.searchParams.getAll(...)` or `url.searchParams.has(...)` and the parameter in question changes. Accessing other properties of `url.searchParams` will have the same effect as accessing `url.search`. - It calls `await parent()` and a parent `load` function reran +- A child `load` function calls `await parent()` and is rerunning, and the parent is a server load function - It declared a dependency on a specific URL via [`fetch`](#making-fetch-requests) (universal load only) or [`depends`](types#public-types-loadevent), and that URL was marked invalid with [`invalidate(url)`](modules#$app-navigation-invalidate) - All active `load` functions were forcibly rerun with [`invalidateAll()`](modules#$app-navigation-invalidateall) diff --git a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md index 525a33197d..3c7d7bb230 100644 --- a/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md +++ b/apps/svelte.dev/content/docs/kit/98-reference/10-@sveltejs-kit.md @@ -814,6 +814,10 @@ Compress files in `directory` with gzip and brotli, where appropriate. Generates +## Config + +See the [configuration reference](/docs/kit/configuration) for details. + ## Cookies
@@ -1085,6 +1089,10 @@ The content of the error.
+## KitConfig + +See the [configuration reference](/docs/kit/configuration) for details. + ## LessThan
diff --git a/apps/svelte.dev/content/docs/svelte/04-runtime/03-lifecycle-hooks.md b/apps/svelte.dev/content/docs/svelte/04-runtime/03-lifecycle-hooks.md index b4af4e5df7..05aa38ccbb 100644 --- a/apps/svelte.dev/content/docs/svelte/04-runtime/03-lifecycle-hooks.md +++ b/apps/svelte.dev/content/docs/svelte/04-runtime/03-lifecycle-hooks.md @@ -45,7 +45,13 @@ If a function is returned from `onMount`, it will be called when the component i ## `onDestroy` -> EXPORT_SNIPPET: svelte#onDestroy +
+ +```dts +function onDestroy(fn: () => any): void; +``` + +
Schedules a callback to run immediately before the component is unmounted. diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-store.md b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-store.md index 7b14037aa6..eecc60e33e 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-store.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-store.md @@ -186,4 +186,140 @@ function writable(
+## Readable + +Readable interface for subscribing. + +
+ +```dts +interface Readable {/*…*/} +``` + +
+ +```dts +subscribe(this: void, run: Subscriber, invalidate?: () => void): Unsubscriber; +``` + +
+ +
+ +- `run` subscription callback +- `invalidate` cleanup callback + +
+ +Subscribe on value changes. + +
+
+
+ +## StartStopNotifier + +Start and stop notification callbacks. +This function is called when the first subscriber subscribes. + +
+ +```dts +type StartStopNotifier = ( + set: (value: T) => void, + update: (fn: Updater) => void +) => void | (() => void); +``` + + +
+ +## Subscriber + +Callback to inform of a value updates. + +
+ +```dts +type Subscriber = (value: T) => void; +``` + + +
+ +## Unsubscriber + +Unsubscribes from value updates. + +
+ +```dts +type Unsubscriber = () => void; +``` + + +
+ +## Updater + +Callback to update a value. + +
+ +```dts +type Updater = (value: T) => T; +``` + + +
+ +## Writable + +Writable interface for both updating and subscribing. + +
+ +```dts +interface Writable extends Readable {/*…*/} +``` + +
+ +```dts +set(this: void, value: T): void; +``` + +
+ +
+ +- `value` to set + +
+ +Set value and inform subscribers. + +
+
+ +
+ +```dts +update(this: void, updater: Updater): void; +``` + +
+ +
+ +- `updater` callback + +
+ +Update value using callback and inform subscribers. + +
+
+
+ diff --git a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-transition.md b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-transition.md index 71fc9fe42c..af50214ab8 100644 --- a/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-transition.md +++ b/apps/svelte.dev/content/docs/svelte/98-reference/21-svelte-transition.md @@ -193,4 +193,402 @@ function slide( +## BlurParams + +
+ +```dts +interface BlurParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+ +
+ +```dts +amount?: number | string; +``` + +
+
+ +
+ +```dts +opacity?: number; +``` + +
+
+
+ +## CrossfadeParams + +
+ +```dts +interface CrossfadeParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number | ((len: number) => number); +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+
+ +## DrawParams + +
+ +```dts +interface DrawParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +speed?: number; +``` + +
+
+ +
+ +```dts +duration?: number | ((len: number) => number); +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+
+ +## EasingFunction + +
+ +```dts +type EasingFunction = (t: number) => number; +``` + + +
+ +## FadeParams + +
+ +```dts +interface FadeParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+
+ +## FlyParams + +
+ +```dts +interface FlyParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+ +
+ +```dts +x?: number | string; +``` + +
+
+ +
+ +```dts +y?: number | string; +``` + +
+
+ +
+ +```dts +opacity?: number; +``` + +
+
+
+ +## ScaleParams + +
+ +```dts +interface ScaleParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+ +
+ +```dts +start?: number; +``` + +
+
+ +
+ +```dts +opacity?: number; +``` + +
+
+
+ +## SlideParams + +
+ +```dts +interface SlideParams {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+ +
+ +```dts +axis?: 'x' | 'y'; +``` + +
+
+
+ +## TransitionConfig + +
+ +```dts +interface TransitionConfig {/*…*/} +``` + +
+ +```dts +delay?: number; +``` + +
+
+ +
+ +```dts +duration?: number; +``` + +
+
+ +
+ +```dts +easing?: EasingFunction; +``` + +
+
+ +
+ +```dts +css?: (t: number, u: number) => string; +``` + +
+
+ +
+ +```dts +tick?: (t: number, u: number) => void; +``` + +
+
+
+ diff --git a/apps/svelte.dev/src/sync-docs.ts b/apps/svelte.dev/src/sync-docs.ts index 75de18d410..db0c787182 100644 --- a/apps/svelte.dev/src/sync-docs.ts +++ b/apps/svelte.dev/src/sync-docs.ts @@ -1,11 +1,4 @@ -import { - stringify_expanded_type, - replace_export_type_placeholders, - stringify_module, - stringify_type, - type ModuleChild, - type Modules -} from '@sveltejs/site-kit/markdown'; +import { replace_export_type_placeholders, type Modules } from '@sveltejs/site-kit/markdown'; import { spawn } from 'node:child_process'; import { cpSync, @@ -24,7 +17,7 @@ import glob from 'tiny-glob/sync'; // Adjust the following variables as needed for your local setup /** If `true`, will checkout the docs from Git. If `false`, will use the `..._repo_path` vars to get content from your local file system */ -const use_git = true; +const use_git = false; /** The path to your local Svelte repository (only relevant if `use_git` is `false`) */ let svelte_repo_path = '../../../svelte'; /** The path to your local SvelteKit repository (only relevant if `use_git` is `false`) */ @@ -72,16 +65,10 @@ async function sync_svelte_docs() { const files = glob('content/docs/svelte/**/*.md'); for (const file of files) { - let content = readFileSync(file, 'utf-8'); - - // TODO if we settle on the sync approach we can remove this and use the > XXX syntax in the doc files again - content = content.replace(//g, (match, moduleName) => { - const module = svelte_modules.find((m: any) => m.name === moduleName); - if (!module) throw new Error('Reference not found in generated types: ' + moduleName); - return stringify_module(module); - }); - - content = await replace_export_type_placeholders(content, svelte_modules); + const content = await replace_export_type_placeholders( + readFileSync(file, 'utf-8'), + svelte_modules + ); writeFileSync(file, content); } @@ -120,31 +107,27 @@ async function sync_kit_docs() { const svelte_kit_types = sveltekit_modules.find((m) => m.name === '@sveltejs/kit')!.types!; const config = svelte_kit_types.find((t) => t.name === 'Config')!; const kit_config = svelte_kit_types.find((t) => t.name === 'KitConfig')!; + const full_config = { ...config }; + const full_kit_config = { ...kit_config }; - sveltekit_modules.find((m) => m.name === '@sveltejs/kit')!.types = svelte_kit_types.filter( - (t) => t.name !== 'Config' && t.name !== 'KitConfig' - ); + // special case — we want these to be on a separate page + config.children = kit_config.children = undefined; + config.bullets = kit_config.bullets = undefined; + config.snippet = kit_config.snippet = ''; + config.comment = kit_config.comment = + 'See the [configuration reference](/docs/kit/configuration) for details.'; const kit_files = glob('content/docs/kit/**/*.md'); for (const file of kit_files) { - let content = readFileSync(file, 'utf-8'); - - // TODO if we settle on the sync approach we can remove this and use the > XXX syntax in the doc files again - content = content.replace(//g, (match, moduleName) => { - if (moduleName === 'Config') { - return stringify_type(config as ModuleChild); - } - if (moduleName === 'KitConfig') { - return stringify_expanded_type(kit_config); - } - - const module = sveltekit_modules.find((m) => m.name === moduleName); - if (!module) throw new Error('Reference not found in generated types: ' + moduleName); - return stringify_module(module as any); - }); - - content = await replace_export_type_placeholders(content, sveltekit_modules); + const content = await replace_export_type_placeholders( + readFileSync(file, 'utf-8'), + !file.includes('configuration') + ? sveltekit_modules + : sveltekit_modules.map((m) => + m.name === '@sveltejs/kit' ? { ...m, types: [full_config, full_kit_config] } : m + ) + ); writeFileSync(file, content); } diff --git a/packages/site-kit/src/lib/markdown/index.ts b/packages/site-kit/src/lib/markdown/index.ts index 226e9747e9..0385e876a4 100644 --- a/packages/site-kit/src/lib/markdown/index.ts +++ b/packages/site-kit/src/lib/markdown/index.ts @@ -1,9 +1,6 @@ export { render_content_markdown as renderContentMarkdown, - replace_export_type_placeholders, - stringify_module, - stringify_type, - stringify_expanded_type + replace_export_type_placeholders } from './renderer'; export { diff --git a/packages/site-kit/src/lib/markdown/renderer.ts b/packages/site-kit/src/lib/markdown/renderer.ts index c08b5b26f6..e29a68bf88 100644 --- a/packages/site-kit/src/lib/markdown/renderer.ts +++ b/packages/site-kit/src/lib/markdown/renderer.ts @@ -520,10 +520,17 @@ export async function convert_to_ts(js_code: string, indent = '', offset = '') { */ export async function replace_export_type_placeholders(content: string, modules: Modules) { const REGEXES = { + /** Render a specific type from a module with more details. Example: `> EXPANDED_TYPES: svelte#compile` */ EXPANDED_TYPES: /> EXPANDED_TYPES: (.+?)#(.+)$/gm, + /** Render types from a specific module. Example: `> TYPES: svelte` */ TYPES: /> TYPES: (.+?)(?:#(.+))?$/gm, + /** Render all exports and types from a specific module. Example: `> MODULE: svelte` */ + MODULE: /> MODULE: (.+?)$/gm, + /** Render the snippet of a specific export. Example: `> EXPORT_SNIPPET: svelte#compile` */ EXPORT_SNIPPET: /> EXPORT_SNIPPET: (.+?)#(.+)?$/gm, + /** Render all modules. Example: `> MODULES` */ MODULES: /> MODULES/g, //! /g is VERY IMPORTANT, OR WILL CAUSE INFINITE LOOP + /** Render all value exports from a specific module. Example: `> EXPORTS: svelte` */ EXPORTS: /> EXPORTS: (.+)/ }; @@ -542,32 +549,9 @@ export async function replace_export_type_placeholders(content: string, modules: const type = module.types.find((t) => t.name === id); - if (!type) return ''; + if (!type) throw new Error(`Could not find type ${name}#${id}`); - return ( - type.comment + - type.children - ?.map((child) => { - let section = `### ${child.name}`; - - if (child.bullets) { - section += `\n\n
\n\n${child.bullets.join( - '\n' - )}\n\n
`; - } - - section += `\n\n${child.comment}`; - - if (child.children) { - section += `\n\n
\n\n${child.children - .map((v) => stringify(v)) - .join('\n')}\n\n
`; - } - - return section; - }) - .join('\n\n') - ); + return stringify_expanded_type(type); }); content = await async_replace(content, REGEXES.TYPES, async ([_, name, id]) => { @@ -578,35 +562,17 @@ export async function replace_export_type_placeholders(content: string, modules: if (id) { const type = module.types.find((t) => t.name === id); - if (!type) return ''; + if (!type) throw new Error(`Could not find type ${name}#${id}`); - return ( - `
${fence(type.snippet, 'dts')}` + - type.children?.map((v) => stringify(v)).join('\n\n') + - `
` - ); + return stringify_type(type); } - return `${module.comment}\n\n${( - await Promise.all( - module.types.map(async (t) => { - let children = t.children?.map((val) => stringify(val, 'dts')).join('\n\n'); - if (t.name === 'Config' || t.name === 'KitConfig') { - // special case — we want these to be on a separate page - children = - '
\n\nSee the [configuration reference](/docs/configuration) for details.
'; - } - - const deprecated = t.deprecated - ? `
${await transform(t.deprecated)}
` - : ''; - - const markdown = `
${fence(t.snippet, 'dts')}` + children + `
`; + let comment = ''; + if (module.comment) { + comment += `${module.comment}\n\n`; + } - return `### ${t.name}\n\n${deprecated}\n\n${t.comment ?? ''}\n\n${markdown}\n\n`; - }) - ) - ).join('')}`; + return comment + module.types.map((t) => `## ${t.name}\n\n${stringify_type(t)}`).join(''); }); content = await async_replace(content, REGEXES.EXPORT_SNIPPET, async ([_, name, id]) => { @@ -626,6 +592,13 @@ export async function replace_export_type_placeholders(content: string, modules: ); }); + content = await async_replace(content, REGEXES.MODULE, async ([_, name]) => { + const module = modules.find((module) => module.name === name); + if (!module) throw new Error(`Could not find module ${name}`); + + return stringify_module(module); + }); + content = await async_replace(content, REGEXES.MODULES, async () => { return modules .map((module) => { @@ -698,7 +671,7 @@ export async function replace_export_type_placeholders(content: string, modules: /** * Takes a module and returns a markdown string. */ -export function stringify_module(module: Modules[0]) { +function stringify_module(module: Modules[0]) { let content = ''; if (module.exports && module.exports.length > 0) { @@ -726,20 +699,13 @@ export function stringify_module(module: Modules[0]) { } for (const t of module.types || []) { - if (module.name === '@sveltejs/kit' && (t.name === 'Config' || t.name === 'KitConfig')) { - // special case — we want these to be on a separate page - content += - `## ${t.name}\n\n` + - 'See the [configuration reference](/docs/reference/configuration) for details.\n\n'; - } else { - content += `## ${t.name}\n\n` + stringify_type(t); - } + content += `## ${t.name}\n\n` + stringify_type(t); } return content; } -export function stringify_type(t: ModuleChild) { +function stringify_type(t: ModuleChild) { let content = ''; if (t.deprecated) { @@ -750,12 +716,14 @@ export function stringify_type(t: ModuleChild) { content += `${t.comment}\n\n`; } - const children = t.children?.map((val) => stringify(val, 'dts')).join('\n\n'); - content += `
${fence(t.snippet, 'dts')}` + children + `\n
\n\n`; + if (t.children || t.snippet) { + const children = t.children?.map((val) => stringify(val, 'dts')).join('\n\n'); + content += `
${fence(t.snippet, 'dts')}` + children + `\n
\n\n`; + } return content; } -export function stringify_expanded_type(type: ModuleChild) { +function stringify_expanded_type(type: ModuleChild) { return ( type.comment + type.children