diff --git a/.changeset/tall-dots-learn.md b/.changeset/tall-dots-learn.md new file mode 100644 index 0000000..8786a65 --- /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 components, props, slots, events, methods and css diff --git a/docs/docs/api/styling.md b/docs/docs/api/styling.md index 5aaa223..952bd89 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 @@ -44,39 +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) | -| `md-h1` | Markdown `
` elements | -| `md-ul` | Markdown `
` elements |
-| `md-code` | Markdown `` elements |
-| `md-strong` | Markdown `` elements |
-| `md-em` | Markdown `` elements |
-| `md-blockquote` | Markdown `` elements |
-| `md-del` | Markdown `` elements |
+| 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-item` | Description for deprecated item |
+| `docs-deprecated-component` | Description for deprecated component |
+| `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 `
` elements |
+| `md-ol` | Markdown `` elements |
+| `md-li` | Markdown `- ` elements |
+| `md-pre` | Markdown `
` elements |
+| `md-code` | Markdown `` elements |
+| `md-strong` | Markdown `` elements |
+| `md-em` | Markdown `` elements |
+| `md-blockquote` | Markdown `` elements |
+| `md-del` | Markdown `` elements |
### Live demo
diff --git a/packages/api-common/src/manifest.ts b/packages/api-common/src/manifest.ts
index 445af20..94070f8 100644
--- a/packages/api-common/src/manifest.ts
+++ b/packages/api-common/src/manifest.ts
@@ -124,7 +124,8 @@ export const getElementData = (
// TODO: analyzer should sort CSS custom properties
cssProperties: [...(decl.cssProperties ?? [])].sort((a, b) =>
a.name > b.name ? 1 : -1
- )
+ ),
+ deprecated: decl.deprecated
};
};
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/base.ts b/packages/api-docs/src/base.ts
index 3d28554..cae9ad0 100644
--- a/packages/api-docs/src/base.ts
+++ b/packages/api-docs/src/base.ts
@@ -10,6 +10,7 @@ import {
ManifestMixin,
type Package
} from '@api-viewer/common/lib/index.js';
+import { classMap } from 'lit/directives/class-map.js';
import { parse } from './utils/markdown.js';
import './layout.js';
@@ -49,8 +50,16 @@ async function renderDocs(
-
- ${parse(data.description)}
+
+
+ ${data.deprecated === true ? 'Deprecated' : data.deprecated}
+
+
+ ${parse(data.description)}
+
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..e0446db 100644
--- a/packages/api-docs/src/styles.ts
+++ b/packages/api-docs/src/styles.ts
@@ -96,6 +96,20 @@ export default css`
margin: 0.5rem 0;
}
+ [part='docs-deprecated-item'] {
+ font-style: italic;
+ }
+
+ [part='docs-deprecated-component'] {
+ font-style: italic;
+ display: block;
+ padding: 0.5rem 1rem;
+ }
+
+ .deprecated {
+ background: var(--ave-deprecated-background-color);
+ }
+
[part$='params'] {
color: var(--ave-item-color);
}
diff --git a/packages/api-viewer/src/base.ts b/packages/api-viewer/src/base.ts
index 949320e..d47e6b0 100644
--- a/packages/api-viewer/src/base.ts
+++ b/packages/api-viewer/src/base.ts
@@ -1,4 +1,5 @@
import { LitElement, html, type TemplateResult } from 'lit';
+import { classMap } from 'lit/directives/class-map.js';
import { property } from 'lit/decorators/property.js';
import { cache } from 'lit/directives/cache.js';
import { until } from 'lit/directives/until.js';
@@ -80,8 +81,17 @@ async function renderDocs(
${cache(
section === 'docs'
? html`
-
- ${parse(data.description)}
+
+
+ ${data.deprecated === true ? 'Deprecated' : data.deprecated}
+
+
+ ${parse(data.description)}
+