From 20f3e36bdeb1c99cfde6df25e26601b0db5cf14e Mon Sep 17 00:00:00 2001 From: Lassepitkanen Date: Sat, 19 Oct 2024 15:33:56 +0300 Subject: [PATCH 1/3] feat: support deprecated --- docs/docs/api/styling.md | 48 +++++++------- packages/api-common/src/shared-styles.ts | 1 + packages/api-docs/src/layout.ts | 80 ++++++++++++++++++++---- packages/api-docs/src/styles.ts | 8 +++ 4 files changed, 101 insertions(+), 36 deletions(-) diff --git a/docs/docs/api/styling.md b/docs/docs/api/styling.md index 5aaa223..bffb427 100644 --- a/docs/docs/api/styling.md +++ b/docs/docs/api/styling.md @@ -4,29 +4,30 @@ The following custom CSS properties are available: -| Property | Description | -| -------------------------------- | ----------------------------------------------- | -| `--ave-accent-color` | Accent color, used for property / method names | -| `--ave-border-color` | Color used for borders and dividers | -| `--ave-border-radius` | Border radius used for the outer border | -| `--ave-button-active-background` | Color of the `:focus` and `:hover` button | -| `--ave-button-background` | Background of the button (code snippet, events) | -| `--ave-button-color` | Color of the button (code snippet, events) | -| `--ave-header-background` | Background of the header used for tag name | -| `--ave-header-color` | Header text color used for tag name | -| `--ave-item-color` | API items content color (main text) | -| `--ave-label-color` | API items labels color | -| `--ave-link-color` | API description links default color | -| `--ave-link-hover-color` | API description links hover color | -| `--ave-monospace-font` | Monospace font stack for the API items | -| `--ave-primary-color` | Primary color, used for header and active tab | -| `--ave-secondary-color` | Color used for method types in API docs | -| `--ave-tab-color` | Inactive tabs color | -| `--ave-tab-selected-color` | Selected tab color | -| `--ave-tab-indicator-size` | Size of the selected tab indicator | -| `--ave-tag-background-color` | Background color of tags (e.g., `static`) | -| `--ave-tag-border-color` | Color of tag borders | -| `--ave-tag-color` | Color of tags | +| Property | Description | +| ----------------------------------- | ----------------------------------------------- | +| `--ave-accent-color` | Accent color, used for property / method names | +| `--ave-border-color` | Color used for borders and dividers | +| `--ave-border-radius` | Border radius used for the outer border | +| `--ave-button-active-background` | Color of the `:focus` and `:hover` button | +| `--ave-button-background` | Background of the button (code snippet, events) | +| `--ave-button-color` | Color of the button (code snippet, events) | +| `--ave-header-background` | Background of the header used for tag name | +| `--ave-header-color` | Header text color used for tag name | +| `--ave-item-color` | API items content color (main text) | +| `--ave-deprecated-background-color` | API items deprecated background color | +| `--ave-label-color` | API items labels color | +| `--ave-link-color` | API description links default color | +| `--ave-link-hover-color` | API description links hover color | +| `--ave-monospace-font` | Monospace font stack for the API items | +| `--ave-primary-color` | Primary color, used for header and active tab | +| `--ave-secondary-color` | Color used for method types in API docs | +| `--ave-tab-color` | Inactive tabs color | +| `--ave-tab-selected-color` | Selected tab color | +| `--ave-tab-indicator-size` | Size of the selected tab indicator | +| `--ave-tag-background-color` | Background color of tags (e.g., `static`) | +| `--ave-tag-border-color` | Color of tag borders | +| `--ave-tag-color` | Color of tags | ## CSS shadow parts @@ -60,6 +61,7 @@ The following CSS shadow parts are available: | `docs-row` | Row containing columns. Child of a `docs-item` part | | `docs-value` | Sibling of a `docs-label` part (name, attribute, type) | | `docs-value` | Sibling of a `docs-label` part (name, attribute, type) | +| `docs-deprecated` | Description for deprecated item | | `md-h1` | Markdown `

` elements | | `md-h2` | Markdown `

