From 4a288a5e336b4e41509f7de6612f55b6f523758a Mon Sep 17 00:00:00 2001 From: Puru Vijay Date: Fri, 14 Apr 2023 17:38:46 +0530 Subject: [PATCH] Add two-slash to docs pages --- .../01-svelte-components.md | 3 +- .../05-element-directives.md | 6 +- .../docs/03-runtime/02-svelte-store.md | 76 +++++- .../docs/03-runtime/03-svelte-motion.md | 32 ++- .../04-compiler-and-api/01-svelte-compiler.md | 75 +++++- .../02-client-side-component-api.md | 154 +++++++++++- .../03-server-side-component-api.md | 3 + .../04-custom-elements-api.md | 2 + .../docs/06-legacy/01-svelte-register.md | 4 +- sites/svelte.dev/package-lock.json | 25 ++ sites/svelte.dev/package.json | 2 + sites/svelte.dev/src/lib/server/docs/index.js | 234 ++++++++---------- .../svelte.dev/src/lib/server/docs/render.js | 9 +- sites/svelte.dev/src/lib/utils/Tooltip.svelte | 67 +++++ sites/svelte.dev/src/lib/utils/hovers.js | 60 +++++ .../src/routes/docs/[slug]/+page.svelte | 62 ++++- 16 files changed, 656 insertions(+), 158 deletions(-) create mode 100644 sites/svelte.dev/src/lib/utils/Tooltip.svelte create mode 100644 sites/svelte.dev/src/lib/utils/hovers.js diff --git a/site/content/docs/02-template-syntax/01-svelte-components.md b/site/content/docs/02-template-syntax/01-svelte-components.md index 648c572394..b13a4e1757 100644 --- a/site/content/docs/02-template-syntax/01-svelte-components.md +++ b/site/content/docs/02-template-syntax/01-svelte-components.md @@ -239,7 +239,8 @@ Local variables (that do not represent store values) must _not_ have a `$` prefi #### Store contract -```js +```ts +// @noErrors store = { subscribe: (subscription: (value: any) => void) => (() => void), set?: (value: any) => void } ``` diff --git a/site/content/docs/02-template-syntax/05-element-directives.md b/site/content/docs/02-template-syntax/05-element-directives.md index 8cb8c4c01d..3c3f1e6d86 100644 --- a/site/content/docs/02-template-syntax/05-element-directives.md +++ b/site/content/docs/02-template-syntax/05-element-directives.md @@ -397,7 +397,8 @@ use:action use:action={parameters} ``` -```js +```ts +// @noErrors action = (node: HTMLElement, parameters: any) => { update?: (parameters: any) => void, destroy?: () => void @@ -471,6 +472,7 @@ transition:fn|local={params} ``` ```js +// @noErrors transition = (node: HTMLElement, params: any, options: { direction: 'in' | 'out' | 'both' }) => { delay?: number, duration?: number, @@ -670,6 +672,7 @@ animate:name={params} ``` ```js +// @noErrors animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => { delay?: number, duration?: number, @@ -680,6 +683,7 @@ animation = (node: HTMLElement, { from: DOMRect, to: DOMRect } , params: any) => ``` ```ts +// @noErrors DOMRect { bottom: number, height: number, diff --git a/site/content/docs/03-runtime/02-svelte-store.md b/site/content/docs/03-runtime/02-svelte-store.md index d7dad3cc6f..fd5ac4c8df 100644 --- a/site/content/docs/03-runtime/02-svelte-store.md +++ b/site/content/docs/03-runtime/02-svelte-store.md @@ -36,6 +36,7 @@ count.update((n) => n + 1); // logs '2' If a function is passed as the second argument, it will be called when the number of subscribers goes from zero to one (but not from one to two, etc). That function will be passed a `set` function which changes the value of the store. It must return a `stop` function that is called when the subscriber count goes from one to zero. ```js +/// file: store.js import { writable } from 'svelte/store'; const count = writable(0, () => { @@ -64,8 +65,7 @@ Creates a store whose value cannot be set from 'outside', the first argument is /// file: store.js import { readable } from 'svelte/store'; -/** @type {import('svelte/store').Readable} */ -const time = readable(null, (set) => { +const time = readable(new Date(), (set) => { set(new Date()); const interval = setInterval(() => { @@ -84,7 +84,18 @@ Derives a store from one or more other stores. The callback runs initially when In the simplest version, `derived` takes a single store, and the callback returns a derived value. -```js +```ts +// @filename: ambient.d.ts +import { type Writable } from 'svelte/store'; + +declare global { + const a: Writable; +} + +export {}; + +// @filename: index.ts +// ---cut--- import { derived } from 'svelte/store'; const doubled = derived(a, ($a) => $a * 2); @@ -94,9 +105,18 @@ The callback can set a value asynchronously by accepting a second argument, `set In this case, you can also pass a third argument to `derived` — the initial value of the derived store before `set` is first called. - - ```js +// @filename: ambient.d.ts +import { type Writable } from 'svelte/store'; + +declare global { + const a: Writable; +} + +export {}; + +// @filename: index.ts +// ---cut--- import { derived } from 'svelte/store'; const delayed = derived( @@ -104,15 +124,24 @@ const delayed = derived( ($a, set) => { setTimeout(() => set($a), 1000); }, - 'one moment...' + 2000 ); ``` If you return a function from the callback, it will be called when a) the callback runs again, or b) the last subscriber unsubscribes. - - ```js +// @filename: ambient.d.ts +import { type Writable } from 'svelte/store'; + +declare global { + const frequency: Writable; +} + +export {}; + +// @filename: index.ts +// ---cut--- import { derived } from 'svelte/store'; const tick = derived( @@ -126,15 +155,26 @@ const tick = derived( clearInterval(interval); }; }, - 'one moment...' + 2000 ); ``` In both cases, an array of arguments can be passed as the first argument instead of a single store. - +```ts +// @filename: ambient.d.ts +import { type Writable } from 'svelte/store'; -```js +declare global { + const a: Writable; + const b: Writable; +} + +export {}; + +// @filename: index.ts + +// ---cut--- import { derived } from 'svelte/store'; const summed = derived([a, b], ([$a, $b]) => $a + $b); @@ -151,7 +191,7 @@ const delayed = derived([a, b], ([$a, $b], set) => { This simple helper function makes a store readonly. You can still subscribe to the changes from the original one using this new readable store. ```js -import { readonly } from 'svelte/store'; +import { readonly, writable } from 'svelte/store'; const writableStore = writable(1); const readableStore = readonly(writableStore); @@ -159,6 +199,7 @@ const readableStore = readonly(writableStore); readableStore.subscribe(console.log); writableStore.set(2); // console: 2 +// @errors: 2339 readableStore.set(2); // ERROR ``` @@ -171,6 +212,17 @@ Generally, you should read the value of a store by subscribing to it and using t > This works by creating a subscription, reading the value, then unsubscribing. It's therefore not recommended in hot code paths. ```js +// @filename: ambient.d.ts +import { type Writable } from 'svelte/store'; + +declare global { + const store: Writable; +} + +export {}; + +// @filename: index.ts +// ---cut--- import { get } from 'svelte/store'; const value = get(store); diff --git a/site/content/docs/03-runtime/03-svelte-motion.md b/site/content/docs/03-runtime/03-svelte-motion.md index 1654b5613a..0351d89586 100644 --- a/site/content/docs/03-runtime/03-svelte-motion.md +++ b/site/content/docs/03-runtime/03-svelte-motion.md @@ -44,7 +44,19 @@ Out of the box, Svelte will interpolate between two numbers, two arrays or two o If the initial value is `undefined` or `null`, the first value change will take effect immediately. This is useful when you have tweened values that are based on props, and don't want any motion when the component first renders. -```js +```ts +// @filename: ambient.d.ts +declare global { + var $size: number; + var big: number; +} + +export {}; +// @filename: motion.ts +// ---cut--- +import { tweened } from 'svelte/motion'; +import { cubicOut } from 'svelte/easing'; + const size = tweened(undefined, { duration: 300, easing: cubicOut @@ -90,6 +102,8 @@ A `spring` store gradually changes to its target value based on its `stiffness` All of the options above can be changed while the spring is in motion, and will take immediate effect. ```js +import { spring } from 'svelte/motion'; + const size = spring(100); size.stiffness = 0.3; size.damping = 0.4; @@ -101,6 +115,8 @@ As with [`tweened`](/docs/svelte-motion#tweened) stores, `set` and `update` retu Both `set` and `update` can take a second argument — an object with `hard` or `soft` properties. `{ hard: true }` sets the target value immediately; `{ soft: n }` preserves existing momentum for `n` seconds before settling. `{ soft: true }` is equivalent to `{ soft: 0.5 }`. ```js +import { spring } from 'svelte/motion'; + const coords = spring({ x: 50, y: 50 }); // updates the value immediately coords.set({ x: 100, y: 200 }, { hard: true }); @@ -131,7 +147,19 @@ coords.update( If the initial value is `undefined` or `null`, the first value change will take effect immediately, just as with `tweened` values (see above). -```js +```ts +// @filename: ambient.d.ts +declare global { + var $size: number; + var big: number; +} + +export {}; + +// @filename: motion.ts +// ---cut--- +import { spring } from 'svelte/motion'; + const size = spring(); $: $size = big ? 100 : 10; ``` diff --git a/site/content/docs/04-compiler-and-api/01-svelte-compiler.md b/site/content/docs/04-compiler-and-api/01-svelte-compiler.md index 42e6668ee2..326ddeb2b4 100644 --- a/site/content/docs/04-compiler-and-api/01-svelte-compiler.md +++ b/site/content/docs/04-compiler-and-api/01-svelte-compiler.md @@ -13,6 +13,15 @@ Nonetheless, it's useful to understand how to use the compiler, since bundler pl This is where the magic happens. `svelte.compile` takes your component source code, and turns it into a JavaScript module that exports a class. ```js +// @filename: ambient.d.ts +declare global { + var source: string +} + +export {} + +// @filename: index.ts +// ---cut--- import { compile } from 'svelte/compiler'; const result = compile(source, { @@ -74,7 +83,17 @@ The following options can be passed to the compiler. None are required: The returned `result` object contains the code for your component, along with useful bits of metadata. -```js +```ts +// @filename: ambient.d.ts +declare global { + const source: string; +} + +export {}; + +// @filename: main.ts +import { compile } from 'svelte/compiler'; +// ---cut--- const { js, css, ast, warnings, vars, stats } = compile(source); ``` @@ -143,6 +162,15 @@ compiled: { The `parse` function parses a component, returning only its abstract syntax tree. Unlike compiling with the `generate: false` option, this will not perform any validation or other analysis of the component beyond parsing it. Note that the returned AST is not considered public API, so breaking changes could occur at any point in time. ```js +// @filename: ambient.d.ts +declare global { + var source: string; +} + +export {}; + +// @filename: main.ts +// ---cut--- import { parse } from 'svelte/compiler'; const ast = parse(source, { filename: 'App.svelte' }); @@ -167,6 +195,15 @@ The `markup` function receives the entire component source text, along with the > Preprocessor functions should additionally return a `map` object alongside `code` and `dependencies`, where `map` is a sourcemap representing the transformation. ```js +// @filename: ambient.d.ts +declare global { + var source: string; +} + +export {}; + +// @filename: main.ts +// ---cut--- import { preprocess } from 'svelte/compiler'; import MagicString from 'magic-string'; @@ -196,10 +233,21 @@ The `script` and `style` functions receive the contents of ` + + +
+
+ {@html html} +
+
+ + diff --git a/sites/svelte.dev/src/lib/utils/hovers.js b/sites/svelte.dev/src/lib/utils/hovers.js new file mode 100644 index 0000000000..f0a079f2a5 --- /dev/null +++ b/sites/svelte.dev/src/lib/utils/hovers.js @@ -0,0 +1,60 @@ +import { onMount } from 'svelte'; +import Tooltip from './Tooltip.svelte'; + +export function setup() { + onMount(() => { + let tooltip; + let timeout; + + function over(event) { + if (event.target.tagName === 'DATA-LSP') { + clearTimeout(timeout); + + if (!tooltip) { + tooltip = new Tooltip({ + target: document.body + }); + + tooltip.$on('mouseenter', () => { + clearTimeout(timeout); + }); + + tooltip.$on('mouseleave', () => { + clearTimeout(timeout); + tooltip.$destroy(); + tooltip = null; + }); + } + + const rect = event.target.getBoundingClientRect(); + const html = event.target.getAttribute('lsp'); + + const x = (rect.left + rect.right) / 2 + window.scrollX; + const y = rect.top + window.scrollY; + + tooltip.$set({ + html, + x, + y + }); + } + } + + function out(event) { + if (event.target.tagName === 'DATA-LSP') { + timeout = setTimeout(() => { + tooltip.$destroy(); + tooltip = null; + }, 200); + } + } + + window.addEventListener('mouseover', over); + window.addEventListener('mouseout', out); + + return () => { + window.removeEventListener('mouseover', over); + window.removeEventListener('mouseout', out); + }; + }); +} diff --git a/sites/svelte.dev/src/routes/docs/[slug]/+page.svelte b/sites/svelte.dev/src/routes/docs/[slug]/+page.svelte index f5088ff43e..fd8ea6431b 100644 --- a/sites/svelte.dev/src/routes/docs/[slug]/+page.svelte +++ b/sites/svelte.dev/src/routes/docs/[slug]/+page.svelte @@ -1,15 +1,75 @@ - {data.page.title} - Svelte + {data.page.title} • Docs • SvelteKit + + + +
{@html data.page.content}
+
+
+ previous + {#if prev} + {prev.title} + {/if} +
+ +
+ next + {#if next} + {next.title} + {/if} +
+
+ + +