feat: add only property to filter elements (#153)

Author: bashmish

.changeset/rare-numbers-hide.md

@@ -0,0 +1,9 @@
+---
+'@api-viewer/common': patch
+'@api-viewer/demo': patch
+'@api-viewer/docs': patch
+'api-viewer-element': patch
+'@api-viewer/tabs': patch
+---
+
+Add only property to filter elements

docs/docs/api/properties.md

@@ -31,6 +31,14 @@ Use `manifest` property instead of `src` to pass manifest data directly:
 </script>
 ```
 
+### `only`
+
+Use `only` to display API only for one or a few elements in the scope of a certain documentation page and filter out the rest.
+
+```html
+<api-viewer src="./custom-elements.json" only="my-el,my-other-el"></api-viewer>
+```
+
 ### `selected`
 
 Use `selected` property to configure the displayed element.

packages/api-common/src/manifest-mixin.ts

@@ -10,6 +10,8 @@ export interface ManifestMixinInterface {
 
   manifest?: Package;
 
+  only?: string[];
+
   selected?: string;
 
   jsonFetched: Promise<Package | null>;
@@ -28,6 +30,15 @@ export const ManifestMixin = <T extends Constructor<LitElement>>(
     @property({ attribute: false })
     manifest?: Package;
 
+    @property({
+      reflect: true,
+      converter: {
+        fromAttribute: (value: string) => value.split(','),
+        toAttribute: (value: string[]) => value.join(',')
+      }
+    })
+    only?: string[];
+
     @property() selected?: string;
 
     jsonFetched: Promise<Package | null> = Promise.resolve(null);

packages/api-common/src/manifest.ts

@@ -65,10 +65,14 @@ export async function fetchManifest(src: string): Promise<Package | null> {
   }
 }
 
-export function getCustomElements(manifest: Package): CustomElementExport[] {
-  return (manifest.modules ?? []).flatMap(
+export function getCustomElements(
+  manifest: Package,
+  only?: string[]
+): CustomElementExport[] {
+  const exports = (manifest.modules ?? []).flatMap(
     (x) => x.exports?.filter(isCustomElementExport) ?? []
   );
+  return only ? exports.filter((e) => only.includes(e.name)) : exports;
 }
 
 export const getElementData = (

packages/api-demo/src/base.ts

@@ -16,6 +16,7 @@ import './layout.js';
 async function renderDemo(
   jsonFetched: Promise<Package | null>,
   onSelect: (e: CustomEvent) => void,
+  only?: string[],
   selected?: string,
   id?: number,
   exclude = ''
@@ -26,7 +27,7 @@ async function renderDemo(
     return emptyDataWarning;
   }
 
-  const elements = getCustomElements(manifest);
+  const elements = getCustomElements(manifest, only);
 
   const data = getElementData(manifest, selected) as CustomElement;
   const props = getPublicFields(data.members);
@@ -81,6 +82,7 @@ export class ApiDemoBase extends ManifestMixin(LitElement) {
         renderDemo(
           this.jsonFetched,
           this._onSelect,
+          this.only,
           this.selected,
           this._id,
           this.excludeKnobs

packages/api-docs/src/base.ts

@@ -17,6 +17,7 @@ import './layout.js';
 async function renderDocs(
   jsonFetched: Promise<Package | null>,
   onSelect: (e: CustomEvent) => void,
+  only?: string[],
   selected?: string
 ): Promise<TemplateResult> {
   const manifest = await jsonFetched;
@@ -25,7 +26,7 @@ async function renderDocs(
     return emptyDataWarning;
   }
 
-  const elements = getCustomElements(manifest);
+  const elements = getCustomElements(manifest, only);
 
   const data = getElementData(manifest, selected) as CustomElement;
   const props = getPublicFields(data.members);
@@ -69,7 +70,7 @@ async function renderDocs(
 export class ApiDocsBase extends ManifestMixin(LitElement) {
   protected render(): TemplateResult {
     return html`${until(
-      renderDocs(this.jsonFetched, this._onSelect, this.selected)
+      renderDocs(this.jsonFetched, this._onSelect, this.only, this.selected)
     )}`;
   }
 

packages/api-viewer/package.json

@@ -59,7 +59,7 @@
   "size-limit": [
     {
       "path": "lib/api-viewer.js",
-      "limit": "38.6 KB"
+      "limit": "38.7 KB"
     }
   ]
 }

packages/api-viewer/src/base.ts

@@ -23,6 +23,7 @@ async function renderDocs(
   section: string,
   onSelect: (e: CustomEvent) => void,
   onToggle: (e: CustomEvent) => void,
+  only?: string[],
   selected?: string,
   id?: number,
   exclude = ''
@@ -33,7 +34,7 @@ async function renderDocs(
     return emptyDataWarning;
   }
 
-  const elements = getCustomElements(manifest);
+  const elements = getCustomElements(manifest, only);
 
   const data = getElementData(manifest, selected) as CustomElement;
   const props = getPublicFields(data.members);
@@ -134,6 +135,7 @@ export class ApiViewerBase extends ManifestMixin(LitElement) {
           this.section,
           this._onSelect,
           this._onToggle,
+          this.only,
           this.selected,
           this._id,
           this.excludeKnobs