Update docs

mantou132 · Dec 3, 2023 · dcd0759 · dcd0759
1 parent 65cd9eb
commit dcd0759
Show file tree

Hide file tree

Showing 9 changed files with 70 additions and 34 deletions.
diff --git a/packages/duoyun-ui/src/lib/styles.ts b/packages/duoyun-ui/src/lib/styles.ts
@@ -12,8 +12,4 @@ export const focusStyle = createCSSSheet(css`
     outline: 2px solid ${theme.focusColor};
     outline-offset: -2px;
   }
-  :host::highlight(search) {
-    color: white;
-    background: ${theme.informativeColor};
-  }
 `);
diff --git a/packages/gem-book/src/element/elements/main.ts b/packages/gem-book/src/element/elements/main.ts
@@ -124,19 +124,19 @@ const style = createCSSSheet(css`
     padding: 0.8em 1em;
   }
   blockquote.note {
-    --highlight: ${theme.noteColor};
+    --highlight: ${theme.noteColorRGB};
   }
   blockquote.tip {
-    --highlight: ${theme.tipColor};
+    --highlight: ${theme.tipColorRGB};
   }
   blockquote.important {
-    --highlight: ${theme.importantColor};
+    --highlight: ${theme.importantColorRGB};
   }
   blockquote.warning {
-    --highlight: ${theme.warningColor};
+    --highlight: ${theme.warningColorRGB};
   }
   blockquote.caution {
-    --highlight: ${theme.cautionColor};
+    --highlight: ${theme.cautionColorRGB};
   }
   blockquote > .title {
     font-weight: bold;
@@ -201,9 +201,10 @@ const style = createCSSSheet(css`
       Liberation Mono,
       Courier New,
       monospace;
-    font-size: 90%;
-    background: ${theme.inlineCodeBackground};
-    padding: 0 3px;
+    padding: 0.15em 0.4em 0.1em;
+    font-size: 0.9em;
+    background: rgba(${theme.textColorRGB}, 0.05);
+    border-radius: 0.125em;
   }
   gem-book-pre {
     z-index: 2;
@@ -235,25 +236,19 @@ export class Main extends GemElement {
       display: inline-flex;
       align-items: center;
       gap: 0.2em;
-      color: inherit;
+      color: ${theme.primaryColor};
       text-decoration: none;
       line-height: 1.2;
-      background: rgba(${theme.primaryColorRGB}, 0.2);
-      border-bottom: 1px solid rgba(${theme.textColorRGB}, 0.4);
-    }
-    .link code {
-      background: transparent;
-      padding: 0;
+      border-bottom: 1px solid transparent;
     }
     .link:hover {
-      background: rgba(${theme.primaryColorRGB}, 0.4);
       border-color: currentColor;
     }
   `;
 
   #hashChangeHandle = () => {
     const { hash } = location;
-    const ele = hash && this.shadowRoot?.querySelector(decodeURIComponent(hash));
+    const ele = hash && this.shadowRoot?.querySelector(`[id="${decodeURIComponent(location.hash.slice(1))}"]`);
     if (!hash) {
       document.body.scroll(0, 0);
     } else if (ele) {

diff --git a/packages/gem-book/src/element/helper/default-theme.ts b/packages/gem-book/src/element/helper/default-theme.ts
@@ -11,7 +11,6 @@ export const defaultTheme = {
   borderColor: '#eaeaea',
   textColor: 'rgb(40, 44, 52)',
   primaryColor: 'rgb(38, 192, 227)',
-  inlineCodeBackground: '#fffae0',
   noteColor: 'rgb(9, 105, 218)',
   tipColor: 'rgb(26, 127, 55)',
   importantColor: 'rgb(130, 80, 223)',

diff --git a/packages/gem-book/src/element/helper/theme.ts b/packages/gem-book/src/element/helper/theme.ts
@@ -17,6 +17,11 @@ function generateTheme(theme: Theme) {
   const colors = {
     textColorRGB: getRGB(theme.textColor),
     primaryColorRGB: getRGB(theme.primaryColor),
+    noteColorRGB: getRGB(theme.noteColor),
+    tipColorRGB: getRGB(theme.tipColor),
+    importantColorRGB: getRGB(theme.importantColor),
+    warningColorRGB: getRGB(theme.warningColor),
+    cautionColorRGB: getRGB(theme.cautionColor),
   };
   div.remove();
 

diff --git a/packages/gem-book/themes/cyberpunk.json b/packages/gem-book/themes/cyberpunk.json
@@ -2,6 +2,5 @@
   "backgroundColor": "rgb(10, 23, 45)",
   "borderColor": "rgb(19, 61, 201)",
   "textColor": "rgb(11, 196, 207)",
-  "primaryColor": "rgb(240, 0, 219)",
-  "inlineCodeBackground": "#133DC9"
+  "primaryColor": "rgb(240, 0, 219)"
 }
diff --git a/packages/gem-book/themes/dark.json b/packages/gem-book/themes/dark.json
@@ -1,6 +1,5 @@
 {
   "backgroundColor": "#1a1a1a",
   "borderColor": "rgb(102, 102, 102)",
-  "textColor": "rgb(240, 240, 240)",
-  "inlineCodeBackground": "#ffe56433"
+  "textColor": "rgb(240, 240, 240)"
 }
diff --git a/packages/gem/docs/en/004-blog/001-create-standard-element.md b/packages/gem/docs/en/004-blog/001-create-standard-element.md
@@ -142,11 +142,33 @@ If you need to render many instances at once, you can use `isAsync` to create as
 @customElement('my-element')
 class MyElement extends GemElement {
   constructor() {
-    super({ isAsync: ture });
+    super({ isAsync: true });
   }
 }
 ```
 
+### Styling
+
+Suppose you use the `<my-element>` element defined above somewhere else, and for some reason add the `hidden` attribute in the hope of temporarily hiding it:
+
+```ts
+html`<my-element hidden>My content</my-element>`;
+```
+
+You will look that the `hidden` attribute does not take effect because the custom element's style `display: contents` will override the browser style `display: none`,
+so the `:host` style should be defined carefully to avoid making it difficult for external use, such as using [`:where`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where):
+
+```css
+:host(:where(:not([hidden]))) {
+  display: contents;
+}
+```
+
+In addition, use [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) to solve the problem of [multi-state](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet) style coverage of elements; use [CSS Nesting](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting) simplified stylesheets.
+
+> [!WARNING]
+> Chrome 中 `:host` 不能使用 CSS 嵌套, [Bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1442408)
+
 ### Accessibility
 
 When users use custom elements, they can use the `role`,`aria-*` attributes to specify the semantics of the element:

diff --git a/packages/gem/docs/zh/004-blog/001-create-standard-element.md b/packages/gem/docs/zh/004-blog/001-create-standard-element.md
@@ -142,11 +142,33 @@ class MyElement extends GemElement {}
 @customElement('my-element')
 class MyElement extends GemElement {
   constructor() {
-    super({ isAsync: ture });
+    super({ isAsync: true });
   }
 }
 ```
 
+### 样式
+
+假设在其他地方使用上面定义的`<my-element>`元素，出于某种原因添加 `hidden` 属性希望暂时隐藏它：
+
+```ts
+html`<my-element hidden>My content</my-element>`;
+```
+
+会发现 `hidden` 属性没有生效，原因是自定义元素的样式 `display: contents` 将覆盖浏览器样式 `display: none`,
+所以应该小心定义 `:host` 样式避免为外部使用时增加难度，例如使用 [`:where`](https://developer.mozilla.org/en-US/docs/Web/CSS/:where)：
+
+```css
+:host(:where(:not([hidden]))) {
+  display: contents;
+}
+```
+
+此外，使用 [`@layer`](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) 解决元素[多状态](https://developer.mozilla.org/en-US/docs/Web/API/CustomStateSet)样式覆盖的问题；使用 [CSS 嵌套](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting) 简化样式表。
+
+> [!WARNING]
+> Chrome 中 `:host` 不能使用 CSS 嵌套, [Bug](https://bugs.chromium.org/p/chromium/issues/detail?id=1442408)
+
 ### 可访问性
 
 在用户使用自定义元素时，他们可以用 `role`,`aria-*` 属性指定元素的语义:

diff --git a/packages/gem/src/lib/element.ts b/packages/gem/src/lib/element.ts
@@ -318,12 +318,11 @@ export abstract class GemElement<T = Record<string, unknown>> extends HTMLElemen
     const styles = useNativeCSSStyleSheet
       ? ''
       : html`${this.shadowRoot?.adoptedStyleSheets?.map(
-          (e: any) =>
-            html`
-              <style media=${e.media.mediaText}>
-                ${e.style}
-              </style>
-            `,
+          (e: any) => html`
+            <style media=${e.media.mediaText}>
+              ${e.style}
+            </style>
+          `,
         )}`;
     if (this.render) {
       const r = this.render();