From dcd07598d1feef7927e19b8d9cddf7e4c1f97a21 Mon Sep 17 00:00:00 2001 From: mantou132 <709922234@qq.com> Date: Sun, 3 Dec 2023 20:34:43 +0800 Subject: [PATCH] Update docs --- packages/duoyun-ui/src/lib/styles.ts | 4 --- .../gem-book/src/element/elements/main.ts | 29 ++++++++----------- .../src/element/helper/default-theme.ts | 1 - packages/gem-book/src/element/helper/theme.ts | 5 ++++ packages/gem-book/themes/cyberpunk.json | 3 +- packages/gem-book/themes/dark.json | 3 +- .../004-blog/001-create-standard-element.md | 24 ++++++++++++++- .../004-blog/001-create-standard-element.md | 24 ++++++++++++++- packages/gem/src/lib/element.ts | 11 ++++--- 9 files changed, 70 insertions(+), 34 deletions(-) diff --git a/packages/duoyun-ui/src/lib/styles.ts b/packages/duoyun-ui/src/lib/styles.ts index 11fdb456..e2bc173e 100644 --- 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 index 484a111d..22a253bd 100644 --- 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 index 2d1025f7..cc33879e 100644 --- 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 index e678d4c3..fafd9ce4 100644 --- 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 index 155aa36e..c38d7741 100644 --- 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 index 87cdcc9a..046e5f03 100644 --- 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 index 6ae575fe..d3f78e5f 100644 --- 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 `` element defined above somewhere else, and for some reason add the `hidden` attribute in the hope of temporarily hiding it: + +```ts +html``; +``` + +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 index eaf982c0..120708e3 100644 --- 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 }); } } ``` +### 样式 + +假设在其他地方使用上面定义的``元素，出于某种原因添加 `hidden` 属性希望暂时隐藏它： + +```ts +html``; +``` + +会发现 `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 index 98e2bc1a..c6794e78 100644 --- a/packages/gem/src/lib/element.ts +++ b/packages/gem/src/lib/element.ts @@ -318,12 +318,11 @@ export abstract class GemElement> extends HTMLElemen const styles = useNativeCSSStyleSheet ? '' : html`${this.shadowRoot?.adoptedStyleSheets?.map( - (e: any) => - html` - - `, + (e: any) => html` + + `, )}`; if (this.render) { const r = this.render();