feat: remove content property & add shadow mode detection to render property (#258)

BREAKING CHANGE: The `content` property is no longer supported. The `render` property must be used. In some cases, usage of the `shadow` option might be required.

Author: smalluban

README.md

@@ -104,7 +104,7 @@ import Details from  "./details.js";
 const Home = define({
   [router.connect]: { stack: [Details, ...] },
   tag: "app-home",
-  content: () => html`
+  render: () => html`
     <template layout="column">
       <h1>Home</h1>
       <nav layout="row gap">
@@ -118,7 +118,7 @@ const Home = define({
 export define({
   tag: "app-router",
   stack: router(Home),
-  content: ({ stack }) => html`
+  render: ({ stack }) => html`
     <template layout="column">
       ${stack}
     </template>
@@ -139,7 +139,7 @@ Create CSS layouts in-place in templates, even without using Shadow DOM, but sti
 ```javascript
 define({
   tag: "app-home-view",
-  content: () => html`
+  render: () => html`
     <template layout="column center gap:2">
       <div layout="grow grid:1|max">
         <h1>Home</h1>

docs/README.md

@@ -110,7 +110,7 @@ import Details from  "./details.js";
 const Home = define({
   [router.connect]: { stack: [Details, ...] },
   tag: "app-home",
-  content: () => html`
+  render: () => html`
     <template layout="column">
       <h1>Home</h1>
       <nav layout="row gap">
@@ -124,7 +124,7 @@ const Home = define({
 export define({
   tag: "app-router",
   stack: router(Home),
-  content: ({ stack }) => html`
+  render: ({ stack }) => html`
     <template layout="column">
       ${stack}
     </template>
@@ -145,7 +145,7 @@ Create CSS layouts in-place in templates, even without using Shadow DOM, but sti
 ```javascript
 define({
   tag: "app-home-view",
-  content: () => html`
+  render: () => html`
     <template layout="column center gap:2">
       <div layout="grow grid:1|max">
         <h1>Home</h1>

docs/component-model/definition.md

@@ -145,7 +145,7 @@ import Home from './views/home.js';
 
 const App = {
   stack: router(Home),
-  content: () => html`
+  render: () => html`
     <template layout="column">
       ...
       ${stack}

docs/component-model/layout-engine.md

@@ -28,7 +28,7 @@ The feature supports both `content` and `render` properties of the component's d
 ```js
 define({
   tag: "my-app-view",
-  content: () => html`
+  render: () => html`
     <template layout="column">
       ...
     </template>

docs/component-model/structure.md

@@ -12,10 +12,10 @@ The cache mechanism uses equality check to compare values (`nextValue` !== `last
 
 ## Reserved Keys
 
-There are three reserved property names in the definition:
+There are two reserved property names in the definition:
 
 * `tag` - a string which sets the custom element tag name
-* `render` and `content`, which expect the value as a function, and have additional options available
+* `render` - expects its value as a function for rendering the internal structure of the custom element
 
 ## Translation
 
@@ -53,7 +53,7 @@ define({
 });
 ```
 
-Usually, the shorthand definition is more readable and less verbose, but the second one gives more control over the property behavior, as it provides additional options.
+Usually, the shorthand syntax is more readable and less verbose, but the second one gives more control over the property behavior, as it provides additional options.
 
 ## Attributes
 
@@ -286,21 +286,31 @@ define({
 });
 ```
 
-## `render` & `content`
+## Rendering
 
-The `render` and `content` properties are reserved for the rendering structure of the custom element. The `value` option must be a function, which returns a result of the call to the built-in template engine or a custom update function.
+The `render` property is reserved for the creating structure of the custom element. The `value` option must be a function, which returns a result of the call to the built-in template engine.
 
-The library uses internally the `observe` pattern to called function automatically when dependencies change. As the property returns an update function, it can also be called manually, by `el.render()` or `el.content()`.
+The library uses the `observe` pattern to call the function automatically when dependencies change. As the property resolves to the update function, it can also be called manually, by `el.render()`.
 
-> You can use built-in [template engine](/component/templates.md) with those properties without additional code
+### Element's Content
+
+By default `render` property creates and updates the content of the custom element:
+
+```javascript
+define({
+  tag: "my-element",
+  name: "",
+  render: ({ name }) => html`<h1>Hello ${name}!</h1>`,
+});
+```
 
 ### Shadow DOM
 
-Use the `render` key for the internal structure of the custom element, where you can add isolated styles, slot elements, etc.
+If the root template of the element includes styles (`css` and `style` helpers, or `<style>` elements) or `<slot>` element, the library will render the content to the shadow DOM:
 
-```javascript
-import { define, html } from "hybrids";
+The template with styles:
 
+```javascript
 define({
   tag: "my-element",
   name: "",
@@ -313,88 +323,55 @@ define({
 });
 ```
 
-The `render` property provides unique `options` key for passing additional arguments to `host.attachShadow()` method:
-
-```ts
-render: {
-  value: (host) => { ... },
-  options: {
-    mode: "open" | "closed",
-    delegatesFocus: boolean,
-  },
-  ...
-}
-```
+The template with `<slot>` element:
 
 ```javascript
-import { define, html } from "hybrids";
-
 define({
   tag: "my-element",
-  render: {
-    value: html`<div>...</div>`, 
-    options: { delegatesFocus: true },
-  },
+  render: () => html`
+    <slot></slot>
+  `,
 });
 ```
 
-### Element's Content
+Templates are compiled "just in time", so only the root template can be used to determine the rendering mode. If your nested template includes styles or slots, you must use the `shadow` option to force rendering in the Shadow DOM explicitly.
 
-Use the `content` property for rendering templates in the content of the custom element. By the design, it does not support isolated styles, slot elements, etc.
+### Explicit Mode
 
-However, it is the way to build an app-like views structure, which can be rendered as a document content in light DOM. It is easily accessible in developer tools and search engines. For example, form elements (like `<input>`) have to be in the same subtree with the `<form>` element.
+Use the `shadow` option of the `render` property to set rendering mode to Shadow DOM or element's content:
 
-```javascript
-import { define, html } from "hybrids";
-
-define({
-  tag: "my-element",
-  name: "",
-  content: ({ name }) => html`<h1>Hello ${name}!</h1>`
-});
-```
-
-### Custom Function
-
-The preferred way is to use a built-in [template engine](/component/templates.md), but you can use any function to update the DOM of the custom element, which accepts the following structure:
+```ts
+// Disable Shadow DOM
+render: {
+  value: (host) => html`...`,
+  shadow: false,
+  ...
+}
 
-```javascript
-import React from "react";
-import ReactDOM from "react-dom";
-
-export default function reactify(fn) {
-  return (host) => {
-    // get the component using the fn and host element
-    const Component = fn(host); 
-
-    // return the update function
-    return (host, target) => {
-      ReactDOM.render(Component, target);
-    }
-  }
+// Force Shadow DOM
+render: {
+  value: (host) => html`...`,
+  shadow: true,
 }
 ```
 
-```javascript
-import reactify from "./reactify.js";
+You can use this option for passing custom values to the `host.attachShadow()` method:
 
-function MyComponent({ name }) {
-  return <div>{name}</div>;
-}
+```javascript
+import { define, html } from "hybrids";
 
 define({
   tag: "my-element",
-  render: reactify(({ name }) => <MyComponent name={name} />),
-})
+  render: {
+    value: html`<div>...</div>`, 
+    shadow: { mode: "close", delegatesFocus: true },
+  },
+});
 ```
 
-The above example uses the [`factory` pattern](#factories), to produce a function, which accepts the host element and returns the update function, which has `host` and `target` arguments. The `target` argument in the update function can be a `host` or `host.shadowRoot` depending on the property name.
-
-!> The other properties from the `host` must be called in the main function body (not in the update function), as only then they will be correctly observed
-
 ### Reference Internals
 
-Both `render` and `content` properties can be used to reference internals of the custom element. The DOM update process is asynchronous, so to avoid rendering timing issues, always use a property as a reference to the target element. If the property depending on `render` or `content` is called before the first update, the update will be triggered manually by calling the function.
+The `render` property can be used to reference internals of the custom element. The DOM update process is asynchronous, so to avoid rendering timing issues, always use the property as a reference to the target element. If the property depending on `render` is called before the first update, the update will be triggered manually by calling the function.
 
 ```javascript
 import { define, html } from "hybrids";
@@ -419,8 +396,8 @@ define({
       console.log("connected");
       return () => console.log("disconnected");
     },
-    observe(host, value, lastValue) {
-      console.log(`${value} -> ${lastValue}`);
+    observe(host) {
+      console.log("rendered");
     },
   },
 });

docs/component-model/templates.md

@@ -545,7 +545,7 @@ The built-in `html.transition` plugin utilizes the [Transition API](https://deve
 define({
   tag: 'my-app',
   stack: router([Home]),
-  content: ({ stack }) => html`
+  render: ({ stack }) => html`
     <header>...</header>
     <main>${stack}</main>
     ...
@@ -560,7 +560,7 @@ The transition API can be customized by the CSS properties. The DOM elements mig
 ```javascript
 export default define({
   tag: 'my-app-home',
-  content: () => html`
+  render: () => html`
     <template layout="column">
       ...
       <div layout="view:card"></div>

docs/getting-started.md

@@ -21,7 +21,7 @@ Otherwise, you can use it directly from a number of CDNs, which provide a hybrid
   define({
     tag: "hello-world",
     name: '',
-    content: ({ name }) => html`<p>Hello ${name}!</p>`,
+    render: ({ name }) => html`<p>Hello ${name}!</p>`,
   });
 </script>
 ```

docs/migration.md

@@ -2,7 +2,7 @@
 
 ## v9.0.0
 
-The `v9.0` release brings simplification into the full object property descriptor and moves out some rarely used default behaviors into optional features.
+The `v9.0` release brings simplification into the full object property descriptor, removes the `content` property, and moves out some rarely used default behaviors into optional features.
 
 ### Descriptors
 
@@ -49,11 +49,11 @@ Writable properties are no longer automatically synchronized back to the attribu
 
 Read more about the attribute synchronization in the [Structure](/component-model/structure.md#reflect) section.
 
-### Render and Content
+### Render Property
 
-#### Keys
+#### Key
 
-The `render` and `content` properties are now reserved and expect an update function as a value (they cannot be used for other purpose). If you defined them as a full descriptor with custom behavior, you must rename them:
+The `render` property is now reserved and expects an update function as a value (it cannot be used for other purpose). If you defined it as a full descriptor with custom behavior, you must rename the property:
 
 ```javascript
 // before
@@ -74,7 +74,39 @@ The `render` and `content` properties are now reserved and expect an update func
 }
 ```
 
-#### Shadow DOM
+#### Content
+
+From now, the `content` property has no special behavior, so it does not render. As the content should not include styles or `<slot>` elements, it is sufficient to just rename the property to `render`:
+
+```javascript
+// before
+{
+  content: () => html`...`,
+  ...
+}
+```
+
+```javascript
+// after
+{
+  render: () => html`...`,
+  ...
+}
+```
+
+If you need to pass styles to the element's content, you can disable Shadow DOM explicitly:
+  
+```javascript
+{
+  render: {
+    value: () => html`...`.css`body { font-size: 14px }`,
+    shadow: false,
+  },
+  ...
+}
+```
+
+#### Options
 
 The options are now part of the `render` descriptor instead of a need to extend the `render` function:
 
@@ -91,7 +123,7 @@ The options are now part of the `render` descriptor instead of a need to extend
 {
   render: {
     value: (host) => html`...`,
-    options: { mode: "close" },
+    shadow: { mode: "close" },
   },
   ...
 }

docs/router/typescript.md

@@ -12,7 +12,7 @@ interface MyView {
 export default define<MyView>({
   [router.connect]: { url: "/my-view" },
   tag: "my-view",
-  content: ({ param }) => html`
+  render: ({ param }) => html`
     <p>${param}</p>
   `,
 });
@@ -60,7 +60,7 @@ interface MyView {
 const MyView: Component<MyView> = {
   [router.connect]: { url: "/my-view" },
   tag: "my-view",
-  content: ({ param }) => html`
+  render: ({ param }) => html`
     <p>${param}</p>
   `,
 };