@astryxdesign/core 0.1.8 → 0.1.9

package/src/Table/plugins/tree/useTableTreeState.test.tsx

@@ -634,3 +634,107 @@ describe('useTableTreeState — semantics edges', () => {
     expect(ids(result.current.visibleData)).toEqual(['src', 'readme']);
   });
 });
+
+// =============================================================================
+// isAllExpanded (drives the header expand-all control)
+// =============================================================================
+
+describe('useTableTreeState: isAllExpanded', () => {
+  it('reports false when nothing is expanded', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({data: fileTree, idKey: 'id'}),
+    );
+
+    expect(result.current.isAllExpanded).toBe(false);
+  });
+
+  it('reports true only when every expandable row is expanded', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({data: fileTree, idKey: 'id'}),
+    );
+
+    act(() => {
+      result.current.expandAll();
+    });
+
+    expect(result.current.isAllExpanded).toBe(true);
+  });
+
+  it("reports 'indeterminate' when some but not all expandable rows are expanded", () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({
+        data: fileTree,
+        idKey: 'id',
+        defaultExpandedIds: ['src'],
+      }),
+    );
+
+    // 'src' and 'components' are both expandable; only 'src' is expanded.
+    expect(result.current.isAllExpanded).toBe('indeterminate');
+  });
+
+  it('returns to false after collapseAll', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({
+        data: fileTree,
+        idKey: 'id',
+        defaultExpandedIds: ['src', 'components'],
+      }),
+    );
+
+    act(() => {
+      result.current.collapseAll();
+    });
+
+    expect(result.current.isAllExpanded).toBe(false);
+  });
+
+  it('reports false for flat data (no expandable rows)', () => {
+    const flat: FileRow[] = [
+      {id: 'a', name: 'A', size: 1},
+      {id: 'b', name: 'B', size: 2},
+    ];
+    const {result} = renderHook(() =>
+      useTableTreeState({data: flat, idKey: 'id'}),
+    );
+
+    expect(result.current.isAllExpanded).toBe(false);
+  });
+
+  it('ignores expanded ids that match no expandable row when aggregating', () => {
+    // 'readme' is a leaf (not expandable) and 'ghost' matches nothing; neither
+    // should count toward the expandable total, so an all-expandable set that
+    // omits them still reads as fully expanded.
+    const {result} = renderHook(() =>
+      useTableTreeState({
+        data: fileTree,
+        idKey: 'id',
+        defaultExpandedIds: ['src', 'components', 'readme', 'ghost'],
+      }),
+    );
+
+    expect(result.current.isAllExpanded).toBe(true);
+  });
+
+  it('exposes the aggregate state and expand/collapse handlers through treeConfig', () => {
+    const {result} = renderHook(() =>
+      useTableTreeState({data: fileTree, idKey: 'id'}),
+    );
+
+    // The headless plugin reads everything it needs to render the header
+    // expand-all control from treeConfig, not from the state hook directly.
+    expect(result.current.treeConfig.isAllExpanded).toBe(false);
+
+    act(() => {
+      result.current.treeConfig.onExpandAll?.();
+    });
+    expect(result.current.isAllExpanded).toBe(true);
+    expect(result.current.treeConfig.isAllExpanded).toBe(true);
+
+    act(() => {
+      result.current.treeConfig.onCollapseAll?.();
+    });
+    expect(result.current.isAllExpanded).toBe(false);
+    expect(result.current.treeConfig.isAllExpanded).toBe(false);
+  });
+});

package/src/Table/plugins/tree/useTableTreeState.tsx

