feat: v4.40 (#1568)

* chore:

* chore:

* chore:

* chore: slotAssignment and dev sourceMaps

---------

Co-authored-by: John Jenkins <john.jenkins@nanoporetech.com>

Author: johnjenkins

docs/components/component.md

@@ -184,7 +184,7 @@ export class TodoList {
 
 **Optional**
 
-**Type: `boolean | { delegatesFocus: boolean }`**
+**Type: `boolean | { delegatesFocus?: boolean, slotAssignment?: 'manual' | 'named' }`**
 
 **Default: `false`**
 
@@ -201,6 +201,10 @@ When `delegatesFocus` is `true` and a non-focusable part of the component is cli
 - the first focusable part of the component is given focus
 - the component receives any available `focus` styling
 
+When `slotAssignment` is set to `'manual'` or `'named'`, the component will have `slotAssignment` added to its shadow DOM.
+
+`slotAssignment: 'manual'` enables [manual slot assignment](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/slotAssignment) (otherwise known as [imperative slot assignment](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Imperative-Shadow-DOM-Distribution-API.md)) for the component.
+
 If `shadow` is set to `false`, the component will not use native shadow DOM encapsulation.
 
 This option cannot be set to enabled if `scoped` is enabled.

docs/components/reactive-data.md

@@ -16,7 +16,7 @@ When props or state change on a component, the [`render()` method](./templating-
 ## The Watch Decorator (`@Watch()`)
 
 `@Watch()` is a decorator that is applied to a method of a Stencil component.
-The decorator accepts a single argument, the name of a class member that is decorated with `@Prop()` or `@State()`, or
+The decorator's first required argument is the name of a class member that is decorated with `@Prop()` or `@State()`, or
 a host attribute. A method decorated with `@Watch()` will automatically run when its associated class member or attribute changes.
 
 ```tsx
@@ -52,22 +52,29 @@ export class LoadingIndicator {
   }
 
   @Watch('activated')
-  @Watch('busy')
+  @Watch('busy', {immediate: true})
   watchMultiple(newValue: boolean, oldValue: boolean, propName:string) {
     console.log(`The new value of ${propName} is: `, newValue);
   }
 }
 ```
 
-In the example above, there are two `@Watch()` decorators.
-One decorates `watchPropHandler`, which will fire when the class member `activated` changes.
-The other decorates `watchStateHandler`, which will fire when the class member `busy` changes.
+In the example above, there are four `@Watch()` decorators:
+- The first decorates `watchPropHandler`, which will fire when the class member `activated` changes.
+- The second decorates `watchStateHandler`, which will fire when the class member `busy` changes.
+- The third and fourth decorators both decorate `watchMultiple`, which will fire when either `activated` or `busy` change. 
+
+Passing `{immediate: true}` as the second argument to `@Watch()` causes the decorated 
+method to fire when the component initially loads, in addition to when the watched member changes.
 
 When fired, the decorated method will receive the old and new values of the prop/state.
 This is useful for validation or the handling of side effects.
 
 :::info
-The `@Watch()` decorator does not fire when a component initially loads.
+By default, the `@Watch()` decorator does not fire when a component initially loads.
+Use `@Watch('propName', {immediate: true})` to have the decorated method fire when the component first loads. 
+`immediate` watchers will be invoked before the component's first render, so be careful when trying to access DOM elements
+that may not yet be available.
 :::
 
 ### Watching Native HTML Attributes

docs/config/01-overview.md

@@ -406,13 +406,14 @@ Will generate the following comment:
 
 ## sourceMap
 
-*default: `true`*
+*default: `'dev'`*
 
-When omitted or set to `true`, sourcemaps will be generated for a project.
-When set to `false`, sourcemaps will not be generated.
+- Set to `true` to always generate source maps, 
+- Set to `false` to never generate source maps
+- Set to `'dev'` to only generate source maps during development (`--dev`) builds.
 
 ```tsx
-sourceMap: true | false
+sourceMap: true | false | 'dev'
 ```
 
 Sourcemaps create a translation between Stencil components that are written in TypeScript/JSX and the resulting 

versioned_docs/version-v4.40/build-variables.md

@@ -0,0 +1,48 @@
+---
+title: Build Constants
+description: Stencil has a number of add-ons that you can use with the build process.
+slug: /build-variables
+---
+
+# Build Constants
+
+Build Constants in Stencil allow you to run specific code only when Stencil is running in development mode. This code is stripped from your bundles when doing a production build, therefore keeping your bundles as small as possible.
+
+### Using Build Constants
+
+Lets dive in and look at an example of how to use our build constants:
+
+```tsx
+import { Component, Build } from '@stencil/core';
+
+@Component({
+  tag: 'stencil-app',
+  styleUrl: 'stencil-app.scss'
+})
+export class StencilApp {
+
+  componentDidLoad() {
+    if (Build.isDev) {
+      console.log('im in dev mode');
+    } else {
+      console.log('im running in production');
+    }
+
+    if (Build.isBrowser) {
+      console.log('im in the browser');
+    } else {
+      console.log('im in prerendering (server)');
+    }
+  }
+}
+```
+
+As you can see from this example, we just need to import `Build` from `@stencil/core` and then we can use the `isDev` constant to detect when we are running in dev mode or production mode.
+
+### Use Cases
+
+Some use cases we have come up with are:
+
+- Diagnostics code that runs in dev to make sure logic is working like you would expect
+- `console.log()`'s that may be useful for debugging in dev mode but that you don't want to ship
+- Disabling auth checks when in dev mode

versioned_docs/version-v4.40/components/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Components",
+  "position": 2
+}