From 3d8c7b16072374ad2f0a23504cbe006e41a8acfd Mon Sep 17 00:00:00 2001 From: Simon Holthausen Date: Wed, 11 Sep 2024 23:12:44 +0200 Subject: [PATCH] feat: legacy notes + checkbox This adds a note variant, which can be enabled using !LEGACY as the first text. It adds a blockquote using the "deprecated API" look. Additionally, a checkbox is added to the bottom (where the TS toggle was previously) to optionally disable those contents. The idea is to add legacy syntax inline into the documentation at the appropriate places using these notes, and devs can hide those when unchecking the checkbox. The "Reactivity Fundamentals" page shows how this would look like. --- .../03-reactivity-fundamentals.md | 56 +++++++++++++++++++ apps/svelte.dev/src/app.html | 12 ++-- .../src/routes/docs/[...path]/+layout.svelte | 2 +- .../site-kit/src/lib/docs/DocsContents.svelte | 18 +++--- .../site-kit/src/lib/docs/LegacyToggle.svelte | 38 +++++++++++++ .../site-kit/src/lib/docs/TSToggle.svelte | 48 ---------------- .../site-kit/src/lib/docs/TsJsSelect.svelte | 2 +- packages/site-kit/src/lib/docs/index.ts | 2 +- packages/site-kit/src/lib/markdown/utils.ts | 5 ++ packages/site-kit/src/lib/styles/text.css | 9 ++- 10 files changed, 123 insertions(+), 69 deletions(-) create mode 100644 packages/site-kit/src/lib/docs/LegacyToggle.svelte delete mode 100644 packages/site-kit/src/lib/docs/TSToggle.svelte diff --git a/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md b/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md index 0f1c8e0799..f5ec471cb5 100644 --- a/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md +++ b/apps/svelte.dev/content/docs/svelte/01-introduction/03-reactivity-fundamentals.md @@ -40,6 +40,19 @@ class Todo { } ``` +> !LEGACY +> In Svelte 4, state was implicitly reactive if the variable was declared at the top level +> +> ```svelte +> +> +> +> ``` + ## `$derived` Derived state is declared with the `$derived` rune: @@ -61,6 +74,24 @@ The expression inside `$derived(...)` should be free of side-effects. Svelte wil As with `$state`, you can mark class fields as `$derived`. +> !LEGACY +> In Svelte 4, you could use reactive statements for this. +> +> ```svelte +> +> +> +> +>

{count} doubled is {doubled}

