An open source design system that's fully customizable and agent ready
TypeScript
feat(cli): expose hook in @xds/cli/api with types and parity coverage (#2558)
Joey66ea58193d0f
diff --git a/.github/scripts/api-cli-parity-test.mjs b/.github/scripts/api-cli-parity-test.mjsindex 4c82c83cf8..b7b880e597 100644--- a/.github/scripts/api-cli-parity-test.mjs+++ b/.github/scripts/api-cli-parity-test.mjs@@ -87,7 +87,16 @@ const allTopics = docsList.data && !docsList.errorconst categories = componentList.data ? Object.keys(componentList.data) : [];+const hookList = cliJson(['hook', '--list']);+const allHooks = hookList.data && !hookList.error+ ? Object.values(hookList.data).flat()+ : [];+const hookCategories = hookList.data && !hookList.error+ ? Object.keys(hookList.data)+ : [];+console.log(` ${allComponents.length} components, ${allTopics.length} doc topics, ${categories.length} categories`);+console.log(` ${allHooks.length} hooks, ${hookCategories.length} hook categories`);// ─── Build cases ──────────────────────────────────────────────────────────────//@@ -146,6 +155,32 @@ add('template --list', ['template', '--list'],add('template nonexistent', ['template', 'nonexistent99'],() => apiCall(api.template, 'nonexistent99'));+// Hook — list variants+add('hook --list', ['hook', '--list'],+ () => apiCall(api.hook, undefined, {list: true, cwd: ROOT}));++for (const cat of hookCategories) {+ add(`hook --category ${cat}`, ['hook', '--category', cat],+ () => apiCall(api.hook, undefined, {category: cat, cwd: ROOT}));+}++// Hook — every discovered hook+for (const name of allHooks) {+ add(`hook ${name}`, ['hook', name],+ () => apiCall(api.hook, name, {cwd: ROOT}));+}++// Hook — params (sample)+const hookSample = allHooks[0];+if (hookSample) {+ add(`hook ${hookSample} --params`, ['hook', hookSample, '--params'],+ () => apiCall(api.hook, hookSample, {params: true, cwd: ROOT}));+}++// Hook — error+add('hook NotARealHook99', ['hook', 'NotARealHook99'],+ () => apiCall(api.hook, 'NotARealHook99', {cwd: ROOT}));+// Other commands — probe with safe read-only args (no API yet)const otherCommands = [['swizzle', '--list'],diff --git a/packages/cli/README.md b/packages/cli/README.mdindex ca09f81b37..fbbcdd8399 100644--- a/packages/cli/README.md+++ b/packages/cli/README.md@@ -57,7 +57,7 @@ Errors:The same logic that powers `xds --json` is available as importable, type-safe functions:```typescript-import {component, docs, discover, template, XDSError} from '@xds/cli/api';+import {component, docs, discover, template, hook, XDSError} from '@xds/cli/api';// Same result as: xds --json component Buttonconst btn = await component('Button');@@ -72,6 +72,10 @@ list.data; // Record<string, string[]>const principles = await docs('principles');principles.data.title; // 'XDS Principles'+// Same result as: xds --json hook useMediaQuery+const useMediaQuery = await hook('useMediaQuery');+useMediaQuery.data.params; // typed as HookParamDoc[]+// Errors throw XDSError with optional .suggestionstry {await component('Buttn');@@ -133,9 +137,10 @@ Every response has a `type` string that uniquely identifies it:| `xds --json template <name> --skeleton` | `template.skeleton` | `TemplateSkeletonResponse` || `xds --json template <name> [path]` | `template.copy` | `TemplateCopyResponse` || `xds --json hook [--list]` | `hook.list` | `HookListResponse` |-| `xds --json hook --list --detail compact` | `hook.brief` | (untyped envelope) |-| `xds --json hook --list --detail full` | `hook.full` | (untyped envelope) |+| `xds --json hook --list --detail compact` | `hook.brief` | `HookBriefResponse` |+| `xds --json hook --list --detail full` | `hook.full` | `HookFullResponse` || `xds --json hook <name>` | `hook.detail` | `HookDetailResponse` |+| `xds --json hook <name> --params` | `hook.detail.params` | `HookDetailParamsResponse` || `xds --json swizzle [--list]` | `swizzle.list` | `SwizzleListResponse` || `xds --json swizzle <component>` | `swizzle.copy` | `SwizzleCopyResponse` || `xds --json theme build <file>` | `theme.build` | `ThemeBuildResponse` |diff --git a/packages/cli/src/api/hook.mjs b/packages/cli/src/api/hook.mjsindex 7778ae202f..0a4c75c75e 100644--- a/packages/cli/src/api/hook.mjs+++ b/packages/cli/src/api/hook.mjs@@ -20,7 +20,7 @@ import {XDSError} from './error.mjs';* @param {boolean} [options.list]* @param {string} [options.category]* @param {boolean} [options.params]- * @param {'full'|'compact'|'brief'} [options.detail]+ * @param {'full'|'compact'|'brief'} [options.detail] - Defaults to 'full' for a single hook, 'brief' for list views (list/category/no name), matching the CLI.* @param {string} [options.lang]* @param {boolean} [options.zh]* @returns {Promise<{type: string, data: unknown}>}@@ -31,11 +31,18 @@ export async function hook(name, options = {}) {list = false,category,params = false,- detail = 'full',+ detail: detailOption,lang = null,zh = false,} = options;+ // Default detail level mirrors the CLI (see commands/hook/index.mjs):+ // single-hook views default to 'full', list-style views (--list,+ // --category, or no name) default to 'brief' (scannable name lists).+ // Keeping this in sync with the CLI is what the API↔CLI parity test checks.+ const isListView = list || category != null || !name;+ const detail = detailOption ?? (isListView ? 'brief' : 'full');+const coreDir = findCoreDir(cwd);if (!coreDir) {throw new XDSError('Could not find @xds/core package');diff --git a/packages/cli/src/api/index.mjs b/packages/cli/src/api/index.mjsindex 442157b2c2..39fcaccb2a 100644--- a/packages/cli/src/api/index.mjs+++ b/packages/cli/src/api/index.mjs@@ -7,17 +7,21 @@* Errors throw XDSError (with optional .suggestions).** @example- * import { component, docs, XDSError } from '@xds/cli/api';+ * import { component, docs, hook, XDSError } from '@xds/cli/api';** const result = await component('Button');* // { type: 'component.detail', data: { name: 'Button', ... } }** const list = await component(undefined, { list: true });* // { type: 'component.list', data: { Layout: [...], ... } }+ *+ * const useMediaQuery = await hook('useMediaQuery');+ * // { type: 'hook.detail', data: { name: 'useMediaQuery', ... } }*/export {component} from './component.mjs';export {docs} from './docs.mjs';export {discover} from './discover.mjs';export {template} from './template.mjs';+export {hook} from './hook.mjs';export {XDSError} from './error.mjs';diff --git a/packages/cli/src/types/api.d.ts b/packages/cli/src/types/api.d.tsindex 05c199d64d..0641c370b7 100644--- a/packages/cli/src/types/api.d.ts+++ b/packages/cli/src/types/api.d.ts@@ -34,6 +34,13 @@ import type {TemplateCopyResponse,TemplateGetResponse,} from './template';+import type {+ HookListResponse,+ HookBriefResponse,+ HookFullResponse,+ HookDetailResponse,+ HookDetailParamsResponse,+} from './hook';/** Structured API error with optional suggestions. */export declare class XDSError extends Error {@@ -136,3 +143,27 @@ export declare function getTemplateById(id: string,options?: {cwd?: string},): Promise<TemplateGetResponse>;++// ── Hook ─────────────────────────────────────────────────────────────++export interface HookOptions {+ cwd?: string;+ list?: boolean;+ category?: string;+ params?: boolean;+ detail?: 'full' | 'compact' | 'brief';+ lang?: string;+ zh?: boolean;+}++type HookResult =+ | HookListResponse+ | HookBriefResponse+ | HookFullResponse+ | HookDetailResponse+ | HookDetailParamsResponse;++export declare function hook(+ name?: string,+ options?: HookOptions,+): Promise<HookResult>;diff --git a/packages/cli/src/types/base.d.ts b/packages/cli/src/types/base.d.tsindex c5858812d6..4766c28039 100644--- a/packages/cli/src/types/base.d.ts+++ b/packages/cli/src/types/base.d.ts@@ -34,6 +34,13 @@ import type {TemplateCopyResponse,TemplateGetResponse,} from './template';+import type {+ HookListResponse,+ HookBriefResponse,+ HookFullResponse,+ HookDetailResponse,+ HookDetailParamsResponse,+} from './hook';import type {SwizzleListResponse, SwizzleCopyResponse} from './swizzle';import type {ThemeBuildResponse} from './theme';import type {UpgradeListResponse, UpgradeRunResponse} from './upgrade';@@ -76,6 +83,11 @@ export type CLIAnyResponse =| TemplateSkeletonResponse| TemplateCopyResponse| TemplateGetResponse+ | HookListResponse+ | HookBriefResponse+ | HookFullResponse+ | HookDetailResponse+ | HookDetailParamsResponse| SwizzleListResponse| SwizzleCopyResponse| ThemeBuildResponsediff --git a/packages/cli/src/types/hook.d.ts b/packages/cli/src/types/hook.d.tsnew file mode 100644index 0000000000..36bf305aca--- /dev/null+++ b/packages/cli/src/types/hook.d.ts@@ -0,0 +1,59 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * Hook command JSON responses.+ *+ * Detail-level contract for list views (brief < compact < full):+ * --detail brief Names only. Smallest, most scannable. (DEFAULT for --list)+ * --detail compact Names + 1-line description + import path.+ * --detail full Full HookDoc per entry (params, returns, usage, etc.).+ *+ * Invocation -> type discriminator+ * ------------------------------------------------------------------+ * xds --json hook -> hook.list+ * xds --json hook --list -> hook.list+ * xds --json hook --category State -> hook.list (filtered)+ * xds --json hook --list --detail compact -> hook.brief+ * xds --json hook --list --detail full -> hook.full+ * xds --json hook useMediaQuery -> hook.detail+ * xds --json hook useMediaQuery --params -> hook.detail.params+ * (not found) -> CLIError+ */++import type {HookDoc, HookParamDoc} from '../../../core/src/docs-types';++/** xds --json hook [--list] [--category X] [--detail brief] */+export interface HookListResponse {+ type: 'hook.list';+ data: Record<string, string[]>;+}++/** xds --json hook --list --detail compact */+export interface HookBriefResponse {+ type: 'hook.brief';+ data: Record<string, HookBriefEntry[]>;+}++export interface HookBriefEntry {+ name: string;+ description: string;+ import: string;+}++/** xds --json hook --list --detail full */+export interface HookFullResponse {+ type: 'hook.full';+ data: Record<string, HookDoc[]>;+}++/** xds --json hook <name> */+export interface HookDetailResponse {+ type: 'hook.detail';+ data: HookDoc;+}++/** xds --json hook <name> --params */+export interface HookDetailParamsResponse {+ type: 'hook.detail.params';+ data: HookParamDoc[];+}diff --git a/packages/cli/src/types/index.d.ts b/packages/cli/src/types/index.d.tsindex 829788df1c..db1e211255 100644--- a/packages/cli/src/types/index.d.ts+++ b/packages/cli/src/types/index.d.ts@@ -5,6 +5,7 @@ export * from './component';export * from './discover';export * from './docs';export * from './template';+export * from './hook';export * from './swizzle';export * from './theme';export * from './gap-report';