marko 5.37.6 → 6.0.0-3.12

package/docs/installing.md

@@ -1,51 +0,0 @@
-# Installation
-
-## Trying out Marko
-
-If you just want to play around with Marko in the browser, head on over to our [Try Online](https://markojs.com/try-online) feature. You'll be able to develop a Marko application right in your browser.
-
-## Creating new apps (Recommended)
-
-If you're starting from scratch, you can use Marko's [CLI](https://github.com/marko-js/cli) commands to quickly create a starter app:
-
-```bash
-npm init marko
-```
-
-This will use an interactive [CLI](https://github.com/marko-js/cli) to automatically create a project for you using the pre-made starter template of your choosing. The `basic` template is the most minimal and the easiest way to get started. It uses our recommended app framework [Marko Run](https://github.com/marko-js/run) that handles building, bundling, and serving your web application. These projects are config-free with built-in file based routing and automatic code reloading.
-
-## Custom Bundling
-
-Marko relies on JavaScript bundlers to package your code on both the client and the server. This is because Marko's client and server bundling works closely together to optimize the smallest client bundles and handle shared assets properly.
-
-Using the CLI is still the easiest way to get started even when you want to get your hands dirty tweaking every last part of your config files. Marko currently supports Webpack, Lasso, and Rollup.
-
-### Webpack
-
-[Webpack Integration Docs](https://markojs.com/docs/webpack/)
-
-[Marko Webpack Plugin](https://github.com/marko-js/webpack)
-
-[Webpack Example](https://github.com/marko-js/examples/tree/master/examples/webpack-express)
-
-CLI Command: `npx @marko/create --template webpack-express`
-
-### Lasso
-
-[Lasso Integration Docs](https://markojs.com/docs/lasso/)
-
-[Marko Lasso Plugin](https://github.com/lasso-js/lasso-marko)
-
-[Lasso Example](https://github.com/marko-js/examples/tree/master/examples/lasso-express)
-
-CLI Command: `npx @marko/create --template lasso-express`
-
-### Rollup
-
-[Rollup Integration Docs](https://markojs.com/docs/rollup/)
-
-[Marko Rollup Plugin](https://github.com/marko-js/rollup)
-
-<!-- [Rollup Example](https://github.com/marko-js/examples/tree/master/examples/rollup)
-
-CLI Command: `npx @marko/create --template rollup` -->

package/docs/koa.md

@@ -1,35 +0,0 @@
-# Marko + Koa
-
-See the [the koa sample](https://github.com/marko-js/examples/tree/master/examples/vite-koa)
-project for a working example.
-
-## Installation
-
-```terminal
-npm install koa marko --save
-```
-
-## Usage
-
-```javascript
-import Koa from "koa";
-import Template from "./index.marko";
-
-const app = new Koa();
-
-app.use((ctx, next) => {
-  ctx.type = "html";
-  ctx.body = Template.stream({
-    name: "Frank",
-    count: 30,
-    colors: ["red", "green", "blue"],
-  });
-});
-
-app.listen(8080);
-```
-
-### BYOB (Bring your own bundler)
-
-For the large portion of Marko's API a bundler is required. The example code above assumes that Marko templates can be loaded in your environment.
-Marko supports a number of bundlers, [take a look through our supported bundlers](https://markojs.com/docs/bundler-integrations-overview/) and pick what works best for you.

package/docs/lasso.md

@@ -1,196 +0,0 @@
-# Marko + Lasso
-
-The [lasso-marko](https://github.com/lasso-js/lasso-marko) plugin for [Lasso.js](https://github.com/lasso-js/lasso) will automatically compile all imported Marko templates during bundling. In addition, the `lasso-marko` plugin will automatically bundle any template dependencies (including required CSS).
-
-Lasso.js provides Marko custom tags for injecting JavaScript and CSS bundles, images and other resources.
-
-The sample [lasso-express](https://github.com/marko-js/examples/tree/master/examples/lasso-express) app demonstrates how to build a production-ready web application using Marko and Lasso. Run `npx @marko/create --template lasso-express` to use this sample as a starting point for a new app.
-
-## Installation
-
-```
-npm install lasso-marko --save
-```
-
-## Registering the plugin
-
-```js
-require('lasso').configure({
-    "plugins": [
-        ...
-        "lasso-marko"
-    ]
-    ...
-});
-```
-
-## Lasso custom tags
-
-To inject the required JavaScript and CSS into the page you will want to use the `<lasso-page>`, `<lasso-head>` and `<lasso-body>` tags.
-
-If you are using lasso@^3 (latest), make sure to install the [lasso-marko-taglib](https://github.com/lasso-js/lasso-marko-taglib), so that you can use the lasso custom tags.
-
-```
-npm install lasso-marko
-npm install @lasso/marko-taglib
-```
-
-After installing, the lasso custom tags can be used in your templates:
-
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <title>Marko + Lasso</title>
-    <lasso-head />
-  </head>
-  <body>
-    <lasso-body />
-  </body>
-</html>
-```
-
-Lasso.js will automatically bundle up transitive dependencies by building and walking a dependency graph.
-
-## Client-side rendering
-
-Marko templates can be imported and rendered by any JavaScript module. The code below shows how to render a top-level UI component and have it be mounted to the DOM as a child `document.body`:
-
-_client.js_
-
-<!-- prettier-ignore -->
-```js
-require("./components/app/index.marko")
-  .renderSync({})
-  .appendTo(document.body);
-```
-
-When Lasso.js bundles up the code above it will automatically bundle up the required `./components/app/index.marko` file.
-
-## Server-side rendering
-
-If you are rendering the initial UI on the server then it is necessary to make sure that all UI components are bundled and sent to the browser so that UI components can be mounted in the browser. For example:
-
-_about-me/index.marko_
-
-```marko
-<!DOCTYPE html>
-<html lang="en">
-    <head>
-        <meta charset="UTF-8">
-        <title>Marko + Lasso</title>
-
-        <!-- CSS will be inserted here -->
-        <lasso-head/>
-    </head>
-    <body>
-        <!-- Top-level UI component: -->
-        <app/>
-
-        <!-- JS will be inserted here -->
-        <lasso-body/>
-    </body>
-</html>
-```
-
-## Browser refresh
-
-[browser-refresh](https://github.com/patrick-steele-idem/browser-refresh) is recommended in development for instant page refreshes and hot reloading of Marko templates, styles and other resources. `browser-refresh` works well with Lasso and Marko and is very easy to use as a drop-in replacement for `node`:
-
-```bash
-browser-refresh server.js
-```
-
-## Lasso package types commonly used with Marko
-
-For many use cases, the combination of `lasso-marko` and `@lasso/marko-taglib` is sufficient to render and bundle components without the need for explicit `browser.json` files. For more advanced use cases, the following bundle types may be defined in a `browser.json` for Lasso.
-
-#### `marko-dependencies` _(provided by `lasso-marko`)_
-
-Includes all the dependencies needed by template and the code to register all components that would be rendered by the template. It does not automatically initialize the component, so is most useful if you need to initialize components manually.
-
-```json
-{
-  "type": "marko-dependencies",
-  "path": "src/ui-modules/outdated-browser-banner/index.marko"
-}
-```
-
-**Note:** To initialize the server rendered components, there are 2 steps:
-
-**Step 1:** Manually _retrieve_ server rendered components, shipped via `marko-dependencies`.
-
-To retrieve the list of server rendered components, do:
-
-```javascript
-template.render(data, (err, output) => {
-  const renderedComponentsList =
-    require("marko/components").getRenderedComponents(output.out);
-  const html = output.getOutput();
-});
-res.json({
-  renderedComponentsList,
-  html,
-});
-```
-
-**Step 2:** Manually _initialize_ server rendered components, shipped via `marko-dependencies`.
-
-To initialize the list of server rendered components, do:
-
-```javascript
-// from the response received, retrieve as
-require("marko/components").init(response.renderedComponentsList);
-```
-
-**Note:** Ensure Step 2 is inside a DOM-ready wrapper, for the legacy widgets layer to load (if there are widgets built out of Marko 3, that is being used inside a Marko 4 component.)
-
-#### `marko-hydrate` _(provided by `lasso-marko`)_
-
-Includes all the dependencies needed by template and the code to register all components that would be rendered by the template. This also includes the code to initialize the rendered components. Including this bundle on the page will automatically hydrate server rendered components.
-
-```json
-{
-  "type": "marko-hydrate",
-  "path": "src/ui-modules/outdated-browser-banner/index.marko"
-}
-```
-
-**Note:** `marko-hydrate` will initialize the component if its defined on the global `window.$components` which is inserted by `Marko` when it sees a `<body>` tag. Else, if you are just rendering out and lasso-ing the a portion of a page with a set of components, include `<init-components/>` at the end of the associated `template.marko` file that builds out the page fragment.
-
-#### `package`
-
-A collection of dependencies. `browser.json` is the most common package type.
-It could be used to point to another `browser.json` from within one component's `browser.json`.
-Typically also used when the dependencies of the referred `browser.json` have to be packaged inline.
-
-```json
-{
-  "type": "package",
-  "path": "src/ui-modules/show-diag/browser.json"
-}
-```
-
-#### `require`
-
-If a javascript file has to be wrapped over for its common JS syntax, to a browser understandable format.
-
-```json
-{
-  "type": "require",
-  "path": "src/ui-modules/dynamic-module-loader/dynamic-init-client.js"
-}
-```
-
-#### `require` and `run`
-
-If a javascript file has to be wrapped over for its common JS syntax, to a browser understandable format and be executed immediately.
-
-```json
-{
-  "run": true,
-  "type": "require",
-  "path": "src/ui-modules/my-module/init.js"
-}
-```

package/docs/marko-5-upgrade.md

@@ -1,59 +0,0 @@
-# Upgrading to Marko 5
-
-## Step 0 - Ensure you're in a working state on the latest version of Marko 4
-
-Before we start, you'll want to make sure that you are already on the latest `4.x` release of `marko`.
-
-```bash
-# Upgrade using yarn
-yarn upgrade marko@^4
-```
-
-```bash
-# Upgrade using npm
-npm install marko@^4
-```
-
-> [!Warning]
-> Do _not_ run `npm install marko` (without the `@^4`). This will put you on Marko 5 and we're not quite there yet.
-
-> [!Tip]
-> If upgrading from Marko 3 you may want to reference [this guide](https://marko-v4.github.io/docs/marko-4-upgrade/).
-
-Run your application and tests to ensure your project is in a working state. There's little worse than finding an issue after you've started the upgrade process only to figure out the issue existed beforehand.
-
-## Step 1 - Upgrade Marko & Dependencies
-
-**TL;DR**: Paste & run this random shell script. It's safe. Trust us.
-
-```bash
-# Update Marko, and related ecosystem dependencies
-npx -y npm-check-updates -u \
-  marko \
-  `# for webpack projects` \
-  @marko/webpack \
-  `# for lasso projects` \
-  lasso lasso-marko @lasso/marko-taglib \
-  `# for jest test runner` \
-  @marko/jest \
-  `# for projects with v3 widgets` \
-  marko-widgets
-
-# Install @marko/compat-v4 unless `marko-widgets` is already installed
-grep -q "marko-widgets" package.json || { [[ -f yarn.lock ]] && yarn add @marko/compat-v4 || npm install @marko/compat-v4; }
-[[ -f yarn.lock ]] && npx -y yarn-deduplicate && yarn
-[[ -f yarn.lock ]] || npm i
-```
-
-This script automates the following steps for you:
-
-- Install the compat package
-  - `marko-widgets` if using Marko 3's Widgets
-  - `@marko/compat-v4` if not using Widgets
-- Update `marko` to 5.x
-- Update any ecosystem packages used by your app (lasso, webpack, jest, etc)
-
-> [!Note]
-> Check your `package.json`. If you have other third-party Marko packages not covered by the script, you may need to update them as well.
-
-Your application should continue to work. Run your tests to ensure everything is working. Congratulations! You've upgraded to Marko 5.

package/docs/marko-json.md

@@ -1,248 +0,0 @@
-# `marko.json` & `marko-tag.json`
-
-Marko supports configuration files for validation, enabling experimental features, and custom paths for component files.
-
-These configuration files are automatically found with [the same discovery mechanism as custom tags](./custom-tags.md#how-tags-are-discovered).
-
-There are 2 types of configuration files:
-
-1. `marko.json` describes an entire suite of components.
-2. `marko-tag.json` describes a single component.
-
-## Single component definition
-
-`marko-tag.json` configures a single component. It’s automatically discovered if placed inside a [tag directory](./custom-tags.md#tag-directories).
-
-### Options
-
-```js
-{
-  "html": true, // Treat as a native HTML tag, not a custom tag.
-  "htmlType": "svg", // Optimizes for specific types of native tags (currently only `svg` and `html`).
-  "open-tag-only": true, // Forbids passing body content to this tag.
-  "featureFlags": [ "feature-a" ], // Enable beta features by passing feature flags.
-  "nested-tags": { // This section configures attribute tags.
-    "tab": {
-      "target-property": "tabs", // Puts `<@tab>` tags into `input.tabs`.
-      "is-repeated": true,  // Allow more than one nested `<@tab>`.
-      "attributes": {
-        // Same as the “Attributes” section below.
-      }
-    }
-  }
-}
-```
-
-### Attributes
-
-One commonly-used feature of this config file is compile-time checks for attributes.
-
-```js
-{
-  "attributes": {
-    "heading": "string"
-  }
-}
-```
-
-The above code ensures that the `heading` attribute is the _only_ attribute supplied to this tag.
-
-The `string` value is used as documentation for the custom tag. It may be picked up by tooling, like Marko’s editor plugins, to provide hints to the user.
-
-The recommended list of attribute types are as follows:
-
-- `expression` (any JavaScript expression)
-- `string`
-- `number`
-- `boolean`
-- `regexp`
-- `date`
-- `object`
-- `array`
-- `function`
-
-You can also provide an object for an attribute definition’s value for additional options:
-
-```js
-{
-  "attributes": {
-    "heading": {
-      "type": "string", // Same as setting "string" above.
-      "default-value": 0, // The attribute will default to this value.
-      "required": true, // Error during compilation if this attribute is undefined. (Mutually exclusive with "default-value"
-      "preserve-name": true, // By default component attributes are camelCased; this disables that feature.
-      "remove-dashes": true, // By default native tag attributes are dash-cased; this disables that feature.
-
-      // The following attributes do nothing, but are picked up by tooling.
-      "deprecated": true,
-      "description": "The component’s heading text" // Describes the attribute’s purpose.
-    }
-  }
-}
-```
-
-We can also describe a _pattern_ of attributes to match a definition:
-
-```js
-{
-    "attributes": {
-        "data-*": {
-          "type": "string",
-          "pattern": true
-        }
-    }
-}
-```
-
-In the above, all attributes prefixed with `data-` are configured to be a `string`.
-
-> **Note:** Future Marko versions will describe these definitions/types in the component itself, reducing the need for this configuration file.
-
-### Paths
-
-There are several options that override the default discovery of component files, such as the template.
-
-Typically, you should let Marko find these files automatically, but here is a reference in case you encounter these settings in the wild.
-
-```javascript
-{
-  "template": "./template.marko", // Custom path to the `.marko` template.
-  "renderer": "./renderer.js", // Custom path to the `renderer.js` file.
-
-  // Compiler file hooks
-  "parse": "./parse.js", // Used to augment parsing.
-  "migrate": "./migrate.js", // Used for migrating deprecated features.
-  "transform": "./transform.js", // Used to modify the AST before generating it.
-  "analyze": "./analyze.js" // Used to analyze metadata the entire ast before beginning to translate it.
-  "translate": "./translate.js" // Used to generate custom JS.
-}
-```
-
-For more information about the compiler hooks [jump over here](./compiler.md#hooks).
-
-## Tag library definition
-
-Along with configuring a single component, you can use a `marko.json` file to configure an _entire library of components_.
-
-Similar to [`marko-tag.json`](#single-component-definition), this file is discovered if placed within a [tag directory](./custom-tags.md#tag-directories). It will also be discovered at the root directory of a project, or [in a `node_module` package](./custom-tags.md#publishing-tags-to-npm).
-
-### Options
-
-```js
-{
-  "taglib-id": "my-custom-tag-library", // Names the component library, for better errors.
-  "exports": "./dist", // Where to export the compiled components.
-  "tags-dir": "./ui-modules", // What directory to crawl to autodiscover components. Default:`./components/`
-  "taglib-imports": ["./some-folder/marko.json", "./other-folder/marko.json"], // Creates a _combined_ tag library by referencing others.
-
-  "tags": { // Definitions for individual tags.
-    "my-tag": {
-      // Same options as “marko-tag.json”.
-    }
-  },
-
-  "attributes": {
-    // Defines attributes on all tags.
-    // Options are the same as the “attributes” section in “marko-tag.json”.
-  },
-
-  // Compiler file hooks (run on all templates)
-  "migrator": "./migrator.js", // Hooks into the migration stage for migrating deprecated features.
-  "transformer": "./transformer.js", // Used to modify the AST before generating it.
-  "text-transformer": "./text-transformer.js", // Used to transform all static text in the template.
-}
-```
-
-> **⚠️ Note:** Compiler hooks are currently undocumented: avoid using them. The compiler API is overhauled in Marko 5, and will be documented once that transition is complete.
-
-## Shorthands
-
-Both configuration files support _shorthands_ for defining `tags` and `attributes`. For example, take this `marko.json` file:
-
-_marko.json_
-
-```js
-{
-  "taglib-id": "my-custom-tag-library",
-  "tags": {
-    "my-layout": {
-      "attributes": {
-        "name": "string",
-        "age": "number"
-      },
-      "nested-tags": {
-        "heading": {
-          "attributes": {
-            "color": "string"
-          }
-        },
-        "body": {
-          "attributes": {
-            "color": "string"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-As a shorthand, anywhere `tags` or `nested-tags` is used, you can remove the outer object and wrap the individual tags in `<angle-brackets>`.
-
-For `attributes`, you can remove the outer object and prefix the attributes with an `@`.
-
-The above example using the shorthand syntax would become:
-
-_marko.json_
-
-```js
-{
-  "taglib-id": "my-custom-tag-library",
-  "<my-layout>": {
-    "@name": "string",
-    "@age": "number",
-    "<heading>": {
-      "@color": "string"
-    },
-    "<body>": {
-      "@color": "string"
-    }
-  }
-}
-```
-
-For `nested-tags`, there is also a shorthand for `is-repeated` (a postfix of `[]`) and `target-property` (a prefix of `@newName`):
-
-_marko.json_
-
-```javascript
-{
-  "<my-layout>": {
-    "@sections <section>[]": {
-      "@color": "string"
-    }
-  }
-}
-```
-
-Is equivalent to:
-
-_marko.json_
-
-```javascript
-{
-  "tags": {
-    "my-layout": {
-      "nested-tags": {
-        "section": {
-          "target-property": "sections",
-          "is-repeated": true,
-          "attributes": {
-            "color": "string"
-          }
-        }
-      }
-    }
-  }
-}
-```