+> ``` +> +> This only worked at the top level of a component. + ## `$effect` To run _side-effects_ when the component is mounted to the DOM, and when values change, we can use the `$effect` rune ([demo](/#H4sIAAAAAAAAE31T24rbMBD9lUG7kAQ2sbdlX7xOYNk_aB_rQhRpbAsU2UiTW0P-vbrYubSlYGzmzMzROTPymdVKo2PFjzMzfIusYB99z14YnfoQuD1qQh-7bmdFQEonrOppVZmKNBI49QthCc-OOOH0LZ-9jxnR6c7eUpOnuv6KeT5JFdcqbvbcBcgDz1jXKGg6ncFyBedYR6IzLrAZwiN5vtSxaJA-EzadfJEjKw11C6GR22-BLH8B_wxdByWpvUYtqqal2XB6RVkG1CoHB6U1WJzbnYFDiwb3aGEdDa3Bm1oH12sQLTcNPp7r56m_00mHocSG97_zd7ICUXonA5fwKbPbkE2ZtMJGGVkEdctzQi4QzSwr9prnFYNk5hpmqVuqPQjNnfOJoMF22lUsrq_UfIN6lfSVyvQ7grB3X2mjMZYO3XO9w-U5iLx42qg29md3BP_ni5P4gy9ikTBlHxjLzAtPDlyYZmRdjAbGq7HprEQ7p64v4LU_guu0kvAkhBim3nMplWl8FreQD-CW20aZR0wq12t-KqDWeBywhvexKC3memmDwlHAv9q4Vo2ZK8KtK0CgX7u9J8wXbzdKv-nRnfF_2baTqlYoWUF2h5efl9-n0O6koAMAAA==)): @@ -86,3 +117,28 @@ To run _side-effects_ when the component is mounted to the DOM, and when values ``` The function passed to `$effect` will run when the component mounts, and will re-run after any changes to the values it reads that were declared with `$state` or `$derived` (including those passed in with `$props`). Re-runs are batched (i.e. changing `color` and `size` in the same moment won't cause two separate runs), and happen after any DOM updates have been applied. + +> !LEGACY +> In Svelte 4, you could use reactive statements for this. +> +> ```svelte +> +> +> +> ``` +> +> This only worked at the top level of a component. diff --git a/apps/svelte.dev/src/app.html b/apps/svelte.dev/src/app.html index 14594cf757..140f9b79a6 100644 --- a/apps/svelte.dev/src/app.html +++ b/apps/svelte.dev/src/app.html @@ -20,16 +20,16 @@ diff --git a/apps/svelte.dev/src/routes/docs/[...path]/+layout.svelte b/apps/svelte.dev/src/routes/docs/[...path]/+layout.svelte index ea6ef38404..9e71cddc16 100644 --- a/apps/svelte.dev/src/routes/docs/[...path]/+layout.svelte +++ b/apps/svelte.dev/src/routes/docs/[...path]/+layout.svelte @@ -30,7 +30,7 @@ .container { --sidebar-menu-width: 28rem; --sidebar-width: var(--sidebar-menu-width); - --ts-toggle-height: 4.2rem; + --legacy-toggle-height: 4.2rem; display: flex; flex-direction: column; diff --git a/packages/site-kit/src/lib/docs/DocsContents.svelte b/packages/site-kit/src/lib/docs/DocsContents.svelte index c6e789492f..f5b05b622f 100644 --- a/packages/site-kit/src/lib/docs/DocsContents.svelte +++ b/packages/site-kit/src/lib/docs/DocsContents.svelte @@ -1,6 +1,6 @@ -{#if show_ts_toggle} -
- -
-{/if} +
+ +
diff --git a/packages/site-kit/src/lib/docs/TSToggle.svelte b/packages/site-kit/src/lib/docs/TSToggle.svelte deleted file mode 100644 index 1945bd7e18..0000000000 --- a/packages/site-kit/src/lib/docs/TSToggle.svelte +++ /dev/null @@ -1,48 +0,0 @@ - - -
- - - -
- - diff --git a/packages/site-kit/src/lib/docs/TsJsSelect.svelte b/packages/site-kit/src/lib/docs/TsJsSelect.svelte index fd29ff5ddf..15b2ee6053 100644 --- a/packages/site-kit/src/lib/docs/TsJsSelect.svelte +++ b/packages/site-kit/src/lib/docs/TsJsSelect.svelte @@ -7,7 +7,7 @@ if (browser) { prefers_ts.subscribe((ts) => { - document.body.classList.toggle('prefers-ts', ts); + document.body.classList.toggle('prefers-js', !ts); }); } diff --git a/packages/site-kit/src/lib/docs/index.ts b/packages/site-kit/src/lib/docs/index.ts index f1377163bb..2b933680bc 100644 --- a/packages/site-kit/src/lib/docs/index.ts +++ b/packages/site-kit/src/lib/docs/index.ts @@ -1,4 +1,4 @@ export { default as DocsContents } from './DocsContents.svelte'; export { default as DocsOnThisPage } from './DocsOnThisPage.svelte'; -export { default as TSToggle } from './TSToggle.svelte'; +export { default as LegacyToggle } from './LegacyToggle.svelte'; export { setupDocsHovers } from './hover'; diff --git a/packages/site-kit/src/lib/markdown/utils.ts b/packages/site-kit/src/lib/markdown/utils.ts index 25cbb98c6b..f17d3fc02f 100644 --- a/packages/site-kit/src/lib/markdown/utils.ts +++ b/packages/site-kit/src/lib/markdown/utils.ts @@ -100,6 +100,11 @@ const default_renderer: Partial = { }, blockquote(quote) { + if (quote.startsWith('

!LEGACY')) { + quote = quote.replace('

!LEGACY', '

'); + return '

\n' + quote + '
\n'; + } + return '
\n' + quote + '
\n'; }, diff --git a/packages/site-kit/src/lib/styles/text.css b/packages/site-kit/src/lib/styles/text.css index 8756bd5609..a4d675b30f 100644 --- a/packages/site-kit/src/lib/styles/text.css +++ b/packages/site-kit/src/lib/styles/text.css @@ -324,7 +324,7 @@ margin-bottom: 0; } -.text :where(blockquote.deprecated) { +.text :where(blockquote.deprecated, blockquote.legacy) { --primary-hsl: var(--sk-text-warning-hsl); --color: var(--primary-hsl); } @@ -333,10 +333,15 @@ content: 'Deprecated'; } -.text :where(blockquote.deprecated a) { +.text :where(blockquote.deprecated a), +.text :where(blockquote.legacy a) { --color: var(--primary-hsl); } +.text :where(blockquote.legacy)::before { + content: 'In Svelte 4 / Legacy mode'; +} + .text :where(section a code) { color: inherit; }