Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(storybook): fix @example blocks for autodocs compat (#1380)

Joey0ebe9dc0f3cb
diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.tsx b/packages/core/src/Dialog/useXDSImperativeDialog.tsx
index 73523f7ed8..340d50d750 100644
--- a/packages/core/src/Dialog/useXDSImperativeDialog.tsx
+++ b/packages/core/src/Dialog/useXDSImperativeDialog.tsx
@@ -13,7 +13,6 @@
* @example
* ```
* const dialog = useXDSImperativeDialog();
- *
* <button onClick={() => dialog.show(<MyContent />)}>Open</button>
* {dialog.element}
* ```
@@ -44,16 +43,9 @@ export interface XDSImperativeDialogReturn {
* @example
* ```
* const dialog = useXDSImperativeDialog();
- *
- * // Fire and forget — no isOpen state needed
* onClick={() => dialog.show(
* <XDSCodeBlock code={output} language="bash" />
* )}
- *
- * // With options
- * onClick={() => dialog.show(content, { width: 720, variant: 'fullscreen' })}
- *
- * // Render the portal
* return <>{dialog.element}</>;
* ```
*/
diff --git a/packages/core/src/Icon/globalIconRegistry.tsx b/packages/core/src/Icon/globalIconRegistry.tsx
index 8d93175396..b0a2c267cb 100644
--- a/packages/core/src/Icon/globalIconRegistry.tsx
+++ b/packages/core/src/Icon/globalIconRegistry.tsx
@@ -68,11 +68,9 @@ let globalRegistry: Partial<XDSIconRegistry> = {};
* server-rendered ones that can't access React Context.
*
* @example
- * ```ts
- * // app/layout.tsx (RSC-compatible)
+ * ```
* import { registerIcons } from '@xds/core';
* import { brandIcons } from './brand-icons';
- *
* registerIcons(brandIcons);
* ```
*/
diff --git a/packages/core/src/Layer/useXDSLayer.tsx b/packages/core/src/Layer/useXDSLayer.tsx
index e79c8ef16b..2e5acbf73c 100644
--- a/packages/core/src/Layer/useXDSLayer.tsx
+++ b/packages/core/src/Layer/useXDSLayer.tsx
@@ -262,17 +262,9 @@ function getPositionArea(
*
* @example
* ```
- * // Context mode (anchor positioning)
* const layer = useXDSLayer({ mode: 'context' });
- *
* <button ref={layer.ref}>Trigger</button>
* {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
- *
- * // Fixed mode (positioned at coordinates)
- * const layer = useXDSLayer({ mode: 'fixed' });
- *
- * layer.show();
- * {layer.render(<Content />, { x: mouseX, y: mouseY })}
* ```
*/
export function useXDSLayer(options: ContextLayerOptions): ContextLayerReturn;
diff --git a/packages/core/src/Link/useXDSLinkify.tsx b/packages/core/src/Link/useXDSLinkify.tsx
index 30a892e89f..5780dc2005 100644
--- a/packages/core/src/Link/useXDSLinkify.tsx
+++ b/packages/core/src/Link/useXDSLinkify.tsx
@@ -150,39 +150,9 @@ function findMatches(
*
* @example
* ```
- * // Basic: auto-detect URLs and emails
* const nodes = useXDSLinkify('Visit https://example.com or email [email protected]');
* return <p>{nodes}</p>;
* ```
- *
- * @example
- * ```
- * // Custom patterns: task and diff references
- * const nodes = useXDSLinkify('See T1234 and D5678', {
- * patterns: [
- * {
- * pattern: /\bT(\d+)\b/g,
- * href: (m) => `https://tasks.example.com/${m[1]}`,
- * },
- * {
- * pattern: /\bD(\d+)\b/g,
- * href: (m) => `https://phabricator.example.com/${m[0]}`,
- * },
- * ],
- * });
- * ```
- *
- * @example
- * ```
- * // With XDSMarkdown — linkify text nodes in rendered markdown
- * <XDSMarkdown
- * components={{
- * p: ({children}) => <p>{useXDSLinkify(String(children))}</p>,
- * }}
- * >
- * {markdown}
- * </XDSMarkdown>
- * ```
*/
export function useXDSLinkify(
text: string,
diff --git a/packages/core/src/Table/XDSTable.tsx b/packages/core/src/Table/XDSTable.tsx
index 3cb590bf6b..6544c527ce 100644
--- a/packages/core/src/Table/XDSTable.tsx
+++ b/packages/core/src/Table/XDSTable.tsx
@@ -71,7 +71,6 @@ export interface XDSTableProps<T extends Record<string, unknown>> extends Omit<
*
* @example
* ```
- * // Top-align rows for multi-line cell content
* <XDSTable data={items} columns={columns} verticalAlign="top" />
* ```
*/
diff --git a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx
index 73eaedd116..dae466a810 100644
--- a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx
+++ b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettings.tsx
@@ -76,22 +76,10 @@ export type UseXDSTableColumnSettingsConfig<
*
* @example
* ```
- * // With the state hook (recommended)
* const state = useXDSTableColumnSettingsState({ columns, activeColumnKeys, onChangeActiveColumnKeys });
* const plugin = useXDSTableColumnSettings(state.columnSettingsConfig);
- *
* <XDSTable columns={allColumns} plugins={{ columnSettings: plugin }} />
* ```
- *
- * @example
- * ```
- * // Without state hook — manual config
- * const plugin = useXDSTableColumnSettings({
- * columns: columnDefs,
- * activeColumnKeys: activeKeys,
- * onChangeActiveColumnKeys: setActiveKeys,
- * });
- * ```
*/
export function useXDSTableColumnSettings<
T extends Record<string, unknown>,
diff --git a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsx b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsx
index 993dc8d137..4cadba4f85 100644
--- a/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsx
+++ b/packages/core/src/Table/plugins/columnSettings/useXDSTableColumnSettingsState.tsx
@@ -36,25 +36,17 @@ import type {XDSColumnSettingsOption} from './useXDSTableColumnSettings';
* @example
* ```
* const [activeKeys, setActiveKeys] = useState(['name', 'email', 'role']);
- *
* const columnState = useXDSTableColumnSettingsState({
* columns: [
* { key: 'name', label: 'Name', isAlwaysVisible: true },
* { key: 'email', label: 'Email' },
* { key: 'role', label: 'Role' },
- * { key: 'status', label: 'Status' },
* ],
* activeColumnKeys: activeKeys,
* onChangeActiveColumnKeys: setActiveKeys,
* });
- *
* const plugin = useXDSTableColumnSettings(columnState.columnSettingsConfig);
- *
- * <XDSTable
- * data={data}
- * columns={allColumns}
- * plugins={{ columnSettings: plugin }}
- * />
+ * <XDSTable data={data} columns={allColumns} plugins={{ columnSettings: plugin }} />
* ```
*/
export interface UseXDSTableColumnSettingsStateConfig<
@@ -162,7 +154,6 @@ export interface UseXDSTableColumnSettingsStateReturn<
* @example
* ```
* const [activeKeys, setActiveKeys] = useState(['name', 'email']);
- *
* const state = useXDSTableColumnSettingsState({
* columns: [
* { key: 'name', label: 'Name', isAlwaysVisible: true },
@@ -172,20 +163,8 @@ export interface UseXDSTableColumnSettingsStateReturn<
* activeColumnKeys: activeKeys,
* onChangeActiveColumnKeys: setActiveKeys,
* });
- *
- * // Feed into the plugin hook
* const plugin = useXDSTableColumnSettings(state.columnSettingsConfig);
- *
- * // Build your own column picker UI using state helpers
- * state.columns.map(col => (
- * <Checkbox
- * key={col.key}
- * checked={state.isColumnActive(col.key)}
- * disabled={!state.isColumnToggleable(col.key)}
- * onChange={() => state.toggleColumn(col.key)}
- * label={col.label}
- * />
- * ));
+ * <XDSTable data={data} columns={allColumns} plugins={{ columnSettings: plugin }} />
* ```
*/
export function useXDSTableColumnSettingsState<
diff --git a/packages/core/src/Table/plugins/filtering/useXDSTableFilterState.tsx b/packages/core/src/Table/plugins/filtering/useXDSTableFilterState.tsx
index ad44b84e30..dcf332aeee 100644
--- a/packages/core/src/Table/plugins/filtering/useXDSTableFilterState.tsx
+++ b/packages/core/src/Table/plugins/filtering/useXDSTableFilterState.tsx
@@ -40,7 +40,6 @@ export interface UseXDSTableFilterStateResult {
* @example
* ```
* const {filters, onFilterChange} = useXDSTableFilterState();
- *
* const filterPlugin = useXDSTableFiltering({
* filters,
* onFilterChange,
diff --git a/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx b/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx
index f6a4246314..436e33b729 100644
--- a/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx
+++ b/packages/core/src/Table/plugins/filtering/useXDSTableFiltering.tsx
@@ -266,24 +266,13 @@ export type XDSTableFilterVariant = 'popover' | 'inline' | 'inline-compact';
*
* @example
* ```
- * const [filters, setFilters] = useState<XDSTableFilterState>({});
- *
+ * const {filters, onFilterChange} = useXDSTableFilterState();
* const filterPlugin = useXDSTableFiltering({
* filters,
- * onFilterChange: (columnKey, value) => {
- * setFilters(prev => {
- * const next = { ...prev };
- * if (value == null) {
- * delete next[columnKey];
- * } else {
- * next[columnKey] = value;
- * }
- * return next;
- * });
- * },
+ * onFilterChange,
+ * variant: 'inline',
* });
- *
- * <XDSTable plugins={[filterPlugin]} ... />
+ * <XDSTable plugins={{ filter: filterPlugin }} columns={columns} data={data} />
* ```
*/
export interface UseXDSTableFilteringConfig {
@@ -997,27 +986,19 @@ function InlineFilterSlot({
*
* @example
* ```
- * const [filters, setFilters] = useState<XDSTableFilterState>({});
- *
+ * const {filters, onFilterChange} = useXDSTableFilterState();
* const filterPlugin = useXDSTableFiltering({
* filters,
- * onFilterChange: (key, value) => {
- * setFilters(prev => ({
- * ...prev,
- * [key]: value ?? undefined,
- * }));
- * },
+ * onFilterChange,
* variant: 'popover',
* });
- *
* <XDSTable
* data={users}
* columns={[
* { key: 'name', header: 'Name', filter: 'name' },
* { key: 'status', header: 'Status', filter: 'status' },
- * { key: 'age', header: 'Age', filter: 'age' },
* ]}
- * plugins={[filterPlugin]}
+ * plugins={{ filter: filterPlugin }}
* />
* ```
*/
diff --git a/packages/core/src/Table/plugins/pagination/useXDSTablePagination.tsx b/packages/core/src/Table/plugins/pagination/useXDSTablePagination.tsx
index 7094f2d0e8..35fda381f5 100644
--- a/packages/core/src/Table/plugins/pagination/useXDSTablePagination.tsx
+++ b/packages/core/src/Table/plugins/pagination/useXDSTablePagination.tsx
@@ -58,50 +58,14 @@ const styles = stylex.create({
*
* @example
* ```
- * // Client-side pagination
* const [page, setPage] = useState(1);
- * const pageSize = 10;
- *
* const plugin = useXDSTablePagination({
* page,
* onPageChange: setPage,
* totalItems: data.length,
- * pageSize,
- * });
- *
- * <XDSTable
- * data={paginateData(data, page, pageSize)}
- * columns={columns}
- * plugins={{ pagination: plugin }}
- * />
- * ```
- *
- * @example
- * ```
- * // Server-side pagination \u2014 data already sliced
- * const plugin = useXDSTablePagination({
- * page,
- * onPageChange: (p) => fetchPage(p),
- * totalItems: serverTotal,
- * pageSize: 25,
- * });
- *
- * <XDSTable
- * data={serverData}
- * columns={columns}
- * plugins={{ pagination: plugin }}
- * />
- * ```
- *
- * @example
- * ```
- * // Cursor-based pagination \u2014 total unknown
- * const plugin = useXDSTablePagination({
- * page,
- * onPageChange: setPage,
- * hasMore: cursor != null,
- * pageSize: 20,
+ * pageSize: 10,
* });
+ * <XDSTable data={pageData} columns={columns} plugins={{ pagination: plugin }} />
* ```
*/
export interface UseXDSTablePaginationConfig {
@@ -215,19 +179,13 @@ export interface UseXDSTablePaginationConfig {
* @example
* ```
* const [page, setPage] = useState(1);
- * const pageSize = 10;
- *
* const plugin = useXDSTablePagination({
* page,
* onPageChange: setPage,
* totalItems: data.length,
- * pageSize,
+ * pageSize: 10,
* });
- *
- * <XDSTable
- * data={paginateData(data, page, pageSize)}
- * plugins={{ pagination: plugin }}
- * />
+ * <XDSTable data={pageData} plugins={{ pagination: plugin }} />
* ```
*/
export function useXDSTablePagination<T extends Record<string, unknown>>(
diff --git a/packages/core/src/Table/plugins/sortable/useXDSTableSortable.tsx b/packages/core/src/Table/plugins/sortable/useXDSTableSortable.tsx
index de7bb01dee..60e75ae6a3 100644
--- a/packages/core/src/Table/plugins/sortable/useXDSTableSortable.tsx
+++ b/packages/core/src/Table/plugins/sortable/useXDSTableSortable.tsx
@@ -73,13 +73,8 @@ export type XDSTableSortState<TSortKey extends string = string> =
* const [sort, setSort] = useState<XDSTableSortState>([
* { sortKey: 'name', direction: 'ascending' },
* ]);
- *
- * const sortPlugin = useXDSTableSortable({
- * sort,
- * onSortChange: setSort,
- * });
- *
- * <XDSTable plugins={{ sort: sortPlugin }} ... />
+ * const sortPlugin = useXDSTableSortable({ sort, onSortChange: setSort });
+ * <XDSTable plugins={{ sort: sortPlugin }} columns={columns} data={data} />
* ```
*/
export interface UseXDSTableSortableConfig<TSortKey extends string = string> {
@@ -321,7 +316,6 @@ function SortHeaderButton<T extends Record<string, unknown>>({
* ```
* const [sort, setSort] = useState<XDSTableSortState>([]);
* const sortPlugin = useXDSTableSortable({ sort, onSortChange: setSort });
- *
* <XDSTable
* data={users}
* columns={[
diff --git a/packages/core/src/Table/plugins/sortable/useXDSTableSortableState.tsx b/packages/core/src/Table/plugins/sortable/useXDSTableSortableState.tsx
index 306b6d3a21..d5e7ad82a0 100644
--- a/packages/core/src/Table/plugins/sortable/useXDSTableSortableState.tsx
+++ b/packages/core/src/Table/plugins/sortable/useXDSTableSortableState.tsx
@@ -49,20 +49,9 @@ export type XDSTableSortComparator<T> = (a: T, b: T) => number;
* data: users,
* defaultSort: [{ sortKey: 'name', direction: 'ascending' }],
* });
- *
* const sortPlugin = useXDSTableSortable(sortConfig);
* <XDSTable data={sortedData} plugins={{ sort: sortPlugin }} />
* ```
- *
- * @example
- * ```
- * const [sort, setSort] = useState<XDSTableSortState>([]);
- * const { sortedData, sortConfig } = useXDSTableSortableState({
- * data: users,
- * sort,
- * onSortChange: setSort,
- * });
- * ```
*/
export interface UseXDSTableSortableStateConfig<
T extends Record<string, unknown>,
@@ -220,18 +209,10 @@ function sortData<
* const { sortedData, sortConfig } = useXDSTableSortableState({
* data: employees,
* defaultSort: [{ sortKey: 'name', direction: 'ascending' }],
- * comparators: {
- * age: (a, b) => a.age - b.age,
- * },
+ * comparators: { age: (a, b) => a.age - b.age },
* });
- *
* const sortPlugin = useXDSTableSortable(sortConfig);
- *
- * <XDSTable
- * data={sortedData}
- * columns={columns}
- * plugins={{ sort: sortPlugin }}
- * />
+ * <XDSTable data={sortedData} columns={columns} plugins={{ sort: sortPlugin }} />
* ```
*/
export function useXDSTableSortableState<