From a07eac432af686e3f3f127d25f07ef274c54bb40 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Fri, 29 Mar 2019 21:49:31 -0400 Subject: [PATCH] update API reference docs (#2206) --- site/content/docs/00-introduction.md | 9 + site/content/docs/01-component-format.md | 193 ++++ site/content/docs/02-template-syntax.md | 1000 +++++++++++++++++ site/content/docs/03-run-time.md | 550 +++++++++ site/content/docs/04-compile-time.md | 291 +++++ .../_old_docs}/02-template-syntax.md | 0 .../_old_docs}/03-scoped-styles.md | 0 .../{guide => docs/_old_docs}/04-behaviour.md | 0 .../_old_docs}/05-nested-components.md | 0 .../_old_docs}/06-special-components.md | 0 .../{guide => docs/_old_docs}/07-events.md | 0 .../{guide => docs/_old_docs}/08-bindings.md | 0 .../_old_docs}/09-transitions.md | 0 .../{guide => docs/_old_docs}/10-actions.md | 0 .../{guide => docs/_old_docs}/11-classes.md | 0 .../_old_docs}/14-module-context.md | 0 .../_old_docs}/15-server-side-rendering.md | 0 .../_old_docs}/16-state-management.md | 0 .../_old_docs}/17-preprocessing.md | 0 .../{guide => docs/_old_docs}/18-advanced.md | 0 .../_old_docs}/19-custom-elements.md | 0 .../_old_docs}/20-miscellaneous.md | 0 .../_old_docs}/98-api-reference.md | 0 .../_old_docs}/99-still-to-come.md | 0 site/content/guide/0-important-note.md | 7 - site/content/guide/00-introduction.md | 112 -- site/src/routes/about.svelte | 7 - .../blog/[slug].js => blog/[slug].json.js} | 0 site/src/routes/blog/[slug].svelte | 2 +- site/src/routes/{api => }/blog/_posts.js | 2 +- .../{api/blog/index.js => blog/index.json.js} | 0 site/src/routes/blog/index.svelte | 2 +- site/src/routes/blog/rss.xml.js | 2 +- site/src/routes/docs/_GuideContents.svelte | 38 +- site/src/routes/docs/_sections.js | 80 +- site/src/routes/docs/demo/[hash].json.js | 22 - site/src/routes/docs/index.svelte | 98 +- site/static/global.css | 2 +- site/static/prism.css | 2 +- site/static/repl-viewer.css | 2 +- src/compile/index.ts | 2 +- .../action-custom-event-handler/expected.js | 6 +- test/js/samples/action/expected.js | 6 +- test/js/samples/bind-online/expected.js | 6 +- test/js/samples/bind-width-height/expected.js | 6 +- .../expected.js | 6 +- .../component-static-array/expected.js | 6 +- .../component-static-immutable/expected.js | 6 +- .../component-static-immutable2/expected.js | 6 +- test/js/samples/component-static/expected.js | 6 +- .../samples/computed-collapsed-if/expected.js | 6 +- test/js/samples/css-media-query/expected.js | 6 +- .../css-shadow-dom-keyframes/expected.js | 6 +- test/js/samples/debug-empty/expected.js | 10 +- .../debug-foo-bar-baz-things/expected.js | 28 +- test/js/samples/debug-foo/expected.js | 16 +- test/js/samples/debug-ssr-foo/expected.js | 4 +- .../samples/deconflict-builtins/expected.js | 6 +- .../js/samples/deconflict-globals/expected.js | 6 +- .../expected.js | 10 +- test/js/samples/do-use-dataset/expected.js | 6 +- .../samples/dont-invalidate-this/expected.js | 6 +- .../dont-use-dataset-in-legacy/expected.js | 6 +- .../dont-use-dataset-in-svg/expected.js | 6 +- test/js/samples/dynamic-import/expected.js | 6 +- .../each-block-array-literal/expected.js | 6 +- .../each-block-changed-check/expected.js | 6 +- .../each-block-keyed-animated/expected.js | 6 +- test/js/samples/each-block-keyed/expected.js | 6 +- .../event-handler-no-passive/expected.js | 6 +- test/js/samples/event-modifiers/expected.js | 6 +- .../js/samples/head-no-whitespace/expected.js | 6 +- test/js/samples/hoisted-const/expected.js | 6 +- test/js/samples/hoisted-let/expected.js | 6 +- .../js/samples/if-block-no-update/expected.js | 6 +- test/js/samples/if-block-simple/expected.js | 6 +- .../expected.js | 6 +- .../inline-style-optimized-url/expected.js | 6 +- .../inline-style-optimized/expected.js | 6 +- .../inline-style-unoptimized/expected.js | 6 +- test/js/samples/input-files/expected.js | 6 +- test/js/samples/input-range/expected.js | 6 +- .../input-without-blowback-guard/expected.js | 6 +- .../expected.js | 6 +- .../expected.js | 6 +- .../expected.js | 6 +- .../expected.js | 6 +- test/js/samples/legacy-input-type/expected.js | 6 +- test/js/samples/media-bindings/expected.js | 6 +- .../non-imported-component/expected.js | 6 +- .../samples/non-mutable-reference/expected.js | 6 +- .../expected.js | 6 +- .../expected.js | 6 +- .../samples/select-dynamic-value/expected.js | 6 +- test/js/samples/setup-method/expected.js | 6 +- .../samples/ssr-no-oncreate-etc/expected.js | 4 +- .../samples/ssr-preserve-comments/expected.js | 4 +- test/js/samples/svg-title/expected.js | 6 +- test/js/samples/title/expected.js | 6 +- test/js/samples/transition-local/expected.js | 6 +- .../use-elements-as-anchors/expected.js | 6 +- .../samples/window-binding-scroll/expected.js | 6 +- 102 files changed, 2364 insertions(+), 459 deletions(-) create mode 100644 site/content/docs/00-introduction.md create mode 100644 site/content/docs/01-component-format.md create mode 100644 site/content/docs/02-template-syntax.md create mode 100644 site/content/docs/03-run-time.md create mode 100644 site/content/docs/04-compile-time.md rename site/content/{guide => docs/_old_docs}/02-template-syntax.md (100%) rename site/content/{guide => docs/_old_docs}/03-scoped-styles.md (100%) rename site/content/{guide => docs/_old_docs}/04-behaviour.md (100%) rename site/content/{guide => docs/_old_docs}/05-nested-components.md (100%) rename site/content/{guide => docs/_old_docs}/06-special-components.md (100%) rename site/content/{guide => docs/_old_docs}/07-events.md (100%) rename site/content/{guide => docs/_old_docs}/08-bindings.md (100%) rename site/content/{guide => docs/_old_docs}/09-transitions.md (100%) rename site/content/{guide => docs/_old_docs}/10-actions.md (100%) rename site/content/{guide => docs/_old_docs}/11-classes.md (100%) rename site/content/{guide => docs/_old_docs}/14-module-context.md (100%) rename site/content/{guide => docs/_old_docs}/15-server-side-rendering.md (100%) rename site/content/{guide => docs/_old_docs}/16-state-management.md (100%) rename site/content/{guide => docs/_old_docs}/17-preprocessing.md (100%) rename site/content/{guide => docs/_old_docs}/18-advanced.md (100%) rename site/content/{guide => docs/_old_docs}/19-custom-elements.md (100%) rename site/content/{guide => docs/_old_docs}/20-miscellaneous.md (100%) rename site/content/{guide => docs/_old_docs}/98-api-reference.md (100%) rename site/content/{guide => docs/_old_docs}/99-still-to-come.md (100%) delete mode 100644 site/content/guide/0-important-note.md delete mode 100644 site/content/guide/00-introduction.md delete mode 100644 site/src/routes/about.svelte rename site/src/routes/{api/blog/[slug].js => blog/[slug].json.js} (100%) rename site/src/routes/{api => }/blog/_posts.js (93%) rename site/src/routes/{api/blog/index.js => blog/index.json.js} (100%) delete mode 100644 site/src/routes/docs/demo/[hash].json.js diff --git a/site/content/docs/00-introduction.md b/site/content/docs/00-introduction.md new file mode 100644 index 0000000000..4730a0c1d5 --- /dev/null +++ b/site/content/docs/00-introduction.md @@ -0,0 +1,9 @@ +--- +title: Before we begin +--- + +> Temporary note: This document is a work-in-progress. Please forgive any missing or misleading parts, and don't be shy about asking for help in the [Discord chatroom](https://discord.gg/yy75DKs). The [tutorial](tutorial) is more complete; start there. + +This page contains detailed API reference documentation. It's intended to be a resource for people who already have some familiarity with Svelte. + +If that's not you (yet), you may prefer to visit the [interactive tutorial](tutorial) or the [examples](examples) before consulting this reference. diff --git a/site/content/docs/01-component-format.md b/site/content/docs/01-component-format.md new file mode 100644 index 0000000000..f001fee6aa --- /dev/null +++ b/site/content/docs/01-component-format.md @@ -0,0 +1,193 @@ +--- +title: Component format +--- + +--- + +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. + +```html + + + + + +``` + +### <script> + +A ` +``` + +#### 2. Assignments are 'reactive' + +--- + +To change component state and trigger a re-render, just assign to a locally declared variable. + +Update expressions (`count += 1`) and property assignments (`obj.x = y`) have the same effect. + +```html + +``` + +#### 3. `$:` marks a statement as reactive + +--- + +Any top-level statement (i.e. not inside a block or a function) can be made reactive by prefixing it with the `$:` label. Reactive statements run immediately before the component updates, whenever the values that they depend on have changed. + +```html + +``` + +--- + +If a statement consists entirely of an assignment to an undeclared variable, Svelte will inject a `let` declaration on your behalf. + +```html + +``` + +#### 4. Prefix stores with `$` to access their values + +--- + +Any time you have a reference to a store, you can access its value inside a component by prefixing it with the `$` character. This causes Svelte to declare the prefixed variable, and set up a store subscription that will be unsubscribed when appropriate. + +Note that the store must be declared at the top level of the component — not inside an `if` block or a function, for example. + +Local variables (that do not represent store values) must *not* have a `$` prefix. + +```html + +``` + + +### <script context="module"> + +--- + +A ` + + +``` + + +### <style> + +--- + +CSS inside a ` +``` + +--- + +To apply styles to a selector globally, use the `:global(...)` modifier. + +```html + +``` \ No newline at end of file diff --git a/site/content/docs/02-template-syntax.md b/site/content/docs/02-template-syntax.md new file mode 100644 index 0000000000..8778694789 --- /dev/null +++ b/site/content/docs/02-template-syntax.md @@ -0,0 +1,1000 @@ +--- +title: Template syntax +--- + + +### Tags + +--- + +A lowercase tag, like `
`, denotes a regular HTML element. A capitalised tag, such as ``, indicates a *component*. + +```html + + +
+ +
+``` + + +### Attributes + +--- + +By default, attributes work exactly like their HTML counterparts. + +```html +
+ +
+``` + +--- + +As in HTML, values may be unquoted. + +```html + +``` + +--- + +Attribute values can contain JavaScript expressions. + +```html +page {p} +``` + +--- + +Or they can *be* JavaScript expressions. + +```html + +``` + +--- + +An expression might include characters that would cause syntax highlighting to fail in regular HTML, so quoting the value is permitted. The quotes do not affect how the value is parsed: + +```html + +``` + +--- + +When the attribute name and value match (`name={name}`), they can be replaced with `{name}`. + +```html + + + +``` + +--- + +*Spread attributes* allow many attributes or properties to be passed to an element or component at once. + +An element or component can have multiple spread attributes, interspersed with regular ones. + +```html + +``` + + +### Text expressions + +* `{expression}` + +--- + +Text can also contain JavaScript expressions: + +```html +

Hello {name}!

+

{a} + {b} = {a + b}.

+``` + + +### HTML expressions + +* `{@html expression}` + +--- + +In a text expression, characters like `<` and `>` are escaped. With HTML expressions, they're not. + +> Svelte does not sanitize expressions before injecting HTML. If the data comes from an untrusted source, you must sanitize it, or you are exposing your users to an XSS vulnerability. + +```html +
+

{post.title}

+ {@html post.content} +
+``` + + +### If blocks + +* `{#if expression}...{/if}` +* `{#if expression}...{:else if expression}...{/if}` +* `{#if expression}...{:else}...{/if}` + +--- + +Content that is conditionally rendered can be wrapped in an if block. + +```html +{#if answer === 42} +

what was the question?

+{/if} +``` + +--- + +Additional conditions can be added with `{:else if expression}`, optionally ending in an `{:else}` clause. + +```html +{#if porridge.temperature > 100} +

too hot!

+{:else if 80 > porridge.temperature} +

too cold!

+{:else} +

just right!

+{/if} +``` + + +### Each blocks + +* `{#each expression as name}...{/each}` +* `{#each expression as name, index}...{/each}` +* `{#each expression as name, index (key)}...{/each}` +* `{#each expression as name}...{:else}...{/each}` + +--- + +Iterating over lists of values can be done with an each block. + +```html +

Shopping list

+
    + {#each items as item} +
  • {item.name} x {item.qty}
  • + {/each} +
+``` + +--- + +An each block can also specify an *index*, equivalent to the second argument in an `array.map(...)` callback: + +```html +{#each items as item, i} +
  • {i + 1}: {item.name} x {item.qty}
  • +{/each} +``` + +--- + +If a *key* expression is provided — which must uniquely identify each list item — Svelte will use it to diff the list when data changes, rather than adding or removing items at the end. + +```html +{#each items as item, i (item.id)} +
  • {i + 1}: {item.name} x {item.qty}
  • +{/each} +``` + +--- + +You can freely use destructuring patterns in each blocks. + +```html +{#each items as { id, name, qty }, i (id)} +
  • {i + 1}: {name} x {qty}
  • +{/each} +``` + +--- + +An each block can also have an `{:else}` clause, which is rendered if the list is empty. + +```html +{#each todos as todo} +

    {todo.text}

    +{:else} +

    No tasks today!

    +{/each} +``` + + +### Await blocks + +* `{#await expression}...{:then name}...{:catch name}...{/await}` +* `{#await expression}...{:then name}...{/await}` +* `{#await expression then name}...{/await}` + +--- + +Await blocks allow you to branch on the three possible states of a Promise — pending, fulfilled or rejected. + +```html +{#await promise} + +

    waiting for the promise to resolve...

    +{:then value} + +

    The value is {value}

    +{:catch error} + +

    Something went wrong: {error.message}

    +{/await} +``` + +--- + +The `catch` block can be omitted if you don't need to render anything when the promise rejects (or no error is possible). + +```html +{#await promise} + +

    waiting for the promise to resolve...

    +{:then value} + +

    The value is {value}

    +{/await} +``` + +--- + +If you don't care about the pending state, you can also omit the initial block. + +```html +{#await promise then value} +

    The value is {value}

    +{/await} +``` + + +### DOM events + +* `on:eventname={handler}` +* `on:eventname|modifiers={handler}` + +--- + +Use the `on:` directive to listen to DOM events. + +```html + + + +``` + +--- + +Handlers can be declared inline with no performance penalty. As with attributes, directive values may be quoted for the sake of syntax highlighters. + +```html + +``` + +--- + +Add *modifiers* to DOM events with the `|` character. + +The following modifiers are available: + +* `preventDefault` — calls `event.preventDefault()` before running the handler +* `stopPropagation` — calls `event.stopPropagation()`, preventing the event reaching the next element +* `passive` — improves scrolling performance on touch/wheel events (Svelte will add it automatically where it's safe to do so) +* `capture` — fires the handler during the *capture* phase instead of the *bubbling* phase +* `once` — remove the handler after the first time it runs + +Modifiers can be chained together, e.g. `on:click|once|capture={...}`. + +```html +
    + +
    +``` + +--- + +If the `on:` directive is used without a value, the component will *forward* the event, meaning that a consumer of the component can listen for it. + +```html + +``` + + +### Component events + +* `on:eventname={handler}` + +--- + +Components can emit events using [createEventDispatcher](#docs/createEventDispatcher), or by forwarding DOM events. Listening for component events looks the same as listening for DOM events: + +```html + +``` + + + +### Element bindings + +* `bind:property={value}` + +--- + +Data ordinarily flows down, from parent to child. The `bind:` directive allows data to flow the other way, from child to parent. Most bindings are specific to particular elements. + +The simplest bindings reflect the value of a property, such as `input.value`. + +```html + + + + +``` + +--- + +If the name matches the value, you can use a shorthand. + +```html + + + +``` + +--- + +Numeric input values are coerced; even though `input.value` is a string as far as the DOM is concerned, Svelte will treat it as a number. If the input is empty or invalid (in the case of `type="number"`), the value is `undefined`. + +```html + + +``` + +--- + +Inputs that work together can use `bind:group`. + +```html + + + + + + + + + + + + +``` + +--- + +A ` + + + + +``` + +--- + +A ` + + + + + +``` + +--- + +When the value of an `