@@ -74,6 +74,12 @@ export interface UseTableTreeStateResult<T extends Record<string, unknown>> {
   treeConfig: UseTableTreeDataConfig<T>;
   /** The current expanded row ids. */
   expandedIds: ReadonlySet<string>;
+  /**
+   * Aggregate expansion state across every expandable row: `true` when all are
+   * expanded, `false` when none are, `'indeterminate'` when some but not all
+   * are. Drives the header expand-all control. Reports `false` for flat data.
+   */
+  isAllExpanded: boolean | 'indeterminate';
   /** Expand every expandable row in the tree. */
   expandAll: () => void;
   /** Collapse every row. */
@@ -211,6 +217,25 @@ export function useTableTreeState<T extends Record<string, unknown>>(
 
   const hasExpandableRows = allExpandableIds.length > 0;
 
+  // Aggregate state for the header expand-all control. Only expandable ids
+  // count toward the total, so expanded ids that match a leaf or no row at
+  // all never skew the tally.
+  const isAllExpanded: boolean | 'indeterminate' = useMemo(() => {
+    if (!hasExpandableRows) {
+      return false;
+    }
+    const expandedCount = allExpandableIds.filter(id =>
+      expandedIds.has(id),
+    ).length;
+    if (expandedCount === 0) {
+      return false;
+    }
+    if (expandedCount === allExpandableIds.length) {
+      return true;
+    }
+    return 'indeterminate';
+  }, [hasExpandableRows, allExpandableIds, expandedIds]);
+
   const onToggleItem = useCallback(
     (item: T) => {
       const id = getId(item);
@@ -243,11 +268,30 @@ export function useTableTreeState<T extends Record<string, unknown>>(
       getRowMeta,
       onToggleItem,
       hasExpandableRows,
+      isAllExpanded,
+      onExpandAll: expandAll,
+      onCollapseAll: collapseAll,
       indent,
       treeColumnKey,
     }),
-    [getRowMeta, onToggleItem, hasExpandableRows, indent, treeColumnKey],
+    [
+      getRowMeta,
+      onToggleItem,
+      hasExpandableRows,
+      isAllExpanded,
+      expandAll,
+      collapseAll,
+      indent,
+      treeColumnKey,
+    ],
   );
 
-  return {visibleData, treeConfig, expandedIds, expandAll, collapseAll};
+  return {
+    visibleData,
+    treeConfig,
+    expandedIds,
+    isAllExpanded,
+    expandAll,
+    collapseAll,
+  };
 }

package/src/Table/useBaseTablePlugins.ts

@@ -38,6 +38,7 @@
 
 import {useRef} from 'react';
 import type {TablePlugin} from './types';
+import {devWarn} from '../utils/devWarning';
 
 // ======================================================================// Canonical Plugin Order
 // ======================================================================
@@ -112,8 +113,9 @@ function validatePlugin<T extends Record<string, unknown>>(
   // Warn about unknown keys (likely misspelled transform names)
   for (const key of keys) {
     if (!VALID_TRANSFORM_KEYS.has(key)) {
-      console.warn(
-        `[Table] Plugin "${name}" has unknown key "${key}". ` +
+      devWarn(
+        'Table',
+        `Plugin "${name}" has unknown key "${key}". ` +
           `Valid keys: ${[...VALID_TRANSFORM_KEYS].join(', ')}. ` +
           `This key will be ignored.`,
       );
@@ -125,8 +127,9 @@ function validatePlugin<T extends Record<string, unknown>>(
     if (VALID_TRANSFORM_KEYS.has(key)) {
       const value = (plugin as Record<string, unknown>)[key];
       if (value != null && typeof value !== 'function') {
-        console.warn(
-          `[Table] Plugin "${name}" has non-function value for "${key}" ` +
+        devWarn(
+          'Table',
+          `Plugin "${name}" has non-function value for "${key}" ` +
             `(got ${typeof value}). Transform will be skipped.`,
         );
       }
@@ -140,8 +143,9 @@ function validatePlugin<T extends Record<string, unknown>>(
       typeof (plugin as Record<string, unknown>)[key] === 'function',
   );
   if (!hasTransforms) {
-    console.warn(
-      `[Table] Plugin "${name}" has no transform methods. ` +
+    devWarn(
+      'Table',
+      `Plugin "${name}" has no transform methods. ` +
         `It will be included in the pipeline but won't do anything.`,
     );
   }

package/src/Table/useTableRowStatus.doc.mjs

@@ -0,0 +1,30 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+  name: 'useTableRowStatus',
+  subComponentOf: 'Table',
+  displayName: 'useTableRowStatus',
+  description:
+    'Hook that returns a TablePlugin which prepends a narrow column signaling per-row status: a colored status dot by default, or an icon when provided (shape + color is more accessible than color alone). getStatus maps a row to a semantic color (mapped to a theme token) or raw CSS color, an optional icon, and a required accessible label (shown in a tooltip on hover and announced to assistive technology, so status is never color-only); return null for no indicator. Memoize getStatus with useCallback for a stable plugin identity.',
+  props: [
+    {
+      name: 'getStatus',
+      type: "(item: T) => { color: 'accent' | 'success' | 'error' | 'warning' | 'red' | 'orange' | 'green' | 'yellow' | 'blue' | 'gray' | string; icon?: IconName; label: string } | null",
+      description:
+        'Derive the status indicator for a row: a semantic color (accent, success, error, warning, red, orange, green, yellow, blue, gray — mapped to a theme token) or a raw CSS color as an escape hatch; an optional icon to signal status by shape instead of the dot (recommended when multiple statuses coexist; valid names: close, chevronDown, chevronLeft, chevronRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone); and a required accessible label (announced via role="img" and shown in a tooltip on hover, so a status is never conveyed by color alone). Return null for rows with no status. Memoize with useCallback for a stable plugin identity.',
+      required: true,
+    },
+  ],
+};
+
+/** @type {import('../docs-types').TranslationDoc} */
+export const docsDense = {
+  description:
+    'Returns a TablePlugin that prepends a narrow per-row status column: a colored dot, or an icon when provided (shape + color beats color alone for a11y). getStatus maps a row to {color, icon?, label} or null. color is a semantic name (success/error/warning/etc.) mapped to a theme token, or a raw CSS color. label is required (tooltip + accessible name). Memoize getStatus with useCallback.',
+  propDescriptions: {
+    getStatus:
+      'Map a row to {color, icon?, label} or null. color = semantic status name (mapped to a token) or raw CSS; icon = shape signifier (a11y); label = required accessible name (tooltip + role="img"). Memoize with useCallback.',
+  },
+};

package/src/Table/useTableSelection.doc.mjs

@@ -6,7 +6,8 @@ export const docs = {
   name: 'useTableSelection',
   subComponentOf: 'Table',
   displayName: 'useTableSelection',
-  description: 'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
+  description:
+    'Hook that returns a TablePlugin implementing row selection with checkboxes, select-all, and aria-selected. Uses React Context for independent checkbox re-renders.',
   props: [
     {
       name: 'getIsItemSelected',
@@ -17,7 +18,8 @@ export const docs = {
     {
       name: 'onSelectItem',
       type: '(event: {item: T; isSelected: boolean}) => void',
-      description: 'Called when a row checkbox is toggled. isSelected is the new desired state.',
+      description:
+        'Called when a row checkbox is toggled. isSelected is the new desired state.',
       required: true,
     },
     {
@@ -29,33 +31,67 @@ export const docs = {
     {
       name: 'getIsAllSelected',
       type: '() => boolean',
-      description: 'Returns whether all selectable items are currently selected.',
+      description:
+        'Returns whether all selectable items are currently selected.',
       required: true,
     },
     {
       name: 'getIsIndeterminate',
       type: '() => boolean',
-      description: 'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
+      description:
+        'Returns whether selection is partial (some but not all). Renders the select-all checkbox in indeterminate state.',
     },
     {
       name: 'getIsItemSelectable',
       type: '(item: T) => boolean',
-      description: 'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
+      description:
+        'Returns whether a row should show a checkbox. Non-selectable rows render nothing in the selection cell.',
       default: '() => true',
     },
     {
       name: 'getIsItemEnabled',
       type: '(item: T) => boolean',
-      description: 'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
+      description:
+        'Returns whether a row checkbox is interactive. Disabled rows show a disabled checkbox.',
       default: '() => true',
     },
+    {
+      name: 'getRowLabel',
+      type: '(item: T) => string',
+      description:
+        'Derives a human-readable identity for a row; the row checkbox\'s hidden label becomes `Select ${getRowLabel(item)}` so screen readers announce which row each checkbox selects. Falls back to "Select row" when omitted.',
+    },
+  ],
+  examples: [
+    {
+      label: 'Accessible per-row checkbox names',
+      code: `
+const selectionPlugin = useTableSelection({
+  getIsItemSelected: item => selectedIds.has(item.id),
+  onSelectItem: ({item, isSelected}) => toggle(item.id, isSelected),
+  onSelectAll: ({isAllSelected}) => selectAll(isAllSelected),
+  getIsAllSelected: () => selectedIds.size === users.length,
+  // Screen readers announce "Select Alice", "Select Bob", ...
+  // instead of an undifferentiated "Select row" for every checkbox.
+  getRowLabel: item => item.name,
+});
+
+<Table
+  data={users}
+  columns={columns}
+  idKey="id"
+  plugins={{selection: selectionPlugin}}
+/>;
+`,
+    },
   ],
 };
 
 export const docsZh = {
   name: 'useTableSelection',
   displayName: 'useTableSelection',
-  description: '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
+  description:
+    '返回 TablePlugin 的 Hook，实现带复选框、全选和 aria-selected 的行选择功能。使用 React Context 实现独立的复选框重新渲染。',
   props: [
     {
       name: 'getIsItemSelected',
@@ -84,12 +120,14 @@ export const docsZh = {
     {
       name: 'getIsIndeterminate',
       type: '() => boolean',
-      description: '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
+      description:
+        '返回选择是否为部分选中（部分但非全部）。将全选复选框渲染为不确定状态。',
     },
     {
       name: 'getIsItemSelectable',
       type: '(item: T) => boolean',
-      description: '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
+      description:
+        '返回行是否应显示复选框。不可选择的行在选择单元格中不渲染任何内容。',
       default: '() => true',
     },
     {
@@ -98,20 +136,33 @@ export const docsZh = {
       description: '返回行复选框是否可交互。禁用的行显示禁用状态的复选框。',
       default: '() => true',
     },
+    {
+      name: 'getRowLabel',
+      type: '(item: T) => string',
+      description:
+        '为行派生人类可读的标识；行复选框的隐藏标签变为 `Select ${getRowLabel(item)}`，让屏幕阅读器播报每个复选框选择的是哪一行。省略时回退为 "Select row"。',
+    },
   ],
 };
 
 export const docsDense = {
   name: 'useTableSelection',
   displayName: 'useTableSelection',
-  description: 'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
+  description:
+    'Hook returning TablePlugin for row selection w/ checkboxes, select-all, aria-selected. Uses React Context for independent checkbox re-renders.',
   propDescriptions: {
     getIsItemSelected: 'Returns whether item is selected.',
-    onSelectItem: 'Called on row checkbox toggle; isSelected = new desired state.',
+    onSelectItem:
+      'Called on row checkbox toggle; isSelected = new desired state.',
     onSelectAll: 'Called on select-all header checkbox toggle.',
     getIsAllSelected: 'Returns whether all selectable items are selected.',
-    getIsIndeterminate: 'Returns partial selection state; renders indeterminate checkbox.',
-    getIsItemSelectable: 'Returns whether row shows checkbox; non-selectable rows render nothing.',
-    getIsItemEnabled: 'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+    getIsIndeterminate:
+      'Returns partial selection state; renders indeterminate checkbox.',
+    getIsItemSelectable:
+      'Returns whether row shows checkbox; non-selectable rows render nothing.',
+    getIsItemEnabled:
+      'Returns whether row checkbox is interactive; disabled rows show disabled checkbox.',
+    getRowLabel:
+      'Derives row identity for the checkbox\'s hidden label: `Select ${getRowLabel(item)}`. Falls back to "Select row" when omitted.',
   },
 };

package/src/Table/useTableTreeData.doc.mjs

@@ -29,6 +29,29 @@ export const docs = {
         'Whether any row in the dataset is expandable. When false the plugin is a no-op: no expanders, no indent, no tree ARIA.',
       required: true,
     },
+    {
+      name: 'hasExpandAllControl',
+      type: 'boolean',
+      description:
+        'Show an expand-all/collapse-all toggle in the tree column header. Requires isAllExpanded plus onExpandAll/onCollapseAll (all supplied by useTableTreeState).',
+      default: 'false',
+    },
+    {
+      name: 'isAllExpanded',
+      type: "boolean | 'indeterminate'",
+      description:
+        'Aggregate expansion state across every expandable row, driving the header expand-all toggle. true when all are expanded, false when none are, indeterminate when some are.',
+    },
+    {
+      name: 'onExpandAll',
+      type: '() => void',
+      description: 'Expand every expandable row. Wired to the header control.',
+    },
+    {
+      name: 'onCollapseAll',
+      type: '() => void',
+      description: 'Collapse every row. Wired to the header control.',
+    },
     {
       name: 'indent',
       type: "'sm' | 'md' | 'lg'",
@@ -71,5 +94,11 @@ export const docsDense = {
     indent:
       "indent step per level: 'sm' | 'md' | 'lg' (spacing-3/4/6). Defaults to 'md'.",
     treeColumnKey: 'column carrying indent + expander. Defaults to first column.',
+    hasExpandAllControl:
+      'show expand-all/collapse-all toggle in tree column header. Needs isAllExpanded + onExpandAll/onCollapseAll (from useTableTreeState). Defaults to false.',
+    isAllExpanded:
+      "aggregate state driving the header toggle: true (all) | false (none) | 'indeterminate' (some).",
+    onExpandAll: 'expand every expandable row (header control)',
+    onCollapseAll: 'collapse every row (header control)',
   },
 };

package/src/Table/useTableTreeState.doc.mjs

@@ -7,7 +7,7 @@ export const docs = {
   subComponentOf: 'Table',
   displayName: 'useTableTreeState',
   description:
-    'State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array; collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.',
+    'State management companion for useTableTreeData. Owns the expanded set (controlled or uncontrolled) and flattens nested data into the visible row array; collapsed subtrees are unmounted, not hidden, so the table body contains exactly the visible rows. Returns expandAll/collapseAll helpers, the aggregate isAllExpanded state (true/false/indeterminate) for a header expand-all control, and a ready-to-use config for the tree plugin. Note: because collapsed rows unmount, cell-local React state inside collapsed subtrees is lost on collapse; lift state that must survive.',
   props: [
     {
       name: 'data',
@@ -79,7 +79,7 @@ export const docsDense = {
   name: 'useTableTreeState',
   displayName: 'useTableTreeState',
   description:
-    'State companion for useTableTreeData. Owns expanded set (controlled or uncontrolled), flattens nested data to visible rows (collapsed subtrees unmounted, not hidden). Returns {visibleData, treeConfig, expandedIds, expandAll, collapseAll}. Cell-local state in collapsed subtrees is lost on collapse; lift state that must survive.',
+    'State companion for useTableTreeData. Owns expanded set (controlled or uncontrolled), flattens nested data to visible rows (collapsed subtrees unmounted, not hidden). Returns {visibleData, treeConfig, expandedIds, isAllExpanded, expandAll, collapseAll} (isAllExpanded = true/false/indeterminate for a header expand-all control). Cell-local state in collapsed subtrees is lost on collapse; lift state that must survive.',
   propDescriptions: {
     data: 'nested data; rows carry child rows under childrenKey. Flat data => plugin is a no-op.',
     idKey: 'row ID accessor: property name or fn returning unique id',

package/src/TextArea/TextArea.test.tsx

@@ -10,11 +10,19 @@
  */
 
 import {useState} from 'react';
-import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {describe, it, expect, vi, beforeEach, afterEach} from 'vitest';
 import {render, screen, fireEvent, waitFor} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {TestIcon} from '../__tests__/TestIcon';
 import {TextArea} from './TextArea';
+import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
+
+// FieldStatus announces status messages through the persistent useAnnounce
+// singletons; remove them between tests so role/aria-live queries in this
+// file never match a leftover region.
+afterEach(() => {
+  __resetLiveRegionsForTest();
+});
 
 // Mock showPopover/hidePopover since jsdom does not implement them. Used by the
 // disabledMessage tooltip.

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -16,7 +16,7 @@ export const docs = {
     {
       name: 'alt',
       type: 'string',
-      description: 'Alt text for the image.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) and hidden from screen readers; a dev warning fires if neither alt nor label is set.',
     },
     {
       name: 'label',
@@ -31,7 +31,7 @@ export const docs = {
     {
       name: 'onClick',
       type: '(e: React.MouseEvent) => void',
-      description: 'Click handler. Adds button semantics and hover shadow.',
+      description: 'Click handler. Adds button semantics and a hover overlay.',
     },
     {
       name: 'isLoading',
@@ -45,6 +45,13 @@ export const docs = {
       description: 'Whether the thumbnail is disabled.',
       default: 'false',
     },
+    {
+      name: 'showRemoveOn',
+      type: "'always' | 'hover'",
+      description:
+        'When the remove button is visible. `hover` (the default) reveals it on hover and on keyboard focus, and keeps it visible on any touch-capable device; `always` shows it at rest. Only applies when `onRemove` is set.',
+      default: "'hover'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -77,14 +84,14 @@ export const docs = {
     bestPractices: [
       {guidance: true, description: 'Always provide a label prop with the file name so the thumbnail and its remove button are accessible to screen readers and show a tooltip on hover.'},
       {guidance: true, description: 'Use isLoading without a src to show a skeleton during initial upload, and isLoading with a src to show a spinner overlay once a preview URL is available.'},
-      {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image; the thumbnail adds button semantics and a hover shadow automatically.'},
+      {guidance: true, description: 'Pair onClick with a lightbox or detail view so users can inspect the full image; the thumbnail adds button semantics and a hover overlay automatically.'},
       {guidance: false, description: "Don't use Thumbnail for non-image file types like PDFs or spreadsheets; use a file attachment component with an appropriate icon instead."},
       {guidance: false, description: "Don't omit alt text when a src is provided; screen readers need a description of the image content, not just the file name from label."},
     ],
     anatomy: [
       {name: 'Image', required: false, description: 'The preview image, displayed as a square with cover fit.'},
       {name: 'Placeholder', required: false, description: 'An image silhouette icon shown when no src is provided.'},
-      {name: 'Remove button', required: false, description: 'An overlaid close button in the top-right corner. Appears when onRemove is set. Uses APCA luminance detection to stay visible on any image.'},
+      {name: 'Remove button', required: false, description: 'An overlaid close button in the top-right corner. Appears when onRemove is set. Sits on a fixed --color-overlay scrim with an --color-on-dark icon to stay visible on any image.'},
       {name: 'Upload overlay', required: false, description: 'A semi-transparent overlay with a spinner, shown when isLoading is true and a src preview is available.'},
       {name: 'Skeleton', required: false, description: 'A shimmer animation shown when isLoading is true and no src is set.'},
     ],
@@ -95,12 +102,13 @@ export const docs = {
 export const docsZh = {
   propDescriptions: {
     src: '\u56FE\u7247\u6E90 URL\u3002',
-    alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002',
+    alt: '\u56FE\u7247\u7684\u66FF\u4EE3\u6587\u672C\u3002\u7701\u7565\u65F6\u56FE\u7247\u4F1A\u88AB\u663E\u5F0F\u6807\u8BB0\u4E3A\u88C5\u9970\u6027\uFF08alt=""\u3001role="presentation"\u3001aria-hidden\uFF09\u5E76\u5BF9\u5C4F\u5E55\u9605\u8BFB\u5668\u9690\u85CF\uFF1B\u82E5 alt \u548C label \u5747\u672A\u8BBE\u7F6E\uFF0C\u5F00\u53D1\u73AF\u5883\u4F1A\u53D1\u51FA\u8B66\u544A\u3002',
     label: '\u65E0\u969C\u788D\u6807\u7B7E\uFF08\u5982\u6587\u4EF6\u540D\uFF09\u3002\u60AC\u505C\u65F6\u4EE5\u63D0\u793A\u5DE5\u5177\u663E\u793A\u3002',
     onRemove: '\u8986\u76D6\u5C42\u79FB\u9664\u6309\u94AE\u7684\u56DE\u8C03\u3002',
-    onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002',
+    onClick: '\u70B9\u51FB\u5904\u7406\u5668\u3002\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u8986\u76D6\u5C42\u3002',
     isLoading: '\u663E\u793A\u9AA8\u67B6\u5C4F\uFF08\u65E0 src\uFF09\u6216\u4E0A\u4F20\u8986\u76D6\u5C42\uFF08\u6709 src\uFF09\u3002',
     isDisabled: '\u662F\u5426\u7981\u7528\u7F29\u7565\u56FE\u3002',
+    showRemoveOn: '\u4F55\u65F6\u663E\u793A\u79FB\u9664\u6309\u94AE\uFF1Ahover\uFF08\u9ED8\u8BA4\uFF0C\u60AC\u505C\u65F6\u4EE5\u53CA\u952E\u76D8\u805A\u7126\u65F6\u663E\u793A\uFF0C\u89E6\u6478\u8BBE\u5907\u4E0A\u4FDD\u6301\u53EF\u89C1\uFF09| always\uFF08\u59CB\u7EC8\u663E\u793A\uFF09\u3002\u4EC5\u5728\u8BBE\u7F6E onRemove \u65F6\u751F\u6548\u3002',
     xstyle: '\u7528\u4E8E\u5E03\u5C40\u81EA\u5B9A\u4E49\u7684 StyleX \u6837\u5F0F\u3002\u5FC5\u987B\u662F stylex.create() \u7684\u503C\uFF0C\u800C\u975E\u5185\u8054\u6837\u5F0F\u5BF9\u8C61\u3002',
     className: '\u6839\u5143\u7D20\u7684 CSS \u7C7B\u540D\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
     style: '\u6839\u5143\u7D20\u7684\u5185\u8054\u6837\u5F0F\u3002\u5EFA\u8BAE\u4F7F\u7528 xstyle\u3002',
@@ -112,7 +120,7 @@ export const docsZh = {
     bestPractices: [
       {guidance: true, description: '\u59CB\u7EC8\u63D0\u4F9B label \u5C5E\u6027\u5E76\u586B\u5199\u6587\u4EF6\u540D\uFF0C\u4EE5\u4FBF\u5C4F\u5E55\u9605\u8BFB\u5668\u80FD\u591F\u8BC6\u522B\u7F29\u7565\u56FE\u53CA\u5176\u79FB\u9664\u6309\u94AE\uFF0C\u5E76\u5728\u60AC\u505C\u65F6\u663E\u793A\u63D0\u793A\u3002'},
       {guidance: true, description: '\u4E0A\u4F20\u521D\u671F\u4F7F\u7528\u4E0D\u5E26 src \u7684 isLoading \u663E\u793A\u9AA8\u67B6\u5C4F\uFF1B\u83B7\u5F97\u9884\u89C8 URL \u540E\u4F7F\u7528\u5E26 src \u7684 isLoading \u663E\u793A\u65CB\u8F6C\u52A0\u8F7D\u8986\u76D6\u5C42\u3002'},
-      {guidance: true, description: '\u5C06 onClick \u4E0E\u706F\u7BB1\u6216\u8BE6\u60C5\u89C6\u56FE\u914D\u5BF9\uFF0C\u4EE5\u4FBF\u7528\u6237\u67E5\u770B\u5B8C\u6574\u56FE\u7247\u2014\u2014\u7EC4\u4EF6\u4F1A\u81EA\u52A8\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u9634\u5F71\u3002'},
+      {guidance: true, description: '\u5C06 onClick \u4E0E\u706F\u7BB1\u6216\u8BE6\u60C5\u89C6\u56FE\u914D\u5BF9\uFF0C\u4EE5\u4FBF\u7528\u6237\u67E5\u770B\u5B8C\u6574\u56FE\u7247\u2014\u2014\u7EC4\u4EF6\u4F1A\u81EA\u52A8\u6DFB\u52A0\u6309\u94AE\u8BED\u4E49\u548C\u60AC\u505C\u8986\u76D6\u5C42\u3002'},
       {guidance: false, description: '\u5BF9 PDF \u6216\u7535\u5B50\u8868\u683C\u7B49\u975E\u56FE\u7247\u6587\u4EF6\u7C7B\u578B\u4F7F\u7528 Thumbnail\u2014\u2014\u5E94\u4F7F\u7528\u5E26\u6709\u76F8\u5E94\u56FE\u6807\u7684\u6587\u4EF6\u9644\u4EF6\u7EC4\u4EF6\u3002'},
       {guidance: false, description: '\u63D0\u4F9B src \u65F6\u7701\u7565 alt \u6587\u672C\u2014\u2014\u5C4F\u5E55\u9605\u8BFB\u5668\u9700\u8981\u56FE\u7247\u5185\u5BB9\u7684\u63CF\u8FF0\uFF0C\u800C\u4E0D\u4EC5\u662F label \u4E2D\u7684\u6587\u4EF6\u540D\u3002'},
     ],
@@ -128,19 +136,20 @@ export const docsDense = {
     bestPractices: [
       {guidance: true, description: 'Always set label (file name) for a11y; powers screen reader announce + hover tooltip.'},
       {guidance: true, description: 'isLoading w/o src \u2192 skeleton; isLoading w/ src \u2192 spinner overlay. Two distinct loading states.'},
-      {guidance: true, description: 'onClick adds button semantics + hover shadow; pair with lightbox for full preview.'},
+      {guidance: true, description: 'onClick adds button semantics + hover overlay; pair with lightbox for full preview.'},
       {guidance: false, description: "Don't use for non-image files (PDF, xlsx); use file attachment component with icon instead."},
       {guidance: false, description: "Don't omit alt when src present; screen readers need image content description, not just label."},
     ],
   },
   propDescriptions: {
     src: 'Image source URL.',
-    alt: 'Alt text for image.',
+    alt: 'Alt text for image. Omitted → explicitly decorative (alt="" + role="presentation" + aria-hidden); dev warn when src set with no alt and no label.',
     label: 'Accessible label (file name). Tooltip on hover, aria-label.',
     onRemove: '(e) => void. Overlaid remove button callback.',
-    onClick: '(e) => void. Adds button semantics + hover shadow.',
+    onClick: '(e) => void. Adds button semantics + hover overlay.',
     isLoading: 'Skeleton (no src) or upload overlay (with src). Default: false.',
     isDisabled: 'Disabled state. Default: false.',
+    showRemoveOn: "When remove button shows: hover (default — reveal on hover/focus, stays visible on touch) | always. Only when onRemove set.",
     xstyle: 'stylex.create() for layout.',
     className: 'CSS class. Prefer xstyle.',
     style: 'Inline styles. Prefer xstyle.',