marko 5.22.6 → 5.22.8

package/dist/core-tags/core/await/index.marko

@@ -1,10 +1,10 @@
 /**
  * @template T
  * @typedef {{
- *   value?: readonly [T];
- *   then?: { renderBody: Marko.Body<[Awaited<T>], void> };
- *   catch?: { renderBody: Marko.Body<[unknown], void> };
- *   placeholder?: { renderBody: Marko.Body<[], void> };
+ *   value: readonly [T];
+ *   then?: { renderBody: Marko.Body<[Awaited<T>]> };
+ *   catch?: { renderBody: Marko.Body<[unknown]> };
+ *   placeholder?: { renderBody: Marko.Body };
  *   "client-reorder"?: boolean;
  *   name?: string;
  *   timeout?: number;

package/docs/icons/js.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 630 630">
+<rect width="630" height="630" fill="#f7df1e"/>
+<path d="m423.2 492.19c12.69 20.72 29.2 35.95 58.4 35.95 24.53 0 40.2-12.26 40.2-29.2 0-20.3-16.1-27.49-43.1-39.3l-14.8-6.35c-42.72-18.2-71.1-41-71.1-89.2 0-44.4 33.83-78.2 86.7-78.2 37.64 0 64.7 13.1 84.2 47.4l-46.1 29.6c-10.15-18.2-21.1-25.37-38.1-25.37-17.34 0-28.33 11-28.33 25.37 0 17.76 11 24.95 36.4 35.95l14.8 6.34c50.3 21.57 78.7 43.56 78.7 93 0 53.3-41.87 82.5-98.1 82.5-54.98 0-90.5-26.2-107.88-60.54zm-209.13 5.13c9.3 16.5 17.76 30.45 38.1 30.45 19.45 0 31.72-7.61 31.72-37.2v-201.3h59.2v202.1c0 61.3-35.94 89.2-88.4 89.2-47.4 0-74.85-24.53-88.81-54.075z"/>
+</svg>

package/docs/icons/marko.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" viewBox="0 0 2560 1400"><path fill="url(#a)" d="M427 0h361L361 697l427 697H427L0 698z"/><linearGradient id="a" x2="0" y2="1"><stop offset="0" stop-color="hsl(181, 96.3%, 38.8%)"/><stop offset=".25" stop-color="hsl(186, 94.9%, 46.1%)"/><stop offset=".5" stop-color="hsl(191, 93.3%, 60.8%)"/><stop offset=".5" stop-color="hsl(195, 94.3%, 50.8%)"/><stop offset=".75" stop-color="hsl(199, 95.9%, 48.0%)"/><stop offset="1" stop-color="hsl(203, 94.9%, 38.6%)"/></linearGradient><path fill="url(#b)" d="M854 697h361L788 0H427z"/><linearGradient id="b" x2="0" y2="1"><stop offset="0" stop-color="hsl(170, 80.3%, 50.8%)"/><stop offset=".5" stop-color="hsl(161, 79.1%, 47.3%)"/><stop offset="1" stop-color="hsl(157, 78.1%, 38.9%)"/></linearGradient><path fill="url(#c)" d="M1281 0h361l-427 697H854z"/><linearGradient id="c" x2="0" y2="1"><stop offset="0" stop-color="hsl(86, 95.9%, 37.1%)"/><stop offset=".5" stop-color="hsl(86, 91.9%, 45.0%)"/><stop offset="1" stop-color="hsl(90, 82.1%, 51.2%)"/></linearGradient><path fill="url(#d)" d="M1642 0h-361l428 697-428 697h361l428-697z"/><linearGradient id="d" x2="0" y2="1"><stop offset="0" stop-color="hsl(55, 99.9%, 53.1%)"/><stop offset=".25" stop-color="hsl(51, 99.9%, 50.0%)"/><stop offset=".5" stop-color="hsl(47, 99.2%, 49.8%)"/><stop offset=".5" stop-color="hsl(39, 99.9%, 50.0%)"/><stop offset=".75" stop-color="hsl(35, 99.9%, 50.0%)"/><stop offset="1" stop-color="hsl(29, 99.9%, 46.9%)"/></linearGradient><path fill="url(#e)" d="M2132 0h-361l427 697-428 697h361l428-697z"/><linearGradient id="e" x2="0" y2="1"><stop offset="0" stop-color="hsl(352, 99.9%, 62.9%)"/><stop offset=".25" stop-color="hsl(345, 90.3%, 51.8%)"/><stop offset=".5" stop-color="hsl(341, 88.3%, 51.8%)"/><stop offset=".5" stop-color="hsl(336, 80.9%, 45.4%)"/><stop offset=".75" stop-color="hsl(332, 80.3%, 44.8%)"/><stop offset="1.1" stop-color="hsl(328, 78.1%, 35.9%)"/></linearGradient></svg>

package/docs/icons/ts.svg

@@ -0,0 +1 @@
+<svg fill="none" height="512" viewBox="0 0 512 512" width="512" xmlns="http://www.w3.org/2000/svg"><rect fill="#3178c6" height="512" rx="50" width="512"/><rect fill="#3178c6" height="512" rx="50" width="512"/><path clip-rule="evenodd" d="m316.939 407.424v50.061c8.138 4.172 17.763 7.3 28.875 9.386s22.823 3.129 35.135 3.129c11.999 0 23.397-1.147 34.196-3.442 10.799-2.294 20.268-6.075 28.406-11.342 8.138-5.266 14.581-12.15 19.328-20.65s7.121-19.007 7.121-31.522c0-9.074-1.356-17.026-4.069-23.857s-6.625-12.906-11.738-18.225c-5.112-5.319-11.242-10.091-18.389-14.315s-15.207-8.213-24.18-11.967c-6.573-2.712-12.468-5.345-17.685-7.9-5.217-2.556-9.651-5.163-13.303-7.822-3.652-2.66-6.469-5.476-8.451-8.448-1.982-2.973-2.974-6.336-2.974-10.091 0-3.441.887-6.544 2.661-9.308s4.278-5.136 7.512-7.118c3.235-1.981 7.199-3.52 11.894-4.615 4.696-1.095 9.912-1.642 15.651-1.642 4.173 0 8.581.313 13.224.938 4.643.626 9.312 1.591 14.008 2.894 4.695 1.304 9.259 2.947 13.694 4.928 4.434 1.982 8.529 4.276 12.285 6.884v-46.776c-7.616-2.92-15.937-5.084-24.962-6.492s-19.381-2.112-31.066-2.112c-11.895 0-23.163 1.278-33.805 3.833s-20.006 6.544-28.093 11.967c-8.086 5.424-14.476 12.333-19.171 20.729-4.695 8.395-7.043 18.433-7.043 30.114 0 14.914 4.304 27.638 12.912 38.172 8.607 10.533 21.675 19.45 39.204 26.751 6.886 2.816 13.303 5.579 19.25 8.291s11.086 5.528 15.415 8.448c4.33 2.92 7.747 6.101 10.252 9.543 2.504 3.441 3.756 7.352 3.756 11.733 0 3.233-.783 6.231-2.348 8.995s-3.939 5.162-7.121 7.196-7.147 3.624-11.894 4.771c-4.748 1.148-10.303 1.721-16.668 1.721-10.851 0-21.597-1.903-32.24-5.71-10.642-3.806-20.502-9.516-29.579-17.13zm-84.159-123.342h64.22v-41.082h-179v41.082h63.906v182.918h50.874z" fill="#fff" fill-rule="evenodd"/></svg>

package/docs/structure.json

@@ -10,6 +10,7 @@
       "Styles",
       "Events",
       "Body content",
+      "TypeScript",
       "Marko 5 upgrade",
       "Troubleshooting Streaming"
     ]

package/docs/typescript.md

@@ -0,0 +1,359 @@
+# TypeScript in Marko
+
+> **Note:** Types are supported in Marko v5.22.7+ and Marko v4.24.6+
+
+Marko’s TypeScript support offers in-editor error checking, makes refactoring less scary, verifies that data matches expectations, and even helps with API design.
+
+Or maybe you just want more autocomplete in VSCode. That works too.
+
+## Enabling TypeScript in your Marko project
+
+There are two (non-exclusive) ways to add TypeScript to a Marko project:
+
+- **For sites and web apps**, you can place [a `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) at the project root:
+  <pre>
+  📁 components/
+  📁 node_modules/
+  <img src="./icons/marko.svg" width=16> index.marko
+  📦 package.json
+  <mark><img src="./icons/ts.svg" width=16> tsconfig.json</mark>
+  </pre>
+- **If you’re [publishing packages of Marko tags](https://markojs.com/docs/custom-tags/#publishing-tags-to-npm)**, add the following to [your `marko.json`](https://markojs.com/docs/marko-json/):
+  ```json
+  "script-lang": "ts"
+  ```
+  This will automatically expose type-checking and autocomplete for the published tags.
+
+> **ProTip**: You can also use the `script-lang` method for sites and apps.
+
+## Typing a tag's `input`
+
+A `.marko` file will use any exported `Input` type for [that file’s `input` object](https://markojs.com/docs/class-components/#input).
+
+This can be `export type Input` or `export interface Input`.
+
+### Example
+
+_PriceField.marko_
+
+```marko
+export interface Input {
+  currency: string;
+  amount: number;
+}
+
+<label>
+  Price in ${input.currency}:
+  <input type="number" value=input.amount min=0 step=0.01>
+</label>
+```
+
+You can also import, reuse, and extend `Input` interfaces from other `.marko` or `.ts` files:
+
+```marko
+import { Input as PriceInput } from "<PriceField>";
+import { ExtraTypes } from "lib/utils.ts";
+export type Input = { ...PriceInput, ...ExtraTypes };
+```
+
+```marko
+import { Input as PriceInput } from "<PriceField>";
+export interface Input extends PriceInput {
+  discounted: boolean;
+  expiresAt: Date;
+};
+```
+
+### Generic `Input`s
+
+[Generic Types and Type Parameters](https://www.typescriptlang.org/docs/handbook/2/generics.html) on `Input` are recognized throughout the entire `.marko` template (excluding [static statements](https://markojs.com/docs/syntax/#static-javascript)).
+
+For example, if you set up a component like this:
+
+_components/my-select.marko_
+
+```marko
+export interface Input<T> {
+  options: T[];
+  onSelect: (newVal: T) => unknown;
+}
+
+static function staticFn() {
+  // can NOT use `T` here
+}
+
+$ const instanceFn = (val: T) => {
+  // can use `T` here
+}
+
+// can use `as T` here
+<select on-input(evt => input.onSelect(options[evt.target.value] as T))>
+  <for|value, i| of=input.options>
+    <option value=i>${value}</option>
+  </for>
+</select>
+```
+
+…then your editor will figure out the types of inputs to that component:
+
+```marko
+<my-select options=[1,2,3] onSelect=val => {}/>
+                                 // ^^^ number
+
+<my-select options=["M","K","O"] onSelect=val => {}/>
+                                       // ^^^ string
+```
+
+## Built-in Marko Types
+
+Marko exposes [type definitions](https://github.com/marko-js/marko/blob/main/packages/marko/index.d.ts) you can reuse in [a TypeScript namespace](https://www.typescriptlang.org/docs/handbook/namespaces.html) called `Marko`:
+
+- **`Marko.Template<Input, Return>`**
+  - The type of a `.marko` file
+  - `typeof import("./template.marko")`
+- **`Marko.TemplateInput<Input>`**
+  - The object accepted by the render methods of a template. It includes the template's `Input` as well as `$global` values.
+- **`Marko.Body<Params, Return>`**
+  - The type of the [body content](https://markojs.com/docs/body-content/) of a tag (`renderBody`)
+- **`Marko.Component<Input, State>`**
+  - The base class for a [class component](https://markojs.com/docs/class-components/)
+- **`Marko.Renderable`**
+  - Values accepted by the [`<${dynamic}/>` tag](https://markojs.com/docs/syntax/#dynamic-tagname)
+  - `string | Marko.Template | Marko.Body | { renderBody: Marko.Body}`
+- **`Marko.Out`**
+  - The render context with methods like `write`, `beginAsync`, etc.
+  - `ReturnType<template.render>`
+- **`Marko.Global`**
+  - The type of the object on `out.global` that can be passed to a template's render methods as the `$global` property
+- **`Marko.RenderResult`**
+  - The [result](https://markojs.com/docs/rendering/#renderresult) of rendering a Marko template
+  - `ReturnType<template.renderSync>`
+  - `Awaited<ReturnType<template.render>>`
+- **`Marko.Emitter`**
+  - `EventEmitter` from `@types/node`
+- **`Marko.NativeTags`**
+  - `Marko.NativeTags`: An object containing all native tags and their types
+- **`Marko.NativeTagInput<TagName>`** and **`Marko.NativeTagReturn<TagName>`**
+  - Helpers to extract the input and return types for the specified `keyof Marko.NativeTag`
+- **`Marko.BodyParameters<Body>`** and **`Marko.BodyReturnType<Body>`**
+  - Helpers to extract the parameters and return types from the specified `Marko.Body`
+- **`Marko.Repeated<T>`** and **`Marko.Repeatable<T>`**
+  - Used to represent types for attributes tags which can have one or many instances
+  - `Marko.Repeated<T>`: `[T, T, ...T[]]` (array with at least two items)
+  - `Marko.Repeatable<T>`: `T | Marko.Repeated<T>`
+
+### Typing `renderBody`
+
+The most commonly used type from the `Marko` namespace is `Marko.Body` which can be used to type `input.renderBody`:
+
+_child.marko_
+
+```marko
+export interface Input {
+  renderBody?: Marko.Body;
+}
+```
+
+Here, the following will be acceptable values:
+
+_index.marko_
+
+```marko
+<child/>
+<child>Text in render body</child>
+<child>
+  <div>Any combination of components</div>
+</child>
+```
+
+Passing other values (including components) will cause a type error:
+
+_index.marko_
+
+```marko
+import OtherTag from "<other-tag>";
+<child renderBody=OtherTag/>
+```
+
+### Typing Tag Parameters
+
+Tag parameters are passed to the `renderBody` by the child tag. For this reason, `Marko.Body` also allows typing of its parameters:
+
+_for-by-two.marko_
+
+```marko
+export interface Input {
+  to: number;
+  renderBody: Marko.Body<[number]>
+}
+
+<for|i| from=0 to=input.to by=2>
+  <${input.renderBody}(i)/>
+</for>
+```
+
+_index.marko_
+
+```marko
+<for-by-two|i| to=10>
+  <div>${i}</div>
+</for-by-two>
+```
+
+### Extending a native tag type
+
+The types for native tags are accessed via the global `Marko.NativeTags` type. Here's an example of a component that adds a feature to the `button` element:
+
+_color-button.marko_
+
+```marko
+export interface Input extends Marko.NativeTagInput<"button"> {
+  color: string;
+  renderBody?: Marko.Body;
+}
+
+$ const { color, renderBody, ...restOfInput } = input;
+
+<button style=`color: ${color}` ...restOfInput>
+  <${renderBody}/>
+</button>
+```
+
+## TypeScript Syntax in `.marko`
+
+Any [JavaScript expression in Marko](https://markojs.com/docs/syntax/#inline-javascript) can also be written as a TypeScript expression.
+
+### Tag Type Parameters
+
+```marko
+<child <T>|value: T|>
+  ...
+</child>
+```
+
+### Tag Type Arguments
+
+_components/child.marko_
+
+```marko
+export interface Input<T> {
+  value: T;
+}
+```
+
+_index.marko_
+
+```marko
+// number would be inferred in this case, but we can be explicit
+<child<number> value=1 />
+```
+
+### Method Shorthand Type Parameters
+
+```marko
+<child process<T>() { /* ... */ } />
+```
+
+### Attribute Type Assertions
+
+The types of attribute values can _usually_ be inferred. When needed, you can assert values to be more specific with [TypeScript’s `as` keyword](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#type-assertions):
+
+```marko
+<some-component
+  number=1 as const
+  names=[] as string[]
+/>
+```
+
+# JSDoc Support
+
+For existing projects that want to incrementally add type safety, adding full TypeScript support is a big leap. This is why Marko also includes full support for [incremental typing via JSDoc](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html).
+
+## Setup
+
+You can enable type checking in an existing `.marko` file by adding a `// @ts-check` comment at the top:
+
+```js
+// @ts-check
+```
+
+If you want to enable type checking for all Marko & JavaScript files in a JavaScript project, you can switch to using a [`jsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html#using-tsconfigjson-or-jsconfigjson). You can skip checking some files by adding a `// @ts-nocheck` comment to files.
+
+Once that has been enabled, you can start by typing the input with JSDoc. Here's an example component with typed `input`:
+
+```marko
+// @ts-check
+
+/**
+ * @typedef {{
+ *   firstName: string,
+ *   lastName: string,
+ * }} Input
+ */
+
+<div>${firstName} ${lastName}</div>
+```
+
+## With a separate `component.js` file
+
+Many components in existing projects adhere to the following structure:
+
+<pre>
+📁 components/
+  📁 color-rotate-button/
+    <img src="./icons/marko.svg" width=16> index.marko
+    <img src="./icons/js.svg" width=16> component.js
+</pre>
+
+The `color-rotate-button` takes a list of colors and moves to the next one each time the button is clicked:
+
+```marko
+<color-rotate-button colors=["red", "blue", "yellow"]>
+  Next Color
+</color-rotate-button>
+```
+
+Here is an example of how this `color-rotate-button` component could be typed:
+
+_components/color-rotate-button/component.js_
+
+```js
+// @ts-check
+
+/**
+ * @typedef {{
+ *   colors: string[],
+ *   renderBody: Marko.Renderable
+ * }} Input
+ * @typedef {{
+ *   colorIndex: number
+ * }} State
+ * @extends {Marko.Component<Input, State>}
+ */
+export default class extends Marko.Component {
+  onCreate() {
+    this.state = {
+      colorIndex: 0
+    };
+  }
+
+  rotateColor() {
+    this.state.colorIndex =
+      (this.state.colorIndex + 1) % this.input.colors.length;
+  }
+}
+```
+
+_components/color-rotate-button/index.marko_
+
+```marko
+// @ts-check
+
+/* Input will be automatically imported from `component.js`! */
+
+<button
+  onClick('rotateColor')
+  style=`color: ${input.colors[state.colorIndex]}`>
+  <${input.renderBody}/>
+</button>
+```

package/index.d.ts

@@ -11,7 +11,14 @@ declare namespace NodeJS {
 declare namespace Marko {
   /** A mutable global object for the current render. */
   export interface Global {
+    /** A list of globals that should be serialized to the browser. */
     serializedGlobals?: Record<string, boolean>;
+    /** A CSP Nonce to add to each script output from Marko. */
+    cspNonce?: string;
+    /** Used to uniquely identify a instance of a Marko runtime. */
+    runtimeId?: string;
+    /** Used for rendering multiple Marko templates in a single hydrated page. */
+    componentIdPrefix?: string;
     [attr: PropertyKey]: unknown;
   }
 
@@ -211,7 +218,10 @@ declare namespace Marko {
   }
 
   /** The top level api for a Marko Template. */
-  export abstract class Template {
+  export abstract class Template<
+    Input = { [attr: PropertyKey]: any },
+    Return = unknown
+  > {
     /** Creates a Marko compatible output stream. */
     createOut(): Out;
 
@@ -228,7 +238,7 @@ declare namespace Marko {
     /** @marko-overload-start */
     /** Asynchronously render the template. */
     abstract render(
-      input: Marko.TemplateInput,
+      input: Marko.TemplateInput<Input>,
       stream?: {
         write: (chunk: string) => void;
         end: (chunk?: string) => void;
@@ -237,15 +247,15 @@ declare namespace Marko {
 
     /** Synchronously render the template. */
     abstract renderSync(
-      input: Marko.TemplateInput
+      input: Marko.TemplateInput<Input>
     ): Marko.RenderResult<Marko.Component>;
 
     /** Synchronously render a template to a string. */
-    abstract renderToString(input: Marko.TemplateInput): string;
+    abstract renderToString(input: Marko.TemplateInput<Input>): string;
 
     /** Render a template and return a stream.Readable in nodejs or a ReadableStream in a web worker environment. */
     abstract stream(
-      input: Marko.TemplateInput
+      input: Marko.TemplateInput<Input>
     ): ReadableStream<string> & NodeJS.ReadableStream;
     /** @marko-overload-end */
   }
@@ -303,7 +313,6 @@ declare namespace Marko {
 
   export type Repeated<T> = [T, T, ...T[]];
   export type Repeatable<T> = T | Repeated<T>;
-  export type MaybeRepeatable<T> = undefined | Repeatable<T>;
 
   export interface NativeTags {
     [name: string]: {
@@ -311,4 +320,9 @@ declare namespace Marko {
       return: unknown;
     };
   }
+
+  export type NativeTagInput<Name extends keyof NativeTags> =
+    NativeTags[Name]["input"];
+  export type NativeTagReturn<Name extends keyof NativeTags> =
+    NativeTags[Name]["return"];
 }

package/package.json

@@ -1,11 +1,11 @@
 {
     "name": "marko",
-    "version": "5.22.6",
+    "version": "5.22.8",
     "license": "MIT",
     "description": "UI Components + streaming, async, high performance, HTML templating for Node.js and the browser.",
     "dependencies": {
-        "@marko/compiler": "^5.23.5",
-        "@marko/translator-default": "^5.22.5",
+        "@marko/compiler": "^5.23.6",
+        "@marko/translator-default": "^5.22.6",
         "app-module-path": "^2.2.0",
         "argly": "^1.2.0",
         "browser-refresh-client": "1.1.4",

package/src/core-tags/core/await/index.marko

@@ -1,10 +1,10 @@
 /**
  * @template T
  * @typedef {{
- *   value?: readonly [T];
- *   then?: { renderBody: Marko.Body<[Awaited<T>], void> };
- *   catch?: { renderBody: Marko.Body<[unknown], void> };
- *   placeholder?: { renderBody: Marko.Body<[], void> };
+ *   value: readonly [T];
+ *   then?: { renderBody: Marko.Body<[Awaited<T>]> };
+ *   catch?: { renderBody: Marko.Body<[unknown]> };
+ *   placeholder?: { renderBody: Marko.Body };
  *   "client-reorder"?: boolean;
  *   name?: string;
  *   timeout?: number;