` elements | | `md-h3` | Markdown `

` elements | diff --git a/packages/api-common/src/shared-styles.ts b/packages/api-common/src/shared-styles.ts index 3c66d9c..ec2a8ba 100644 --- a/packages/api-common/src/shared-styles.ts +++ b/packages/api-common/src/shared-styles.ts @@ -21,6 +21,7 @@ export default css` --ave-header-color: #fff; --ave-item-color: rgba(0, 0, 0, 0.87); --ave-label-color: #424242; + --ave-deprecated-background-color: #fcc7c7; --ave-link-color: #01579b; --ave-link-hover-color: #d63200; --ave-tab-indicator-size: 2px; diff --git a/packages/api-docs/src/layout.ts b/packages/api-docs/src/layout.ts index ac3e8b6..6efab99 100644 --- a/packages/api-docs/src/layout.ts +++ b/packages/api-docs/src/layout.ts @@ -6,6 +6,7 @@ import { type TemplateResult } from 'lit'; import { property } from 'lit/decorators/property.js'; +import { classMap } from 'lit/directives/class-map.js'; import { unquote, type Attribute, @@ -27,9 +28,10 @@ const renderItem = ( value?: unknown, attribute?: string, isStatic?: boolean, - reflects?: boolean + reflects?: boolean, + deprecated?: boolean | string ): TemplateResult => html` -
+
${isStatic || reflects ? html`
${isStatic ? html`
static
` : nothing} @@ -68,6 +70,12 @@ const renderItem = (
Description
${parse(description)}
+
+ ${deprecated === true ? 'Deprecated' : deprecated} +
`; @@ -173,7 +181,8 @@ class ApiDocsLayout extends LitElement { description, type, static: isStatic, - reflects + reflects, + deprecated } = prop; const attribute = attrs.find((x) => x.fieldName === name); return renderItem( @@ -184,7 +193,8 @@ class ApiDocsLayout extends LitElement { prop.default, attribute?.name, isStatic, - reflects + reflects, + deprecated ); })} ` @@ -203,7 +213,17 @@ class ApiDocsLayout extends LitElement { methods, html` ${methods.map((method) => - renderItem('method', renderMethod(method), method.description) + renderItem( + 'method', + renderMethod(method), + method.description, + undefined, + undefined, + undefined, + undefined, + undefined, + method.deprecated + ) )} ` )} @@ -211,8 +231,18 @@ class ApiDocsLayout extends LitElement { 'Slots', slots, html` - ${slots.map(({ name, description }) => - renderItem('slot', name, description) + ${slots.map(({ name, description, deprecated }) => + renderItem( + 'slot', + name, + description, + undefined, + undefined, + undefined, + undefined, + undefined, + deprecated + ) )} ` )} @@ -220,8 +250,18 @@ class ApiDocsLayout extends LitElement { 'Events', events, html` - ${events.map(({ name, description }) => - renderItem('event', name, description) + ${events.map(({ name, description, deprecated }) => + renderItem( + 'event', + name, + description, + undefined, + undefined, + undefined, + undefined, + undefined, + deprecated + ) )} ` )} @@ -230,13 +270,17 @@ class ApiDocsLayout extends LitElement { cssProps, html` ${cssProps.map((prop) => { - const { name, description } = prop; + const { name, description, deprecated } = prop; return renderItem( 'css', name, description, '', // TODO: manifest does not provide type for CSS custom properties - unquote(prop.default) + unquote(prop.default), + undefined, + undefined, + undefined, + deprecated ); })} ` @@ -245,8 +289,18 @@ class ApiDocsLayout extends LitElement { 'CSS Shadow Parts', cssParts, html` - ${cssParts.map(({ name, description }) => - renderItem('part', name, description) + ${cssParts.map(({ name, description, deprecated }) => + renderItem( + 'part', + name, + description, + undefined, + undefined, + undefined, + undefined, + undefined, + deprecated + ) )} ` )} diff --git a/packages/api-docs/src/styles.ts b/packages/api-docs/src/styles.ts index 7a76469..9e9ca98 100644 --- a/packages/api-docs/src/styles.ts +++ b/packages/api-docs/src/styles.ts @@ -96,6 +96,14 @@ export default css` margin: 0.5rem 0; } + [part='docs-deprecated'] { + font-style: italic; + } + + .deprecated { + background: var(--ave-deprecated-background-color); + } + [part$='params'] { color: var(--ave-item-color); } From a4ce170aa32c668c28c07947e33de601be3d5ec8 Mon Sep 17 00:00:00 2001 From: Lassepitkanen Date: Sat, 19 Oct 2024 15:41:08 +0300 Subject: [PATCH 2/3] chore: add changeset --- .changeset/tall-dots-learn.md | 9 +++++++++ 1 file changed, 9 insertions(+) create mode 100644 .changeset/tall-dots-learn.md diff --git a/.changeset/tall-dots-learn.md b/.changeset/tall-dots-learn.md new file mode 100644 index 0000000..0b4d5cb --- /dev/null +++ b/.changeset/tall-dots-learn.md @@ -0,0 +1,9 @@ +--- +'@api-viewer/common': patch +'@api-viewer/docs': patch +'@api-viewer/demo': patch +'@api-viewer/tabs': patch +'api-viewer-element': patch +--- + +Support deprecated props, slots, events, methods and css From 455d66314d5097b020b91ef95d8e2aad7841ccba Mon Sep 17 00:00:00 2001 From: Lassepitkanen Date: Sun, 20 Oct 2024 14:43:55 +0300 Subject: [PATCH 3/3] feat: deprecated components --- .changeset/tall-dots-learn.md | 2 +- docs/docs/api/styling.md | 69 +++++++++++++++-------------- packages/api-common/src/manifest.ts | 3 +- packages/api-docs/src/base.ts | 13 +++++- packages/api-docs/src/layout.ts | 2 +- packages/api-docs/src/styles.ts | 8 +++- packages/api-viewer/src/base.ts | 14 +++++- 7 files changed, 69 insertions(+), 42 deletions(-) diff --git a/.changeset/tall-dots-learn.md b/.changeset/tall-dots-learn.md index 0b4d5cb..8786a65 100644 --- a/.changeset/tall-dots-learn.md +++ b/.changeset/tall-dots-learn.md @@ -6,4 +6,4 @@ 'api-viewer-element': patch --- -Support deprecated props, slots, events, methods and css +Support deprecated components, props, slots, events, methods and css diff --git a/docs/docs/api/styling.md b/docs/docs/api/styling.md index bffb427..952bd89 100644 --- a/docs/docs/api/styling.md +++ b/docs/docs/api/styling.md @@ -45,40 +45,41 @@ The following CSS shadow parts are available: ### API docs -| Part | Description | -| -------------------------| --------------------------------------------------------| -| `docs-description` | Custom element description placed under the header | -| `docs-container` | The wrapper element placed under the description | -| `docs-column` | Column, child of a `docs-row` part | -| `docs-item` | Item representing a single entry (property, event etc) | -| `docs-label` | Label (name, attribute, type, description) | -| `docs-markdown` | Item description with parsed markdown content | -| `docs-method` | Method name with its params and return type | -| `docs-method-params` | Comma-separated list of method params their types | -| `docs-method-type` | Return type of a method, or "void" if not specified | -| `docs-param-name` | Name of a method parameter | -| `docs-param-type` | Type of a method parameter | -| `docs-row` | Row containing columns. Child of a `docs-item` part | -| `docs-value` | Sibling of a `docs-label` part (name, attribute, type) | -| `docs-value` | Sibling of a `docs-label` part (name, attribute, type) | -| `docs-deprecated` | Description for deprecated item | -| `md-h1` | Markdown `

` elements | -| `md-h2` | Markdown `

` elements | -| `md-h3` | Markdown `

` elements | -| `md-h4` | Markdown `

` elements | -| `md-h5` | Markdown `

` elements | -| `md-h6` | Markdown `
` elements | -| `md-a` | Markdown `` elements | -| `md-p` | Markdown `

` elements | -| `md-ul` | Markdown `