marko 5.37.0 → 6.0.0-3.4

package/docs/redux.md

@@ -1,61 +0,0 @@
-# Redux + Marko
-
-See the [`marko-redux` sample project](https://github.com/marko-js/examples/tree/master/examples/redux) for a fully-working example.
-
-## Installation
-
-First, save the [`marko`](https://www.npmjs.com/package/marko) and [`redux`](https://www.npmjs.com/package/redux) packages to your project’s dependencies:
-
-```bash
-npm i marko redux
-```
-
-## Usage
-
-The partial code below shows how a Marko UI component can connect to a Redux store, using Redux’s `store.subscribe()` method and Marko’s `forceUpdate()` method:
-
-### `counter.marko`
-
-```marko
-import store from './store.js';
-
-class {
-  onMount () {
-    store.subscribe(() => {
-      // Force this UI component to rerender
-      this.forceUpdate();
-
-      // The UI component will rerender with the new
-      // state returned by `store.getState()`
-      //
-      // You could also force an update like this:
-      // this.input = store.getState();
-    });
-  }
-}
-
-<counter(store.getState()) />
-```
-
-### `reducer.js`
-
-```js
-export default function (state, action) {
-  state = state || { value: 0 };
-
-  // Additional reducer logic here…
-
-  return state;
-}
-```
-
-### `store.js`
-
-In `counter.marko`, the imported store module exports a Redux store created with the following code:
-
-```js
-import redux from "redux";
-import counter from "./reducer.js";
-
-export default redux.createStore(counter);
-```

package/docs/rendering.md

@@ -1,268 +0,0 @@
-# Rendering
-
-To render a Marko view, you need to `import` it.
-
-_example.js_
-
-```js
-import FancyButton from "./components/fancy-button.marko";
-```
-
-> **Note:** If you are targeting node.js, you will need to enable the [require extension](./installing.md#require-marko-views) in order to require `.marko` files or you will need to precompile all of your templates using [Marko CLI](https://github.com/marko-js/cli). If you are targeting the browser, you will need to use a bundler like [`lasso`](./lasso.md), [`webpack`](./webpack.md) or [`rollup`](./rollup.md).
-
-Once you have a view, you can pass input data and render it:
-
-_example.js_
-
-```js
-import FancyButton from "./components/fancy-button.marko";
-const html = FancyButton.renderToString({ label: "Click me!" });
-
-console.log(html);
-```
-
-The data passed to `renderToString` becomes available as `input` in the component, so if `fancy-button.marko` looked like this:
-
-_./components/fancy-button.marko_
-
-```marko
-<button>${input.label}</button>
-```
-
-The output HTML would be:
-
-```html
-<button>Click me!</button>
-```
-
-## Rendering methods
-
-We used the `renderToString` method above to render the view, but there are a number of different method signatures that can be used to render.
-
-Many of these methods return a [`RenderResult`](#renderresult) which is an object with helper methods for working with the rendered output.
-
-### `renderSync(input)`
-
-| params       | type                            | description                            |
-| ------------ | ------------------------------- | -------------------------------------- |
-| `input`      | `Object`                        | the input data used to render the view |
-| return value | [`RenderResult`](#renderresult) | The result of the render               |
-
-Using `renderSync` forces the render to complete synchronously. If a tag attempts to run asynchronously, an error will be thrown.
-
-```js
-import View from "./view.marko";
-var result = View.renderSync({});
-
-result.appendTo(document.body);
-```
-
-### `render(input)`
-
-| params       | type                             | description                            |
-| ------------ | -------------------------------- | -------------------------------------- |
-| `input`      | `Object`                         | the input data used to render the view |
-| return value | `AsyncStream`/`AsyncVDOMBuilder` | the async `out` render target          |
-
-The `render` method returns an async `out` which is used to generate HTML on the server or a virtual DOM in the browser. In either case, the async `out` has a `then` method that follows the Promises/A+ spec, so it can be used as if it were a Promise. This promise resolves to a [`RenderResult`](#renderresult).
-
-```js
-import View from "./view.marko";
-var resultPromise = View.render({});
-
-resultPromise.then((result) => {
-  result.appendTo(document.body);
-});
-```
-
-### `render(input, callback)`
-
-| params         | type                             | description                                    |
-| -------------- | -------------------------------- | ---------------------------------------------- |
-| `input`        | `Object`                         | the input data used to render the view         |
-| `callback`     | `Function`                       | a function to call when the render is complete |
-| callback value | [`RenderResult`](#renderresult)  | The result of the render                       |
-| return value   | `AsyncStream`/`AsyncVDOMBuilder` | the async `out` render target                  |
-
-```js
-import View from "./view.marko";
-
-View.render({}, (err, result) => {
-  result.appendTo(document.body);
-});
-```
-
-### `render(input, stream)`
-
-| params       | type                             | description                            |
-| ------------ | -------------------------------- | -------------------------------------- |
-| `input`      | `Object`                         | the input data used to render the view |
-| `stream`     | `WritableStream`                 | a writeable stream                     |
-| return value | `AsyncStream`/`AsyncVDOMBuilder` | the async `out` render target          |
-
-The HTML output is written to the passed `stream`.
-
-```js
-import http from "http";
-import View from "./view.marko";
-
-http.createServer((req, res) => {
-  res.setHeader("content-type", "text/html");
-  View.render({}, res);
-});
-```
-
-### `render(input, out)`
-
-| params       | type                             | description                            |
-| ------------ | -------------------------------- | -------------------------------------- |
-| `input`      | `Object`                         | the input data used to render the view |
-| `out`        | `AsyncStream`/`AsyncVDOMBuilder` | The async `out` to render to           |
-| return value | `AsyncStream`/`AsyncVDOMBuilder` | The `out` that was passed              |
-
-The `render` method also allows passing an existing async `out`. If you do this, `render` will not automatically end the async `out` (this allows rendering a view in the middle of another view). If the async `out` won't be ended by other means, you are responsible for ending it.
-
-```js
-import View from "./view.marko";
-var out = View.createOut();
-
-View.render({}, out);
-
-out.on("finish", () => {
-  console.log(out.getOutput());
-});
-
-out.end();
-```
-
-### `renderToString(input)`
-
-| params       | type     | description                            |
-| ------------ | -------- | -------------------------------------- |
-| `input`      | `Object` | the input data used to render the view |
-| return value | `String` | The HTML string produced by the render |
-
-Returns an HTML string and forces the render to complete synchronously. If a tag attempts to run asynchronously, an error will be thrown.
-
-```js
-import View from "./view.marko";
-var html = View.renderToString({});
-
-document.body.innerHTML = html;
-```
-
-### `renderToString(input, callback)`
-
-| params         | type        | description                            |
-| -------------- | ----------- | -------------------------------------- |
-| `input`        | `Object`    | the input data used to render the view |
-| callback value | `String`    | The HTML string produced by the render |
-| return value   | `undefined` | N/A                                    |
-
-An HTML string is passed to the callback.
-
-```js
-import View from "./view.marko";
-
-View.renderToString({}, (err, html) => {
-  document.body.innerHTML = html;
-});
-```
-
-### `stream(input)`
-
-The `stream` method returns a Node.js-style stream of the output HTML.
-
-```js
-import fs from "fs";
-import View from "./view.marko";
-const writeStream = fs.createWriteStream("output.html");
-
-View.stream({}).pipe(writeStream);
-```
-
-This method is available on the server, but not available by default in the browser. If you need to use streams in the browser, you may `import 'marko/stream'` as part of your client-side bundle.
-
-## RenderResult
-
-### `getComponent()`
-
-### `getComponents(selector)`
-
-### `afterInsert(doc)`
-
-### `getNode(doc)`
-
-### `getOutput()`
-
-### `appendTo(targetEl)`
-
-### `insertAfter(targetEl)`
-
-### `insertBefore(targetEl)`
-
-### `prependTo(targetEl)`
-
-### `replace(targetEl)`
-
-### `replaceChildrenOf(targetEl)`
-
-## Global data
-
-If you need to make data available to all rendered views, use the `$global` property on the input data object. This property will be removed from `input` and provided to the template through a variable called `$global`. It is also made available on the `out.global` property.
-
-Global values persist across renders.
-
-```js
-View.render({
-  $global: {
-    flags: ["mobile"],
-  },
-});
-```
-
-Within the template you can access `$global` similar to accessing `input`.
-
-```marko
-<div>
-  You are on ${$global.flags.includes("mobile") ? "mobile" : "desktop"}
-</div>
-```
-
-> **Note:** `$global` is not available within [`static`](./syntax.md#static-javascript) parts of the template. In order to reference `$global` within the component class you must use `out.global` from one of the lifecycle methods that provide it.
-
-> **Warning:** Use `$global` with caution; it is visible in any component.
-
-### Sending global data to browsers
-
-⚠️ To prevent accidentally exposing sensitive data, by default **no keys** in `$global` are sent to browsers. To serialize data to the frontend, name the desired properties in `$global.serializedGlobals`.
-
-Values must be serializable by [the `warp10` module](https://www.npmjs.com/package/warp10).
-
-```js
-import Page from "./index.marko";
-
-app.get("/", (req, res) => {
-  const ua = req.get("User-Agent");
-
-  Page.render(
-    {
-      $global: {
-        isIos: /iPad|iPhone/.test(ua), // Serialized and available on the server and browser as `$global.isIos`
-        isAndroid: /Android/.test(ua), // Serialized and available on the server and browser as `$global.isAndroid`
-        req, // Only available server-side and not serialized, because it’s not in `serializedGlobals`
-
-        serializedGlobals: {
-          isIos: true, // Tell Marko to serialize `isIos`
-          isAndroid: true, // Tell Marko to serialize `isAndroid`
-        },
-      },
-    },
-    res,
-  );
-});
-```
-
-> **Warning:** Ensure that you serialize only data which is necessary for the browser. Serialization is expensive for both server rendering performance and HTML output size.
-
-For details, check [#672: “Serialize only input and state on top-level server-rendered UI components”](https://github.com/marko-js/marko/pull/672).

package/docs/rollup.md

@@ -1,352 +0,0 @@
-# Marko + Rollup
-
-This is Marko’s official integration plugin for [the Rollup bundler](https://rollupjs.org/).
-
-## Installation
-
-```sh
-npm install --save-dev \
-  @marko/rollup \
-  rollup \
-  @rollup/plugin-node-resolve \
-  @rollup/plugin-commonjs
-```
-
-> **Note**: The Marko runtime is CommonJS, so don’t forget the `@rollup/plugin-commonjs` package!
-
-## Configuration
-
-`@marko/rollup` exports two methods for use in [Rollup configuration files](https://rollupjs.org/guide/en/#configuration-files): `.browser()` and `.server()`.
-
-You _probably_ want to use both, since that’ll get you…
-
-- Automatic [`input` entrypoint configuration](https://rollupjs.org/guide/en/#input) for route-based bundle splitting
-- Complete control over asset loading with [the `<rollup>` tag](#rollup-tag)
-- The strengths behind why Marko exists in the first place: cooperation between servers and browsers for high performance in both
-
-> **ProTip**: You _could_ use only `.browser()` or only `.server()` to build a completely client-side-rendered or server-side-rendered app. That would be a little odd, but you could.
-
-### Config example
-
-```js
-import nodeResolve from "@rollup/plugin-node-resolve";
-import commonjs from "@rollup/plugin-commonjs";
-import marko from "@marko/rollup";
-
-const sharedPlugins = [
-  commonjs({
-    extensions: [".js", ".marko"]
-  }),
-  // If using Marko’s `style {}` blocks, you’ll need an appropriate plugin, like npmjs.com/rollup-plugin-postcss
-  postcss({ external: true })
-]
-
-const serverAssetsConfig = {
-  input: "src/start-server.js",
-  plugins: [
-    marko.server(),
-    nodeResolve({ preferBuiltins: true })
-    ...sharedPlugins
-  ]
-};
-const browsersAssetsConfig = {
-  plugins: [
-    marko.browser(),
-    nodeResolve({ browser: true })
-    ...sharedPlugins
-  ]
-};
-
-export default [serverAssetsConfig, browsersAssetsConfig];
-```
-
-### Advanced config example
-
-The following configuration file is long and hairy, which may be upsetting to some viewers. However, it does show how to accomplish the following:
-
-- Support for Rollup’s watch mode
-- A bundle analyzer
-- The ability to `import` JSON files to use their data
-- The ability to `import` image files to use their asset URLs for `img[src]` and such
-- Dead-code elimination for development-only code
-- Static compression of assets for something like [NGiNX’s `gzip_static`](https://nginx.org/en/docs/http/ngx_http_gzip_static_module.html)
-- A CSS preprocessor (Sass, in this case)
-- Browserslist to automatically configure:
-  - Babel for JS transpilation
-  - Autoprefixer for CSS transpilation
-
-<details><summary>Big ugly production-esque Rollup config</summary>
-
-```js
-import { builtinModules } from "module";
-import path from "path";
-import autoprefixer from "autoprefixer";
-import babelPlugin from "@rollup/plugin-babel";
-import commonjsPlugin from "@rollup/plugin-commonjs";
-import jsonPlugin from "@rollup/plugin-json";
-import markoPlugin from "@marko/rollup";
-import nodeResolvePlugin from "@rollup/plugin-node-resolve";
-import replacePlugin from "@rollup/plugin-replace";
-import runPlugin from "@rollup/plugin-run";
-import stylesPlugin from "rollup-plugin-styles";
-import urlPlugin from "@rollup/plugin-url";
-import pkg from "./package.json";
-
-const __DEV__ = process.env.NODE_ENV === "development";
-const __PROD__ = !__DEV__;
-
-const isWatch = Boolean(process.env.ROLLUP_WATCH);
-
-const publicPath = "/s/"; // Guess what character is only 5 bits under HPACK
-const assetFileNames = "[name]-[hash][extname]";
-
-const externalDependencies = [
-  ...Object.keys(pkg.dependencies),
-  ...builtinModules,
-];
-
-process.env.SASS_PATH = "./:./node_modules";
-
-export default (async () => [
-  compiler("server", {
-    input: "index.js",
-    output: {
-      dir: "built/server/",
-      assetFileNames: `../browser/${assetFileNames}`,
-      format: "cjs",
-      sourcemap: true,
-    },
-    external: (id) =>
-      externalDependencies.some(
-        (dependency) => id === dependency || id.startsWith(dependency + "/"),
-      ),
-    plugins: [isWatch && runPlugin({ execArgv: ["--enable-source-maps"] })],
-  }),
-
-  compiler("browser", {
-    output: {
-      dir: "built/browser/",
-      chunkFileNames: __PROD__ ? "[name]-[hash].js" : null,
-      entryFileNames: __PROD__ ? "[name]-[hash].js" : null,
-      assetFileNames,
-      sourcemap: true,
-      sourcemapExcludeSources: __PROD__,
-    },
-    plugins: [
-      stylesPlugin({
-        mode: "extract",
-        sourceMap: true,
-        config: {
-          target: "browserslist:css",
-          plugins: [autoprefixer({ env: "css" })],
-        },
-        minimize: __PROD__,
-        url: {
-          publicPath,
-          hash: assetFileNames,
-        },
-      }),
-      __PROD__ && (await import("rollup-plugin-terser")).terser(),
-      __PROD__ &&
-        (await import("rollup-plugin-gzip")).default({
-          filter: /\.(?:js|css|svg|json|xml|txt)$/,
-          minSize: 1024,
-          gzipOptions: {
-            level: 9,
-            memLevel: 9,
-          },
-        }),
-      __PROD__ &&
-        !isWatch &&
-        (await import("rollup-plugin-visualizer")).default(),
-      __PROD__ &&
-        !isWatch && {
-          name: "bundle-visualizer-location",
-          writeBundle() {
-            console.info(
-              `📊 Bundle visualizer at \x1b[4;36mfile://${path.join(
-                __dirname,
-                "../../",
-                bundleAnalyzerFilename,
-              )}\x1b[0m`,
-            );
-          },
-        },
-    ],
-  }),
-])();
-
-function compiler(target, config) {
-  const isBrowser = target === "browser";
-  const browserslistEnv = isBrowser ? "js" : "server";
-  const babelConfig = {
-    comments: false,
-    browserslistEnv,
-    compact: false,
-    babelrc: false,
-    caller: { target },
-  };
-  if (isBrowser) {
-    babelConfig.presets = [
-      [
-        "@babel/preset-env",
-        {
-          browserslistEnv,
-          bugfixes: true,
-        },
-      ],
-    ];
-  }
-
-  return {
-    ...config,
-    preserveEntrySignatures: false,
-    plugins: [
-      markoPlugin[target]({ babelConfig }),
-      nodeResolvePlugin({
-        browser: isBrowser,
-        preferBuiltins: !isBrowser,
-      }),
-      commonjsPlugin(),
-      replacePlugin({
-        preventAssignment: true,
-        values: { __DEV__, __PROD__ },
-      }),
-      babelPlugin({
-        babelHelpers: "bundled",
-        ...babelConfig,
-      }),
-      jsonPlugin(),
-      urlPlugin({
-        publicPath,
-        destDir: "built/browser/",
-        fileName: assetFileNames,
-        include: "**/*.{svg,png,jpg,jpeg}",
-        limit: 0, // Never Base64 & inline
-        emitFiles: !isBrowser,
-      }),
-      ...config.plugins,
-    ],
-  };
-}
-```
-
-</details>
-
-## `<rollup>` tag
-
-Using both `.server()` and `.browser()` enables **the `<rollup>` tag**, which gives you complete control over how your app loads assets. That lets you do things like:
-
-- [Critical CSS](https://web.dev/extract-critical-css/) for components as they write out within a kB budget, or [as components first appear on the page](https://jakearchibald.com/2016/link-in-body/#a-simpler-better-way), or any other style-loading mad science
-- [`module`/`nomodule` scripts](https://philipwalton.com/articles/using-native-javascript-modules-in-production-today/) for smaller bundles in modern browsers
-- [Content-Security Policy `nonce`s](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) or [Subresource `integrity` hashes](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity)
-- Anything a web page can do, really. You can even combine `<rollup>` with [the `serialize` option](#options.serialize) to be as fancy as you wanna be.
-
-The `<rollup>` tag provides two [tag parameters](https://markojs.com/docs/syntax/#parameters):
-
-1. `entry` is the generated `input` string that the `server` plugin gave to the `browser` plugin. You can use it to find the corresponding entry chunk from Rollup’s `output` (the next parameter).
-
-2. `output` is an array of `AssetInfo | ChunkInfo` objects with most of [the data returned from Rollup's `generateBundle` hook](https://rollupjs.org/guide/en/#generatebundle). Some properties are omitted, like `code` and `map`, since they’re often too large to inline directly. However, each chunk also has a `size` property, to let you filter out empty chunks, inline code yourself below a certain size, or other delightful devilishness.
-
-For example, using the `entry` name and properties of `output` items to load scripts:
-
-```marko
-<head>
-  <rollup|entry, output|>
-    $ const entryChunk = output.find(chunk => chunk.name === entry);
-
-    <if(entryChunk.size /* only load non-empty JS entry points */)>
-      <for|fileName| of=entryChunk.imports>
-        <link rel="modulepreload" href=fileName />
-      </for>
-
-      <script async type="module" src=entryChunk.fileName></script>
-    </if>
-  </rollup>
-</head>
-```
-
-> **Note**: It’s up to you to transform the chunk data (also called the **manifest**) into `<link>`s, `<script>`s, and other HTML to load assets. Opting into complete control means we can’t do any of it for you.
-
-If your Rollup `browser` config contains multiple `output` options, or you have multiple `browser` configs, every `output`’s chunk is passed to the `<rollup>` tag.
-
-For example, if you have both `esm` and `iife` build outputs configured:
-
-```js
-{
-  output: [
-    { dir: "dist/iife", format: "iife" },
-    { dir: "dist/esm", format: "esm" },
-  ];
-}
-```
-
-…you could cross-reference assets from both…
-
-```marko
-<rollup|entry, iifeOutput, esmOutput|>
-  $ const iifeEntryChunk = iifeOutput.find(chunk => chunk.name === entry);
-  $ const esmEntryChunk = esmOutput.find(chunk => chunk.name === entry);
-
-  <script src=esmEntryChunk.fileName type="module" async></script>
-  <script src=iifeEntryChunk.fileName nomodule async></script>
-</rollup>
-```
-
-…and _boom:_ you now have [a `module`/`nomodule` setup](https://philipwalton.com/articles/using-native-javascript-modules-in-production-today/).
-
-## Options
-
-### `options.babelConfig`
-
-Both the `.server()` and `.browser()` plugins accept this option.
-
-You can manually override the builtin Babel configuration by passing a `babelConfig` object. By default, [Babel’s regular config file resolution](https://babeljs.io/docs/en/config-files) will be used.
-
-```js
-marko.browser({
-  babelConfig: {
-    presets: ["@babel/preset-env"],
-  },
-});
-```
-
-### `options.runtimeId`
-
-Both the `.server()` and `.browser()` plugins accept this option. In fact, you _really_ want to use it with both simultaneously.
-
-In some cases, you may want to embed multiple isolated copies of Marko on the page. (If you can’t think of why, then don’t worry about this option.)
-
-Since Marko uses some `window` properties to initialize, multiple instances can cause issues. For example, by default Marko checks `window.$components` for server-rendered hydration. Usually you can change these `window` properties by [rendering with `{ $global: { runtimeId: "MY_MARKO_RUNTIME_ID" } }` as input](https://markojs.com/docs/rendering/#global-data) on the server, but since `@marko/rollup` usually writes the autoinitialization code for you, instead this plugin exposes a `runtimeId` option to automatically set `$global.runtimeId` to initialize properly in the browser:
-
-```js
-const runtimeId = "MY_MARKO_RUNTIME_ID";
-// Make the `runtimeId` the same across `server` and `browser`, or it’ll error!
-marko.server({ runtimeId });
-marko.browser({ runtimeId });
-```
-
-### `options.serialize`
-
-This option is only available for the `.browser()` plugin. It lets you inspect and transform the `output` chunks before they’re passed to [the `<rollup>` tag](#rollup-tag).
-
-For example, if you _did_ want to include the `code` property from the Rollup chunk — say, to inline code small enough that it’s not worth the overhead of an HTTP request, you’d try something like the following:
-
-```js
-marko.browser({
-  serialize(output) {
-    return output.map(({ type, fileName, isEntry, code }) =>
-      type === "asset"
-        ? { type, fileName }
-        : {
-            type,
-            name,
-            isEntry,
-            fileName,
-            // only inline code chunks below 1kB
-            inline: code.trim().length < 1024 && code,
-          },
-    );
-  },
-});
-```