Update docs

Author: mantou132

.prettierrc.json

@@ -8,7 +8,7 @@
     {
       "files": ["*.md"],
       "options": {
-        "printWidth": 80
+        "printWidth": 100
       }
     }
   ]

packages/gem-book/docs/en/003-plugins.md

@@ -0,0 +1,204 @@
+---
+isNav: true
+---
+
+# Plugins
+
+## `<gbp-code-group>`
+
+Used to display several pieces of code with similar functionality:
+
+<gbp-code-group>
+
+```bash npm
+npm i gem-book
+```
+
+```bash yarn
+yarn add gem-book
+```
+
+</gbp-code-group>
+
+````md
+<gbp-code-group>
+
+```bash npm
+npm i gem-book
+```
+
+```bash yarn
+yarn add gem-book
+```
+
+</gbp-code-group>
+````
+
+## `<gbp-raw>`
+
+Used to display remote code. If the provided `src` only contains a path, it will read content from the current project's GitHub (affected by [`sourceDir`](./002-cli.md#--source-dir) and [`sourceBranch`](./002-cli.md#--source-branch)), for example:
+
+<gbp-raw src="package.json" range="2-3,-4--6,author-license" highlight="-5,author"></gbp-raw>
+
+```md
+<!-- `range` specifies the display range, supporting negative numbers and string matching, `highlight` format is the same -->
+
+<gbp-raw src="package.json" range="2-3,-4--6,author-license" highlight="-5,author"></gbp-raw>
+```
+
+## `<gbp-var>`
+
+Reference global variable: <gbp-var>hello</gbp-var>
+
+```md
+<gbp-var>hello</gbp-var>
+```
+
+The variable needs to be defined in the [configuration file](./002-cli.md).
+
+## `<gbp-media>`
+
+Displays remote multimedia content, such as images or videos, using the same resource retrieval method as `<gbp-raw>`:
+
+```md
+<gbp-media src="preview.png"></gbp-media>
+```
+
+## `<gbp-include>`
+
+Dynamically loads Markdown snippets:
+
+<gbp-include src="./guide/007-extension.md" range="[!NOTE]->"></gbp-include>
+
+```md
+<!-- `range` syntax is the same as `<gbp-raw>`, here `range` uses string matching -->
+
+<gbp-include src="./guide/007-extension.md" range="[!NOTE]->"></gbp-include>
+```
+
+## `<gbp-import>`
+
+Dynamically imports modules, which can be used to load plugins on demand. For example, the following custom element is dynamically loaded (the `.ts` file will be compiled using [esm.sh](https://esm.sh/)):
+
+<gbp-import src="docs/hello.ts"></gbp-import>
+
+<my-plugin-hello></my-plugin-hello>
+
+```md
+<gbp-import src="docs/hello.ts"></gbp-import>
+
+<my-plugin-hello></my-plugin-hello>
+```
+
+## `<gbp-content>`
+
+Insert content into `<gem-book>`, allowing customization of `<gem-book>` content on specific pages, such as a custom sidebar:
+
+```md
+<gbp-content slot="sidebar-before">
+  <div>Test</div>
+  <style>
+    gem-book [part=sidebar-content] {
+      display: none;
+    }
+  </style>
+</gbp-content>
+```
+
+## `<gbp-docsearch>`
+
+Use [Algolia DocSearch](https://docsearch.algolia.com/) to provide search for the website, instantiated only once, and can be placed using [slots](./guide/007-extension.md#slots):
+
+<gbp-raw src="docs/template.html" range="13--4"></gbp-raw>
+
+> [!WARNING]
+>
+> `renderJavaScript` must be enabled in the [configuration](https://crawler.algolia.com/admin/crawlers) for Algolia DocSearch Crawler.
+
+Using `docsearch?local` can provide local search service (thanks to [MiniSearch](https://github.com/lucaong/minisearch/)), [example](https://duoyun-ui.gemjs.org).
+
+## `<gbp-comment>`
+
+It uses [Gitalk](https://github.com/gitalk/gitalk) to bring comment functionality to the website, similar to the usage of `<gbp-docsearch>`:
+
+```html
+<gem-book>
+  <gbp-comment
+    slot="main-after"
+    client-id="xxx"
+    client-secret="xxx"
+  ></gbp-comment>
+</gem-book>
+```
+
+## `<gbp-sandpack>`
+
+Use [Sandpack](https://sandpack.codesandbox.io/) to create interactive examples:
+
+<gbp-sandpack dependencies="@mantou/gem, duoyun-ui">
+
+```ts
+import { render, html } from '@mantou/gem';
+
+import 'duoyun-ui/elements/button';
+
+render(
+  html`<dy-button>Time: ${new Date().toLocaleString()}</dy-button>`,
+  document.getElementById('root'),
+);
+```
+
+</gbp-sandpack>
+
+````md
+<gbp-sandpack dependencies="@mantou/gem, duoyun-ui">
+
+```ts
+import { render, html } from '@mantou/gem';
+
+import 'duoyun-ui/elements/button';
+
+render(
+  html`<dy-button>Time: ${new Date().toLocaleString()}</dy-button>`,
+  document.getElementById('root'),
+);
+```
+
+</gbp-sandpack>
+````
+
+## `<gbp-example>`
+
+Generate examples for any custom element, for example:
+
+<gbp-example name="dy-avatar"  src="https://esm.sh/duoyun-ui/elements/avatar">
+
+```json
+{
+  "src": "https://api.dicebear.com/5.x/bottts-neutral/svg",
+  "status": "positive",
+  "size": "large",
+  "square": true
+}
+```
+
+</gbp-example>
+
+````md
+<gbp-example name="dy-avatar"  src="https://esm.sh/duoyun-ui/elements/avatar">
+
+```json
+{
+  "src": "https://api.dicebear.com/5.x/bottts-neutral/svg",
+  "status": "positive",
+  "size": "large",
+  "square": true
+}
+```
+
+</gbp-example>
+````
+
+## `<gbp-api>`
+
+Use [`gem-analyzer`](https://github.com/mantou132/gem/blob/main/packages/gem-analyzer) to generate API documentation for `GemElement`, such as [GemBookElement API](./004-api.md);

packages/gem-devtools/src/scripts/get-gem.ts

@@ -10,6 +10,7 @@ export const getSelectedGem = function (data: PanelStore): PanelStore | string {
   if (!$0) return `Not Gem: $0 is ${$0}`;
   const { __GEM_DEVTOOLS__HOOK__ } = window;
   if (__GEM_DEVTOOLS__HOOK__) {
+    // 不支持多种 GemElement，__GEM_DEVTOOLS__HOOK__ 只记录首个
     const { GemElement } = __GEM_DEVTOOLS__HOOK__;
     if (!GemElement || !($0 instanceof GemElement)) return 'Not Gem: gem hook';
   } else {

packages/gem-devtools/src/sidebarpanel.ts

@@ -16,6 +16,7 @@ async function updateElementProperties() {
     if (typeof result !== 'string') {
       changePanelStore(result);
     } else {
+      logger.info(result);
       changePanelStore(await execution(getDomStat, [new PanelStore({ isGemElement: false })]));
     }
   } catch (err) {

packages/gem-examples/src/scope/index.ts

@@ -9,15 +9,19 @@ const closedStyles = createCSSSheet(css`
 `);
 @shadow({ mode: 'closed' })
 @adoptedStyle(closedStyles)
-@customElement('app-closed')
+@customElement('closed-shadow-dom')
 class _Closed extends GemElement {
   render() {
     return html`<div>Closed shadow</div>`;
   }
 }
 
-@customElement('other-element')
-class _OtherElement extends GemElement {}
+@customElement('light-dom')
+class _OtherElement extends GemElement {
+  render() {
+    return html`<p>Other Content</p>`;
+  }
+}
 
 const style = createCSSSheet(css`
   :scope {
@@ -36,13 +40,11 @@ export class App extends GemElement {
       Text
       <header><h1>Header</h1></header>
       <p>Content</p>
-      <other-element>
-        <p>Other Content</p>
-      </other-element>
+      <light-dom></light-dom>
       <article>
         <p>Content</p>
       </article>
-      <app-closed></app-closed>
+      <closed-shadow-dom></closed-shadow-dom>
     `;
   }
 }

packages/gem/docs/en/001-guide/001-basic/001-reactive-element.md

@@ -41,19 +41,19 @@ class MyElement extends GemElement {
 > [!TIP]
 > Do not modify prop/attr within the element, they should be passed in one-way by the parent element, just like native elements
 
-In addition, `GemElement` provides React-like `state`/`setState` API to manage the state of the element itself. an element re-rendered is triggered whenever `setState` is called:
+In addition, Gem provides the `createState` API to create the element's own state, and the created state object also acts as an update function, triggering the element to re-render when called.
 
 ```js
 // Omit import...
 
 @customElement('my-element')
 class MyElement extends GemElement {
-  state = { id: 1 };
-  clicked() {
-    this.setState({ id: 2 });
+  #state = createState({ id: 1 });
+  #clicked() {
+    this.#state({ id: 2 });
   }
   render() {
-    return html`${this.state.id}`;
+    return html`${this.#state.id}`;
   }
 }
 ```
@@ -152,3 +152,6 @@ Complete life cycle:
 
 > [!NOTE]
 > The `constructor` and `unmounted` of the parent element are executed before the child element, but the `mounted` is executed after the child element
+
+> [!WARNING]
+> The lifecycle may be replaced in the future by decorators based on `@effect` `@memo` `@willMount` `@renderTemplate` `@mounted` `@unmounted

packages/gem/docs/en/001-guide/001-basic/006-styled-element.md

@@ -31,12 +31,7 @@ You can reference CSS selectors in JS:
 
 ```js 17
 import { GemElement, html } from '@mantou/gem';
-import {
-  createCSSSheet,
-  styled,
-  adoptedStyle,
-  customElement,
-} from '@mantou/gem';
+import { createCSSSheet, styled, adoptedStyle, customElement } from '@mantou/gem';
 
 const styles = createCSSSheet({
   header: styled.class`
@@ -56,6 +51,9 @@ class MyElement extends GemElement {
 }
 ```
 
+> [!NOTE]
+> Use `$` as a key to represent `:host, :scope` selectors, allowing styles to apply to both ShadowDOM and LightDOM.
+
 ## Customize the style outside the element
 
 Use [`::part`](https://drafts.csswg.org/css-shadow-parts-1/#part)(only ShadowDOM) to export the internal content of the element, allowing external custom styles:
@@ -95,7 +93,7 @@ class MyElement extends GemElement {
 ```
 
 > [!NOTE]
-> Note the difference with `state`/`setState`
+> Note the difference with `createState`
 
 > [!TIP]
 > Can also customize element styles using hack, for example:

packages/gem/docs/en/001-guide/002-advance/003-theme.md

@@ -95,3 +95,7 @@ class App extends GemElement {
   }
 }
 ```
+
+## Scoped and override theme
+
+<gbp-include src="../../snippets/scoped-theme.md"></gbp-include>

packages/gem/docs/en/001-guide/002-advance/010-debug.md

@@ -5,3 +5,8 @@ GemElement is a standard custom element that can be inspected and debugged in th
 ## Use Gem DevTools
 
 ![Gem DevTools](https://raw.githubusercontent.com/mantou132/gem/master/packages/gem-devtools/screenshot/firefox.jpg)
+
+Features:
+
+- Display all public non-standard members of the gem element, simple types allow editing
+- When the non Gem element is selected, statistical analysis of all custom elements on the page will be displayed.