@astryxdesign/core 0.1.9 → 0.2.0-canary.0b7a99e

package/src/NumberInput/NumberInput.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/NumberInput/NumberInput.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/NumberInput/index.ts (exports if types change)
  * - /apps/storybook/stories/NumberInput.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/NumberInput/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/NumberInput/ (showcase blocks)
  */
 
 import {
@@ -27,7 +27,6 @@ import {
   type ReactNode,
 } from 'react';
 import * as stylex from '@stylexjs/stylex';
-import type {IconName} from '../Icon';
 import {
   colorVars,
   sizeVars,
@@ -39,11 +38,11 @@ import {
 import {
   Field,
   type InputStatus,
-  type InputStatusType,
   inputWrapperStyles,
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
+  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {VisuallyHidden} from '../VisuallyHidden';
@@ -51,6 +50,7 @@ import {useTooltip} from '../Tooltip';
 import {getInputARIA} from '../utils';
 import {useSize} from '../SizeContext/SizeContext';
 import {useInputContainer} from '../hooks/useInputContainer';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
 
 const styles = stylex.create({
@@ -207,6 +207,14 @@ interface NumberInputPropsBase extends Omit<
    * If message is provided, displays a floating message box below the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * The size of the input.
    * - 'sm': Compact size (28px height)
@@ -374,6 +382,7 @@ export function NumberInput({
   startIcon,
   labelIcon,
   status,
+  statusVariant = 'attached',
   size: sizeProp,
   onChange,
   value,
@@ -405,6 +414,7 @@ export function NumberInput({
   const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
+  const unitsID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
   const inputGroup = useInputGroup();
@@ -426,26 +436,26 @@ export function NumberInput({
     isEnabled: showsDisabledMessage,
   });
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
-
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+      isInGroup: !!inputGroup,
+    });
 
   const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(
     inputLabelID,
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      // The status message element is rendered by Field, which is skipped
+      // inside an InputGroup — only reference it when it actually exists.
+      !inputGroup && statusVariant !== 'tooltip' && status?.message
+        ? statusMessageID
+        : null,
+      // The tooltip variant renders no message box; describe the input by the
+      // tooltip's content instead so the status is still announced.
+      statusTooltipDescribedBy,
+      units ? unitsID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ],
     inputGroup,
@@ -605,7 +615,7 @@ export function NumberInput({
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
           status && inputStatusBorderStyles[status.type],
-          status && inputStatusHoverShadowStyles[status.type],
+          status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
           inputGroup && groupStyles.inGroup,
           xstyle,
@@ -651,7 +661,11 @@ export function NumberInput({
           !isInputValid && styles.inputInvalid,
         )}
       />
-      {units && <span {...stylex.props(styles.units)}>{units}</span>}
+      {units && (
+        <span id={unitsID} {...stylex.props(styles.units)}>
+          {units}
+        </span>
+      )}
       {/*
         Live region announcing invalid typed input to assistive technology.
         The value silently reverts on blur, so without this a screen-reader
@@ -669,13 +683,7 @@ export function NumberInput({
           <Icon icon="close" size="sm" color="secondary" />
         </button>
       )}
-      {status && !inputGroup && (
-        <Icon
-          icon={statusIconMap[status.type]}
-          size="md"
-          color={statusIconColorMap[status.type]}
-        />
-      )}
+      {statusIcon}
     </div>
   );
 
@@ -709,6 +717,7 @@ export function NumberInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       {inputWrapper}

package/src/Outline/Outline.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Outline',
@@ -236,7 +236,7 @@ function FlashOnArrival() {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Outline',
   displayName: 'Outline',
@@ -334,7 +334,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Document outline/table-of-contents nav with sliding indicator track. Flat items array {id,label,level}; anchor links; density variant (default/compact); uncontrolled scroll-spy by scroll position (last heading past its resting line = offset + its own scroll-margin-top; first item at top, last at bottom); controlled with activeId; smooth-scroll on click that pins the active item until the next manual scroll. Single tab stop (roving tabindex): Arrow keys move, Home/End jump, Enter/Space activate. onNavigateStart/onNavigateEnd fire around the scroll. Scroll scoping via offset / scrollContainerRef / hasScrollOnClick.',

package/src/Outline/Outline.test.tsx

@@ -86,7 +86,7 @@ describe('Outline', () => {
     render(<Outline items={items} activeId="install" />);
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
     expect(
       screen.getByRole('link', {name: 'Introduction'}),
@@ -111,7 +111,7 @@ describe('Outline', () => {
     // so it has not moved to the clicked item yet.
     expect(
       screen.getByRole('link', {name: 'Installation'}),
-    ).not.toHaveAttribute('aria-current', 'true');
+    ).not.toHaveAttribute('aria-current', 'location');
 
     // When the scroll settles, the indicator lands on the clicked item.
     act(() => {
@@ -120,7 +120,7 @@ describe('Outline', () => {
     expect(onActiveIdChange).toHaveBeenCalledWith('install');
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     document.body.removeChild(target);
@@ -224,7 +224,7 @@ describe('Outline', () => {
 
     expect(screen.getByRole('link', {name: 'Introduction'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     // Controlled active id is driven entirely by the prop.
@@ -237,7 +237,7 @@ describe('Outline', () => {
     );
     expect(screen.getByRole('link', {name: 'API'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
     expect(
       screen.getByRole('link', {name: 'Introduction'}),
@@ -277,7 +277,7 @@ describe('Outline', () => {
 
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
     expect(onActiveIdChange).toHaveBeenCalledWith('install');
 
@@ -493,7 +493,7 @@ describe('Outline keyboard navigation', () => {
     expect(onNavigateEnd).toHaveBeenCalledTimes(1);
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     cleanup();
@@ -764,7 +764,7 @@ describe('Outline scroll scoping', () => {
     expect(onNavigateEnd).toHaveBeenCalledWith('install');
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     cleanup();
@@ -797,7 +797,7 @@ describe('Outline scroll scoping', () => {
     // has not reached it, so `intro` stays active.
     expect(screen.getByRole('link', {name: 'Introduction'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     rerender(<Outline items={items} offset={64} />);
@@ -806,7 +806,7 @@ describe('Outline scroll scoping', () => {
     });
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     cleanup();
@@ -930,7 +930,7 @@ describe('Outline scroll scoping', () => {
 
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
     expect(screen.getByRole('link', {name: 'API'})).not.toHaveAttribute(
       'aria-current',
@@ -981,7 +981,7 @@ describe('Outline scroll scoping', () => {
 
     expect(screen.getByRole('link', {name: 'Installation'})).toHaveAttribute(
       'aria-current',
-      'true',
+      'location',
     );
 
     pane.remove();

package/src/Outline/Outline.tsx

@@ -20,7 +20,7 @@
  * - /packages/core/src/Outline/Outline.doc.mjs
  * - /packages/core/src/Outline/index.ts
  * - /apps/storybook/stories/Outline.stories.tsx
- * - /packages/cli/templates/blocks/components/Outline/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Outline/ (showcase blocks)
  */
 
 import {useRef} from 'react';
@@ -372,7 +372,7 @@ export function Outline({
     }
     const links = Array.from(list.querySelectorAll<HTMLElement>('a[href]'));
     const active = links.find(
-      link => link.getAttribute('aria-current') === 'true',
+      link => link.getAttribute('aria-current') === 'location',
     );
     if (active == null) {
       return;
@@ -465,7 +465,7 @@ export function Outline({
             <li key={item.id} {...stylex.props(styles.item)} role="listitem">
               <LinkComponent
                 href={`#${item.id}`}
-                aria-current={isActive ? 'true' : undefined}
+                aria-current={isActive ? 'location' : undefined}
                 onClick={handleClick(item.id)}
                 onKeyDown={handleKeyDown(item.id)}
                 {...mergeProps(

package/src/OverflowList/OverflowList.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'OverflowList',
@@ -112,7 +112,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'OverflowList',
   displayName: 'Overflow List',
@@ -188,7 +188,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'horizontal list w/ overflow indicator: hides items beyond container width',
   usage: {

package/src/OverflowList/OverflowList.tsx

@@ -15,7 +15,7 @@
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/OverflowList/index.ts (exports if types change)
- * - /packages/cli/templates/blocks/components/OverflowList/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/OverflowList/ (showcase blocks)
  */
 
 import {type ReactNode, type ReactElement, Children} from 'react';

package/src/Overlay/Overlay.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Overlay',
@@ -188,7 +188,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'layered content over media/card surfaces with scrim + hover/focus/controlled reveal',
   usage: {

package/src/Pagination/Pagination.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Pagination',
@@ -131,7 +131,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Pagination',
   displayName: 'Pagination',
@@ -251,7 +251,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Standalone pagination controls for navigating content pages. Supports multiple display variants + works w/ known totals or cursor-based pagination.',

package/src/Pagination/Pagination.tsx

@@ -4,7 +4,8 @@
 
 /**
  * @file Pagination.tsx
- * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button
+ * @input Uses React, StyleX, Button, Icon, Selector, Text; page number buttons delegate to Button.
+ *   Reads i18n direction via useDirection() to flip the prev/next chevrons under RTL.
  * @output Exports Pagination component, PaginationProps, PaginationVariant, PaginationSize types
  * @position Core implementation; consumed by index.ts, tested by Pagination.test.tsx
  *
@@ -12,7 +13,7 @@
  * - /packages/core/src/Pagination/Pagination.test.tsx (tests for new/changed behavior)
  * - /packages/core/src/Pagination/index.ts (exports if types change)
  * - /apps/storybook/stories/Pagination.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/Pagination/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Pagination/ (showcase blocks)
  *
  * Last synced props: page, onChange, changeAction, totalItems, totalPages, hasMore,
  *   pageSize, pageSizeOptions, onPageSizeChange, variant, siblingCount, size, isDisabled,
@@ -40,32 +41,13 @@ import {mergeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n/useTranslator';
+import {useDirection} from '../i18n/useDirection';
+import type {PaginationVariantMap} from './index';
 
 // =============================================================================
 // Types
 // =============================================================================
 
-/**
- * Extensible variant map for Pagination.
- *
- * Theme packages can add custom variants via TypeScript module augmentation:
- * @example
- * ```
- * declare module '@astryxdesign/core/Pagination' {
- *   interface PaginationVariantMap {
- *     'progress': true;
- *   }
- * }
- * ```
- */
-export interface PaginationVariantMap {
-  pages: true;
-  count: true;
-  compact: true;
-  dots: true;
-  none: true;
-}
-
 /** Visual variant controlling what appears between prev/next buttons.
  * Extensible via module augmentation of PaginationVariantMap.
  */
@@ -360,6 +342,12 @@ export function Pagination({
   const label = labelFromProps ?? t('@astryx.pagination.label');
   const previousLabel = t('@astryx.pagination.previous');
   const nextLabel = t('@astryx.pagination.next');
+
+  // Directional icons: under RTL, the "previous" control points right and the
+  // "next" control points left. aria-labels stay semantic (unchanged).
+  const direction = useDirection();
+  const previousIcon = direction === 'rtl' ? 'chevronRight' : 'chevronLeft';
+  const nextIcon = direction === 'rtl' ? 'chevronLeft' : 'chevronRight';
   const pageIndicatorsLabel = t('@astryx.pagination.pageIndicators');
   const itemsPerPageLabel = t('@astryx.pagination.itemsPerPage');
 
@@ -663,7 +651,7 @@ export function Pagination({
           label={previousLabel}
           variant="ghost"
           size={buttonSize}
-          icon={<Icon icon="chevronLeft" size={isSm ? 'sm' : 'md'} />}
+          icon={<Icon icon={previousIcon} size={isSm ? 'sm' : 'md'} />}
           onClick={handlePrevious}
           isDisabled={isDisabled || !hasPrevious}
           isIconOnly
@@ -675,7 +663,7 @@ export function Pagination({
           label={nextLabel}
           variant="ghost"
           size={buttonSize}
-          icon={<Icon icon="chevronRight" size={isSm ? 'sm' : 'md'} />}
+          icon={<Icon icon={nextIcon} size={isSm ? 'sm' : 'md'} />}
           onClick={handleNext}
           isDisabled={isDisabled || !hasNext}
           isIconOnly

package/src/Pagination/index.ts

@@ -9,10 +9,30 @@
  * @position Barrel export; consumed by packages/core/src/index.ts
  */
 
+/**
+ * Extensible variant map for Pagination.
+ *
+ * Theme packages can add custom variants via TypeScript module augmentation:
+ * @example
+ * ```
+ * declare module '@astryxdesign/core/Pagination' {
+ *   interface PaginationVariantMap {
+ *     'progress': true;
+ *   }
+ * }
+ * ```
+ */
+export interface PaginationVariantMap {
+  pages: true;
+  count: true;
+  compact: true;
+  dots: true;
+  none: true;
+}
+
 export {Pagination, generatePageRange} from './Pagination';
 export type {
   PaginationProps,
   PaginationVariant,
-  PaginationVariantMap,
   PaginationSize,
 } from './Pagination';

package/src/Popover/Popover.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Popover',
@@ -145,7 +145,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'Popover',
   displayName: 'Popover',
@@ -275,7 +275,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Click-triggered popover displaying interactive content anchored to trigger element; implements button+dialog ARIA pattern.',

package/src/Popover/Popover.tsx

@@ -14,7 +14,7 @@
  * - /packages/core/src/Popover/Popover.test.tsx
  * - /packages/core/src/Popover/index.ts
  * - /apps/storybook/stories/Popover.stories.tsx
- * - /packages/cli/templates/blocks/components/Popover/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/Popover/ (showcase blocks)
  */
 
 import React, {

package/src/Popover/usePopover.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').HookDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
 export const docs = {
   name: 'usePopover',
   displayName: 'usePopover',
@@ -46,7 +46,7 @@ export const docs = {
   category: 'interaction',
 };
 
-/** @type {import('../docs-types').HookTranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description: 'Headless click-triggered popovers w/ focus trap, auto-focus, light dismiss, Escape, optional hidden close button. Use for custom interactive floating content needing keyboard nav.',
   paramDescriptions: {

package/src/Popover/usePopover.tsx

@@ -27,6 +27,7 @@ import {
   shadowVars,
 } from '../theme/tokens.stylex';
 import {Button} from '../Button';
+import {rtlStyles} from '../utils';
 import {useTranslator} from '../i18n';
 import {useDevWarning} from '../hooks/useDevWarning';
 
@@ -43,12 +44,13 @@ const styles = stylex.create({
   contentWrapper: {
     position: 'relative',
   },
-  // Hidden close button wrapper - sr-only until focused, then positioned below popover
+  // Hidden close button wrapper - sr-only until focused, then positioned below
+  // popover. Inline-axis centering (+ the translateY(100%) that drops it below
+  // the surface) comes from rtlStyles.centerInline('100%') at the call site —
+  // it centers correctly in both LTR and RTL.
   closeButtonWrapper: {
     position: 'absolute',
     bottom: 0,
-    left: '50%',
-    transform: 'translate(-50%, 100%)',
     zIndex: 1,
     // sr-only by default
     width: {
@@ -417,7 +419,11 @@ export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
           )}>
           {children}
           {hasCloseButton && (
-            <div {...stylex.props(styles.closeButtonWrapper)}>
+            <div
+              {...stylex.props(
+                styles.closeButtonWrapper,
+                rtlStyles.centerInline('100%'),
+              )}>
               <Button
                 variant="secondary"
                 label={closeButtonLabel}

package/src/PowerSearch/PowerSearch.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'PowerSearch',
@@ -90,6 +90,13 @@ export const docs = {
         'Icon to display at the start of the input, before any filter tokens. Forwarded to the internal Tokenizer. Accepts a semantic icon name, an SVG icon component, or a ReactNode directly.',
       slotElements: [{__element: 'Icon', props: {icon: 'search', size: 'sm'}}],
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -165,7 +172,7 @@ export const docs = {
 // See .context/decisions/dense-compression-protocol.md
 // -------------------------------------------------------
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 export const docsZh = {
   name: 'PowerSearch',
   displayName: 'Power Search',
@@ -248,6 +255,13 @@ export const docsZh = {
       description:
         '在输入框开头（筛选 token 之前）显示的图标，转发给内部的 Tokenizer。接受语义图标名称、SVG 图标组件或直接传入 ReactNode。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'maxTokenLength',
       type: 'number',
@@ -305,7 +319,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'Structured filter bar where each token represents filter (field+operator+value). Users select fields from typeahead dropdown, configure operators+values in edit popover, manage filters as removable tokens.',
@@ -332,6 +346,7 @@ export const docsDense = {
     isDisabled: 'Disables entire component.',
     status: 'Validation status object w/ type + optional message.',
     startIcon: 'Icon at input start, before filter tokens. Forwarded to internal Tokenizer.',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     maxTokenLength: 'Max char length for filter value display in tokens.',
     popoverSaveButtonLabel: 'Label for save button in edit popover.',
     timezoneID: 'Timezone ID for date formatting (e.g. "America/New_York").',