Skip to content
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.

Sign up for GitHub

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

feat: support deprecated #211

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

feat: support deprecated #211

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
20f3e36
feat: support deprecated
Lassepitkanen Oct 19, 2024
a4ce170
chore: add changeset
Lassepitkanen Oct 19, 2024
455d663
feat: deprecated components
Lassepitkanen Oct 20, 2024
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
View file
Open in desktop
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
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

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

Expand Down
1 change: 1 addition & 0 deletions packages/api-common/src/shared-styles.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down
13 changes: 11 additions & 2 deletions packages/api-docs/src/base.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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';

Expand Down Expand Up @@ -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}
Expand Down
80 changes: 67 additions & 13 deletions packages/api-docs/src/layout.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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}
Expand Down Expand Up @@ -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>
`;

Expand Down Expand Up @@ -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(
Expand All @@ -184,7 +193,8 @@ class ApiDocsLayout extends LitElement {
prop.default,
attribute?.name,
isStatic,
reflects
reflects,
deprecated
);
})}
`
Expand All @@ -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
)
)}
`
)}
Expand All @@ -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
);
})}
`
Expand All @@ -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
)
)}
`
)}
Expand Down
14 changes: 14 additions & 0 deletions packages/api-docs/src/styles.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
}
Expand Down
14 changes: 12 additions & 2 deletions packages/api-viewer/src/base.ts
View file
Open in desktop
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';
Expand Down Expand Up @@ -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}
Expand Down