Skip to content

feat: support deprecated #211

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .changeset/tall-dots-learn.md
Original file line number Diff line number Diff line change
@@ -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
115 changes: 59 additions & 56 deletions docs/docs/api/styling.md
Original file line number Diff line number Diff line change
@@ -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 `<h1>` elements |
| `md-h2` | Markdown `<h2>` elements |
| `md-h3` | Markdown `<h3>` elements |
| `md-h4` | Markdown `<h4>` elements |
| `md-h5` | Markdown `<h5>` elements |
| `md-h6` | Markdown `<h6>` elements |
| `md-a` | Markdown `<a>` elements |
| `md-p` | Markdown `<p>` elements |
| `md-ul` | Markdown `<ul>` elements |
| `md-ol` | Markdown `<ol>` elements |
| `md-li` | Markdown `<li>` elements |
| `md-pre` | Markdown `<pre>` elements |
| `md-code` | Markdown `<code>` elements |
| `md-strong` | Markdown `<strong>` elements |
| `md-em` | Markdown `<em>` elements |
| `md-blockquote` | Markdown `<blockquote>` elements |
| `md-del` | Markdown `<del>` 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 `<h1>` elements |
| `md-h2` | Markdown `<h2>` elements |
| `md-h3` | Markdown `<h3>` elements |
| `md-h4` | Markdown `<h4>` elements |
| `md-h5` | Markdown `<h5>` elements |
| `md-h6` | Markdown `<h6>` elements |
| `md-a` | Markdown `<a>` elements |
| `md-p` | Markdown `<p>` elements |
| `md-ul` | Markdown `<ul>` elements |
| `md-ol` | Markdown `<ol>` elements |
| `md-li` | Markdown `<li>` elements |
| `md-pre` | Markdown `<pre>` elements |
| `md-code` | Markdown `<code>` elements |
| `md-strong` | Markdown `<strong>` elements |
| `md-em` | Markdown `<em>` elements |
| `md-blockquote` | Markdown `<blockquote>` elements |
| `md-del` | Markdown `<del>` elements |

### Live demo

3 changes: 2 additions & 1 deletion packages/api-common/src/manifest.ts
Original file line number Diff line number Diff line change
@@ -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
};
};

1 change: 1 addition & 0 deletions packages/api-common/src/shared-styles.ts
Original file line number Diff line number Diff line change
@@ -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;
13 changes: 11 additions & 2 deletions packages/api-docs/src/base.ts
Original file line number Diff line number Diff line change
@@ -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(
</label>
</nav>
</header>
<div ?hidden=${data.description === ''} part="docs-description">
${parse(data.description)}
<div class=${classMap({ deprecated: !!data.deprecated })}>
<div
?hidden=${data.deprecated === undefined || data.deprecated === false}
part="docs-deprecated-component"
>
${data.deprecated === true ? 'Deprecated' : data.deprecated}
</div>
<div ?hidden=${data.description === ''} part="docs-description">
${parse(data.description)}
</div>
</div>
<api-docs-layout
.name=${data.name}
80 changes: 67 additions & 13 deletions packages/api-docs/src/layout.ts
Original file line number Diff line number Diff line change
@@ -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`
<div part="docs-item">
<div part="docs-item" class=${classMap({ deprecated: !!deprecated })}>
${isStatic || reflects
? html`<div part="docs-row">
${isStatic ? html`<div part="docs-tag">static</div>` : nothing}
@@ -68,6 +70,12 @@ const renderItem = (
<div part="docs-label">Description</div>
<div part="docs-markdown">${parse(description)}</div>
</div>
<div
?hidden=${deprecated === undefined || deprecated === false}
part="docs-deprecated-item"
>
${deprecated === true ? 'Deprecated' : deprecated}
</div>
</div>
`;

@@ -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,25 +213,55 @@ 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
)
)}
`
)}
${renderTab(
'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
)
)}
`
)}
${renderTab(
'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
)
)}
`
)}
14 changes: 14 additions & 0 deletions packages/api-docs/src/styles.ts
Original file line number Diff line number Diff line change
@@ -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);
}
14 changes: 12 additions & 2 deletions packages/api-viewer/src/base.ts
Original file line number Diff line number Diff line change
@@ -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`
<div ?hidden=${data.description === ''} part="docs-description">
${parse(data.description)}
<div class=${classMap({ deprecated: !!data.deprecated })}>
<div
?hidden=${data.deprecated === undefined ||
data.deprecated === false}
part="docs-deprecated-component"
>
${data.deprecated === true ? 'Deprecated' : data.deprecated}
</div>
<div ?hidden=${data.description === ''} part="docs-description">
${parse(data.description)}
</div>
</div>
<api-docs-layout
.name=${data.name}