Skip to content

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.mjs
index 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.error
const 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.md
index 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 Button
const 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 .suggestions
try {
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.mjs
index 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.mjs
index 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.ts
index 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.ts
index 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
| ThemeBuildResponse
diff --git a/packages/cli/src/types/hook.d.ts b/packages/cli/src/types/hook.d.ts
new file mode 100644
index 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.ts
index 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';