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,39 @@ define({
 });
 ```
 
-## `render` & `content`
+## Render
 
-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 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 `value` option must be a function, which returns a result of the call to the built-in template engine.
 
-> You can use built-in [template engine](/component/templates.md) with those properties without additional code
+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()`.
 
-### Shadow DOM
+### Element's Content
 
-Use the `render` key for the internal structure of the custom element, where you can add isolated styles, slot elements, etc.
+By default `render` property creates and updates the contents of the custom element:
 
 ```javascript
-import { define, html } from "hybrids";
+define({
+  tag: "my-element",
+  name: "",
+  render: ({ name }) => html`<h1>Hello ${name}!</h1>`,
+});
+```
 
+```html
+<my-element>
+  <h1>Hello John!</h1>
+</my-element>
+```
+
+### Shadow DOM
+
+If the root template of the element includes styles or `<slot>` elements, the library renders the content to the shadow DOM:
+
+The template with inline styles:
+
+```javascript
 define({
   tag: "my-element",
   name: "",
@@ -313,88 +331,95 @@ 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,
-  },
-  ...
-}
+```html
+<my-element>
+  #adopted-stylesheets
+  #shadow-root
+    <h1>Hello John!</h1>
+</my-element>
 ```
 
-```javascript
-import { define, html } from "hybrids";
+The template with `<slot>` element:
 
+```javascript
 define({
   tag: "my-element",
-  render: {
-    value: html`<div>...</div>`, 
-    options: { delegatesFocus: true },
-  },
+  render: () => html`
+    <div id="container">
+      <slot></slot>
+    </div>
+  `,
 });
 ```
 
-### Element's Content
+```html
+<my-element>
+  #shadow-root
+    <div id="container">
+      <slot></slot>
+    </div>
+</my-element>
+```
 
-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.
+!> Only the root template can be used to determine the rendering mode implicitly. The nested template with styles does not force rendering in the Shadow DOM.
 
-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.
+### Explicit Mode
 
-```javascript
-import { define, html } from "hybrids";
+Use the `shadow` option to force one of the rendering modes:
 
-define({
-  tag: "my-element",
-  name: "",
-  content: ({ name }) => html`<h1>Hello ${name}!</h1>`
-});
+```ts
+// Disable Shadow DOM (even if the template includes styles or slot elements)
+render: {
+  value: (host) => html`...`.css`...`,
+  shadow: false,
+  ...
+}
+
+// Force Shadow DOM
+render: {
+  value: (host) => html`...`,
+  shadow: true,
+}
 ```
 
-### Custom Function
+#### Nested Templates
 
-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:
+If only your nested template includes styles, you must use the `shadow` option to force rendering in the Shadow DOM explicitly:
 
 ```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);
-    }
-  }
-}
+define({
+  tag: "my-element",
+  show: false,
+  render: {
+    value: ({ show }) => html`
+      <div id="container">
+        ${show && html`<slot></slot>`}
+      </div>
+    `,
+    shadow: true,
+  },
+});
 ```
 
-```javascript
-import reactify from "./reactify.js";
+#### Shadow DOM Options
 
-function MyComponent({ name }) {
-  return <div>{name}</div>;
-}
+You can use `shadow` option for passing custom arguments to the `host.attachShadow()` method:
+
+```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 +444,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>
 ```