add filter tokens, list examples, more metadata in actions

Author: Simek

README.md

@@ -1,12 +1,24 @@
 <dd align="center"><img alt="React Native Directory Logo" height="96" src="./assets/icon.png" /></dd>
 <h1 align="center">vscode-react-native-directory</h1>
 
-A VS Code extension allowing to browse through React Native Directory and perform actions on the packages inside build-in Command Palette.
+A VS Code extension allowing to browse through React Native Directory and perform actions related to the chosen package
+inside build-in Command Palette.
 
 <p align="center">
-<img alt="Extension preview" src="./assets/screenshot.png" width="520" align="center" />
+<img alt="Search mode" src="./assets/screenshot.png" width="500" align="center" />
+<img alt="Actions list" src="./assets/screenshot-actions.png" width="500" align="center" />
 </p>
 
+## ⚡️ Features
+
+* Search through the packages registered in the React Native Directory.
+* Narrow down the results by using filter tokens, such as `:ios`, `:newArchitecture`, or `:hasTypes`.
+  * Valid tokens are a subset of all possible API query options, and the values can be seen [in this file](https://github.com/react-native-community/vscode-react-native-directory/blob/main/src/utils.ts#L33).
+* Install the selected packages in the current workspace using your preferred package manager.
+* Dive deep into the stats and analysis with the provided metadata and links.
+
+## Preview
+
 ## 📦 Installation
 
 > [!tip]

assets/screenshot-actions.png

@@ -3,7 +3,16 @@ import * as vscode from 'vscode';
 import { QuickPickItemKind } from 'vscode';
 import preferredPM from 'preferred-pm';
 import { DirectoryEntry } from './types';
-import { ENTRY_OPTION, fetchData, getCommandToRun, STRINGS } from './utils';
+import {
+  ENTRY_OPTION,
+  fetchData,
+  getCommandToRun,
+  KEYWORD_REGEX,
+  numberFormatter,
+  STRINGS,
+  VALID_KEYWORDS_MAP,
+  ValidKeyword
+} from './utils';
 
 export async function activate(context: vscode.ExtensionContext) {
   const workspacePath = vscode.workspace.workspaceFolders?.[0].uri.fsPath ?? vscode.workspace.rootPath;
@@ -16,7 +25,7 @@ export async function activate(context: vscode.ExtensionContext) {
     const packagesPick = vscode.window.createQuickPick<DirectoryEntry>();
 
     packagesPick.placeholder = STRINGS.PLACEHOLDER_BUSY;
-    packagesPick.title = 'Search in React Native Directory';
+    packagesPick.title = STRINGS.DEFAULT_TITLE;
     packagesPick.matchOnDescription = false;
     packagesPick.matchOnDetail = false;
     packagesPick.busy = true;
@@ -29,31 +38,72 @@ export async function activate(context: vscode.ExtensionContext) {
 
     packagesPick.onDidChangeValue(async (value) => {
       packagesPick.busy = true;
-      packagesPick.title = 'Search in React Native Directory';
-      packagesPick.items = await fetchData(value);
+
+      if (value.includes(':')) {
+        const keywords = (value.match(KEYWORD_REGEX) ?? []).map((token) => token.slice(1));
+        const searchString = value.replace(KEYWORD_REGEX, '').trim();
+
+        const validKeywords = keywords
+          .map((keyword) => keyword.toLowerCase())
+          .filter((keyword): keyword is ValidKeyword => keyword in VALID_KEYWORDS_MAP)
+          .map((keyword) => VALID_KEYWORDS_MAP[keyword] as ValidKeyword);
+
+        if (validKeywords.length > 0) {
+          packagesPick.title = `Active filters: ${validKeywords.join(', ')}`;
+        } else {
+          packagesPick.title = STRINGS.DEFAULT_TITLE;
+        }
+        packagesPick.items = await fetchData(searchString, validKeywords);
+      } else {
+        packagesPick.items = await fetchData(value);
+      }
+
       packagesPick.busy = false;
     });
 
     packagesPick.onDidAccept(() => {
       const selectedEntry = packagesPick.selectedItems[0];
 
+      const examplesActions =
+        selectedEntry.examples && selectedEntry.examples.length > 0
+          ? [
+              { label: 'view examples', kind: QuickPickItemKind.Separator },
+              ...selectedEntry.examples.map((example, index) => ({
+                label: `Example #${index + 1}`,
+                description: example
+              }))
+            ]
+          : [];
+
       const possibleActions = [
         workspacePath && {
           label: ENTRY_OPTION.INSTALL,
           description: `with ${preferredManager}${selectedEntry.dev ? ' as devDependency' : ''}`
         },
         { label: `open URLs`, kind: QuickPickItemKind.Separator },
+        {
+          label: ENTRY_OPTION.VISIT_REPO,
+          description: [
+            `$(star) ${numberFormatter.format(selectedEntry.github.stats.stars)}`,
+            `$(gist-fork) ${numberFormatter.format(selectedEntry.github.stats.forks)}`
+          ].join(' ')
+        },
+        {
+          label: ENTRY_OPTION.VISIT_NPM,
+          description: selectedEntry.npm?.downloads
+            ? `$(arrow-circle-down) ${numberFormatter.format(selectedEntry.npm.downloads)}`
+            : ''
+        },
         selectedEntry.github.urls.homepage && {
           label: ENTRY_OPTION.VISIT_HOMEPAGE,
           description: selectedEntry.github.urls.homepage
         },
-        { label: ENTRY_OPTION.VISIT_REPO },
-        { label: ENTRY_OPTION.VISIT_NPM },
-        { label: ENTRY_OPTION.VIEW_BUNDLEPHOBIA },
         selectedEntry.github.license && {
           label: ENTRY_OPTION.VIEW_LICENSE,
           description: selectedEntry.github.license.name
         },
+        { label: ENTRY_OPTION.VIEW_BUNDLEPHOBIA },
+        ...examplesActions,
         { label: 'copy data', kind: QuickPickItemKind.Separator },
         { label: ENTRY_OPTION.COPY_NAME },
         { label: ENTRY_OPTION.COPY_REPO_URL },

src/extension.ts

@@ -3,7 +3,8 @@ import { type QuickPickItem } from 'vscode';
 export type DirectoryEntry = QuickPickItem & PackageData;
 
 /**
- * Mirror of https://github.com/react-native-community/directory/blob/main/types/index.ts#L41
+ * Mirror of React Native Directory library type.
+ * @see https://github.com/react-native-community/directory/blob/main/types/index.ts#L41
  */
 export type PackageData = {
   githubUrl: string;

src/types.ts

@@ -3,7 +3,8 @@ import axios from 'axios';
 
 import { DirectoryEntry, PackageData } from './types';
 
-const BASE_API_URL = 'https://reactnative.directory/api/libraries';
+export const BASE_API_URL = 'https://reactnative.directory/api/libraries';
+export const KEYWORD_REGEX = /:\w+/g;
 
 export const numberFormatter = new Intl.NumberFormat('en-EN', { notation: 'compact' });
 
@@ -21,10 +22,35 @@ export enum ENTRY_OPTION {
 }
 
 export enum STRINGS {
+  DEFAULT_TITLE = 'Search in React Native Directory',
   PLACEHOLDER_BUSY = 'Loading directory data...',
   PLACEHOLDER = 'Search for a package'
 }
 
+/**
+ * A subset of API query params mapped with normalized (lowercased) keyword values.
+ * @see https://github.com/react-native-community/directory/blob/main/types/index.ts#L14
+ */
+export const VALID_KEYWORDS_MAP = {
+  android: 'android',
+  expogo: 'expoGo',
+  ios: 'ios',
+  macos: 'macos',
+  fireos: 'fireos',
+  tvos: 'tvos',
+  visionos: 'visionos',
+  web: 'web',
+  windows: 'windows',
+  hasexample: 'hasExample',
+  hasimage: 'hasImage',
+  hastypes: 'hasTypes',
+  ismaintained: 'isMaintained',
+  ispopular: 'isPopular',
+  wasrecentlyupdated: 'wasRecentlyUpdated',
+  newarchitecture: 'newArchitecture'
+};
+export type ValidKeyword = keyof typeof VALID_KEYWORDS_MAP;
+
 function getDetailLabel(item: PackageData) {
   const platforms = [
     item.android ? 'Android' : null,
@@ -42,8 +68,8 @@ function getDetailLabel(item: PackageData) {
     item.npm?.downloads && `$(arrow-circle-down) ${numberFormatter.format(item.npm.downloads)}`,
     '•',
     platforms.join(', '),
-    (item.newArchitecture || item.github.hasTypes) && '•',
-    item.newArchitecture && `$(verified) New Architecture`,
+    (item.newArchitecture || item.expoGo || item.github.hasTypes) && '•',
+    (item.newArchitecture || item.expoGo) && `$(verified) New Architecture`,
     item.github.hasTypes && `$(symbol-type-parameter) Types`
   ]
     .filter(Boolean)
@@ -61,7 +87,7 @@ export function getCommandToRun({ dev, npmPkg }: DirectoryEntry, preferredManage
   }
 }
 
-export async function fetchData(query?: string): Promise<DirectoryEntry[]> {
+export async function fetchData(query?: string, keywords?: ValidKeyword[]): Promise<DirectoryEntry[]> {
   try {
     const apiUrl = new URL(BASE_API_URL);
 
@@ -70,6 +96,10 @@ export async function fetchData(query?: string): Promise<DirectoryEntry[]> {
       apiUrl.searchParams.append('order', 'downloads');
     }
 
+    if (keywords) {
+      keywords.forEach((keyword) => apiUrl.searchParams.append(keyword, 'true'));
+    }
+
     const { data } = await axios.get(apiUrl.href);
 
     if ('libraries' in data && Array.isArray(data.libraries)) {